@embedpdf/engine-services 3.0.0-next.0

package/dist/index.d.ts

@@ -0,0 +1,1481 @@
+import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometrySnapshot, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
+import { PdfFunctions, PdfRuntimeMemory, PdfRuntimeModule, Ptr } from "@embedpdf/engine-runtime";
+//#region src/runtime/lifecycle/bootstrap.d.ts
+/**
+ * Initialize the thread-confined PDFium runtime for the calling thread. Each
+ * worker thread owns its own PDFium state, so this must run on every thread
+ * that uses the runtime. Safe to call multiple times.
+ */
+declare function ensureInitialized(runtime: PdfRuntimeModule): void;
+/**
+ * Tear down PDFium for the calling thread. Lifecycle-strict: every PDFium
+ * handle created on this thread must already be closed.
+ */
+declare function destroyLibrary(runtime: PdfRuntimeModule): void;
+//#endregion
+//#region src/shared/abort.d.ts
+/**
+ * Throw if the AbortSignal has been aborted. Service code peppers calls to
+ * this between PDFium calls so cooperative cancellation works without
+ * needing async/await.
+ */
+declare function throwIfAborted(signal: AbortSignal): void;
+//#endregion
+//#region src/shared/uuid.d.ts
+/**
+ * Generate an RFC 4122 v4 UUID using the Web Crypto API surface that's
+ * available in every realm we ship to: Node 19+ (global), Web Workers,
+ * browsers (https), browsers (http/intranet/file:), and Edge runtimes.
+ *
+ * Why this implementation, exactly:
+ *   - `crypto.randomUUID()` was historically gated to *secure contexts*
+ *     in older browsers and we shipped that bug to production once.
+ *     `getRandomValues()` has no such restriction.
+ *   - `import { randomUUID } from 'crypto'` makes Vite externalize the
+ *     `crypto` module for browser builds and emit a build-time warning;
+ *     we then crash at runtime in the rare path that hits it.
+ *   - 16 bytes + RFC 4122 bit-twiddling is six lines and correct.
+ *
+ * Output is the canonical hex form: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`,
+ * where `y` is one of `8/9/a/b` (variant nibble = 10xx).
+ */
+declare function generateUuid(): string;
+//#endregion
+//#region src/shared/pdf-date.d.ts
+/**
+ * PDF date string format conversion utilities.
+ *
+ * PDF stores timestamps as ASCII strings shaped like
+ * `D:YYYYMMDDHHmmSSOHH'mm'`, where `O` is `+` / `-` / `Z` (Z means
+ * UTC and omits the offset). See ISO 32000 §7.9.4.
+ *
+ * The wire format used by the engine DTOs is always ISO 8601;
+ * readers convert PDF → ISO via {@link pdfDateToIso}, writers convert
+ * the other way via {@link formatPdfDate}.
+ */
+/**
+ * Parse a PDF date string `D:YYYYMMDDHHmmSSOHH'mm'` to an ISO 8601
+ * string. Returns null if the input is malformed.
+ *
+ * When the timezone is omitted, PDF defines the relationship to UTC as
+ * unknown. Since the engine DTO wire format requires an absolute ISO 8601
+ * timestamp, this converter retains the pre-existing fallback of treating
+ * an omitted timezone as UTC.
+ */
+declare function pdfDateToIso(pdf: string): string | null;
+/**
+ * Format a JS Date as a PDF date string `D:YYYYMMDDHHmmSSOHH'mm'`.
+ *
+ * Emits the offset in PDF's funny `OHH'mm'` form, where the apostrophe
+ * after the hour is literal and the offset always carries a sign. UTC
+ * is emitted as `+00'00'` (not `Z`) for maximum reader compatibility —
+ * the `Z` shorthand is allowed by the spec but not universally
+ * supported.
+ *
+ * Always uses the supplied Date's local fields and offset. For
+ * server-side stamps callers typically pass `new Date()` (default).
+ */
+declare function formatPdfDate(d?: Date): string;
+//#endregion
+//#region src/runtime/memory/bits.d.ts
+/**
+ * Coerce a value to an unsigned 32-bit integer. PDFium permission words
+ * arrive as signed JS numbers (the high bit makes them negative); reading
+ * them as `u32` restores the bit pattern the PDF spec describes.
+ */
+declare function u32(value: number): number;
+//#endregion
+//#region src/shared/securityPermissions.d.ts
+/**
+ * PDF Standard security handlers reserve bits 1-2 as 0, and PDFium masks
+ * even owner permissions through that convention — so "all permissions"
+ * for an encrypted document is `0xFFFFFFFC`, not `0xFFFFFFFF`.
+ */
+declare const ALL_STANDARD_SECURITY_PERMISSIONS = 4294967292;
+/** Coerce PDFium's signed permission word to its unsigned 32-bit value. */
+declare const normalizeU32: typeof u32;
+/** True when `bits` grants every standard security permission. */
+declare function hasAllStandardSecurityPermissions(bits: number): boolean;
+//#endregion
+//#region src/events/EventHub.d.ts
+/**
+ * The in-process implementation of `DocumentEventStream`, shared by both
+ * engine shells (one hub per open `DocumentHandle`). The engine that
+ * performs a mutation publishes here at confirmation time; the cloud
+ * engine's remote channel will also publish here for OTHER sessions'
+ * mutations — listeners never learn which transport delivered an event.
+ *
+ * Delivery contract:
+ *   - synchronous fan-out in subscription order;
+ *   - error isolation: a throwing listener is re-thrown on a microtask
+ *     (so it surfaces to the host's unhandled-error reporting) without
+ *     blocking other listeners or failing the mutation path;
+ *   - `lastServerId` tracks the highest remote cursor seen, for the
+ *     remote channel's reconnect/backfill.
+ */
+declare class EventHub implements DocumentEventStream {
+  /** Where a throwing listener's error goes. Defaults to an async
+   *  rethrow so it reaches the host's unhandled-error reporting. */
+  private readonly onListenerError;
+  private readonly listeners;
+  private serverId;
+  constructor(
+  /** Where a throwing listener's error goes. Defaults to an async
+   *  rethrow so it reaches the host's unhandled-error reporting. */
+  onListenerError?: (err: unknown) => void);
+  subscribe(listener: (event: DocumentEvent) => void): () => void;
+  publish(event: DocumentEvent): void;
+  lastServerId(): number | null;
+  /** Drop every listener (handle close). Idempotent. */
+  clear(): void;
+}
+/**
+ * Stamps provenance onto events a mutation path produces. One per open
+ * handle: the engine shell constructs it with the instance's `sessionId`
+ * (and, on cloud, the authenticated `sub` when known) and hands it to the
+ * mutation services — they publish results, never build origins.
+ */
+declare class SessionEventPublisher {
+  private readonly hub;
+  private readonly sessionId;
+  private readonly sub;
+  constructor(hub: EventHub, sessionId: string, sub?: string | null);
+  /** Publish a mutation THIS engine instance just confirmed. */
+  publishLocal(event: DocumentEventInit): void;
+}
+//#endregion
+//#region src/document-session/lifecycle/PdfDocumentOpener.d.ts
+type OpenedPdfDocumentKind = 'fat-memory' | 'layer';
+interface OpenedPdfDocument {
+  readonly kind: OpenedPdfDocumentKind;
+  readonly docPtr: Ptr;
+  close(): void;
+}
+interface AcquiredBaseDocument {
+  readonly key: string;
+  readonly basePtr: Ptr;
+  release(): void;
+}
+type LayerSource = {
+  readonly kind: 'fresh';
+} | {
+  readonly kind: 'raw-delta';
+  readonly bytes: Uint8Array | ArrayBuffer;
+} | {
+  readonly kind: 'artifact';
+  readonly bytes: Uint8Array | ArrayBuffer;
+} | {
+  readonly kind: 'artifact-file';
+  readonly path: string;
+};
+declare class CloseStack {
+  private readonly actions;
+  private closed;
+  push(action: () => void): void;
+  close(): void;
+}
+declare function openFatMemoryDocument(runtime: PdfRuntimeModule, bytes: Uint8Array, password?: string | null): OpenedPdfDocument;
+declare function openLayerDocument(runtime: PdfRuntimeModule, base: AcquiredBaseDocument, layer?: LayerSource, password?: string | null): OpenedPdfDocument;
+//#endregion
+//#region src/document-session/pages/PagePtrPool.d.ts
+/**
+ * Manages pagePtr lifetime for a single open `DocumentSession`.
+ *
+ * `acquire(pon)` returns a loaded pagePtr for the given PDF object number,
+ * loading it via `EPDFDoc_LoadPageByObjectNumberNormalized` (rotation forced
+ * to 0deg so render/text/geometry/annotation coordinates all share one
+ * normalized space) if not already in the pool. `release(pon)` decrements the
+ * refcount and closes when it reaches
+ * zero; `closeAll()` is called by `DocumentSession.close()`.
+ *
+ * While at least one holder is active the pagePtr is shared (refcounted),
+ * so overlapping `acquire(pon)` calls for the same page reuse a single
+ * load. Once the refcount reaches zero the page is closed; a later
+ * `acquire` reloads it — there is no LRU retention across the zero-ref
+ * boundary. A future slice could add that without changing callers.
+ */
+declare class PagePtrPool {
+  private readonly runtime;
+  private readonly docPtr;
+  private readonly counts;
+  constructor(runtime: PdfRuntimeModule, docPtr: Ptr);
+  acquire(pageObjectNumber: PageObjectNumber): Ptr;
+  /**
+   * True while at least one holder has the page open. Page-STRUCTURE
+   * mutations (delete) assert on this: thread confinement means no other
+   * job can be mid-flight, so a held pagePtr during a structural mutation
+   * is a leaked `acquire` (an internal bug) — the mutator fails loudly
+   * instead of mutating under a live handle.
+   */
+  isHeld(pageObjectNumber: PageObjectNumber): boolean;
+  release(pageObjectNumber: PageObjectNumber): void;
+  closeAll(): void;
+}
+//#endregion
+//#region src/document-session/pages/PageRecord.d.ts
+/**
+ * Record of one page within a `DocumentSession`. Built lazily by
+ * `DocumentSession.ensurePageRegistry()`; the registry is only forced
+ * to populate fully when a path that needs `pageIndex -> pageObjectNumber`
+ * for the whole document is invoked (most notably `listRawAll()`).
+ *
+ * Carries no `pagePtr`. Lifetime of the actual PDFium page handle is owned
+ * by the `PagePtrPool`; the page record is metadata only.
+ */
+interface PageRecord {
+  pageObjectNumber: PageObjectNumber;
+  pageIndex: number;
+}
+//#endregion
+//#region src/document-session/DocumentSession.d.ts
+/**
+ * Owns the lifecycle of a single open PDFium document and the v3
+ * identity machinery: page registry (pageObjectNumber <-> pageIndex),
+ * `RevisionAuthority` (per-page generation counters), and `PagePtrPool`
+ * (refcounted pagePtr access).
+ *
+ * Both the local browser Worker and the server worker_thread instantiate
+ * this exactly the same way; the only thing that differs is the
+ * underlying PdfRuntimeModule (WASM vs native).
+ */
+declare class DocumentSession {
+  private readonly runtime;
+  private docPtr;
+  private closeDocument;
+  private _kind;
+  private readonly _sessionId;
+  /** pon -> record */
+  private readonly recordsByObjectNumber;
+  /** pageIndex -> record */
+  private readonly recordsByIndex;
+  private fullyEnumerated;
+  private revisions;
+  private mutationSeqCounter;
+  private pages;
+  constructor(runtime: PdfRuntimeModule, sessionId?: string);
+  get sessionId(): string;
+  get kind(): OpenedPdfDocumentKind | null;
+  isOpen(): boolean;
+  open(bytes: Uint8Array, password?: string | null): void;
+  openFromHandle(handle: OpenedPdfDocument): void;
+  /**
+   * Park this session in the password-locked state: the document could not
+   * be loaded because a (correct) password is missing, so the session keeps
+   * the already-transferred bytes and waits for an unlock attempt to load
+   * them. A locked session occupies its docId key like an open one — every
+   * operation except the password check rejects with DocPasswordRequired.
+   */
+  parkLocked(bytes: Uint8Array): void;
+  isLocked(): boolean;
+  /** The bytes retained for a later unlock attempt. Locked sessions only. */
+  lockedBytes(): Uint8Array;
+  private parkedBytes;
+  /** Number of pages in the document. */
+  pageCount(): number;
+  /**
+   * Lazily enumerate every page and cache (pageObjectNumber, pageIndex).
+   * Necessary before `listRawAll()` and any pon -> pageIndex resolution.
+   */
+  ensureFullPageRegistry(): void;
+  /** Lookup; populates the cache for one page only on cache miss. */
+  recordByObjectNumber(pageObjectNumber: PageObjectNumber): PageRecord;
+  /** All page records, in display order. Forces full enumeration. */
+  allRecords(): PageRecord[];
+  /**
+   * Drop the cached `pageIndex <-> pageObjectNumber` mapping and force a
+   * fresh enumeration on next access. Called by `PagesMutator`
+   * after `FPDF_MovePages` shuffles page positions; we keep
+   * weak-annotation knowledge and per-page revision counters intact, both of
+   * which are keyed by durable `pageObjectNumber` and survive a page reorder.
+   */
+  refreshPageRegistry(): void;
+  /** Per-page liveness envelope used by annotation read/mutation results. */
+  pageState(pageObjectNumber: PageObjectNumber): PageState;
+  /** Set by readers as they discover whether a page has weak annotations. */
+  recordWeakFlag(pageObjectNumber: PageObjectNumber, hasWeak: boolean): void;
+  recordWeakAnnotationState(pageObjectNumber: PageObjectNumber, state: WeakAnnotationState): void;
+  weakAnnotationState(pageObjectNumber: PageObjectNumber): WeakAnnotationState;
+  /** Bump and return the new revision token; called by mutation paths. */
+  bumpRevision(pageObjectNumber: PageObjectNumber): RevisionToken;
+  /**
+   * Monotonic count of successful document mutations in this session.
+   * Version key for detached-snapshot caches (e.g. the forms model):
+   * a cache entry built at sequence N is exactly valid while the
+   * sequence is still N. Coarse on purpose — widgets are annotations
+   * and page ops move widgets, so ANY mutation may affect derived
+   * form state; per-domain counters are a later optimization.
+   */
+  mutationSeq(): number;
+  /** Record one successful mutation; called by mutation paths. */
+  noteMutation(): void;
+  /**
+   * Forget a page's per-session state (revision generation + weak-annotation
+   * flag). Called by `pages.delete` after the page object is retired; the
+   * PON is never recycled, so this is hygiene, not correctness.
+   */
+  dropPageState(pageObjectNumber: PageObjectNumber): void;
+  validateRevision(token: RevisionToken): void;
+  pagePool(): PagePtrPool;
+  requireDocPtr(): Ptr;
+  /**
+   * Park a disposer to run when THIS session closes. Used by operations
+   * whose native side leaves the session document referencing another
+   * resource — e.g. `pages.insert`: `FPDF_ImportPagesByIndex` does not
+   * fully detach imported objects from their source document, so the
+   * source doc + its byte buffer must stay alive until the destination
+   * can no longer be saved (i.e. until this session closes).
+   */
+  retainUntilClose(dispose: () => void): void;
+  private readonly retained;
+  close(): void;
+  private requireRevisions;
+}
+//#endregion
+//#region src/document-session/lifecycle/BaseDocumentRegistry.d.ts
+declare class BaseDocumentRegistry {
+  private readonly runtime;
+  private readonly entries;
+  constructor(runtime: PdfRuntimeModule);
+  acquireMemoryBase(opts: {
+    key: string;
+    bytes: Uint8Array;
+    password?: string | null;
+  }): AcquiredBaseDocument;
+  acquireFileBase(opts: {
+    key: string;
+    path: string;
+    password?: string | null;
+  }): AcquiredBaseDocument;
+  releaseAll(): void;
+  /** @internal Test-only probe of the per-key share refcount. */
+  getRefCountForTesting(key: string): number;
+  private retain;
+  private insert;
+  private handleFor;
+}
+//#endregion
+//#region src/document-session/revisions/RevisionAuthority.d.ts
+interface RevisionAuthority {
+  readonly docSessionId: string;
+  token(pageObjectNumber: PageObjectNumber): RevisionToken;
+  bump(pageObjectNumber: PageObjectNumber): RevisionToken;
+  validate(token: RevisionToken): void;
+  weakAnnotationState(pageObjectNumber: PageObjectNumber): WeakAnnotationState;
+  recordWeakAnnotationState(pageObjectNumber: PageObjectNumber, state: WeakAnnotationState): void;
+  /** Forget a page entirely (generation + weak state). Called when the page
+   *  is DELETED — its object number is retired, never recycled, so dropping
+   *  is hygiene, not correctness. */
+  drop(pageObjectNumber: PageObjectNumber): void;
+  clear(): void;
+}
+/**
+ * Per-page generation counter. Backs `RevisionToken` so weak
+ * `AnnotationRef.kind === 'index'` references can be validated against the
+ * exact page state they were minted from.
+ *
+ * `bump()` is the only mutator; mutation services call it after a
+ * structural change to the page (annotation create/delete/reorder).
+ * Read paths never mutate the store.
+ */
+declare class LocalRevisionAuthority implements RevisionAuthority {
+  readonly docSessionId: string;
+  private readonly generations;
+  private readonly weakAnnotationStates;
+  constructor(docSessionId: string);
+  /** Returns the current generation, defaulting to 0 for first read. */
+  current(pageObjectNumber: PageObjectNumber): number;
+  /** Mints a fresh `RevisionToken` for the page's current generation. */
+  token(pageObjectNumber: PageObjectNumber): RevisionToken;
+  /**
+   * Increments the generation counter for a page. Returns the new token.
+   * Called by mutation services after every structural change.
+   */
+  bump(pageObjectNumber: PageObjectNumber): RevisionToken;
+  /**
+   * Strict equality check. Throws `EngineError(InvalidReference)` when the
+   * caller's token does not match what the store currently holds.
+   */
+  validate(token: RevisionToken): void;
+  weakAnnotationState(pageObjectNumber: PageObjectNumber): WeakAnnotationState;
+  recordWeakAnnotationState(pageObjectNumber: PageObjectNumber, state: WeakAnnotationState): void;
+  drop(pageObjectNumber: PageObjectNumber): void;
+  clear(): void;
+}
+//#endregion
+//#region src/features/metadata/MetadataReader.d.ts
+/**
+ * Synchronous, runtime-agnostic implementation of the metadata read.
+ *
+ * Lives in @embedpdf/engine-services so it can be reused unchanged by:
+ *   - @embedpdf/engine (inside a browser Worker, WASM runtime)
+ *   - @cloudpdf/server       (inside a Node worker_thread, native runtime)
+ *
+ * Async-ness lives at the worker boundary, not here.
+ */
+declare class MetadataReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  read(signal: AbortSignal): DocumentMetadata;
+}
+//#endregion
+//#region src/features/metadata/MetadataMutator.d.ts
+/**
+ * Synchronous orchestrator for document metadata writes. Lives next to
+ * `MetadataReader` (one orchestrator per feature) so both worker hosts
+ * (browser Web Worker and Node `worker_thread`) share the same code path.
+ *
+ * A metadata write rewrites the document Info dictionary in place. Like
+ * `PagesMutator.move`, it is a structural layer edit: it returns the
+ * re-read metadata and a `null` cache (the worker never fills cloud
+ * coherence pins — the server does, after persisting the artifact and
+ * bumping `metadataVersion`).
+ */
+declare class MetadataMutator {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  update(patch: MetadataPatch, signal: AbortSignal): MetadataUpdateResult;
+}
+//#endregion
+//#region src/features/pages/PagesReader.d.ts
+/**
+ * Runtime-agnostic page geometry reader. Produces the `pages.list()`
+ * snapshot from the lightweight `...ByIndex` PDFium bindings, none of which
+ * load or parse a page (no `pagePtr`), so listing stays cheap. Shared
+ * verbatim by the local WASM worker and the server native worker, so a
+ * given PDF yields an identical `PageListSnapshot` on both engines.
+ */
+declare class PagesReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  read(signal: AbortSignal): PageListSnapshot;
+}
+//#endregion
+//#region src/features/pages/PagesMutator.d.ts
+/**
+ * Synchronous orchestrator for page-level reads and reorder mutations.
+ * Lives next to `AnnotationMutator` (one orchestrator per
+ * mutation domain) so both worker hosts (browser Web Worker and Node
+ * `worker_thread`) share the same code path.
+ *
+ * Architectural anchor — locked with the user, do not loosen without
+ * re-reading the doc comments on `PageMoveResult` and `RevisionAuthority`:
+ *
+ *   - Pages are addressed by their durable `pageObjectNumber`. There is
+ *     no "weak page ref" model in the engine; therefore there is no
+ *     document-level revision token, no `DocumentRevisionStore`, and no
+ *     "doc-level shouldRefetch" semantic. Anything that *is* listed
+ *     here must remain stable across every reorder permutation.
+ *
+ *   - Per-page `RevisionToken`s do NOT bump on `move()`. The /Annots
+ *     array of each affected page is untouched (PDFium just rewrites
+ *     pointer entries in the doc-level pages tree), so weak
+ *     `AnnotationRef.kind === 'index'` references the caller is
+ *     holding remain valid across a page reorder. This is the right
+ *     semantic for an editing UI: shuffling pages must NOT silently
+ *     break a pending highlight edit.
+ *
+ *   - Identity strengthening (the opportunistic `/NM` stamping that
+ *     applies to weak annotations on `update()` / `move()`) is also
+ *     intentionally absent here. Pages are durable by construction;
+ *     there is nothing to upgrade.
+ */
+declare class PagesMutator {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /**
+   * Reorder pages. Mirrors `FPDF_MovePages`: detach the supplied pages,
+   * then re-insert them as a contiguous block at `destIndex` in the
+   * post-removal index space, preserving caller order.
+   *
+   * Atomicity:
+   *   - `FPDF_MovePages` rejects atomically: if it returns false, no
+   *     change has happened. We surface that as `InvalidArg`.
+   *   - On success we refresh the per-session page registry and read the
+   *     new layout back, which is what the result returns.
+   *
+   * Validation done up front (the helper repeats these checks; we do
+   * them here for clean error messages):
+   *   - non-empty inputs;
+   *   - duplicate `pageObjectNumber`s rejected;
+   *   - every `pon` resolvable via the session's page registry;
+   *   - `destIndex` in `[0, pageCount - len]`.
+   */
+  move(pageObjectNumbers: PageObjectNumber[], destIndex: number, signal: AbortSignal): PageMoveResult;
+  /**
+   * Set the ABSOLUTE display rotation of the supplied pages. Rotation is
+   * presentation metadata over normalized content (pages always load with
+   * rotation forced to 0 — see `PagePtrPool`), so:
+   *   - no cached render, text run, or geometry coordinate changes;
+   *   - per-page `RevisionToken`s do NOT bump;
+   *   - page identity and order are untouched — no registry refresh.
+   *
+   * Atomicity: every PON is resolved up front (`NotFound` on caller error),
+   * so the apply loop below operates on validated pages only and each write
+   * is absolute + idempotent — a retry after an unexpected mid-loop engine
+   * fault converges to the requested state. Abort is honored BEFORE the
+   * loop, never inside it.
+   */
+  rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation, signal: AbortSignal): PageRotateResult;
+  /**
+   * Delete pages. Deleted object numbers are RETIRED — the engine nulls the
+   * page object rather than freeing the number — so per-page state keyed by
+   * PON can never silently attach to an unrelated future page; we still drop
+   * the session's revision/weak entries as hygiene. Surviving pages keep
+   * their identity and `RevisionToken`s.
+   *
+   * Guards:
+   *   - a document must keep at least one page (`InvalidArg`);
+   *   - every PON must resolve (`NotFound`);
+   *   - no target page may have a live pooled `pagePtr`. Thread confinement
+   *     means no other job can be mid-flight, so a held ptr here is a leaked
+   *     `acquire` — an internal bug we surface loudly instead of deleting
+   *     under a live handle.
+   *
+   * Abort is honored BEFORE the apply loop, never inside it.
+   */
+  delete(pageObjectNumbers: PageObjectNumber[], signal: AbortSignal): PageDeleteResult;
+  /** Shared input check: non-empty, no duplicate PONs. */
+  private requireUniquePons;
+}
+//#endregion
+//#region src/features/pages/PagesExtractor.d.ts
+/**
+ * Export a subset of pages as a standalone PDF. A READ over the session:
+ * `FPDF_ImportPagesByIndex` copies pages into a scratch document, so the
+ * source is untouched — no revision bumps, no registry refresh, no layer
+ * artifact. Lives next to `PagesReader`/`PagesMutator` (one file per page
+ * verb family) so both worker hosts share the code path.
+ */
+declare class PagesExtractor {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /**
+   * Copy the given pages, in the supplied caller order, into a new
+   * document and serialize it. Validation up front: non-empty, no
+   * duplicates, every PON resolvable (`NotFound` from the session on a
+   * bad one). The scratch document is always closed, success or throw.
+   */
+  extract(pageObjectNumbers: PageObjectNumber[], signal: AbortSignal): {
+    bytes: ArrayBuffer;
+    size: number;
+  };
+}
+//#endregion
+//#region src/features/pages/PagesInserter.d.ts
+/**
+ * Insert every page of a standalone PDF into the session document. A
+ * structural MUTATION (like move/delete): the source bytes are loaded as a
+ * throwaway PDFium document, `FPDF_ImportPagesByIndex` deep-copies its
+ * pages in at `destIndex`, and the page registry is rebuilt. Pre-existing
+ * pages keep their identity and `RevisionToken`s; the inserted copies get
+ * fresh object numbers, resolved from the post-insert registry.
+ */
+declare class PagesInserter {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  insert(bytes: ArrayBuffer, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
+}
+//#endregion
+//#region src/features/pages/PagesFlattener.d.ts
+/** Layer-safe page flattening. Content and annotation liveness change together. */
+declare class PagesFlattener {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  flatten(pageObjectNumbers: PageObjectNumber[], usage: PageFlattenUsage, signal: AbortSignal): PageFlattenResult;
+}
+//#endregion
+//#region src/features/redaction/RedactionApplier.d.ts
+/**
+ * The destructive half of redaction (see `DocumentRedactionService` for the
+ * model and the layer trust boundary). Content and annotation liveness
+ * change together, exactly like {@link PagesFlattener} — this class mirrors
+ * its validate-then-apply boundary and ordered-batch semantics.
+ *
+ * Scope semantics:
+ *   - `pages`: every REDACT annotation on each listed page is applied; a
+ *     page with none is `unchanged`.
+ *   - `annotations`: exactly the referenced REDACT annotations are applied.
+ *     Every ref is resolved and subtype-checked BEFORE the first native
+ *     write; a non-REDACT ref rejects the whole call with `InvalidArg`.
+ *
+ * The per-page `removedAnnotationCount` is the native collateral count:
+ * annotations other than REDACT ones removed alongside the apply (popup
+ * cascades and detached widgets included).
+ */
+declare class RedactionApplier {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  apply(scope: RedactionApplyScope, signal: AbortSignal): RedactionApplyResult;
+  /**
+   * Normalize the scope into an ordered per-page plan. `null` refs means
+   * "every REDACT annotation on the page" (the `pages` scope).
+   */
+  private buildPlan;
+  /**
+   * Validate every ref BEFORE the first native write: it must resolve and
+   * it must be a REDACT annotation. After this returns, the apply loop's
+   * writes begin and per-page failures are recorded, not thrown.
+   */
+  private preflight;
+  private applyAllOnPage;
+  private applyRefsOnPage;
+}
+//#endregion
+//#region src/features/text/PageTextReader.d.ts
+/**
+ * Per-page slow-path text reader. Acquires a `pagePtr` from the
+ * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
+ * extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
+ * and releases everything in reverse order.
+ *
+ * Memory model:
+ *   - `count` is in UTF-16 code units (FPDFText's "char").
+ *   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
+ *     trailing NUL terminator).
+ *   - `mem.readU16String` walks the buffer up to the NUL and decodes
+ *     to a JS string, faithfully preserving surrogate pairs.
+ *
+ * Errors:
+ *   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
+ *     (raised by `PagePtrPool.acquire`).
+ *   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
+ *     not happen on a healthy page; treat it as a runtime bug rather
+ *     than user error.
+ */
+declare class PageTextReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageTextSnapshot;
+}
+//#endregion
+//#region src/features/geometry/PageGeometryReader.d.ts
+/**
+ * Geometry-only text layout reader.
+ *
+ * Emits geometry in PDF user space (y-up edges) — the canonical engine
+ * geometry. The viewer converts to content/view space via the page geometry
+ * matrix; this reader applies NO Y-flip or device transform.
+ */
+declare class PageGeometryReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageGeometrySnapshot;
+  private buildRunsFromGlyphs;
+  private readGlyphInfo;
+}
+//#endregion
+//#region src/features/render/PageRenderReader.d.ts
+declare class PageRenderReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  render(pageObjectNumber: PageObjectNumber, options: PageRenderOptions, signal: AbortSignal): import("@embedpdf/engine-core/runtime").PageRaster;
+}
+//#endregion
+//#region src/features/annotations/AnnotationReader.d.ts
+/**
+ * Per-page slow-path reader. Acquires a `pagePtr` from the
+ * `PagePtrPool`, dispatches the same per-subtype catalog as the raw
+ * reader (via `collectPageAnnotations`), and releases the page on exit.
+ *
+ * Currently the dispatched readers do not use the `pagePtr` parameter
+ * (text-markup is fully readable from the dict). Subtype readers that
+ * need form/widget access (e.g. widget) will plug into this code path
+ * as they land - the public DTO surface stays the same.
+ */
+declare class AnnotationReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  list(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+}
+//#endregion
+//#region src/features/annotations/AnnotationAppearanceReader.d.ts
+/**
+ * Batch-renders the appearance streams (`/AP`) of every annotation on a page,
+ * one bitmap per requested mode. Ported from the v2 PDFium engine's
+ * `renderPageAnnotationsRaw` / `renderSingleAnnotAppearance`, but expressed in
+ * PDF user space and against the `PdfRuntimeModule` (`fn` + `mem`).
+ *
+ * Each appearance bitmap is sized to its annotation's `/Rect` scaled by
+ * `options.scale`. The shared raster helper handles PDFium's display matrix
+ * convention, so this reader stays in normalized PDF page coordinates.
+ */
+declare class AnnotationAppearanceReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  render(pageObjectNumber: PageObjectNumber, options: AnnotationAppearanceRenderOptions, signal: AbortSignal): AnnotationAppearancesResult;
+  /**
+   * Render a single annotation appearance into its own raster. Returns `null`
+   * when the mode has no appearance stream (after an optional form-field AP
+   * generation fallback) or the render fails.
+   */
+  private renderOne;
+}
+//#endregion
+//#region src/features/annotations/RawAnnotationReader.d.ts
+/**
+ * Whole-document and per-page raw read paths. Never acquires a pagePtr;
+ * uses `EPDFPage_GetAnnotCountRaw` / `EPDFPage_GetAnnotRaw` /
+ * `EPDFAnnot_GetObjectNumber` directly off the docPtr.
+ *
+ * Per-subtype dispatch is the same as the full reader (both share
+ * `collectPageAnnotations`), so the wire shape `AnnotationDTO[]` is
+ * identical between raw and full read paths for the subtypes that don't
+ * actually need a pagePtr to materialise their fields.
+ */
+declare class RawAnnotationReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  listAll(signal: AbortSignal): AnnotationListSnapshotAllPages;
+  listOne(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+}
+//#endregion
+//#region src/features/fonts/FontRegistrar.d.ts
+/**
+ * A font to register at thread startup from a local file. Used by hosts that
+ * own their font policy (the cloud server's fallback fonts), as opposed to the
+ * per-request `fonts.register` wire path the browser engine drives.
+ *
+ * Registration is by path, mirroring how the server opens base documents
+ * (`fileAccess.fromNodeFile`): the bytes are range-read on demand and never
+ * held resident in the JS heap, so a deployment can configure many large
+ * fallback fonts (CJK families) without paying RAM per font.
+ */
+interface StartupFontSpec {
+  key: string;
+  /** Absolute path to a TTF/OTF file (native/node runtimes only). */
+  path: string;
+  familyName?: string;
+  weight?: number;
+  /** `undefined` → infer from the file. */
+  italic?: boolean;
+  /** Also add to the glyph-fallback chain (automatic missing-glyph fill). */
+  fallback?: boolean;
+}
+/**
+ * Thread-confined runtime font registry binding.
+ *
+ * Wraps the `EPDFFont_*` C API on a single PDFium thread. PDFium's font
+ * registry is thread-local: a font registered here is visible only to this
+ * thread's page rendering and annotation-authoring calls, and the numeric
+ * `CFX_FontRegistry::FontId` it returns is a per-thread `next_font_id++`.
+ *
+ * That id is volatile, so we never let it cross the worker boundary. The host
+ * owns the `fontKey → id` map (passed in by reference) and every wire message
+ * references the stable `fontKey`. The FreeText writer resolves a key to the
+ * current thread's id through {@link idFor} at authoring time.
+ *
+ * Lives in `engine-services` (not a worker host) so the browser Web Worker,
+ * the Node `worker_thread` server, and any future direct-thread embedding
+ * share the exact same binding — only the `PdfRuntimeModule` (WASM vs native)
+ * differs.
+ */
+declare class FontRegistrar {
+  private readonly runtime;
+  /** Host-owned `fontKey → native FontId` map for this thread. */
+  private readonly ids;
+  /**
+   * File-access handles retained for path-registered fonts. PDFium range-reads
+   * the file lazily (on each face creation), so the FPDF_FILEACCESS must stay
+   * alive until the registry is cleared — same lifetime rule as a file-backed
+   * base document. Closed in {@link clear}.
+   */
+  private readonly fileHandles;
+  constructor(runtime: PdfRuntimeModule,
+  /** Host-owned `fontKey → native FontId` map for this thread. */
+  ids: Map<string, number>);
+  /**
+   * Register a font from its bytes. Copies into the WASM heap, hands the
+   * pointer to `EPDFFont_RegisterMemFont64` (which copies the bytes into the
+   * native registry), then frees the scratch — so the heap holds exactly one
+   * retained copy per registered font.
+   *
+   * Throws `InvalidArg` when the runtime rejects the font (corrupt, no glyphs).
+   */
+  register(fontKey: string, familyName: string, weight: number, italic: number, bytes: Uint8Array): void;
+  /**
+   * Register a font from a local file via `EPDFFont_RegisterFont`. The runtime
+   * range-reads the file on demand (it is not loaded into the JS heap), and the
+   * file-access handle is retained until {@link clear}. Native/node only.
+   *
+   * Throws `InvalidArg` when the runtime rejects the font (corrupt, no glyphs).
+   */
+  registerFromNodeFile(fontKey: string, familyName: string, weight: number, italic: number, path: string): void;
+  /**
+   * Register host-owned startup fonts on this thread, in order, optionally
+   * adding each to the fallback chain. Order matters: it fixes both the native
+   * FontIds and the fallback precedence, so every worker thread that runs the
+   * same list ends up identical.
+   */
+  registerStartup(specs: readonly StartupFontSpec[]): void;
+  /** Append a registered font to the ordered glyph-fallback chain. */
+  addFallback(fontKey: string): void;
+  clearFallbacks(): void;
+  /** Unregister every font and reset the fallback chain (clears the map too). */
+  clear(): void;
+  /** Resolve a stable key to this thread's native FontId. Throws if unknown. */
+  idFor(fontKey: string): number;
+  private requireId;
+}
+//#endregion
+//#region src/features/annotations/AnnotationMutator.d.ts
+/**
+ * Synchronous orchestrator for `create` / `update` / `delete` annotation
+ * mutations. Owns the dance between PDFium calls, identity bookkeeping,
+ * revision bumping (only for structural ops), and the
+ * `AnnotationListMutationMeta` envelope every result type carries.
+ *
+ * Lives in `engine-services` (not the worker hosts) so the local Web
+ * Worker, the Node `worker_thread` server, and any future direct-thread
+ * embedding share the exact same code path. The only difference between
+ * them is the underlying `PdfRuntimeModule` (WASM vs native).
+ *
+ * Identity rules enforced here, locked with the user:
+ *   - `create` always uses `EPDFPage_CreateAnnot` (the fork helper that
+ *     creates an INDIRECT object) so new annotations are born durable.
+ *     If the fork helper ever returns a direct object, we throw — never
+ *     silently produce a weak annotation.
+ *   - `update` is non-structural. /NM is monotonic per annotation:
+ *       * already durable (objectNumber > 0 OR /NM present) -> NEVER touched.
+ *       * weak (no objectNumber, no /NM) -> stamp engine-generated UUID v4.
+ *     The patch type has no `nm` field, so the writer surface enforces
+ *     "callers cannot rename a stable id" at the type level. Updates do
+ *     not bump the revision.
+ *   - `delete` is subtype-agnostic. Three native fork helpers handle the
+ *     three ref kinds without round-tripping through index. For weak
+ *     deletes (`AnnotationStableId | null`-shaped result), we set
+ *     `deleted: null` so callers can detect that no durable id was
+ *     reportable.
+ */
+declare class AnnotationMutator {
+  private readonly runtime;
+  private readonly session;
+  /**
+   * Registered-font registry for this thread. Optional: when absent, the
+   * registered-font authoring path is unavailable and a draft/patch carrying
+   * a `registeredFontKey` fails loud (rather than silently using a standard
+   * font). Standard-font FreeText and all other subtypes are unaffected.
+   */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /**
+   * Registered-font registry for this thread. Optional: when absent, the
+   * registered-font authoring path is unavailable and a draft/patch carrying
+   * a `registeredFontKey` fails loud (rather than silently using a standard
+   * font). Standard-font FreeText and all other subtypes are unaffected.
+   */
+  fonts?: FontRegistrar | undefined);
+  /** Build the per-write context handed to subtype writers: font resolver
+   *  (FreeText `/DA`), doc/page pointers and binary resources (stamp). */
+  private writeContext;
+  create(pageObjectNumber: PageObjectNumber, draft: WireAnnotationDraft, signal: AbortSignal, actor?: AnnotationActor, resources?: WireResourceMap): AnnotationCreateResult;
+  update(ref: AnnotationRef, patch: WireAnnotationPatch, signal: AbortSignal, actor?: AnnotationActor, resources?: WireResourceMap): AnnotationUpdateResult;
+  /**
+   * Attached widgets are views of a form field: deleting one here would
+   * orphan the field's /Kids (the corruption class doc.forms.repair
+   * exists to fix). Detach first, or use the forms-plane cascade.
+   */
+  private assertNotAttachedWidget;
+  delete(ref: AnnotationRef, signal: AbortSignal): AnnotationDeleteResult;
+  /**
+   * Batch reorder of a contiguous block of annotations within a single
+   * page's /Annots array. Symmetric with `pages.move()` for pages.
+   *
+   * Semantics (locked with the user, mirrors `EPDFPage_MoveAnnots`):
+   *   - Each ref in `refs` is resolved to its current /Annots index.
+   *     The block is detached, then re-inserted at `toIndex` in the
+   *     post-removal index space, preserving caller-supplied order.
+   *   - Single-annotation case is `move([ref], toIndex)`. There is no
+   *     separate single-move path; one batch primitive serves both.
+   *   - Atomic from the caller's perspective:
+   *       * one revision bump per batch, regardless of `refs.length`.
+   *       * one `AnnotationListMutationMeta` envelope.
+   *       * if `EPDFPage_MoveAnnots` rejects (returns false) the page is
+   *         untouched and we throw `InvalidArg` without bumping.
+   *   - Identity strengthening: each weak ref in the batch (no
+   *     `objectNumber`, no `/NM`) is opportunistically stamped with a
+   *     fresh engine-generated UUID v4 BEFORE the move. So
+   *     `meta.changed` always lists durable stable ids, and the moved
+   *     DTOs come out durable. Same monotonic `/NM` rule as `update()`.
+   *
+   * Validation rules applied here BEFORE calling the helper, so callers
+   * get clean errors instead of an opaque `false` return code:
+   *   - `refs.length >= 1`.
+   *   - All refs target the page identified by `pageObjectNumber`.
+   *   - `toIndex >= 0` and `toIndex <= count - refs.length` (count is
+   *     captured AFTER ref resolution, so the helper sees the same view).
+   *   - Resolved indices have no duplicates.
+   *
+   * The `EPDFPage_MoveAnnots` helper itself enforces the same rules; the
+   * up-front validation is purely for a usable error surface.
+   */
+  move(pageObjectNumber: PageObjectNumber, refs: AnnotationRef[], toIndex: number, signal: AbortSignal): AnnotationMoveResult;
+  /**
+   * Bake (or re-bake) an annotation's `/AP` normal appearance stream from
+   * its current dictionary properties using PDFium's native AP generator,
+   * then flush the page content so the result is persisted into the
+   * page/object tree. Same path the v2 engine used after every
+   * create/update; runs for every writable subtype (shapes + text-markup).
+   *
+   * Best-effort: `EPDFAnnot_GenerateAppearance` returns false for subtypes
+   * PDFium has no generator for (e.g. widgets), in which case the
+   * annotation simply ships without a baked `/AP` and viewers synthesize
+   * one — so a false return is not a hard error; it is surfaced to `update`
+   * callers as the `generation-unavailable` appearance outcome. This step is
+   * non-structural: it never shifts annotation indices or bumps revisions.
+   */
+  private regenerateAppearance;
+  private captureOrStampStableId;
+  private ensureKnownWeakStateFromPage;
+  private recordWeakStateFromPage;
+  private computeHasWeakAnnotations;
+}
+//#endregion
+//#region src/features/annotations/internal/mutations/computeMutationImpact.d.ts
+/**
+ * The kind of mutation that just happened on a page.
+ *
+ * Index-space behaviour drives whether weak (`kind: 'index'`) refs
+ * the client may be holding stay valid:
+ *
+ *   - `update` does not touch the /Annots array at all.
+ *   - `create` is append-only — the new annotation lands at
+ *     `index = previousCount`, so no existing index ever shifts.
+ *     The array grows, but every pre-existing weak ref still points
+ *     at the same physical annotation.
+ *   - `delete` removes an entry and shifts every later index down by
+ *     one. Pre-existing weak refs at or after the removed index are
+ *     now off-by-one and stale.
+ *   - `move` detaches a contiguous block and re-inserts it, rewriting
+ *     indices on both ends of the gap. Existing weak refs across that
+ *     range are stale.
+ *
+ * So the doctrine for `MutationKind` is: only `delete` and `move`
+ * actually invalidate weak refs. `update` and `create` leave them
+ * alone. (A future explicit-position `createAt(index)` API would
+ * shift indices >= toIndex and would join the structural cohort —
+ * see `MutationKind` extension note in `compute()` below.)
+ */
+type MutationKind = AnnotationMutationKind;
+/**
+ * Inputs that decide whether a mutation should make a client refetch.
+ *
+ *   `pageStateBefore` is captured BEFORE the mutation. Its known
+ *   `weakAnnotationState` drives the locked rule:
+ *     index-shifting mutation × any weak annotation on the page  ⇒  refetch.
+ *
+ *   `pageStateAfter` is captured AFTER the mutation. It carries the
+ *   bumped revision token (for index-shifting ops) and the recomputed
+ *   weak-annotation state (for any op that might have changed it, e.g.
+ *   opportunistic /NM stamping during update).
+ *
+ *   `changed` is the list of stable ids the mutation actually touched.
+ *   Empty for a weak delete (we have no durable id to report).
+ */
+interface ImpactInputs {
+  mutation: MutationKind;
+  pageStateBefore: PageState;
+  pageStateAfter: PageState;
+  changed: AnnotationStableId[];
+}
+/**
+ * Pure helper: turn a mutation outcome into the side-effect envelope
+ * every result type carries on its `meta` field.
+ *
+ * The rules — locked with the user, do not change without re-reading
+ * the doc comment on `AnnotationListMutationMeta` and the
+ * `MutationKind` definition above:
+ *
+ *   1. `update` and `create` are non-invalidating.
+ *
+ *      - `update` doesn't touch the /Annots array; indices on the page
+ *        do not move, so weak refs the client may be holding stay
+ *        valid. Opportunistic /NM stamping during an update is also
+ *        non-structural — it changes the annotation's identity quality
+ *        but not its position.
+ *
+ *      - `create` is append-only. The new annotation goes at
+ *        `index = previousCount`, so no existing index shifts and no
+ *        pre-existing weak ref ever becomes stale. We treat `create`
+ *        the same as `update` for impact purposes: no revision bump,
+ *        `weakRefsInvalidated = false`, `shouldRefetch = null`.
+ *
+ *        The "revisions exist solely for weak-ref authentication"
+ *        doctrine (see `pages.move()`'s identical reasoning) means we
+ *        deliberately do NOT bump on `create` — bumping a revision
+ *        that nobody's weak ref depends on would erode the invariant
+ *        and turn revisions into a generic "something changed" signal.
+ *
+ *   2. `delete` and `move` ARE index-shifting. They genuinely move
+ *      pre-existing indices:
+ *        - `delete` removes an annotation, shifting every later index
+ *          down by one.
+ *        - `move` detaches a contiguous block and re-inserts it
+ *          elsewhere, rewriting indices on both ends of the gap.
+ *      They invalidate weak refs iff the page actually had any weak
+ *      refs *before* the mutation — if every annotation already had a
+ *      durable identity, no client could possibly be holding a stale
+ *      index, and we keep `shouldRefetch = null`.
+ *
+ *      (`move` opportunistically stamps /NM on weak refs in the batch
+ *      BEFORE the move, so the annotations actually being moved end up
+ *      durable on the way out; but other weak annotations on the page
+ *      still need a refetch.)
+ *
+ *   3. When rule (2) fires, the reason is always `'weakRefsInvalidated'`.
+ *      `'pageRebuilt'` and `'externalChange'` are reserved for higher-
+ *      level signals the engine doesn't emit yet (insert/delete-page
+ *      that rebuilds /Annots, watch-based refresh). Page **reorder**
+ *      explicitly does NOT bump per-page revisions and does NOT emit
+ *      `pageRebuilt` — see `PagesMutator`.
+ *
+ *   Future note: when an explicit-position `createAt(index)` API
+ *   ships, add `'createAt'` to `MutationKind` and slot it into rule
+ *   (2) — it shifts every index >= toIndex and is structural in the
+ *   same way `delete` and `move` are.
+ */
+declare function computeMutationImpact(inputs: ImpactInputs): AnnotationListMutationMeta;
+//#endregion
+//#region src/features/attachments/AttachmentReader.d.ts
+/**
+ * Read-only access to embedded files, at both of their homes: the
+ * document catalog's `/EmbeddedFiles` name tree (list / readFile by
+ * index) and a FileAttachment annotation's `/FS` (readAnnotationFile by
+ * ref). Pure READS over the session — no revision bumps, no layer
+ * artifacts (the `PagesExtractor` shape).
+ *
+ * Byte delivery mirrors the request's `path?`: absent → a standalone
+ * buffer for the transfer list (browser); present → the decoded file is
+ * streamed to `path` via `FPDF_FILEWRITE` (server), and only metadata
+ * rides the response.
+ */
+declare class AttachmentReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /** Snapshot of the `/EmbeddedFiles` name tree, in tree (key-sorted) order. */
+  list(signal: AbortSignal): EmbeddedFileItem[];
+  /** Decode one document-level embedded file, addressed by key. */
+  readFile(ref: EmbeddedFileRef, path: string | undefined, maxDecodedBytes: number | undefined, signal: AbortSignal): AttachmentFileWorkerPayload;
+  /** Decode the file embedded in a FileAttachment annotation's `/FS`. */
+  readAnnotationFile(pageObjectNumber: PageObjectNumber, ref: AnnotationRef, path: string | undefined, maxDecodedBytes: number | undefined, signal: AbortSignal): AttachmentFileWorkerPayload;
+  private extract;
+}
+//#endregion
+//#region src/features/attachments/AttachmentMutator.d.ts
+/**
+ * Create/delete mutations over the document catalog's `/EmbeddedFiles`
+ * name tree — the doc-level sibling of `AnnotationMutator`, sharing the
+ * write path (`writeAttachmentFilePayload`) with the file-attachment
+ * annotation writer.
+ *
+ * Identity is the name-tree KEY (unique by construction), so unlike
+ * annotations there is no weak-ref/revision bookkeeping here. Note the
+ * tree is key-sorted: both mutations shift OTHER entries' indices; keys
+ * never move. Layer persistence (`finishMutation`) and event publication
+ * happen in the callers, exactly like every other mutation family.
+ */
+declare class AttachmentMutator {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /**
+   * Create an embedded file. `file.name` becomes the tree key (PDFium
+   * writes key = /UF = /F); a duplicate key rejects with `InvalidArg`.
+   * The result carries the read-back entry, `checksum`/`size`/dates
+   * included.
+   */
+  create(file: WireAttachmentFile, resources: WireResourceMap | undefined, signal: AbortSignal): AttachmentCreateResult;
+  /** Delete an embedded file by key. Unlinks the tree entry only. */
+  delete(ref: EmbeddedFileRef, signal: AbortSignal): AttachmentDeleteResult;
+}
+//#endregion
+//#region src/features/attachments/internal/attachmentPrimitives.d.ts
+/**
+ * Write an embedded file's payload onto an existing FPDF_ATTACHMENT:
+ * bytes via FPDFAttachment_SetFile (which also writes /Params
+ * Size/CheckSum/CreationDate), declared mime via EPDFAttachment_SetSubtype
+ * (attachments accept any format — no sniffing), optional /Desc. Shared
+ * by the file-attachment annotation writer and the document-level
+ * `attachments.create` mutation — the write half of the one attachment
+ * vocabulary.
+ */
+declare function writeAttachmentFilePayload(fn: PdfFunctions, mem: PdfRuntimeMemory, attachmentPtr: Ptr, docPtr: Ptr, file: {
+  mimeType?: string;
+  description?: string;
+}, resource: WireResource): void;
+/** Read the metadata projection of an embedded file (never its bytes). */
+declare function readAttachmentFileInfo(fn: PdfFunctions, mem: PdfRuntimeMemory, attachmentPtr: Ptr): AttachmentFileInfo;
+//#endregion
+//#region src/features/security/SecurityReader.d.ts
+/**
+ * Reads document security/permission state. Three entry points:
+ *
+ *   - `probeFile` is the only doc-less path: it opens, inspects, and
+ *     closes its own document straight off a file. It is the intentional
+ *     exception to the package's `(runtime, session)` reader shape — it
+ *     answers "what is this file's security?" before any session exists.
+ *   - `readLiveSecurityInfo` / `checkPasswordPermissions` inspect an
+ *     already-open `DocumentSession`.
+ */
+declare class SecurityReader {
+  private readonly runtime;
+  constructor(runtime: PdfRuntimeModule);
+  probeFile(path: string, password?: string | null): DocumentSecurityProbeInfo;
+  /**
+   * Snapshot of the live session's EFFECTIVE security state.
+   * `FPDF_GetDocUserPermissions` reports the permission word in force
+   * right now (e.g. after an owner unlock), as opposed to the declared
+   * word the cold `probeFile` path reads.
+   */
+  readLiveSecurityInfo(session: DocumentSession): DocumentSecurityProbeInfo;
+  /**
+   * Verify a password against the live session and report the resulting
+   * effective permissions. Throws `DocPasswordIncorrect` when the
+   * password is rejected, or (in `'owner'` mode) when it unlocks only as
+   * a user.
+   */
+  checkPasswordPermissions(session: DocumentSession, password: string, mode?: 'any' | 'owner'): DocumentSecurityProbeInfo;
+}
+//#endregion
+//#region src/features/save/DocumentSaver.d.ts
+/**
+ * Owns every "serialize the open document" path for a `DocumentSession`.
+ * Two distinct outputs:
+ *
+ *   - Layer artifacts (`saveLayerArtifact*`) are the storage-optimized
+ *     `.layer` delta used by server-side persistence. Only valid for a
+ *     `layer` session.
+ *   - Standalone saves (`saveStandalone*`) export a self-contained PDF
+ *     view (base + applied delta) via `FPDF_SaveAsCopy` /
+ *     `EPDF_SaveDocumentToOwnedBuffer`, valid for any session kind.
+ *
+ * Lives in `engine-services` so the browser Worker and the Node
+ * `worker_thread` server share the exact same save code path.
+ */
+declare class DocumentSaver {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  saveLayerArtifact(): {
+    bytes: ArrayBuffer;
+    size: number;
+  };
+  saveLayerArtifactToFile(path: string): {
+    path: string;
+  };
+  saveStandaloneToBuffer(mode: PdfSaveMode): {
+    bytes: ArrayBuffer;
+    size: number;
+  };
+  saveStandaloneToFile(path: string, mode: PdfSaveMode): {
+    path: string;
+  };
+  private requireLayer;
+}
+//#endregion
+//#region src/features/forms/FormReader.d.ts
+/**
+ * Read side of the forms feature. All reads go through the session's
+ * version-keyed model cache, so repeated reads between mutations reuse
+ * one native snapshot build.
+ */
+declare class FormReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  snapshot(signal: AbortSignal): FormSnapshot;
+  field(ref: FormFieldRef, signal: AbortSignal): FormFieldDTO;
+  /**
+   * Serialize form data. Exports read the reconciled view (recovered
+   * fields included; on layers, promoted values win) straight from the
+   * document — the model cache is not involved.
+   */
+  exportData(format: FormDataFormat, signal: AbortSignal): {
+    format: FormDataFormat;
+    bytes: ArrayBuffer;
+  };
+}
+//#endregion
+//#region src/features/forms/FormMutator.d.ts
+/**
+ * Write side of the forms feature. Every method is a validate-then-apply
+ * transaction over the native EPDFForm_* write API: a failed call leaves
+ * the document untouched (on layers: nothing promoted), and each success
+ * bumps the session's mutation sequence so version-keyed caches rebuild.
+ */
+declare class FormMutator {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  setValue(ref: FormFieldRef, value: FormFieldValue, signal: AbortSignal): FormSetValueResult;
+  reset(ref: FormFieldRef, signal: AbortSignal): FormSetValueResult;
+  importData(data: ArrayBuffer, format: FormDataFormat | undefined, signal: AbortSignal): FormImportResult;
+  repair(bakeAppearances: boolean, signal: AbortSignal): FormRepairResult;
+  /**
+   * Create a field and (optionally) its widgets in one composed
+   * transaction: native field creation, widget birth through the
+   * annotation plane, adoption, then field-plane setters. A failure
+   * mid-composition throws; earlier steps stay applied (the document is
+   * never inconsistent - at worst a partially configured field exists).
+   */
+  createField(draft: FormFieldDraft, signal: AbortSignal): {
+    field: FormFieldDTO;
+  };
+  updateField(ref: FormFieldRef, patch: FormFieldPatch, signal: AbortSignal): {
+    field: FormFieldDTO;
+  };
+  /**
+   * Delete a terminal field. Widgets are DETACHED here (they become inert
+   * annotations); the worker host cascades their annotation deletion so
+   * page /Annots bookkeeping flows through the annotation feature.
+   */
+  deleteField(ref: FormFieldRef, signal: AbortSignal): {
+    deletedFieldObjectNumber: number;
+    detachedWidgets: FormWidgetRef[];
+  };
+  attachWidget(ref: FormFieldRef, widget: FormWidgetRef, onState: string | undefined, signal: AbortSignal): {
+    field: FormFieldDTO;
+  };
+  detachWidget(ref: FormFieldRef, widget: FormWidgetRef, signal: AbortSignal): {
+    field: FormFieldDTO;
+  };
+  private placementsOf;
+  private applyOptions;
+  private applyWideSetter;
+  private applyDefaultValues;
+  private readBackField;
+  private assertWritable;
+  /** Dispatch the typed native write. Returns the changed widget objnums. */
+  private applyWrite;
+  /** Run a native write with the changed-widgets out buffer wired up. */
+  private withChangedWidgets;
+  /** Bump the session version, rebuild the model, and read the field back. */
+  private readBack;
+}
+//#endregion
+//#region src/features/forms/FormsEffectsApplier.d.ts
+/** Ordered, non-rollback-atomic sink for one committed client script run. */
+declare class FormsEffectsApplier {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  apply(effects: FormEffect[], signal: AbortSignal): FormEffectsResult;
+  private preflight;
+  private resolve;
+  private readField;
+  private readFieldsBestEffort;
+  private applyNative;
+  private applyValue;
+  private withChangedWidgets;
+}
+//#endregion
+//#region src/features/forms/internal/formModelCache.d.ts
+/** Close and forget the session's cached model, if any. */
+declare function disposeFormModel(runtime: PdfRuntimeModule, session: DocumentSession): void;
+//#endregion
+//#region src/features/search/SearchReader.d.ts
+/**
+ * The whole search pipeline for one budgeted slice, running inside the
+ * trust boundary (worker locally, server process in the cloud):
+ *
+ *   extract — page text via the session corpus cache (version-keyed on
+ *             `mutationSeq`, so results always reflect the CURRENT layer
+ *             view — text a redaction removed is unfindable),
+ *   match   — the pure engine-core matcher (identical code on every
+ *             engine; parity by construction),
+ *   anchor  — geometry read only for pages that actually matched, rects
+ *             via the selection line-merge (one rect per visual line).
+ *
+ * Scope gating (`doc.text.search`, `doc.text.copy` for `'full'`) is the
+ * caller's job — this reader assumes an authorized request.
+ */
+declare class SearchReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  query(request: SearchRequest, signal: AbortSignal): SearchSlice;
+}
+//#endregion
+//#region src/features/actions/ActionModelReader.d.ts
+/** Mutable aggregate budget shared by every action model in one read job. */
+declare class ActionReadBudgetTracker {
+  private readonly limits;
+  private models;
+  private nodes;
+  private scriptCodeUnits;
+  constructor(limits?: ActionReadBudget);
+  addModel(nodeCount: number): void;
+  addScript(script: string): void;
+  private assertWithinBudget;
+}
+/**
+ * Convert and close one detached native action model. This is the only
+ * native-model walker used by document, page, field, and annotation reads.
+ */
+declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
+//#endregion
+//#region src/features/actions/DocumentActionsReader.d.ts
+/** Read catalog-owned actions. Extraction only; no action is executed. */
+declare class DocumentActionsReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  read(signal: AbortSignal): DocumentActionsSnapshot;
+}
+//#endregion
+//#region src/worker-host/WorkerHost.d.ts
+/**
+ * The piece that runs "inside the worker": owns runtime, manages document
+ * sessions, dispatches requests to the engine-services synchronous code.
+ *
+ * Environment-agnostic. Wrap it with a Web Worker entry, a Node
+ * worker_thread entry, or an inline transport. The wrapper owns
+ * postMessage plumbing and any process/lifecycle concerns; the host only
+ * knows about PdfRuntimeModule, DocumentSession, AbortController, and the
+ * worker wire shape from @embedpdf/engine-core.
+ */
+declare class WorkerHost {
+  private readonly runtime;
+  /**
+   * Receives a fully-typed `WirePack<WorkerResponse>` (the envelope
+   * payload plus its transfer manifest). The wrapper (browser
+   * `worker-entry.ts`, Node `worker-entry.ts`, or `InlineTransport`)
+   * is responsible for actually invoking `postMessage(pack.payload,
+   * pack.transfer)` — the host doesn't know which environment it
+   * runs in.
+   */
+  private readonly post;
+  private readonly sessions;
+  private readonly baseDocuments;
+  private readonly aborts;
+  /**
+   * Runtime-global registered fonts for this thread. The registry is
+   * thread-local in PDFium, so it lives on the host (one per thread), not per
+   * document session. `fontIds` maps the stable wire `fontKey` to this
+   * thread's volatile native FontId.
+   */
+  private readonly fontIds;
+  private readonly fonts;
+  private destroyed;
+  constructor(runtime: PdfRuntimeModule,
+  /**
+   * Receives a fully-typed `WirePack<WorkerResponse>` (the envelope
+   * payload plus its transfer manifest). The wrapper (browser
+   * `worker-entry.ts`, Node `worker-entry.ts`, or `InlineTransport`)
+   * is responsible for actually invoking `postMessage(pack.payload,
+   * pack.transfer)` — the host doesn't know which environment it
+   * runs in.
+   */
+  post: (pack: WirePack<WorkerResponse>) => void);
+  /**
+   * Register deployment-owned fonts on this worker thread, after init and
+   * before serving requests. Server-only: the cloud engine never exposes font
+   * configuration to clients, so the host (not a wire message) seeds the
+   * thread's fallback fonts. Browser engines drive fonts through the
+   * `fonts.*` wire path instead. Throws if any font fails to load.
+   */
+  registerStartupFonts(specs: readonly StartupFontSpec[]): void;
+  receive(msg: WorkerRequest): void;
+  private handleOpen;
+  private handleMetadataRead;
+  private handleMetadataUpdate;
+  private handleActionsRead;
+  private handleAnnotationsListRawAll;
+  private handleAnnotationsListRawPage;
+  private handleAnnotationsListFullPage;
+  private handleAnnotationsRenderAppearances;
+  private handleAnnotationsCreate;
+  private handleAnnotationsUpdate;
+  private handleAnnotationsDelete;
+  private handleAnnotationsMove;
+  private handlePagesList;
+  private handlePagesMove;
+  private handlePagesRotate;
+  private handlePagesDelete;
+  private handlePagesFlatten;
+  private handleRedactionApply;
+  private handlePagesExtract;
+  private handlePagesInsert;
+  private handleAttachmentsList;
+  private handleAttachmentsReadFile;
+  private handleAttachmentsCreate;
+  private handleAttachmentsDelete;
+  private handleAnnotationsReadFile;
+  private handlePieceInfoRead;
+  private handlePieceInfoUpdate;
+  private handlePieceInfoApplications;
+  private handlePieceInfoClear;
+  private handlePagesText;
+  private handlePagesGeometry;
+  private handleSearchQuery;
+  private handlePagesRender;
+  private handleDocumentSaveBuffer;
+  private handleDocumentSaveFile;
+  private handleDocumentSaveLayerBuffer;
+  private handleDocumentProbeSecurityFile;
+  /**
+   * One-shot file render (the derived-artifact warmer's producer): open the
+   * base from a file path into a TRANSIENT session — never stored in
+   * `this.sessions`, so it can't collide with (or leak into) live document
+   * sessions — resolve the display index to its durable page object number,
+   * render, close. Shares the base parse with concurrent ad-hoc opens of
+   * the same file via the registry refcount.
+   */
+  private handleDocumentRenderPageFile;
+  private handleDocumentCheckPasswordPermissions;
+  private handleFontsRegister;
+  private handleFontsAddFallback;
+  private handleFontsClearFallbacks;
+  private handleFontsClear;
+  /**
+   * Close exactly ONE layer session — the reload seam for layer-session
+   * freshness. The base document's refcount releases through the session's
+   * close stack, so sibling layer sessions (and the base session) are
+   * untouched. Idempotent: closing an absent session is a no-op ack,
+   * because the caller may be reloading a layer this worker never held
+   * (e.g. after a pool eviction).
+   */
+  private handleLayerClose;
+  private handleClose;
+  private handleShutdown;
+  private requireSession;
+  /**
+   * Finalize a mutation response. For a standalone session the mutation
+   * result is returned as-is. For a layer session we additionally persist
+   * the layer artifact (to file when `artifactPath` is given, otherwise to
+   * a transferable buffer) and merge it onto the response envelope. This
+   * is the one place the layer-vs-standalone branch lives, shared by every
+   * annotation and page mutation handler.
+   */
+  private handleFormsList;
+  private handleFormsSetValue;
+  private handleFormsReset;
+  private handleFormsApplyEffects;
+  private handleFormsExport;
+  private handleFormsImport;
+  private handleFormsRepair;
+  private handleFormsCreateField;
+  private handleFormsUpdateField;
+  private handleFormsDeleteField;
+  private handleFormsAttachWidget;
+  private handleFormsDetachWidget;
+  private finishMutation;
+  private saveLayerArtifact;
+}
+//#endregion
+export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, type ImpactInputs, type LayerSource, LocalRevisionAuthority, MetadataMutator, MetadataReader, type MutationKind, type OpenedPdfDocument, type OpenedPdfDocumentKind, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, type StartupFontSpec, WorkerHost, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+//# sourceMappingURL=index.d.ts.map