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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionReadBudget, AnnotationActor, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationFlattenResult, AnnotationListMutationMeta, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationMutationKind, AnnotationRef, AnnotationStableId, AnnotationUpdateResult, AttachmentCreateResult, AttachmentDeleteResult, AttachmentFileInfo, AttachmentFileWorkerPayload, DocumentActionsSnapshot, DocumentEvent, DocumentEventInit, DocumentEventStream, DocumentMetadata, DocumentSecurityProbeInfo, EmbeddedFileItem, EmbeddedFileRef, FormDataFormat, FormEffect, FormEffectsResult, FormFieldDTO, FormFieldDraft, FormFieldPatch, FormFieldRef, FormFieldValue, FormImportResult, FormRepairResult, FormSetValueResult, FormSnapshot, FormWidgetRef, MetadataPatch, MetadataUpdateResult, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryRun, PageGeometrySnapshot, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNameInput, PageNameResult, PageNetworkRenderFormat, PageObjectNumber, PageRaster, PageRemoveNameInput, PageRenderOptions, PageRotateResult, PageRotation, PageState, PageTextSnapshot, PdfActionTree, PdfQuad, PdfRect, PdfSaveMode, RedactionApplyResult, RedactionApplyScope, RevisionToken, SearchRequest, SearchSlice, WeakAnnotationState, WireAnnotationDraft, WireAnnotationPatch, WireAttachmentFile, WirePack, WireResource, WireResourceMap, WorkerRequest, WorkerResponse } from "@embedpdf/engine-core/runtime";
+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 { PdfFunctions, PdfRuntimeMemory, PdfRuntimeModule, Ptr } from "@embedpdf/engine-runtime";
 //#region src/runtime/lifecycle/bootstrap.d.ts
 /**
@@ -146,13 +146,38 @@ declare class SessionEventPublisher {
 //#endregion
 //#region src/document-session/lifecycle/PdfDocumentOpener.d.ts
 type OpenedPdfDocumentKind = 'fat-memory' | 'layer';
+/**
+ * Where a session's bytes come from, retained for the session's lifetime
+ * so that every consumer (signing candidates, overlays, verbatim reads)
+ * shares one interpretation: an immutable base in the registry (by key;
+ * file bases also carry their path) and the layer the session was opened
+ * with. A plain session has neither. Byte-backed layer sources keep their
+ * bytes: they are what a candidate reopens over the same base.
+ */
+type BaseSource = {
+  readonly kind: 'memory';
+  readonly key: string;
+} | {
+  readonly kind: 'file';
+  readonly key: string;
+  readonly path: string;
+};
+interface DocumentSource {
+  readonly base: BaseSource | null;
+  readonly layer: LayerSource | null;
+  readonly password: string | null;
+}
 interface OpenedPdfDocument {
   readonly kind: OpenedPdfDocumentKind;
   readonly docPtr: Ptr;
+  readonly source: DocumentSource;
   close(): void;
 }
 interface AcquiredBaseDocument {
   readonly key: string;
+  readonly kind: 'memory' | 'file';
+  /** File bases only. */
+  readonly path?: string;
   readonly basePtr: Ptr;
   release(): void;
 }
@@ -238,11 +263,49 @@ interface PageRecord {
  * this exactly the same way; the only thing that differs is the
  * underlying PdfRuntimeModule (WASM vs native).
  */
+/**
+ * A serialised signing candidate: the sealed-to-be file with the
+ * zero-filled /Contents hole, either as one buffer in JS memory (the local
+ * engine) or as a file beside the session's base (the server), plus where
+ * the signature value object lies in it.
+ */
+type SavedCandidate = {
+  kind: 'memory';
+  bytes: Uint8Array;
+  size: number;
+  objectOffset: number;
+  objectLength: number;
+} | {
+  kind: 'file';
+  path: string;
+  size: number;
+  objectOffset: number;
+  objectLength: number;
+};
+/**
+ * A sealed-to-be candidate parked on a session between `prepare` and
+ * `complete`/`abort`. The native candidate documents are closed as soon as
+ * the seal is computed; only the serialised candidate remains.
+ */
+interface PendingSigning {
+  readonly prepared: SignaturePrepared;
+  readonly fieldObjectNumber: number;
+  readonly saved: SavedCandidate;
+  readonly contentsOffset: number;
+  readonly contentsHexLength: number;
+}
+/** What a completed signing left behind, for idempotent replays. */
+interface SigningCompletion {
+  readonly signingId: string;
+  readonly cms: Uint8Array;
+  readonly result: SignatureCompleteResult;
+}
 declare class DocumentSession {
   private readonly runtime;
   private docPtr;
   private closeDocument;
   private _kind;
+  private _source;
   private readonly _sessionId;
   /** pon -> record */
   private readonly recordsByObjectNumber;
@@ -252,12 +315,70 @@ declare class DocumentSession {
   private revisions;
   private mutationSeqCounter;
   private pages;
+  /**
+   * 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.
+   */
+  persistLayerArtifact: boolean;
+  /** The mutation 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;
+  /** The signing candidate parked by `signatures.prepare`, if any. */
+  pendingSigning: PendingSigning | null;
+  /** The last completed signing, so a replayed `complete` answers `already-completed`. */
+  lastCompletion: SigningCompletion | null;
   constructor(runtime: PdfRuntimeModule, sessionId?: string);
   get sessionId(): string;
   get kind(): OpenedPdfDocumentKind | null;
+  /**
+   * Where the current bytes come from: the immutable base (registry key,
+   * file path for file bases) and the layer the session was opened with.
+   * One interpretation for signing candidates, overlays and verbatim reads.
+   */
+  get source(): DocumentSource;
   isOpen(): boolean;
   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
+   * and a signing candidate is built straight on them.
+   */
+  hasUnsavedEdits(): boolean;
+  /** Cached hash of the current loaded bytes, or `null` when not computed since the last load. */
+  cachedPlainSha256(): string | null;
+  rememberPlainSha256(sha256: string): void;
+  /**
+   * Re-point this session at new bytes — the one operation that changes
+   * what an open session is backed by, used when a completed signature
+   * 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.
+   */
+  install(handle: OpenedPdfDocument): void;
+  /** The two publish fences a candidate is built on. */
+  versionRef(baseSha256: string): DocumentVersionRef;
   /**
    * Park this session in the password-locked state: the document could not
    * be loaded because a (correct) password is missing, so the session keeps
@@ -340,12 +461,29 @@ declare class BaseDocumentRegistry {
     key: string;
     bytes: Uint8Array;
     password?: string | null;
+    /** A verified SHA-256 (hex) of `bytes`; spares the runtime a full hashing pass. */
+    knownSha256?: string;
   }): AcquiredBaseDocument;
   acquireFileBase(opts: {
     key: string;
     path: string;
     password?: string | null;
+    /** A verified SHA-256 (hex) of the file; spares the runtime a full hashing pass. */
+    knownSha256?: string;
   }): AcquiredBaseDocument;
+  /**
+   * One more retain on a base already in the registry (a session holds one
+   * for its lifetime, so its key is live while it is open), or null. The
+   * way a signing candidate reopens over its session's own base without
+   * copying a byte.
+   */
+  retainByKey(key: string): AcquiredBaseDocument | null;
+  /**
+   * Hand the runtime a hash the host already verified for these exact
+   * bytes, so it never hashes them itself. Malformed values are ignored:
+   * the runtime then hashes lazily on first use, which is always correct.
+   */
+  private supplyKnownSha;
   releaseAll(): void;
   /** @internal Test-only probe of the per-key share refcount. */
   getRefCountForTesting(key: string): number;
@@ -777,67 +915,6 @@ declare class PageRenderReader {
   render(pageObjectNumber: PageObjectNumber, options: PageRenderOptions, signal: AbortSignal): import("@embedpdf/engine-core/runtime").PageRaster;
 }
 //#endregion
-//#region src/features/annotations/AnnotationReader.d.ts
-/**
- * Per-page slow-path reader. Acquires a `pagePtr` from the
- * `PagePtrPool`, dispatches the same per-subtype catalog as the raw
- * reader (via `collectPageAnnotations`), and releases the page on exit.
- *
- * Currently the dispatched readers do not use the `pagePtr` parameter
- * (text-markup is fully readable from the dict). Subtype readers that
- * need form/widget access (e.g. widget) will plug into this code path
- * as they land - the public DTO surface stays the same.
- */
-declare class AnnotationReader {
-  private readonly runtime;
-  private readonly session;
-  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  list(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
-}
-//#endregion
-//#region src/features/annotations/AnnotationAppearanceReader.d.ts
-/**
- * Batch-renders the appearance streams (`/AP`) of every annotation on a page,
- * one bitmap per requested mode. Ported from the v2 PDFium engine's
- * `renderPageAnnotationsRaw` / `renderSingleAnnotAppearance`, but expressed in
- * PDF user space and against the `PdfRuntimeModule` (`fn` + `mem`).
- *
- * Each appearance bitmap is sized to its annotation's `/Rect` scaled by
- * `options.scale`. The shared raster helper handles PDFium's display matrix
- * convention, so this reader stays in normalized PDF page coordinates.
- */
-declare class AnnotationAppearanceReader {
-  private readonly runtime;
-  private readonly session;
-  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  render(pageObjectNumber: PageObjectNumber, options: AnnotationAppearanceRenderOptions, signal: AbortSignal): AnnotationAppearancesResult;
-  /**
-   * Render a single annotation appearance into its own raster. Returns `null`
-   * when the mode has no appearance stream (after an optional form-field AP
-   * generation fallback) or the render fails.
-   */
-  private renderOne;
-}
-//#endregion
-//#region src/features/annotations/RawAnnotationReader.d.ts
-/**
- * Whole-document and per-page raw read paths. Never acquires a pagePtr;
- * uses `EPDFPage_GetAnnotCountRaw` / `EPDFPage_GetAnnotRaw` /
- * `EPDFAnnot_GetObjectNumber` directly off the docPtr.
- *
- * Per-subtype dispatch is the same as the full reader (both share
- * `collectPageAnnotations`), so the wire shape `AnnotationDTO[]` is
- * identical between raw and full read paths for the subtypes that don't
- * actually need a pagePtr to materialise their fields.
- */
-declare class RawAnnotationReader {
-  private readonly runtime;
-  private readonly session;
-  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
-  listAll(signal: AbortSignal): AnnotationListSnapshotAllPages;
-  listOne(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
-}
-//#endregion
 //#region src/features/fonts/FontRegistrar.d.ts
 /**
  * A font to register at thread startup from a local file. Used by hosts that
@@ -889,6 +966,9 @@ declare class FontRegistrar {
    * base document. Closed in {@link clear}.
    */
   private readonly fileHandles;
+  /** What the runtime resolved for each key: the identity a document names
+   *  the face by, and the licence. */
+  private readonly identities;
   constructor(runtime: PdfRuntimeModule,
   /** Host-owned `fontKey → native FontId` map for this thread. */
   ids: Map<string, number>);
@@ -909,6 +989,19 @@ declare class FontRegistrar {
    * Throws `InvalidArg` when the runtime rejects the font (corrupt, no glyphs).
    */
   registerFromNodeFile(fontKey: string, familyName: string, weight: number, italic: number, path: string): void;
+  /** The identity and licence the runtime resolved for a key. Throws if unknown. */
+  describe(fontKey: string): FontIdentityInfo;
+  /** {@link describe} for callers that treat an unknown key as "not a key". */
+  describeOrUndefined(fontKey: string): FontIdentityInfo | undefined;
+  /**
+   * The key of the registered font whose identity matches a face (family
+   * compared the engine's way; the closest weight, italic first), or
+   * undefined when no registered family matches.
+   */
+  keyForFace(family: string, weight: number, italic: boolean): string | undefined;
+  /** The application asserts a licence permitting editing with the font. */
+  authorizeEditing(fontKey: string): FontIdentityInfo;
+  private readIdentity;
   /**
    * Register host-owned startup fonts on this thread, in order, optionally
    * adding each to the fallback chain. Order matters: it fixes both the native
@@ -926,6 +1019,75 @@ declare class FontRegistrar {
   private requireId;
 }
 //#endregion
+//#region src/features/annotations/AnnotationReader.d.ts
+/**
+ * Per-page slow-path reader. Acquires a `pagePtr` from the
+ * `PagePtrPool`, dispatches the same per-subtype catalog as the raw
+ * reader (via `collectPageAnnotations`), and releases the page on exit.
+ *
+ * Currently the dispatched readers do not use the `pagePtr` parameter
+ * (text-markup is fully readable from the dict). Subtype readers that
+ * need form/widget access (e.g. widget) will plug into this code path
+ * as they land - the public DTO surface stays the same.
+ */
+declare class AnnotationReader {
+  private readonly runtime;
+  private readonly session;
+  /** 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);
+  list(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+}
+//#endregion
+//#region src/features/annotations/AnnotationAppearanceReader.d.ts
+/**
+ * Batch-renders the appearance streams (`/AP`) of every annotation on a page,
+ * one bitmap per requested mode. Ported from the v2 PDFium engine's
+ * `renderPageAnnotationsRaw` / `renderSingleAnnotAppearance`, but expressed in
+ * PDF user space and against the `PdfRuntimeModule` (`fn` + `mem`).
+ *
+ * Each appearance bitmap is sized to its annotation's `/Rect` scaled by
+ * `options.scale`. The shared raster helper handles PDFium's display matrix
+ * convention, so this reader stays in normalized PDF page coordinates.
+ */
+declare class AnnotationAppearanceReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  render(pageObjectNumber: PageObjectNumber, options: AnnotationAppearanceRenderOptions, signal: AbortSignal): AnnotationAppearancesResult;
+  /**
+   * Render a single annotation appearance into its own raster. Returns `null`
+   * when the mode has no appearance stream (after an optional form-field AP
+   * generation fallback) or the render fails.
+   */
+  private renderOne;
+}
+//#endregion
+//#region src/features/annotations/RawAnnotationReader.d.ts
+/**
+ * Whole-document and per-page raw read paths. Never acquires a pagePtr;
+ * uses `EPDFPage_GetAnnotCountRaw` / `EPDFPage_GetAnnotRaw` /
+ * `EPDFAnnot_GetObjectNumber` directly off the docPtr.
+ *
+ * Per-subtype dispatch is the same as the full reader (both share
+ * `collectPageAnnotations`), so the wire shape `AnnotationDTO[]` is
+ * identical between raw and full read paths for the subtypes that don't
+ * actually need a pagePtr to materialise their fields.
+ */
+declare class RawAnnotationReader {
+  private readonly runtime;
+  private readonly session;
+  /** 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);
+  listAll(signal: AbortSignal): AnnotationListSnapshotAllPages;
+  listOne(pageObjectNumber: PageObjectNumber, signal: AbortSignal): AnnotationListPageSnapshot;
+}
+//#endregion
 //#region src/features/annotations/AnnotationMutator.d.ts
 /**
  * Synchronous orchestrator for `create` / `update` / `delete` annotation
@@ -1272,6 +1434,8 @@ declare class SecurityReader {
 }
 //#endregion
 //#region src/features/save/DocumentSaver.d.ts
+/** Whose bytes a snapshot holds: the loaded file, or the file a save would write. */
+type SaveSource = 'loaded' | 'working-copy';
 /**
  * Owns every "serialize the open document" path for a `DocumentSession`.
  * Two distinct outputs:
@@ -1290,10 +1454,94 @@ declare class DocumentSaver {
   private readonly runtime;
   private readonly session;
   constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /**
+   * The bytes a save would produce, and whether they are the loaded bytes.
+   * Three answers, cheapest first: nothing was mutated since load (the
+   * session's counter); something was mutated but the document is still
+   * the one it was opened with — the fork's save pass found no reachable
+   * object that differs from its loaded version, an annotation added and
+   * removed again being the common case; or a real delta. The one pass
+   * answers the second and produces the third, comparing only the objects
+   * that were touched. A signed file must come back exactly as sealed, so
+   * the loaded bytes are returned verbatim in the first two cases.
+   */
+  snapshot(): {
+    bytes: ArrayBuffer;
+    source: SaveSource;
+  };
+  /** The complete loaded bytes: a plain file, or a layer's base plus the delta it was opened with. */
+  loadedBytes(): ArrayBuffer;
+  /**
+   * The loaded bytes streamed to `path` in chunks: a plain file, or a
+   * layer's base plus the delta it was opened with, never the base alone.
+   * Native only. Replaces whatever `path` held.
+   */
+  copyLoadedBytesToFile(path: string): void;
+  /**
+   * `snapshot()` onto a file: `path` ends up holding the document a save
+   * would write — the loaded bytes when nothing changed, else the standalone
+   * save — without the document ever being an in-memory buffer. Native only.
+   */
+  snapshotToFile(path: string): {
+    path: string;
+    source: SaveSource;
+  };
+  /** Whether this runtime and session can put scratch output beside the base file. */
+  canWriteScratchFiles(): boolean;
   saveLayerArtifact(): {
     bytes: ArrayBuffer;
     size: number;
   };
+  /**
+   * `saveLayerArtifact` that says whether anything reachable changed since
+   * the layer was opened. When nothing did, `bytes` is empty and the
+   * artifact the session was opened with stands. The artifact written
+   * otherwise is cumulative against the base (empty delta when the layer
+   * came to equal its base).
+   */
+  saveLayerArtifactEx(): {
+    bytes: ArrayBuffer;
+    size: number;
+    changedSinceLoad: boolean;
+  };
+  /**
+   * `saveLayerArtifactEx` onto a file: nothing reaches `path` when nothing
+   * changed since load. The delta inside is streamed, never held whole.
+   * Native only.
+   */
+  saveLayerArtifactToFileEx(path: string): {
+    path: string;
+    changedSinceLoad: boolean;
+  };
+  /** `saveLayerDeltaEx` onto a file: the cumulative delta, or nothing when nothing changed since load. Native only. */
+  saveLayerDeltaToFileEx(path: string): {
+    path: string;
+    changedSinceLoad: boolean;
+  };
+  private saveLayerToFileImpl;
+  private saveLayerArtifactImpl;
+  /**
+   * The raw cumulative delta a layer save writes (every promoted object,
+   * offsets notional from the base's append offset), without the artifact
+   * header: what `EPDFDoc_OpenBaseOverlay` composes with the base. Empty
+   * when nothing was promoted.
+   */
+  saveLayerDelta(): {
+    bytes: ArrayBuffer;
+    size: number;
+  };
+  /**
+   * `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).
+   */
+  saveLayerDeltaEx(): {
+    bytes: ArrayBuffer;
+    size: number;
+    changedSinceLoad: boolean;
+  };
+  private saveLayerDeltaImpl;
   saveLayerArtifactToFile(path: string): {
     path: string;
   };
@@ -1301,12 +1549,261 @@ declare class DocumentSaver {
     bytes: ArrayBuffer;
     size: number;
   };
+  /**
+   * `saveStandaloneToBuffer` that says whether the save wrote anything. An
+   * incremental save of a layer never rewrites an object equal to its base
+   * twin, and when no reachable object differs from the document the layer
+   * was opened with it writes nothing at all: `unchangedSinceLoad`, empty
+   * bytes — the loaded bytes are the document.
+   */
+  saveStandaloneToBufferEx(mode: PdfSaveMode): {
+    bytes: ArrayBuffer;
+    size: number;
+    unchangedSinceLoad: boolean;
+  };
   saveStandaloneToFile(path: string, mode: PdfSaveMode): {
     path: string;
   };
+  /**
+   * `saveStandaloneToFile` with the report of `saveStandaloneToBufferEx`.
+   * On `unchangedSinceLoad` no byte reached the file: the caller streams
+   * the loaded bytes instead.
+   */
+  saveStandaloneToFileEx(path: string, mode: PdfSaveMode): {
+    path: string;
+    unchangedSinceLoad: boolean;
+  };
   private requireLayer;
 }
 //#endregion
+//#region src/features/signature/SignatureReader.d.ts
+declare const DIGEST_CODE: Record<DigestAlgorithm, number>;
+/**
+ * Reads the signature model of a session: revisions, every signature
+ * field with its signed state, and the protection those signatures
+ * impose. Byte facts (revisions, coverage, digests, loaded bytes) come
+ * from the bytes the document was loaded from — for a layer session the
+ * base plus the delta it was opened with — never from unsaved edits.
+ */
+declare class SignatureReader {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  readSnapshot(): SignatureSnapshot;
+  /** The protection alone, for the open probe and the form write guard. */
+  readProtection(): DocumentProtection;
+  /** The DER `/Contents` of a signed field, padding stripped. */
+  readContents(ref: FormFieldRef): ArrayBuffer;
+  /** Hash a signed field's `/ByteRange` straight from the loaded bytes. */
+  digest(ref: FormFieldRef, algorithm: DigestAlgorithm): ArrayBuffer;
+  /** The exact bytes of one revision. */
+  revisionBytes(revisionIndex: number): ArrayBuffer;
+  /** Resolve a signature-field ref to its identity in the current model. */
+  resolveField(ref: FormFieldRef): {
+    index: number;
+    fieldObjectNumber: number;
+    signed: boolean;
+    widget: {
+      annotObjectNumber: number;
+      pageObjectNumber: number;
+    } | null;
+  };
+  /** One signature by field object number, from the current model. */
+  readSignatureByObjectNumber(fieldObjectNumber: number): SignatureDTO;
+  /** The complete loaded bytes (a plain file, or a layer's base + delta). */
+  loadedBytes(): ArrayBuffer;
+  /**
+   * SHA-256 and length of the base the session is on. A layer session
+   * reports its base's hash (supplied by the host or computed once by the
+   * runtime); a plain session hashes its loaded bytes once per load.
+   */
+  version(): BaseVersionInfo;
+  private digestRange;
+  /** `[offset, offset + length)` of the loaded bytes (base + loaded delta for a layer), copied out. */
+  readLoadedBytes(offset: number, length: number): ArrayBuffer;
+  private indexOf;
+  private requireSignedIndex;
+  private readString;
+  private readWide;
+}
+//#endregion
+//#region src/features/signature/SignatureMutator.d.ts
+/**
+ * The two-phase signing protocol on a session, local and native alike.
+ *
+ * `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.
+ */
+declare class SignatureMutator {
+  private readonly runtime;
+  private readonly session;
+  private readonly baseDocuments;
+  /** Where a file-backed session's candidate is written; defaults to beside the base file. */
+  private readonly candidatePath?;
+  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;
+  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.
+   */
+  private storeFor;
+  /**
+   * Prove the sealed bytes carry a whole-revision signature on the field
+   * before anything is installed; closes the handle on failure.
+   */
+  /**
+   * Read the sealed candidate back before it is installed: the checks in
+   * `assertSealedSignature` are made on a model loaded from the sealed
+   * bytes themselves, so a candidate the writer got wrong never becomes
+   * the session's bytes.
+   */
+  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
+   * 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
+   * fill-and-sign. The fallback freezes the complete loaded bytes as a new
+   * memory base: for a plain session, and for a layer whose loaded delta
+   * already holds signed bytes (a layer save rewrites the delta and would
+   * drop them; the fork refuses to prepare such a candidate).
+   */
+  private openCandidate;
+  /** Whether a signature's byte range reaches into the layer's loaded delta (past the base). */
+  private loadedDeltaHoldsSignedBytes;
+}
+//#endregion
+//#region src/features/signature/SignatureAnalyzer.d.ts
+/**
+ * Modification analysis over a session: which revisions to compare, the
+ * fork's exact object diff for each adjacent pair, each revision's
+ * structure, and the pure rule engine's verdict per step. Every revision
+ * is opened as its own prefix document from the target's loaded bytes;
+ * `working-copy` first snapshots the session the way a save would.
+ */
+declare class SignatureAnalyzer {
+  private readonly runtime;
+  private readonly session;
+  constructor(runtime: PdfRuntimeModule, session: DocumentSession);
+  /**
+   * The signature snapshot of the session's working copy: the unsaved
+   * state snapshotted the way a save would write it, as one more revision
+   * over the loaded bytes. Identical to the loaded-bytes snapshot when
+   * nothing is unsaved.
+   */
+  readWorkingCopySnapshot(): SignatureSnapshot;
+  analyze(input: AnalyzeInput): ChangeAnalysis;
+  /** Revision `index` of `target`'s bytes as its own document, owned by `stack`. */
+  private openPrefix;
+  /**
+   * Every pairwise step between `since` and `until`, two prefix documents
+   * open at a time whatever the revision count. `sealedStructure` is the
+   * structure of `since` (already read); every later structure is read once
+   * and dropped with its document.
+   */
+  private walkSteps;
+  /**
+   * The document as a save would write it, opened read-only, and whose
+   * bytes that is. `loaded`: nothing was mutated since load, or the saver's
+   * pass found no reachable object that differs from its loaded version —
+   * 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
+   * 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. */
+  private freshLayerOverBase;
+  /**
+   * The fork's exact object diff between two revision documents,
+   * marshalled: values in pass one, anchored edges in pass two (the anchors
+   * are the changed objects plus each side's structural objects).
+   */
+  private compare;
+  /** What the fork learned about one revision as a whole (see `RevisionHealth`). */
+  private readHealth;
+  /**
+   * Pass two: every changed object's inbound edges, resolved through
+   * unchanged non-structural objects to the nearest anchor (the fork's
+   * referrer index covers every reachable object, so the walk never leaves
+   * the diff). An object whose edges exceed the resolver's budget is
+   * marked `usageIncomplete` and the evaluator refuses to permit it.
+   */
+  private withAnchoredUsage;
+  private readValue;
+  private readReferrers;
+}
+//#endregion
+//#region src/features/signature/CandidateFinalizer.d.ts
+interface FinalizeCandidateInput {
+  /** The rebuilt candidate on this filesystem; patched in place. */
+  path: string;
+  byteRange: [number, number, number, number];
+  contentsSize: number;
+  fieldObjectNumber: number;
+  cms: Uint8Array;
+  password: string | null;
+}
+interface FinalizedCandidate {
+  signature: SignatureDTO;
+  protection: DocumentProtection;
+  version: BaseVersionInfo;
+}
+/**
+ * The session-less half of a durable signing. A server prepares a
+ * candidate on one replica, keeps only its tail, and may complete it on
+ * another: the completing replica rebuilds base ⊕ tail into a private
+ * file and hands it here with what the prepare reported. The CMS is
+ * hex-encoded into the /Contents hole in place — never more than the
+ * hole itself is held in memory — and the file is then opened like any
+ * other base and read back through the signature model, so the version
+ * returned is the file's own hash and the signature is what the file
+ * says, not what the writer meant. Nothing here touches a live session.
+ */
+declare class CandidateFinalizer {
+  private readonly runtime;
+  private readonly baseDocuments;
+  constructor(runtime: PdfRuntimeModule, baseDocuments: BaseDocumentRegistry);
+  finalize(input: FinalizeCandidateInput): FinalizedCandidate;
+}
+//#endregion
+//#region src/features/signature/internal/signatureModelCache.d.ts
+declare function acquireSignatureModel(runtime: PdfRuntimeModule, session: DocumentSession): Ptr;
+declare function disposeSignatureModel(runtime: PdfRuntimeModule, session: DocumentSession): void;
+//#endregion
+//#region src/features/signature/internal/readSignatureModel.d.ts
+/** Every signature field of a native signature model, in model order. */
+declare function readSignaturesFromModel(runtime: PdfRuntimeModule, model: Ptr): SignatureDTO[];
+/** The chained revisions of a document, oldest first; empty when the chain is not valid. */
+declare function readRevisions(runtime: PdfRuntimeModule, docPtr: Ptr, signatures: ReadonlyArray<SignatureDTO>): PdfRevision[];
+/** Whether any signature field of the document carries a signed value (fields alone do not count). */
+declare function hasSignedSignature(runtime: PdfRuntimeModule, docPtr: Ptr): boolean;
+/**
+ * The structure of one document (a revision prefix, usually): catalog,
+ * AcroForm and page-tree object numbers, the pages, the terminal fields
+ * with their widgets, and the signatures. What the rule engine needs to
+ * give every changed object a role.
+ */
+declare function readStructure(runtime: PdfRuntimeModule, docPtr: Ptr): RevisionStructure;
+//#endregion
 //#region src/features/forms/FormReader.d.ts
 /**
  * Read side of the forms feature. All reads go through the session's
@@ -1355,6 +1852,17 @@ declare class FormMutator {
   createField(draft: FormFieldDraft, signal: AbortSignal): {
     field: FormFieldDTO;
   };
+  /**
+   * 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.
+   */
+  setSignatureAppearance(ref: FormFieldRef, pdf: Uint8Array, pageIndex: number, signal: AbortSignal): {
+    field: FormFieldDTO;
+    pages: PageObjectNumber[];
+  };
   updateField(ref: FormFieldRef, patch: FormFieldPatch, signal: AbortSignal): {
     field: FormFieldDTO;
   };
@@ -1379,6 +1887,14 @@ declare class FormMutator {
   private applyDefaultValues;
   private readBackField;
   private assertWritable;
+  /**
+   * 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.
+   */
+  private assertNotLockedBySignature;
   /** Dispatch the typed native write. Returns the changed widget objnums. */
   private applyWrite;
   /** Run a native write with the changed-widgets out buffer wired up. */
@@ -1496,6 +2012,13 @@ interface WorkerImageEncoder {
 }
 interface WorkerHostOptions {
   imageEncoder?: WorkerImageEncoder;
+  /**
+   * Where a file-backed session (a file base) writes its signing candidate
+   * between `prepare` and `complete`. Defaults to beside the base file
+   * (`<base>.signing-<id>.pdf`); a server maps it into its storage layout so
+   * the sealed file can be published by rename.
+   */
+  signingCandidatePath?: (basePath: string, signingId: string) => string;
 }
 /**
  * The piece that runs "inside the worker": owns runtime, manages document
@@ -1554,6 +2077,48 @@ declare class WorkerHost {
   registerStartupFonts(specs: readonly StartupFontSpec[]): void;
   receive(msg: WorkerRequest): void;
   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.
+   */
+  private openSignedAware;
+  /**
+   * What the document's signatures forbid, read at open and after an
+   * unlock so the main-thread guard can subtract capabilities before the
+   * first mutation. A document whose signature model cannot be built
+   * still opens: protection is then `null` (nothing is known to be
+   * signed), and the reads report the failure on their own.
+   */
+  private probeProtection;
+  private handleSignaturesList;
+  private handleSignaturesContents;
+  private handleSignaturesDigest;
+  private handleSignaturesRevisionBytes;
+  private handleDocumentVersion;
+  private handleSignaturesPrepare;
+  private handleSignaturesComplete;
+  private handleSignaturesAnalyze;
+  /**
+   * Session-less, like `document.renderPageFile`: the candidate file is
+   * the caller's, patched in place and read back through a transient
+   * session that is never stored in `this.sessions`.
+   */
+  private handleSignaturesFinalizeCandidate;
+  private handleSignaturesAbort;
+  /**
+   * 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`.
+   */
+  private assertNoPendingSigning;
   private handleMetadataRead;
   private handleMetadataUpdate;
   private handleActionsRead;
@@ -1611,6 +2176,9 @@ declare class WorkerHost {
   private handleDocumentRenderPageFile;
   private handleDocumentCheckPasswordPermissions;
   private handleFontsRegister;
+  private handleFontsAuthorizeEditing;
+  /** Per-document font and text-layout settings (session state). */
+  private handleDocumentSetFontSettings;
   private handleFontsAddFallback;
   private handleFontsClearFallbacks;
   private handleFontsClear;
@@ -1643,6 +2211,7 @@ declare class WorkerHost {
   private handleFormsRepair;
   private handleFormsCreateField;
   private handleFormsUpdateField;
+  private handleFormsSetSignatureAppearance;
   private handleFormsDeleteField;
   private handleFormsAttachWidget;
   private handleFormsDetachWidget;
@@ -1650,5 +2219,5 @@ declare class WorkerHost {
   private saveLayerArtifact;
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, type AcquiredBaseDocument, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationFlattener, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, 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, type StartupFontSpec, type WorkerEncodedImage, WorkerHost, type WorkerHostOptions, type WorkerImageEncoder, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+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 };
 //# sourceMappingURL=index.d.ts.map