@cloudpdf/engine 3.0.0-next.11 → 3.0.0-next.13

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
+import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationFlattenResult, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentSignaturesService, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNameInput, PageNameResult, PageObjectNumber, PageRaster, PageRemoveNameInput, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
 import { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
 import { SessionEventPublisher } from "@embedpdf/engine-services";
 //#region src/transport/HttpClient.d.ts
@@ -318,6 +318,7 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
   readonly annotations: DocumentAnnotationsService$1;
   readonly actions: DocumentActionsService;
   readonly attachments: DocumentAttachmentsService;
+  readonly signatures: DocumentSignaturesService;
   readonly forms: DocumentFormsService;
   readonly search: CloudDocumentSearchService;
   readonly pages: DocumentPagesService$1;
@@ -513,6 +514,14 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
    */
   list(): AbortablePromise$1<PageListSnapshot>;
   move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise$1<PageMoveResult>;
+  setName(input: PageNameInput): AbortablePromise$1<PageNameResult>;
+  removeName(input: PageRemoveNameInput): AbortablePromise$1<PageNameResult>;
+  /**
+   * Named pages are LAYOUT: both verbs share the page-move patch exactly —
+   * docVersion + layoutVersion advance, no per-page pin changes, so the
+   * cached manifest is patched in place and the fresh layout is published.
+   */
+  private runNameMutation;
   rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation): AbortablePromise$1<PageRotateResult>;
   delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<PageDeleteResult>;
   insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise$1<PageInsertResult>;
@@ -559,6 +568,8 @@ declare class CloudPageAnnotationsService implements PageAnnotationsService$1 {
   private patchMutation;
   delete(ref: AnnotationRef): AbortablePromise$1<AnnotationDeleteResult>;
   move(refs: AnnotationRef[], toIndex: number): AbortablePromise$1<AnnotationMoveResult>;
+  flatten(refs: AnnotationRef[], usage?: PageFlattenUsage): AbortablePromise$1<AnnotationFlattenResult>;
+  exportAppearance(refs: AnnotationRef[]): AbortablePromise$1<Uint8Array>;
   /**
    * Patch the cached manifest, then publish the mutation to the document's
    * event stream (in that order — listeners reading the manifest in their

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
+import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationFlattenResult, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentSignaturesService, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageNameInput, PageNameResult, PageObjectNumber, PageRaster, PageRemoveNameInput, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
 import { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
 import { SessionEventPublisher } from "@embedpdf/engine-services";
 //#region src/transport/HttpClient.d.ts
@@ -318,6 +318,7 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
   readonly annotations: DocumentAnnotationsService$1;
   readonly actions: DocumentActionsService;
   readonly attachments: DocumentAttachmentsService;
+  readonly signatures: DocumentSignaturesService;
   readonly forms: DocumentFormsService;
   readonly search: CloudDocumentSearchService;
   readonly pages: DocumentPagesService$1;
@@ -513,6 +514,14 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
    */
   list(): AbortablePromise$1<PageListSnapshot>;
   move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise$1<PageMoveResult>;
+  setName(input: PageNameInput): AbortablePromise$1<PageNameResult>;
+  removeName(input: PageRemoveNameInput): AbortablePromise$1<PageNameResult>;
+  /**
+   * Named pages are LAYOUT: both verbs share the page-move patch exactly —
+   * docVersion + layoutVersion advance, no per-page pin changes, so the
+   * cached manifest is patched in place and the fresh layout is published.
+   */
+  private runNameMutation;
   rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation): AbortablePromise$1<PageRotateResult>;
   delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<PageDeleteResult>;
   insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise$1<PageInsertResult>;
@@ -559,6 +568,8 @@ declare class CloudPageAnnotationsService implements PageAnnotationsService$1 {
   private patchMutation;
   delete(ref: AnnotationRef): AbortablePromise$1<AnnotationDeleteResult>;
   move(refs: AnnotationRef[], toIndex: number): AbortablePromise$1<AnnotationMoveResult>;
+  flatten(refs: AnnotationRef[], usage?: PageFlattenUsage): AbortablePromise$1<AnnotationFlattenResult>;
+  exportAppearance(refs: AnnotationRef[]): AbortablePromise$1<Uint8Array>;
   /**
    * Patch the cached manifest, then publish the mutation to the document's
    * event stream (in that order — listeners reading the manifest in their

package/dist/index.js

@@ -1,5 +1,5 @@
 import { AbortError, AbortError as AbortError$1, AbortablePromise, AbortablePromise as AbortablePromise$1, CONTINUOUS_RENDER_POLICY, DEFAULT_PDF_SAVE_MODE, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineErrorCode as EngineErrorCode$1, canonicalSearchQuery, checkCapability, checkCollab, checkSetGroup, createPageImageHandle, decodePdfBits, encodeFieldRefKey, encodeStableIdKey, expandRawScope, normalizeAnnotationDraft, normalizeAnnotationPatch, normalizeAttachmentFileSource, passwordPromptFromState, searchContentEpoch, securityStateFromHead } from "@embedpdf/engine-core/runtime";
-import { AccessResponseSchema, AnnotationAppearanceManifestSchema, AnnotationCreateResultSchema, AnnotationDeleteResultSchema, AnnotationListPageSnapshotSchema, AnnotationListSnapshotAllPagesSchema, AnnotationMoveResultSchema, AnnotationUpdateResultSchema, AttachmentCreateResultSchema, AttachmentDeleteResultSchema, DEFAULT_LAYER_NAME, DocumentActionsSnapshotSchema, DocumentHeadSchema, DocumentManifestSchema, DocumentMetadataSchema, EmbeddedFileItemSchema, EngineErrorPayloadSchema, FormEffectsResultSchema, FormFieldCreateResultSchema, FormFieldDTOSchema, FormFieldDeleteResultSchema, FormFieldUpdateResultSchema, FormImportResultSchema, FormRepairResultSchema, FormSetValueResultSchema, FormSnapshotSchema, FormWidgetLinkResultSchema, MetadataUpdateResultSchema, PageDeleteResultSchema, PageFlattenResultSchema, PageGeometrySnapshotSchema, PageInsertResultSchema, PageListSnapshotSchema, PageMoveResultSchema, PageRotateResultSchema, PageTextSnapshotSchema, RedactionApplyResultSchema, SearchSliceSchema, WeakAnnotationSessionResponseSchema, annotationAppearancesImageOptionsToWire, applyCdnAccess, decodeSearchToken, decodeTokenText, encodeSearchToken, renderImageOptionsToWire, wirePaths } from "@embedpdf/engine-core/wire";
+import { AccessResponseSchema, AnnotationAppearanceManifestSchema, AnnotationCreateResultSchema, AnnotationDeleteResultSchema, AnnotationFlattenResultSchema, AnnotationListPageSnapshotSchema, AnnotationListSnapshotAllPagesSchema, AnnotationMoveResultSchema, AnnotationUpdateResultSchema, AttachmentCreateResultSchema, AttachmentDeleteResultSchema, ChangeAnalysisSchema, DEFAULT_LAYER_NAME, DocumentActionsSnapshotSchema, DocumentHeadSchema, DocumentManifestSchema, DocumentMetadataSchema, EmbeddedFileItemSchema, EngineErrorPayloadSchema, FormEffectsResultSchema, FormFieldCreateResultSchema, FormFieldDTOSchema, FormFieldDeleteResultSchema, FormFieldUpdateResultSchema, FormImportResultSchema, FormRepairResultSchema, FormSetValueResultSchema, FormSnapshotSchema, FormWidgetLinkResultSchema, MetadataUpdateResultSchema, PageDeleteResultSchema, PageFlattenResultSchema, PageGeometrySnapshotSchema, PageInsertResultSchema, PageListSnapshotSchema, PageMoveResultSchema, PageNameResultSchema, PageRotateResultSchema, PageTextSnapshotSchema, RedactionApplyResultSchema, SearchSliceSchema, SignatureAbortResultSchema, SignatureCompleteResultSchema, SignaturePreparedWireSchema, SignatureSnapshotSchema, WeakAnnotationSessionResponseSchema, annotationAppearancesImageOptionsToWire, applyCdnAccess, decodePrepared, decodeSearchToken, decodeTokenText, encodeSearchToken, renderImageOptionsToWire, toBase64, wirePaths } from "@embedpdf/engine-core/wire";
 import { EventHub, SessionEventPublisher, generateUuid } from "@embedpdf/engine-services";
 //#region src/document/planes.ts
 /**
@@ -434,6 +434,24 @@ var CloudDocumentFormsService = class {
 			return this.absorbMutation(result, "form.fieldUpdated");
 		});
 	}
+	setSignatureAppearance(ref, appearance) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const bytes = new ArrayBuffer(appearance.pdf.byteLength);
+			new Uint8Array(bytes).set(appearance.pdf);
+			const form = buildMutationForm({
+				resource: "r0",
+				pageIndex: appearance.pageIndex ?? 0
+			}, { r0: {
+				bytes,
+				mimeType: "application/pdf",
+				name: "appearance.pdf"
+			} });
+			const result = await this.http.postMultipartJson(wirePaths.layerFormFieldSignatureAppearance(this.docId, this.layerName, encodeFieldRefKey(ref)), form, (raw) => FormFieldUpdateResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.fieldUpdated");
+		});
+	}
 	deleteField(ref) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
@@ -559,6 +577,31 @@ var CloudDocumentPagesService = class {
 			return result;
 		});
 	}
+	setName(input) {
+		return this.runNameMutation(wirePaths.layerPagesNames(this.docId, this.layerName), input, input.name, input.pageObjectNumber);
+	}
+	removeName(input) {
+		return this.runNameMutation(wirePaths.layerPagesNamesDelete(this.docId, this.layerName), input, input.name, null);
+	}
+	/**
+	* Named pages are LAYOUT: both verbs share the page-move patch exactly —
+	* docVersion + layoutVersion advance, no per-page pin changes, so the
+	* cached manifest is patched in place and the fresh layout is published.
+	*/
+	runNameMutation(path, body, name, pageObjectNumber) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(path, body, (raw) => PageNameResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageStructure(result.cache);
+			this.publisher.publishLocal({
+				type: "pages.named",
+				name,
+				pageObjectNumber,
+				...result
+			});
+			return result;
+		});
+	}
 	rotate(pageObjectNumbers, rotation) {
 		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
 		return AbortablePromise$1.run(async (signal) => {
@@ -989,6 +1032,176 @@ function identityFromClaims(claims) {
 	return Object.keys(out).length > 0 ? out : null;
 }
 //#endregion
+//#region src/document/CloudDocumentSignaturesService.ts
+/**
+* Cloud-side digital signatures. Two kinds of read, two kinds of URL:
+*
+*   - The LAYER view (`list`, and `analyze` of the working copy) is pinned
+*     by the manifest's `docVersion`, like every other layer read: a
+*     signature is a layer state change, the immutable URL moves with it.
+*   - Signed BYTES (`contents`, `digest`, `revisionBytes`, and `analyze`
+*     of history) belong to a base VERSION and are content-addressed by
+*     the manifest's `baseSha`: immutable forever, shared by every layer
+*     and every caller.
+*
+* Signing is the server's two-phase protocol over the same wire shapes
+* the local engine uses. `prepare` and `complete` change the manifest in
+* ways no delta carries (a publish moves `baseSha` itself), so both
+* refresh it before returning.
+*/
+var CloudDocumentSignaturesService = class {
+	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+		this.publisher = publisher;
+	}
+	list() {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => this.http.getJsonWithRefresh(async (s) => {
+			const manifest = await this.manifest.get(s);
+			return wirePaths.layerSignatures(this.docId, this.layerName, manifest.docVersion);
+		}, (raw) => SignatureSnapshotSchema.parse(raw), async (s) => {
+			await this.manifest.refresh(s);
+		}, signal));
+	}
+	contents(field) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const manifest = await this.manifest.get(signal);
+			const name = await this.fieldName(field, signal);
+			return this.http.getBytes(wirePaths.docVersionSignatureContents(this.docId, manifest.baseSha, name), signal);
+		});
+	}
+	digest(field, algorithm) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const manifest = await this.manifest.get(signal);
+			const name = await this.fieldName(field, signal);
+			return this.http.getBytes(wirePaths.docVersionSignatureDigest(this.docId, manifest.baseSha, name, algorithm), signal);
+		});
+	}
+	revisionBytes(revisionIndex) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const manifest = await this.manifest.get(signal);
+			return this.http.getBytes(wirePaths.docVersionRevision(this.docId, manifest.baseSha, revisionIndex), signal);
+		});
+	}
+	/**
+	* `until: 'working-copy'` (or unset while the layer holds edits) judges
+	* the layer's pending edits against the base at the layer URL; anything
+	* else is history of the base version and resolves at the version URL.
+	*/
+	analyze(input) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const manifest = await this.manifest.get(signal);
+			if (input.until === "working-copy" || input.until === void 0 && manifest.working) return this.http.getJsonWithRefresh(async (s) => {
+				const current = await this.manifest.get(s);
+				return wirePaths.layerSignaturesAnalysis(this.docId, this.layerName, {
+					docVersion: current.docVersion,
+					since: input.since,
+					...input.exploratoryLevel !== void 0 ? { exploratoryLevel: input.exploratoryLevel } : {},
+					...input.detail !== void 0 ? { detail: input.detail } : {}
+				});
+			}, (raw) => ChangeAnalysisSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+			return this.http.getJson(wirePaths.docVersionAnalysis(this.docId, manifest.baseSha, {
+				since: input.since,
+				...typeof input.until === "object" ? { until: input.until.revisionIndex } : {},
+				...input.exploratoryLevel !== void 0 ? { exploratoryLevel: input.exploratoryLevel } : {},
+				...input.detail !== void 0 ? { detail: input.detail } : {}
+			}), (raw) => ChangeAnalysisSchema.parse(raw), signal);
+		});
+	}
+	prepare(input) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const { appearance, ...rest } = input;
+			const form = buildMutationForm({
+				...rest,
+				...appearance ? { appearance: {
+					resource: "appearance",
+					...appearance.pageIndex !== void 0 ? { pageIndex: appearance.pageIndex } : {}
+				} } : {}
+			}, appearance ? { appearance: {
+				bytes: appearance.pdf.slice().buffer,
+				mimeType: "application/pdf",
+				name: "appearance.pdf"
+			} } : {});
+			const prepared = await this.http.postMultipartJson(wirePaths.layerSignaturesPrepare(this.docId, this.layerName), form, (raw) => decodePrepared(SignaturePreparedWireSchema.parse(raw)), signal);
+			await this.manifest.refresh(signal);
+			this.publisher.publishLocal({
+				type: "signature.prepared",
+				signingId: prepared.signingId,
+				field: input.field
+			});
+			return prepared;
+		});
+	}
+	complete(input) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerSignatureComplete(this.docId, this.layerName, input.signingId), {
+				cms: toBase64(input.cms),
+				expectedVersion: input.expectedVersion
+			}, (raw) => SignatureCompleteResultSchema.parse(raw), signal);
+			await this.manifest.refresh(signal);
+			if (result.status === "completed") {
+				this.publisher.publishLocal({
+					type: "signature.completed",
+					signingId: input.signingId,
+					...result
+				});
+				this.publisher.publishLocal({
+					type: "document.versioned",
+					version: result.version
+				});
+			}
+			return result;
+		});
+	}
+	abort(signingId) {
+		const rejected = this.closedRejection();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.deleteJson(wirePaths.layerSignatureAbort(this.docId, this.layerName, signingId), (raw) => SignatureAbortResultSchema.parse(raw), signal);
+			if (result.status === "aborted") this.publisher.publishLocal({
+				type: "signature.aborted",
+				signingId
+			});
+			return result;
+		});
+	}
+	/** Version routes address a field by its fully qualified name; an object-number ref is resolved through the snapshot. */
+	async fieldName(field, signal) {
+		if (field.kind === "fqn") return field.name;
+		const match = (await this.http.getJsonWithRefresh(async (s) => {
+			const manifest = await this.manifest.get(s);
+			return wirePaths.layerSignatures(this.docId, this.layerName, manifest.docVersion);
+		}, (raw) => SignatureSnapshotSchema.parse(raw), async (s) => {
+			await this.manifest.refresh(s);
+		}, signal)).signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === field.fieldObjectNumber);
+		if (!match) throw new EngineError$1(EngineErrorCode$1.NotFound, `no signature field #${field.fieldObjectNumber}`);
+		return match.fieldName;
+	}
+	closedRejection() {
+		if (!this.isClosed()) return null;
+		return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+	}
+};
+//#endregion
 //#region src/document/CloudMetadataService.ts
 var CloudMetadataService = class {
 	constructor(http, docId, layerName, isClosed, manifest, publisher) {
@@ -1184,6 +1397,29 @@ var CloudPageAnnotationsService = class {
 			return this.absorbMutation(result, "annotation.moved");
 		});
 	}
+	flatten(refs, usage = "display") {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `flatten ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
+		const path = wirePaths.layerPageAnnotationsFlatten(this.docId, this.layerName, this.pageObjectNumber);
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(path, {
+				refs,
+				usage
+			}, (raw) => AnnotationFlattenResultSchema.parse(raw), signal);
+			if (result.meta === null) return result;
+			this.manifest.apply(result.meta, ["content", "annotations"]);
+			this.publisher.publishLocal({
+				type: "annotations.flattened",
+				...result
+			});
+			return result;
+		});
+	}
+	exportAppearance(refs) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `exportAppearance ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
+		return AbortablePromise$1.run(async (signal) => this.http.postJsonBytes(wirePaths.layerPageAnnotationsAppearance(this.docId, this.layerName, this.pageObjectNumber), { refs }, signal));
+	}
 	/**
 	* Patch the cached manifest, then publish the mutation to the document's
 	* event stream (in that order — listeners reading the manifest in their
@@ -1513,7 +1749,8 @@ function auditRowToEvent(row, mySessionId) {
 			origin,
 			...row.payload
 		};
-		case "form.updateField": return {
+		case "form.updateField":
+		case "form.setSignatureAppearance": return {
 			type: "form.fieldUpdated",
 			origin,
 			...row.payload
@@ -1653,6 +1890,7 @@ var CloudDocumentHandle = class {
 		_defineProperty(this, "annotations", void 0);
 		_defineProperty(this, "actions", void 0);
 		_defineProperty(this, "attachments", void 0);
+		_defineProperty(this, "signatures", void 0);
 		_defineProperty(this, "forms", void 0);
 		_defineProperty(this, "search", void 0);
 		_defineProperty(this, "pages", void 0);
@@ -1722,6 +1960,7 @@ var CloudDocumentHandle = class {
 		this.annotations = new CloudDocumentAnnotationsService(http, id, layerName, () => this.closed, this.manifestAccessor);
 		this.actions = new CloudDocumentActionsService(http, id, layerName, () => this.closed, this.manifestAccessor);
 		this.attachments = new CloudDocumentAttachmentsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
+		this.signatures = new CloudDocumentSignaturesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
 		this.forms = new CloudDocumentFormsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
 		this.search = new CloudDocumentSearchService(http, id, layerName, () => this.closed, this.manifestAccessor);
 		this.pages = new CloudDocumentPagesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
@@ -1824,6 +2063,8 @@ var CloudDocumentHandle = class {
 			...this.manifestCache,
 			docVersion: delta?.docVersion ?? this.manifestCache.docVersion,
 			...delta?.annotationsVersion !== void 0 ? { annotationsVersion: delta.annotationsVersion } : {},
+			...delta?.layerVersion !== void 0 ? { layerVersion: delta.layerVersion } : {},
+			...delta?.working !== void 0 ? { working: delta.working } : {},
 			pages: Array.from(byPageObjectNumber.values()).sort((a, b) => a.state.pageObjectNumber - b.state.pageObjectNumber)
 		};
 	}