@embedpdf/plugin-signature 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.cjs

@@ -1,12 +1,515 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-CojqGdMH.cjs");
+const require_contract = require("./contract-Bu7_S84K.cjs");
 let _embedpdf_core = require("@embedpdf/core");
+let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
 let _embedpdf_plugin_form_contract = require("@embedpdf/plugin-form/contract");
-let _embedpdf_plugin_interaction_contract = require("@embedpdf/plugin-interaction/contract");
+let _embedpdf_plugin_interaction_contract_host = require("@embedpdf/plugin-interaction/contract/host");
 let _embedpdf_plugin_stamp_contract = require("@embedpdf/plugin-stamp/contract");
-let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
-let _embedpdf_core_signature = require("@embedpdf/core-signature");
+let _embedpdf_plugin_annotation_contract_host = require("@embedpdf/plugin-annotation/contract/host");
 let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
+let _embedpdf_core_signature = require("@embedpdf/core-signature");
+//#region src/tools/armed-mark.ts
+/**
+* The armed mark over a field. The annotation plugin places an armed stamp
+* on click (`annotation-place`, priority 95) and selects an existing
+* annotation under the pointer before that (`annotation-edit`, 100; a
+* widget is an annotation). This handler sits above both, enabled for the
+* armed stamp's tool only, and captures exactly when the armed asset is a
+* person's mark (a library of kind `signatures`) and the pointer is over a
+* signature field: then the destination decides, and the mark goes into the
+* field (`placeMark` by mode) instead of onto the page. Everywhere else it
+* declines and the click stays a stamp placement, as in Preview.
+*/
+function createArmedMarkHandler(documentId, signature, form, stamp) {
+	return {
+		id: "signature:armed-mark-on-field",
+		priority: _embedpdf_plugin_annotation_contract_host.ANNOTATION_EDIT_PRIORITY + 1,
+		enabledFor: (tool) => tool.id === _embedpdf_plugin_annotation_contract_host.ARMED_STAMP_TOOL_ID,
+		onDown: (sample) => {
+			if (!sample.page) return false;
+			const armed = stamp.getArmedAsset(documentId);
+			if (!armed || stamp.getLibrary(armed.libraryId)?.kind !== "signatures") return false;
+			const hit = form.getWidgetAt(sample.page.ref, sample.page.point);
+			if (!hit || hit.field.family !== "signature") return false;
+			if (signature.getSignature(hit.field.ref)?.signed || hit.field.valueEntry.kind !== "none") return true;
+			stamp.disarm(documentId);
+			signature.placeMark({ assetId: armed.id }, { field: hit.field.ref }).catch((error) => globalThis.console?.error("[signature] placing the mark failed:", error));
+			return true;
+		}
+	};
+}
+//#endregion
+//#region src/connect.ts
+/**
+* Wiring to sibling plugins. With the interaction hub and the stamp plugin
+* present, an armed mark from a `signatures` library dropped over an
+* unsigned signature field goes into the field instead of onto the page.
+*/
+function connectSiblings(ctx, signature) {
+	const interaction = ctx.tryGet(_embedpdf_plugin_interaction_contract_host.InteractionToken);
+	const stamp = ctx.tryGet(_embedpdf_plugin_stamp_contract.StampToken);
+	const documentId = ctx.documentId;
+	if (!interaction || !stamp || !documentId) return;
+	ctx.cleanup(interaction.registerHandler(createArmedMarkHandler(documentId, signature, ctx.get(_embedpdf_plugin_form_contract.FormToken), stamp)));
+}
+//#endregion
+//#region src/services/errors.ts
+/**
+* A capability verb: whatever the engine, a signer port or the validator
+* rejects with reaches the caller as a `PluginError`.
+*/
+const verb = (run) => async (...args) => {
+	try {
+		return await run(...args);
+	} catch (error) {
+		throw (0, _embedpdf_core.toPluginError)("signature", error);
+	}
+};
+//#endregion
+//#region src/read/judging.ts
+/**
+* The judging verbs: re-reading the facts, validating, and the byte-level
+* questions a verdict rests on (what changed after a signature, the exact
+* revision it covers).
+*/
+function createJudging(ctx, { store }, { validate }, signatures, { getSignature, getVerdict }) {
+	const { requireSignatures } = store;
+	return { api: {
+		refresh: verb(async (options) => {
+			await ctx.cancellable(options?.signal, signatures.refresh());
+			return signatures.get().snapshot;
+		}),
+		validate: verb(validate),
+		validateField: verb(async (field, options) => {
+			await validate(options);
+			const verdict = getVerdict(field);
+			if (!verdict) throw new _embedpdf_core.PluginError("not-found", "signature", "no signed field at that address");
+			return verdict;
+		}),
+		analyzeChanges: verb(async (input, options) => ctx.cancellable(options?.signal, requireSignatures().analyze(input))),
+		readRevision: verb(async (target, options) => {
+			ctx.assertAllowed("doc.download", "signature.readRevision");
+			const service = requireSignatures();
+			let revisionIndex;
+			if ("revisionIndex" in target) revisionIndex = target.revisionIndex;
+			else {
+				const signature = getSignature(target);
+				if (!signature?.signed || signature.revisionIndex === null) throw new _embedpdf_core.PluginError("not-found", "signature", "no signed revision at that address");
+				revisionIndex = signature.revisionIndex;
+			}
+			return ctx.cancellable(options?.signal, service.downloadRevision(revisionIndex));
+		})
+	} };
+}
+//#endregion
+//#region src/model.ts
+/**
+* The signature plugin's state, in two kinds. Session state (the last
+* validation, the sign-here target, the busy flag) changes only through the
+* pure transitions below. The signature facts (the snapshot and the parked
+* two-phase signing) are engine data: a mirror folds them from confirmed
+* document events with {@link foldSignatureEvent}.
+*/
+const initialSignatureState = () => ({
+	verdicts: null,
+	target: null,
+	busy: false
+});
+const sameFieldRef = (left, right) => left.kind === "objectNumber" && right.kind === "objectNumber" ? left.objectNumber === right.objectNumber : left.kind === "fqn" && right.kind === "fqn" ? left.name === right.name : false;
+function setVerdicts(state, verdicts) {
+	return state.verdicts === verdicts ? state : {
+		...state,
+		verdicts
+	};
+}
+/** Name the sign-here target; the same field (by ref) changes nothing. */
+function setTarget(state, field) {
+	const current = state.target;
+	if (current === field || current && field && sameFieldRef(current, field)) return state;
+	return {
+		...state,
+		target: field
+	};
+}
+function setBusy(state, busy) {
+	return state.busy === busy ? state : {
+		...state,
+		busy
+	};
+}
+/**
+* The verdicts that turned invalid because of unsaved edits: judged on the
+* working copy, invalid now, and not already invalid in the previous
+* validation (a signature that held, or was never judged).
+*/
+function newlyInvalidated(previous, next) {
+	return next.filter((verdict) => {
+		if (verdict.modifications.basis !== "working-copy" || verdict.summary !== "invalid") return false;
+		const before = previous?.find((earlier) => earlier.signature.index === verdict.signature.index);
+		return !before || before.summary !== "invalid";
+	});
+}
+const emptySignatureRecord = () => ({
+	snapshot: null,
+	pending: null
+});
+const hasSignedField = (snapshot) => snapshot?.signatures.some((signature) => signature.signed) ?? false;
+/** The result a `signatures.completed` event carries, without the event envelope. */
+const completeResultOf = (event) => ({
+	status: event.status,
+	signature: event.signature,
+	version: event.version,
+	previous: event.previous,
+	protection: event.protection,
+	meta: event.meta
+});
+/**
+* A completed signing, applied to the snapshot: the sealed field's facts and
+* the protection now in force. The revisions change as well; the
+* `document.versioned` event that follows every completion reloads them.
+*/
+function withCompletedSignature(snapshot, event) {
+	if (!snapshot) return null;
+	const sealed = event.signature;
+	return {
+		...snapshot,
+		signatures: snapshot.signatures.map((signature) => sameFieldRef(signature.field, sealed.field) ? sealed : signature),
+		protection: event.protection
+	};
+}
+/** Events that change which signature fields exist; the snapshot lists fields, so it is re-read. */
+const FIELD_SET_EVENTS = /* @__PURE__ */ new Set([
+	"forms.created",
+	"forms.deleted",
+	"forms.widgetAdded",
+	"forms.widgetRemoved",
+	"forms.repaired"
+]);
+/** Apply one confirmed document event to the signature facts. Pure, the same for every origin. */
+function foldSignatureEvent(record, event) {
+	switch (event.type) {
+		case "signatures.prepared": return {
+			...record,
+			pending: {
+				signingId: event.signingId,
+				field: event.field
+			}
+		};
+		case "signatures.cancelled": return record.pending ? {
+			...record,
+			pending: null
+		} : record;
+		case "signatures.completed": return {
+			snapshot: withCompletedSignature(record.snapshot, event),
+			pending: null
+		};
+		default: return FIELD_SET_EVENTS.has(event.type) ? (0, _embedpdf_core.reload)() : record;
+	}
+}
+//#endregion
+//#region src/read/signatures.ts
+/** Reads over the signature facts and the last validation. The lists are
+*  memoized per snapshot so they stay reference-stable for selectors. */
+const EMPTY_SIGNATURES = [];
+const EMPTY_FIELDS = [];
+/** The widget an address names, or null for a field ref. */
+const widgetOf = (field) => {
+	if (!("kind" in field)) return field;
+	if (field.kind === "objectNumber" && "page" in field) return field;
+	return null;
+};
+const isFieldRef = (field) => "kind" in field && (field.kind === "fqn" || field.kind === "objectNumber" && !("page" in field));
+function createSignatureReads(ctx, { authority, siblings }, signatures) {
+	const { form } = siblings;
+	const snapshot = () => signatures.get().snapshot;
+	const lists = (0, _embedpdf_core.memo)(() => [snapshot(), ctx.state.get().verdicts], (current, verdicts) => {
+		if (!current) return {
+			signed: EMPTY_SIGNATURES,
+			unsigned: EMPTY_FIELDS
+		};
+		const verdictOf = (signature) => verdicts?.find((verdict) => verdict.signature.index === signature.index) ?? null;
+		return {
+			signed: current.signatures.filter((signature) => signature.signed).map((signature) => ({
+				...signature,
+				verdict: verdictOf(signature)
+			})),
+			unsigned: current.signatures.filter((signature) => !signature.signed).map((signature) => signature.field)
+		};
+	});
+	const getSignature = (field) => {
+		const current = snapshot();
+		if (!current) return null;
+		const widget = widgetOf(field);
+		if (widget) {
+			const byWidget = current.signatures.find((signature) => signature.widget?.objectNumber === widget.objectNumber);
+			if (byWidget) return byWidget;
+			const owner = form.getFieldForWidget(widget);
+			return owner ? getSignature(owner.ref) : null;
+		}
+		if (!isFieldRef(field)) return null;
+		return current.signatures.find((signature) => field.kind === "fqn" ? signature.fieldName === field.name : sameFieldRef(signature.field, field)) ?? null;
+	};
+	const getVerdict = (field) => {
+		const signature = getSignature(field);
+		if (!signature) return null;
+		return ctx.state.get().verdicts?.find((verdict) => verdict.signature.index === signature.index) ?? null;
+	};
+	return {
+		snapshot,
+		getSignature,
+		getVerdict,
+		api: {
+			getSnapshot: snapshot,
+			getStatus: signatures.getStatus,
+			listSignatures: () => lists().signed,
+			listUnsignedFields: () => lists().unsigned,
+			getSignature,
+			listVerdicts: () => ctx.state.get().verdicts,
+			getVerdict,
+			getProtection: () => snapshot()?.protection ?? null,
+			getPending: () => signatures.get().pending,
+			isBusy: () => ctx.state.get().busy,
+			getMode: authority.mode,
+			getTarget: () => ctx.state.get().target
+		}
+	};
+}
+//#endregion
+//#region src/services/authority.ts
+/**
+* The mode and the key, read from the settings where they're used, so a change
+* applies at once; and who may sign or fill in which field, by the field's
+* group (`ctx.allowsField`), as the engine checks it.
+*/
+function createAuthority(ctx, { form }) {
+	const settings = ctx.settings();
+	const mode = () => {
+		const { mode: chosen, key } = settings.get();
+		return chosen ?? (key ? "sign" : "visual");
+	};
+	const resolveKey = async (override) => {
+		const key = override ?? settings.get().key;
+		if (!key) throw new _embedpdf_core.PluginError("invalid-input", "signature", "no key: set the `key` setting or pass one with the call");
+		return typeof key === "function" ? key() : key;
+	};
+	/** Whether the session may `action` this field; `false` for a field the form doesn't have. */
+	const allowsField = (action, ref) => {
+		const field = form.get(ref);
+		return field !== null && ctx.allowsField(action, field);
+	};
+	/** Refuse a write to this field the session may not make, before anything starts. */
+	const assertAllowedField = (action, ref, operation) => {
+		const field = form.get(ref);
+		if (field) ctx.assertAllowedField(action, field, operation);
+	};
+	return {
+		mode,
+		resolveKey,
+		assertAllowedField,
+		canSign: (field) => allowsField("sign", field),
+		canFill: (field) => allowsField("fill", field),
+		canCertify: () => settings.get().allowCertify && ctx.allows("doc.sign.certify"),
+		canReadRevision: () => ctx.allows("doc.download")
+	};
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
+	const events = {
+		signed: ctx.events.source(),
+		filled: ctx.events.source(),
+		cleared: ctx.events.source(),
+		validated: ctx.events.source(),
+		protectionChanged: ctx.events.source(),
+		invalidationPredicted: ctx.events.source(),
+		targetChanged: ctx.events.source(),
+		signRequested: ctx.events.source(),
+		inspectionRequested: ctx.events.source()
+	};
+	ctx.state.onChange(({ previous, next }) => {
+		if (previous.target !== next.target) events.targetChanged.emit({ field: next.target });
+		if (previous.verdicts !== next.verdicts && next.verdicts) for (const verdict of newlyInvalidated(previous.verdicts, next.verdicts)) events.invalidationPredicted.emit({
+			field: verdict.signature.field,
+			detail: verdict.modifications.detail ?? ""
+		});
+	});
+	return events;
+}
+//#endregion
+//#region src/services/marks.ts
+/** Marks → the one-page appearance bytes the engine draws into a field. */
+function createMarks({ stamp }) {
+	const bytesOf = async (source) => new Uint8Array((await (0, _embedpdf_engine_core_runtime.resolveBinarySource)(source)).bytes);
+	const markBytes = async (mark) => {
+		if ("assetId" in mark) {
+			const bytes = stamp()?.readAssetBytes(mark.assetId);
+			if (!bytes) throw new _embedpdf_core.PluginError("not-found", "signature", `unknown mark '${mark.assetId}'`);
+			return bytes;
+		}
+		return bytesOf(mark.source);
+	};
+	return {
+		bytesOf,
+		markBytes
+	};
+}
+//#endregion
+//#region src/services/siblings.ts
+/** The sibling planes: the form plugin (required), the stamp and annotation plugins (optional). */
+function resolveSiblings(ctx) {
+	return {
+		form: ctx.get(_embedpdf_plugin_form_contract.FormToken),
+		stamp: () => ctx.tryGet(_embedpdf_plugin_stamp_contract.StampToken),
+		annotation: () => ctx.tryGet(_embedpdf_plugin_annotation_contract.AnnotationToken)
+	};
+}
+//#endregion
+//#region src/services/store.ts
+/** The busy bracket and the engine doors every area needs. */
+function createStore(ctx) {
+	const withBusy = async (work) => {
+		ctx.state.update(setBusy, true);
+		try {
+			return await work();
+		} finally {
+			ctx.state.update(setBusy, false);
+		}
+	};
+	const requireSignatures = () => {
+		const signatures = ctx.doc.signatures;
+		if (!signatures) throw new _embedpdf_core.PluginError("unsupported", "signature", "this engine does not implement signatures");
+		return signatures;
+	};
+	const documentId = () => {
+		const id = ctx.documentId;
+		if (!id) throw new _embedpdf_core.PluginError("not-ready", "signature", "no document id");
+		return id;
+	};
+	return {
+		withBusy,
+		requireSignatures,
+		documentId
+	};
+}
+//#endregion
+//#region src/services/index.ts
+/**
+* Plugin-private services every area is built on (not the kernel): the
+* events, the busy bracket and engine doors, authority, the sibling plugins
+* and mark resolution.
+*/
+function createServices(ctx) {
+	const siblings = resolveSiblings(ctx);
+	return {
+		events: createEvents(ctx),
+		store: createStore(ctx),
+		authority: createAuthority(ctx, siblings),
+		siblings,
+		marks: createMarks(siblings)
+	};
+}
+//#endregion
+//#region src/sync/signatures.ts
+/** Edits of the working copy: what a save would write changed, so a verdict may have too. */
+const WORKING_COPY_EDITS = /* @__PURE__ */ new Set([
+	"annotations.created",
+	"annotations.updated",
+	"annotations.deleted",
+	"annotations.reordered",
+	"forms.valueSet",
+	"forms.updated"
+]);
+const sameProtection = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+function createSignaturesMirror(ctx, { events }, { validateNow, revalidateSoon }) {
+	const { signed, protectionChanged } = events;
+	/** Parked signings the engine answered it does not know: no event will clear them. */
+	const disowned = /* @__PURE__ */ new Set();
+	const mirror = ctx.mirror({
+		name: "signatures",
+		initial: emptySignatureRecord,
+		load: async (doc) => {
+			const snapshot = doc.signatures ? await doc.signatures.list() : null;
+			const pending = mirror.get().pending;
+			return { value: {
+				snapshot,
+				pending: pending && !disowned.has(pending.signingId) ? pending : null
+			} };
+		},
+		fold: foldSignatureEvent,
+		changed: ({ cause, event, previous, next }) => {
+			const protection = next.snapshot?.protection ?? null;
+			if (protection && !sameProtection(previous.snapshot?.protection ?? null, protection)) protectionChanged.emit({ protection });
+			if (event?.type === "signatures.completed") signed.emit({
+				field: event.signature.field,
+				result: completeResultOf(event),
+				origin: event.origin
+			});
+			if (!hasSignedField(next.snapshot)) return;
+			if (cause === "load") validateNow();
+			else if (previous.snapshot !== next.snapshot) revalidateSoon();
+		}
+	});
+	return {
+		mirror,
+		/**
+		* The engine does not know this parked signing (its cancel answered
+		* `unknown`), so no event will ever clear it: reload without it.
+		*/
+		disown(signingId) {
+			disowned.add(signingId);
+			return mirror.refresh();
+		},
+		connect() {
+			ctx.listen(ctx.doc.events, (event) => {
+				if (WORKING_COPY_EDITS.has(event.type) && hasSignedField(mirror.get().snapshot)) revalidateSoon();
+			});
+		}
+	};
+}
+//#endregion
+//#region src/sync/validation.ts
+const REVALIDATE_DELAY_MS = 300;
+function createValidation(ctx, { events }) {
+	const { validated } = events;
+	const settings = ctx.settings();
+	const validate = async (options) => {
+		if (!ctx.doc.signatures) return [];
+		const { validateSignatures } = await ctx.cancellable(options?.signal, import("@embedpdf/core-signature"));
+		const verdicts = await ctx.cancellable(options?.signal, validateSignatures(ctx.doc, {
+			trust: settings.get().trust,
+			at: options?.at,
+			until: options?.until ?? "working-copy"
+		}));
+		ctx.state.update(setVerdicts, verdicts);
+		validated.emit({ verdicts });
+		return verdicts;
+	};
+	let cancelRevalidate = null;
+	const cancelScheduled = () => {
+		cancelRevalidate?.();
+		cancelRevalidate = null;
+	};
+	const validateInBackground = () => {
+		validate().catch((error) => globalThis.console?.error("[signature] validation failed:", error));
+	};
+	return {
+		validate,
+		/** Judge now; a scheduled re-judgement is superseded. */
+		validateNow: () => {
+			cancelScheduled();
+			validateInBackground();
+		},
+		/** Judge once the edits pause. */
+		revalidateSoon: () => {
+			cancelScheduled();
+			cancelRevalidate = ctx.clock.after(REVALIDATE_DELAY_MS, () => {
+				cancelRevalidate = null;
+				validateInBackground();
+			});
+		}
+	};
+}
+//#endregion
 //#region src/blank-page.ts
 const OBJECTS = [
 	"<< /Type /Catalog /Pages 2 0 R >>",
@@ -31,431 +534,376 @@ function blankPagePdf() {
 	return new Uint8Array(cached);
 }
 //#endregion
-//#region src/capability.ts
-const sameRef = (a, b) => a.kind === "objectNumber" && b.kind === "objectNumber" ? a.fieldObjectNumber === b.fieldObjectNumber : a.kind === "fqn" && b.kind === "fqn" ? a.name === b.name : false;
-const sameProtection = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-function createSignatureCapability(ctx, config = {}) {
-	const form = ctx.get(_embedpdf_plugin_form_contract.FormToken);
-	const changed = (0, _embedpdf_core.createEventHook)((error) => globalThis.console?.error("[signature] listener failed:", error));
-	ctx.cleanup(() => changed.dispose());
-	const state = () => ctx.getState();
-	const requireDoc = () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[signature] no document bound");
-		return doc;
+//#region src/write/fill.ts
+/** Visual fills: the mark becomes the widget's appearance, nothing is sealed. */
+function createFills(ctx, { events, store, marks, authority }, { getSignature }, target) {
+	const { filled, cleared } = events;
+	const { withBusy } = store;
+	const { markBytes } = marks;
+	const setAppearance = async (field, pdf, options) => {
+		const forms = ctx.doc.forms;
+		if (!forms.setSignatureAppearance) throw new _embedpdf_core.PluginError("unsupported", "signature", "this engine cannot draw into a signature field");
+		const signature = getSignature(field);
+		if (signature?.signed) throw new _embedpdf_core.PluginError("conflict", "signature", `'${signature.fieldName}' is signed`);
+		await ctx.cancellable(options?.signal, forms.setSignatureAppearance(field, { pdf }));
 	};
-	const requireSignatures = () => {
-		const doc = requireDoc();
-		if (!doc.signatures) throw new Error("[signature] this engine does not implement signatures");
-		return {
-			doc,
-			signatures: doc.signatures
-		};
-	};
-	const stamp = () => ctx.tryGet(_embedpdf_plugin_stamp_contract.StampToken);
-	const documentId = () => {
-		const id = ctx.documentId;
-		if (!id) throw new Error("[signature] no document id");
-		return id;
-	};
-	const mode = () => config.mode ?? (config.signer ? "sign" : "visual");
-	const resolveSigner = async () => {
-		const signer = config.signer;
-		if (!signer) throw new Error("[signature] no signer configured (mode \"sign\" needs one)");
-		return typeof signer === "function" ? signer() : signer;
-	};
-	const allows = (cap) => ctx.doc?.security.allows(cap) ?? false;
-	const refresh = async () => {
-		const doc = ctx.doc;
-		if (!doc?.signatures) {
-			ctx.dispatch({
-				type: "SNAPSHOT",
-				snapshot: null
-			});
-			return null;
-		}
-		const before = state().snapshot?.protection ?? null;
-		const snapshot = await doc.signatures.list();
-		ctx.dispatch({
-			type: "SNAPSHOT",
-			snapshot
-		});
-		if (!sameProtection(before, snapshot.protection)) changed.emit({
-			type: "protectionChanged",
-			protection: snapshot.protection
+	const fillField = async (field, mark, options) => {
+		authority.assertAllowedField("fill", field, "signature.fillField");
+		return withBusy(async () => {
+			await setAppearance(field, await markBytes(mark), options);
+			target.clearIfTarget(field);
+			filled.emit({ field });
 		});
-		return snapshot;
-	};
-	const validate = async (opts) => {
-		const doc = ctx.doc;
-		if (!doc?.signatures) return [];
-		const verdicts = await (0, _embedpdf_core_signature.validateSignatures)(doc, {
-			trust: config.trust ?? null,
-			at: opts?.at,
-			until: opts?.until ?? "working-copy"
-		});
-		const before = state().verdicts;
-		ctx.dispatch({
-			type: "VERDICTS",
-			verdicts
-		});
-		changed.emit({
-			type: "validated",
-			verdicts
+	};
+	const clearField = async (field, options) => {
+		authority.assertAllowedField("fill", field, "signature.clearField");
+		return withBusy(async () => {
+			await setAppearance(field, blankPagePdf(), options);
+			cleared.emit({ field });
 		});
-		for (const v of verdicts) {
-			if (v.modifications.basis !== "working-copy" || v.summary !== "invalid") continue;
-			const was = before?.find((b) => b.signature.index === v.signature.index);
-			if (was && was.summary === "invalid") continue;
-			changed.emit({
-				type: "invalidating",
-				field: v.signature.field,
-				detail: v.modifications.detail ?? ""
-			});
-		}
-		return verdicts;
 	};
-	let revalidateTimer = null;
-	const revalidateSoon = () => {
-		if (!state().snapshot?.signatures.some((s) => s.signed)) return;
-		if (revalidateTimer) clearTimeout(revalidateTimer);
-		revalidateTimer = setTimeout(() => {
-			revalidateTimer = null;
-			validate().catch((error) => globalThis.console?.error("[signature] re-validation failed:", error));
-		}, 300);
-	};
-	ctx.cleanup(() => {
-		if (revalidateTimer) clearTimeout(revalidateTimer);
-	});
-	const analyze = (input) => requireSignatures().signatures.analyze(input);
-	const signatureOf = (field) => {
-		const snapshot = state().snapshot;
-		if (!snapshot) return null;
-		if ("annotObjectNumber" in field) {
-			const byWidget = snapshot.signatures.find((s) => s.widget?.annotObjectNumber === field.annotObjectNumber);
-			if (byWidget) return byWidget;
-			const owner = form.fieldForWidget(field.annotObjectNumber);
-			return owner ? signatureOf(owner.ref) : null;
+	return {
+		fillField,
+		api: {
+			fillField: verb(fillField),
+			clearField: verb(clearField)
 		}
-		return snapshot.signatures.find((s) => field.kind === "fqn" ? s.fieldName === field.name : sameRef(s.field, field)) ?? null;
 	};
-	const verdictOf = (field) => {
-		const signature = signatureOf(field);
-		if (!signature) return null;
-		return state().verdicts?.find((v) => v.signature.index === signature.index) ?? null;
+}
+//#endregion
+//#region src/write/place.ts
+/**
+* The destination rule and the sign-here flow: a mark over a field is
+* signed, drawn, or handed to the chrome by mode; a free placement is a
+* stamp (one placement law, the stamp plugin's).
+*/
+function createTarget(ctx, { events }, { getSignature }) {
+	const { inspectionRequested } = events;
+	/** One field, whether a ref names it by object number or by name. */
+	const sameField = (left, right) => {
+		if (sameFieldRef(left, right)) return true;
+		const signature = getSignature(left);
+		return signature !== null && signature.index === getSignature(right)?.index;
 	};
-	const bytesOf = async (source) => new Uint8Array((await (0, _embedpdf_engine_core_runtime.resolveBinarySource)(source)).bytes);
-	const markBytes = async (mark) => {
-		if ("assetId" in mark) {
-			const bytes = stamp()?.assetBytes(mark.assetId);
-			if (!bytes) throw new Error(`[signature] unknown mark '${mark.assetId}'`);
-			return bytes;
-		}
-		return bytesOf(mark.source);
+	/** A field that was just signed or filled is no longer the target. */
+	const clearIfTarget = (field) => {
+		const current = ctx.state.get().target;
+		if (current && sameField(current, field)) ctx.state.update(setTarget, null);
 	};
-	const withBusy = async (work) => {
-		ctx.dispatch({
-			type: "BUSY",
-			busy: true
-		});
-		try {
-			return await work();
-		} finally {
-			ctx.dispatch({
-				type: "BUSY",
-				busy: false
-			});
+	return {
+		clearIfTarget,
+		api: {
+			setTarget: (field) => ctx.state.update(setTarget, field),
+			requestInspection: (field) => inspectionRequested.emit({ field })
 		}
 	};
-	const signField = (input) => withBusy(async () => {
-		const { doc } = requireSignatures();
-		const signer = await resolveSigner();
-		const subject = signer.kind === "raw" && signer.certificateChain[0] ? (0, _embedpdf_core_signature.certificateCommonName)(signer.certificateChain[0]) : null;
-		const attribution = {
-			...subject ? { name: subject } : {},
-			...input.attribution
-		};
-		const appearance = input.appearance ? await bytesOf(input.appearance) : await markBytes(input.mark);
-		const result = await (0, _embedpdf_core_signature.sign)(doc, {
-			field: input.field,
-			signer,
-			attribution,
-			certify: input.certify,
-			lock: input.lock,
-			appearance: {
-				pdf: appearance,
-				pageIndex: 0
-			}
-		});
-		if (state().target && sameRef(state().target, input.field)) setTarget(null);
-		await refresh();
-		validate().catch((error) => globalThis.console?.error("[signature] validation after signing failed:", error));
-		changed.emit({
-			type: "signed",
-			field: input.field,
-			result
-		});
-		return result;
-	});
-	const setAppearance = async (field, pdf) => {
-		const doc = requireDoc();
-		if (!doc.forms.setSignatureAppearance) throw new Error("[signature] this engine cannot draw into a signature field");
-		const signature = signatureOf(field);
-		if (signature?.signed) throw new Error(`[signature] '${signature.fieldName}' is signed`);
-		await doc.forms.setSignatureAppearance(field, {
-			pdf,
-			pageIndex: 0
-		});
-		await form.refresh();
-	};
-	const fillField = (field, mark) => withBusy(async () => {
-		await setAppearance(field, await markBytes(mark));
-		if (state().target && sameRef(state().target, field)) setTarget(null);
-		changed.emit({
-			type: "filled",
-			field
-		});
-	});
-	const clearField = (field) => withBusy(async () => {
-		await setAppearance(field, blankPagePdf());
-		changed.emit({
-			type: "cleared",
-			field
-		});
-	});
-	const placeMark = async (mark, target) => {
+}
+function createPlacement(ctx, { events, store, authority, siblings }, { snapshot }, { sign }, { fillField }) {
+	const { signRequested } = events;
+	const { documentId } = store;
+	const { mode } = authority;
+	const { stamp, annotation } = siblings;
+	const settings = ctx.settings();
+	const placeMark = async (mark, target, options) => {
 		if (!("field" in target)) {
 			if ("assetId" in mark) {
 				const library = stamp();
-				if (!library) throw new Error("[signature] no stamp plugin to place an asset");
-				await library.placeAsset(documentId(), mark.assetId, target);
-			} else await ctx.get(_embedpdf_plugin_annotation_contract.AnnotationToken).placeStamp({ source: mark.source }, target);
-			return;
+				if (!library) throw new _embedpdf_core.PluginError("unsupported", "signature", "no stamp plugin to place an asset");
+				return {
+					kind: "placed",
+					annotation: (await library.placeAsset(mark.assetId, target, {
+						documentId: documentId(),
+						signal: options?.signal
+					})).annotation.ref
+				};
+			}
+			const annotations = annotation();
+			if (!annotations) throw new _embedpdf_core.PluginError("unsupported", "signature", "no annotation plugin to place a mark");
+			return {
+				kind: "placed",
+				annotation: (await annotations.stamps.place({ source: mark.source }, target, options)).annotation.ref
+			};
 		}
 		switch (mode()) {
 			case "sign":
-				if (config.allowCertify && !state().snapshot?.signatures.some((s) => s.signed)) {
-					changed.emit({
-						type: "ask",
+				if (settings.get().allowCertify && !hasSignedField(snapshot())) {
+					signRequested.emit({
 						field: target.field,
 						mark
 					});
-					return;
+					return {
+						kind: "requested",
+						field: target.field
+					};
 				}
-				await signField({
+				return {
+					kind: "signed",
 					field: target.field,
-					mark
-				});
-				return;
+					result: await sign({
+						field: target.field,
+						mark
+					}, options)
+				};
 			case "visual":
-				await fillField(target.field, mark);
-				return;
+				await fillField(target.field, mark, options);
+				return {
+					kind: "filled",
+					field: target.field
+				};
 			case "ask":
-				changed.emit({
-					type: "ask",
+				signRequested.emit({
 					field: target.field,
 					mark
 				});
-				return;
+				return {
+					kind: "requested",
+					field: target.field
+				};
 		}
 	};
-	const setTarget = (field) => {
-		const current = state().target;
-		if (current === field || current && field && sameRef(current, field)) return;
-		ctx.dispatch({
-			type: "TARGET",
-			field
+	return { api: { placeMark: verb(placeMark) } };
+}
+//#endregion
+//#region src/write/sign.ts
+/**
+* The act of sealing. One-shot: `sign` (prepare, the key, complete,
+* through `@embedpdf/core-signature`). Two-phase: `prepareSignature` parks
+* the signing and hands out the digest; `completeSignature` seals it with a
+* detached CMS; `cancelPending` cancels. The parked signing, the sealed
+* field's facts and `onSigned` come from the confirmed events the engine
+* publishes for each step (`sync/signatures.ts`), for every session alike.
+*/
+function createSigning(ctx, { store, authority, marks }, { api: reads }, target, signatures) {
+	const { withBusy, requireSignatures } = store;
+	const { resolveKey, assertAllowedField } = authority;
+	const { bytesOf, markBytes } = marks;
+	/** Two-phase signings this session prepared: the version each one must complete against. */
+	const prepared = /* @__PURE__ */ new Map();
+	const cancelled = (signal) => new _embedpdf_core.PluginError("operation-cancelled", "signature", "signing cancelled", { cause: signal.reason });
+	/**
+	* The document as one-shot signing sees it, with the caller's signal checked
+	* right before the seal: a signal that fired by then leaves nothing signed
+	* (the signing gives the prepared candidate up), and after it the seal is
+	* done.
+	*/
+	const sealUnlessCancelled = (signal) => {
+		const signatures = requireSignatures();
+		if (!signal) return ctx.doc;
+		return { signatures: {
+			prepare: (input) => signatures.prepare(input),
+			cancel: (signingId) => signatures.cancel(signingId),
+			complete: (input) => {
+				if (signal.aborted) return Promise.reject(cancelled(signal));
+				return signatures.complete(input);
+			}
+		} };
+	};
+	/**
+	* Refused before anything starts: signing the field (`doc.sign`, or
+	* `fields:sign` for its group), and `doc.sign.certify` for a certification.
+	*/
+	const assertMaySign = (input, operation) => {
+		assertAllowedField("sign", input.field, operation);
+		if (input.certify) ctx.assertAllowed("doc.sign.certify", operation);
+	};
+	const appearanceOf = async (input) => {
+		if (input.appearance) return bytesOf(input.appearance);
+		if (input.mark) return markBytes(input.mark);
+		return null;
+	};
+	const sign = async (input, options) => {
+		assertMaySign(input, "signature.sign");
+		if (options?.signal?.aborted) throw cancelled(options.signal);
+		return withBusy(async () => {
+			const doc = sealUnlessCancelled(options?.signal);
+			const { certificateCommonName, sign: signDocument } = await import("@embedpdf/core-signature");
+			const key = await resolveKey(input.key);
+			const subject = key.kind === "raw" && key.certificateChain[0] ? certificateCommonName(key.certificateChain[0]) : null;
+			const signer = {
+				...subject ? { name: subject } : {},
+				...input.signer
+			};
+			const appearance = await appearanceOf(input);
+			const result = await signDocument(doc, {
+				field: input.field,
+				key,
+				signer,
+				certify: input.certify,
+				lock: input.lock,
+				appearance: { pdf: appearance }
+			});
+			target.clearIfTarget(input.field);
+			return result;
 		});
-		changed.emit({
-			type: "target",
-			field
+	};
+	const prepareSignature = async (input, options) => {
+		assertMaySign(input, "signature.prepareSignature");
+		return withBusy(async () => {
+			const signatures = requireSignatures();
+			const appearance = await appearanceOf(input);
+			const pending = signatures.prepare({
+				field: input.field,
+				signer: input.signer,
+				certify: input.certify,
+				lock: input.lock,
+				subFilter: input.subFilter,
+				digest: input.digest,
+				...appearance ? { appearance: { pdf: appearance } } : {}
+			});
+			const result = await ctx.cancellable(options?.signal, pending);
+			prepared.set(result.signingId, result);
+			return result;
 		});
 	};
-	const doc = ctx.doc;
-	if (doc) {
-		const unsubscribe = doc.events.subscribe((event) => {
-			switch (event.type) {
-				case "signature.prepared":
-					ctx.dispatch({
-						type: "PENDING",
-						pending: {
-							signingId: event.signingId,
-							field: event.field
-						}
-					});
-					return;
-				case "signature.aborted":
-					ctx.dispatch({
-						type: "PENDING",
-						pending: null
-					});
-					return;
-				case "signature.completed":
-					ctx.dispatch({
-						type: "PENDING",
-						pending: null
-					});
-					return;
-				case "document.versioned":
-				case "stream.desynced":
-					refresh().then(() => validate()).catch((error) => globalThis.console?.error("[signature] refresh failed:", error));
-					return;
-				case "form.fieldCreated":
-				case "form.fieldDeleted":
-				case "form.widgetAttached":
-				case "form.widgetDetached":
-				case "form.imported":
-				case "form.repaired":
-					refresh().then(() => revalidateSoon()).catch((error) => globalThis.console?.error("[signature] refresh failed:", error));
-					return;
-				case "annotation.created":
-				case "annotation.updated":
-				case "annotation.deleted":
-				case "annotation.moved":
-				case "form.valueChanged":
-				case "form.fieldUpdated":
-				case "form.effectsApplied":
-					revalidateSoon();
-					return;
-				default: return;
-			}
+	const completeSignature = async (signingId, cms, options) => {
+		if (options?.signal?.aborted) throw cancelled(options.signal);
+		return withBusy(async () => {
+			const signatures = requireSignatures();
+			const parked = prepared.get(signingId);
+			if (!parked) throw new _embedpdf_core.PluginError("not-found", "signature", `no signing '${signingId}' was prepared in this session`);
+			const result = await signatures.complete({
+				signingId,
+				cms,
+				expectedVersion: parked.expectedVersion
+			});
+			prepared.delete(signingId);
+			target.clearIfTarget(result.signature.field);
+			return result;
 		});
-		ctx.cleanup(unsubscribe);
-	}
+	};
+	const cancelPending = async (options) => {
+		const pending = reads.getPending();
+		if (!pending) return;
+		assertAllowedField("sign", pending.field, "signature.cancelPending");
+		const { status } = await ctx.cancellable(options?.signal, requireSignatures().cancel(pending.signingId));
+		prepared.delete(pending.signingId);
+		if (status === "unknown") await signatures.disown(pending.signingId);
+	};
 	return {
-		snapshot: () => state().snapshot,
-		verdicts: () => state().verdicts,
-		protection: () => state().snapshot?.protection ?? null,
-		pending: () => state().pending,
-		target: () => state().target,
-		busy: () => state().busy,
-		mode,
-		signatureOf,
-		verdictOf,
-		canSign: () => allows("doc.sign") && config.signer != null,
-		canFill: () => allows("doc.forms.fill") && ctx.doc?.forms.setSignatureAppearance != null,
-		canCertify: () => config.allowCertify === true && allows("doc.sign.certify"),
-		signField,
-		fillField,
-		clearField,
-		placeMark,
-		setTarget,
-		inspect: (field) => changed.emit({
-			type: "inspect",
-			field
-		}),
-		refresh,
-		validate,
-		analyze,
-		revisionBytes: (revisionIndex) => requireSignatures().signatures.revisionBytes(revisionIndex),
-		onChanged: changed.on
+		sign,
+		api: {
+			sign: verb(sign),
+			prepareSignature: verb(prepareSignature),
+			completeSignature: verb(completeSignature),
+			cancelPending: verb(cancelPending)
+		}
 	};
 }
 //#endregion
-//#region src/handler.ts
+//#region src/controller.ts
 /**
-* The armed mark over a field. The annotation plugin places an armed stamp
-* on click (`annotation-place`, priority 95) and selects an existing
-* annotation under the pointer before that (`annotation-edit`, 100 — a
-* widget is an annotation). This handler sits above BOTH, enabled for the
-* armed stamp's tool only, and captures exactly when the armed asset is a
-* person's mark (a library of kind `signatures`) and the pointer is over a
-* signature field: then the destination decides — the mark goes INTO the
-* field (`placeMark` by mode) instead of onto the page. Everywhere else it
-* declines and the click stays a stamp placement, as in Preview.
+* The signature controller: the composition root. It builds the plugin's
+* services once, wires each area with the services it declares, and
+* assembles the capability from the areas' API slices. No behavior lives
+* here: every verb and read has a home in `read/`, `write/` or `sync/`.
 */
-function createArmedMarkHandler(documentId, signature, form, stamp) {
+function createSignatureController(ctx) {
+	const services = createServices(ctx);
+	const { events, authority } = services;
+	const settings = ctx.settings();
+	const validation = createValidation(ctx, services);
+	const signatures = createSignaturesMirror(ctx, services, validation);
+	const reads = createSignatureReads(ctx, services, signatures.mirror);
+	const judging = createJudging(ctx, services, validation, signatures.mirror, reads);
+	const target = createTarget(ctx, services, reads);
+	const signing = createSigning(ctx, services, reads, target, signatures);
+	const fills = createFills(ctx, services, reads, target);
+	const placement = createPlacement(ctx, services, reads, signing, fills);
+	const api = (0, _embedpdf_core.composeApi)("signature", [
+		settings.api,
+		reads.api,
+		judging.api,
+		target.api,
+		signing.api,
+		fills.api,
+		placement.api,
+		{
+			canSign: authority.canSign,
+			canFill: authority.canFill,
+			canCertify: authority.canCertify,
+			canReadRevision: authority.canReadRevision,
+			onSigned: events.signed.on,
+			onFilled: events.filled.on,
+			onCleared: events.cleared.on,
+			onValidated: events.validated.on,
+			onProtectionChanged: events.protectionChanged.on,
+			onInvalidationPredicted: events.invalidationPredicted.on,
+			onTargetChanged: events.targetChanged.on,
+			onSignRequested: events.signRequested.on,
+			onInspectionRequested: events.inspectionRequested.on
+		}
+	]);
 	return {
-		id: "signature:armed-mark-on-field",
-		priority: _embedpdf_plugin_annotation_contract.ANNOTATION_EDIT_PRIORITY + 1,
-		enabledFor: (tool) => tool.id === _embedpdf_plugin_annotation_contract.ARMED_STAMP_TOOL_ID,
-		onDown: (sample) => {
-			if (!sample.page) return false;
-			const armed = stamp.armedAsset(documentId);
-			if (!armed || stamp.library(armed.libraryId)?.kind !== "signatures") return false;
-			const hit = form.widgetAt(sample.page.pon, sample.page.point);
-			if (!hit || hit.field.family !== "signature") return false;
-			if (signature.signatureOf(hit.field.ref)?.signed || hit.field.valueEntry.kind !== "none") return true;
-			stamp.disarm(documentId);
-			signature.placeMark({ assetId: armed.id }, { field: hit.field.ref }).catch((error) => globalThis.console?.error("[signature] placing the mark failed:", error));
-			return true;
+		api,
+		connect() {
+			signatures.connect();
+			connectSiblings(ctx, api);
 		}
 	};
 }
 //#endregion
-//#region src/reducer.ts
-const initialSignatureState = () => ({
-	snapshot: null,
-	verdicts: null,
-	target: null,
-	pending: null,
-	busy: false
-});
-function signatureReducer(state, action) {
-	switch (action.type) {
-		case "SNAPSHOT": return {
-			...state,
-			snapshot: action.snapshot
-		};
-		case "VERDICTS": return {
-			...state,
-			verdicts: action.verdicts
-		};
-		case "TARGET": return {
-			...state,
-			target: action.field
-		};
-		case "PENDING": return {
-			...state,
-			pending: action.pending
-		};
-		case "BUSY": return {
-			...state,
-			busy: action.busy
-		};
-		default: return state;
-	}
-}
-//#endregion
 //#region src/signature.plugin.ts
 /**
-* The signature plugin — the ACT of signing, document-scoped. It owns no
+* The signature plugin: the act of signing, document-scoped. It owns no
 * mark: marks are stamp-library assets (or bytes the embedder brings), and
-* the mark IS the appearance the engine draws into the field. Signing goes
-* through `@embedpdf/core-signature` with the configured signer port; the
-* engine seals; on the cloud the server publishes the new version.
+* the mark is the appearance the engine draws into the field. Signing goes
+* through `@embedpdf/core-signature` with the `key` setting's signer port;
+* the engine seals; on the cloud the server publishes the new version.
 *
 * With the interaction hub and the stamp plugin present, an armed mark from
 * a `signatures` library dropped over an unsigned signature field goes into
-* the field (sign / visual fill / ask, by mode) instead of onto the page.
+* the field (sign, visual fill or ask, by mode) instead of onto the page.
+* `config` is the settings the app registers, over {@link SIGNATURE_DEFAULTS}.
 */
-const signaturePlugin = (config = {}) => (0, _embedpdf_core.definePlugin)({
+const signaturePlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	id: "signature",
 	token: require_contract.SignatureToken,
 	scope: "document",
 	requires: [_embedpdf_plugin_form_contract.FormToken],
 	optional: [
-		_embedpdf_plugin_interaction_contract.InteractionToken,
+		_embedpdf_plugin_interaction_contract_host.InteractionToken,
 		_embedpdf_plugin_stamp_contract.StampToken,
 		_embedpdf_plugin_annotation_contract.AnnotationToken
 	],
-	initialState: initialSignatureState,
-	reduce: signatureReducer,
-	capability: (ctx) => createSignatureCapability(ctx, config),
-	init: (ctx) => {
-		const signature = ctx.get(require_contract.SignatureToken);
-		signature.refresh().then((snapshot) => snapshot?.signatures.some((s) => s.signed) ? signature.validate() : null).catch((error) => globalThis.console?.error("[signature] initial read failed:", error));
-		const interaction = ctx.tryGet(_embedpdf_plugin_interaction_contract.InteractionToken);
-		const stamp = ctx.tryGet(_embedpdf_plugin_stamp_contract.StampToken);
-		if (interaction && stamp && ctx.documentId) ctx.cleanup(interaction.registerHandler(createArmedMarkHandler(ctx.documentId, signature, ctx.get(_embedpdf_plugin_form_contract.FormToken), stamp)));
+	state: initialSignatureState,
+	settings: {
+		defaults: require_contract.SIGNATURE_DEFAULTS,
+		registered: config,
+		whole: ["key", "trust"]
+	},
+	create: createSignatureController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The signatures page's State table as code: what `useSignatureState()`
+* returns, and the same fields in every other framework.
+*/
+const NO_SIGNATURES = Object.freeze([]);
+const signatureState = (0, _embedpdf_core.defineState)(require_contract.SignatureToken, {
+	read: (signature) => ({
+		signatures: signature.listSignatures(),
+		protection: signature.getProtection(),
+		target: signature.getTarget(),
+		busy: signature.isBusy(),
+		pending: signature.getPending(),
+		status: signature.getStatus()
+	}),
+	empty: {
+		signatures: NO_SIGNATURES,
+		protection: null,
+		target: null,
+		busy: false,
+		pending: null,
+		status: "idle"
 	}
 });
 //#endregion
 exports.INITIALS_MARK_NAME = require_contract.INITIALS_MARK_NAME;
 exports.SIGNATURES_LIBRARY_KIND = require_contract.SIGNATURES_LIBRARY_KIND;
+exports.SIGNATURE_DEFAULTS = require_contract.SIGNATURE_DEFAULTS;
 exports.SIGNATURE_MARK_NAME = require_contract.SIGNATURE_MARK_NAME;
 exports.SignatureToken = require_contract.SignatureToken;
-exports.createArmedMarkHandler = createArmedMarkHandler;
 Object.defineProperty(exports, "createTestSigner", {
 	enumerable: true,
 	get: function() {
@@ -488,6 +936,8 @@ Object.defineProperty(exports, "remoteSigner", {
 	}
 });
 exports.signaturePlugin = signaturePlugin;
+exports.signatureState = signatureState;
+exports.signerRowsOf = require_contract.signerRowsOf;
 Object.defineProperty(exports, "webCryptoSigner", {
 	enumerable: true,
 	get: function() {