@embedpdf/engine-core 3.0.0-next.0

package/dist/Engine-B7Oe7f5i.d.ts

@@ -0,0 +1,1013 @@
+import { Aa as EmbeddedFileItem, Ai as AnnotationCreateResult, Ao as PageImageHandle, Ar as FormFieldDeleteResult, Bo as PageRenderOptions, Di as FormWidgetRef, Ea as AttachmentContent, Ei as FormFieldRef, Fn as RedactionApplyScope, Fr as FormWidgetLinkResult, Gn as PageRotateResult, Gr as FormFieldPatch, Hn as PageInsertResult, Hr as FormFieldValue, Io as PageRaster, Ir as FormEffect, Jn as PageMoveResult, Jo as PageTextSnapshot, Mc as DocumentActionsSnapshot, Mi as AnnotationMoveResult, Mn as MetadataUpdateResult, Mo as PageImageOptions, Mr as FormImportResult, Ni as AnnotationUpdateResult, Nr as FormRepairResult, Or as FormDataExport, Pn as RedactionApplyResult, Pr as FormSetValueResult, So as AnnotationAppearanceRenderOptions, Tr as SearchSlice, Un as PageDeleteResult, Uo as PageRenderViewport, Vc as DocumentMetadata, Vn as PageFlattenUsage, Vr as FormDataFormat, Zr as FormFieldDraft, Zs as AnnotationRef, _o as AnnotationAppearanceImagesResult, _s as OpenOptions, do as FontSpec, ds as OpenInput, ec as PageObjectNumber, go as AnnotationAppearanceImageOptions, ii as FormSnapshot, ja as EmbeddedFileRef, ji as AnnotationDeleteResult, jr as FormFieldUpdateResult, ka as AttachmentFileSource, kc as PdfRotation, kr as FormFieldCreateResult, l as AnnotationPatch, la as AttachmentCreateResult, lo as FontHandle, n as AnnotationListSnapshotAllPages, o as AnnotationDraft, os as PageListSnapshot, pi as FormFieldDTO, po as PdfSaveMode, qo as PageGeometrySnapshot, t as AnnotationListPageSnapshot, ua as AttachmentDeleteResult, uo as FontKey, us as MetadataPatch, wo as AnnotationAppearancesResult, wr as SearchRequest, zn as PageFlattenResult, zr as FormEffectsResult } from "./AnnotationListSnapshot-W0RCsyDE.js";
+import { g as AbortablePromise, s as DocumentSecurityService } from "./DocumentSecurityService-B-tULKNY.js";
+//#region src/engine/DocumentActionsService.d.ts
+/** Lazy, catalog-owned PDF action read. This API extracts; it never executes. */
+interface DocumentActionsService {
+  read(): AbortablePromise<DocumentActionsSnapshot>;
+}
+//#endregion
+//#region src/engine/DocumentAnnotationsService.d.ts
+interface WeakAnnotationEditSession {
+  readonly id: string;
+  readonly expiresAt: number;
+  readonly heartbeatIntervalMs: number;
+  readonly pageObjectNumbers: readonly PageObjectNumber[];
+  covers(pageObjectNumber: PageObjectNumber): boolean;
+  updatePages(pageObjectNumbers: readonly PageObjectNumber[]): AbortablePromise<void>;
+  heartbeat(): AbortablePromise<void>;
+  release(): AbortablePromise<void>;
+}
+/**
+ * Document-scoped annotation service exposed via
+ * `DocumentHandle.annotations`. The two read paths matter:
+ *
+ *   `listRawAll()` - whole-doc raw read. No `pagePtr` is acquired; uses
+ *                    `EPDFPage_GetAnnotCountRaw` + `EPDFPage_GetAnnotRaw`.
+ *                    Cheapest possible path; ideal for "do anything with
+ *                    a document" UX where the caller wants to know what's
+ *                    where but does not need full per-subtype fields yet.
+ *
+ *   `listRaw(p)`   - single-page raw read. Same fast path scoped to one
+ *                    page, by PDF object number.
+ *
+ * The slow per-subtype `pagePtr`-driven read lives on
+ * `PageAnnotationsService.list()`.
+ */
+interface DocumentAnnotationsService {
+  listRawAll(): AbortablePromise<AnnotationListSnapshotAllPages>;
+  listRaw(pageObjectNumber: PageObjectNumber): AbortablePromise<AnnotationListPageSnapshot>;
+  beginWeakEdit(pageObjectNumbers: readonly PageObjectNumber[]): AbortablePromise<WeakAnnotationEditSession>;
+}
+//#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 (`EmbeddedFileRef`) — unique by
+ * construction, so there is no weak/index tier and no revision to
+ * validate (see the ref's doc comment). `list()` returns metadata only;
+ * bytes leave the engine exclusively through {@link download}. The
+ * annotation-level counterpart is
+ * `PageAnnotationsService.downloadFile(ref)`.
+ *
+ * `create`/`delete` are optional (the `downloadLayer?` pattern) while
+ * transports ship — feature-detect with `attachments.create !== undefined`.
+ */
+interface DocumentAttachmentsService {
+  /** Snapshot of the `/EmbeddedFiles` name tree, in tree (key-sorted) order. */
+  list(): AbortablePromise<EmbeddedFileItem[]>;
+  /**
+   * Decode and return one embedded file's bytes plus the metadata needed
+   * to hand it to a user (name, mime type). Throws
+   * `EngineError(NotFound)` when no entry has the ref's key and
+   * `EngineError(InvalidArg)` when the entry has no embedded file stream.
+   */
+  download(ref: EmbeddedFileRef): AbortablePromise<AttachmentContent>;
+  /**
+   * 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 `attachment.created` event is
+   * published. Note the tree is key-sorted, so other entries' indices
+   * may shift; keys never move.
+   */
+  create?(file: AttachmentFileSource): 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
+   * `attachment.deleted` event is published.
+   */
+  delete?(ref: EmbeddedFileRef): AbortablePromise<AttachmentDeleteResult>;
+}
+//#endregion
+//#region src/engine/DocumentFormsService.d.ts
+/** Options for {@link DocumentFormsService.repair}. */
+interface FormRepairOptions {
+  /**
+   * 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. Filling mutates the field plane; rendering only ever reads the
+ * widget plane (through the annotation subsystem — join widgets to
+ * annotations via `FormFieldWidget.annotObjectNumber`).
+ *
+ * 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, options, and widgets. 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. The value's `type` must match the field
+   * family (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 `form.valueChanged`.
+   */
+  setValue(ref: FormFieldRef, value: FormFieldValue): AbortablePromise<FormSetValueResult>;
+  /**
+   * Restore a field to its default value (/DV), or clear it when no
+   * default exists. Emits `form.valueChanged`.
+   */
+  reset(ref: FormFieldRef): AbortablePromise<FormSetValueResult>;
+  /**
+   * Apply one script run's ordered effects as one worker/cloud job. The batch
+   * is not rollback-atomic. All references are preflighted before writes;
+   * after a post-preflight internal failure the remaining effects are marked
+   * skipped and any landed state is finalized as one artifact/event/version.
+   */
+  applyEffects?(effects: FormEffect[]): AbortablePromise<FormEffectsResult>;
+  /**
+   * Serialize the form data for interchange. Defaults to `'xfdf'` (the
+   * XML sibling; UTF-8, friendliest to web pipelines) — pass `'fdf'` for
+   * the PDF-native container. Exports read the same reconciled view as
+   * `list()`, so recovered fields are included and, on layer documents,
+   * filled values win over the base.
+   */
+  exportData(format?: FormDataFormat): AbortablePromise<FormDataExport>;
+  /**
+   * Apply an FDF or XFDF payload. The format is sniffed from the bytes
+   * when `format` is omitted. Each entry replays through the same typed,
+   * validated write path as `setValue` — one bad entry is skipped and
+   * counted, never fatal. Emits `form.imported`.
+   */
+  importData(data: Uint8Array | ArrayBuffer, format?: FormDataFormat): AbortablePromise<FormImportResult>;
+  /**
+   * Create a logical form field, optionally with styled widgets, in one
+   * atomic job. Widgets are born through the annotation plane and adopted
+   * (see {@link attachWidget}); the inline `widget(s)` config is sugar for
+   * exactly that composition. Gated by `doc.forms.modify`. Emits
+   * `form.fieldCreated`.
+   */
+  createField(draft: FormFieldDraft): 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
+   * `form.fieldUpdated`.
+   */
+  updateField(ref: FormFieldRef, patch: FormFieldPatch): 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 `form.fieldDeleted`.
+   */
+  deleteField(ref: FormFieldRef): AbortablePromise<FormFieldDeleteResult>;
+  /**
+   * Adopt an existing, unattached widget annotation as a view of the
+   * field. `onState` names the checked appearance state and is required
+   * for radio groups (checkboxes default to "Yes"). Attaching into a
+   * legacy merged field splits it — the FIELD object number never
+   * changes; widget identity may. Emits `form.widgetAttached`.
+   */
+  attachWidget(ref: FormFieldRef, widget: FormWidgetRef, options?: {
+    onState?: string;
+  }): AbortablePromise<FormWidgetLinkResult>;
+  /**
+   * The inverse of {@link attachWidget}: the widget keeps its page
+   * placement and last appearance but becomes an ordinary, inert
+   * annotation (deletable through the annotation APIs). The field
+   * survives, "unplaced" when this was its last widget. Emits
+   * `form.widgetDetached`.
+   */
+  detachWidget(ref: FormFieldRef, widget: FormWidgetRef): AbortablePromise<FormWidgetLinkResult>;
+  /**
+   * 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 `form.repaired`.
+   */
+  repair(options?: FormRepairOptions): AbortablePromise<FormRepairResult>;
+}
+//#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 are `move`, `rotate`, and `delete`; the surface is
+ * designed for `insert` to slot in without API churn.
+ *
+ * Identity rule: pages are addressed by indirect `pageObjectNumber`
+ * everywhere except `list()`, which exposes display order through
+ * `PageState.pageIndex`. There is no "weak page ref" model — structure
+ * verbs therefore do not bump per-page revisions and do not invalidate
+ * any in-flight annotation refs on surviving pages.
+ */
+interface DocumentPagesService {
+  /**
+   * Snapshot of every page in display order. Cheap; never acquires a
+   * `pagePtr`.
+   */
+  list(): AbortablePromise<PageListSnapshot>;
+  /**
+   * Reorder pages. The supplied pages are detached and re-inserted as
+   * a contiguous block starting at `destIndex` in the post-removal
+   * index space, preserving caller order. Per-page `RevisionToken`s
+   * survive — index-based annotation refs the caller is holding remain
+   * valid across a page reorder.
+   *
+   * @param pageObjectNumbers Pages to move, in the order they should
+   *                          appear after the move.
+   * @param destIndex Insertion point in `[0, pageCount - len]`.
+   */
+  move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise<PageMoveResult>;
+  /**
+   * 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,
+   * annotation refs, and `RevisionToken`s all survive untouched. See
+   * `PageRotateInput` for why the wire is absolute, never relative.
+   */
+  rotate(pageObjectNumbers: PageObjectNumber[], rotation: PdfRotation): AbortablePromise<PageRotateResult>;
+  /**
+   * Delete pages. Deleting every page is rejected (`InvalidArg`) — a
+   * document must keep at least one. Deleted PONs are retired, never
+   * recycled; surviving pages keep their identity and revisions.
+   */
+  delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;
+  /**
+   * 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?(pageObjectNumbers: PageObjectNumber[], usage?: PageFlattenUsage): 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 draft's
+   * `source` bytes.
+   *
+   * Optional while the cloud endpoint ships (the `downloadLayer?`
+   * pattern): the local engine implements it; the cloud engine omits it
+   * until the server exposes extraction. Feature-detect with
+   * `pages.extract !== undefined`.
+   */
+  extract?(pageObjectNumbers: PageObjectNumber[]): AbortablePromise<Uint8Array>;
+  /**
+   * Insert every page of a standalone PDF (`bytes`) at `destIndex`
+   * (omitted → append). 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 will ship them as a
+   * multipart mutation.
+   *
+   * Slated REQUIRED-parity (a cloud viewer must be able to add pages);
+   * optional only until the server endpoint ships — feature-detect with
+   * `pages.insert !== undefined`.
+   */
+  insert?(bytes: Uint8Array | ArrayBuffer, destIndex?: number): 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 what leaves the system: a layer download/export, or
+ * a local document saved after apply. Surfaces that promise "permanent
+ * removal" must scope that promise to the 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): 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 {
+  policy(): Promise<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;
+/**
+ * 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`; `mode: 'full'` (snippets) also
+ * requires `doc.text.copy` — see {@link SearchMode}. 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 merged line rects from the same line-merge 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/MetadataService.d.ts
+interface MetadataService {
+  read(): AbortablePromise<DocumentMetadata>;
+  /**
+   * Rewrite the document Info dict 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): AbortablePromise<MetadataUpdateResult>;
+}
+//#endregion
+//#region src/engine/PageAnnotationsService.d.ts
+/**
+ * Per-page annotation service exposed via `PageHandle.annotations`.
+ *
+ * `list()` is the slow path: the engine acquires a `pagePtr` from the
+ * `PagePtrPool`, dispatches per-subtype readers, and returns
+ * fully-typed annotations. Mutations all funnel through this service
+ * because they need a `pagePtr` anyway.
+ *
+ * Mutation methods are typed in this slice but throw
+ * `EngineError(NotImplemented)` until the next slice. The signatures are
+ * stable so client code can be written against them today.
+ */
+interface PageAnnotationsService {
+  list(): AbortablePromise<AnnotationListPageSnapshot>;
+  /**
+   * Batch-render every annotation appearance (`/AP`) stream on the page into
+   * its own raw RGBA raster, sized to the annotation's `/Rect`. Read-only and
+   * gated by `doc.annotate.read` — reading an annotation implies you may see
+   * its rendered appearance (the Adobe boundary).
+   *
+   * Cloud engines do not expose the raw rasters (the HTTP surface ships
+   * encoded images); use {@link renderAppearanceImages} there instead.
+   */
+  renderAppearances(options?: AnnotationAppearanceRenderOptions): AbortablePromise<AnnotationAppearancesResult>;
+  /**
+   * Encoded counterpart of {@link renderAppearances}: each raster is run
+   * through the engine's image encoder (local) or fetched as a
+   * `multipart/form-data` body (cloud) and returned as a lazily-resolved
+   * `PageImageHandle`. This is the cross-engine portable surface.
+   */
+  renderAppearanceImages(options?: AnnotationAppearanceImageOptions): AbortablePromise<AnnotationAppearanceImagesResult>;
+  /**
+   * Decode and return the file embedded in a FileAttachment annotation
+   * (its `/FS` filespec). A read — listings carry the file's metadata
+   * (`FileAttachmentAnnotationDTO.file`); this is the explicit bytes-out
+   * call. Optional while the cloud endpoint ships (the `extract?`
+   * pattern); feature-detect with `annotations.downloadFile !== undefined`.
+   * Throws `EngineError(InvalidArg)` when the annotation is not a
+   * file-attachment or has no embedded file stream.
+   */
+  downloadFile?(ref: AnnotationRef): AbortablePromise<AttachmentContent>;
+  create(draft: AnnotationDraft): AbortablePromise<AnnotationCreateResult>;
+  update(ref: AnnotationRef, patch: AnnotationPatch): AbortablePromise<AnnotationUpdateResult>;
+  delete(ref: AnnotationRef): AbortablePromise<AnnotationDeleteResult>;
+  /**
+   * Batch move (contiguous-block; `refs.length === 1` is the
+   * single-annotation case). Refs may mix stable ids and weak `index`
+   * refs; weak refs are opportunistically upgraded to durable `/NM`
+   * before the move (same rule as `update()`). Atomic — one revision
+   * bump and one impact computation per batch.
+   *
+   * @param refs Annotations to move, in the order they should appear
+   *             after the move.
+   * @param toIndex Insertion point in the post-removal /Annots index
+   *                space, in `[0, count - refs.length]`.
+   */
+  move(refs: AnnotationRef[], toIndex: number): AbortablePromise<AnnotationMoveResult>;
+}
+//#endregion
+//#region src/engine/PageGeometryService.d.ts
+interface PageGeometryService {
+  read(): AbortablePromise<PageGeometrySnapshot>;
+}
+//#endregion
+//#region src/engine/PageRenderService.d.ts
+interface PageRenderService {
+  image(options?: PageImageOptions): AbortablePromise<PageImageHandle>;
+  raw(options?: PageRenderOptions): AbortablePromise<PageRaster>;
+}
+//#endregion
+//#region src/engine/PageTextService.d.ts
+/**
+ * Per-page text service exposed via `PageHandle.text`.
+ *
+ * `read()` acquires a `pagePtr` on the worker, runs PDFium's
+ * `FPDFText_LoadPage` → `FPDFText_GetText` chain, and returns the
+ * full plain-text extraction together with the current `PageState`.
+ *
+ * The single-method shape is intentional: future per-character
+ * features (bounding boxes, font runs, search) land on this service
+ * as additional methods without changing the existing URL or DTO.
+ */
+interface PageTextService {
+  read(): AbortablePromise<PageTextSnapshot>;
+}
+//#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`, as ISO 8601 (null if absent). */
+  lastModified: string | null;
+}
+//#endregion
+//#region src/engine/PieceInfoService.d.ts
+/**
+ * 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.
+   */
+  read(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): AbortablePromise<void>;
+  /** Application names present under this holder's `/PieceInfo`. */
+  applications(): AbortablePromise<string[]>;
+  /** Remove the application's entire entry (sibling applications survive). */
+  clear(application: string): AbortablePromise<void>;
+}
+//#endregion
+//#region src/engine/PageHandle.d.ts
+/**
+ * Page-scoped handle returned by `DocumentHandle.page(pageObjectNumber)`.
+ * The handle is keyed on the PDF indirect object number, never the page
+ * index, so it survives page-list mutations.
+ */
+interface PageHandle {
+  readonly pageObjectNumber: PageObjectNumber;
+  /**
+   * Display index at the time this handle was minted. The engine refreshes
+   * this on every annotation/list call against the live `PageRecord`, but
+   * callers should treat it as advisory metadata only.
+   */
+  readonly pageIndex: number;
+  readonly annotations: PageAnnotationsService;
+  readonly text: PageTextService;
+  readonly geometry: PageGeometryService;
+  readonly render: PageRenderService;
+  /**
+   * PAGE-level `/PieceInfo` private application data (ISO 32000 §14.5) —
+   * e.g. a stamp page's name/subject. Optional: local implements it; cloud
+   * omits it until a cloud consumer ships (the `downloadLayer?` pattern).
+   */
+  readonly pieceInfo?: PieceInfoService;
+}
+//#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 caused by THIS ENGINE INSTANCE — not "this user".
+ * The same user in two tabs is two sessions: tab A's mutation arrives in
+ * tab B 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' = caused by this engine instance; 'remote' = another session. */
+  kind: 'local' | 'remote';
+  /** Identifies the engine instance that caused 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;
+}
+/**
+ * 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 engine 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`).
+ *   - 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.
+ *
+ * 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: 'annotation.created';
+  pageObjectNumber: PageObjectNumber;
+  origin: EventOrigin;
+} & AnnotationCreateResult) | ({
+  type: 'annotation.updated';
+  pageObjectNumber: PageObjectNumber;
+  origin: EventOrigin;
+} & AnnotationUpdateResult) | ({
+  type: 'annotation.deleted';
+  pageObjectNumber: PageObjectNumber;
+  origin: EventOrigin;
+} & AnnotationDeleteResult) | ({
+  type: 'annotation.moved';
+  pageObjectNumber: PageObjectNumber;
+  origin: EventOrigin;
+} & AnnotationMoveResult) | ({
+  type: 'pages.moved';
+  /** Locally: the moved block. Remotely the audit row only records the
+   *  outcome, so this is the full new order — consumers should read
+   *  `layout` for positions, never reconstruct the gesture. */
+  pageObjectNumbers: PageObjectNumber[];
+  /** The originator's insertion point; absent on remote events. */
+  destIndex?: number;
+  origin: EventOrigin;
+} & PageMoveResult) | ({
+  type: 'pages.rotated';
+  pageObjectNumbers: PageObjectNumber[];
+  rotation: PdfRotation;
+  origin: EventOrigin;
+} & PageRotateResult) | ({
+  type: 'pages.deleted';
+  /** The RETIRED pons — not derivable from the surviving `layout`. */
+  pageObjectNumbers: PageObjectNumber[];
+  origin: EventOrigin;
+} & PageDeleteResult) | ({
+  type: 'pages.inserted';
+  /** The originator's insertion point; absent on remote events. */
+  destIndex?: number;
+  origin: EventOrigin;
+} & PageInsertResult) | ({
+  type: 'attachment.created';
+  origin: EventOrigin;
+} & AttachmentCreateResult) | ({
+  type: 'attachment.deleted';
+  origin: EventOrigin;
+} & AttachmentDeleteResult) | ({
+  type: 'metadata.updated';
+  origin: EventOrigin;
+} & MetadataUpdateResult) | ({
+  type: 'form.valueChanged';
+  origin: EventOrigin;
+} & FormSetValueResult) | ({
+  type: 'form.imported';
+  origin: EventOrigin;
+} & FormImportResult) | ({
+  type: 'form.repaired';
+  origin: EventOrigin;
+} & FormRepairResult) | ({
+  type: 'form.fieldCreated';
+  origin: EventOrigin;
+} & FormFieldCreateResult) | ({
+  type: 'form.fieldUpdated';
+  origin: EventOrigin;
+} & FormFieldUpdateResult) | ({
+  type: 'form.fieldDeleted';
+  origin: EventOrigin;
+} & FormFieldDeleteResult) | ({
+  type: 'form.widgetAttached';
+  origin: EventOrigin;
+} & FormWidgetLinkResult) | ({
+  type: 'form.widgetDetached';
+  origin: EventOrigin;
+} & FormWidgetLinkResult) | ({
+  type: 'form.effectsApplied';
+  origin: EventOrigin;
+} & FormEffectsResult) | ({
+  type: 'pages.flattened';
+  pageObjectNumbers: PageObjectNumber[];
+  usage: PageFlattenUsage;
+  origin: EventOrigin;
+} & PageFlattenResult) | ({
+  type: 'redaction.applied';
+  origin: EventOrigin;
+} & RedactionApplyResult);
+type DocumentEventType = DocumentEvent['type'];
+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`. */
+type DocumentEventInit = DistributiveOmit<DocumentEvent, 'origin'>;
+//#endregion
+//#region src/events/DocumentEventStream.d.ts
+/**
+ * The subscription surface on `DocumentHandle.events`. Intentionally
+ * minimal — no filtering, no replay-from-id: plugins build their own
+ * filter wrappers (per-page, per-type, …). One subscription, one stream.
+ *
+ * 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;
+  /**
+   * 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;
+}
+//#endregion
+//#region src/engine/DocumentHandle.d.ts
+interface DocumentCapabilities {
+  readonly weakAnnotationEditSessions: 'not-needed' | 'required';
+  readonly pageEditSessions: 'unsupported' | 'supported';
+}
+interface DocumentHandle {
+  readonly id: string;
+  readonly capabilities: DocumentCapabilities;
+  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).
+   * Optional while transports ship (the `downloadLayer?` pattern) —
+   * feature-detect with `doc.attachments !== undefined`. Files attached to
+   * annotations are downloaded via `page(pon).annotations.downloadFile`.
+   */
+  readonly attachments?: DocumentAttachmentsService;
+  /** The document's interactive form (AcroForm): fields, values, interchange. */
+  readonly forms: DocumentFormsService;
+  /**
+   * CATALOG-level `/PieceInfo` private application data (ISO 32000 §14.5)
+   * — e.g. a stamp library's display name. Optional: the local engine
+   * implements it; the cloud engine omits it until a cloud consumer ships
+   * (the `downloadLayer?` pattern). Per-page piece data lives on
+   * `page(pon).pieceInfo`.
+   */
+  readonly pieceInfo?: PieceInfoService;
+  /** Document text search: budgeted, cursor-resumable slices. */
+  readonly search: DocumentSearchService;
+  /**
+   * Render POLICY surface (`doc.render.policy()`): the engine's render
+   * lattice, or `continuous` on engines that render any viewport exactly
+   * (the local engine). Pixels stay on `page(pon).render` — this carries
+   * policy only. Conformance is explicit via `snapFullPageViewport`; no
+   * engine ever snaps a render call implicitly. Optional while engines
+   * ship it — feature-detect with `doc.render !== undefined`.
+   */
+  readonly render?: DocumentRenderService;
+  /**
+   * Document-scoped page service. Use for cross-page operations:
+   *   - `pages.list()` for the current display order.
+   *   - `pages.move(pons, destIndex)` for reorder.
+   *
+   * Per-page reads/writes still live on `page(pon).annotations`.
+   */
+  readonly pages: DocumentPagesService;
+  /**
+   * Destructive redaction apply (the second stage of the two-stage model;
+   * marking rides the normal annotation verbs). Optional while engines
+   * ship it — feature-detect with `doc.redaction !== undefined`.
+   */
+  readonly redaction?: DocumentRedactionService;
+  /**
+   * The document's event stream — every confirmed mutation, exactly once,
+   * identical shape on local and cloud engines (see `DocumentEvent`). The
+   * engine-instance identity lives on each event's `origin.sessionId`.
+   */
+  readonly events: DocumentEventStream;
+  /**
+   * Returns a handle scoped to a page by PDF indirect object number.
+   * Throws `EngineError(NotFound)` if the document has no such page.
+   * Synchronous because page records are cached on `DocumentSession`.
+   */
+  page(pageObjectNumber: PageObjectNumber): PageHandle;
+  download(opts?: {
+    mode?: PdfSaveMode;
+  }): AbortablePromise<Uint8Array>;
+  /**
+   * Export JUST this document's LAYER as a self-contained artifact (the small
+   * overlay diff over the immutable base) — re-openable later via
+   * `OpenInputLayerBytes` with `{ kind: 'artifact', bytes }`. Optional: only the
+   * local engine, opened WITH a layer (`layerBytes`), supports it; the cloud
+   * engine manages layers server-side and omits it. Rejects if the document was
+   * opened without a layer.
+   */
+  downloadLayer?(): AbortablePromise<Uint8Array>;
+  close(): AbortablePromise<void>;
+}
+//#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
+ * (`FreeTextDraft.registeredFontKey`); 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. Idempotent: registering a font whose `key` (or, if
+   * `key` is omitted, whose content hash) is 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).
+   */
+  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>;
+  /** Currently registered fonts, in registration order. */
+  list(): readonly FontHandle[];
+}
+//#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.
+ *
+ * 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 {
+  open(input: OpenInput, options?: OpenOptions): AbortablePromise<DocumentHandle>;
+  destroy(): AbortablePromise<void>;
+  /**
+   * Start booting the engine's backing resources (Worker spawn, WASM compile,
+   * transport connect) without performing any work. Optional because some
+   * engines have nothing to warm (cloud). Idempotent and non-blocking:
+   * engines that boot lazily do so on first use anyway — calling `warmup()`
+   * just overlaps that boot with app/plugin initialization instead of paying
+   * for it on the first `open()`.
+   */
+  warmup?(): void;
+  /**
+   * Runtime font registration + fallback configuration. Present on the local
+   * (WASM) engine only; `undefined` on the cloud engine, where fallback fonts
+   * are a server-side policy decision and cannot be configured from the
+   * client. See {@link FontService}.
+   */
+  readonly fonts?: FontService;
+}
+/**
+ * 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
+export { DocumentPagesService as A, CONTINUOUS_RENDER_POLICY as C, snapFullPageViewport as D, snapAppearanceScale as E, WeakAnnotationEditSession as F, DocumentActionsService as I, FormRepairOptions as M, DocumentAttachmentsService as N, snapTileScale as O, DocumentAnnotationsService as P, DocumentSearchService as S, EngineRenderPolicy as T, PageTextService as _, DocumentHandle as a, PageAnnotationsService as b, DocumentEventInit as c, PageHandle as d, PieceInfoService as f, PieceInfoSnapshot as g, PieceInfoPatchValue as h, DocumentCapabilities as i, DocumentFormsService as j, DocumentRedactionService as k, DocumentEventType as l, PieceInfoPatch as m, EngineFactory as n, DocumentEventStream as o, PieceInfoEntry as p, FontService as r, DocumentEvent as s, Engine as t, EventOrigin as u, PageRenderService as v, DocumentRenderService as w, MetadataService as x, PageGeometryService as y };
+//# sourceMappingURL=Engine-B7Oe7f5i.d.ts.map