@embedpdf/engine-core 3.0.0-next.14 → 3.0.0-next.16

package/dist/LocalEngine-IA9zh3Jh.d.cts

@@ -0,0 +1,1649 @@
+import { $g as MutationMeta, $l as AnnotationImportResult, $u as AttachmentRef, Ah as OutlineItemRef, Ba as FormFieldValue, Bd as AnnotationResourceRole, Bg as SignatureCompleteResult, Bl as WidgetPatch, Bo as WidgetPlacement, Ca as AnnotationPosition, Cd as PdfMeasure, Cu as AnnotationExportSelection, Cv as DocumentActionsSnapshot, Da as PagePosition, Dg as BaseVersionInfo, Ea as OutlinePosition, Ei as FormSubmissionReceipt, Fs as AnnotationDraft, Gg as SignaturePrepared, Gi as Change, Gn as RedactionApplyResult, I_ as PdfRotation, Is as AnnotationPatch, Kc as AttachmentRestoreResult, Kh as OpenOptions, Kn as RedactionApplyScope, Kp as TextRange, Lg as SignatureAppearanceInput, Lh as OpenInput, Ll as WidgetAnnotation, Lp as PageTextSnapshot, Ma as CustomMetadataUpdateResult, Mm as PageFlattenResult, No as FormFieldDraft, Ns as Annotation, Og as DigestAlgorithm, Oh as OutlineItemDraft, Oi as FormSubmissionRequest, Pm as PageFlattenUsage, Qc as FormImportResult, Ql as AnnotationImportOptions, Qu as AttachmentList, R_ as FormFieldRef, Rg as SignatureCancelResult, Sa as MetadataUpdateResult, Su as AnnotationListMutationMeta, Th as DocumentOutline, Tl as FormExportSelection, Tp as PageExtractOptions, Tu as AnnotationBundle, Uc as AttachmentCreateResult, Wa as FormFieldPatch, Wc as AttachmentDeleteResult, Wg as SignaturePrepareInput, Xi as ChangeResult, Yg as SignatureSnapshot, Zc as FormImportOptions, Zu as AttachmentFileSource, Zv as PageRef, _l as FormWidgetLinkResult, _p as AnnotationAppearanceRenderOptions, ap as FontSpec, au as FormWidgetAddOptions, b_ as PageBox, ba as OutlineUpdateResult, bh as CustomMetadata, bl as FormWidgetUpdateResult, bm as PageRenderViewport, ca as PageRestoreResult, cf as ObjectNumberPool, cl as FormCalculationsReorderResult, dl as FormFieldUpdateResult, du as AnnotationReorderResult, fa as PageInsertBlankSpec, fl as FormMutationMeta, fu as AnnotationUpdateResult, ga as OutlineMoveResult, gl as FormWidgetDeleteResult, gm as PageRenderOptions, ha as OutlineDeleteResult, hl as FormSetValueResult, hn as PageScaleResult, i_ as FormFieldDTO, im as PageImageOptions, ip as FontKey, ir as PageRemoveNameInput, iu as FormFieldCreateOptions, iy as DocumentMetadata, jl as FormBundle, kh as OutlineItemPatch, kl as FormSnapshot, la as PageReorderResult, li as ChangeAnalysis, ll as FormFieldCreateResult, lu as AnnotationCreateResult, ma as OutlineCreateResult, ml as FormResetResult, mm as PageRenderImage, mp as AnnotationAppearanceImagesResult, n as AnnotationListOptions, nl as FormValuesImportOptions, np as FontHandle, nr as PageNameResult, ns as SearchRequest, nu as AnnotationUpdateOptions, ou as PageInsertBlankOptions, pa as PageDeleteResult, ph as PageListSnapshot, pl as FormRepairResult, pp as AnnotationAppearanceImageOptions, q_ as AnnotationRef, rl as FormValuesImportResult, rr as PageNameInput, rs as SearchSlice, ru as FlattenWriteOptions, sa as PageRotateResult, si as AnalyzeInput, sp as DownloadOptions, ss as TextLayout, su as WriteOptions, sy as IsoDateTime, t as AnnotationList, tr as AnnotationFlattenResult, tu as AnnotationCreateOptions, ua as PageInsertResult, ul as FormFieldDeleteResult, uu as AnnotationDeleteResult, vl as FormWidgetRestoreResult, vm as PageRenderRaster, wa as FieldPosition, xd as PageMeasurementViewportList, xh as MetadataPatch, xl as FormWidgetsReorderResult, xv as AbortablePromise, ya as OutlineRestoreResult, yh as CustomMetadataPatch, yp as AnnotationAppearancesResult, zg as SignatureCompleteInput } from "./AnnotationList-DcyhF2kU.cjs";
+import { c as DocumentSecurityService } from "./DocumentSecurityService-D2zA4NKi.cjs";
+//#region src/engine/DocumentActionsService.d.ts
+/** Lazy, catalog-owned PDF action read. This API extracts; it never executes. */
+interface DocumentActionsService {
+  get(): AbortablePromise<DocumentActionsSnapshot>;
+}
+//#endregion
+//#region src/engine/DocumentAnnotationsService.d.ts
+/**
+ * Document-scoped annotation service exposed via
+ * `DocumentHandle.annotations`.
+ */
+interface DocumentAnnotationsService {
+  /**
+   * The annotations of the given pages, or of every page. A raw read: no
+   * page is loaded, so listing a whole document is cheap. Returns what
+   * `page.annotations.list()` returns for each page.
+   */
+  list(options?: AnnotationListOptions): AbortablePromise<AnnotationList>;
+  /**
+   * Take annotations out of the document, with the bytes beside them, as one
+   * bundle: every annotation, or the selection with what it points at and,
+   * by default, its threads (see {@link AnnotationExportSelection}). One
+   * drawing is one resource however many stamps place it. Refused with
+   * `PayloadTooLarge`, naming the limit, when the bundle would pass one of
+   * the import limits, and with `NotFound` for a selected page or
+   * annotation the document doesn't have. Needs `doc.annotate.read` and
+   * `doc.download`.
+   */
+  export(selection?: AnnotationExportSelection): AbortablePromise<AnnotationBundle>;
+  /**
+   * Create a bundle's annotations in this document, as one change: every
+   * item is checked, its pages mapped and what can't be carried left out
+   * (`dropped`) before the first write, and a failure while writing leaves
+   * the document as it was. `reply.to` and a popup's `parent` link to the
+   * items they name in the bundle. Emits one `annotations.created` per
+   * annotation, sharing `origin.tx`. Needs `doc.annotate.modify`; the
+   * default `attribution: 'restore'` also needs `doc.annotate.import`.
+   */
+  import(bundle: AnnotationBundle, options?: AnnotationImportOptions): AbortablePromise<AnnotationImportResult>;
+}
+//#endregion
+//#region src/engine/DocumentAttachmentsService.d.ts
+/**
+ * Document-level attachments: the catalog's `/EmbeddedFiles` name tree
+ * (ISO 32000 §7.11.4). Exposed via `DocumentHandle.attachments`.
+ *
+ * Addressing is by name-tree key (`AttachmentRef`), unique by
+ * construction (see the ref's doc comment). `list()` returns metadata only;
+ * bytes leave the engine exclusively through {@link download}. The
+ * annotation-level counterpart is
+ * `PageAnnotationsService.downloadResource(ref, 'file')`, which answers the
+ * same way: the bytes, the name and type being what the listing says.
+ *
+ * `create` and `delete` are each one op of a change (`attachments.create`,
+ * `attachments.delete`): their `opId` undoes them, and an undo of a delete
+ * brings the same file back (`attachments.restored`).
+ */
+interface DocumentAttachmentsService {
+  /** Snapshot of the `/EmbeddedFiles` name tree, in tree (key-sorted) order. */
+  list(): AbortablePromise<AttachmentList>;
+  /**
+   * Decode and return one embedded file's bytes. Throws
+   * `EngineError(NotFound)` when no entry has the ref's key,
+   * `EngineError(InvalidArg)` when the entry has no embedded file stream,
+   * and `EngineError(PayloadTooLarge)` when the file decodes to more than
+   * `ATTACHMENT_LIMITS.decodedBytes` on an engine that holds it in memory.
+   */
+  download(ref: AttachmentRef): AbortablePromise<Uint8Array>;
+  /**
+   * Create an embedded file in the name tree. The file's `name` becomes
+   * the tree key (`/UF` = `/F` = key); a duplicate key rejects with
+   * `EngineError(InvalidArg)` — rename and retry. A mutation: layer
+   * sessions persist an artifact and an `attachments.created` event is
+   * published. Note the tree is key-sorted, so other entries' indices
+   * may shift; keys never move.
+   */
+  create(file: AttachmentFileSource, options?: WriteOptions): AbortablePromise<AttachmentCreateResult>;
+  /**
+   * Delete an embedded file from the name tree. Unlinks the entry only —
+   * the stream bytes remain in the document until a full rewrite (the
+   * immutable-base/layer model). Throws `EngineError(NotFound)` for an
+   * unknown key. A mutation: layer sessions persist an artifact and an
+   * `attachments.deleted` event is published.
+   */
+  delete(ref: AttachmentRef, options?: WriteOptions): AbortablePromise<AttachmentDeleteResult>;
+}
+//#endregion
+//#region src/engine/DocumentFormsService.d.ts
+/** Options for {@link DocumentFormsService.repair}. */
+interface FormRepairOptions extends WriteOptions {
+  /**
+   * Also regenerate widget appearance streams: widgets with no /AP get
+   * one, and when the /AcroForm sets /NeedAppearances every widget is
+   * re-baked and the flag cleared, making rendering deterministic across
+   * viewers.
+   */
+  bakeAppearances?: boolean;
+}
+/**
+ * The document's interactive form: a document-scoped record system where
+ * fields hold the values and widget annotations are their page-scoped
+ * views. A form field's widgets come with the form, never with the
+ * annotations: `list()` holds the fields and every widget's row, and widget
+ * writes are form writes.
+ *
+ * Reads are gated by `doc.forms.read`, value writes and imports by
+ * `doc.forms.fill`, and repair by `doc.forms.modify`. On layer documents
+ * every write lands as a minimal delta over the shared immutable base — a
+ * filled form layer is semantically an FDF diff.
+ */
+interface DocumentFormsService {
+  /**
+   * The complete reconciled form state: every terminal field with its
+   * effective value and options, and every widget with its place, look and
+   * state. Fields broken producers left out of /AcroForm /Fields are
+   * included with `origin: 'recovered'`.
+   */
+  list(): AbortablePromise<FormSnapshot>;
+  /**
+   * One field by ref. Prefer `objectNumber` refs (durable); `fqn` refs
+   * resolve against the current field tree. Fails with `NotFound` when
+   * the ref matches nothing.
+   */
+  get(ref: FormFieldRef): AbortablePromise<FormFieldDTO>;
+  /**
+   * Write one field's value, in the fields a read of it returns (see
+   * {@link FormFieldValue}). Validation happens before any write — a failed
+   * call leaves the document untouched. Appearance streams regenerate for
+   * text/choice widgets; toggles flip their appearance state. Emits
+   * `forms.valueSet`.
+   */
+  setValue(ref: FormFieldRef, value: FormFieldValue, options?: WriteOptions): AbortablePromise<FormSetValueResult>;
+  /**
+   * Put fields back to their default value (/DV), or empty them when they
+   * have none: the whole form without an argument, else the fields named.
+   * Fields that hold no value (push buttons, signature fields) are skipped,
+   * and so, in a whole-form reset, are fields a signature locked; naming a
+   * locked field fails with `ProtectedDocument`. The result lists the
+   * fields that changed. Emits one `forms.valueSet` per changed field,
+   * sharing `origin.tx`.
+   */
+  reset(fields?: FormFieldRef | FormFieldRef[], options?: WriteOptions): AbortablePromise<FormResetResult>;
+  /**
+   * Deliver a resolved form submission to the document's home. Present only
+   * where the document has a home that accepts submissions — the cloud
+   * engine when the deployment advertises the capability; the local engine
+   * truthfully lacks it (an in-process document has no home, and this
+   * contract is never a callback trampoline). Gated by `doc.forms.submit`
+   * (grant-minted; no PDF permission bit exists for submission), asserted
+   * at the home's boundary where enforcement is real. The home stores the
+   * dataset with the declared intent as metadata and derives who submitted
+   * from its own verified session — it never fetches the PDF's URL.
+   */
+  submit?(request: FormSubmissionRequest): AbortablePromise<FormSubmissionReceipt>;
+  /**
+   * The fields `selection` takes, each whole with all of its widgets, their
+   * values and who made and filled them, as one bundle (every field without
+   * a selection). A field the form doesn't export comes without its value,
+   * a signature field without its signature. Needs `doc.forms.read` and
+   * `doc.download`.
+   */
+  export(selection?: FormExportSelection): AbortablePromise<FormBundle>;
+  /**
+   * Copy a bundle's design into this document: its fields, their widgets,
+   * scripts and actions, values (`options.values`), and their place in the
+   * calculation order, created as one change, all or nothing. A field whose
+   * name is taken, and what can't be carried, is left out and reported in
+   * `dropped`. Needs `doc.forms.modify`; `doc.forms.import` to restore who
+   * made and filled the fields (the default); `doc.forms.script` to keep
+   * scripts, submits and links. Emits one `forms.created` per field.
+   */
+  import(bundle: FormBundle, options?: FormImportOptions): AbortablePromise<FormImportResult>;
+  /**
+   * Fill this document's fields from a bundle, by full name, as one change.
+   * A field the document doesn't have, of another family, that can't take
+   * the value or that a signature locked is left out and reported. Runs no
+   * scripts. Needs `doc.forms.fill`; `doc.forms.import` to restore who
+   * filled the fields (the default). Emits one `forms.valueSet` per field.
+   */
+  importValues(bundle: FormBundle, options?: FormValuesImportOptions): AbortablePromise<FormValuesImportResult>;
+  /**
+   * Create a logical form field, optionally with styled widgets, in one
+   * atomic job. Widgets are born through the annotation plane and adopted
+   * (see {@link addWidget}); the inline `widget(s)` config is sugar for
+   * exactly that composition. Gated by `doc.forms.modify`. Emits
+   * `forms.created`.
+   *
+   * `options.objectNumber` names the field and `options.widgetObjectNumbers`
+   * its widgets (in `draft.widgets` order), all taken from
+   * `doc.objectNumbers`, so their refs are known before the engine answers.
+   * Parent fields created on the way get the next free numbers. A number
+   * this session doesn't hold, or one an object already has, is refused
+   * with `ObjectNumberUnavailable`.
+   */
+  create(draft: FormFieldDraft, options?: FormFieldCreateOptions): AbortablePromise<FormFieldCreateResult>;
+  /**
+   * Update field-plane properties (name, universal and family flags,
+   * options, default value, names). The patch's `family` must match the
+   * target field. Validate-then-apply per property. Emits
+   * `forms.updated`.
+   */
+  update(ref: FormFieldRef, patch: FormFieldPatch, options?: WriteOptions): AbortablePromise<FormFieldUpdateResult>;
+  /**
+   * Draw a PDF page into every widget of an unsigned signature field — the
+   * visual "sign" of a viewer that has no signer. The field's value stays
+   * empty and nothing is sealed; a signed field is refused. Gated by
+   * `doc.forms.fill`. Emits `forms.updated`.
+   */
+  setSignatureAppearance(ref: FormFieldRef, appearance: SignatureAppearanceInput, options?: WriteOptions): AbortablePromise<FormFieldUpdateResult>;
+  /**
+   * Delete a terminal field and cascade: every widget is removed from its
+   * page, the field leaves the tree, and empty ancestors are pruned.
+   * Emits `forms.deleted`.
+   */
+  delete(ref: FormFieldRef, options?: WriteOptions): AbortablePromise<FormFieldDeleteResult>;
+  /**
+   * Show the field in one more place: a new widget, placed and styled like
+   * an entry of a draft's `widgets`, in one change. A radio button needs
+   * its `exportValue`. Adding a widget to a legacy merged field splits it:
+   * the field keeps its object number and its widget moves to a new one
+   * (`options.splitObjectNumber`, or the next free one). Emits
+   * `forms.widgetAdded`.
+   *
+   * `options.objectNumber` names the new widget, taken from
+   * `doc.objectNumbers` like `splitObjectNumber`. A number this session
+   * doesn't hold, or one an object already has, is refused with
+   * `ObjectNumberUnavailable`.
+   */
+  addWidget(ref: FormFieldRef, placement: WidgetPlacement, options?: FormWidgetAddOptions): AbortablePromise<FormWidgetLinkResult>;
+  /**
+   * Take a widget out of its field: it keeps its page placement and last
+   * appearance but belongs to no field any more (its `field` is `null`;
+   * `deleteWidget` takes it off the page). The field survives, "unplaced"
+   * when this was its last widget. Emits `forms.widgetRemoved`.
+   */
+  removeWidget(ref: FormFieldRef, widget: AnnotationRef, options?: WriteOptions): AbortablePromise<FormWidgetLinkResult>;
+  /**
+   * Delete a widget: it leaves its page, and its field when it has one. The
+   * field survives, "unplaced" when this was its last widget. A widget that
+   * is its field's own dictionary (a merged field/widget) is refused with
+   * `InvalidArg`: delete the field with `delete`. A widget is the form's, so
+   * `annotations.delete` refuses one. Gated by `doc.forms.modify`. Emits
+   * `forms.widgetDeleted`.
+   */
+  deleteWidget(widget: AnnotationRef, options?: WriteOptions): AbortablePromise<FormWidgetDeleteResult>;
+  /**
+   * Change a widget's place and look: what `annotations.update` takes for a
+   * widget (rect, colors, border, font, alignment, flags). A widget is the
+   * form's, so `annotations.update` refuses one. Gated by
+   * `doc.forms.modify`. Emits `forms.widgetUpdated`.
+   */
+  updateWidget(widget: AnnotationRef, patch: WidgetPatch, options?: WriteOptions): AbortablePromise<FormWidgetUpdateResult>;
+  /**
+   * Change the widgets' stacking order on their page: they go together, in
+   * the order given, to `position` among the page's widgets, next to a
+   * neighbour widget or at `'start'` (bottom) / `'end'` (top). Widgets paint
+   * above every annotation, so only widgets are named here; an annotation is
+   * refused with `InvalidArg` (`page.annotations.reorder()` orders those).
+   * Where a page's `/Tabs` is `/A` or `/W`, this is also the fields' tab
+   * order. Gated by `doc.forms.modify`. Emits `forms.widgetsReordered`.
+   */
+  reorderWidgets(widgets: AnnotationRef[], position: AnnotationPosition, options?: WriteOptions): AbortablePromise<FormWidgetsReorderResult>;
+  /**
+   * Change the form's calculation order (`/AcroForm /CO`), the order the
+   * fields' calculate scripts run in: the fields go together, in the order
+   * given, to `position`, next to a neighbour or at `'start'` / `'end'`.
+   * Every field named must be in the order already: a `calculate` script
+   * puts a field in it (`create`, `update`). `doc.forms.list()` reads the
+   * order as `calculationOrder`. Gated by `doc.forms.modify`. Emits
+   * `forms.calculationsReordered`.
+   */
+  reorderCalculations(fields: FormFieldRef[], position: FieldPosition, options?: WriteOptions): AbortablePromise<FormCalculationsReorderResult>;
+  /**
+   * Make the engine's read-time reconciliation durable in the document
+   * ("form doctor"): bootstrap a missing /AcroForm, link recovered field
+   * roots into /Fields, re-attach stray widgets to their parent's /Kids,
+   * and optionally bake appearances. Validate-then-apply and idempotent —
+   * a second call reports zero fixes. Emits `forms.repaired`.
+   */
+  repair(options?: FormRepairOptions): AbortablePromise<FormRepairResult>;
+}
+//#endregion
+//#region src/engine/DocumentOutlineService.d.ts
+/** Where `create` puts a new item, and the name it gets. */
+interface OutlineCreateOptions extends WriteOptions {
+  /** The item it goes under; the top level when left out or `null`. */
+  parent?: OutlineItemRef | null;
+  /** Its place among `parent`'s children; the end when left out. */
+  position?: OutlinePosition;
+  /** Its object number, taken from `doc.objectNumbers`; the engine picks one when left out. */
+  objectNumber?: number;
+}
+/**
+ * The document's outline (`/Root /Outlines`, the bookmarks). Reading it is
+ * part of opening the document (`doc.open`); writing takes
+ * `doc.outline.modify`. Each write is a one-op change: the same op, checks
+ * and undo as `doc.apply`, its events `outline.*`.
+ */
+interface DocumentOutlineService {
+  /** Every item, depth first. */
+  get(): AbortablePromise<DocumentOutline>;
+  /** A new item; `'outline.create'` in a change. */
+  create(data: OutlineItemDraft, options?: OutlineCreateOptions): AbortablePromise<OutlineCreateResult>;
+  /** Change the fields `patch` names; `'outline.update'` in a change. */
+  update(ref: OutlineItemRef, patch: OutlineItemPatch, options?: WriteOptions): AbortablePromise<OutlineUpdateResult>;
+  /**
+   * Move items, each with the items under it, under `parent` (`null`: the
+   * top level) at `position` among its children; `'outline.move'` in a
+   * change.
+   */
+  move(refs: readonly OutlineItemRef[], parent: OutlineItemRef | null, position: OutlinePosition, options?: WriteOptions): AbortablePromise<OutlineMoveResult>;
+  /** Delete an item and the items under it; `'outline.delete'` in a change. */
+  delete(ref: OutlineItemRef, options?: WriteOptions): AbortablePromise<OutlineDeleteResult>;
+}
+//#endregion
+//#region src/engine/DocumentPagesService.d.ts
+/**
+ * Document-scoped page service exposed via `DocumentHandle.pages`.
+ *
+ * Mirrors the shape of `DocumentAnnotationsService` so that anything
+ * touching "many things at the document level" lives in one place: the
+ * structure verbs (`reorder`, `rotate`, `delete`, `insert`, `insertBlank`),
+ * `extract`, `flatten` and the page names.
+ *
+ * Identity rule: pages are addressed by `PageRef` (the durable object
+ * number) everywhere except `list()`, which exposes display order through
+ * `PageLayout.index`. Structure verbs never change the names of the
+ * annotations on surviving pages.
+ *
+ * Each structure verb is a one-op change through `doc.apply` (`pageVerbs`):
+ * its `opId` undoes it, and an undo of a delete brings the same pages back
+ * (`pages.restored`).
+ */
+interface DocumentPagesService {
+  /**
+   * Snapshot of every page in display order. Cheap; never acquires a
+   * `pagePtr`.
+   */
+  list(): AbortablePromise<PageListSnapshot>;
+  /**
+   * Reorder pages: they go together, in the order given, to `position`,
+   * next to a neighbour (`{ before: page }`, `{ after: page }`) or at
+   * `'start'` / `'end'`. Annotation refs the caller is holding stay valid
+   * across a page reorder. A neighbour that isn't in the document is
+   * `NotFound`; one of the pages that move is `InvalidArg`. Emits
+   * `pages.reordered`.
+   */
+  reorder(pages: PageRef[], position: PagePosition, options?: WriteOptions): AbortablePromise<PageReorderResult>;
+  /**
+   * Set the absolute display rotation of the supplied pages (one value
+   * for all — the multi-select thumbnail gesture). Pure presentation
+   * metadata: content coordinates are normalized, so cached renders and
+   * annotation refs survive untouched. See
+   * `PageRotateInput` for why the wire is absolute, never relative.
+   */
+  rotate(pages: PageRef[], rotation: PdfRotation, options?: WriteOptions): AbortablePromise<PageRotateResult>;
+  /**
+   * Delete pages. Deleting every page is rejected (`InvalidArg`) — a
+   * document must keep at least one. Deleted page object numbers are retired, never
+   * recycled; surviving pages keep their identity and revisions.
+   */
+  delete(pages: PageRef[], options?: WriteOptions): AbortablePromise<PageDeleteResult>;
+  /**
+   * Register `name` → page in the catalog's `/Names /Pages` tree (create,
+   * or replace what an existing key points at); with `replace`, drop that
+   * other key in the same job (rename). Named pages are layout — read them
+   * back from `list().namedPages` — so this is a page-structure mutation:
+   * `docVersion` + `layoutVersion` advance, per-page pins do not. Gated like
+   * `reorder` (`doc.pages.assemble`).
+   *
+   * Rejects with `InvalidArg` for an empty name and `NotFound` for a page
+   * that is not in the page tree (hidden templates included).
+   */
+  setName(input: PageNameInput, options?: WriteOptions): AbortablePromise<PageNameResult>;
+  /**
+   * Remove one `/Names /Pages` registration; the page itself is untouched.
+   * `NotFound` when no registration has that decoded key. Page deletion
+   * removes registrations by itself — callers never need to pair the two.
+   */
+  removeName(input: PageRemoveNameInput, options?: WriteOptions): AbortablePromise<PageNameResult>;
+  /**
+   * Paint eligible annotation appearances into page content and remove only
+   * those annotations that were painted. This changes content and annotation
+   * liveness, not layout. The default usage is normal display.
+   */
+  flatten(pages: PageRef[], options?: FlattenWriteOptions): AbortablePromise<PageFlattenResult>;
+  /**
+   * Export the given pages, in the supplied order, as a standalone PDF
+   * (bytes of a new document containing copies of those pages). A read:
+   * the source document is untouched — no revisions bump, no event is
+   * published. This is how a page becomes a portable asset (a vector
+   * stamp, a signature) that re-enters a document as a stamp's `appearance`
+   * resource. Gated by `doc.download` (it egresses content), not
+   * `doc.pages.assemble`.
+   *
+   * With `flatten`, the copy is the pages as they draw for its `usage`: the
+   * annotations and form fields painted in, nothing interactive left, layers
+   * in their state for `usage` (`{ usage: 'print' }` is a print copy). It
+   * takes `doc.download` or `doc.download.flattened`, and paints only what
+   * the caller may read; `includeAnnotations` and `includeFormFields` choose
+   * what it paints, and are refused without `flatten`. The copy keeps the
+   * document's title.
+   *
+   * Required-parity, delivered: the local engine runs it in the worker,
+   * the cloud engine as POST /pages/extract.
+   */
+  extract(pages: PageRef[], options?: PageExtractOptions): AbortablePromise<Uint8Array>;
+  /**
+   * Insert every page of a standalone PDF (`bytes`) at `position`
+   * (default `'end'`). The pages are copied in; the inserted copies get
+   * fresh object numbers, returned in insertion order. Bytes are a call
+   * argument (the same law as annotation binaries): the local engine
+   * transfers them to its worker, the cloud engine ships them as a part of
+   * its change request.
+   *
+   * Required-parity, delivered — a cloud viewer must be able to add pages,
+   * so this is a mandatory member: any engine implements it or is not a
+   * conforming engine.
+   */
+  insert(bytes: Uint8Array | ArrayBuffer, position?: PagePosition, options?: WriteOptions): AbortablePromise<PageInsertResult>;
+  /**
+   * Create `spec.count` (default 1) blank pages of `spec.size` (PDF points)
+   * at `position` (default `'end'`). The blank-page sibling of `insert`:
+   * same gate (`doc.pages.assemble`), same result shape, same
+   * `pages.inserted` event — it is a separate verb because it takes pure
+   * parameters where `insert` takes a binary payload. Every pre-existing
+   * page keeps its identity.
+   * Mandatory, like `insert`.
+   *
+   * `options.objectNumbers` names the new pages, one number per page in
+   * order, taken from `doc.objectNumbers`: their refs are known before the
+   * engine answers, so they can be annotated at once. Without them the
+   * engine picks the next free numbers. A number this session doesn't hold,
+   * or one an object already has, is refused with `ObjectNumberUnavailable`.
+   */
+  insertBlank(spec: PageInsertBlankSpec, position?: PagePosition, options?: PageInsertBlankOptions): AbortablePromise<PageInsertResult>;
+}
+//#endregion
+//#region src/engine/DocumentRedactionService.d.ts
+/**
+ * The destructive half of the two-stage redaction model (ISO 32000-2
+ * 12.5.6.23). Marking is annotation-plane work: a `redact` annotation rides
+ * the normal create/update/delete verbs and destroys nothing. Applying —
+ * this service — permanently removes the content under each marked region,
+ * paints the configured overlay in its place, and removes the consumed
+ * redact annotations along with any annotation intersecting the region.
+ *
+ * Trust boundary (deliberate, documented): on a layered document, apply
+ * rewrites this layer's bytes only. The immutable base document still
+ * contains the original content — byte-perfect original recovery is a
+ * feature of the storage model, not a leak. Redacted content becomes truly
+ * unrecoverable only in a full-rewrite export after apply. Callers must select
+ * `download({ mode: 'rewrite' })` (or the corresponding file/cloud save mode)
+ * before sharing the redacted PDF. The default incremental download preserves
+ * the original content in prior revisions; apply does not change that default.
+ * Surfaces that promise "permanent removal" must scope that promise to the
+ * full-rewrite exported artifact.
+ *
+ * Applying is irreversible within the layer (no undo). Emits a
+ * `redaction.applied` document event; content-scope raster invalidation and
+ * search-corpus refresh ride the normal content-version machinery.
+ */
+interface DocumentRedactionService {
+  /**
+   * Apply redactions in `scope`. Ordered batch verb: pages are processed
+   * independently and a failed page is recorded in its item result rather
+   * than throwing after the first native write; `unchanged` means the page
+   * had no matching redact annotation. Returns no `meta` only when nothing
+   * changed.
+   */
+  apply(scope: RedactionApplyScope, options?: WriteOptions): AbortablePromise<RedactionApplyResult>;
+}
+//#endregion
+//#region src/engine/DocumentRenderService.d.ts
+/**
+ * The engine's render-parameter policy.
+ *
+ * - `continuous` — any viewport renders exactly as requested. The local
+ *   engine always answers this: rendering is in-process, there is no
+ *   shared cache to protect, and exactness is the local product promise.
+ * - `lattice` — the deployment treats a finite set of render points as
+ *   durable, CDN-shared artifacts. The bounded quantity
+ *   is output pixels, never zoom:
+ *
+ *   - `fullPage.widths` — full-page renders quantize on `viewport.width`
+ *     (a scale lattice bounds artifact count but not size: PDF page space
+ *     is effectively unbounded, so scale 1 of a poster page is a memory
+ *     bomb while width caps the dominant dimension by construction).
+ *   - `tiles` — reserved for the deep-zoom vertical: a scale-based
+ *     pyramid × fixed tile size, where per-job cost is constant. Absent
+ *     until the tiling plugin ships; reserving the shape keeps the SDK
+ *     contract from churning twice.
+ *   - `maxRenderPixels` — the worker-side output budget for degenerate
+ *     geometry (width bounds width, not height).
+ *
+ * The SDK never conforms a request implicitly — the same `render.image`
+ * call must not return different pixels on local vs cloud. Conformance is
+ * the caller's visible choice via {@link snapFullPageViewport}.
+ */
+type EngineRenderPolicy = {
+  readonly kind: 'continuous';
+} | {
+  readonly kind: 'lattice';
+  readonly fullPage: {
+    readonly widths: readonly number[];
+  };
+  readonly tiles?: {
+    readonly tileSizes: readonly number[];
+    readonly scales: readonly number[];
+  };
+  /**
+   * Annotation-appearance lattice — scale-based, unlike full pages:
+   * an appearance is sized by `annotation.rect × scale`, rects span
+   * orders of magnitude (a 4pt caret vs a page-sized stamp), and the
+   * composite must track the page's effective render scale or
+   * annotations sit blurry on a crisp raster. Small images → the
+   * ladder affords finer, taller steps than pages ever could.
+   */
+  readonly appearances?: {
+    readonly scales: readonly number[];
+  };
+  readonly maxRenderPixels?: number;
+  readonly formats: readonly ('webp' | 'png')[];
+  readonly background: 'white';
+  readonly enforced: boolean;
+};
+declare const CONTINUOUS_RENDER_POLICY: EngineRenderPolicy;
+/**
+ * Document-scoped render policy surface (`doc.render`). Async because the
+ * cloud engine learns its policy from `/v1/access`; the local engine
+ * resolves immediately with `continuous`.
+ *
+ * Per-page rendering itself stays on `page(pon).render` — this service
+ * carries policy, not pixels.
+ */
+interface DocumentRenderService {
+  getPolicy(): AbortablePromise<EngineRenderPolicy>;
+}
+/**
+ * Conform a full-page viewport to a render policy — the one snap
+ * implementation, shared by every engine and plugin. Pure and explicit
+ * by design:
+ *
+ * - `continuous` → identity (local/cloud plugin code stays byte-identical).
+ * - `lattice` → returns a `width`-kind viewport at the smallest ladder
+ *   width ≥ the requested detail (snap up: always crisp, CSS downscales
+ *   for free), capped at the largest width — detail beyond the cap is the
+ *   tile pyramid's job, by design.
+ * - `scale`-kind requests convert through the page's width in PDF user
+ *   units — pass `opts.pageWidth` (the caller has it from the layout);
+ *   omitting it for a scale viewport under a lattice policy is a
+ *   programmer error and throws `InvalidArg`.
+ */
+declare function snapFullPageViewport(policy: EngineRenderPolicy, viewport: PageRenderViewport, opts?: {
+  pageWidth?: number;
+}): PageRenderViewport;
+/**
+ * Conform an annotation-appearance scale to the policy's appearance
+ * lattice. Same discipline as {@link snapFullPageViewport}: identity on
+ * continuous (and when the policy carries no appearance block), snap up,
+ * cap at the largest point. Callers derive `scale` from the page's
+ * effective render scale (`snappedWidth / pageWidth`, × devicePixelRatio
+ * as needed) so composites stay crisp against the page raster.
+ */
+declare function snapAppearanceScale(policy: EngineRenderPolicy, scale: number): number;
+/**
+ * The scale an appearance render's viewport puts on the appearance lattice:
+ * a `scale` viewport's scale (1 when omitted), and `undefined` for a
+ * `width` viewport, whose scale depends on the page's size and so is never
+ * on the lattice.
+ */
+declare function appearanceLatticeScale(viewport: PageRenderViewport | undefined): number | undefined;
+/**
+ * Conform a tile-pyramid scale to the policy's tile lattice — the third
+ * member of the `snap<PolicyBlock><Quantity>` family. Identity on
+ * continuous and while the deployment doesn't advertise a `tiles` block
+ * (the block is reserved until the deep-zoom vertical ships server-side;
+ * the tiling client uses its own default pyramid then — see
+ * plugin-render). Snap up, cap at the largest scale: per-tile cost is
+ * constant by construction (`tileSize²` pixels regardless of level), so
+ * the cap bounds artifact count, not memory.
+ */
+declare function snapTileScale(policy: EngineRenderPolicy, scale: number): number;
+//#endregion
+//#region src/engine/DocumentSearchService.d.ts
+/**
+ * Document-scoped text search, exposed via `DocumentHandle.search`.
+ *
+ * The contract is a client-driven cursor loop over bounded slices: each
+ * `query()` call scans at most a budgeted amount of work (pages/matches)
+ * and returns what it found plus a resume cursor. There is no job to
+ * start or cancel — a 40K-page document is searched by asking for slices
+ * until `nextCursor` is null or the user stops caring. Engines clamp the
+ * requested budget to their own ceilings, so no single call can hold a
+ * worker (or the server) for minutes.
+ *
+ * Reads are gated by `doc.text.search`; `snippets: true` also requires
+ * `doc.text.copy` — see {@link SearchRequest.snippets}. Results always
+ * reflect the current layer view: text removed by redaction in this
+ * layer is unfindable, and a cursor issued before a content mutation is
+ * rejected rather than resumed over stale pages.
+ *
+ * Matches carry canonical visual-line segments from the same layout as text
+ * selection (never per-glyph boxes) and text-page character offsets that
+ * join the selection/geometry subsystem directly.
+ */
+interface DocumentSearchService {
+  query(request: SearchRequest): AbortablePromise<SearchSlice>;
+}
+//#endregion
+//#region src/engine/DocumentSignaturesService.d.ts
+/**
+ * Digital signatures on the document: the read side (what is signed, what
+ * it seals, what it forbids) and the two-phase signing protocol. The
+ * engine does the PDF job — candidate file, digest, sealing — and never
+ * holds a key; the CMS comes from the caller (`@embedpdf/core-signature`
+ * builds one from a raw signer, or a signing service returns it).
+ *
+ * Every read here describes the bytes the document was loaded from
+ * (for a layer document: base + the delta it was opened with). Unsaved
+ * edits are not part of any revision until `prepare` snapshots them.
+ *
+ * Reads ride `doc.forms.read`; `revisionBytes` rides `doc.download`;
+ * `prepare`/`complete`/`abort` ride `doc.sign`, a certification
+ * additionally `doc.sign.certify`.
+ */
+interface DocumentSignaturesService {
+  /** Revisions, every signature field with its signed state, and the protection in force. */
+  list(): AbortablePromise<SignatureSnapshot>;
+  /** The DER `/Contents` of a signed field (exactly `contentsSize` bytes, padding stripped). `NotFound` for an unsigned field. */
+  getContents(field: FormFieldRef): AbortablePromise<Uint8Array>;
+  /**
+   * Hash the signed field's `/ByteRange` with `algorithm`, straight from
+   * the loaded bytes. What a CMS verifier compares its message digest to.
+   */
+  getDigest(field: FormFieldRef, algorithm: DigestAlgorithm): AbortablePromise<Uint8Array>;
+  /** The exact bytes of revision `revisionIndex` (`[0, end)`): what a signature over it signed. */
+  downloadRevision(revisionIndex: number): AbortablePromise<Uint8Array>;
+  /**
+   * What changed after a signature (or after any revision), judged
+   * revision by revision against the restrictions in force: every object
+   * whose cross-reference mapping moved, with its value and every
+   * reference to it in both revisions, and the rule that explains each —
+   * or the reference no rule explains. `until: 'working-copy'` snapshots
+   * unsaved edits as one more revision first. A truncated value is never
+   * permitted; a broken chain is `indeterminate`.
+   */
+  analyze(input: AnalyzeInput): AbortablePromise<ChangeAnalysis>;
+  /**
+   * Build the candidate (unsaved edits become their own revision, the
+   * signature lands in a fresh update over it), seal it, and return the
+   * digest to sign. The live document is untouched and read-only until
+   * `complete` or `abort` (`SigningPending`). Refusals are
+   * `SignatureRefused` with the reason in the message.
+   */
+  prepare(input: SignaturePrepareInput, options?: WriteOptions): AbortablePromise<SignaturePrepared>;
+  /**
+   * Write the CMS into the candidate and install the sealed bytes as the
+   * document's new version. `expectedVersion` must be what `prepare`
+   * returned (`SigningVersionMismatch` otherwise). Idempotent: a replay
+   * with the same CMS answers `already-completed`. Emits
+   * `signatures.completed` and `document.versioned`.
+   */
+  complete(input: SignatureCompleteInput, options?: WriteOptions): AbortablePromise<SignatureCompleteResult>;
+  /** Discard a pending candidate. */
+  cancel(signingId: string, options?: WriteOptions): AbortablePromise<SignatureCancelResult>;
+}
+//#endregion
+//#region src/engine/CustomMetadataService.d.ts
+/**
+ * The document's own Info-dict keys, as an object of their own: each key is
+ * a top-level field, so an update follows the one write rule (a key left
+ * out stays, `null` removes it, a string sets it).
+ */
+interface CustomMetadataService {
+  get(): AbortablePromise<CustomMetadata>;
+  /**
+   * Set and remove keys via a {@link CustomMetadataPatch}. Returns the keys
+   * as they are after the write plus cloud coherence pins (`null` for local
+   * engines). Gated by `doc.metadata.modify` on the cloud.
+   */
+  update(patch: CustomMetadataPatch, options?: WriteOptions): AbortablePromise<CustomMetadataUpdateResult>;
+}
+//#endregion
+//#region src/engine/MetadataService.d.ts
+interface MetadataService {
+  get(): AbortablePromise<DocumentMetadata>;
+  /**
+   * Rewrite the standard Info-dict fields via a three-state
+   * {@link MetadataPatch} (undefined=leave, null=clear, value=set). Returns
+   * the re-read metadata plus cloud coherence pins (`null` for local
+   * engines). Gated by `doc.metadata.modify` on the cloud.
+   */
+  update(patch: MetadataPatch, options?: WriteOptions): AbortablePromise<MetadataUpdateResult>;
+  /** The Info dict's other keys: an object of their own. */
+  readonly custom: CustomMetadataService;
+}
+//#endregion
+//#region src/engine/PageAnnotationsService.d.ts
+/**
+ * Per-page annotation service exposed via `PageHandle.annotations`.
+ *
+ * `list()` returns the page's fully typed annotations except widgets, which
+ * are the form's (`doc.forms.list()`); every annotation write of one page
+ * goes through this service.
+ */
+interface PageAnnotationsService {
+  /** This page's annotations except widgets, in display order: `doc.annotations.list()` for one page. */
+  list(): AbortablePromise<AnnotationList>;
+  /**
+   * Batch-render every annotation appearance (`/AP`) stream on the page,
+   * widgets excepted (`page.forms.renderAppearances()` has those), into
+   * its own image, sized to the annotation's `/Rect`: encoded by the engine's
+   * image encoder (local) or fetched as a `multipart/form-data` body (cloud),
+   * each a lazily-resolved `PageImageHandle`. Read-only and gated by
+   * `doc.annotate.read`: reading an annotation implies you may see its
+   * rendered appearance (the Adobe boundary).
+   */
+  renderAppearances(options?: AnnotationAppearanceImageOptions): AbortablePromise<AnnotationAppearanceImagesResult>;
+  /**
+   * One of an annotation's resources: the bytes `create(data, { resources })`
+   * takes to make the same annotation again. A read never contains them.
+   *
+   * - `appearance` (stamps): the drawing, as a one-page PDF, before the fit,
+   *   rotation and opacity the data describes. A stamp another tool made is
+   *   drawn as the page shows it, on a page the size of its `/Rect`.
+   * - `file` (file attachments): the attached file's exact bytes; its name,
+   *   MIME type and description are the data's `file`.
+   *
+   * Egresses content, so it needs `doc.download`. A role the annotation's
+   * kind doesn't take is refused with `InvalidArg`.
+   */
+  downloadResource(ref: AnnotationRef, role: AnnotationResourceRole): AbortablePromise<Uint8Array>;
+  /**
+   * Create an annotation on this page from its data. The options say how:
+   * bytes beside the data by role (`resources`: a stamp needs its
+   * `appearance`, a file attachment its `file`; a resource the kind doesn't
+   * take is refused), and the object number it gets (`objectNumber`, taken
+   * from `doc.objectNumbers`), which makes its ref known before the engine
+   * answers. Without a number the engine picks the next free one. Without
+   * an `nm` in the data the annotation gets a fresh UUIDv7 `/NM`.
+   *
+   * A number this session doesn't hold, or one an object already has, is
+   * refused with `ObjectNumberUnavailable`.
+   */
+  create(data: AnnotationDraft, options?: AnnotationCreateOptions): AbortablePromise<AnnotationCreateResult>;
+  /**
+   * Change the fields `patch` names; the others stay. A resource replaces
+   * what it is for: a stamp's drawing, an attached file's bytes.
+   */
+  update(ref: AnnotationRef, patch: AnnotationPatch, options?: AnnotationUpdateOptions): AbortablePromise<AnnotationUpdateResult>;
+  delete(ref: AnnotationRef, options?: WriteOptions): AbortablePromise<AnnotationDeleteResult>;
+  /**
+   * Change the stacking order: the annotations go together, in the order
+   * given, to `position` in the page's paint order (later paints over
+   * earlier): next to a neighbour (`{ before: ref }`, `{ after: ref }`) or at
+   * `'start'` (bottom) / `'end'` (top). Widgets paint above every annotation
+   * and have their own order (`doc.forms.reorderWidgets()`): a widget, as a
+   * row or a neighbour, is refused with `InvalidArg`. A neighbour that isn't
+   * on the page is `NotFound`. Answers the page's new order. Emits
+   * `annotations.reordered`.
+   */
+  reorder(refs: AnnotationRef[], position: AnnotationPosition, options?: WriteOptions): AbortablePromise<AnnotationReorderResult>;
+  /**
+   * Flatten the given annotations of this page into its content —
+   * `pages.flatten` for a chosen set. Painted annotations are removed from
+   * the page; ones that are ineligible (hidden for `usage`, Popups, no
+   * usable appearance) stay and report `unchanged`, so a caller can say
+   * "2 of 3 flattened". A content + annotation mutation of this page: its
+   * content and annotation pins advance, layout does not; a
+   * `annotations.flattened` event is published when anything was applied.
+   * Gated like `pages.flatten` (`doc.pages.modify` + `doc.annotate.modify`).
+   * `InvalidArg` for a ref on another page; `NotFound` for an unknown ref.
+   */
+  flatten(refs: AnnotationRef[], options?: FlattenWriteOptions): AbortablePromise<AnnotationFlattenResult>;
+  /**
+   * Flatten the normal appearances of the given annotations of this page
+   * into a new single-page PDF sized to their union `/Rect` — vector,
+   * positions preserved, exactly as this page shows them. The same plan as
+   * `flatten` aimed at a fresh page; the source document is untouched. A
+   * derived read that egresses content, so it is gated by `doc.download`
+   * like `pages.extract`. All-or-nothing: `InvalidArg` when any ref is not
+   * on this page, hidden, or has no appearance (a stamp silently missing a
+   * part would be worse than an error).
+   */
+  exportAppearance(refs: AnnotationRef[]): AbortablePromise<Uint8Array>;
+}
+/** A local engine page's annotations: the shared service and the raw appearance pixels. */
+interface LocalPageAnnotationsService extends PageAnnotationsService {
+  /**
+   * The same appearances as `renderAppearances()`, each as its own raw RGBA
+   * raster instead of an encoded image.
+   */
+  renderAppearancesRaw(options?: AnnotationAppearanceRenderOptions): AbortablePromise<AnnotationAppearancesResult>;
+}
+//#endregion
+//#region src/engine/PageFormsService.d.ts
+/**
+ * Per-page form service exposed via `PageHandle.forms`: the page's widget
+ * images. The widgets themselves are rows of the form
+ * (`doc.forms.list().widgets`).
+ */
+interface PageFormsService {
+  /**
+   * Batch-render every widget appearance (`/AP`) on the page, every mode and
+   * every state, each into its own image sized to the widget's `/Rect` —
+   * what `page.annotations.renderAppearances()` does for the other
+   * annotations. Gated by `doc.forms.read`.
+   */
+  renderAppearances(options?: AnnotationAppearanceImageOptions): AbortablePromise<AnnotationAppearanceImagesResult>;
+}
+/** A local engine page's form: the shared service and the raw appearance pixels. */
+interface LocalPageFormsService extends PageFormsService {
+  /** The same appearances as `renderAppearances()`, each as its own raw RGBA raster. */
+  renderAppearancesRaw(options?: AnnotationAppearanceRenderOptions): AbortablePromise<AnnotationAppearancesResult>;
+}
+//#endregion
+//#region src/engine/PageRenderService.d.ts
+interface PageRenderService {
+  image(options?: PageImageOptions): AbortablePromise<PageRenderImage>;
+}
+/** A local engine page's rendering: an image, or the pixels themselves. */
+interface LocalPageRenderService extends PageRenderService {
+  /** The page's pixels, with the transform they were made with, not encoded as an image. */
+  raw(options?: PageRenderOptions): AbortablePromise<PageRenderRaster>;
+}
+//#endregion
+//#region src/engine/PageTextService.d.ts
+/**
+ * Per-page text service exposed via `PageHandle.text`. Text changes only
+ * with the page's content.
+ */
+interface PageTextService {
+  /**
+   * The page's text in reading order, its character count and, when the two
+   * numberings differ, the character↔text map. Needs `doc.text.copy`.
+   */
+  get(): AbortablePromise<PageTextSnapshot>;
+  /** The text of a character range: the copy primitive. Needs `doc.text.copy`. */
+  slice(range: TextRange): AbortablePromise<string>;
+  /**
+   * Where the page's characters are: hit-testing, words and lines, and the
+   * segments to draw a selection or a highlight. Needs `doc.text.select`
+   * (where text is, not what it says).
+   */
+  layout(): AbortablePromise<TextLayout>;
+}
+//#endregion
+//#region src/engine/PageMeasureService.d.ts
+interface PageMeasureService {
+  /** Viewports in drawing order. Last containing viewport wins, including foreign ones. */
+  listViewports(): AbortablePromise<PageMeasurementViewportList>;
+  /** Upsert/remove EmbedPDF's full-page calibration. Other producers' entries survive.
+   * Existing annotations retain their own scale snapshots. */
+  setScale(measure: PdfMeasure | null, options?: WriteOptions): AbortablePromise<PageScaleResult>;
+}
+//#endregion
+//#region src/engine/PageHandle.d.ts
+/**
+ * Page-scoped handle returned by `DocumentHandle.page(ref)`. The handle is
+ * keyed on the page's durable address (its PDF indirect object number),
+ * never the page index, so it survives page-list mutations.
+ */
+interface PageHandle {
+  readonly ref: PageRef;
+  readonly annotations: PageAnnotationsService;
+  readonly forms: PageFormsService;
+  readonly text: PageTextService;
+  readonly render: PageRenderService;
+  readonly measure: PageMeasureService;
+}
+//#endregion
+//#region src/events/DocumentEvent.d.ts
+/**
+ * Provenance of a `DocumentEvent` — whose hand caused the mutation, never
+ * which transport delivered it (transport is invisible by design).
+ *
+ * `kind: 'local'` means made through this open document (this handle), not
+ * "this user". Every open is its own session: the same user in two tabs, or
+ * an app that opens one cloud document twice, is two sessions, and a
+ * mutation made through one arrives in the other as `'remote'` (with the
+ * same `sub`). Rule of thumb for consumers: "is this my action" → check
+ * `kind` / `sessionId` (undo stacks, optimism reconciliation); "is this my
+ * user" → check `sub` (attribution).
+ */
+interface EventOrigin {
+  /** 'local' = made through this handle; 'remote' = another session. */
+  kind: 'local' | 'remote';
+  /** Identifies the session (the open document handle) that made the mutation. */
+  sessionId: string;
+  /** Authenticated subject of the originator (cloud); `null` locally. */
+  sub: string | null;
+  /** Mutation timestamp (server ts for remote, client ts for local). */
+  ts: number;
+  /** Server audit-log row id — monotonic per document, the resume cursor.
+   *  `null` until the mutation has a server identity (local engines; cloud
+   *  own-mutation events before the server echoes the id). */
+  serverId: number | null;
+  /**
+   * Set when this fact is one of several committed together, such as the
+   * annotations of one import: they share `id`, and `index` counts from 0 to
+   * `count - 1` in the order they were emitted.
+   */
+  tx?: {
+    id: string;
+    index: number;
+    count: number;
+  };
+  /** Set on the events of an undo: the `opId` of the change it undid. */
+  undoOf?: string;
+}
+/**
+ * The one event stream both engines speak — the model is the contract, the
+ * transport differs (local: in-process after the worker confirms; cloud:
+ * in-process for your own mutations, SSE for everyone else's).
+ *
+ * Invariants (locked — the collaboration design rests on these):
+ *
+ *   - exactly once: every mutation that touches your document appears in
+ *     your stream exactly once. The handle that performs a mutation emits
+ *     the event itself at confirmation time; the remote channel exists to
+ *     tell everyone else (own echoes are dropped by `sessionId`). A change
+ *     that commits several facts at once, such as an import, emits one
+ *     event per fact, back to back, sharing `origin.tx`.
+ *   - ground truth only: events fire after the mutation is confirmed —
+ *     never optimistically. Optimism is a plugin concern.
+ *   - results ride verbatim: each event embeds the mutation result the
+ *     caller received, unmodified — which (cloud) is byte-identical to the
+ *     audit-log payload. A handler sees the same fact whether it performed
+ *     the mutation, watched it locally, or received it over the wire.
+ *   - published before settlement: the event for a session's own mutation
+ *     reaches subscribers before the mutation's promise settles, so a caller
+ *     awaiting the mutation already sees every state derived from the event.
+ *
+ * Handlers updating UI/document state should be origin-agnostic ("a page
+ * was removed → update the registry"); `origin` is metadata for the few
+ * provenance-aware features (undo, attribution toasts, camera etiquette).
+ */
+type DocumentEvent = ({
+  type: 'pages.scaleSet';
+  origin: EventOrigin;
+} & PageScaleResult) | ({
+  type: 'annotations.created';
+  page: PageRef;
+  origin: EventOrigin;
+} & AnnotationCreateResult) | ({
+  type: 'annotations.updated';
+  page: PageRef;
+  origin: EventOrigin;
+} & AnnotationUpdateResult) | ({
+  type: 'annotations.deleted';
+  page: PageRef;
+  origin: EventOrigin;
+  /**
+   * What was deleted: the annotation and what went with it (replies,
+   * grouped parts, review states, popups), the annotation first; see
+   * `deletedAnnotationsOf`.
+   */
+  deleted: AnnotationRef[];
+} & AnnotationDeleteResult) | ({
+  /** A stacking-order change: the page's annotations in their new order. */
+  type: 'annotations.reordered';
+  page: PageRef;
+  origin: EventOrigin;
+} & AnnotationReorderResult) | {
+  /**
+   * An undo brought deleted annotations back: the same objects, under
+   * the refs they had, with their owner, replies and popup. A listener
+   * that keeps things by ref (comments, links) attaches them again.
+   */
+  type: 'annotations.restored';
+  page: PageRef;
+  origin: EventOrigin;
+  /** What came back, in `/Annots` order: the annotation first, then what went with it. */
+  annotations: Annotation[];
+  meta: AnnotationListMutationMeta;
+} | ({
+  type: 'annotations.flattened';
+  origin: EventOrigin;
+} & AnnotationFlattenResult) | ({
+  type: 'pages.reordered';
+  origin: EventOrigin;
+} & PageReorderResult) | ({
+  type: 'pages.rotated';
+  pages: PageRef[];
+  rotation: PdfRotation;
+  origin: EventOrigin;
+} & PageRotateResult) | ({
+  type: 'pages.deleted';
+  /** The retired pages — not derivable from the surviving `layout`. */
+  pages: PageRef[];
+  origin: EventOrigin;
+} & PageDeleteResult) | ({
+  type: 'pages.inserted';
+  origin: EventOrigin;
+} & PageInsertResult) |
+/** An undo brought deleted pages back, or a redo brought inserted pages back. */
+({
+  type: 'pages.restored';
+  origin: EventOrigin;
+} & PageRestoreResult) | ({
+  type: 'pages.named';
+  /** The decoded key that was registered, renamed, or removed. */
+  name: string;
+  /** The page it now points at; `null` when the registration was removed. */
+  page: PageRef | null;
+  origin: EventOrigin;
+} & PageNameResult) | ({
+  type: 'attachments.created';
+  origin: EventOrigin;
+} & AttachmentCreateResult) | ({
+  type: 'attachments.deleted';
+  origin: EventOrigin;
+  /** What was deleted (see `deletedAttachmentOf`). */
+  deleted: AttachmentRef | null;
+} & AttachmentDeleteResult) |
+/** An undo brought a deleted file back, under the key it had. */
+({
+  type: 'attachments.restored';
+  origin: EventOrigin;
+} & AttachmentRestoreResult) | ({
+  type: 'metadata.updated';
+  origin: EventOrigin;
+} & MetadataUpdateResult) | ({
+  type: 'metadata.customUpdated';
+  origin: EventOrigin;
+} & CustomMetadataUpdateResult) | ({
+  type: 'outline.created';
+  origin: EventOrigin;
+} & OutlineCreateResult) | ({
+  type: 'outline.updated';
+  origin: EventOrigin;
+} & OutlineUpdateResult) | ({
+  type: 'outline.moved';
+  origin: EventOrigin;
+} & OutlineMoveResult) | ({
+  type: 'outline.deleted';
+  origin: EventOrigin;
+  /** What was deleted: the item first, then the items under it (see `deletedOutlineItemsOf`). */
+  deleted: OutlineItemRef[];
+} & OutlineDeleteResult) | ({
+  /**
+   * An undo brought deleted outline items back: the same items, under the
+   * refs they had, at the place the item had among its parent's children.
+   */
+  type: 'outline.restored';
+  origin: EventOrigin;
+} & OutlineRestoreResult) | ({
+  type: 'forms.valueSet';
+  origin: EventOrigin;
+} & FormSetValueResult) | ({
+  type: 'forms.repaired';
+  origin: EventOrigin;
+} & FormRepairResult) | ({
+  type: 'forms.created';
+  origin: EventOrigin;
+} & FormFieldCreateResult) | ({
+  type: 'forms.updated';
+  origin: EventOrigin;
+} & FormFieldUpdateResult) | ({
+  type: 'forms.deleted';
+  origin: EventOrigin;
+  /** The field that went (see `deletedFieldOf`). */
+  deleted: FormFieldRef | null;
+} & FormFieldDeleteResult) | {
+  /**
+   * An undo brought a deleted field back: the same field and widgets,
+   * under the refs they had, at their places, with its value.
+   */
+  type: 'forms.restored';
+  origin: EventOrigin;
+  field: FormFieldDTO;
+  widgets: WidgetAnnotation[];
+  meta: FormMutationMeta;
+} | ({
+  type: 'forms.widgetAdded';
+  origin: EventOrigin;
+} & FormWidgetLinkResult) | ({
+  type: 'forms.widgetRemoved';
+  origin: EventOrigin;
+} & FormWidgetLinkResult) | ({
+  type: 'forms.widgetDeleted';
+  origin: EventOrigin;
+} & FormWidgetDeleteResult) | ({
+  /** An undo brought a deleted widget back: onto its page at its place, into its field. */
+  type: 'forms.widgetRestored';
+  origin: EventOrigin;
+} & FormWidgetRestoreResult) | ({
+  type: 'forms.widgetUpdated';
+  origin: EventOrigin;
+} & FormWidgetUpdateResult) | ({
+  /** A stacking-order change: the page's widgets in their new order. */
+  type: 'forms.widgetsReordered';
+  origin: EventOrigin;
+} & FormWidgetsReorderResult) | ({
+  /** A calculation-order change: the form's whole new order. */
+  type: 'forms.calculationsReordered';
+  origin: EventOrigin;
+} & FormCalculationsReorderResult) | ({
+  type: 'pages.flattened';
+  pages: PageRef[];
+  usage: PageFlattenUsage;
+  origin: EventOrigin;
+} & PageFlattenResult) | ({
+  type: 'redaction.applied';
+  origin: EventOrigin;
+} & RedactionApplyResult) | ({
+  /** A signing candidate was parked: the document is read-only until it completes or is cancelled. */
+  type: 'signatures.prepared';
+  field: FormFieldRef;
+  origin: EventOrigin;
+} & SignaturePrepared) | ({
+  /** The sealed bytes are installed; `version` is what they became. */
+  type: 'signatures.completed';
+  signingId: string;
+  origin: EventOrigin;
+} & SignatureCompleteResult) | {
+  type: 'signatures.cancelled';
+  signingId: string;
+  origin: EventOrigin;
+} | {
+  /**
+   * The session moved to a new saved version (a completed signature,
+   * here or in another session). Byte-level facts — revisions,
+   * coverage, digests, verdicts — must be re-read.
+   */
+  type: 'document.versioned';
+  version: BaseVersionInfo;
+  origin: EventOrigin;
+} | {
+  /**
+   * Cloud only: the live event stream fell too far behind to replay
+   * (the server's SSE `full-refresh`) — state derived from earlier
+   * events or snapshots may be stale, and the gap's mutations will
+   * never arrive as events. Consumers must re-read the snapshots they
+   * keep fresh from this stream (`doc.annotations.list()`,
+   * `doc.forms.list()`, …).
+   *
+   * Carries no `EventOrigin`: it is a transport notice, not a
+   * document mutation — the exactly-once / results-ride-verbatim
+   * invariants above apply to mutation events only. The local engine
+   * never emits it.
+   */
+  type: 'stream.desynced';
+  reason: 'backlog-overflow';
+  ts: number;
+};
+type DocumentEventType = DocumentEvent['type'];
+/** The event of one type, such as `DocumentEventOf<'annotations.created'>`. */
+type DocumentEventOf<T extends DocumentEventType> = Extract<DocumentEvent, {
+  type: T;
+}>;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** A `DocumentEvent` before provenance is stamped — what mutation paths
+ *  hand to their engine's publisher, which adds `origin`. Transport
+ *  notices (`stream.desynced`) are excluded: they are published directly
+ *  by the remote channel, never through a mutation publisher. */
+type DocumentEventInit = DistributiveOmit<Exclude<DocumentEvent, {
+  type: 'stream.desynced';
+}>, 'origin'>;
+//#endregion
+//#region src/events/DocumentEventStream.d.ts
+/**
+ * The subscription surface on `DocumentHandle.events`: every event with
+ * `subscribe`, one type with `on`. No replay-from-id: plugins build their
+ * own filter wrappers (per-page, …) on top.
+ *
+ * Delivery is synchronous fan-out with error isolation: a throwing
+ * listener never blocks other listeners, and never fails the mutation
+ * whose confirmation produced the event.
+ */
+interface DocumentEventStream {
+  /** Subscribe to every event for this document. Returns the unsubscriber. */
+  subscribe(listener: (event: DocumentEvent) => void): () => void;
+  /** Subscribe to one type of event, typed by it. Returns the unsubscriber. */
+  on<T extends DocumentEventType>(type: T, listener: (event: DocumentEventOf<T>) => void): () => void;
+  /**
+   * Highest `origin.serverId` observed so far — the reconnect/backfill
+   * cursor for the remote channel. `null` until a remote-identified event
+   * has been seen (always `null` on purely-local engines).
+   */
+  lastServerId(): number | null;
+}
+/**
+ * `on(type, listener)` built on a stream's `subscribe`, so both engines
+ * filter the same way and a type listener counts as a subscriber (the cloud
+ * opens its live stream for the first one).
+ */
+declare function subscribeToType<T extends DocumentEventType>(subscribe: DocumentEventStream['subscribe'], type: T, listener: (event: DocumentEventOf<T>) => void): () => void;
+//#endregion
+//#region src/scheduling/facts.d.ts
+/**
+ * How much a call matters, with `fetch`'s words. The caller says it, so the
+ * engine knows no feature: a viewer gives `high` to what its views are for.
+ * Most calls say nothing (`auto`).
+ *
+ * - `high`: the main thing a view shows of a page: its picture, in a viewer.
+ * - `auto`: everything else about the document and what's shown (the default).
+ * - `low`: background work, about nothing the views show (a search scan): it
+ *   runs after everything else.
+ *
+ * Where a page is on screen counts before `high` and `auto` (see `rank`), so
+ * a caller never says where its page is: the views say that.
+ */
+type CallPriority = 'high' | 'auto' | 'low';
+/**
+ * What's true about a call for as long as it waits (`doc.with(facts)`). Both
+ * are fixed once the call is made; when a result becomes urgent later, its
+ * owner asks again.
+ */
+interface CallFacts {
+  /** Default `auto`. */
+  readonly priority?: CallPriority;
+  /**
+   * The view the call serves, when its result is that view's own (a render
+   * layer's pixels): the call then ranks by where its page is in that view.
+   * Absent: the result is shared by every view (text, links, annotations),
+   * and the call ranks by the best place its page has in any of them.
+   */
+  readonly view?: string;
+}
+/**
+ * A page a view shows (`doc.setWorkingSet`). The engine ranks the calls for
+ * the page by it, and keeps the pages it shows parsed longest.
+ */
+interface WorkingSetPage {
+  readonly page: PageRef;
+  /** `visible`: some of it is on screen. `near`: placed just off screen, where the view goes next. */
+  readonly role: 'visible' | 'near';
+  /** The part on screen, in page space. Absent: the whole page, or none of a near page. */
+  readonly visible?: PageBox;
+  /** Device pixels of it on screen: what ranks visible pages among themselves. 0 for a near page. */
+  readonly pixels: number;
+}
+//#endregion
+//#region src/engine/DocumentHandle.d.ts
+/**
+ * A document an engine opened: the same on every engine. What only the local
+ * engine can do lives on `LocalDocumentHandle` (see `isLocalDocument`).
+ */
+interface DocumentHandle {
+  readonly id: string;
+  readonly security: DocumentSecurityService;
+  readonly metadata: MetadataService;
+  readonly annotations: DocumentAnnotationsService;
+  /** Lazy catalog-owned action extraction. The engine never executes scripts. */
+  readonly actions: DocumentActionsService;
+  /**
+   * Document-level attachments (the catalog's `/EmbeddedFiles` name tree).
+   * Files attached to annotations are read via
+   * `page(ref).annotations.downloadResource(ref, 'file')`.
+   */
+  readonly attachments: DocumentAttachmentsService;
+  /** The document's interactive form (AcroForm): fields, values, interchange. */
+  readonly forms: DocumentFormsService;
+  /** The document's outline (`/Root /Outlines`, the bookmarks): its items, read and written. */
+  readonly outline: DocumentOutlineService;
+  /** Document text search: budgeted, cursor-resumable slices. */
+  readonly search: DocumentSearchService;
+  /**
+   * Render policy surface (`doc.render.getPolicy()`): the engine's render
+   * lattice, or `continuous` on engines that render any viewport exactly
+   * (the local engine). Pixels stay on `page(ref).render` — this carries
+   * policy only. Conformance is explicit via `snapFullPageViewport`; no
+   * engine ever snaps a render call implicitly.
+   */
+  readonly render: DocumentRenderService;
+  /**
+   * Document-scoped page service. Use for cross-page operations:
+   *   - `pages.list()` for the current display order.
+   *   - `pages.reorder(refs, position)` for reorder.
+   *
+   * Per-page reads/writes still live on `page(ref).annotations`.
+   */
+  readonly pages: DocumentPagesService;
+  /**
+   * Destructive redaction apply (the second stage of the two-stage model;
+   * marking rides the normal annotation verbs).
+   */
+  readonly redaction: DocumentRedactionService;
+  /**
+   * Digital signatures: the read side (revisions, signed fields, the
+   * protection they impose) and the two-phase signing protocol.
+   */
+  readonly signatures: DocumentSignaturesService;
+  /**
+   * The document's event stream — every confirmed mutation, exactly once,
+   * identical shape on local and cloud engines (see `DocumentEvent`). Each
+   * open is its own session, named on each event's `origin.sessionId`.
+   */
+  readonly events: DocumentEventStream;
+  /**
+   * This session's reserved object numbers: take one to name an object
+   * before creating it (`page.annotations.create(data, { objectNumber })`,
+   * `pages.insertBlank(spec, position, { objectNumbers })`, `forms.create`,
+   * `forms.addWidget`). Its ref is then known at once and stays its name
+   * for life. Creates without a number still work; the engine picks one.
+   */
+  readonly objectNumbers: ObjectNumberPool;
+  /**
+   * A handle for the page `ref` names: an address with the page's verbs,
+   * made without asking the engine anything (so synchronous). The page is
+   * looked up when a call runs; a page the document doesn't have fails that
+   * call with `NotFound`. It carries no page data: `pages.list()` does.
+   */
+  page(ref: PageRef): PageHandle;
+  /**
+   * Apply one change, as one transaction: its ops in order, all of them or
+   * none (`{ ops }`), or the reverse of an earlier write (`{ undoOf: opId }`).
+   * Put everything one user action does into one change; it is one audit
+   * row, one burst of events and one undo step. An undo applies where the
+   * document still shows what the write set, and its items list what it left
+   * alone (`skipped`). Its own result is undoable: that is redo.
+   */
+  apply(change: Change, options?: WriteOptions): AbortablePromise<ChangeResult>;
+  /**
+   * The same document, every call made through it carrying `facts`: whether
+   * a person waits on it, and the view it serves (see {@link CallFacts}). Most
+   * calls need none. The local engine ranks the jobs it runs by them; the
+   * cloud engine sends every call as it's made, so it ignores them.
+   */
+  with(facts: CallFacts): DocumentHandle;
+  /**
+   * What `view` shows of the document. The local engine ranks the jobs for
+   * those pages by it, ranking again whatever waits each time a set arrives,
+   * and keeps the pages it shows parsed longest. Each call replaces the view's
+   * last set; an empty set withdraws it. A hint: it changes no result. The
+   * cloud engine ignores it.
+   */
+  setWorkingSet(view: string, pages: readonly WorkingSetPage[]): void;
+  download(options?: DownloadOptions): AbortablePromise<Uint8Array>;
+  close(): AbortablePromise<void>;
+}
+//#endregion
+//#region src/engine/Engine.d.ts
+/**
+ * Engine contract shared by `@embedpdf/engine` and
+ * `@cloudpdf/engine`. Both implementations expose the same
+ * `open()` surface and return the same {@link DocumentHandle} shape;
+ * the only observable difference is transport — local goes through a
+ * Worker + WASM PDFium, cloud goes through HTTPS to a remote server. What
+ * only the local engine can do lives on `LocalEngine` (see `isLocalEngine`).
+ *
+ * Authorization parity:
+ *   - Cloud reads scope + identity from the doc-scoped JWT it gets at
+ *     transport setup time. `OpenOptions.scope` / `OpenOptions.identity`
+ *     are silently ignored by cloud (the JWT is the authority).
+ *   - Local reads scope + identity from `OpenOptions.scope` /
+ *     `OpenOptions.identity` (no JWT involved). Defaults to `['*']`
+ *     wildcard with a one-time console warning.
+ *
+ * Both engines run the same resolver against the same `pdf.permissions`
+ * expansion → identical allow/deny decisions for the same
+ * scope+identity+PDF-bits inputs. The parity test at
+ * `engine-core/test/scope-parity.test.ts` (commit 17) locks this in.
+ */
+interface Engine {
+  /**
+   * Whether `open()` takes a file's own bytes (`{ kind: 'bytes' }`), such as a file someone
+   * picked on their computer. The local engine does; the cloud engine opens only the documents
+   * your server holds (`'id'`, `'token'`, `'share'`).
+   */
+  readonly canOpenFiles: boolean;
+  open(input: OpenInput, options?: OpenOptions): AbortablePromise<DocumentHandle>;
+  destroy(): AbortablePromise<void>;
+}
+/**
+ * A thunk that constructs a fresh {@link Engine}. Construction is synchronous
+ * and cheap — engines allocate no live resources (no Worker, no WASM, no
+ * socket) until first use — so the thunk exists purely to express ownership:
+ *
+ *   - Pass an `Engine` instance to an adapter (`<Viewer>`, `provideEmbedPdf`)
+ *     and it is borrowed: the adapter never destroys it. You own the
+ *     lifetime — the module-scope singleton case.
+ *   - Pass a thunk (`() => localEngine()`) and the adapter owns the result:
+ *     it calls the thunk on mount and destroys the engine on unmount. Use
+ *     this for per-mount isolation (StrictMode/HMR-clean teardown,
+ *     multi-viewer independence).
+ *
+ * Deliberately synchronous — an async thunk would reintroduce a "maybe
+ * engine" that every consumer must await (the deferredEngine problem this
+ * design removed). Async acquisition (dynamic `import()`, remote config)
+ * belongs outside the thunk: await it, then hand over the instance. Code
+ * that genuinely needs a lazily-resolved engine models that itself with
+ * `Engine | Promise<Engine>` (see the stamp plugin's `assetEngine`).
+ */
+type EngineFactory = () => Engine;
+//#endregion
+//#region src/engine/FontService.d.ts
+/**
+ * Engine-level service for registering runtime fonts and configuring the
+ * ordered glyph-fallback chain. Runtime-global, not document-scoped: a
+ * registered font is shared by every page render and annotation-authoring
+ * call on the engine's PDFium thread, and survives document open/close.
+ *
+ * Availability is the deliberate local-vs-cloud split:
+ *   - `@embedpdf/engine` (local/WASM) implements it: the developer embedding
+ *     the viewer decides what fonts ship to the client runtime.
+ *   - `@cloudpdf/engine` (cloud) does not expose it (`Engine.fonts` is
+ *     undefined). Fallback fonts are a server policy decision, loaded once on
+ *     the server runtime; clients cannot influence them.
+ *
+ * `register` and `addFallback` are intentionally separate calls: registering a
+ * font makes it available for explicit annotation authoring
+ * (a free text's `fontFamily`); adding it to the fallback chain *also*
+ * makes it eligible for automatic missing-glyph substitution during page
+ * rendering and appearance generation. Many fonts want one without the other.
+ */
+interface FontService {
+  /**
+   * Register a single font under its `key`. Idempotent: registering a `key`
+   * already known resolves to the existing handle without re-uploading bytes
+   * to the runtime.
+   *
+   * Rejects with `EngineErrorCode.InvalidArg` when the runtime cannot load the
+   * font (corrupt file, unsupported format, no glyphs), and for a key that is
+   * empty or one of the 14 standard font names (`'helvetica'`, …), which a
+   * `fontFamily` always resolves to the standard font.
+   */
+  register(spec: FontSpec): AbortablePromise<FontHandle>;
+  /** Register several fonts, preserving order. */
+  registerAll(specs: FontSpec[]): AbortablePromise<FontHandle[]>;
+  /**
+   * Append a registered font to the ordered fallback chain. Order is
+   * precedence: the first registered font that covers a missing glyph wins,
+   * with style (weight/italic) used as a tie-breaker by the runtime.
+   */
+  addFallback(font: FontHandle | FontKey): AbortablePromise<void>;
+  /** Clear the fallback chain without unregistering the fonts themselves. */
+  clearFallbacks(): AbortablePromise<void>;
+  /** Unregister every font and reset the fallback chain. */
+  clear(): AbortablePromise<void>;
+  /**
+   * Assert that the application holds a licence permitting editing with a
+   * preview-and-print font, so FreeText authoring and missing-glyph fallback
+   * may use it. Resolves to the updated handle (`editingAuthorized: true`).
+   * Rejects with `InvalidArg` for an unregistered key.
+   */
+  authorizeEditing(font: FontHandle | FontKey): AbortablePromise<FontHandle>;
+  /** Currently registered fonts, in registration order. */
+  list(): readonly FontHandle[];
+}
+//#endregion
+//#region src/engine/DocumentFontSettings.d.ts
+/**
+ * How much of a registered font's program the appearances authored in this
+ * document carry. `default` subsets annotation text (FreeText, redaction
+ * labels) and embeds form-field text whole; `subset` and `full` apply to
+ * both. A font whose licence forbids subsetting is embedded whole under
+ * every policy; programs already in the document are never re-embedded.
+ */
+type FontEmbeddingPolicy = 'default' | 'subset' | 'full';
+/**
+ * Per-document font and text-layout settings: session state of this
+ * document handle, never written to the file, applied to appearances
+ * generated after the call. Local engine only (`doc.fonts` is undefined on
+ * engines that do not lay text out in-process).
+ */
+interface DocumentFontSettings {
+  setEmbeddingPolicy(policy: FontEmbeddingPolicy): AbortablePromise<void>;
+  /**
+   * Latin typographic features (kerning, ligatures) when shaping rich text.
+   * Off by default: Acrobat's appearances show plain advance widths and no
+   * ligatures, and parity with what Acrobat draws wins.
+   */
+  setTypographicFeatures(enabled: boolean): AbortablePromise<void>;
+}
+//#endregion
+//#region src/dto/PieceInfo.d.ts
+/**
+ * Page-piece metadata (ISO 32000 §14.5): private, application-scoped data
+ * under `/PieceInfo` on a page or on the document catalog. The engine
+ * round-trips a constrained, wire-safe value vocabulary; anything else in
+ * the file is preserved untouched and surfaced as `{ type: 'unknown' }`.
+ *
+ * Reads are lossless-tagged (a PDF name and a PDF string both arrive as
+ * JS strings, so the tag is what keeps them distinguishable); writes take
+ * plain JS values, with `{ name: '...' }` as the one wrapper needed to
+ * request a PDF name. `/LastModified` bookkeeping (application dict, page
+ * dict, doc /Info /ModDate) is engine-managed on every write.
+ */
+/** One `/Private` value as read from the file. */
+type PieceInfoEntry = {
+  type: 'string';
+  value: string;
+} | {
+  type: 'name';
+  value: string;
+} | {
+  type: 'number';
+  value: number;
+} | {
+  type: 'boolean';
+  value: boolean;
+} | {
+  type: 'string-array';
+  value: string[];
+} |
+/** Present in the file but outside the supported vocabulary — preserved
+ *  by writes to sibling keys, not readable through this API. */
+{
+  type: 'unknown';
+};
+/** A write value: plain JS, `{ name }` requests a PDF name, `null` deletes. */
+type PieceInfoPatchValue = string | number | boolean | readonly string[] | {
+  name: string;
+};
+type PieceInfoPatch = Record<string, PieceInfoPatchValue | null>;
+interface PieceInfoSnapshot {
+  /** The application's `/Private` entries, keyed by PDF key name. */
+  entries: Record<string, PieceInfoEntry>;
+  /** The application data dict's `/LastModified` (null if absent). */
+  modifiedAt: IsoDateTime | null;
+}
+//#endregion
+//#region src/engine/PieceInfoService.d.ts
+/** Result of `pieceInfo.update()`: the application's data after the write. */
+interface PieceInfoUpdateResult {
+  pieceInfo: PieceInfoSnapshot | null;
+  meta: MutationMeta;
+}
+/** Result of `pieceInfo.delete()`: nothing exists after it, so only `meta`. */
+interface PieceInfoDeleteResult {
+  meta: MutationMeta;
+}
+/**
+ * Access to `/PieceInfo` private application data (ISO 32000 §14.5). The
+ * same interface serves both levels — `DocumentHandle.pieceInfo?` reads and
+ * writes the catalog's `/PieceInfo`, `PageHandle.pieceInfo?` the page's —
+ * mirroring the native API's doc/page symmetry.
+ *
+ * Optional on the contract while the cloud endpoints ship (the
+ * `downloadLayer?` pattern): the local engine implements it; the cloud
+ * engine omits it until a cloud consumer exists (writes there also need an
+ * authorization-scope decision — currently they ride `doc.metadata.modify`
+ * locally). Feature-detect with `handle.pieceInfo !== undefined`.
+ *
+ * Writes are engine-managed for spec bookkeeping: every update refreshes
+ * the application dict's `/LastModified`, the page's `/LastModified`
+ * (required once `/PieceInfo` is present), and — for catalog writes — the
+ * document `/Info` `/ModDate`. No document event is published: piece data
+ * is private app state, not rendered document state.
+ */
+interface PieceInfoService {
+  /**
+   * The application's data, or null when the holder has no well-formed
+   * entry for it. Unknown value types arrive as `{ type: 'unknown' }` and
+   * survive sibling writes untouched.
+   */
+  get(application: string): AbortablePromise<PieceInfoSnapshot | null>;
+  /**
+   * Merge-write entries into the application's `/Private` dictionary:
+   * strings/numbers/booleans/string-arrays write as the corresponding PDF
+   * types, `{ name }` writes a PDF name, `null` deletes the key. One call
+   * is one worker job — atomic with respect to every other engine
+   * operation on this document.
+   */
+  update(application: string, patch: PieceInfoPatch, options?: WriteOptions): AbortablePromise<PieceInfoUpdateResult>;
+  /** Application names present under this holder's `/PieceInfo`. */
+  list(): AbortablePromise<string[]>;
+  /** Remove the application's entire entry (sibling applications survive). */
+  delete(application: string, options?: WriteOptions): AbortablePromise<PieceInfoDeleteResult>;
+}
+//#endregion
+//#region src/engine/LocalPageHandle.d.ts
+/**
+ * A page of a document the local engine opened (`LocalDocumentHandle.page()`):
+ * the shared {@link PageHandle}, its raw pixels and its `/PieceInfo`.
+ */
+interface LocalPageHandle extends PageHandle {
+  readonly annotations: LocalPageAnnotationsService;
+  readonly forms: LocalPageFormsService;
+  readonly render: LocalPageRenderService;
+  /**
+   * Page-level `/PieceInfo` private application data (ISO 32000 §14.5), such
+   * as a stamp page's name and subject.
+   */
+  readonly pieceInfo: PieceInfoService;
+}
+/** Whether `page` is a page of a local engine's document, with its raw pixels and `/PieceInfo`. */
+declare function isLocalPage(page: PageHandle): page is LocalPageHandle;
+//#endregion
+//#region src/engine/LocalDocumentHandle.d.ts
+/**
+ * A document the local engine opened: the shared {@link DocumentHandle} and
+ * what only an engine running PDFium itself can do. Code that takes any
+ * document checks with {@link isLocalDocument}.
+ */
+interface LocalDocumentHandle extends DocumentHandle {
+  /** Font embedding and text layout settings of this document (session state). */
+  readonly fonts: DocumentFontSettings;
+  /**
+   * Catalog-level `/PieceInfo` private application data (ISO 32000 §14.5),
+   * such as a stamp library's display name. Per-page piece data lives on
+   * `page(ref).pieceInfo`.
+   */
+  readonly pieceInfo: PieceInfoService;
+  page(ref: PageRef): LocalPageHandle;
+  with(facts: CallFacts): LocalDocumentHandle;
+  /**
+   * Node only: write the document to a local file without moving its bytes
+   * through JS. An untouched session (no unsaved edits, incremental mode) is
+   * streamed out verbatim; for a signed document, exactly as sealed.
+   */
+  downloadToFile(path: string, options?: DownloadOptions): AbortablePromise<void>;
+  /**
+   * The saved version this session is on: SHA-256 and length of the loaded
+   * bytes (for a layer session, of its base). Changes only when a signature
+   * completes.
+   */
+  version(): AbortablePromise<BaseVersionInfo>;
+  /**
+   * Export just this document's layer as a self-contained artifact (the small
+   * overlay diff over the unchanged base), which `open()` takes back with
+   * `{ kind: 'artifact', bytes }`.
+   */
+  downloadLayer(): AbortablePromise<Uint8Array>;
+}
+/**
+ * Whether `doc` is a local engine's document, with its fonts, `/PieceInfo`,
+ * layers, raw pixels and files.
+ */
+declare function isLocalDocument(doc: DocumentHandle): doc is LocalDocumentHandle;
+//#endregion
+//#region src/engine/LocalEngine.d.ts
+/**
+ * The engine that runs PDFium itself, in the browser or in Node: the shared
+ * {@link Engine} and what only it can do. `localEngine()` returns one, so an
+ * app built on it reaches these without a check; code that takes any engine
+ * checks with {@link isLocalEngine}.
+ */
+interface LocalEngine extends Engine {
+  open(input: OpenInput, options?: OpenOptions): AbortablePromise<LocalDocumentHandle>;
+  /**
+   * Start booting the engine (Worker spawn, WASM compile) without doing any
+   * work. Idempotent and non-blocking: the engine boots on first use anyway,
+   * so this only overlaps that boot with the app's own start.
+   */
+  warmup(): void;
+  /** Runtime font registration and fallback fonts. See {@link FontService}. */
+  readonly fonts: FontService;
+}
+/** Whether `engine` is the local engine, with its fonts and `warmup()`. */
+declare function isLocalEngine(engine: Engine): engine is LocalEngine;
+//#endregion
+export { OutlineCreateOptions as $, PageHandle as A, CustomMetadataService as B, DocumentEventStream as C, DocumentEventOf as D, DocumentEventInit as E, LocalPageFormsService as F, EngineRenderPolicy as G, DocumentSearchService as H, PageFormsService as I, snapFullPageViewport as J, appearanceLatticeScale as K, LocalPageAnnotationsService as L, PageTextService as M, LocalPageRenderService as N, DocumentEventType as O, PageRenderService as P, DocumentOutlineService as Q, PageAnnotationsService as R, WorkingSetPage as S, DocumentEvent as T, CONTINUOUS_RENDER_POLICY as U, DocumentSignaturesService as V, DocumentRenderService as W, DocumentRedactionService as X, snapTileScale as Y, DocumentPagesService as Z, Engine as _, LocalPageHandle as a, CallFacts as b, PieceInfoService as c, PieceInfoPatch as d, DocumentFormsService as et, PieceInfoPatchValue as f, FontService as g, FontEmbeddingPolicy as h, isLocalDocument as i, DocumentActionsService as it, PageMeasureService as j, EventOrigin as k, PieceInfoUpdateResult as l, DocumentFontSettings as m, isLocalEngine as n, DocumentAttachmentsService as nt, isLocalPage as o, PieceInfoSnapshot as p, snapAppearanceScale as q, LocalDocumentHandle as r, DocumentAnnotationsService as rt, PieceInfoDeleteResult as s, LocalEngine as t, FormRepairOptions as tt, PieceInfoEntry as u, EngineFactory as v, subscribeToType as w, CallPriority as x, DocumentHandle as y, MetadataService as z };
+//# sourceMappingURL=LocalEngine-IA9zh3Jh.d.cts.map