@embedpdf/engine-services 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { ActionReadBudget, AnalyzeInput, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationFlattenResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, BaseVersionInfo, ChangeAnalysis, DigestAlgorithm, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentProtection, DocumentSecurityProbeInfo, DocumentVersionRef, EmbeddedFileItem, EmbeddedFileRef, FontIdentityInfo, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryRun, PageGeometrySnapshot, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNameInput, PageNameResult, PageNetworkRenderFormat, PageObjectNumber, PageRaster, PageRemoveNameInput, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfQuad, PdfRect, PdfRevision, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionStructure, RevisionToken, SearchRequest, SearchSlice, SessionKind, SignatureAbortResult, SignatureCompleteInput, SignatureCompleteResult, SignatureDTO, SignaturePrepareInput, SignaturePrepared, SignatureSnapshot, SignedDocumentPolicy, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
+import { ActionReadBudget, AnalyzeInput, Annotation, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationAuthority, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationExportSelection, AnnotationFamily, AnnotationFlattenResult, AnnotationImportResult, AnnotationList, AnnotationListMutationMeta, AnnotationPatch, AnnotationRef, AnnotationReplyType, AnnotationUpdateResult, Attachment, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, AttachmentRef, BaseVersionInfo, BundleImportPages, BundleLimits, ChangeAnalysis, ChangeAuthority, ChangeItem, ChangeItemType, ChangeRecordPayload, ChangeResult, CustomMetadata, CustomMetadataPatch, CustomMetadataUpdateResult, DateInput, DigestAlgorithm, DocumentActionsSnapshot, DocumentMetadata, DocumentProtection, DocumentSecurityProbeInfo, DocumentVersionRef, EngineError, FieldPosition, FontIdentityInfo, FormExportSelection, FormFieldDTO, FormFieldDisplay, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormResetResult, FormSetValueResult, FormSnapshot, FormValuesImportDrop, FormWidget, IsoDateTime, MetadataPatch, MetadataUpdateResult, ObjectNumberRange, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryRun, PageGeometrySnapshot, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageNameInput, PageNameResult, PageNetworkRenderFormat, PageObjectNumber, PagePosition, PageRaster, PageRef, PageRemoveNameInput, PageRenderOptions, PageReorderResult, PageRotateResult, PageTextSnapshot, PdfActionTree, PdfCoordinates, PdfDestination, PdfQuad, PdfRect, PdfRevision, PdfRotation, PdfSaveMode, RecordedOp, RedactionApplyResult, RedactionApplyScope, RevisionStructure, SearchScanRequest, SearchSlice, SerializedEngineError, SignatureCancelResult, SignatureCompleteInput, SignatureCompleteResult, SignatureDTO, SignaturePrepareInput, SignaturePrepared, SignatureSnapshot, SignedDocumentPolicy, VisibleBoxOf, WidgetAnnotation, WidgetPlacement, WireAnnotationBundle, WireAnnotationResources, WireAttachmentFile, WireFormBundle, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse, WorkingSetPage, generateUuid } from "@embedpdf/engine-core/runtime";
 import { PdfFunctions, PdfRuntimeMemory, PdfRuntimeModule, Ptr } from "@embedpdf/engine-runtime";
+import { PlannedValueWrite } from "@embedpdf/engine-core/validation";
 //#region src/runtime/lifecycle/bootstrap.d.ts
 /**
  * Initialize the thread-confined PDFium runtime for the calling thread. Each
@@ -15,67 +16,29 @@ 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.
+ * Throw if the AbortSignal has been aborted. Service code calls this between
+ * PDFium calls. It only sees an abort the thread has received, and a worker
+ * thread receives messages only while it awaits: work that never pauses (see
+ * `Slices`) sees an abort sent while it ran only when it is done.
  */
 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.
+ * A PDF date as ISO 8601, keeping its offset: zero reads as `Z`, and a date
+ * without an offset reads without one. Fields the date leaves out take the
+ * spec's defaults (month and day 1, the rest 0). The `D:` prefix and the
+ * apostrophes of the offset are optional, as readers in the wild treat them.
+ * Returns `null` when the text isn't a date.
  */
-declare function pdfDateToIso(pdf: string): string | null;
+declare function pdfDateToIso(pdf: string): IsoDateTime | 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).
+ * A moment as a PDF date. A string keeps its own offset (none if it has
+ * none); a `Date` is an instant, written in UTC. A fraction of a second is
+ * dropped: PDF dates have whole seconds. UTC is written as `+00'00'` rather
+ * than `Z`, which some readers don't accept.
  */
-declare function formatPdfDate(d?: Date): string;
+declare function formatPdfDate(value?: DateInput): string;
 //#endregion
 //#region src/runtime/memory/bits.d.ts
 /**
@@ -97,51 +60,37 @@ 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
+//#region src/document-session/DrawingIndex.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.
+ * An open document's stamp drawings, known by content, so stamps with the
+ * same artwork place one drawing. It lives in memory for as long as the
+ * native document does; nothing of it is written into the PDF, and a reopen
+ * rebuilds it from what the drawings are then.
  *
- * 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.
+ * Both maps stay true because no writer edits a drawing in place: a stamp
+ * that changes gets a new wrapper, and new artwork is a new drawing. Anything
+ * that deletes objects or reuses object numbers (a rollback) must call
+ * {@link DrawingIndex.forget}.
  */
-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;
+declare class DrawingIndex {
+  /**
+   * Content id (the SHA-256, in hex, of a drawing's canonical bytes) → the
+   * drawing's object number. `null` until the first lookup builds it from
+   * the drawings the document's stamps place.
+   */
+  byContent: Map<string, number> | null;
+  /**
+   * SHA-256 (hex) of bytes as a caller gave them → the drawing made from
+   * them, so placing the same bytes again skips making the drawing.
+   */
+  readonly bySource: Map<string, number>;
+  /**
+   * SHA-256 (hex) of bytes already hashed, by the buffer holding them. The
+   * stamps of one import share one buffer per resource, so it is copied and
+   * hashed once. A fact about the bytes, so {@link forget} keeps it.
+   */
+  readonly hashes: WeakMap<ArrayBuffer, string>;
+  forget(): void;
 }
 //#endregion
 //#region src/document-session/lifecycle/PdfDocumentOpener.d.ts
@@ -202,38 +151,198 @@ declare class CloseStack {
 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/shared/slices.d.ts
+/**
+ * How long work runs before it lets the thread receive messages. PDFium works
+ * for `budgetMs` at a time - a slice of a page render or of a page load - and
+ * the caller awaits `between()` before it goes on, so the thread can receive
+ * messages meanwhile: an abort stops the work at the next slice. The result is
+ * that of the work done at once, however it is sliced.
+ */
+interface Slices {
+  readonly budgetMs: number;
+  between(): Promise<void>;
+}
+//#endregion
+//#region src/document-session/pages/PageResidency.d.ts
+/**
+ * The parsed pages of every document on one runtime - one WASM heap, or one
+ * server thread - kept within a budget of bytes.
+ *
+ * Parsing a page is the costly part of using it: seconds for a page of
+ * millions of vector objects, where one tile of it renders in milliseconds.
+ * So a page stays parsed after the job that used it, for the next one, as long
+ * as memory allows:
+ * - A page costs what its parse made (`EPDFPage_GetParsedSize`) and a fixed
+ *   overhead for the page itself.
+ * - Room is made before a page loads, for its size when it was last open, and
+ *   again after every slice of a load, as the page grows. A page a job holds
+ *   never closes, so one page may be over the budget on its own: the one a
+ *   job needs.
+ * - A page bigger than the whole budget stays parsed after its job too, or
+ *   every job on it would parse it again: of such pages, the one that would
+ *   close last is kept, and the budget holds every other page beside it. It
+ *   closes when the pages jobs hold need the budget's room themselves.
+ * - What the viewers show decides what closes first (`setWorkingSet`): pages
+ *   in no working set, then `near` pages, then `visible` pages from the
+ *   fewest device pixels on screen up, so a thumbnail rail's pages close
+ *   before the main view's. Least recently used first among equals.
+ * - A render loads its page in slices, between which its job can be aborted.
+ *   An aborted load is set aside half parsed, and the next job that needs the
+ *   page goes on with it.
+ * - A page whose content changed since it was parsed closes when it is next
+ *   taken (`EPDFPage_IsContentCurrent`). That sees writes made in layer
+ *   transactions; the worker host closes a document's pages around the writes
+ *   that change content in place.
+ * - A page's image cache is emptied when its last job releases it, so its next
+ *   job renders images as a newly loaded page does.
+ * - Pages no job uses and no viewer shows close after a while, giving their
+ *   memory back to the allocator.
+ *
+ * Pages belong to an owner, one per open document ({@link PagePtrPool}).
+ */
+interface PageResidencyPolicy {
+  /**
+   * Bytes of parsed pages kept at once; a page a job holds, or one page bigger
+   * than the budget, may be over it alone.
+   */
+  budgetBytes: number;
+  /** Pages no job uses close after this many milliseconds; 0 disables the timer. */
+  idleMs: number;
+}
+declare class PageResidency {
+  private readonly runtime;
+  private readonly policy;
+  /**
+   * True while a job is between two of its steps, such as a page render
+   * between slices, when nothing else may use PDFium: the idle timer then
+   * waits another period instead of closing pages.
+   */
+  private readonly busy;
+  private readonly pages;
+  /** What each closed page cost when it was last open: the room its next load needs. */
+  private readonly closedSizes;
+  /** Per owner, per view: where the pages it shows are (see {@link setWorkingSet}). */
+  private readonly workingSets;
+  private totalBytes;
+  private clock;
+  private timer;
+  constructor(runtime: PdfRuntimeModule, policy?: PageResidencyPolicy,
+  /**
+   * True while a job is between two of its steps, such as a page render
+   * between slices, when nothing else may use PDFium: the idle timer then
+   * waits another period instead of closing pages.
+   */
+  busy?: () => boolean);
+  /** The page, loaded in one go when it isn't parsed; held until {@link release}. */
+  acquire(owner: object, docPtr: Ptr, pageObjectNumber: PageObjectNumber): Ptr;
+  /**
+   * The page, loaded in slices when it isn't parsed: between slices the
+   * caller's thread receives messages, and an abort stops the load there. An
+   * aborted load is set aside, to go on when a job next needs the page. Held
+   * until {@link release}.
+   */
+  acquireInSlices(owner: object, docPtr: Ptr, pageObjectNumber: PageObjectNumber, signal: AbortSignal, slices: Slices): Promise<Ptr>;
+  /** A job is done with the page; it stays parsed while there is room. */
+  release(owner: object, pageObjectNumber: PageObjectNumber): void;
+  /**
+   * What `view` shows of `owner`'s pages, replacing its last set; an empty set
+   * withdraws it. Decides which kept pages close first (see the class notes).
+   * Only bookkeeping: it touches no PDFium state, so it may run mid-render.
+   */
+  setWorkingSet(owner: object, view: string, pages: Iterable<{
+    pageObjectNumber: PageObjectNumber;
+  } & Pick<WorkingSetPage, 'role' | 'pixels'>>): void;
+  /** True while a job holds the page; an idle page is not held. */
+  isHeld(owner: object, pageObjectNumber: PageObjectNumber): boolean;
+  /** True while the page is kept, parsed or loading: a job for it parses nothing new. */
+  isKept(owner: object, pageObjectNumber: PageObjectNumber): boolean;
+  /** Closes every page of `owner`, held or not: its document closes. */
+  closeOwner(owner: object): void;
+  /** Closes the pages of `owner` no job holds: a write changed its content in place. */
+  closeIdleOf(owner: object): void;
+  /** Closes every page no job holds. */
+  closeIdle(): void;
+  /** Closes the pages no job holds and no viewer shows on screen: the idle timer. */
+  private closeUnshown;
+  /** Pages kept, held or not (tests and diagnostics). */
+  get size(): number;
+  /** What the pages kept cost, as last measured (tests and diagnostics). */
+  get bytes(): number;
+  /** The page when it is kept, unless its content changed meanwhile. */
+  private take;
+  private add;
+  private measure;
+  private expectedBytes;
+  /**
+   * Closes pages no job holds until `incoming` more bytes fit: the worst
+   * placed first (see the class notes), least recently used first among
+   * equals.
+   *
+   * A page bigger than the budget on its own may stay over it: of such pages,
+   * the one that would close last. So it stays parsed between the jobs that
+   * use it, instead of parsing again for each one. Every other page fits in
+   * the budget beside it; when the pages jobs hold don't, they are the pages
+   * over it, and the spared page closes too. A budget of 0 keeps nothing.
+   */
+  private makeRoom;
+  /** The page no job holds that closes first, other than `spared`. */
+  private firstToClose;
+  /**
+   * Of the pages bigger than the budget, the one that closes last: the best
+   * placed, the most recently used among equals.
+   */
+  private lastToCloseOverBudget;
+  /** Where the working sets have the page: the best place any view gives it. */
+  private placeOf;
+  private close;
+  /** Closes the page without remembering its size. */
+  private drop;
+  private armTimer;
+  private disarmTimer;
+}
+//#endregion
 //#region src/document-session/pages/PagePtrPool.d.ts
 /**
- * Manages pagePtr lifetime for a single open `DocumentSession`.
+ * The pages of one open `DocumentSession`, kept by the runtime's
+ * {@link PageResidency}.
  *
- * `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()`.
+ * `acquire(pon)` returns the page with that PDF object number, loaded with
+ * `EPDFDoc_LoadPageByObjectNumberNormalized` when it isn't kept (rotation
+ * forced to 0deg, so render, text, geometry and annotation coordinates all
+ * share one normalized space); `acquireInSlices` loads it in slices, for a
+ * render. Overlapping acquires of one page share it; `release(pon)` hands it
+ * back to the residency, which keeps it parsed while there is room.
+ * `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.
+ * A session made without a residency (a one-off render of a file) gets one
+ * of its own that keeps nothing: its pages close when released.
  */
 declare class PagePtrPool {
-  private readonly runtime;
   private readonly docPtr;
-  private readonly counts;
-  constructor(runtime: PdfRuntimeModule, docPtr: Ptr);
+  private readonly residency;
+  constructor(runtime: PdfRuntimeModule, docPtr: Ptr, residency?: PageResidency | null);
   acquire(pageObjectNumber: PageObjectNumber): Ptr;
+  /** {@link acquire}, loading the page in slices between which `signal` can abort. */
+  acquireInSlices(pageObjectNumber: PageObjectNumber, signal: AbortSignal, slices: Slices): Promise<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.
+   * True while at least one holder has the page open; a page the residency
+   * keeps between jobs is not held. 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;
+  /** True while the residency keeps the page, parsed or loading, held or not. */
+  isKept(pageObjectNumber: PageObjectNumber): boolean;
   release(pageObjectNumber: PageObjectNumber): void;
+  /** What `view` shows of the document, replacing its last set (see {@link PageResidency}). */
+  setWorkingSet(view: string, pages: Iterable<{
+    pageObjectNumber: PageObjectNumber;
+  } & Pick<WorkingSetPage, 'role' | 'pixels'>>): void;
+  /** Closes the pages no job holds: a write changed the document's content in place. */
+  closeIdle(): void;
   closeAll(): void;
 }
 //#endregion
@@ -242,7 +351,7 @@ declare class PagePtrPool {
  * 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()`).
+ * for the whole document is invoked (most notably a whole-document annotation list).
  *
  * Carries no `pagePtr`. Lifetime of the actual PDFium page handle is owned
  * by the `PagePtrPool`; the page record is metadata only.
@@ -254,10 +363,9 @@ interface PageRecord {
 //#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).
+ * Owns the lifecycle of a single open PDFium document and the
+ * identity machinery: page registry (pageObjectNumber <-> pageIndex) 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
@@ -300,6 +408,11 @@ interface SigningCompletion {
   readonly cms: Uint8Array;
   readonly result: SignatureCompleteResult;
 }
+/** What every meta of a write carries: its id, and whether it can be undone. */
+interface WriteStamp {
+  readonly opId: string;
+  readonly undoable: boolean;
+}
 declare class DocumentSession {
   private readonly runtime;
   private docPtr;
@@ -312,33 +425,36 @@ declare class DocumentSession {
   /** pageIndex -> record */
   private readonly recordsByIndex;
   private fullyEnumerated;
-  private revisions;
-  private mutationSeqCounter;
+  /** Bumped by {@link invalidateDerived}: the version caches built from the document key on. */
+  private cacheSeqCounter;
+  /** Bumped by {@link noteEdit}: one per committed write, never inside or for an abort. */
+  private editsSeqCounter;
+  /** The open layer transaction, if any (see {@link beginTransaction}). */
+  private transaction;
+  /** Why the session can't be used anymore, after a transaction neither committed nor aborted. */
+  private unusableReason;
   private pages;
+  /**
+   * The runtime's parsed pages, kept between jobs. Set before the document
+   * loads; without it every page closes when its last holder releases it.
+   */
+  residency: PageResidency | null;
   /**
    * Whether writers honour what the document's signatures forbid (locked
    * fields, structural edits). Set at open from the engine option; the
    * main-thread guard subtracts the matching capabilities.
    */
   signedDocumentPolicy: SignedDocumentPolicy;
-  /**
-   * The shape the caller asked for when opening plain bytes. `layer` (the
-   * default) opens them as an immutable base with a fresh layer; `plain`
-   * keeps one in-memory document unless the bytes already carry a
-   * signature, which always opens as a layer.
-   */
-  sessionKind: SessionKind;
   /** The password the document was opened with; signing candidates open with the same one. */
   password: string | null;
   /**
    * Whether mutations on a layer session also serialize the layer artifact
-   * into their response (what a server persists). False for a session that
-   * became a layer only because its document is signed (see
-   * `WorkerHost.openSignedAware`): the caller opened plain bytes and never
-   * asked for artifacts.
+   * into their response (what a server persists). False for a session opened
+   * from bytes (`WorkerHost.openBytesAsLayer`): the caller holds the document
+   * and never asked for artifacts.
    */
   persistLayerArtifact: boolean;
-  /** The mutation sequence the current bytes were loaded at (see `hasUnsavedEdits`). */
+  /** The edits sequence the current bytes were loaded at (see `hasUnsavedEdits`). */
   private loadedSeq;
   /** SHA-256 (hex) of a plain session's loaded bytes, hashed once per load. */
   private plainSha256;
@@ -346,6 +462,8 @@ declare class DocumentSession {
   pendingSigning: PendingSigning | null;
   /** The last completed signing, so a replayed `complete` answers `already-completed`. */
   lastCompletion: SigningCompletion | null;
+  /** The stamp drawings of the open document, by content; dropped with it. */
+  private drawings;
   constructor(runtime: PdfRuntimeModule, sessionId?: string);
   get sessionId(): string;
   get kind(): OpenedPdfDocumentKind | null;
@@ -359,8 +477,8 @@ declare class DocumentSession {
   open(bytes: Uint8Array, password?: string | null): void;
   openFromHandle(handle: OpenedPdfDocument): void;
   /**
-   * Whether anything was mutated since the current bytes were loaded. When
-   * false, the loaded bytes ARE the document: a save returns them verbatim
+   * Whether a write was committed since the current bytes were loaded. When
+   * false, the loaded bytes are the document: a save returns them verbatim
    * and a signing candidate is built straight on them.
    */
   hasUnsavedEdits(): boolean;
@@ -373,8 +491,9 @@ declare class DocumentSession {
    * installs its sealed file. The session id, its page object numbers
    * (an incremental save never renumbers) and its retained resources
    * survive; the old document is closed, every page is re-pinned (its
-   * revision bumped, its cached pointer dropped), and the mutation
-   * sequence advances so every version-keyed cache rebuilds.
+   * cached pointer dropped), and both sequences
+   * advance, so every version-keyed cache rebuilds and the new bytes count as
+   * loaded.
    */
   install(handle: OpenedPdfDocument): void;
   /** The two publish fences a candidate is built on. */
@@ -382,64 +501,139 @@ declare class DocumentSession {
   /**
    * 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.
+   * how to load it (the already-transferred bytes, a base's path, the layer
+   * to open) and waits for an unlock attempt. A locked session occupies its
+   * docId key like an open one — every operation except the password check
+   * rejects with DocPasswordRequired.
    */
-  parkLocked(bytes: Uint8Array): void;
+  parkLocked(load: (password: string | null) => void): void;
   isLocked(): boolean;
-  /** The bytes retained for a later unlock attempt. Locked sessions only. */
-  lockedBytes(): Uint8Array;
-  private parkedBytes;
+  /**
+   * Load a locked session with `password`. A wrong one throws
+   * `DocPasswordIncorrect` and leaves the session parked for another try.
+   */
+  unlockWith(password: string | null): void;
+  private parkedLoad;
   /** Number of pages in the document. */
   pageCount(): number;
   /**
    * Lazily enumerate every page and cache (pageObjectNumber, pageIndex).
-   * Necessary before `listRawAll()` and any pon -> pageIndex resolution.
+   * Necessary before a whole-document list and any pon -> pageIndex resolution.
    */
   ensureFullPageRegistry(): void;
   /** Lookup; populates the cache for one page only on cache miss. */
   recordByObjectNumber(pageObjectNumber: PageObjectNumber): PageRecord;
+  /**
+   * Resolve a page address to its registry record — the one boundary where
+   * a `PageRef` becomes a page object number. Throws `NotFound` for an
+   * unknown page.
+   */
+  resolvePageRef(ref: PageRef): PageRecord;
+  /** `resolvePageRef` over a batch, preserving order. */
+  resolvePageRefs(refs: readonly PageRef[]): PageObjectNumber[];
   /** 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.
+   * after `FPDF_MovePages` shuffles page positions.
    */
   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;
+  /**
+   * The version key for caches built from the document (the forms model,
+   * the signature model, search text): an entry built at sequence N is
+   * exactly valid while the sequence is still N. Coarse on purpose: widgets
+   * are annotations and page edits move widgets, so any write may change
+   * derived form state.
+   */
+  cacheSeq(): number;
+  /**
+   * Make every cache keyed on {@link cacheSeq} build again. Writers call it
+   * after a write, before they read back; an abort calls it too, because a
+   * cache may have been built from what the transaction wrote.
+   */
+  invalidateDerived(): void;
+  /**
+   * The count of committed writes: what {@link hasUnsavedEdits} and a signing
+   * candidate's `editsVersion` compare.
+   */
+  editsSeq(): number;
+  /** Count one committed write. Called once per write, after its commit. */
+  noteEdit(): void;
+  /** Whether a layer transaction is open (see {@link beginTransaction}). */
+  inTransaction(): boolean;
+  /**
+   * Open a layer transaction: until {@link commitTransaction} or
+   * {@link abortTransaction}, every write lands in an overlay that only a
+   * commit keeps, and every read sees it. Only a layer document has
+   * transactions. `opId` names the write it runs (see {@link writeStamp}).
+   */
+  beginTransaction(opId: string): void;
+  /**
+   * What every meta of the running write carries: its `opId`, and whether
+   * it can be undone. A write is undoable once {@link markUndoable} said so,
+   * which a write does when it records its reverse.
+   */
+  writeStamp(): WriteStamp;
+  /** The running write records its reverse, so `{ undoOf: opId }` can undo it. */
+  markUndoable(): void;
+  /**
+   * Keep everything the open transaction wrote. A commit that fails can't
+   * say how far it got, so the session becomes unusable.
+   */
+  commitTransaction(): void;
+  /**
+   * Drop everything the open transaction wrote, and forget what this session
+   * learned from it. Never throws: it runs while a failure is on its way out,
+   * and a failed abort makes the session unusable instead.
+   */
+  abortTransaction(): void;
+  /**
+   * Who decides which object numbers a create may name: `'session'` hands
+   * them out ({@link reserveObjectNumbers}) and refuses a number it doesn't
+   * hold; `'caller'` checked every number before sending the job (a server
+   * that hands numbers to editing sessions).
+   */
+  objectNumberAuthority: 'session' | 'caller';
+  /** Numbers this session handed out that no committed create has used. */
+  private readonly heldObjectNumbers;
+  /** Held numbers the open transaction made objects at: spent when it commits. */
+  private objectNumbersInUse;
+  /** The layer's last object number: every object it has is at or below it. */
+  lastObjectNumber(): number;
+  /**
+   * Raise the layer's last object number to at least `last`, so the objects
+   * the next write makes for itself get numbers above it. A raise outlives
+   * an abort: numbers once passed are never handed out again.
+   */
+  raiseLastObjectNumber(last: number): void;
+  /**
+   * Hand out `count` more numbers: the layer's last object number moves up
+   * by `count`, so nothing the engine makes lands on them, and they are this
+   * session's to name objects with.
+   */
+  reserveObjectNumbers(count: number): ObjectNumberRange;
+  /**
+   * Checks the number a create names before anything is written, and counts
+   * it as used by the open transaction: spent when it commits, held again
+   * if it aborts. A session that hands numbers out refuses one it doesn't
+   * hold (`not-held`); a number the transaction already used is `taken`.
+   * Nothing else creates objects at held numbers, so a held number is free
+   * otherwise; the fork checks that again as it creates.
+   */
+  useObjectNumber(objectNumber: number): void;
+  /**
+   * Throws once a transaction neither committed nor aborted, so nothing reads
+   * or writes a document in an unknown state.
+   */
+  assertUsable(): void;
+  private requireTransaction;
   pagePool(): PagePtrPool;
+  /** The open document's stamp drawings, by content (see {@link DrawingIndex}). */
+  drawingIndex(): DrawingIndex;
   requireDocPtr(): Ptr;
   /**
-   * Park a disposer to run when THIS session closes. Used by operations
+   * 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
@@ -449,7 +643,6 @@ declare class DocumentSession {
   retainUntilClose(dispose: () => void): void;
   private readonly retained;
   close(): void;
-  private requireRevisions;
 }
 //#endregion
 //#region src/document-session/lifecycle/BaseDocumentRegistry.d.ts
@@ -492,54 +685,6 @@ declare class BaseDocumentRegistry {
   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.
@@ -555,6 +700,8 @@ declare class MetadataReader {
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   read(signal: AbortSignal): DocumentMetadata;
+  /** The Info dict's custom keys: every key but the standard ones. */
+  readCustom(signal: AbortSignal): CustomMetadata;
 }
 //#endregion
 //#region src/features/metadata/MetadataMutator.d.ts
@@ -574,6 +721,8 @@ declare class MetadataMutator {
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   update(patch: MetadataPatch, signal: AbortSignal): MetadataUpdateResult;
+  /** Set and remove custom keys, then re-read them the same way. */
+  updateCustom(patch: CustomMetadataPatch, signal: AbortSignal): CustomMetadataUpdateResult;
 }
 //#endregion
 //#region src/features/pages/PagesReader.d.ts
@@ -588,8 +737,14 @@ declare class PagesReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  read(signal: AbortSignal): PageListSnapshot;
+  read(signal: AbortSignal): PageListSnapshot<PdfCoordinates>;
 }
+/**
+ * Each page's visible box, read the first time it is asked for: what a
+ * result's destinations are measured on. A page that isn't in the document
+ * has none.
+ */
+declare function visibleBoxReader(runtime: PdfRuntimeModule, session: DocumentSession): VisibleBoxOf;
 //#endregion
 //#region src/features/pages/PagesMutator.d.ts
 /**
@@ -599,35 +754,26 @@ declare class PagesReader {
  * `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.
+ * re-reading the doc comment on `PageReorderResult`:
  *
- *   - 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.
+ *   - Pages are addressed by their durable `pageObjectNumber`, which must
+ *     remain stable across every reorder permutation.
  *
- *   - 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.
+ *   - The /Annots array of each page is untouched by `reorder()` (PDFium just
+ *     rewrites pointer entries in the doc-level pages tree), so every
+ *     annotation ref the caller is holding stays valid across a page
+ *     reorder: shuffling pages must not silently break a pending
+ *     highlight edit.
  */
 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.
+   * Reorder pages: they go together, in the order given, to `position`, next
+   * to a neighbour page or at the start or end. Mirrors `FPDF_MovePages`,
+   * which detaches the pages and re-inserts them as a block at an index in
+   * the pages left: the neighbour's index there, or the one after it.
    *
    * Atomicity:
    *   - `FPDF_MovePages` rejects atomically: if it returns false, no
@@ -635,66 +781,63 @@ declare class PagesMutator {
    *   - 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]`.
+   * Validation done up front, for clean error messages: at least one page,
+   * none twice, and a neighbour that isn't one of them (`InvalidArg`); every
+   * page and the neighbour pages of the document (`NotFound`).
    */
-  move(pageObjectNumbers: PageObjectNumber[], destIndex: number, signal: AbortSignal): PageMoveResult;
+  reorder(pages: PageRef[], position: PagePosition, signal: AbortSignal): PageReorderResult<PdfCoordinates>;
   /**
-   * Set the ABSOLUTE display rotation of the supplied pages. Rotation is
+   * 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;
+   *   - 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),
+   * Atomicity: every page object number 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
+   * fault converges to the requested state. Abort is honored before the
    * loop, never inside it.
    */
-  rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation, signal: AbortSignal): PageRotateResult;
+  rotate(pages: PageRef[], rotation: PdfRotation, signal: AbortSignal): PageRotateResult<PdfCoordinates>;
   /**
-   * Delete pages. Deleted object numbers are RETIRED — the engine nulls the
+   * 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.
+   * page object number can never silently attach to an unrelated future
+   * page. Surviving pages keep their identity, and their annotations their
+   * names.
    *
    * Guards:
    *   - a document must keep at least one page (`InvalidArg`);
-   *   - every PON must resolve (`NotFound`);
+   *   - every page object number 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.
+   * Abort is honored before the apply loop, never inside it.
    */
-  delete(pageObjectNumbers: PageObjectNumber[], signal: AbortSignal): PageDeleteResult;
+  delete(pages: PageRef[], signal: AbortSignal): PageDeleteResult<PdfCoordinates>;
   /**
    * Register `name` → page in `/Names /Pages` (create, or replace what the
    * key points at); with `replace`, drop that other key first — a rename as
-   * one job. Named pages are LAYOUT: page identity and order are untouched
-   * (no registry refresh, no revision bumps) and the fresh snapshot is
+   * one job. Named pages are layout: page identity and order are untouched
+   * (no registry refresh) and the fresh snapshot is
    * returned like `move()`.
    */
-  setName(input: PageNameInput, signal: AbortSignal): PageNameResult;
+  setName(input: PageNameInput, signal: AbortSignal): PageNameResult<PdfCoordinates>;
   /** Remove one `/Names /Pages` registration; the page stays. */
-  removeName(input: PageRemoveNameInput, signal: AbortSignal): PageNameResult;
-  /** Shared input check: non-empty, no duplicate PONs. */
-  private requireUniquePons;
+  removeName(input: PageRemoveNameInput, signal: AbortSignal): PageNameResult<PdfCoordinates>;
+  /** Shared input check: non-empty, no duplicate page object numbers. */
+  private requireUniquePageObjectNumbers;
 }
 //#endregion
 //#region src/features/pages/PagesExtractor.d.ts
 /**
- * Export a subset of pages as a standalone PDF. A READ over the session:
+ * 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
+ * source is untouched — 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.
  */
@@ -705,10 +848,10 @@ declare class PagesExtractor {
   /**
    * 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
+   * duplicates, every page object number resolvable (`NotFound` from the session on a
    * bad one). The scratch document is always closed, success or throw.
    */
-  extract(pageObjectNumbers: PageObjectNumber[], signal: AbortSignal): {
+  extract(pages: PageRef[], signal: AbortSignal): {
     bytes: ArrayBuffer;
     size: number;
   };
@@ -717,9 +860,9 @@ declare class PagesExtractor {
 //#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
+ * 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 in at `position`, 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.
  */
@@ -727,43 +870,49 @@ declare class PagesInserter {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  insert(bytes: ArrayBuffer, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
+  insert(bytes: ArrayBuffer, position: PagePosition, signal: AbortSignal): PageInsertResult<PdfCoordinates>;
   /**
-   * Create `count` blank pages of `size` at `destIndex`. Same mutation
-   * contract as `insert`, but native creation (`FPDFPage_New`) instead of a
-   * deep copy: no source document, so none of the retain-until-close
-   * lifetime hazard above. Each page gets an empty content stream
-   * (`FPDFPage_GenerateContent`) so the saved PDF renders identically in
-   * third-party viewers.
+   * Create `count` blank pages of `size` at `position`. Same mutation
+   * contract as `insert`, but native creation (`EPDFPage_InsertBlankRaw`,
+   * which never loads the page) instead of a deep copy: no source document,
+   * so none of the retain-until-close lifetime hazard above. A blank page has
+   * no `/Contents`, which ISO 32000-2 defines as an empty page.
+   *
+   * `objectNumbers`, one per page, names the pages: numbers the session
+   * holds, each checked before the first page is made.
    */
-  insertBlank(spec: PageInsertBlankSpec, destIndex: number | undefined, signal: AbortSignal): PageInsertResult;
+  insertBlank(spec: PageInsertBlankSpec, position: PagePosition, signal: AbortSignal, objectNumbers?: readonly number[]): PageInsertResult<PdfCoordinates>;
 }
 //#endregion
 //#region src/features/pages/PagesFlattener.d.ts
-/** Layer-safe page flattening. Content and annotation liveness change together. */
+/**
+ * Layer-safe page flattening. Content and annotation liveness change
+ * together, all or nothing: a page that fails, or a cancel, aborts the whole
+ * flatten.
+ */
 declare class PagesFlattener {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  flatten(pageObjectNumbers: PageObjectNumber[], usage: PageFlattenUsage, signal: AbortSignal): PageFlattenResult;
+  flatten(pages: PageRef[], 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.
+ * change together, exactly like {@link PagesFlattener}: all or nothing, so a
+ * page that fails, or a cancel, aborts the whole apply.
  *
  * Scope semantics:
- *   - `pages`: every REDACT annotation on each listed page is applied; a
+ *   - `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`.
+ *   - `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
+ * annotations other than redact ones removed alongside the apply (popup
  * cascades and detached widgets included).
  */
 declare class RedactionApplier {
@@ -773,29 +922,34 @@ declare class RedactionApplier {
   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).
+   * "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
+   * 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 pageHasRedactAnnotations;
+  /**
+   * Applies `refs` in one native call: their regions are redacted together,
+   * so an image under several of them is read and written once.
+   */
   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 page text, and releases everything in reverse order.
+ * `PagePtrPool` (a page not parsed yet loads in slices, so an abort stops the
+ * load), opens a PDFium text page (`FPDFText_LoadPage`), extracts the page
+ * text, and releases everything in reverse order.
  *
  * Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
- * CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
- * `text` is the TEXT projection. The two diverge when a character
+ * character space (`FPDFText_CountChars` — the space geometry runs tile);
+ * `text` is the text projection. The two diverge when a character
  * contributes zero text units (non-printing) or two (supplementary plane);
  * `charMap` anchors encode exactly those deviations.
  *
@@ -815,7 +969,7 @@ declare class PageTextReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageTextSnapshot;
+  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal, slices: Slices): Promise<PageTextSnapshot>;
 }
 //#endregion
 //#region src/features/geometry/PageGeometryReader.d.ts
@@ -830,9 +984,9 @@ interface RawGeometryGlyphRecord {
   /** Sampled at each text object's first glyph (run splits inherit it). */
   fontSize?: number;
   /**
-   * Wire flags (bit 1 = space, bit 2 = empty). Synthesized-but-visible
-   * glyphs (/ActualText pieces) stay 0, exactly like the legacy reader —
-   * they represent real, selectable text.
+   * `FLAG_SPACE` and `FLAG_EMPTY`. Synthesized-but-visible glyphs
+   * (/ActualText pieces) stay 0, exactly like the legacy reader — they
+   * represent real, selectable text.
    */
   flags: number;
   /** Page-space AABB (zeroed when empty). */
@@ -844,7 +998,7 @@ interface RawGeometryGlyphRecord {
   /** Native uprightness of the char matrix (empty glyphs: true, inert). */
   upright: boolean;
   /** Baseline angle (radians CCW, PDF y-up); 0 when upright. */
-  rotation: number;
+  baselineAngle: number;
   /** True when the ascent vector maps opposite the rotated +y (det < 0). */
   ascentFlip: boolean;
 }
@@ -853,7 +1007,7 @@ interface RawGeometryGlyphRecord {
  *
  * 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.
+ * matrix; this reader applies no Y-flip or device transform.
  *
  * One `EPDFText_GetCharGeometry` call per glyph supplies boxes, oriented
  * cells, and flags together; `buildRunsFromRawGlyphs` then groups glyphs
@@ -865,7 +1019,12 @@ declare class PageGeometryReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal): PageGeometrySnapshot;
+  /**
+   * A page's text geometry. The page loads in slices when it isn't parsed, and
+   * the glyph loop pauses once a slice's budget is spent, so an abort stops the
+   * read at either.
+   */
+  read(pageObjectNumber: PageObjectNumber, signal: AbortSignal, slices: Slices): Promise<PageGeometrySnapshot<PdfCoordinates>>;
   private readGlyphRaw;
 }
 /**
@@ -873,16 +1032,16 @@ declare class PageGeometryReader {
  *
  * Runs split on text-object change (the legacy rule) and on orientation
  * change between classifiable glyphs (θ drift / mixed orientation). A run's
- * variant is decided by its FIRST classifiable glyph:
+ * variant is decided by its first classifiable glyph:
  *   - empty glyphs never classify (they adopt the run's variant);
- *   - real glyphs WITHOUT an oriented cell (singular matrix, synthesized
+ *   - real glyphs without an oriented cell (singular matrix, synthesized
  *     /ActualText pieces) classify as upright — box-only data degrades to
  *     exactly the legacy behavior;
  *   - real glyphs with a non-upright matrix classify as rotated.
  * Runs that never see a classifiable glyph emit as upright (degenerate,
  * legacy behavior).
  */
-declare function buildRunsFromRawGlyphs(records: RawGeometryGlyphRecord[]): PageGeometryRun[];
+declare function buildRunsFromRawGlyphs(records: RawGeometryGlyphRecord[]): PageGeometryRun<PdfCoordinates>[];
 //#endregion
 //#region src/runtime/memory/structs.d.ts
 /** Generated from `EPDF_CHAR_GEOMETRY`; pinned by native static_asserts. */
@@ -912,7 +1071,15 @@ 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;
+  /**
+   * Renders a page in slices, and says which area of it the pixels show.
+   * Until it settles, PDFium holds the page's render: the caller must not let
+   * anything else use PDFium between slices.
+   */
+  render(pageObjectNumber: PageObjectNumber, options: PageRenderOptions<PdfCoordinates>, signal: AbortSignal, slices: Slices): Promise<{
+    raster: PageRaster;
+    area: PdfRect;
+  }>;
 }
 //#endregion
 //#region src/features/fonts/FontRegistrar.d.ts
@@ -1038,29 +1205,38 @@ declare class AnnotationReader {
   constructor(runtime: PdfRuntimeModule, session: DocumentSession,
   /** This thread's font registry: FreeText faces read back as keys. */
   fonts?: FontRegistrar | undefined);
-  list(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+  list(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationList<PdfCoordinates>;
 }
 //#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`).
+ * Batch-renders the appearances of one family of a page's annotations (its
+ * annotations except widgets, or its widgets), one bitmap per mode it stores
+ * (or each requested one) and per state of that mode, each labelled with
+ * both, 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.
+ * A stored appearance (`/AP`) renders into its annotation's `/Rect`. An
+ * annotation with no normal appearance renders as PDFium draws it in memory,
+ * into the box that drawing takes (`EPDFAnnot_GetDrawingRect`), which can
+ * reach past `/Rect`; nothing is written. One PDFium can draw only by
+ * generating an appearance into the file has no raster. Each bitmap is sized
+ * to its box at the scale the page has at `options.viewport`. 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.
+   * The page loads in slices when it isn't parsed, and the loop pauses between
+   * annotations once a slice's budget is spent, so an abort stops it at either.
+   */
+  render(pageObjectNumber: PageObjectNumber, family: AnnotationFamily, options: AnnotationAppearanceRenderOptions, signal: AbortSignal, slices: Slices): Promise<AnnotationAppearancesResult<PdfCoordinates>>;
+  /**
+   * Render a single annotation appearance into its own raster, sized to
+   * `rect`: the stored appearance, or the one PDFium draws in memory. Returns
+   * `null` when the render fails.
    */
   private renderOne;
 }
@@ -1072,9 +1248,13 @@ declare class AnnotationAppearanceReader {
  * `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
+ * `collectPageAnnotations`), so the wire shape `Annotation[]` is
  * identical between raw and full read paths for the subtypes that don't
  * actually need a pagePtr to materialise their fields.
+ *
+ * `family` builds only one family's rows: the public reads pass it
+ * (`'annotations'` for `annotations.list()`, `'widgets'` for the form);
+ * the change internals read every row, by its `/Annots` index.
  */
 declare class RawAnnotationReader {
   private readonly runtime;
@@ -1084,16 +1264,16 @@ declare class RawAnnotationReader {
   constructor(runtime: PdfRuntimeModule, session: DocumentSession,
   /** This thread's font registry: FreeText faces read back as keys. */
   fonts?: FontRegistrar | undefined);
-  listAll(signal: AbortSignal): AnnotationListSnapshotAllPages;
-  listOne(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+  /** The given pages in their order, or every page in document order. */
+  list(pages: readonly PageObjectNumber[] | undefined, signal: AbortSignal, family?: AnnotationFamily): AnnotationList<PdfCoordinates>;
+  listOne(pageObjectNumber: PageObjectNumber, signal: AbortSignal, family?: AnnotationFamily): AnnotationList<PdfCoordinates>;
 }
 //#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.
+ * mutations. Owns the dance between PDFium calls, identity bookkeeping, 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
@@ -1101,21 +1281,19 @@ declare class RawAnnotationReader {
  * 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.
+ *   - `create` is a one-item change set on `AnnotationBatchApplier`, which
+ *     makes the annotation with `EPDFPage_CreateAnnotRaw` (an indirect
+ *     object, on a page that isn't loaded), so a new annotation is named by
+ *     its object number. If the fork helper ever returns a direct object, it
+ *     throws.
+ *   - Every annotation keeps its name through every write (see
+ *     `annotationRefOf`). No write stamps an /NM to name one, and the patch
+ *     type has no `nm` field, so callers cannot rename one either.
+ *   - `delete` is subtype-agnostic and names everything it removed.
+ *
+ * Every write finds its annotations from the page's dictionaries (raw
+ * handles), so none parses the page's content. Each runs inside its job's
+ * layer transaction: a failure after the first write aborts all of it.
  */
 declare class AnnotationMutator {
   private readonly runtime;
@@ -1136,69 +1314,52 @@ declare class AnnotationMutator {
    */
   fonts?: FontRegistrar | undefined);
   /** Build the per-write context handed to subtype writers: font resolver
-   *  (FreeText `/DA`), doc/page pointers and binary resources (stamp). */
+   *  (FreeText `/DA`), the document pointer 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;
+  /**
+   * A one-item change set on {@link AnnotationBatchApplier}: checked before
+   * the first write, made without loading its page, all or nothing. A
+   * `reply` or a popup's `parent` names an annotation the document has.
+   */
+  create(pageObjectNumber: PageObjectNumber, draft: AnnotationDraft<PdfCoordinates>, signal: AbortSignal, options?: {
+    /** Who creates it: stamped as its author. */
+    readonly actor?: AnnotationActor;
+    /** The bytes beside the draft, by role. */
+    readonly resources?: WireAnnotationResources;
+    /** The object number it gets; the next free one when absent. */
+    readonly objectNumber?: number;
+  }): AnnotationCreateResult<PdfCoordinates>;
+  /**
+   * Edit an annotation in place. `authority` is checked against the
+   * annotation as it reads before the first write, and gives the actor the
+   * write stamps.
+   */
+  update(ref: AnnotationRef, patch: AnnotationPatch<PdfCoordinates>, authority: AnnotationAuthority, signal: AbortSignal, resources?: WireAnnotationResources): AnnotationUpdateResult<PdfCoordinates>;
   /**
    * 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.
+   * exists to fix). Remove it from its field first, or delete the field. A
+   * merged field/widget is the field's own dictionary and has nothing to be
+   * removed from, so only the field's delete removes it; that cascade passes
+   * the field it has unlinked as `releasedFieldObjectNumber`.
    */
   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.
+   * Delete an annotation with everything that goes with it
+   * ({@link deletedWith}): its replies and theirs, grouped parts, review
+   * states and every popup, in one change. `authority` is checked against
+   * each of them, and every check runs before the first write.
    */
-  move(pageObjectNumber: PageObjectNumber, refs: AnnotationRef[], toIndex: number, signal: AbortSignal): AnnotationMoveResult;
+  delete(ref: AnnotationRef, authority: AnnotationAuthority, signal: AbortSignal): AnnotationDeleteResult;
   /**
-   * 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;
+   * Remove a widget of the field `doc.forms.delete` has just unlinked from
+   * the field tree, including the field's own dictionary when it is a
+   * merged field/widget. The cascade runs past that mutation's apply
+   * boundary, so it takes no abort signal.
+   */
+  deleteReleasedWidget(ref: AnnotationRef, releasedFieldObjectNumber: number): AnnotationDeleteResult;
+  /** An annotation of the page opened raw at `index`, closed after `body`. */
+  private withAnnotAt;
 }
 //#endregion
 //#region src/features/annotations/AnnotationFlattener.d.ts
@@ -1206,7 +1367,7 @@ declare class AnnotationMutator {
  * The annotation-plane flatten verbs — `pages.flatten` for a chosen set:
  * in place (`flatten`) or into a new single-page document
  * (`exportAppearance`). Both resolve refs to native handles on the page,
- * hand the SET to the fork (one candidate plan, one placement writer — the
+ * hand the set to the fork (one candidate plan, one placement writer — the
  * same code whole-page flatten runs), and release every handle afterwards.
  */
 declare class AnnotationFlattener {
@@ -1218,126 +1379,499 @@ declare class AnnotationFlattener {
     bytes: ArrayBuffer;
     size: number;
   };
-  /** Resolve every ref on `pagePtr` (NotFound / InvalidReference from the
-   *  resolver on caller error); on any failure, close what was opened. */
+  /**
+   * An annotation's `appearance` resource: what its normal appearance draws
+   * apart from what its data describes, as a one-page PDF
+   * (`EPDFAnnot_ExportAppearance`). Only a kind that takes an appearance
+   * resource has one; a copy is created from these bytes and the data.
+   */
+  readAppearance(pageObjectNumber: PageObjectNumber, ref: AnnotationRef, signal: AbortSignal): {
+    bytes: ArrayBuffer;
+    size: number;
+  };
+  /** Resolve every ref on `pagePtr` (NotFound from the resolver on caller
+   *  error); on any failure, close what was opened. */
   private resolveAll;
   /** Marshal an `FPDF_ANNOTATION*` array for the call's duration. */
   private withHandleArray;
   private requireRefs;
 }
 //#endregion
-//#region src/features/annotations/internal/mutations/computeMutationImpact.d.ts
+//#region src/features/annotations/AnnotationExporter.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.)
+ * `doc.annotations.export`: the annotations a selection takes
+ * ({@link closeExportSelection}) and the bytes beside them, as one bundle.
+ * No page is loaded or parsed: annotations are read raw, and each resource
+ * is exported from a raw handle, so a large document costs dictionary reads.
+ * A drawing is one resource however many stamps place it, and equal bytes
+ * are one resource under their hash. A bundle is page space, like
+ * everything the engine hands out: each item is measured from the top-left
+ * of its page. It is checked against `limits` as it is built, in the form
+ * it leaves in, so an export never makes one an import refuses.
  */
-type MutationKind = AnnotationMutationKind;
+declare class AnnotationExporter {
+  private readonly runtime;
+  private readonly session;
+  /** This thread's font registry: FreeText faces read back as keys. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry: FreeText faces read back as keys. */
+  fonts?: FontRegistrar | undefined);
+  export(selection: AnnotationExportSelection, limits: BundleLimits, signal: AbortSignal): WireAnnotationBundle;
+}
+//#endregion
+//#region src/features/annotations/AnnotationImporter.d.ts
+interface AnnotationImportRequest {
+  /** In page space, as bundles are: each item converts on the page it goes to. */
+  readonly bundle: WireAnnotationBundle;
+  readonly pages?: BundleImportPages;
+  readonly attribution: 'restore' | 'stamp';
+  /**
+   * The session's identity: who `'stamp'` attributes each annotation to, and
+   * whose user `'restore'` records as `importedBy`.
+   */
+  readonly actor?: AnnotationActor;
+  readonly limits: BundleLimits;
+  /**
+   * Checks each annotation the import will create, before anything is
+   * written: what its create would need. A refusal refuses the import.
+   */
+  readonly authorizeCreate?: (draft: AnnotationDraft<PdfCoordinates>) => void;
+}
 /**
- * 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).
+ * `doc.annotations.import`: a bundle's annotations, created in this document
+ * as one change. The bundle is checked first, cheapest checks first: its
+ * shape, counts and sizes against the limits, each resource against its id,
+ * and each image's decoded size, before any image is decoded. Then
+ * {@link planAnnotationImport} maps pages and works out what to leave out,
+ * each create is measured on the page it goes to, from that page's
+ * top-left, and {@link AnnotationBatchApplier} writes them, all or nothing. No
+ * page is loaded: names are looked up in the page dictionaries, and
+ * annotations made on raw handles.
+ */
+declare class AnnotationImporter {
+  private readonly runtime;
+  private readonly session;
+  /** This thread's font registry: FreeText faces by key. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry: FreeText faces by key. */
+  fonts?: FontRegistrar | undefined);
+  import(request: AnnotationImportRequest, signal: AbortSignal): AnnotationImportResult<PdfCoordinates>;
+  private assertBundle;
+}
+//#endregion
+//#region src/features/annotations/internal/write/writeEmbedMetadata.d.ts
+/** The `/EMBD_Metadata` fields a restoring import writes as the bundle has them. */
+interface RestoredEmbedMetadata {
+  readonly userId: string | null;
+  readonly createdBy: string | null;
+  readonly modifiedBy: string | null;
+  readonly groupId: string | null;
+}
+//#endregion
+//#region src/features/annotations/internal/write/restoreAttribution.d.ts
+/** The attribution a restoring import writes: the fields a read returned, as they are. */
+interface RestoredAttribution extends RestoredEmbedMetadata {
+  readonly author: string | null;
+  readonly createdAt: string | null;
+  readonly modifiedAt: string | null;
+}
+//#endregion
+//#region src/features/annotations/AnnotationBatchApplier.d.ts
+/**
+ * What a link points at: another create of the same change, by its place in
+ * it, so creates can refer to each other before any exists; or an annotation
+ * the document has.
  */
-interface ImpactInputs {
-  mutation: MutationKind;
-  pageStateBefore: PageState;
-  pageStateAfter: PageState;
-  changed: AnnotationStableId[];
+type BatchLinkTarget = {
+  readonly planned: number;
+} | {
+  readonly existing: AnnotationRef;
+};
+/** One create of a change. */
+interface BatchCreate {
+  /** The page it goes on. */
+  readonly page: PageRef;
+  /** Its data, without its links, which are the two fields below. */
+  readonly draft: AnnotationDraft<PdfCoordinates>;
+  /** `reply`: the annotation it replies to, on the same page. */
+  readonly replyTo?: {
+    readonly to: BatchLinkTarget;
+    readonly type: AnnotationReplyType;
+  };
+  /** For a popup: the annotation it shows, on the same page. */
+  readonly parent?: BatchLinkTarget;
+  /** The bytes beside the draft, by role. */
+  readonly resources?: WireAnnotationResources;
+  /** The object number it gets; the next free one when absent. */
+  readonly objectNumber?: number;
+  /**
+   * Who wrote the annotation, and when: the session now, as `create`
+   * stamps it, or the attribution it already had, restored as it is. A
+   * stamped one is a new annotation: without an `nm` in its data it gets a
+   * fresh UUIDv7 name. A restored one keeps the name it had, or none.
+   */
+  readonly attribution: {
+    readonly kind: 'stamp';
+    readonly actor?: AnnotationActor;
+  } | {
+    readonly kind: 'restore';
+    readonly from: RestoredAttribution;
+    /** The importing session's user, recorded as `importedBy`. */
+    readonly importedBy?: string;
+  };
+  /** A copied file attachment's file dates, kept in either attribution. */
+  readonly fileDates?: Pick<AttachmentFileInfo, 'createdAt' | 'modifiedAt'>;
+  /** Names the create in an error, such as `import: item 3`. */
+  readonly label?: string;
+}
+interface BatchCreateResult {
+  /** In the order of the creates, each as it is now. */
+  created: Annotation<PdfCoordinates>[];
+  meta: AnnotationListMutationMeta;
 }
 /**
- * Pure helper: turn a mutation outcome into the side-effect envelope
- * every result type carries on its `meta` field.
+ * Applies a change set as one unit: every item is checked before the first
+ * write, and the writes run inside the job's layer transaction, so any
+ * failure, an abort included, leaves the document as it was. It currently
+ * applies annotation creates for imports.
  *
- * The rules — locked with the user, do not change without re-reading
- * the doc comment on `AnnotationListMutationMeta` and the
- * `MutationKind` definition above:
+ * No page is loaded or parsed. Each annotation is made on a raw handle
+ * (`EPDFPage_CreateAnnotRaw`) and opened again the same way, by its place in
+ * its page's `/Annots`, for each pass:
  *
- *   1. `update` and `create` are non-invalidating.
+ * 1. create every annotation in order, so each page's `/Annots` keeps it,
+ *    with its data and its appearance;
+ * 2. link replies and popups to what they name: another create, or an
+ *    annotation the document has (one born inline becomes an object, which
+ *    a link needs, and keeps its name);
+ * 3. attribute each, stamped as the session or restored as it was, last,
+ *    so no later write touches `/M`.
  *
- *      - `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.)
+ * A create that names its object number makes the annotation at exactly
+ * that number: one the session holds, checked before the first write, and
+ * free in the layer, which the create itself checks.
+ */
+declare class AnnotationBatchApplier {
+  private readonly runtime;
+  private readonly session;
+  /** This thread's font registry: FreeText faces by key. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry: FreeText faces by key. */
+  fonts?: FontRegistrar | undefined);
+  create(creates: readonly BatchCreate[], signal: AbortSignal): BatchCreateResult;
+  /**
+   * A name must be free on its page (ISO 32000-2 §12.5.2): not used there,
+   * and not by an earlier create of the change.
+   */
+  private claimName;
+  /**
+   * A link's target, checked before the first write: another create of the
+   * change, or an annotation the document has, on the same page (ISO
+   * 32000-2 §12.5.6.2). Creates only append, so its place holds.
+   */
+  private linkTarget;
+  private writeContext;
+  private withOpen;
+  private withOpenExisting;
+}
+//#endregion
+//#region src/features/changes/ChangeRecord.d.ts
+/**
+ * What the engine keeps of a change so it can undo it: who made it, and the
+ * steps that reverse it, in the order they run (the reverses of its ops, in
+ * reverse op order). Each step is guarded by what the change left: it applies
+ * where the document still shows that, and is skipped, and reported, where it
+ * doesn't. Running a step records the step that reverses it in turn, so the
+ * undo of an undo is a redo.
+ */
+interface ChangeRecord {
+  /** Who made the change: only they may undo it. */
+  readonly userId: string | null;
+  readonly steps: readonly ReverseStep[];
+}
+type ReverseStep = ObjectsRevertStep | AnnotationRemoveStep | AnnotationRestoreStep | AnnotationReorderStep | FieldRemoveStep | FieldRestoreStep | WidgetRestoreStep | WidgetDeleteStep | CalculationOrderStep | MetadataRevertStep;
+/**
+ * One dictionary a change wrote, as it was before (the capture, with the
+ * objects under `deep` the layer held) and as the change left it (a shallow
+ * capture, the guard). `before` is null for a dictionary the change made.
+ */
+interface CapturedObject {
+  readonly objectNumber: number;
+  readonly deep: readonly string[];
+  readonly before: Uint8Array | null;
+  readonly after: Uint8Array;
+}
+/**
+ * Puts back the dictionaries an op wrote, exactly as they were, when each
+ * still reads as the op left it. When one doesn't, someone changed it since:
+ * an annotation update, a field update or a form value write puts back, by
+ * value, only what still shows what the op set (`fallback`); any other op is
+ * skipped.
+ */
+interface ObjectsRevertStep {
+  readonly kind: 'objects.revert';
+  /** What its item reports doing: the op it puts back, or its opposite (a widget's add undoes its removal). */
+  readonly reports: ChangeItemType;
+  readonly objects: readonly CapturedObject[];
+  /** What the item reads back: the annotation, or the form fields. */
+  readonly subject: {
+    readonly annotation: AnnotationRef;
+  } | {
+    readonly fields: readonly number[];
+  };
+  /** Whether the op changed what the annotation shows (its update's `appearance.changed`). */
+  readonly appearanceChanged?: boolean;
+  readonly fallback?: RevertFallback;
+  /** The rights it takes beside its op's: an import's (see {@link StepRights}). */
+  readonly rights?: StepRights;
+}
+/** How a revert puts values back when the dictionaries it wrote changed since. */
+type RevertFallback = {
+  readonly kind: 'annotation';
+  /** The old values of the fields the update changed. */
+  readonly restore: AnnotationPatch<PdfCoordinates>;
+  /** The values the update left in them: a field still holding its value is put back. */
+  readonly left: AnnotationPatch<PdfCoordinates>;
+} | {
+  readonly kind: 'properties';
+  readonly objectNumber: number;
+  /** The old values of the properties a field update changed, as a patch. */
+  readonly restore: FormFieldPatch;
+  /** The values it left in them: a property still holding its value is put back. */
+  readonly left: FormFieldPatch;
+} | {
+  readonly kind: 'value';
+  /** Each field the op wrote: its value before, and the value the op left. */
+  readonly fields: readonly {
+    readonly objectNumber: number;
+    readonly before: FormFieldValue;
+    readonly left: FormFieldValue;
+  }[];
+};
+/**
+ * Deletes what a create, an import or a restore brought back, when nobody
+ * changed it since and deleting it takes nothing else: undoing a create
+ * never deletes someone else's reply.
+ */
+interface AnnotationRemoveStep {
+  readonly kind: 'annotation.remove';
+  readonly ref: AnnotationRef;
+  /** What the delete takes, as the change left it: the annotation first. */
+  readonly left: readonly Annotation<PdfCoordinates>[];
+  /** The rights it takes: an import's (see {@link StepRights}); a delete's when absent. */
+  readonly rights?: StepRights;
+}
+/**
+ * The rights a step takes as a restoring import's undo or redo: what the
+ * import took. For annotations, `doc.annotate.modify` and
+ * `doc.annotate.import` instead of the per-annotation rules: a restoring
+ * import gives annotations other people's `userId`, which a delete's rules
+ * (`annotations:delete:self`) would never let the importer remove. For
+ * forms, `doc.forms.import` beside `doc.forms.modify` or `doc.forms.fill`:
+ * putting back who made or filled a field is restoring attribution too.
+ */
+type StepRights = 'import';
+/**
+ * Brings back what a delete removed: the same objects, at the same numbers and
+ * positions, from the capture taken in the delete's transaction.
+ */
+interface AnnotationRestoreStep {
+  readonly kind: 'annotation.restore';
+  readonly page: PageRef;
+  /** What came back: the annotation first, then what went with it. */
+  readonly members: readonly AnnotationRef[];
+  readonly capture: Uint8Array;
+  /** Annotations the delete unlinked a popup from, put back as they were. */
+  readonly unlinked: readonly CapturedObject[];
+  /** The rights it takes: those of the remove it reverses (see {@link StepRights}). */
+  readonly rights?: StepRights;
+}
+/**
+ * Puts rows of one family on a page back beside the neighbours they had
+ * before a reorder: its reverse, and, the other way round, its redo. A row
+ * runs only when it is still where the reorder left it.
+ */
+interface AnnotationReorderStep {
+  readonly kind: 'annotation.reorder';
+  readonly page: PageRef;
+  readonly family: AnnotationFamily;
+  /** The rows the reorder moved, in the order it was given them. */
+  readonly refs: readonly AnnotationRef[];
+  /** The family's order before the reorder, bottom to top: where the rows go back to. */
+  readonly before: readonly AnnotationRef[];
+  /** The family's order it left. */
+  readonly after: readonly AnnotationRef[];
+}
+/**
+ * Takes back what a change did to the form's calculation order, by field
+ * object number, where nobody changed it since (see `orderBack`): a field it
+ * added leaves, one it took out comes back, one it moved goes back beside
+ * its old neighbour.
+ */
+interface CalculationOrderStep {
+  readonly kind: 'calculations.restore';
+  /** The order before the change. */
+  readonly before: readonly number[];
+  /** The order the change left. */
+  readonly after: readonly number[];
+}
+/**
+ * Brings back a widget a delete removed: onto its page at its place, and into
+ * its field again when it had one. Left alone when the page is gone, the
+ * widget is back already, or its field changed since.
+ */
+interface WidgetRestoreStep {
+  readonly kind: 'widget.restore';
+  readonly page: PageRef;
+  readonly widget: AnnotationRef;
+  /** The widget as it was on its page, out of its field. */
+  readonly capture: Uint8Array;
+  /** The field it was in; `null` for a widget in no field. */
+  readonly fieldObjectNumber: number | null;
+  /** The field's dictionary and the widget's, before and after it left the field. */
+  readonly detached: readonly CapturedObject[];
+}
+/** Deletes a widget a restore brought back, when nobody changed it since: the redo of a delete. */
+interface WidgetDeleteStep {
+  readonly kind: 'widget.delete';
+  readonly widget: AnnotationRef;
+  readonly left: WidgetAnnotation<PdfCoordinates>;
+}
+/** Deletes a field a create or an import made, when nobody changed it since. */
+interface FieldRemoveStep {
+  readonly kind: 'field.remove';
+  readonly objectNumber: number;
+  /** The field as the change left it. */
+  readonly left: FormFieldDTO<PdfCoordinates>;
+  /** The rights it takes beside `doc.forms.modify`: an import's (see {@link StepRights}). */
+  readonly rights?: StepRights;
+}
+/** Brings back a field a delete removed, its widgets and the parents it pruned. */
+interface FieldRestoreStep {
+  readonly kind: 'field.restore';
+  readonly objectNumber: number;
+  /** Its fully qualified name: the restore is skipped when another field took it. */
+  readonly name: string;
+  /** The pages its widgets were on: the restore is skipped when one is gone. */
+  readonly pages: readonly PageRef[];
+  readonly capture: Uint8Array;
+  /** The rights it takes: those of the remove it reverses (see {@link StepRights}). */
+  readonly rights?: StepRights;
+}
+/** Puts metadata back, entry by entry, where an entry still holds what the change set. */
+interface MetadataRevertStep {
+  readonly kind: 'metadata.revert';
+  readonly op: 'metadata.update' | 'metadata.updateCustom';
+  readonly restore: MetadataPatch | CustomMetadataPatch;
+  readonly left: MetadataPatch | CustomMetadataPatch;
+}
+//#endregion
+//#region src/features/changes/ChangeApplier.d.ts
+/** What a change did: one item per op (or per step of an undo), and the record that undoes it. */
+interface AppliedChange {
+  readonly items: ChangeItem<PdfCoordinates>[];
+  /** Its steps are empty when nothing was written: there is nothing to undo. */
+  readonly record: ChangeRecord;
+}
+/**
+ * Runs changes inside the job's layer transaction, which its caller opens and
+ * ends, so a failure anywhere leaves the document as it was: a change's ops in
+ * order (`apply`), or the steps of a recorded reverse (`undo`). Each op and
+ * step is checked against the change's authority as it runs, as its single
+ * verb's job checks it.
  *
- *   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`.
+ * Every op records the steps that reverse it as it runs, from what it found
+ * and wrote; the record lists them in reverse op order, so each step meets the
+ * document as the op after it left it.
+ */
+declare class ChangeApplier {
+  private readonly runtime;
+  private readonly session;
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession, fonts?: FontRegistrar | undefined);
+  apply(ops: readonly RecordedOp<PdfCoordinates, WireAnnotationResources>[], authority: ChangeAuthority, signal: AbortSignal): AppliedChange;
+  undo(record: ChangeRecord, authority: ChangeAuthority, signal: AbortSignal): AppliedChange;
+  private context;
+}
+//#endregion
+//#region src/features/changes/ChangeLedger.d.ts
+/** What one change answered, kept under its `opId`. */
+type ChangeOutcome = {
+  readonly kind: 'applied';
+  readonly fingerprint: string;
+  readonly result: ChangeResult<PdfCoordinates>;
+} | {
+  readonly kind: 'refused';
+  readonly fingerprint: string;
+  readonly error: SerializedEngineError;
+};
+/** Why a change can't be undone (`UndoUnavailable`'s `details.reason`). */
+type UndoUnavailableReason = 'final-change' | 'expired';
+/**
+ * What a local session keeps of its changes: every answer under its `opId`,
+ * refusals included, so a retry gets the same one; and each undoable change's
+ * record, until a final change ends undo for everything before it, or the
+ * capture budget runs out (the oldest go first, as `expired`).
  *
- *   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.
+ * The cloud keeps the same in its database; a cloud worker's session keeps
+ * nothing here between requests.
+ */
+declare class ChangeLedger {
+  private readonly entries;
+  private bytes;
+  /** The answer kept under `opId`, if any. */
+  outcome(opId: string): ChangeOutcome | undefined;
+  /**
+   * The record of the change `opId`, or why it can't be undone. Undefined for
+   * a change this session has no answer for.
+   */
+  record(opId: string): {
+    readonly record: ChangeRecord | null;
+  } | {
+    readonly unavailable: UndoUnavailableReason;
+  } | undefined;
+  /** Keeps an applied change's answer, and its record when it can be undone. */
+  keepApplied(opId: string, fingerprint: string, result: ChangeResult<PdfCoordinates>, record: ChangeRecord | null): void;
+  /** Keeps a refusal: asking again answers it again. */
+  keepRefused(opId: string, fingerprint: string, error: SerializedEngineError): void;
+  /**
+   * A final change (redaction apply, flatten, signing, form repair) ended undo
+   * for itself and every change before it: their records go.
+   */
+  endUndo(): void;
+  private add;
+  private trimCaptures;
+  private drop;
+}
+/** The ledger of `session`'s changes. */
+declare function changeLedgerOf(session: DocumentSession): ChangeLedger;
+//#endregion
+//#region src/features/changes/recordCodec.d.ts
+/**
+ * A change's record as a caller stores it: the steps as JSON, every capture's
+ * bytes moved into one blob and named in the JSON by where they are in it
+ * (`{ "$capture": [offset, length] }`). `capture` is null when the record
+ * holds no bytes.
  */
-declare function computeMutationImpact(inputs: ImpactInputs): AnnotationListMutationMeta;
+interface PackedChangeRecord {
+  readonly reverse: string;
+  readonly capture: Uint8Array | null;
+}
+/** A record, packed for storage (see `PackedChangeRecord`). */
+declare function packChangeRecord(record: ChangeRecordPayload): PackedChangeRecord;
+/** A record unpacked from its JSON and its capture blob. */
+declare function unpackChangeRecord(reverse: string, capture: Uint8Array | null): ChangeRecordPayload;
 //#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).
+ * ref). Pure reads over the session — 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
@@ -1349,11 +1883,12 @@ declare class AttachmentReader {
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
   /** Snapshot of the `/EmbeddedFiles` name tree, in tree (key-sorted) order. */
-  list(signal: AbortSignal): EmbeddedFileItem[];
+  list(signal: AbortSignal): Attachment[];
   /** Decode one document-level embedded file, addressed by key. */
-  readFile(ref: EmbeddedFileRef, path: string | undefined, maxDecodedBytes: number | undefined, signal: AbortSignal): AttachmentFileWorkerPayload;
+  readFile(ref: AttachmentRef, 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;
+  /** A file attachment annotation's file; a page not parsed yet loads in slices. */
+  readAnnotationFile(pageObjectNumber: PageObjectNumber, ref: AnnotationRef, path: string | undefined, maxDecodedBytes: number | undefined, signal: AbortSignal, slices: Slices): Promise<AttachmentFileWorkerPayload>;
   private extract;
 }
 //#endregion
@@ -1364,9 +1899,8 @@ declare class AttachmentReader {
  * 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
+ * Identity is the name-tree key (unique by construction). 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.
  */
@@ -1382,7 +1916,7 @@ declare class AttachmentMutator {
    */
   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;
+  delete(ref: AttachmentRef, signal: AbortSignal): AttachmentDeleteResult;
 }
 //#endregion
 //#region src/features/attachments/internal/attachmentPrimitives.d.ts
@@ -1396,7 +1930,7 @@ declare class AttachmentMutator {
  * vocabulary.
  */
 declare function writeAttachmentFilePayload(fn: PdfFunctions, mem: PdfRuntimeMemory, attachmentPtr: Ptr, docPtr: Ptr, file: {
-  mimeType?: string;
+  mimeType?: string | null;
   description?: string;
 }, resource: WireResource): void;
 /** Read the metadata projection of an embedded file (never its bytes). */
@@ -1418,7 +1952,7 @@ declare class SecurityReader {
   constructor(runtime: PdfRuntimeModule);
   probeFile(path: string, password?: string | null): DocumentSecurityProbeInfo;
   /**
-   * Snapshot of the live session's EFFECTIVE security state.
+   * 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.
@@ -1534,7 +2068,7 @@ declare class DocumentSaver {
    * `saveLayerDelta` that says whether anything reachable changed since the
    * layer was opened; empty bytes when nothing did (keep what you have), or
    * when the layer came to equal its base (then `changedSinceLoad` is true
-   * and the document IS the base).
+   * and the document is the base).
    */
   saveLayerDeltaEx(): {
     bytes: ArrayBuffer;
@@ -1603,10 +2137,7 @@ declare class SignatureReader {
     index: number;
     fieldObjectNumber: number;
     signed: boolean;
-    widget: {
-      annotObjectNumber: number;
-      pageObjectNumber: number;
-    } | null;
+    widget: FormWidget | null;
   };
   /** One signature by field object number, from the current model. */
   readSignatureByObjectNumber(fieldObjectNumber: number): SignatureDTO;
@@ -1631,14 +2162,14 @@ declare class SignatureReader {
 /**
  * The two-phase signing protocol on a session, local and native alike.
  *
- * `prepare` never touches the live document: it builds a CANDIDATE — a
+ * `prepare` never touches the live document: it builds a candidate — a
  * fresh layer over the session's own immutable base (see `openCandidate`)
  * — writes the signature there, saves it through a `CandidateStore`
  * (memory locally, a file beside the base on file-backed sessions), seals
  * it, and parks the saved candidate on the session. `complete` writes the
  * CMS into it, opens it as a new base with a fresh layer, proves the new
  * signature seals a whole revision, and installs it as the session's
- * document. `abort` discards the candidate.
+ * document. `cancel` discards the candidate.
  */
 declare class SignatureMutator {
   private readonly runtime;
@@ -1649,15 +2180,27 @@ declare class SignatureMutator {
   constructor(runtime: PdfRuntimeModule, session: DocumentSession, baseDocuments: BaseDocumentRegistry,
   /** Where a file-backed session's candidate is written; defaults to beside the base file. */
   candidatePath?: ((basePath: string, signingId: string) => string) | undefined);
-  prepare(input: SignaturePrepareInput): SignaturePrepared;
-  complete(input: SignatureCompleteInput): SignatureCompleteResult;
-  abort(signingId: string): SignatureAbortResult;
+  /**
+   * Prepare a signing of `input.field`, which `authority` must be allowed to
+   * sign (its group, `fields:sign`). A field in a group, signed without a
+   * `lock`, locks the rest of its group: nobody changes the buyer's fields
+   * once the buyer signed.
+   */
+  prepare(input: SignaturePrepareInput, authority: ChangeAuthority): SignaturePrepared;
+  /**
+   * `opId` names the write. A signing runs outside a layer transaction (it
+   * replaces the document's bytes), so it takes its id here, and it is final:
+   * never undoable.
+   */
+  /** Complete the pending signing; `authority` must still be allowed to sign its field. */
+  complete(input: SignatureCompleteInput, opId: string, authority: ChangeAuthority): SignatureCompleteResult;
+  cancel(signingId: string): SignatureCancelResult;
   private callPrepare;
   /** Draw a page of `pdf` into the widget's appearance stream on the candidate. */
   /**
    * File-backed sessions (a file base in the registry: the server) persist
    * the candidate as a file beside the base; everything else keeps it in
-   * memory. The choice follows the SESSION's base, not the candidate's.
+   * memory. The choice follows the session's base, not the candidate's.
    */
   private storeFor;
   /**
@@ -1673,7 +2216,7 @@ declare class SignatureMutator {
   private verifySealed;
   /**
    * The candidate the signature is authored on. A layer session reopens a
-   * fresh layer over ITS OWN immutable base (a registry retain, no copy of
+   * fresh layer over its own immutable base (a registry retain, no copy of
    * the file), fed the layer it was opened with — or, with unsaved edits,
    * the artifact a save would write, which is cumulative: the edits and
    * the signature then share one revision, as Acrobat saves a
@@ -1723,14 +2266,14 @@ declare class SignatureAnalyzer {
    * the session's own document is the working copy. `working-copy`: a
    * layer session composes its immutable base with the cumulative delta
    * the pass emits (`EPDFDoc_OpenBaseOverlay`: no copy of the base, one
-   * cross-reference parse, the loaded delta's revision REPLACED, as an
+   * cross-reference parse, the loaded delta's revision replaced, as an
    * artifact is), or — when every edit brought the layer back to its base
    * — a fresh layer over that base; a plain session (unsigned by law 9, so
    * this is exploratory) materialises a standalone incremental save and
    * opens it whole.
    */
   private openWorkingCopy;
-  /** Changed since load, nothing to write: the layer equals its base, and a fresh layer over it IS that document. */
+  /** Changed since load, nothing to write: the layer equals its base, and a fresh layer over it is that document. */
   private freshLayerOverBase;
   /**
    * The fork's exact object diff between two revision documents,
@@ -1763,9 +2306,12 @@ interface FinalizeCandidateInput {
   password: string | null;
 }
 interface FinalizedCandidate {
+  /** In page space: no session outlives the finalize to measure it later. */
   signature: SignatureDTO;
   protection: DocumentProtection;
   version: BaseVersionInfo;
+  /** The sealed file's last object number: every object it has is at or below it. */
+  lastObjectNumber: number;
 }
 /**
  * The session-less half of a durable signing. A server prepares a
@@ -1806,25 +2352,130 @@ declare function readStructure(runtime: PdfRuntimeModule, docPtr: Ptr): Revision
 //#endregion
 //#region src/features/forms/FormReader.d.ts
 /**
- * Read side of the forms feature. All reads go through the session's
+ * Read side of the forms feature. Field reads go through the session's
  * version-keyed model cache, so repeated reads between mutations reuse
- * one native snapshot build.
+ * one native snapshot build; widget rows are read from the pages.
  */
 declare class FormReader {
   private readonly runtime;
   private readonly session;
-  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  snapshot(signal: AbortSignal): FormSnapshot;
-  field(ref: FormFieldRef, signal: AbortSignal): FormFieldDTO;
+  /** This thread's font registry, for the widget rows. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry, for the widget rows. */
+  fonts?: FontRegistrar | undefined);
+  snapshot(signal: AbortSignal): FormSnapshot<PdfCoordinates>;
+  field(ref: FormFieldRef, signal: AbortSignal): FormFieldDTO<PdfCoordinates>;
+}
+//#endregion
+//#region src/features/forms/FormExporter.d.ts
+/**
+ * `doc.forms.export`: the fields a selection takes, each whole with all of
+ * its widgets, as one bundle in page space (see `formExportRowsOf`). It
+ * reads the form as `list()` does and writes nothing. A widget is drawn
+ * from its data, so the bundle holds no resources. It is checked against
+ * `limits` as it is built, so an export never makes one an import refuses.
+ */
+declare class FormExporter {
+  private readonly runtime;
+  private readonly session;
+  /** This thread's font registry, for the widget rows. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry, for the widget rows. */
+  fonts?: FontRegistrar | undefined);
+  export(selection: FormExportSelection, limits: BundleLimits, signal: AbortSignal): WireFormBundle;
+}
+//#endregion
+//#region src/features/forms/FormImporter.d.ts
+interface FormImportRequest {
+  /** In page space, as bundles are: each widget is measured on the page it goes to. */
+  readonly bundle: WireFormBundle;
+  readonly pages?: BundleImportPages;
+  readonly attribution: 'restore' | 'stamp';
+  /** Whether each field gets the value the bundle holds. */
+  readonly values: boolean;
+  /**
+   * The session's identity: whom `'stamp'` makes each field's creator and
+   * filler, and whose user `'restore'` records as `importedBy`.
+   */
+  readonly actor: AnnotationActor;
+  readonly limits: BundleLimits;
+  /** Whether scripts, submits and links are kept (`doc.forms.script`); without it they're left out. */
+  readonly mayScript: boolean;
+  /**
+   * The group a field goes in, given the one it had in the bundle (if any):
+   * checked by the caller, which refuses one it may not set.
+   */
+  readonly groupOf: (groupId: string | undefined) => string | undefined;
+}
+/** What a values import writes, decided before the first write. */
+interface FormValuesImportPlan {
+  /** Each against the field as it is now; a write that changes nothing isn't among them. */
+  readonly writes: readonly PlannedValueWrite<FormFieldDTO<PdfCoordinates>>[];
+  readonly dropped: readonly FormValuesImportDrop[];
+}
+/**
+ * `doc.forms.import` and `doc.forms.importValues`: a bundle's fields, copied
+ * into this document or filled in from it. The bundle is checked first: its
+ * shape, counts and sizes against the limits, and each resource against its
+ * id. Then the core plans (`planFormImport`, `planFormValuesImport`), so all
+ * that is left out is decided before the first write, and the writes go
+ * through the form's own: `createField` and `setValue`.
+ */
+declare class FormImporter {
+  private readonly runtime;
+  private readonly session;
+  /** This thread's font registry, for the widget rows. */
+  private readonly fonts?;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession,
+  /** This thread's font registry, for the widget rows. */
+  fonts?: FontRegistrar | undefined);
   /**
-   * 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;
-  };
+   * The design: each field `planFormImport` keeps, created with its widgets on
+   * their mapped pages, their flags, and, with `values`, the value the
+   * bundle holds; then the calculation order among them, appended to the
+   * form's in bundle order; then who made and filled each, restored or
+   * stamped.
+   */
+  import(request: FormImportRequest, signal: AbortSignal): FormImportResult<PdfCoordinates>;
+  /**
+   * What a values import of `bundle` writes, nothing written yet: each
+   * field the bundle holds a value for, matched by full name, when it can
+   * take the value (`fieldValueWriteOf`) and no signature locked it. A field
+   * stored as a direct object can't be written, so it can't take the value
+   * either.
+   */
+  planValues(bundle: WireFormBundle, limits: BundleLimits, signal: AbortSignal,
+  /** Whether the session may fill the field in; one it may not is left out. */
+  mayFill: (field: FormFieldDTO<PdfCoordinates>) => boolean): FormValuesImportPlan;
+  /**
+   * One write of a values import: the value, then, for `'restore'`, who
+   * filled it in as the bundle has it. `'stamp'` leaves the session as the
+   * filler, as `setValue` stamps it.
+   */
+  writeValue(write: PlannedValueWrite<FormFieldDTO<PdfCoordinates>>, bundle: WireFormBundle, attribution: 'restore' | 'stamp', actor: AnnotationActor, signal: AbortSignal): FormFieldDTO<PdfCoordinates>;
+  /** A new widget's flags, as its row in the bundle has them: a create writes none. */
+  private writeFlags;
+  /** The full name of every field of the form. */
+  private fieldNames;
+  /** Every field of the form, as it is now. */
+  private readFields;
+  private readField;
+  private calculationOrder;
+}
+//#endregion
+//#region src/features/forms/internal/calculationOrder.d.ts
+/**
+ * The form's calculation order (`/AcroForm /CO`): the fields whose calculate
+ * scripts run, in the order they run, by object number. A field's calculate
+ * script keeps it in the order; the order is a list like a page's
+ * annotations, moved by neighbour.
+ */
+/** The calculation order before a write and as the write left it. */
+interface OrderChange {
+  readonly before: readonly number[];
+  readonly after: readonly number[];
 }
 //#endregion
 //#region src/features/forms/FormMutator.d.ts
@@ -1834,91 +2485,160 @@ declare class FormReader {
  * the document untouched (on layers: nothing promoted), and each success
  * bumps the session's mutation sequence so version-keyed caches rebuild.
  */
+/**
+ * A form write's result as the mutator gives it: the fields, without the
+ * widget rows, which the change that ran it reads (`withWidgetRows`).
+ */
+type FieldWriteResult<T> = Omit<T, 'widgets'>;
 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).
+   * Set a field's value, as `actor` filled it in: what engine-core's rules
+   * (`fieldAfterValue`) leave the field holding. A write that changes the
+   * field names who filled it in; one that leaves it as it was writes
+   * nothing.
+   */
+  setValue(ref: FormFieldRef, value: FormFieldValue, signal: AbortSignal, actor: AnnotationActor): FieldWriteResult<FormSetValueResult<PdfCoordinates>>;
+  /**
+   * Show, hide or keep from printing every widget of a field, as a script's
+   * `Field.display` does: only the four flags it names change.
+   */
+  setDisplay(ref: FormFieldRef, display: FormFieldDisplay, signal: AbortSignal): FieldWriteResult<FormSetValueResult<PdfCoordinates>>;
+  /**
+   * Draw a text field's or dropdown's widgets with `text` (a format script's
+   * result) without changing its value.
+   */
+  setAppearanceText(ref: FormFieldRef, text: string, signal: AbortSignal): FieldWriteResult<FormSetValueResult<PdfCoordinates>>;
+  /**
+   * The meta of a value write that changed no page list: the cloud layer
+   * computes its own cache delta server-side.
+   */
+  private emptyMeta;
+  /**
+   * Put fields back to their default value: the ones named, or, with
+   * `refs` absent, every field of the form. Fields that hold no value are
+   * skipped; so, in a whole-form reset, are fields stored inline or locked
+   * by a signature (named, they are refused). Every field is checked before
+   * the first write. Returns the fields that changed.
    */
-  createField(draft: FormFieldDraft, signal: AbortSignal): {
-    field: FormFieldDTO;
+  reset(refs: FormFieldRef[] | undefined, signal: AbortSignal): FieldWriteResult<FormResetResult<PdfCoordinates>>;
+  /** Every field a whole-form reset puts back: those with a value, written directly, unlocked. */
+  private wholeFormTargets;
+  /** The named fields with a value, each once; one that can't be written is refused. */
+  private namedTargets;
+  repair(bakeAppearances: boolean, signal: AbortSignal): FormRepairResult;
+  /**
+   * Create a field and (optionally) its widgets as one change: native
+   * field creation, widget birth through the annotation plane, adoption,
+   * then field-plane setters, stamped as `actor` created it. Everything a
+   * caller can get wrong is checked before the first write; any failure
+   * after it aborts the job's layer transaction, so a rejected draft creates
+   * nothing.
+   */
+  createField(draft: FormFieldDraft<PdfCoordinates>, signal: AbortSignal, actor: AnnotationActor, numbers?: {
+    /** The field's object number; the next free one when absent. */
+    readonly objectNumber?: number;
+    /** Its widgets', in `draft.widgets` order; the next free ones when absent. */
+    readonly widgetObjectNumbers?: readonly number[];
+  }): {
+    field: FormFieldDTO<PdfCoordinates>;
+    calculationOrder: OrderChange | null;
   };
+  /** EPDFForm_DeleteField: unlink the field and detach its kid widgets. */
+  private nativeDeleteField;
+  /** Check a widget placement before anything is written; returns its page index. */
+  private preflightPlacement;
   /**
-   * Draw a PDF page into every widget of an UNSIGNED signature field: the
+   * The native field node, linked into the tree, at `objectNumber` (checked
+   * by the session) or the next free number.
+   */
+  private createFieldNode;
+  /** The draft's field-plane settings, on a field just created. */
+  private configureNewField;
+  /**
+   * Draw a PDF page into every widget of an unsigned signature field: the
    * visual "sign" of a viewer without a signer. The field's value stays
    * empty and nothing is sealed; a signed field is refused (its appearance
-   * is part of what the signature covers). Pages whose widgets changed are
-   * reported so their renders re-pin.
+   * is part of what the signature covers).
    */
-  setSignatureAppearance(ref: FormFieldRef, pdf: Uint8Array, pageIndex: number, signal: AbortSignal): {
-    field: FormFieldDTO;
-    pages: PageObjectNumber[];
+  setSignatureAppearance(ref: FormFieldRef, pdf: Uint8Array, signal: AbortSignal): {
+    field: FormFieldDTO<PdfCoordinates>;
   };
   updateField(ref: FormFieldRef, patch: FormFieldPatch, signal: AbortSignal): {
-    field: FormFieldDTO;
+    field: FormFieldDTO<PdfCoordinates>;
+    calculationOrder: OrderChange | null;
   };
   /**
-   * 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.
+   * Move fields in the calculation order: they go together, in the order
+   * given, to `position`. Every field named must be in the order.
+   */
+  reorderCalculations(fields: readonly FormFieldRef[], position: FieldPosition, signal: AbortSignal): OrderChange & {
+    moved: number[];
+  };
+  /**
+   * Keep the calculation order in step with a field's calculate script, as
+   * a write left it: a script puts the field at the end when it isn't in the
+   * order, removing the script takes the field out. Returns the order before
+   * and after, when it changed.
+   */
+  private followCalculateScript;
+  /**
+   * Delete a terminal field and its widgets in one mutation. The native
+   * write detaches kid widgets and unlinks the field from /Fields or its
+   * parent's /Kids; the cascade then removes every placed widget from its
+   * page through the annotation feature, which owns /Annots bookkeeping. A
+   * merged field/widget has no
+   * kid to detach: its own dictionary leaves its page in the same cascade.
    */
   deleteField(ref: FormFieldRef, signal: AbortSignal): {
-    deletedFieldObjectNumber: number;
-    detachedWidgets: FormWidgetRef[];
+    deleted: FormFieldRef;
+    removedWidgets: FormWidget[];
+    calculationOrder: OrderChange | null;
   };
-  attachWidget(ref: FormFieldRef, widget: FormWidgetRef, onState: string | undefined, signal: AbortSignal): {
-    field: FormFieldDTO;
+  /**
+   * Show a field in one more place: create the widget where the placement
+   * says, styled by it, and add it to the field, as one change. A failure
+   * after the first write rolls the page and the form back.
+   */
+  addWidget(ref: FormFieldRef, placement: WidgetPlacement<PdfCoordinates>, signal: AbortSignal, numbers?: {
+    /** The new widget's object number; the next free one when absent. */
+    readonly objectNumber?: number;
+    /** Where a merged field's widget moves; the next free one when absent. */
+    readonly splitObjectNumber?: number;
+  }): {
+    field: FormFieldDTO<PdfCoordinates>;
+    widget: FormWidget;
   };
-  detachWidget(ref: FormFieldRef, widget: FormWidgetRef, signal: AbortSignal): {
-    field: FormFieldDTO;
+  detachWidget(ref: FormFieldRef, widget: AnnotationRef, signal: AbortSignal): {
+    field: FormFieldDTO<PdfCoordinates>;
+    widget: FormWidget;
   };
-  private placementsOf;
   private applyOptions;
   private applyWideSetter;
-  private applyDefaultValues;
+  /** Write a field's default (`/DV`) when it changes. */
+  private writeDefault;
   private readBackField;
   private assertWritable;
+  /** A field an earlier signature locked refuses every write (see `readFieldLocks`). */
+  private assertNotLockedBySignature;
+  /** Run the native value write. Returns the changed widget objnums. */
   /**
-   * A field an earlier signature froze (its FieldMDP, or the /Lock of a
-   * signed field) refuses every write: document-derived authority, the
-   * same way encryption bits are. Off under `signedDocumentPolicy:
-   * 'permit'`. A document whose signature model cannot be built is not
-   * known to be locked.
+   * Write what `after` holds that `before` doesn't, as engine-core worked it
+   * out: `/V`; a checkbox's or radio group's widgets on or off; a choice
+   * field's selected options (`/I`); and a text or choice field's new
+   * pictures (also with `redraw`, for new options). Returns the widgets whose
+   * pictures changed, or `null` when the field already held it all and
+   * nothing was written.
    */
-  private assertNotLockedBySignature;
-  /** Dispatch the typed native write. Returns the changed widget objnums. */
-  private applyWrite;
+  private writeFieldAfter;
   /** 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;
@@ -1929,26 +2649,26 @@ declare function disposeFormModel(runtime: PdfRuntimeModule, session: DocumentSe
  * 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
+ *             `cacheSeq`, 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
+ * Scope gating (`doc.text.search`, `doc.text.copy` for snippets) 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;
+  query(request: SearchScanRequest, signal: AbortSignal, slices: Slices): Promise<SearchSlice<PdfCoordinates>>;
 }
 //#endregion
 //#region src/features/actions/ActionModelReader.d.ts
 /** Mutable aggregate budget shared by every action model in one read job.
- *  Payload budgets are RESERVED before the backing buffer is allocated. */
+ *  Payload budgets are reserved before the backing buffer is allocated. */
 declare class ActionReadBudgetTracker {
   private readonly limits;
   private models;
@@ -1959,9 +2679,9 @@ declare class ActionReadBudgetTracker {
   constructor(limits?: ActionReadBudget);
   addModel(nodeCount: number): void;
   addScript(script: string): void;
-  /** Charge target entries BEFORE the target array is walked. */
+  /** Charge target entries before the target array is walked. */
   reserveTargets(count: number): void;
-  /** Charge payload text BEFORE the scratch buffer for it is allocated. */
+  /** Charge payload text before the scratch buffer for it is allocated. */
   reservePayloadBytes(length: number): void;
   private assertWithinBudget;
 }
@@ -1978,7 +2698,7 @@ declare class ActionReadBudgetTracker {
  * `subtype`, and the tree gains the `'payload-dropped'` warning — impossible
  * states stay unrepresentable while malformed documents stay readable.
  */
-declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, docPtr: Ptr, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree | null;
+declare function readActionModel(fn: PdfFunctions, mem: PdfRuntimeMemory, docPtr: Ptr, modelPtr: Ptr, budget: ActionReadBudgetTracker): PdfActionTree<PdfDestination> | null;
 //#endregion
 //#region src/features/actions/DocumentActionsReader.d.ts
 /** Read catalog-owned actions. Extraction only; no action is executed. */
@@ -1986,11 +2706,11 @@ declare class DocumentActionsReader {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  read(signal: AbortSignal): DocumentActionsSnapshot;
+  read(signal: AbortSignal): DocumentActionsSnapshot<PdfDestination>;
 }
 //#endregion
 //#region src/worker-host/WorkerHost.d.ts
-/** The image a {@link WorkerImageEncoder} produced. `bytes` must OWN its
+/** The image a {@link WorkerImageEncoder} produced. `bytes` must own its
  *  buffer (a fresh allocation, not a pooled `Buffer` slab view) — it is
  *  placed on the transfer manifest and moved zero-copy. */
 interface WorkerEncodedImage {
@@ -1999,7 +2719,7 @@ interface WorkerEncodedImage {
 }
 /**
  * Injected image-encode capability for the `*.renderEncoded` wire kinds.
- * Dependency inversion keeps the native encoder OUT of this shared
+ * Dependency inversion keeps the native encoder out of this shared
  * package: the cloud server's worker entry injects a sharp/libvips
  * implementation; browser/local entries inject nothing (they encode via
  * canvas) and the encoded kinds reject with `NotImplemented`.
@@ -2019,6 +2739,23 @@ interface WorkerHostOptions {
    * the sealed file can be published by rename.
    */
   signingCandidatePath?: (basePath: string, signingId: string) => string;
+  /**
+   * Bytes of decoded images kept between jobs that write nothing (see
+   * {@link DecodedImageStore}). Defaults to 128 MB; 0 keeps none.
+   */
+  decodedImageBudgetBytes?: number;
+  /**
+   * Bytes of parsed pages kept between jobs, for every document on this
+   * thread (see {@link PageResidency}). Defaults to
+   * {@link DEFAULT_PAGE_RESIDENCY_POLICY}'s; 0 keeps none.
+   */
+  parsedPageBudgetBytes?: number;
+  /**
+   * Milliseconds a job's PDFium work runs (a page render, a page load, a loop
+   * over glyphs or annotations) before it lets this thread receive messages,
+   * so an abort stops it about this soon. Defaults to {@link DEFAULT_SLICE_MS}.
+   */
+  sliceMs?: number;
 }
 /**
  * The piece that runs "inside the worker": owns runtime, manages document
@@ -2054,6 +2791,21 @@ declare class WorkerHost {
    */
   private readonly fontIds;
   private readonly fonts;
+  /** Parsed pages kept between jobs, for every session on this runtime. */
+  private readonly residency;
+  /** Image decodes kept between jobs that write nothing, for every session on this runtime. */
+  private readonly decodedImages;
+  private readonly slices;
+  /**
+   * True while a job's PDFium work is in progress across slices (a render, a
+   * page load, a glyph loop). It pauses between slices so this thread can
+   * receive an abort, but nothing else may use PDFium meanwhile (a render
+   * holds its page until it ends): requests that arrive are held (see
+   * {@link receive}).
+   */
+  private busy;
+  /** Requests that arrived while a job was busy, in arrival order (see {@link takeHeld}). */
+  private readonly held;
   private destroyed;
   constructor(runtime: PdfRuntimeModule,
   /**
@@ -2076,20 +2828,47 @@ declare class WorkerHost {
    */
   registerStartupFonts(specs: readonly StartupFontSpec[]): void;
   receive(msg: WorkerRequest): void;
+  /** What a view shows of a document: the order its kept pages close in. Never answered. */
+  private setWorkingSet;
+  /** Stops a running job, or answers a held one as aborted without running it. */
+  private abort;
+  /** Runs held requests until one is busy across slices. */
+  private drain;
+  /**
+   * The next held request. Requests run in arrival order, except that of page
+   * renders held one after another, a render whose page is parsed runs before
+   * one that must parse it. A render never passes another kind of request, nor
+   * the other way round.
+   */
+  private takeHeld;
+  /** Whether the render's page is kept, so the render parses nothing. */
+  private pageIsKept;
+  private run;
+  /**
+   * The session a job writes to, when it runs as a transaction: a write to an
+   * open, usable layer document. Anything else (no such session, a locked
+   * one) gets its handler's own error.
+   */
+  private transactedSession;
+  /** Closes the pages a job of this effect may change, as no job holds them. */
+  private closePagesChangedBy;
+  /**
+   * Answers a job with its result in page space. The handler decided which
+   * buffers to move; the host relays that decision on the `resolve` envelope.
+   */
+  private resolve;
+  /** The visible boxes of the request's document, read only when a result asks for one. */
+  private visibleBoxesFor;
   private handleOpen;
   /**
-   * Open plain bytes into `session` in the shape it asked for. The default,
-   * `layer`, makes the bytes an immutable base with a fresh layer on top:
-   * reads fall through to the base, a write promotes only what it touches,
-   * a save appends exactly that, and a signature keeps its validity across
-   * later edits because the signature dictionary is never rewritten. The
-   * `plain` shape keeps one in-memory document — unless the bytes already
-   * carry a signature value, which always opens as a layer, because a plain
-   * save rewrites every loaded object into the new revision and strict
-   * validators reject that. Auto-layered sessions serialize no artifact per
-   * mutation: the caller never asked for one.
+   * Open bytes into `session` as an immutable base with a fresh layer on top:
+   * reads fall through to the base, a write promotes only what it touches and
+   * runs as a layer transaction, a save appends exactly that, and a signature
+   * keeps its validity across later edits because the signature dictionary is
+   * never rewritten. The session serializes no artifact per mutation: the
+   * caller holds the document, not a layer.
    */
-  private openSignedAware;
+  private openBytesAsLayer;
   /**
    * What the document's signatures forbid, read at open and after an
    * unlock so the main-thread guard can subtract capabilities before the
@@ -2112,28 +2891,66 @@ declare class WorkerHost {
    * session that is never stored in `this.sessions`.
    */
   private handleSignaturesFinalizeCandidate;
-  private handleSignaturesAbort;
+  private handleSignaturesCancel;
   /**
-   * The dispatch fence for a parked signing candidate. Only mutating kinds
-   * are refused; a request for a session that is not open falls through
-   * to its handler's own `DocNotOpen`.
+   * The dispatch fence for a parked signing candidate. Only writes are
+   * refused, except the signing's own completion; a request for a session
+   * that is not open falls through to its handler's own `DocNotOpen`.
    */
   private assertNoPendingSigning;
   private handleMetadataRead;
   private handleMetadataUpdate;
+  private handleMetadataReadCustom;
+  private handleMetadataUpdateCustom;
   private handleActionsRead;
-  private handleAnnotationsListRawAll;
-  private handleAnnotationsListRawPage;
-  private handleAnnotationsListFullPage;
+  private handleAnnotationsList;
   private handleAnnotationsRenderAppearances;
   private handleAnnotationsCreate;
   private handleAnnotationsUpdate;
   private handleAnnotationsDelete;
   private handleAnnotationsFlatten;
   private handleAnnotationsExportAppearance;
-  private handleAnnotationsMove;
+  private handleAnnotationsExport;
+  /**
+   * An import, as a one-op change: kept under its `opId` with the record
+   * that undoes it, and a retry under it gets the first answer.
+   */
+  private handleAnnotationsImport;
+  private handleAnnotationsReadAppearance;
+  private handleAnnotationsReorder;
+  /**
+   * `doc.apply`: one change, in the job's transaction. A change asked again
+   * under its `opId` answers what it answered the first time, refusals
+   * included, and a different change under it is refused. An undo runs the
+   * record its change left, when the same user asks and nothing ended undo
+   * since.
+   */
+  private handleDocumentApply;
+  /**
+   * A single verb as a one-op change: the same op, checks and record as
+   * `doc.apply`, so its `opId` undoes it, and a retry under it gets the first
+   * answer. What the handle may do was checked before the job; `authority`
+   * carries who the write acts for, and what it checks per annotation.
+   */
+  private applyOne;
+  /** A change's answer the first time, kept under its `opId`; a retry's checks. */
+  private replayed;
+  /**
+   * Runs a change and keeps its answer under `opId`: the result and the record
+   * that undoes it, or a refusal the change keeps (see `isKeptRefusal`).
+   */
+  private recorded;
+  /**
+   * A server request's changes (`POST …/changes`) as one job: each in its own
+   * transaction, committed or rolled back on its own, its record handed back
+   * for the server to keep. An undo of an earlier change of the same request
+   * runs the record this job kept for it. One artifact for all that applied.
+   */
+  private handleDocumentApplyChanges;
+  /** A change's ops, or the steps of the record an undo names. */
+  private runChange;
   private handlePagesList;
-  private handlePagesMove;
+  private handlePagesReorder;
   private handlePagesRotate;
   private handlePagesDelete;
   private handlePagesSetName;
@@ -2148,26 +2965,47 @@ declare class WorkerHost {
   private handleAttachmentsCreate;
   private handleAttachmentsDelete;
   private handleAnnotationsReadFile;
+  private handleMeasureViewports;
+  private handleMeasureSetScale;
   private handlePieceInfoRead;
   private handlePieceInfoUpdate;
   private handlePieceInfoApplications;
-  private handlePieceInfoClear;
+  private handlePieceInfoDelete;
   private handlePagesText;
   private handlePagesGeometry;
   private handleSearchQuery;
   private handlePagesRender;
-  private receiveEncoded;
+  /**
+   * The work of a job that pauses between slices, or null for one that runs in
+   * one go: renders, and the reads that load a page (its text, geometry,
+   * annotation appearances, measurement viewports, an annotation's file) or
+   * many (a search). Writes never pause: a read must never see half of one.
+   */
+  private slicedWork;
+  /**
+   * A job that pauses between slices of its PDFium work, so this thread can
+   * receive an abort meanwhile. Until that work ends (`busy`), requests are
+   * held. An encoded kind then encodes while other requests run.
+   */
+  private runSliced;
   private encodeRaster;
-  private handlePagesRenderEncoded;
-  private handleDocumentRenderPageFileEncoded;
-  private handleAnnotationsRenderAppearancesEncoded;
+  /** The encoded reply of a page render's raw one. */
+  private encodeRendered;
+  /** The encoded reply of an appearance render's raw one, its rasters encoded one by one. */
+  private encodeAppearances;
+  /**
+   * A rewrite drops every revision, and with them every signature: a signed
+   * document refuses it unless the session permits breaking signatures
+   * (`signedDocumentPolicy: 'permit'`). One rule for both engines.
+   */
+  private assertRewriteKeepsSignatures;
   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
+   * 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
@@ -2183,7 +3021,7 @@ declare class WorkerHost {
   private handleFontsClearFallbacks;
   private handleFontsClear;
   /**
-   * Close exactly ONE layer session — the reload seam for layer-session
+   * 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,
@@ -2205,19 +3043,28 @@ declare class WorkerHost {
   private handleFormsList;
   private handleFormsSetValue;
   private handleFormsReset;
-  private handleFormsApplyEffects;
   private handleFormsExport;
+  /**
+   * A design import, as a one-op change: kept under its `opId` with the
+   * record that undoes it, and a retry under it gets the first answer.
+   */
   private handleFormsImport;
+  /** A values import, as a one-op change (see {@link handleFormsImport}). */
+  private handleFormsImportValues;
   private handleFormsRepair;
   private handleFormsCreateField;
   private handleFormsUpdateField;
   private handleFormsSetSignatureAppearance;
   private handleFormsDeleteField;
-  private handleFormsAttachWidget;
+  private handleFormsAddWidget;
   private handleFormsDetachWidget;
+  private handleFormsUpdateWidget;
+  private handleFormsDeleteWidget;
+  private handleFormsReorderCalculations;
+  private handleFormsReorderWidgets;
   private finishMutation;
   private saveLayerArtifact;
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationFlattener, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CandidateFinalizer, CloseStack, DIGEST_CODE, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, 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, type RawGeometryGlyphRecord, RedactionApplier, type RevisionAuthority, SearchReader, SecurityReader, SessionEventPublisher, SignatureAnalyzer, SignatureMutator, SignatureReader, type StartupFontSpec, type WorkerEncodedImage, WorkerHost, type WorkerHostOptions, type WorkerImageEncoder, acquireSignatureModel, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, disposeSignatureModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, hasSignedSignature, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, readRevisions, readSignaturesFromModel, readStructure, throwIfAborted, writeAttachmentFilePayload };
+export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationBatchApplier, AnnotationExporter, AnnotationFlattener, AnnotationImporter, AnnotationMutator, AnnotationReader, type AppliedChange, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, type BatchCreate, type BatchCreateResult, CandidateFinalizer, ChangeApplier, ChangeLedger, type ChangeOutcome, type ChangeRecord, CloseStack, DIGEST_CODE, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, FontRegistrar, FormExporter, FormImporter, FormMutator, FormReader, type LayerSource, MetadataMutator, MetadataReader, type OpenedPdfDocument, type OpenedPdfDocumentKind, type PackedChangeRecord, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, type PageRecord, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, type RawGeometryGlyphRecord, RedactionApplier, type ReverseStep, SearchReader, SecurityReader, SignatureAnalyzer, SignatureMutator, SignatureReader, type StartupFontSpec, type UndoUnavailableReason, type WorkerEncodedImage, WorkerHost, type WorkerHostOptions, type WorkerImageEncoder, acquireSignatureModel, buildRunsFromRawGlyphs, changeLedgerOf, destroyLibrary, disposeFormModel, disposeSignatureModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, hasSignedSignature, normalizeU32, openFatMemoryDocument, openLayerDocument, packChangeRecord, pdfDateToIso, readActionModel, readAttachmentFileInfo, readRevisions, readSignaturesFromModel, readStructure, throwIfAborted, unpackChangeRecord, visibleBoxReader, writeAttachmentFilePayload };
 //# sourceMappingURL=index.d.ts.map