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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AbortError, EMPTY_TRANSFER, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PAGE_INSERT_BLANK_MAX_COUNT, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, UNKNOWN_WEAK_ANNOTATION_STATE, appearanceImpactOf, buildPageTextLayout, buildSnippet, charMapViolation, charRangeForTextOffsets, decodeSubmitFormFlags, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, pdfQuadBounds, revisionTokensEqual, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, textSegmentsForRange, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
+import { AbortError, EMPTY_TRANSFER, EdgeResolver, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PAGE_INSERT_BLANK_MAX_COUNT, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, SIGNATURE_POLICY_VERSION, UNKNOWN_WEAK_ANNOTATION_STATE, USAGE_INCOMPLETE, appearanceImpactOf, assessmentOf, buildPageTextLayout, buildSnippet, charMapViolation, charRangeForTextOffsets, combine, decodeSubmitFormFlags, deriveProtection, evaluateStep, fieldLockFor, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, parsePdfValue, pdfQuadBounds, restrictionsFor, revisionTokensEqual, richTextParagraphsFromPlainText, richTextPlainText, sameEffectiveValue, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, textSegmentsForRange, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
 import { NULL_PTR } from "@embedpdf/engine-runtime";
 //#region src/runtime/lifecycle/bootstrap.ts
 const initialized = /* @__PURE__ */ new WeakSet();
@@ -270,8 +270,108 @@ var SessionEventPublisher = class {
 	}
 };
 //#endregion
+//#region src/runtime/memory/scratch.ts
+/**
+* Allocate a scratch buffer, run `body` with it, and always free it.
+*
+* Every PDFium out-parameter call follows the same shape: malloc a
+* buffer, hand its pointer to the native function, read the result back,
+* free the buffer. Hand-rolling that `try/finally` at each call site is
+* how leaks and copy-paste bugs creep in, so it lives here once.
+*/
+function withScratch(mem, bytes, body) {
+	const ptr = mem.alloc(bytes);
+	try {
+		return body(ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+/**
+* Like {@link withScratch} but for native calls that take several
+* out-parameters at once (e.g. `FPDFAnnot_GetColor` with one pointer per
+* channel). Buffers are freed in reverse allocation order.
+*/
+function withScratchN(mem, sizes, body) {
+	const ptrs = sizes.map((size) => mem.alloc(size));
+	try {
+		return body(ptrs);
+	} finally {
+		for (let i = ptrs.length - 1; i >= 0; i--) mem.free(ptrs[i]);
+	}
+}
+//#endregion
+//#region src/runtime/memory/strings.ts
+/**
+* Read a PDFium UTF-16LE string getter that uses the standard
+* (probe length, allocate, read) ABI. `call(buf, capacity)` must invoke
+* the native function and return the length in BYTES including the
+* trailing NUL (the value PDFium reports when `capacity` is 0).
+*
+* `emptyAs` decides what a present-but-empty value (`len === 2`, a lone
+* UTF-16 NUL) decodes to. This is the one knob different callers actually
+* disagree on: document Info strings treat `''` as a real value, whereas
+* a page label of `''` is indistinguishable from "absent" and reads as
+* `null`. Making it a parameter keeps that decision explicit instead of
+* forking the buffer dance.
+*
+* Returns `null` when the value is absent (`len <= 0`).
+*/
+function readUtf16String(mem, call, emptyAs = "") {
+	const len = call(NULL_PTR, 0);
+	if (len <= 0) return null;
+	if (len === 2) return emptyAs;
+	return withScratch(mem, len, (buf) => {
+		if (call(buf, len) <= 0) return null;
+		return mem.readU16String(buf);
+	});
+}
+/**
+* UTF-8 sibling of {@link readUtf16String} for the handful of native
+* getters that return UTF-8 (e.g. `EPDF_GetMetaKeyName`). UTF-8 has no
+* fixed empty-NUL width to special-case, so an empty value decodes to
+* `''`; absent (`len <= 0`) is `null`.
+*/
+function readUtf8String(mem, call) {
+	const len = call(NULL_PTR, 0);
+	if (len <= 0) return null;
+	return withScratch(mem, len, (buf) => {
+		if (call(buf, len) <= 0) return null;
+		return mem.readU8String(buf);
+	});
+}
+/**
+* Write side of the UTF-16 convention: encode `value` into a scratch
+* buffer, hand the pointer to `set`, and always free it. `set` returns
+* the native call's success flag, which is propagated.
+*/
+function writeUtf16String(mem, value, set) {
+	const ptr = mem.writeU16String(value);
+	try {
+		return set(ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+/**
+* A NUL-terminated UTF-8 copy of `value` in runtime memory for the duration
+* of `fn` (a `FPDF_STRING` parameter: a file system path, say).
+*/
+function withUtf8CString(mem, value, fn) {
+	const encoded = new TextEncoder().encode(value);
+	const bytes = new Uint8Array(encoded.byteLength + 1);
+	bytes.set(encoded);
+	const ptr = mem.alloc(bytes.byteLength);
+	try {
+		mem.writeBytes(ptr, bytes);
+		return fn(ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+//#endregion
 //#region src/document-session/lifecycle/PdfDocumentOpener.ts
-const FPDF_ERR_PASSWORD$1 = 4;
+const FPDF_ERR_PASSWORD$2 = 4;
 var CloseStack = class {
 	constructor() {
 		_defineProperty(this, "actions", []);
@@ -306,7 +406,7 @@ function openFatMemoryDocument(runtime, bytes, password = null) {
 		mem.writeBytes(dataPtr, bytes);
 		const docPtr = fn.FPDF_LoadMemDocument64(dataPtr, bytes.byteLength, password ?? "");
 		if (!docPtr) {
-			if (fn.FPDF_GetLastError() === FPDF_ERR_PASSWORD$1) throw password ? new EngineError(EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new EngineError(EngineErrorCode.DocPasswordRequired, "document requires a password");
+			if (fn.FPDF_GetLastError() === FPDF_ERR_PASSWORD$2) throw password ? new EngineError(EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new EngineError(EngineErrorCode.DocPasswordRequired, "document requires a password");
 			throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to open document");
 		}
 		setRuntimeOwnerPermissionsIfEncrypted(runtime, docPtr);
@@ -314,6 +414,11 @@ function openFatMemoryDocument(runtime, bytes, password = null) {
 		return {
 			kind: "fat-memory",
 			docPtr,
+			source: {
+				base: null,
+				layer: null,
+				password
+			},
 			close: () => stack.close()
 		};
 	} catch (error) {
@@ -331,6 +436,7 @@ function openLayerDocument(runtime, base, layer = { kind: "fresh" }, password =
 		mem.poke(statusPtr, "i32", -1);
 		let docPtr;
 		if (layer.kind === "fresh") docPtr = fn.EPDFLayer_OpenLayer(base.basePtr, NULL_PTR, password ?? "", statusPtr);
+		else if (layer.kind === "artifact-file" && runtime.kind === "native") docPtr = withUtf8CString(mem, layer.path, (pathPtr) => fn.EPDFLayer_OpenLayerArtifactFromPath(base.basePtr, pathPtr, password ?? "", statusPtr));
 		else {
 			layerAccess = layer.kind === "artifact-file" ? runtime.fileAccess.fromNodeFile(layer.path) : runtime.fileAccess.fromMemory(layer.bytes);
 			stack.push(() => layerAccess?.close());
@@ -340,9 +446,22 @@ function openLayerDocument(runtime, base, layer = { kind: "fresh" }, password =
 		if (!docPtr || status !== 0) throw layerOpenError(status);
 		setRuntimeOwnerPermissionsIfEncrypted(runtime, docPtr);
 		stack.push(() => fn.FPDF_CloseDocument(docPtr));
+		const baseSource = base.kind === "file" && base.path !== void 0 ? {
+			kind: "file",
+			key: base.key,
+			path: base.path
+		} : {
+			kind: "memory",
+			key: base.key
+		};
 		return {
 			kind: "layer",
 			docPtr,
+			source: {
+				base: baseSource,
+				layer,
+				password
+			},
 			close: () => stack.close()
 		};
 	} catch (error) {
@@ -495,22 +614,13 @@ var LocalRevisionAuthority = class {
 };
 //#endregion
 //#region src/document-session/DocumentSession.ts
-/**
-* Owns the lifecycle of a single open PDFium document and the v3
-* identity machinery: page registry (pageObjectNumber <-> pageIndex),
-* `RevisionAuthority` (per-page generation counters), and `PagePtrPool`
-* (refcounted pagePtr access).
-*
-* Both the local browser Worker and the server worker_thread instantiate
-* this exactly the same way; the only thing that differs is the
-* underlying PdfRuntimeModule (WASM vs native).
-*/
 var DocumentSession = class {
 	constructor(runtime, sessionId) {
 		this.runtime = runtime;
 		_defineProperty(this, "docPtr", null);
 		_defineProperty(this, "closeDocument", null);
 		_defineProperty(this, "_kind", null);
+		_defineProperty(this, "_source", null);
 		_defineProperty(this, "_sessionId", void 0);
 		_defineProperty(this, "recordsByObjectNumber", /* @__PURE__ */ new Map());
 		_defineProperty(this, "recordsByIndex", /* @__PURE__ */ new Map());
@@ -518,6 +628,59 @@ var DocumentSession = class {
 		_defineProperty(this, "revisions", null);
 		_defineProperty(this, "mutationSeqCounter", 0);
 		_defineProperty(this, "pages", null);
+		_defineProperty(
+			this,
+			/**
+			* 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",
+			"protect"
+		);
+		_defineProperty(
+			this,
+			/**
+			* 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",
+			"layer"
+		);
+		_defineProperty(
+			this,
+			/** The password the document was opened with; signing candidates open with the same one. */
+			"password",
+			null
+		);
+		_defineProperty(
+			this,
+			/**
+			* 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",
+			true
+		);
+		_defineProperty(this, "loadedSeq", 0);
+		_defineProperty(this, "plainSha256", null);
+		_defineProperty(
+			this,
+			/** The signing candidate parked by `signatures.prepare`, if any. */
+			"pendingSigning",
+			null
+		);
+		_defineProperty(
+			this,
+			/** The last completed signing, so a replayed `complete` answers `already-completed`. */
+			"lastCompletion",
+			null
+		);
 		_defineProperty(this, "parkedBytes", null);
 		_defineProperty(this, "retained", []);
 		this._sessionId = sessionId ?? generateSessionId();
@@ -528,6 +691,15 @@ var DocumentSession = class {
 	get kind() {
 		return this._kind;
 	}
+	/**
+	* 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() {
+		if (!this._source) throw new EngineError(EngineErrorCode.DocNotOpen, "document is not open");
+		return this._source;
+	}
 	isOpen() {
 		return this.docPtr !== null;
 	}
@@ -542,9 +714,76 @@ var DocumentSession = class {
 		this.docPtr = handle.docPtr;
 		this.closeDocument = () => handle.close();
 		this._kind = handle.kind;
+		this._source = handle.source;
 		this.revisions = new LocalRevisionAuthority(this._sessionId);
 		this.pages = new PagePtrPool(this.runtime, handle.docPtr);
 		this.parkedBytes = null;
+		this.loadedSeq = this.mutationSeqCounter;
+	}
+	/**
+	* 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() {
+		return this.mutationSeqCounter !== this.loadedSeq;
+	}
+	/** Cached hash of the current loaded bytes, or `null` when not computed since the last load. */
+	cachedPlainSha256() {
+		return this.plainSha256 && this.plainSha256.loadedSeq === this.loadedSeq ? this.plainSha256.sha256 : null;
+	}
+	rememberPlainSha256(sha256) {
+		this.plainSha256 = {
+			loadedSeq: this.loadedSeq,
+			sha256
+		};
+	}
+	/**
+	* 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) {
+		if (!this.docPtr) {
+			handle.close();
+			throw new EngineError(EngineErrorCode.DocNotOpen, "no document to replace");
+		}
+		const previousPages = Array.from(this.recordsByObjectNumber.keys());
+		let firstError = null;
+		try {
+			this.pages?.closeAll();
+		} catch (error) {
+			firstError = error;
+		}
+		try {
+			this.closeDocument?.();
+		} catch (error) {
+			firstError ?? (firstError = error);
+		}
+		this.docPtr = handle.docPtr;
+		this.closeDocument = () => handle.close();
+		this._kind = handle.kind;
+		this._source = handle.source;
+		this.pages = new PagePtrPool(this.runtime, handle.docPtr);
+		this.recordsByIndex.clear();
+		this.recordsByObjectNumber.clear();
+		this.fullyEnumerated = false;
+		for (const pon of previousPages) this.requireRevisions().bump(pon);
+		this.mutationSeqCounter++;
+		this.loadedSeq = this.mutationSeqCounter;
+		this.pendingSigning = null;
+		if (firstError) throw firstError;
+	}
+	/** The two publish fences a candidate is built on. */
+	versionRef(baseSha256) {
+		return {
+			baseSha256,
+			editsVersion: this.mutationSeqCounter
+		};
 	}
 	/**
 	* Park this session in the password-locked state: the document could not
@@ -704,6 +943,11 @@ var DocumentSession = class {
 		} finally {
 			this.pages = null;
 		}
+		if (this.pendingSigning?.saved.kind === "file") try {
+			this.runtime.fileWrite.removeFile(this.pendingSigning.saved.path);
+		} catch (error) {
+			firstError ?? (firstError = error);
+		}
 		try {
 			this.closeDocument?.();
 		} catch (error) {
@@ -712,7 +956,10 @@ var DocumentSession = class {
 			this.closeDocument = null;
 			this.docPtr = null;
 			this._kind = null;
+			this._source = null;
 			this.parkedBytes = null;
+			this.pendingSigning = null;
+			this.lastCompletion = null;
 			this.revisions?.clear();
 			this.revisions = null;
 			this.recordsByIndex.clear();
@@ -738,6 +985,17 @@ function generateSessionId() {
 }
 //#endregion
 //#region src/document-session/lifecycle/BaseDocumentRegistry.ts
+const FPDF_ERR_PASSWORD$1 = 4;
+/**
+* A password failure is a recoverable STATE the caller can act on (prompt,
+* unlock), never a generic open failure — the same distinction
+* `openFatMemoryDocument` draws, so a plain-bytes open that becomes a base
+* parks and unlocks exactly like it always did.
+*/
+function baseOpenError(runtime, password) {
+	if (runtime.fn.FPDF_GetLastError() === FPDF_ERR_PASSWORD$1) return password ? new EngineError(EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new EngineError(EngineErrorCode.DocPasswordRequired, "document requires a password");
+	return new EngineError(EngineErrorCode.DocOpenFailed, "failed to open base document");
+}
 var BaseDocumentRegistry = class {
 	constructor(runtime) {
 		this.runtime = runtime;
@@ -753,10 +1011,17 @@ var BaseDocumentRegistry = class {
 		try {
 			mem.writeBytes(dataPtr, opts.bytes);
 			const basePtr = fn.EPDF_LoadMemBaseDocument64(dataPtr, opts.bytes.byteLength, opts.password ?? "");
-			if (!basePtr) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to open base document");
+			if (!basePtr) throw baseOpenError(this.runtime, opts.password);
 			setRuntimeOwnerPermissionsIfEncrypted(this.runtime, basePtr);
 			stack.push(() => fn.EPDF_ReleaseBaseDocument(basePtr));
-			return this.insert(opts.key, basePtr, () => stack.close());
+			this.supplyKnownSha(basePtr, opts.knownSha256);
+			return this.insert({
+				key: opts.key,
+				kind: "memory",
+				basePtr,
+				refs: 1,
+				close: () => stack.close()
+			});
 		} catch (error) {
 			stack.close();
 			throw error;
@@ -772,15 +1037,50 @@ var BaseDocumentRegistry = class {
 			access = this.runtime.fileAccess.fromNodeFile(opts.path);
 			stack.push(() => access?.close());
 			const basePtr = fn.EPDF_LoadBaseDocument(access.ptr, opts.password ?? "");
-			if (!basePtr) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to open base document");
+			if (!basePtr) throw baseOpenError(this.runtime, opts.password);
 			setRuntimeOwnerPermissionsIfEncrypted(this.runtime, basePtr);
 			stack.push(() => fn.EPDF_ReleaseBaseDocument(basePtr));
-			return this.insert(opts.key, basePtr, () => stack.close());
+			this.supplyKnownSha(basePtr, opts.knownSha256);
+			return this.insert({
+				key: opts.key,
+				kind: "file",
+				path: opts.path,
+				basePtr,
+				refs: 1,
+				close: () => stack.close()
+			});
 		} catch (error) {
 			stack.close();
 			throw error;
 		}
 	}
+	/**
+	* 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) {
+		return this.retain(key);
+	}
+	/**
+	* 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.
+	*/
+	supplyKnownSha(basePtr, sha256Hex) {
+		if (!sha256Hex || !/^[0-9a-fA-F]{64}$/.test(sha256Hex)) return;
+		const { mem, fn } = this.runtime;
+		const bytes = /* @__PURE__ */ new Uint8Array(32);
+		for (let i = 0; i < 32; i++) bytes[i] = parseInt(sha256Hex.slice(i * 2, i * 2 + 2), 16);
+		const ptr = mem.alloc(32);
+		try {
+			mem.writeBytes(ptr, bytes);
+			fn.EPDF_SetBaseDocumentSha256(basePtr, ptr);
+		} finally {
+			mem.free(ptr);
+		}
+	}
 	releaseAll() {
 		const entries = Array.from(this.entries.values());
 		this.entries.clear();
@@ -802,20 +1102,16 @@ var BaseDocumentRegistry = class {
 		entry.refs++;
 		return this.handleFor(entry);
 	}
-	insert(key, basePtr, close) {
-		const entry = {
-			key,
-			basePtr,
-			refs: 1,
-			close
-		};
-		this.entries.set(key, entry);
+	insert(entry) {
+		this.entries.set(entry.key, entry);
 		return this.handleFor(entry);
 	}
 	handleFor(entry) {
 		let released = false;
 		return {
 			key: entry.key,
+			kind: entry.kind,
+			...entry.path !== void 0 ? { path: entry.path } : {},
 			basePtr: entry.basePtr,
 			release: () => {
 				if (released) return;
@@ -831,90 +1127,6 @@ var BaseDocumentRegistry = class {
 	}
 };
 //#endregion
-//#region src/runtime/memory/scratch.ts
-/**
-* Allocate a scratch buffer, run `body` with it, and always free it.
-*
-* Every PDFium out-parameter call follows the same shape: malloc a
-* buffer, hand its pointer to the native function, read the result back,
-* free the buffer. Hand-rolling that `try/finally` at each call site is
-* how leaks and copy-paste bugs creep in, so it lives here once.
-*/
-function withScratch(mem, bytes, body) {
-	const ptr = mem.alloc(bytes);
-	try {
-		return body(ptr);
-	} finally {
-		mem.free(ptr);
-	}
-}
-/**
-* Like {@link withScratch} but for native calls that take several
-* out-parameters at once (e.g. `FPDFAnnot_GetColor` with one pointer per
-* channel). Buffers are freed in reverse allocation order.
-*/
-function withScratchN(mem, sizes, body) {
-	const ptrs = sizes.map((size) => mem.alloc(size));
-	try {
-		return body(ptrs);
-	} finally {
-		for (let i = ptrs.length - 1; i >= 0; i--) mem.free(ptrs[i]);
-	}
-}
-//#endregion
-//#region src/runtime/memory/strings.ts
-/**
-* Read a PDFium UTF-16LE string getter that uses the standard
-* (probe length, allocate, read) ABI. `call(buf, capacity)` must invoke
-* the native function and return the length in BYTES including the
-* trailing NUL (the value PDFium reports when `capacity` is 0).
-*
-* `emptyAs` decides what a present-but-empty value (`len === 2`, a lone
-* UTF-16 NUL) decodes to. This is the one knob different callers actually
-* disagree on: document Info strings treat `''` as a real value, whereas
-* a page label of `''` is indistinguishable from "absent" and reads as
-* `null`. Making it a parameter keeps that decision explicit instead of
-* forking the buffer dance.
-*
-* Returns `null` when the value is absent (`len <= 0`).
-*/
-function readUtf16String(mem, call, emptyAs = "") {
-	const len = call(NULL_PTR, 0);
-	if (len <= 0) return null;
-	if (len === 2) return emptyAs;
-	return withScratch(mem, len, (buf) => {
-		if (call(buf, len) <= 0) return null;
-		return mem.readU16String(buf);
-	});
-}
-/**
-* UTF-8 sibling of {@link readUtf16String} for the handful of native
-* getters that return UTF-8 (e.g. `EPDF_GetMetaKeyName`). UTF-8 has no
-* fixed empty-NUL width to special-case, so an empty value decodes to
-* `''`; absent (`len <= 0`) is `null`.
-*/
-function readUtf8String(mem, call) {
-	const len = call(NULL_PTR, 0);
-	if (len <= 0) return null;
-	return withScratch(mem, len, (buf) => {
-		if (call(buf, len) <= 0) return null;
-		return mem.readU8String(buf);
-	});
-}
-/**
-* Write side of the UTF-16 convention: encode `value` into a scratch
-* buffer, hand the pointer to `set`, and always free it. `set` returns
-* the native call's success flag, which is propagated.
-*/
-function writeUtf16String(mem, value, set) {
-	const ptr = mem.writeU16String(value);
-	try {
-		return set(ptr);
-	} finally {
-		mem.free(ptr);
-	}
-}
-//#endregion
 //#region src/features/metadata/internal/readMetadataText.ts
 /**
 * Read a key from the document's Info dictionary. Returns null if the key
@@ -1731,7 +1943,8 @@ var PagesReader = class {
 			});
 			return {
 				pageCount: pages.length,
-				pages
+				pages,
+				namedPages: readNamedPages(fn, mem, docPtr)
 			};
 		});
 	}
@@ -1796,6 +2009,41 @@ function readUserUnit(fn, mem, docPtr, index, userUnitPtr) {
 function readLabel(fn, mem, docPtr, index) {
 	return readUtf16String(mem, (buf, capacity) => fn.FPDF_GetPageLabel(docPtr, index, buf, capacity), null) || null;
 }
+const NAMED_PAGE_TREES = [0, 1];
+const NAMED_PAGE_KIND_PAGE = 0;
+const NAMED_PAGE_KIND_TEMPLATE = 1;
+/**
+* The catalog's `/Names /Pages` and `/Names /Templates` registrations, in
+* tree order, each value classified by the fork (page / template /
+* dangling). Page-identity data like `label`, so it ships inside the same
+* snapshot — a registration is only meaningful against the page set that
+* contains its target.
+*/
+function readNamedPages(fn, mem, docPtr) {
+	const entries = [];
+	withScratchN(mem, [4, 4], ([objNumPtr, kindPtr]) => {
+		for (const tree of NAMED_PAGE_TREES) {
+			const count = fn.EPDFDoc_GetNamedPageCount(docPtr, tree);
+			for (let index = 0; index < count; index++) {
+				const name = readUtf16String(mem, (buf, capacity) => fn.EPDFDoc_GetNamedPageAt(docPtr, tree, index, buf, capacity, objNumPtr, kindPtr), "");
+				if (name === null) continue;
+				const objectNumber = Number(mem.peek(objNumPtr, "i32")) >>> 0;
+				const kind = Number(mem.peek(kindPtr, "i32"));
+				entries.push({
+					name,
+					target: kind === NAMED_PAGE_KIND_PAGE ? {
+						kind: "page",
+						pageObjectNumber: objectNumber
+					} : kind === NAMED_PAGE_KIND_TEMPLATE ? {
+						kind: "template",
+						objectNumber
+					} : { kind: "dangling" }
+				});
+			}
+		}
+	});
+	return entries;
+}
 //#endregion
 //#region src/features/pages/PagesMutator.ts
 /**
@@ -1943,19 +2191,51 @@ var PagesMutator = class {
 			cache: null
 		};
 	}
-	/** Shared input check: non-empty, no duplicate PONs. */
-	requireUniquePons(op, pageObjectNumbers) {
-		if (pageObjectNumbers.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, `${op} requires at least one page`);
-		const seen = /* @__PURE__ */ new Set();
-		for (const pon of pageObjectNumbers) {
-			if (seen.has(pon)) throw new EngineError(EngineErrorCode.InvalidArg, `${op} was given duplicate page object number ${pon}`);
-			seen.add(pon);
-		}
+	/**
+	* Register `name` → page in `/Names /Pages` (create, or replace what the
+	* key points at); with `replace`, drop that other key first — a rename as
+	* one job. Named pages are LAYOUT: page identity and order are untouched
+	* (no registry refresh, no revision bumps) and the fresh snapshot is
+	* returned like `move()`.
+	*/
+	setName(input, signal) {
+		throwIfAborted(signal);
+		if (input.name.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, "pages.setName requires a non-empty name");
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		this.session.recordByObjectNumber(input.pageObjectNumber);
+		if (input.replace !== void 0 && input.replace !== input.name && input.replace.length > 0) writeUtf16String(mem, input.replace, (ptr) => fn.EPDFDoc_RemoveNamedPage(docPtr, ptr));
+		if (!writeUtf16String(mem, input.name, (ptr) => fn.EPDFDoc_SetNamedPage(docPtr, ptr, input.pageObjectNumber))) throw new EngineError(EngineErrorCode.Unknown, `EPDFDoc_SetNamedPage rejected '${input.name}' for page ${input.pageObjectNumber}`);
+		return {
+			layout: new PagesReader(this.runtime, this.session).read(signal),
+			cache: null
+		};
+	}
+	/** Remove one `/Names /Pages` registration; the page stays. */
+	removeName(input, signal) {
+		throwIfAborted(signal);
+		if (input.name.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, "pages.removeName requires a non-empty name");
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		if (!writeUtf16String(mem, input.name, (ptr) => fn.EPDFDoc_RemoveNamedPage(docPtr, ptr))) throw new EngineError(EngineErrorCode.NotFound, `pages.removeName: no /Names /Pages registration '${input.name}'`);
+		return {
+			layout: new PagesReader(this.runtime, this.session).read(signal),
+			cache: null
+		};
+	}
+	/** Shared input check: non-empty, no duplicate PONs. */
+	requireUniquePons(op, pageObjectNumbers) {
+		if (pageObjectNumbers.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, `${op} requires at least one page`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const pon of pageObjectNumbers) {
+			if (seen.has(pon)) throw new EngineError(EngineErrorCode.InvalidArg, `${op} was given duplicate page object number ${pon}`);
+			seen.add(pon);
+		}
 	}
 };
 //#endregion
 //#region src/features/pages/PagesExtractor.ts
-const FPDF_NO_INCREMENTAL$1 = 2;
+const FPDF_NO_INCREMENTAL$2 = 2;
 /**
 * Export a subset of pages as a standalone PDF. A READ over the session:
 * `FPDF_ImportPagesByIndex` copies pages into a scratch document, so the
@@ -1994,7 +2274,7 @@ var PagesExtractor = class {
 			for (let i = 0; i < indices.length; i++) mem.poke(idxPtr, "i32", indices[i], 4 * i);
 			if (!fn.FPDF_ImportPagesByIndex(destPtr, srcPtr, idxPtr, indices.length, 0)) throw new EngineError(EngineErrorCode.Unknown, `FPDF_ImportPagesByIndex rejected the request (indices=[${indices.join(",")}])`);
 			mem.poke(sizePtr, "i32", 0);
-			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(destPtr, FPDF_NO_INCREMENTAL$1, sizePtr);
+			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(destPtr, FPDF_NO_INCREMENTAL$2, sizePtr);
 			const size = Number(mem.peek(sizePtr, "i32"));
 			if (!pdfPtr || size <= 0) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save extracted pages");
 			const bytes = mem.readBytes(pdfPtr, size);
@@ -2103,8 +2383,11 @@ var PagesInserter = class {
 //#endregion
 //#region src/features/annotations/internal/read/annotationReadContext.ts
 /** Build the read context both read paths (list loop, mutator read-back) use. */
-function readContextFor(session) {
-	return { docPtr: session.requireDocPtr() };
+function readContextFor(session, fonts) {
+	return {
+		docPtr: session.requireDocPtr(),
+		...fonts ? { fonts } : {}
+	};
 }
 //#endregion
 //#region src/features/annotations/internal/annotationFlagBits.ts
@@ -2546,6 +2829,13 @@ function readQuadPoints(fn, mem, annotPtr) {
 		return out;
 	});
 }
+/**
+* `/Name` as text, whatever its value (`EPDFAnnot_GetName`): a standard
+* icon/stamp name or a custom identifier. `null` when absent.
+*/
+function readAnnotName(fn, mem, annotPtr) {
+	return readUtf8String(mem, (buf, capacity) => fn.EPDFAnnot_GetName(annotPtr, buf, capacity));
+}
 //#endregion
 //#region src/features/annotations/internal/read/readAnnotationTransformMetadata.ts
 /**
@@ -2795,29 +3085,29 @@ function normalizeChecksum(raw) {
 //#endregion
 //#region src/features/annotations/internal/annotationIcon.ts
 /**
-* `/Name` icon ↔ `FPDF_ANNOT_NAME` enum code mapping for text and
-* file-attachment annotations (`EPDFAnnot_SetName` / `EPDFAnnot_GetName`).
-* Codes mirror the `FPDF_ANNOT_NAME` enum in `public/fpdf_annot.h` —
-* same pattern as `stampName.ts` (whose stamp block starts at 13, right
-* after these) keeping engine-core PDFium-free.
-*/
-const NOTE_ICON_TO_CODE = Object.freeze({
-	comment: 0,
-	key: 1,
-	note: 2,
-	help: 3,
-	"new-paragraph": 4,
-	paragraph: 5,
-	insert: 6
+* `/Name` icon vocabulary ↔ PDF name mapping for text and file-attachment
+* annotations (ISO 32000-2 tables 175 and 184). The wire speaks the
+* kebab-case ids; `EPDFAnnot_SetName` / `EPDFAnnot_GetName` speak the PDF
+* names. An unknown PDF name reads as the subtype's default (the reader
+* draws the default glyph for names it does not know — spec behavior).
+*/
+const NOTE_ICON_TO_NAME = Object.freeze({
+	comment: "Comment",
+	key: "Key",
+	note: "Note",
+	help: "Help",
+	"new-paragraph": "NewParagraph",
+	paragraph: "Paragraph",
+	insert: "Insert"
 });
-const NOTE_CODE_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(NOTE_ICON_TO_CODE).map(([icon, code]) => [code, icon])));
-const FILE_ICON_TO_CODE = Object.freeze({
-	graph: 7,
-	"push-pin": 8,
-	paperclip: 9,
-	tag: 10
+const NOTE_NAME_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(NOTE_ICON_TO_NAME).map(([icon, name]) => [name, icon])));
+const FILE_ICON_TO_NAME = Object.freeze({
+	graph: "Graph",
+	"push-pin": "PushPin",
+	paperclip: "Paperclip",
+	tag: "Tag"
 });
-const FILE_CODE_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(FILE_ICON_TO_CODE).map(([icon, code]) => [code, icon])));
+const FILE_NAME_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(FILE_ICON_TO_NAME).map(([icon, name]) => [name, icon])));
 //#endregion
 //#region src/features/annotations/internal/read/readFileAttachmentAnnotation.ts
 /** Default `/C` — matches the generator's default icon fill and the writer default. */
@@ -2839,7 +3129,7 @@ function readFileAttachment(fn, mem, annotPtr, base) {
 	const color = readAnnotColor(fn, mem, annotPtr) ?? { ...DEFAULT_FILE_ATTACHMENT_COLOR$1 };
 	const ca = readAnnotOpacity(fn, mem, annotPtr);
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
-	const icon = FILE_CODE_TO_ICON[fn.EPDFAnnot_GetName(annotPtr)] ?? DEFAULT_FILE_ATTACHMENT_ICON;
+	const icon = FILE_NAME_TO_ICON[readAnnotName(fn, mem, annotPtr) ?? ""] ?? DEFAULT_FILE_ATTACHMENT_ICON;
 	const attachmentPtr = fn.FPDFAnnot_GetFileAttachment(annotPtr);
 	const file = attachmentPtr ? readAttachmentFileInfo(fn, mem, attachmentPtr) : { name: "" };
 	return {
@@ -2938,6 +3228,206 @@ function standardFontFromCode(code) {
 	return CODE_TO_FONT[code] ?? "helvetica";
 }
 //#endregion
+//#region src/features/annotations/internal/richTextWire.ts
+const STANDARD_FACES = {
+	courier: {
+		family: "Courier",
+		weight: 400,
+		italic: false
+	},
+	"courier-bold": {
+		family: "Courier",
+		weight: 700,
+		italic: false
+	},
+	"courier-bold-oblique": {
+		family: "Courier",
+		weight: 700,
+		italic: true
+	},
+	"courier-oblique": {
+		family: "Courier",
+		weight: 400,
+		italic: true
+	},
+	helvetica: {
+		family: "Helvetica",
+		weight: 400,
+		italic: false
+	},
+	"helvetica-bold": {
+		family: "Helvetica",
+		weight: 700,
+		italic: false
+	},
+	"helvetica-bold-oblique": {
+		family: "Helvetica",
+		weight: 700,
+		italic: true
+	},
+	"helvetica-oblique": {
+		family: "Helvetica",
+		weight: 400,
+		italic: true
+	},
+	"times-roman": {
+		family: "Times",
+		weight: 400,
+		italic: false
+	},
+	"times-bold": {
+		family: "Times",
+		weight: 700,
+		italic: false
+	},
+	"times-bold-italic": {
+		family: "Times",
+		weight: 700,
+		italic: true
+	},
+	"times-italic": {
+		family: "Times",
+		weight: 400,
+		italic: true
+	},
+	symbol: {
+		family: "Symbol",
+		weight: 400,
+		italic: false
+	},
+	"zapf-dingbats": {
+		family: "ZapfDingbats",
+		weight: 400,
+		italic: false
+	}
+};
+/** Family names compare without case, spaces, hyphens and underscores
+*  (the engine's own rule): "Noto Sans" == "NotoSans" == "noto-sans". */
+function familyKey$1(family) {
+	return family.toLowerCase().replace(/[\s\-_'"]/g, "");
+}
+const STANDARD_FAMILY_KEYS = {
+	helvetica: "Helvetica",
+	arial: "Helvetica",
+	arialmt: "Helvetica",
+	sansserif: "Helvetica",
+	times: "Times",
+	timesroman: "Times",
+	timesnewroman: "Times",
+	timesnewromanpsmt: "Times",
+	serif: "Times",
+	courier: "Courier",
+	couriernew: "Courier",
+	couriernewpsmt: "Courier",
+	monospace: "Courier",
+	symbol: "Symbol",
+	zapfdingbats: "ZapfDingbats",
+	dingbats: "ZapfDingbats"
+};
+/**
+* The face a DTO `fontFamily` (or a rich run's `family`) asks for: a
+* standard font's family/weight/italic, a registered key's resolved
+* identity, or — for anything else — the string itself as a family name
+* (a face the document embeds, or one the engine will substitute).
+*/
+function faceForFreeTextFont(font, describe) {
+	if (isStandardFont(font)) {
+		const face = STANDARD_FACES[font];
+		return {
+			family: face.family,
+			weight: face.weight,
+			italic: face.italic
+		};
+	}
+	const registered = describe?.(font);
+	if (registered) return {
+		family: registered.familyName,
+		weight: registered.weight,
+		italic: registered.italic
+	};
+	return { family: font };
+}
+/**
+* The DTO `fontFamily` for a body face: the registered `key` whose identity
+* matches, else the standard font's kebab name, else the family itself.
+*/
+function freeTextFontForFace(face, keyForFace) {
+	const key = keyForFace?.(face.family, face.weight, face.italic);
+	if (key !== void 0) return key;
+	const standard = STANDARD_FAMILY_KEYS[familyKey$1(face.family)];
+	if (standard) {
+		const bold = face.weight >= 600;
+		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard && spec.weight >= 600 === bold && spec.italic === face.italic) return name;
+		for (const [name, spec] of Object.entries(STANDARD_FACES)) if (spec.family === standard) return name;
+	}
+	return face.family;
+}
+/** A run style or body with its `family` (and the weight/italic a key or
+*  standard name implies) rewritten to what the engine resolves by. */
+function withEngineFace(style, describe) {
+	if (style.family === void 0) return style;
+	const face = faceForFreeTextFont(style.family, describe);
+	const out = {
+		...style,
+		family: face.family
+	};
+	if (face.weight !== void 0 && style.weight === void 0) out.weight = face.weight;
+	if (face.italic !== void 0 && style.italic === void 0) out.italic = face.italic;
+	return out;
+}
+/** The engine's JSON for a write: the input shape with faces resolved. */
+function engineRichTextJson(input, describe) {
+	const body = input.body ? withEngineFace(input.body, describe) : void 0;
+	const paragraphs = input.paragraphs.map((p) => ({
+		...p,
+		runs: p.runs.map((r) => r.style ? {
+			...r,
+			style: withEngineFace(r.style, describe)
+		} : r)
+	}));
+	return JSON.stringify(body ? {
+		body,
+		paragraphs
+	} : { paragraphs });
+}
+/** The engine's JSON, parsed into the DTO shape (its `source` and
+*  `diagnostics` dropped). `null` when it is not what the engine writes. */
+function parseEngineRichText(json) {
+	let raw;
+	try {
+		raw = JSON.parse(json);
+	} catch {
+		return null;
+	}
+	if (!raw || typeof raw !== "object" || !raw.body || !Array.isArray(raw.paragraphs)) return null;
+	const { source: _source, ...bodyRest } = raw.body;
+	return {
+		body: bodyRest,
+		paragraphs: raw.paragraphs.map((p) => {
+			const { runs, ...props } = p;
+			return {
+				...props,
+				runs: (runs ?? []).map((r) => r)
+			};
+		})
+	};
+}
+/** Read an annotation's rich text through `EPDFAnnot_GetRichTextJSON`. */
+function readEngineRichText(fn, mem, annotPtr) {
+	const json = readUtf8String(mem, (buf, cap) => fn.EPDFAnnot_GetRichTextJSON(annotPtr, buf, cap));
+	return json ? parseEngineRichText(json) : null;
+}
+/**
+* A draft or patch that carries both `contents` and `richText` must agree:
+* `contents` is the plain projection of the rich text (plan §4.7). A stale
+* DTO echo fails loud here instead of quietly restoring old text.
+*/
+function assertRichTextAgreement(input) {
+	if (input.subtype !== "free-text" || input.richText === void 0) return;
+	if (input.contents === void 0 || input.contents === null) return;
+	if (input.contents !== richTextPlainText(input.richText)) throw new EngineError(EngineErrorCode.InvalidArg, "free-text: `contents` must equal the plain projection of `richText` when both are given");
+}
+//#endregion
 //#region src/features/annotations/internal/textAlignment.ts
 /**
 * `/Q` quadding codes (ISO 32000 §12.7.3.3) mapped to the wire-stable
@@ -3064,17 +3554,36 @@ const DEFAULT_FONT_SIZE$2 = 12;
 function colorsEqual(a, b) {
 	return a.r === b.r && a.g === b.g && a.b === b.b;
 }
-function readFreeText(fn, mem, annotPtr, base) {
+function readFreeText(fn, mem, annotPtr, base, _subtypeCode, ctx) {
 	const da = readDefaultAppearance(fn, mem, annotPtr);
 	const color = da?.color ?? { ...DEFAULT_FREETEXT_COLOR$1 };
-	const fontFamily = da ? standardFontFromCode(da.fontCode) : DEFAULT_STANDARD_FONT;
-	const fontSize = da && da.fontSize > 0 ? da.fontSize : DEFAULT_FONT_SIZE$2;
+	const rich = readEngineRichText(fn, mem, annotPtr);
+	const fonts = ctx?.fonts;
+	const fontFamily = rich ? freeTextFontForFace(rich.body, fonts ? (family, weight, italic) => fonts.keyForFace(family, weight, italic) : void 0) : da ? standardFontFromCode(da.fontCode) : DEFAULT_STANDARD_FONT;
+	const fontSize = rich && rich.body.size > 0 ? rich.body.size : da && da.fontSize > 0 ? da.fontSize : DEFAULT_FONT_SIZE$2;
+	const richText = rich ?? {
+		body: {
+			family: "Helvetica",
+			weight: 400,
+			italic: false,
+			size: fontSize,
+			color: "#000000",
+			decoration: [],
+			script: "normal",
+			letterSpacing: 0,
+			horizontalScale: 1,
+			align: "left",
+			dir: "ltr"
+		},
+		paragraphs: [{ runs: [{ text: base.contents ?? "" }] }]
+	};
 	const textColor = readAnnotColor(fn, mem, annotPtr, FPDFANNOT_COLORTYPE.TextColor);
 	const fontColor = textColor && !colorsEqual(textColor, color) ? textColor : void 0;
 	const background = readAnnotColor(fn, mem, annotPtr, FPDFANNOT_COLORTYPE.Color);
 	const ca = readAnnotOpacity(fn, mem, annotPtr);
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
-	const textAlign = textAlignmentFromCode(readTextAlignment(fn, annotPtr));
+	const quadding = textAlignmentFromCode(readTextAlignment(fn, annotPtr));
+	const textAlign = rich && rich.body.align !== "justify" ? rich.body.align : quadding;
 	const intent = freeTextIntentFromName(readIntent(fn, mem, annotPtr));
 	const points = readCalloutLine(fn, mem, annotPtr);
 	const calloutLine = points.length === 2 ? [points[0], points[1]] : points.length === 3 ? [
@@ -3093,6 +3602,7 @@ function readFreeText(fn, mem, annotPtr, base) {
 		fontFamily,
 		fontSize,
 		textAlign,
+		richText,
 		color,
 		...fontColor !== void 0 ? { fontColor } : {},
 		interiorColor: background ?? null,
@@ -3308,45 +3818,10 @@ function readSquare(fn, mem, annotPtr, base) {
 	};
 }
 //#endregion
-//#region src/features/annotations/internal/stampName.ts
-/**
-* Stamp `/Name` label ↔ `FPDF_ANNOT_NAME` enum code mapping for the
-* `EPDFAnnot_SetName` / `EPDFAnnot_GetName` fork helpers. Labels are the
-* PDF spec / Adobe literal name values (ISO 32000 §12.5.6.12 table 181
-* plus the Adobe SB/SH extended set the fork supports). Codes mirror the
-* `FPDF_ANNOT_NAME` enum in `public/fpdf_annot.h` — same pattern as
-* `lineEnding.ts` keeping engine-core PDFium-free.
-*/
-const STAMP_NAME_TO_CODE = Object.freeze({
-	Approved: 13,
-	Experimental: 14,
-	NotApproved: 15,
-	AsIs: 16,
-	Expired: 17,
-	NotForPublicRelease: 18,
-	Confidential: 19,
-	Final: 20,
-	Sold: 21,
-	Departmental: 22,
-	ForComment: 23,
-	TopSecret: 24,
-	Draft: 25,
-	ForPublicRelease: 26,
-	Completed: 27,
-	Void: 28,
-	PreliminaryResults: 29,
-	InformationOnly: 30,
-	Rejected: 31,
-	Witness: 32,
-	InitialHere: 33,
-	SignHere: 34,
-	Accepted: 35
-});
-const STAMP_CODE_TO_NAME = Object.freeze(Object.fromEntries(Object.entries(STAMP_NAME_TO_CODE).map(([name, code]) => [code, name])));
-//#endregion
 //#region src/features/annotations/internal/read/readStampAnnotation.ts
 /**
-* Stamp DTO: base + `/Name` label + transform metadata. The visual content
+* Stamp DTO: base + `/Name` (standard or custom identifier, verbatim) +
+* transform metadata. The visual content
 * stays in the `/AP` stream — rendered via `renderAppearanceImages()`,
 * never surfaced as DTO data.
 */
@@ -3356,16 +3831,11 @@ function readStamp(fn, mem, annotPtr, base) {
 	return {
 		...base,
 		subtype: "stamp",
-		name: readStampName(fn, mem, annotPtr),
+		name: readAnnotName(fn, mem, annotPtr),
 		...rotation != null ? { rotation } : {},
 		...unrotatedRect != null ? { unrotatedRect } : {}
 	};
 }
-function readStampName(fn, mem, annotPtr) {
-	const known = STAMP_CODE_TO_NAME[fn.EPDFAnnot_GetName(annotPtr)];
-	if (known !== void 0) return known;
-	return readAnnotString(fn, mem, annotPtr, "Name");
-}
 //#endregion
 //#region src/features/annotations/internal/annotationState.ts
 /**
@@ -3421,7 +3891,7 @@ function readText(fn, mem, annotPtr, base) {
 	const color = readAnnotColor(fn, mem, annotPtr) ?? { ...DEFAULT_NOTE_COLOR$1 };
 	const ca = readAnnotOpacity(fn, mem, annotPtr);
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
-	const icon = NOTE_CODE_TO_ICON[fn.EPDFAnnot_GetName(annotPtr)] ?? DEFAULT_NOTE_ICON;
+	const icon = NOTE_NAME_TO_ICON[readAnnotName(fn, mem, annotPtr) ?? ""] ?? DEFAULT_NOTE_ICON;
 	const stateRaw = readAnnotString(fn, mem, annotPtr, "State");
 	const stateModelRaw = readAnnotString(fn, mem, annotPtr, "StateModel");
 	return {
@@ -3645,18 +4115,18 @@ function pickReader(rawSubtypeCode) {
 * per session, closed before replacement and on session teardown via
 * {@link disposeFormModel}.
 */
-const cache$1 = /* @__PURE__ */ new WeakMap();
+const cache$2 = /* @__PURE__ */ new WeakMap();
 function acquireFormModel(runtime, session) {
 	const seq = session.mutationSeq();
-	const hit = cache$1.get(session);
+	const hit = cache$2.get(session);
 	if (hit && hit.seq === seq) return hit.ptr;
 	if (hit) {
 		runtime.fn.EPDFForm_CloseModel(hit.ptr);
-		cache$1.delete(session);
+		cache$2.delete(session);
 	}
 	const ptr = runtime.fn.EPDFForm_LoadModel(session.requireDocPtr());
 	if (ptr === NULL_PTR) throw new EngineError(EngineErrorCode.Unknown, "failed to build form model");
-	cache$1.set(session, {
+	cache$2.set(session, {
 		seq,
 		ptr
 	});
@@ -3664,10 +4134,10 @@ function acquireFormModel(runtime, session) {
 }
 /** Close and forget the session's cached model, if any. */
 function disposeFormModel(runtime, session) {
-	const hit = cache$1.get(session);
+	const hit = cache$2.get(session);
 	if (!hit) return;
 	runtime.fn.EPDFForm_CloseModel(hit.ptr);
-	cache$1.delete(session);
+	cache$2.delete(session);
 }
 //#endregion
 //#region src/features/forms/internal/readFormSnapshot.ts
@@ -3696,7 +4166,7 @@ const FF_EDIT = 1 << 18;
 const FF_MULTI_SELECT = 1 << 21;
 const FF_COMB = 1 << 24;
 const FF_RADIOS_IN_UNISON = 1 << 25;
-function readWide(runtime, call) {
+function readWide$1(runtime, call) {
 	return readUtf16String(runtime.mem, call) ?? "";
 }
 function readWideOrNull(runtime, call) {
@@ -3710,7 +4180,7 @@ function readToggleWidgets(runtime, model, fieldIndex) {
 		annotObjectNumber: fn.EPDFForm_GetFieldWidgetObjNum(model, fieldIndex, w),
 		pageObjectNumber: fn.EPDFForm_GetFieldWidgetPageObjNum(model, fieldIndex, w),
 		onState: readUtf8String(runtime.mem, (buf, cap) => fn.EPDFForm_GetFieldWidgetOnState(model, fieldIndex, w, buf, cap)) ?? "",
-		exportValue: readWide(runtime, (buf, cap) => fn.EPDFForm_GetFieldWidgetExportValue(model, fieldIndex, w, buf, cap)),
+		exportValue: readWide$1(runtime, (buf, cap) => fn.EPDFForm_GetFieldWidgetExportValue(model, fieldIndex, w, buf, cap)),
 		checked: fn.EPDFForm_IsFieldWidgetChecked(model, fieldIndex, w)
 	});
 	return widgets;
@@ -3730,8 +4200,8 @@ function readOptions(runtime, model, fieldIndex) {
 	const count = fn.EPDFForm_CountFieldOptions(model, fieldIndex);
 	const options = [];
 	for (let o = 0; o < count; o++) options.push({
-		label: readWide(runtime, (buf, cap) => fn.EPDFForm_GetFieldOptionLabel(model, fieldIndex, o, buf, cap)),
-		value: readWide(runtime, (buf, cap) => fn.EPDFForm_GetFieldOptionValue(model, fieldIndex, o, buf, cap)),
+		label: readWide$1(runtime, (buf, cap) => fn.EPDFForm_GetFieldOptionLabel(model, fieldIndex, o, buf, cap)),
+		value: readWide$1(runtime, (buf, cap) => fn.EPDFForm_GetFieldOptionValue(model, fieldIndex, o, buf, cap)),
 		selected: fn.EPDFForm_IsFieldOptionSelected(model, fieldIndex, o)
 	});
 	return options;
@@ -3740,7 +4210,7 @@ function readOptions(runtime, model, fieldIndex) {
 function readFieldAt(runtime, model, fieldIndex, docPtr, actionBudget = new ActionReadBudgetTracker()) {
 	const { fn } = runtime;
 	const fieldObjectNumber = fn.EPDFForm_GetFieldObjNum(model, fieldIndex);
-	const name = readWide(runtime, (buf, cap) => fn.EPDFForm_GetFieldName(model, fieldIndex, buf, cap));
+	const name = readWide$1(runtime, (buf, cap) => fn.EPDFForm_GetFieldName(model, fieldIndex, buf, cap));
 	const rawFlags = fn.EPDFForm_GetFieldFlags(model, fieldIndex);
 	const family = FAMILY_BY_CODE[fn.EPDFForm_GetFieldFamily(model, fieldIndex)] ?? "unknown";
 	const valueEntry = readValueEntry(runtime, model, fieldIndex, false);
@@ -3871,7 +4341,7 @@ function readValueEntry(runtime, model, fieldIndex, isDefault) {
 	if (kind !== 1 && kind !== 2) return { kind: "unsupported" };
 	const count = isDefault ? fn.EPDFForm_CountFieldDefaultValues(model, fieldIndex) : fn.EPDFForm_CountFieldValues(model, fieldIndex);
 	const values = [];
-	for (let index = 0; index < count; index++) values.push(readWide(runtime, (buf, capacity) => isDefault ? fn.EPDFForm_GetFieldDefaultValueAt(model, fieldIndex, index, buf, capacity) : fn.EPDFForm_GetFieldValueAt(model, fieldIndex, index, buf, capacity)));
+	for (let index = 0; index < count; index++) values.push(readWide$1(runtime, (buf, capacity) => isDefault ? fn.EPDFForm_GetFieldDefaultValueAt(model, fieldIndex, index, buf, capacity) : fn.EPDFForm_GetFieldValueAt(model, fieldIndex, index, buf, capacity)));
 	return kind === 1 ? {
 		kind: "scalar",
 		value: values[0] ?? ""
@@ -4212,13 +4682,13 @@ function readAnnotationActions(fn, mem, docPtr, annotPtr, budget) {
 * releasing any enclosing `pagePtr`.
 */
 function collectPageAnnotations(input) {
-	const { runtime, session, pageObjectNumber, count, getAnnotPtrAt, signal } = input;
+	const { runtime, session, pageObjectNumber, count, getAnnotPtrAt, signal, fonts } = input;
 	const { fn, mem } = runtime;
 	const annotations = [];
 	let hasWeak = false;
 	const revision = session.pageState(pageObjectNumber).revision;
 	const actionBudget = new ActionReadBudgetTracker();
-	const readCtx = readContextFor(session);
+	const readCtx = readContextFor(session, fonts);
 	for (let i = 0; i < count; i++) {
 		throwIfAborted(signal);
 		const annotPtr = getAnnotPtrAt(i);
@@ -4254,9 +4724,10 @@ function collectPageAnnotations(input) {
 * as they land - the public DTO surface stays the same.
 */
 var AnnotationReader = class {
-	constructor(runtime, session) {
+	constructor(runtime, session, fonts) {
 		this.runtime = runtime;
 		this.session = session;
+		this.fonts = fonts;
 	}
 	list(pageObjectNumber, signal) {
 		throwIfAborted(signal);
@@ -4271,7 +4742,8 @@ var AnnotationReader = class {
 				pageObjectNumber,
 				count,
 				getAnnotPtrAt: (i) => fn.FPDFPage_GetAnnot(pagePtr, i),
-				signal
+				signal,
+				...this.fonts ? { fonts: this.fonts } : {}
 			});
 		} finally {
 			pool.release(pageObjectNumber);
@@ -4600,9 +5072,10 @@ function normalizeScale(scale) {
 * actually need a pagePtr to materialise their fields.
 */
 var RawAnnotationReader = class {
-	constructor(runtime, session) {
+	constructor(runtime, session, fonts) {
 		this.runtime = runtime;
 		this.session = session;
+		this.fonts = fonts;
 	}
 	listAll(signal) {
 		throwIfAborted(signal);
@@ -4628,7 +5101,8 @@ var RawAnnotationReader = class {
 			pageObjectNumber,
 			count,
 			getAnnotPtrAt: (i) => fn.EPDFPage_GetAnnotRaw(docPtr, record.pageIndex, i),
-			signal
+			signal,
+			...this.fonts ? { fonts: this.fonts } : {}
 		});
 	}
 };
@@ -5443,7 +5917,7 @@ function isFileAttachmentSubtype(subtype) {
 	return subtype === "file-attachment";
 }
 function setFileAttachmentIcon(fn, annotPtr, icon) {
-	if (!fn.EPDFAnnot_SetName(annotPtr, FILE_ICON_TO_CODE[icon])) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, FILE_ICON_TO_NAME[icon])) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 function requireFileResource(file, ctx) {
 	const resource = ctx?.resources?.[file.resource];
@@ -5569,6 +6043,20 @@ const DEFAULT_FREETEXT_COLOR = {
 	b: 0
 };
 /**
+* Write rich text through the engine's rich writer: `/RC`, `/DS`, `/DA`,
+* `/Contents` and the appearance, all or nothing. Faces in the input are
+* resolved from keys / standard names to the identities the engine names.
+*/
+function writeRichText(fn, annotPtr, input, ctx) {
+	const json = engineRichTextJson(input, ctx?.describeRegisteredFont);
+	if (!fn.EPDFAnnot_SetRichTextJSON(annotPtr, json)) throw new EngineError(EngineErrorCode.InvalidArg, "rich text could not be written (empty rect, or a font resource could not be built)");
+}
+/** `#RRGGBB` for a rich body colour. */
+function hexColor(color) {
+	const hex = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+	return `#${hex(color.r)}${hex(color.g)}${hex(color.b)}`.toUpperCase();
+}
+/**
 * Apply a free-text draft to a freshly-created annotation. Colour model:
 *   - `color` -> `/DA` colour = border + default text colour.
 *   - `fontColor` (optional) -> `TextColor` channel, overriding text only;
@@ -5610,6 +6098,7 @@ function applyFreeTextDraft(fn, mem, annotPtr, draft, ctx) {
 		rotation: draft.rotation,
 		unrotatedRect: draft.unrotatedRect
 	});
+	writeRichText(fn, annotPtr, draft.richText ?? { paragraphs: richTextParagraphsFromPlainText(draft.contents ?? "") }, ctx);
 }
 /**
 * Apply a free-text patch to an existing annotation. Only present fields are
@@ -5636,11 +6125,30 @@ function applyFreeTextPatch(fn, mem, annotPtr, patch, ctx) {
 	else setAnnotColor(fn, annotPtr, patch.interiorColor, FPDFANNOT_COLORTYPE.Color);
 	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
 	applyBorderPatch(fn, mem, annotPtr, patch);
-	if (patch.fontFamily !== void 0 || patch.fontSize !== void 0 || patch.color !== void 0) {
+	const current = readEngineRichText(fn, mem, annotPtr);
+	if (patch.color !== void 0) {
 		const cur = readDefaultAppearance(fn, mem, annotPtr);
-		applyDefaultAppearance(fn, annotPtr, patch.fontFamily ?? (cur ? standardFontFromCode(cur.fontCode) : "helvetica"), patch.fontSize ?? (cur && cur.fontSize > 0 ? cur.fontSize : 12), patch.color ?? cur?.color ?? DEFAULT_FREETEXT_COLOR, ctx);
+		applyDefaultAppearance(fn, annotPtr, cur ? standardFontFromCode(cur.fontCode) : DEFAULT_STANDARD_FONT, cur && cur.fontSize > 0 ? cur.fontSize : 12, patch.color, ctx);
 	}
 	if (patch.fontColor !== void 0) setAnnotColor(fn, annotPtr, patch.fontColor, FPDFANNOT_COLORTYPE.TextColor);
+	if (patch.richText !== void 0) writeRichText(fn, annotPtr, patch.richText, ctx);
+	else if (patch.contents !== void 0) writeRichText(fn, annotPtr, { paragraphs: richTextParagraphsFromPlainText(patch.contents ?? "") }, ctx);
+	else if (current && (patch.fontFamily !== void 0 || patch.fontSize !== void 0 || patch.fontColor !== void 0 || patch.textAlign !== void 0)) {
+		const body = { ...current.body };
+		if (patch.fontFamily !== void 0) {
+			const face = faceForFreeTextFont(patch.fontFamily, ctx?.describeRegisteredFont);
+			body.family = face.family;
+			if (face.weight !== void 0) body.weight = face.weight;
+			if (face.italic !== void 0) body.italic = face.italic;
+		}
+		if (patch.fontSize !== void 0) body.size = patch.fontSize;
+		if (patch.fontColor !== void 0) body.color = hexColor(patch.fontColor);
+		if (patch.textAlign !== void 0) body.align = patch.textAlign;
+		writeRichText(fn, annotPtr, {
+			body,
+			paragraphs: current.paragraphs
+		}, ctx);
+	}
 	if (patch.textAlign !== void 0) setTextAlignment(fn, annotPtr, textAlignmentToCode(patch.textAlign));
 	if (patch.intent !== void 0) setIntent(fn, annotPtr, freeTextIntentToName(patch.intent));
 	if (patch.rectDifferences === null) clearRectangleDifferences(fn, annotPtr);
@@ -6105,12 +6613,12 @@ const STAMP_FIT_TO_CODE = {
 * creating an annotation or strengthening a weak annotation id.
 */
 function preflightStampDraft(draft, ctx) {
-	if (draft.name !== void 0) requireStampNameCode(draft.name);
+	if (draft.name !== void 0) requireStampName(draft.name);
 	requireStampFit(draft.fit ?? "contain");
 	requireStampContent(draft.source, ctx);
 }
 function preflightStampPatch(patch, ctx) {
-	if (patch.name !== void 0) requireStampNameCode(patch.name);
+	if (patch.name !== void 0 && patch.name !== null) requireStampName(patch.name);
 	requireStampFit(patch.fit ?? "contain");
 	if (patch.source !== void 0) requireStampContent(patch.source, ctx);
 }
@@ -6136,7 +6644,8 @@ function applyStampDraft(fn, mem, annotPtr, draft, ctx) {
 }
 function applyStampPatch(fn, mem, annotPtr, patch, ctx) {
 	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
-	if (patch.name !== void 0) setStampName(fn, annotPtr, patch.name);
+	if (patch.name === null) fn.EPDFAnnot_RemoveKey(annotPtr, "Name");
+	else if (patch.name !== void 0) setStampName(fn, annotPtr, patch.name);
 	if (patch.source !== void 0) {
 		const rect = patch.rect ?? readAnnotRect(fn, mem, annotPtr);
 		authorStampAppearance(fn, mem, annotPtr, patch.source, patch.fit ?? "contain", {
@@ -6156,15 +6665,14 @@ function applyStampPatch(fn, mem, annotPtr, patch, ctx) {
 function isStampSubtype(subtype) {
 	return subtype === "stamp";
 }
+/** Any non-empty name: standard ('Approved') or custom ('#LBGiYhk8V…') —
+*  the fork writes a name object and escapes it; predefined sets are a
+*  reader concern (ISO 32000-2 table 187 allows additional names). */
 function setStampName(fn, annotPtr, name) {
-	const code = STAMP_NAME_TO_CODE[name];
-	if (code === void 0) throw new EngineError(EngineErrorCode.Unknown, "stamp name preflight invariant broken");
-	if (!fn.EPDFAnnot_SetName(annotPtr, code)) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, name)) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
-function requireStampNameCode(name) {
-	const code = STAMP_NAME_TO_CODE[name];
-	if (code === void 0) throw new EngineError(EngineErrorCode.InvalidArg, `unknown stamp name '${name}'; supported names: ${Object.keys(STAMP_NAME_TO_CODE).join(", ")}`);
-	return code;
+function requireStampName(name) {
+	if (name.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, "stamp name must be non-empty");
 }
 function requireStampFit(fit) {
 	if (STAMP_FIT_TO_CODE[fit] === void 0) throw new EngineError(EngineErrorCode.InvalidArg, `unknown stamp fit '${String(fit)}'; expected contain, cover, or fill`);
@@ -6352,7 +6860,7 @@ function isTextSubtype(subtype) {
 	return subtype === "text";
 }
 function setNoteIcon(fn, annotPtr, icon) {
-	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_CODE[icon])) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_NAME[icon])) throw new EngineError(EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 //#endregion
 //#region src/features/annotations/internal/write/writeVertexAnnotation.ts
@@ -6690,7 +7198,10 @@ var AnnotationMutator = class {
 	writeContext(pagePtr, resources) {
 		const fonts = this.fonts;
 		return {
-			...fonts ? { resolveRegisteredFontId: (key) => fonts.idFor(key) } : {},
+			...fonts ? {
+				resolveRegisteredFontId: (key) => fonts.idFor(key),
+				describeRegisteredFont: (key) => fonts.describeOrUndefined(key)
+			} : {},
 			docPtr: this.session.requireDocPtr(),
 			pagePtr,
 			...resources ? { resources } : {}
@@ -6706,6 +7217,7 @@ var AnnotationMutator = class {
 			this.ensureKnownWeakStateFromPage(pageObjectNumber, pagePtr);
 			const writeCtx = this.writeContext(pagePtr, resources);
 			preflightDraft(draft, writeCtx);
+			assertRichTextAgreement(draft);
 			const pageStateBefore = this.session.pageState(pageObjectNumber);
 			throwIfAborted(signal);
 			const annotPtr = fn.EPDFPage_CreateAnnot(pagePtr, subtypeCode);
@@ -6728,7 +7240,7 @@ var AnnotationMutator = class {
 				if (newObjNum <= 0) throw new EngineError(EngineErrorCode.Unknown, `EPDFPage_CreateAnnot produced a direct object (no objectNumber); fork helper invariant broken`);
 				newIndex = fn.FPDFPage_GetAnnotIndex(pagePtr, annotPtr);
 				if (newIndex < 0) throw new EngineError(EngineErrorCode.Unknown, `FPDFPage_GetAnnotIndex returned ${newIndex} for freshly created annotation`);
-				dto = readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, newIndex, pageStateBefore.revision, readContextFor(this.session));
+				dto = readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, newIndex, pageStateBefore.revision, readContextFor(this.session, this.fonts));
 				joinWidgetFieldNumbers(this.runtime, this.session, [dto]);
 			} finally {
 				fn.FPDFPage_CloseAnnot(annotPtr);
@@ -6763,6 +7275,7 @@ var AnnotationMutator = class {
 			throwIfAborted(signal);
 			const writeCtx = this.writeContext(pagePtr, resources);
 			preflightPatch(patch, writeCtx);
+			assertRichTextAgreement(patch);
 			this.ensureKnownWeakStateFromPage(ref.pageObjectNumber, pagePtr);
 			const pageStateBefore = this.session.pageState(ref.pageObjectNumber);
 			throwIfAborted(signal);
@@ -6770,7 +7283,7 @@ var AnnotationMutator = class {
 			const previousBlendMode = blendModeFromCode(fn.EPDFAnnot_GetBlendMode(annotPtr));
 			const preIndex = fn.FPDFPage_GetAnnotIndex(pagePtr, annotPtr);
 			if (preIndex < 0) throw new EngineError(EngineErrorCode.Unknown, `FPDFPage_GetAnnotIndex returned ${preIndex} before update`);
-			const currentDto = readAnnotationFromPtr(fn, mem, annotPtr, ref.pageObjectNumber, preIndex, pageStateBefore.revision, readContextFor(this.session));
+			const currentDto = readAnnotationFromPtr(fn, mem, annotPtr, ref.pageObjectNumber, preIndex, pageStateBefore.revision, readContextFor(this.session, this.fonts));
 			applyPatch(fn, mem, annotPtr, patch, writeCtx);
 			let linkedParentId = null;
 			if (patch.inReplyTo !== void 0 || patch.replyType !== void 0) linkedParentId = writeAnnotationRelationship(this.runtime, this.session, pagePtr, annotPtr, ref.pageObjectNumber, {
@@ -6797,7 +7310,7 @@ var AnnotationMutator = class {
 			annotPtr = resolveAnnotPtr(this.runtime, this.session, pagePtr, ref);
 			const newIndex = fn.FPDFPage_GetAnnotIndex(pagePtr, annotPtr);
 			if (newIndex < 0) throw new EngineError(EngineErrorCode.Unknown, `FPDFPage_GetAnnotIndex returned ${newIndex} after update`);
-			const dto = readAnnotationFromPtr(fn, mem, annotPtr, ref.pageObjectNumber, newIndex, pageStateBefore.revision, readContextFor(this.session));
+			const dto = readAnnotationFromPtr(fn, mem, annotPtr, ref.pageObjectNumber, newIndex, pageStateBefore.revision, readContextFor(this.session, this.fonts));
 			joinWidgetFieldNumbers(this.runtime, this.session, [dto]);
 			this.recordWeakStateFromPage(ref.pageObjectNumber, pagePtr);
 			const meta = computeMutationImpact({
@@ -7010,7 +7523,7 @@ var AnnotationMutator = class {
 				const annotPtr = fn.FPDFPage_GetAnnot(pagePtr, newIdx);
 				if (!annotPtr) throw new EngineError(EngineErrorCode.Unknown, `failed to re-read moved annotation at index ${newIdx}`);
 				try {
-					moved[i] = readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, newIdx, bumpedRev, readContextFor(this.session));
+					moved[i] = readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, newIdx, bumpedRev, readContextFor(this.session, this.fonts));
 				} finally {
 					fn.FPDFPage_CloseAnnot(annotPtr);
 				}
@@ -7079,6 +7592,141 @@ var AnnotationMutator = class {
 	}
 };
 //#endregion
+//#region src/features/annotations/AnnotationFlattener.ts
+const FLATTEN_FAIL$1 = 0;
+const FLATTEN_SUCCESS$1 = 1;
+const FLATTEN_NOTHING_TO_DO$1 = 2;
+const STATUS_APPLIED = 0;
+const STATUS_NOT_ON_PAGE = 2;
+const FPDF_NO_INCREMENTAL$1 = 2;
+/**
+* The annotation-plane flatten verbs — `pages.flatten` for a chosen set:
+* in place (`flatten`) or into a new single-page document
+* (`exportAppearance`). Both resolve refs to native handles on the page,
+* hand the SET to the fork (one candidate plan, one placement writer — the
+* same code whole-page flatten runs), and release every handle afterwards.
+*/
+var AnnotationFlattener = class {
+	constructor(runtime, session) {
+		this.runtime = runtime;
+		this.session = session;
+	}
+	flatten(pageObjectNumber, refs, usage, signal) {
+		throwIfAborted(signal);
+		this.requireRefs("annotations.flatten", pageObjectNumber, refs);
+		const { fn, mem } = this.runtime;
+		const pool = this.session.pagePool();
+		const pagePtr = pool.acquire(pageObjectNumber);
+		try {
+			const annotPtrs = this.resolveAll(pagePtr, refs);
+			let code;
+			let statuses;
+			try {
+				[code, statuses] = this.withHandleArray(annotPtrs, (arrayPtr) => withScratch(mem, 4 * refs.length, (statusPtr) => {
+					const rc = fn.EPDFPage_FlattenAnnotations(pagePtr, arrayPtr, refs.length, usage === "print" ? 1 : 0, statusPtr);
+					const out = [];
+					for (let i = 0; i < refs.length; i++) out.push(Number(mem.peek(statusPtr, "i32", 4 * i)));
+					return [rc, out];
+				}));
+			} finally {
+				for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+			if (code === FLATTEN_FAIL$1) {
+				const foreign = statuses.findIndex((status) => status === STATUS_NOT_ON_PAGE);
+				throw new EngineError(foreign >= 0 ? EngineErrorCode.InvalidArg : EngineErrorCode.Unknown, foreign >= 0 ? `annotations.flatten: ref ${foreign} is not an annotation of page ${pageObjectNumber}` : "native annotation flatten failed after preflight");
+			}
+			const results = refs.map((ref, i) => ({
+				ref,
+				status: statuses[i] === STATUS_APPLIED ? "applied" : "skipped"
+			}));
+			if (code === FLATTEN_NOTHING_TO_DO$1 || code !== FLATTEN_SUCCESS$1) return {
+				pageObjectNumber,
+				usage,
+				results,
+				meta: null
+			};
+			this.session.noteMutation();
+			this.session.bumpRevision(pageObjectNumber);
+			try {
+				new AnnotationReader(this.runtime, this.session).list(pageObjectNumber, signal);
+			} catch {}
+			return {
+				pageObjectNumber,
+				usage,
+				results,
+				meta: {
+					affectedPages: [this.session.pageState(pageObjectNumber)],
+					cacheDelta: null
+				}
+			};
+		} finally {
+			pool.release(pageObjectNumber);
+		}
+	}
+	exportAppearance(pageObjectNumber, refs, signal) {
+		throwIfAborted(signal);
+		this.requireRefs("annotations.exportAppearance", pageObjectNumber, refs);
+		const { fn, mem } = this.runtime;
+		const pool = this.session.pagePool();
+		const pagePtr = pool.acquire(pageObjectNumber);
+		let exportedPtr = null;
+		let pdfPtr = null;
+		try {
+			const annotPtrs = this.resolveAll(pagePtr, refs);
+			try {
+				exportedPtr = this.withHandleArray(annotPtrs, (arrayPtr) => fn.EPDFPage_ExportAnnotationsAsDocument(pagePtr, arrayPtr, refs.length));
+			} finally {
+				for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+			if (!exportedPtr) throw new EngineError(EngineErrorCode.InvalidArg, "annotations.exportAppearance: every ref must be a visible annotation of this page with a normal appearance");
+			return withScratch(mem, 4, (sizePtr) => {
+				mem.poke(sizePtr, "i32", 0);
+				pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(exportedPtr, FPDF_NO_INCREMENTAL$1, sizePtr);
+				const size = Number(mem.peek(sizePtr, "i32"));
+				if (!pdfPtr || size <= 0) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save exported appearances");
+				const bytes = mem.readBytes(pdfPtr, size);
+				const buffer = new ArrayBuffer(bytes.byteLength);
+				new Uint8Array(buffer).set(bytes);
+				return {
+					bytes: buffer,
+					size
+				};
+			});
+		} finally {
+			if (pdfPtr) fn.EPDF_FreeBuffer(pdfPtr);
+			if (exportedPtr) fn.FPDF_CloseDocument(exportedPtr);
+			pool.release(pageObjectNumber);
+		}
+	}
+	/** Resolve every ref on `pagePtr` (NotFound / InvalidReference from the
+	*  resolver on caller error); on any failure, close what was opened. */
+	resolveAll(pagePtr, refs) {
+		const { fn } = this.runtime;
+		const annotPtrs = [];
+		try {
+			for (const ref of refs) annotPtrs.push(resolveAnnotPtr(this.runtime, this.session, pagePtr, ref));
+			return annotPtrs;
+		} catch (error) {
+			for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			throw error;
+		}
+	}
+	/** Marshal an `FPDF_ANNOTATION*` array for the call's duration. */
+	withHandleArray(annotPtrs, body) {
+		const { mem } = this.runtime;
+		const isWasm = this.runtime.kind === "wasm";
+		const ptrSize = isWasm ? 4 : 8;
+		return withScratch(mem, Math.max(1, annotPtrs.length * ptrSize), (arrayPtr) => {
+			annotPtrs.forEach((ptr, i) => isWasm ? mem.poke(arrayPtr, "i32", Number(ptr), i * 4) : mem.poke(arrayPtr, "i64", ptr, i * 8));
+			return body(arrayPtr);
+		});
+	}
+	requireRefs(op, pageObjectNumber, refs) {
+		if (refs.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, `${op} requires at least one ref`);
+		for (const ref of refs) if (ref.pageObjectNumber !== pageObjectNumber) throw new EngineError(EngineErrorCode.InvalidArg, `${op} refs must all target page ${pageObjectNumber}; got ref on page ${ref.pageObjectNumber}`);
+	}
+};
+//#endregion
 //#region src/features/pages/PagesFlattener.ts
 const FLATTEN_FAIL = 0;
 const FLATTEN_SUCCESS = 1;
@@ -8137,104 +8785,2174 @@ function layerSaveError(status) {
 	return new EngineError(EngineErrorCode.DocOpenFailed, "failed to save layer artifact");
 }
 //#endregion
-//#region src/features/save/DocumentSaver.ts
+//#region src/runtime/memory/u64.ts
 /**
-* Owns every "serialize the open document" path for a `DocumentSession`.
-* Two distinct outputs:
-*
-*   - Layer artifacts (`saveLayerArtifact*`) are the storage-optimized
-*     `.layer` delta used by server-side persistence. Only valid for a
-*     `layer` session.
-*   - Standalone saves (`saveStandalone*`) export a self-contained PDF
-*     view (base + applied delta) via `FPDF_SaveAsCopy` /
-*     `EPDF_SaveDocumentToOwnedBuffer`, valid for any session kind.
-*
-* Lives in `engine-services` so the browser Worker and the Node
-* `worker_thread` server share the exact same save code path.
+* 64-bit out-params as two little-endian 32-bit halves: the wasm memory
+* helpers have no 64-bit accessors (Emscripten's `setValue(i64)` needs
+* WASM_BIGINT), and the native runtime reads the same layout.
 */
-var DocumentSaver = class {
-	constructor(runtime, session) {
-		this.runtime = runtime;
-		this.session = session;
+function pokeU64(mem, ptr, value, byteOffset = 0) {
+	const big = BigInt(value);
+	mem.poke(ptr, "i32", Number(big & 4294967295n) | 0, byteOffset);
+	mem.poke(ptr, "i32", Number(big >> 32n & 4294967295n) | 0, byteOffset + 4);
+}
+function peekU64(mem, ptr, byteOffset = 0) {
+	const lo = Number(mem.peek(ptr, "i32", byteOffset)) >>> 0;
+	return (Number(mem.peek(ptr, "i32", byteOffset + 4)) >>> 0) * 4294967296 + lo;
+}
+//#endregion
+//#region src/features/signature/internal/readSignatureModel.ts
+const KIND_DOC_TIMESTAMP = 1;
+const COVERAGE_BY_CODE = {
+	0: "whole-revision",
+	1: "partial",
+	2: "malformed"
+};
+const STRING_FILTER = 0;
+const STRING_SUBFILTER = 1;
+const STRING_NAME = 2;
+const STRING_REASON = 3;
+const STRING_LOCATION = 4;
+const STRING_CONTACT_INFO = 5;
+const STRING_M = 6;
+const FIELD_ACTION_BY_CODE = {
+	1: "all",
+	2: "include",
+	3: "exclude"
+};
+const FIELDS_FIELDMDP = 0;
+const FIELDS_LOCK = 1;
+const SV_V = 4;
+const SV_MDP = 1 << 17;
+const SV_LIST_SUBFILTER = 0;
+const SV_LIST_DIGEST_METHOD = 1;
+const SV_LIST_REASONS = 2;
+/** The PDF 1.7 seed-value entry set this engine implements. */
+const SUPPORTED_SEED_VALUE_VERSION = 2;
+const SV_UNSUPPORTED_REQUIRED = 432;
+function readWide(runtime, call) {
+	return readUtf16String(runtime.mem, call, "");
+}
+function isPermission(value) {
+	return value === 1 || value === 2 || value === 3;
+}
+function readByteRange(runtime, model, index) {
+	const { fn, mem } = runtime;
+	return withScratch(mem, 32, (ptr) => {
+		for (let k = 0; k < 4; k++) pokeU64(mem, ptr, 0, k * 8);
+		if (!fn.EPDFSig_GetByteRange(model, index, ptr)) return null;
+		return [
+			peekU64(mem, ptr, 0),
+			peekU64(mem, ptr, 8),
+			peekU64(mem, ptr, 16),
+			peekU64(mem, ptr, 24)
+		];
+	});
+}
+function readLock(runtime, model, index, which) {
+	const { fn } = runtime;
+	const code = which === FIELDS_LOCK ? fn.EPDFSig_GetLockAction(model, index) : fn.EPDFSig_GetFieldMDPAction(model, index);
+	const action = FIELD_ACTION_BY_CODE[code];
+	if (!action) return null;
+	const fields = [];
+	const count = fn.EPDFSig_GetFieldNameCount(model, index, which);
+	for (let n = 0; n < count; n++) fields.push(readWide(runtime, (buf, cap) => fn.EPDFSig_GetFieldNameAt(model, index, which, n, buf, cap)) ?? "");
+	const spec = {
+		action,
+		fields
+	};
+	if (which === FIELDS_LOCK) {
+		const permission = fn.EPDFSig_GetLockPermission(model, index);
+		if (isPermission(permission)) spec.permission = permission;
 	}
-	saveLayerArtifact() {
-		this.requireLayer();
-		const { mem, fn } = this.runtime;
-		const sizePtr = mem.alloc(4);
-		const statusPtr = mem.alloc(4);
-		let artifactPtr = null;
-		try {
-			mem.poke(sizePtr, "i32", 0);
-			mem.poke(statusPtr, "i32", -1);
-			artifactPtr = fn.EPDFLayer_SaveLayerArtifactToOwnedBuffer(this.session.requireDocPtr(), sizePtr, statusPtr);
-			const status = Number(mem.peek(statusPtr, "i32"));
-			const size = Number(mem.peek(sizePtr, "i32"));
-			if (!artifactPtr || status !== 0 || size <= 0) throw layerSaveError(status);
-			const bytes = mem.readBytes(artifactPtr, size);
-			const buffer = new ArrayBuffer(bytes.byteLength);
-			new Uint8Array(buffer).set(bytes);
-			return {
-				bytes: buffer,
-				size
-			};
-		} finally {
-			if (artifactPtr) fn.EPDF_FreeBuffer(artifactPtr);
-			mem.free(statusPtr);
-			mem.free(sizePtr);
-		}
+	return spec;
+}
+function readSeedValue(runtime, model, index) {
+	const { fn } = runtime;
+	if (!fn.EPDFSig_HasSeedValue(model, index)) return null;
+	const requiredFlags = fn.EPDFSig_GetSeedValueRequiredFlags(model, index) >>> 0;
+	const presentFlags = fn.EPDFSig_GetSeedValuePresentFlags(model, index) >>> 0;
+	const version = fn.EPDFSig_GetSeedValueVersion(model, index);
+	const mdp = fn.EPDFSig_GetSeedValueMDP(model, index);
+	const list = (which) => {
+		const count = fn.EPDFSig_GetSeedValueListCount(model, index, which);
+		const items = [];
+		for (let n = 0; n < count; n++) items.push(readWide(runtime, (buf, cap) => fn.EPDFSig_GetSeedValueListAt(model, index, which, n, buf, cap)) ?? "");
+		return items;
+	};
+	return {
+		requiredFlags,
+		presentFlags,
+		version: version > 0 ? version : null,
+		mdp: (presentFlags & SV_MDP) !== 0 && mdp >= 0 && mdp <= 3 ? mdp : null,
+		filter: readWide(runtime, (buf, cap) => fn.EPDFSig_GetSeedValueFilter(model, index, buf, cap)),
+		subFilters: list(SV_LIST_SUBFILTER),
+		digestMethods: list(SV_LIST_DIGEST_METHOD),
+		reasons: list(SV_LIST_REASONS),
+		unsupportedRequired: (requiredFlags & SV_UNSUPPORTED_REQUIRED) !== 0 || (requiredFlags & SV_V) !== 0 && version > SUPPORTED_SEED_VALUE_VERSION
+	};
+}
+/** Every signature field of a native signature model, in model order. */
+function readSignaturesFromModel(runtime, model) {
+	const { fn } = runtime;
+	const count = fn.EPDFSig_Count(model);
+	const out = [];
+	const str = (i, key) => readWide(runtime, (buf, cap) => fn.EPDFSig_GetString(model, i, key, buf, cap));
+	for (let i = 0; i < count; i++) {
+		const signed = fn.EPDFSig_IsSigned(model, i);
+		const widgetObjNum = fn.EPDFSig_GetWidgetObjNum(model, i);
+		const revisionIndex = fn.EPDFSig_GetRevisionIndex(model, i);
+		const docMdp = fn.EPDFSig_GetDocMDPPermission(model, i);
+		out.push({
+			index: i,
+			field: {
+				kind: "objectNumber",
+				fieldObjectNumber: fn.EPDFSig_GetFieldObjNum(model, i)
+			},
+			fieldName: readWide(runtime, (buf, cap) => fn.EPDFSig_GetFieldName(model, i, buf, cap)) ?? "",
+			widget: widgetObjNum > 0 ? {
+				annotObjectNumber: widgetObjNum,
+				pageObjectNumber: fn.EPDFSig_GetWidgetPageObjNum(model, i)
+			} : null,
+			signed,
+			kind: fn.EPDFSig_GetKind(model, i) === KIND_DOC_TIMESTAMP ? "timestamp" : "signature",
+			filter: str(i, STRING_FILTER),
+			subFilter: str(i, STRING_SUBFILTER),
+			byteRange: signed ? readByteRange(runtime, model, i) : null,
+			contentsSize: signed ? Math.max(0, fn.EPDFSig_GetContents(model, i, NULL_PTR, 0)) : 0,
+			coverage: signed ? COVERAGE_BY_CODE[fn.EPDFSig_GetCoverage(model, i)] ?? "malformed" : null,
+			revisionIndex: signed && revisionIndex >= 0 ? revisionIndex : null,
+			signer: {
+				name: str(i, STRING_NAME),
+				reason: str(i, STRING_REASON),
+				location: str(i, STRING_LOCATION),
+				contactInfo: str(i, STRING_CONTACT_INFO),
+				claimedTime: str(i, STRING_M)
+			},
+			docMdp: isPermission(docMdp) ? docMdp : null,
+			catalogCertification: fn.EPDFSig_IsCatalogCertification(model, i),
+			fieldMdp: readLock(runtime, model, i, FIELDS_FIELDMDP),
+			lock: readLock(runtime, model, i, FIELDS_LOCK),
+			seedValue: readSeedValue(runtime, model, i)
+		});
 	}
-	saveLayerArtifactToFile(path) {
-		this.requireLayer();
-		const { mem, fn } = this.runtime;
-		const statusPtr = mem.alloc(4);
-		const writer = this.runtime.fileWrite.toNodeFile(path);
-		try {
-			mem.poke(statusPtr, "i32", -1);
-			const ok = fn.EPDFLayer_SaveLayerArtifact(this.session.requireDocPtr(), writer.ptr, statusPtr);
-			const status = Number(mem.peek(statusPtr, "i32"));
-			if (!ok || status !== 0) throw layerSaveError(status);
-			return { path };
-		} finally {
-			writer.close();
-			mem.free(statusPtr);
+	return out;
+}
+/** The DER `/Contents` of signature `index`, copied out; `NotFound` when unsigned or malformed. */
+function readContentsAt(runtime, model, index) {
+	const { fn, mem } = runtime;
+	const length = fn.EPDFSig_GetContents(model, index, NULL_PTR, 0);
+	if (length <= 0) throw new EngineError(EngineErrorCode.NotFound, "signature has no usable /Contents (malformed encoding)");
+	return withScratch(mem, length, (buf) => {
+		if (fn.EPDFSig_GetContents(model, index, buf, length) !== length) throw new EngineError(EngineErrorCode.Unknown, "failed to read signature contents");
+		const out = new Uint8Array(length);
+		out.set(mem.readBytes(buf, length));
+		return out;
+	});
+}
+/** The chained revisions of a document, oldest first; empty when the chain is not valid. */
+function readRevisions(runtime, docPtr, signatures) {
+	const { fn, mem } = runtime;
+	const count = fn.EPDFDoc_GetRevisionCount(docPtr);
+	const revisions = [];
+	if (count <= 0) return revisions;
+	withScratchN(mem, [8, 8], ([endPtr, xrefPtr]) => {
+		for (let i = 0; i < count; i++) {
+			pokeU64(mem, endPtr, 0);
+			pokeU64(mem, xrefPtr, 0);
+			if (!fn.EPDFDoc_GetRevision(docPtr, i, endPtr, xrefPtr)) throw new EngineError(EngineErrorCode.Unknown, `failed to read revision ${i}`);
+			const sealedBy = signatures.find((s) => s.revisionIndex === i);
+			revisions.push({
+				index: i,
+				end: peekU64(mem, endPtr),
+				xrefOffset: peekU64(mem, xrefPtr),
+				signatureIndex: sealedBy ? sealedBy.index : null
+			});
 		}
-	}
-	saveStandaloneToBuffer(mode) {
-		const { mem, fn } = this.runtime;
-		const sizePtr = mem.alloc(4);
-		let pdfPtr = null;
+	});
+	return revisions;
+}
+/** Whether any signature field of the document carries a signed value (fields alone do not count). */
+function hasSignedSignature(runtime, docPtr) {
+	const { fn } = runtime;
+	return withSignatureModel(runtime, docPtr, (model) => {
+		const count = fn.EPDFSig_Count(model);
+		for (let i = 0; i < count; i++) if (fn.EPDFSig_IsSigned(model, i)) return true;
+		return false;
+	});
+}
+/** Run `body` with a fresh signature model of `docPtr`, closing it afterwards. */
+function withSignatureModel(runtime, docPtr, body) {
+	const model = runtime.fn.EPDFSig_LoadModel(docPtr);
+	if (model === NULL_PTR) throw new EngineError(EngineErrorCode.Unknown, "failed to build signature model");
+	try {
+		return body(model);
+	} finally {
+		runtime.fn.EPDFSig_CloseModel(model);
+	}
+}
+/**
+* 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.
+*/
+function readStructure(runtime, docPtr) {
+	const { fn, mem } = runtime;
+	const [root, acroForm, pagesRoot] = withScratchN(mem, [
+		4,
+		4,
+		4
+	], ([r, a, p]) => {
+		mem.poke(r, "i32", 0);
+		mem.poke(a, "i32", 0);
+		mem.poke(p, "i32", 0);
+		fn.EPDFDoc_GetStructureObjectNumbers(docPtr, r, a, p);
+		return [
+			Number(mem.peek(r, "i32")) >>> 0,
+			Number(mem.peek(a, "i32")) >>> 0,
+			Number(mem.peek(p, "i32")) >>> 0
+		];
+	});
+	const pages = [];
+	const pageCount = fn.FPDF_GetPageCount(docPtr);
+	for (let i = 0; i < pageCount; i++) pages.push(fn.EPDFDoc_GetPageObjectNumberByIndex(docPtr, i));
+	const fields = [];
+	const formModel = fn.EPDFForm_LoadModel(docPtr);
+	if (formModel !== NULL_PTR) try {
+		const snapshot = readFormSnapshot(runtime, formModel, docPtr);
+		for (const f of snapshot.fields) fields.push({
+			objectNumber: f.fieldObjectNumber,
+			name: f.name,
+			family: f.family,
+			widgets: f.widgets.map((w) => w.annotObjectNumber),
+			flags: f.flags.raw
+		});
+	} finally {
+		fn.EPDFForm_CloseModel(formModel);
+	}
+	return {
+		root,
+		acroForm,
+		pagesRoot,
+		pages,
+		fields,
+		signatures: withSignatureModel(runtime, docPtr, (model) => readSignaturesFromModel(runtime, model))
+	};
+}
+//#endregion
+//#region src/features/signature/internal/signatureModelCache.ts
+/**
+* Per-session cache of the native `EPDFSig_LoadModel` snapshot, keyed on
+* the session's mutation sequence exactly like the form model: the model
+* walks the revision chain, the field tree and every widget, so it is
+* built once per document state and rebuilt after any mutation.
+*/
+const cache$1 = /* @__PURE__ */ new WeakMap();
+function acquireSignatureModel(runtime, session) {
+	const seq = session.mutationSeq();
+	const hit = cache$1.get(session);
+	if (hit && hit.seq === seq) return hit.ptr;
+	if (hit) {
+		runtime.fn.EPDFSig_CloseModel(hit.ptr);
+		cache$1.delete(session);
+	}
+	const ptr = runtime.fn.EPDFSig_LoadModel(session.requireDocPtr());
+	if (ptr === NULL_PTR) throw new EngineError(EngineErrorCode.Unknown, "failed to build signature model");
+	cache$1.set(session, {
+		seq,
+		ptr
+	});
+	return ptr;
+}
+function disposeSignatureModel(runtime, session) {
+	const hit = cache$1.get(session);
+	if (!hit) return;
+	runtime.fn.EPDFSig_CloseModel(hit.ptr);
+	cache$1.delete(session);
+}
+//#endregion
+//#region src/features/signature/SignatureReader.ts
+const DIGEST_CODE = {
+	sha1: 0,
+	sha256: 1,
+	sha384: 2,
+	sha512: 3
+};
+const DIGEST_LENGTH = {
+	sha1: 20,
+	sha256: 32,
+	sha384: 48,
+	sha512: 64
+};
+/**
+* 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.
+*/
+var SignatureReader = class {
+	constructor(runtime, session) {
+		this.runtime = runtime;
+		this.session = session;
+	}
+	readSnapshot() {
+		const model = acquireSignatureModel(this.runtime, this.session);
+		const chainValid = this.runtime.fn.EPDFSig_IsRevisionChainValid(model);
+		const signatures = readSignaturesFromModel(this.runtime, model);
+		return {
+			chainValid,
+			revisions: chainValid ? readRevisions(this.runtime, this.session.requireDocPtr(), signatures) : [],
+			signatures,
+			protection: deriveProtection(signatures)
+		};
+	}
+	/** The protection alone, for the open probe and the form write guard. */
+	readProtection() {
+		const model = acquireSignatureModel(this.runtime, this.session);
+		return deriveProtection(readSignaturesFromModel(this.runtime, model));
+	}
+	/** The DER `/Contents` of a signed field, padding stripped. */
+	readContents(ref) {
+		const model = acquireSignatureModel(this.runtime, this.session);
+		const index = this.requireSignedIndex(model, ref);
+		return readContentsAt(this.runtime, model, index).buffer;
+	}
+	/** Hash a signed field's `/ByteRange` straight from the loaded bytes. */
+	digest(ref, algorithm) {
+		const model = acquireSignatureModel(this.runtime, this.session);
+		const index = this.requireSignedIndex(model, ref);
+		const range = readByteRange(this.runtime, model, index);
+		if (!range) throw new EngineError(EngineErrorCode.NotFound, "signature has no usable /ByteRange");
+		return this.digestRange(range, algorithm);
+	}
+	/** The exact bytes of one revision. */
+	revisionBytes(revisionIndex) {
+		const snapshot = this.readSnapshot();
+		if (!snapshot.chainValid) throw new EngineError(EngineErrorCode.MalformedPdf, "revision chain is not valid");
+		const revision = snapshot.revisions[revisionIndex];
+		if (!revision) throw new EngineError(EngineErrorCode.NotFound, `no revision ${revisionIndex}`);
+		return this.readLoadedBytes(0, revision.end);
+	}
+	/** Resolve a signature-field ref to its identity in the current model. */
+	resolveField(ref) {
+		const { fn } = this.runtime;
+		const model = acquireSignatureModel(this.runtime, this.session);
+		const index = this.indexOf(model, ref);
+		if (index < 0) throw new EngineError(EngineErrorCode.NotFound, ref.kind === "objectNumber" ? `signature field not found: object ${ref.fieldObjectNumber}` : `signature field not found: "${ref.name}"`);
+		const widgetObjNum = fn.EPDFSig_GetWidgetObjNum(model, index);
+		return {
+			index,
+			fieldObjectNumber: fn.EPDFSig_GetFieldObjNum(model, index),
+			signed: fn.EPDFSig_IsSigned(model, index),
+			widget: widgetObjNum > 0 ? {
+				annotObjectNumber: widgetObjNum,
+				pageObjectNumber: fn.EPDFSig_GetWidgetPageObjNum(model, index)
+			} : null
+		};
+	}
+	/** One signature by field object number, from the current model. */
+	readSignatureByObjectNumber(fieldObjectNumber) {
+		const found = this.readSnapshot().signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === fieldObjectNumber);
+		if (!found) throw new EngineError(EngineErrorCode.NotFound, `signature field not found: object ${fieldObjectNumber}`);
+		return found;
+	}
+	/** The complete loaded bytes (a plain file, or a layer's base + delta). */
+	loadedBytes() {
+		const size = Number(this.runtime.fn.EPDFDoc_GetLoadedBytesSize(this.session.requireDocPtr()));
+		return this.readLoadedBytes(0, size);
+	}
+	/**
+	* 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() {
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		const byteLength = Number(fn.EPDFDoc_GetBaseBytesSize(docPtr));
+		if (byteLength <= 0) throw new EngineError(EngineErrorCode.DocNotOpen, "document has no loaded bytes");
+		if (this.session.kind === "layer") return {
+			sha256: withScratch(mem, 32, (out) => {
+				if (!fn.EPDFLayer_GetBaseSha256(docPtr, out)) throw new EngineError(EngineErrorCode.Unknown, "failed to read the base hash");
+				return toHex(mem.readBytes(out, 32));
+			}),
+			byteLength
+		};
+		const cached = this.session.cachedPlainSha256();
+		if (cached) return {
+			sha256: cached,
+			byteLength
+		};
+		const sha256 = toHex(new Uint8Array(this.digestRange([
+			0,
+			byteLength,
+			byteLength,
+			0
+		], "sha256")));
+		this.session.rememberPlainSha256(sha256);
+		return {
+			sha256,
+			byteLength
+		};
+	}
+	digestRange(range, algorithm) {
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		const outLength = DIGEST_LENGTH[algorithm];
+		return withScratchN(mem, [
+			32,
+			outLength,
+			8
+		], ([rangePtr, outPtr, lenPtr]) => {
+			for (let k = 0; k < 4; k++) pokeU64(mem, rangePtr, range[k], k * 8);
+			pokeU64(mem, lenPtr, outLength);
+			if (!fn.EPDFSig_DigestByteRange(docPtr, rangePtr, DIGEST_CODE[algorithm], outPtr, lenPtr)) throw new EngineError(EngineErrorCode.InvalidArg, "byte range is not within the loaded bytes");
+			const written = Number(mem.peek(lenPtr, "i32"));
+			return copyOut$1(mem.readBytes(outPtr, written));
+		});
+	}
+	/** `[offset, offset + length)` of the loaded bytes (base + loaded delta for a layer), copied out. */
+	readLoadedBytes(offset, length) {
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		if (length === 0) return /* @__PURE__ */ new ArrayBuffer(0);
+		return withScratch(mem, length, (ptr) => {
+			if (fn.EPDFDoc_ReadLoadedBytes(docPtr, BigInt(offset), ptr, length) !== length) throw new EngineError(EngineErrorCode.Unknown, "failed to read the loaded bytes");
+			return copyOut$1(mem.readBytes(ptr, length));
+		});
+	}
+	indexOf(model, ref) {
+		const { fn } = this.runtime;
+		if (ref.kind === "objectNumber") return fn.EPDFSig_GetIndexByFieldObjNum(model, ref.fieldObjectNumber);
+		const count = fn.EPDFSig_Count(model);
+		for (let i = 0; i < count; i++) if (this.readWide((buf, cap) => fn.EPDFSig_GetFieldName(model, i, buf, cap)) === ref.name) return i;
+		return -1;
+	}
+	requireSignedIndex(model, ref) {
+		const { fn } = this.runtime;
+		const index = this.indexOf(model, ref);
+		if (index < 0) throw new EngineError(EngineErrorCode.NotFound, ref.kind === "objectNumber" ? `signature field not found: object ${ref.fieldObjectNumber}` : `signature field not found: "${ref.name}"`);
+		if (!fn.EPDFSig_IsSigned(model, index)) throw new EngineError(EngineErrorCode.NotFound, "signature field is not signed");
+		return index;
+	}
+	readString(model, index, key) {
+		return this.readWide((buf, cap) => this.runtime.fn.EPDFSig_GetString(model, index, key, buf, cap));
+	}
+	readWide(call) {
+		return readUtf16String(this.runtime.mem, call, "");
+	}
+};
+function copyOut$1(view) {
+	const buffer = new ArrayBuffer(view.byteLength);
+	new Uint8Array(buffer).set(view);
+	return buffer;
+}
+function toHex(bytes) {
+	let out = "";
+	for (const b of bytes) out += b.toString(16).padStart(2, "0");
+	return out;
+}
+//#endregion
+//#region src/features/save/DocumentSaver.ts
+/** The fork's `EPDFSaveStatus`. */
+const EPDF_SAVE_WRITTEN = 1;
+const EPDF_SAVE_UNCHANGED_SINCE_LOAD = 2;
+/**
+* Owns every "serialize the open document" path for a `DocumentSession`.
+* Two distinct outputs:
+*
+*   - Layer artifacts (`saveLayerArtifact*`) are the storage-optimized
+*     `.layer` delta used by server-side persistence. Only valid for a
+*     `layer` session.
+*   - Standalone saves (`saveStandalone*`) export a self-contained PDF
+*     view (base + applied delta) via `FPDF_SaveAsCopy` /
+*     `EPDF_SaveDocumentToOwnedBuffer`, valid for any session kind.
+*
+* Lives in `engine-services` so the browser Worker and the Node
+* `worker_thread` server share the exact same save code path.
+*/
+var DocumentSaver = class {
+	constructor(runtime, session) {
+		this.runtime = runtime;
+		this.session = session;
+	}
+	/**
+	* 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() {
+		if (!this.session.hasUnsavedEdits()) return {
+			bytes: this.loadedBytes(),
+			source: "loaded"
+		};
+		const saved = this.saveStandaloneToBufferEx("incremental");
+		if (saved.unchangedSinceLoad) return {
+			bytes: this.loadedBytes(),
+			source: "loaded"
+		};
+		return {
+			bytes: saved.bytes,
+			source: "working-copy"
+		};
+	}
+	/** The complete loaded bytes: a plain file, or a layer's base plus the delta it was opened with. */
+	loadedBytes() {
+		return new SignatureReader(this.runtime, this.session).loadedBytes();
+	}
+	/**
+	* 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) {
+		const reader = new SignatureReader(this.runtime, this.session);
+		const size = Number(this.runtime.fn.EPDFDoc_GetLoadedBytesSize(this.session.requireDocPtr()));
+		const chunk = 4 * 1024 * 1024;
+		this.runtime.fileWrite.removeFile(path);
+		for (let offset = 0; offset < size; offset += chunk) {
+			const length = Math.min(chunk, size - offset);
+			this.runtime.fileWrite.appendBytes(path, new Uint8Array(reader.readLoadedBytes(offset, length)));
+		}
+		if (size === 0) this.runtime.fileWrite.appendBytes(path, /* @__PURE__ */ new Uint8Array(0));
+	}
+	/**
+	* `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) {
+		if (!this.session.hasUnsavedEdits()) {
+			this.copyLoadedBytesToFile(path);
+			return {
+				path,
+				source: "loaded"
+			};
+		}
+		if (this.saveStandaloneToFileEx(path, "incremental").unchangedSinceLoad) {
+			this.copyLoadedBytesToFile(path);
+			return {
+				path,
+				source: "loaded"
+			};
+		}
+		return {
+			path,
+			source: "working-copy"
+		};
+	}
+	/** Whether this runtime and session can put scratch output beside the base file. */
+	canWriteScratchFiles() {
+		return this.runtime.kind === "native" && this.session.source.base?.kind === "file";
+	}
+	saveLayerArtifact() {
+		const saved = this.saveLayerArtifactImpl(false);
+		if (saved.size <= 0) throw layerSaveError(-1);
+		return {
+			bytes: saved.bytes,
+			size: saved.size
+		};
+	}
+	/**
+	* `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() {
+		return this.saveLayerArtifactImpl(true);
+	}
+	/**
+	* `saveLayerArtifactEx` onto a file: nothing reaches `path` when nothing
+	* changed since load. The delta inside is streamed, never held whole.
+	* Native only.
+	*/
+	saveLayerArtifactToFileEx(path) {
+		this.requireLayer();
+		return this.saveLayerToFileImpl(path, "artifact");
+	}
+	/** `saveLayerDeltaEx` onto a file: the cumulative delta, or nothing when nothing changed since load. Native only. */
+	saveLayerDeltaToFileEx(path) {
+		this.requireLayer();
+		return this.saveLayerToFileImpl(path, "delta");
+	}
+	saveLayerToFileImpl(path, what) {
+		const { mem, fn } = this.runtime;
+		const statusPtr = mem.alloc(4);
+		const changedPtr = mem.alloc(4);
+		this.runtime.fileWrite.removeFile(path);
+		const writer = this.runtime.fileWrite.toNodeFile(path);
+		try {
+			mem.poke(statusPtr, "i32", -1);
+			mem.poke(changedPtr, "i32", 1);
+			const ok = what === "artifact" ? fn.EPDFLayer_SaveLayerArtifactEx(this.session.requireDocPtr(), writer.ptr, statusPtr, changedPtr) : fn.EPDFLayer_SaveDeltaEx(this.session.requireDocPtr(), writer.ptr, statusPtr, changedPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			if (!ok || status !== 0) throw layerSaveError(status);
+			return {
+				path,
+				changedSinceLoad: Number(mem.peek(changedPtr, "i32")) !== 0
+			};
+		} finally {
+			writer.close();
+			mem.free(changedPtr);
+			mem.free(statusPtr);
+		}
+	}
+	saveLayerArtifactImpl(reporting) {
+		this.requireLayer();
+		const { mem, fn } = this.runtime;
+		const sizePtr = mem.alloc(4);
+		const statusPtr = mem.alloc(4);
+		const changedPtr = mem.alloc(4);
+		let artifactPtr = null;
+		try {
+			mem.poke(sizePtr, "i32", 0);
+			mem.poke(statusPtr, "i32", -1);
+			mem.poke(changedPtr, "i32", 1);
+			artifactPtr = reporting ? fn.EPDFLayer_SaveLayerArtifactToOwnedBufferEx(this.session.requireDocPtr(), sizePtr, statusPtr, changedPtr) : fn.EPDFLayer_SaveLayerArtifactToOwnedBuffer(this.session.requireDocPtr(), sizePtr, statusPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			const size = Number(mem.peek(sizePtr, "i32"));
+			const changedSinceLoad = reporting ? Number(mem.peek(changedPtr, "i32")) !== 0 : true;
+			if (status !== 0) throw layerSaveError(status);
+			if (reporting && !changedSinceLoad) return {
+				bytes: /* @__PURE__ */ new ArrayBuffer(0),
+				size: 0,
+				changedSinceLoad: false
+			};
+			if (!artifactPtr || size <= 0) throw layerSaveError(status);
+			const bytes = mem.readBytes(artifactPtr, size);
+			const buffer = new ArrayBuffer(bytes.byteLength);
+			new Uint8Array(buffer).set(bytes);
+			return {
+				bytes: buffer,
+				size,
+				changedSinceLoad
+			};
+		} finally {
+			if (artifactPtr) fn.EPDF_FreeBuffer(artifactPtr);
+			mem.free(changedPtr);
+			mem.free(statusPtr);
+			mem.free(sizePtr);
+		}
+	}
+	/**
+	* 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() {
+		const saved = this.saveLayerDeltaImpl(false);
+		return {
+			bytes: saved.bytes,
+			size: saved.size
+		};
+	}
+	/**
+	* `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() {
+		return this.saveLayerDeltaImpl(true);
+	}
+	saveLayerDeltaImpl(reporting) {
+		this.requireLayer();
+		const { mem, fn } = this.runtime;
+		const sizePtr = mem.alloc(4);
+		const statusPtr = mem.alloc(4);
+		const changedPtr = mem.alloc(4);
+		let deltaPtr = null;
+		try {
+			mem.poke(sizePtr, "i32", 0);
+			mem.poke(statusPtr, "i32", -1);
+			mem.poke(changedPtr, "i32", 1);
+			deltaPtr = reporting ? fn.EPDFLayer_SaveDeltaToOwnedBufferEx(this.session.requireDocPtr(), sizePtr, statusPtr, changedPtr) : fn.EPDFLayer_SaveDeltaToOwnedBuffer(this.session.requireDocPtr(), sizePtr, statusPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			const size = Number(mem.peek(sizePtr, "i32"));
+			const changedSinceLoad = reporting ? Number(mem.peek(changedPtr, "i32")) !== 0 : true;
+			if (status !== 0) throw layerSaveError(status);
+			if (!deltaPtr || size <= 0) return {
+				bytes: /* @__PURE__ */ new ArrayBuffer(0),
+				size: 0,
+				changedSinceLoad
+			};
+			const bytes = mem.readBytes(deltaPtr, size);
+			const buffer = new ArrayBuffer(bytes.byteLength);
+			new Uint8Array(buffer).set(bytes);
+			return {
+				bytes: buffer,
+				size,
+				changedSinceLoad
+			};
+		} finally {
+			if (deltaPtr) fn.EPDF_FreeBuffer(deltaPtr);
+			mem.free(changedPtr);
+			mem.free(statusPtr);
+			mem.free(sizePtr);
+		}
+	}
+	saveLayerArtifactToFile(path) {
+		this.requireLayer();
+		const { mem, fn } = this.runtime;
+		const statusPtr = mem.alloc(4);
+		const writer = this.runtime.fileWrite.toNodeFile(path);
+		try {
+			mem.poke(statusPtr, "i32", -1);
+			const ok = fn.EPDFLayer_SaveLayerArtifact(this.session.requireDocPtr(), writer.ptr, statusPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			if (!ok || status !== 0) throw layerSaveError(status);
+			return { path };
+		} finally {
+			writer.close();
+			mem.free(statusPtr);
+		}
+	}
+	saveStandaloneToBuffer(mode) {
+		const { mem, fn } = this.runtime;
+		const sizePtr = mem.alloc(4);
+		let pdfPtr = null;
+		try {
+			mem.poke(sizePtr, "i32", 0);
+			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(this.session.requireDocPtr(), pdfSaveModeFlags(mode), sizePtr);
+			const size = Number(mem.peek(sizePtr, "i32"));
+			if (!pdfPtr || size <= 0) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
+			const bytes = mem.readBytes(pdfPtr, size);
+			const buffer = new ArrayBuffer(bytes.byteLength);
+			new Uint8Array(buffer).set(bytes);
+			return {
+				bytes: buffer,
+				size
+			};
+		} finally {
+			if (pdfPtr) fn.EPDF_FreeBuffer(pdfPtr);
+			mem.free(sizePtr);
+		}
+	}
+	/**
+	* `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) {
+		const { mem, fn } = this.runtime;
+		const sizePtr = mem.alloc(4);
+		const statusPtr = mem.alloc(4);
+		let pdfPtr = null;
+		try {
+			mem.poke(sizePtr, "i32", 0);
+			mem.poke(statusPtr, "i32", 0);
+			pdfPtr = fn.EPDF_SaveDocumentToOwnedBufferEx(this.session.requireDocPtr(), pdfSaveModeFlags(mode), 0, sizePtr, statusPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			if (status === EPDF_SAVE_UNCHANGED_SINCE_LOAD) return {
+				bytes: /* @__PURE__ */ new ArrayBuffer(0),
+				size: 0,
+				unchangedSinceLoad: true
+			};
+			const size = Number(mem.peek(sizePtr, "i32"));
+			if (!pdfPtr || size <= 0 || status !== EPDF_SAVE_WRITTEN) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
+			const bytes = mem.readBytes(pdfPtr, size);
+			const buffer = new ArrayBuffer(bytes.byteLength);
+			new Uint8Array(buffer).set(bytes);
+			return {
+				bytes: buffer,
+				size,
+				unchangedSinceLoad: false
+			};
+		} finally {
+			if (pdfPtr) fn.EPDF_FreeBuffer(pdfPtr);
+			mem.free(statusPtr);
+			mem.free(sizePtr);
+		}
+	}
+	saveStandaloneToFile(path, mode) {
+		const writer = this.runtime.fileWrite.toNodeFile(path);
+		try {
+			if (!this.runtime.fn.FPDF_SaveAsCopy(this.session.requireDocPtr(), writer.ptr, pdfSaveModeFlags(mode))) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
+			return { path };
+		} finally {
+			writer.close();
+		}
+	}
+	/**
+	* `saveStandaloneToFile` with the report of `saveStandaloneToBufferEx`.
+	* On `unchangedSinceLoad` no byte reached the file: the caller streams
+	* the loaded bytes instead.
+	*/
+	saveStandaloneToFileEx(path, mode) {
+		const { mem, fn } = this.runtime;
+		const writer = this.runtime.fileWrite.toNodeFile(path);
+		const statusPtr = mem.alloc(4);
+		try {
+			mem.poke(statusPtr, "i32", 0);
+			const ok = fn.EPDF_SaveAsCopyEx(this.session.requireDocPtr(), writer.ptr, pdfSaveModeFlags(mode), statusPtr);
+			const status = Number(mem.peek(statusPtr, "i32"));
+			if (!ok || status === 0) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
+			return {
+				path,
+				unchangedSinceLoad: status === EPDF_SAVE_UNCHANGED_SINCE_LOAD
+			};
+		} finally {
+			mem.free(statusPtr);
+			writer.close();
+		}
+	}
+	requireLayer() {
+		if (this.session.kind !== "layer") throw new EngineError(EngineErrorCode.InvalidArg, "document session is not a layer");
+	}
+};
+//#endregion
+//#region src/features/signature/internal/candidateStore.ts
+function copyOut(view) {
+	const out = new Uint8Array(view.byteLength);
+	out.set(view);
+	return out;
+}
+/** Marshal `EPDFSig_SealSpan` over a span held in the runtime heap. */
+function sealSpanInHeap(runtime, spanPtr, spanLength, objectOffset, fileLength) {
+	const { fn, mem } = runtime;
+	return withScratchN(mem, [
+		32,
+		8,
+		8
+	], ([rangePtr, coPtr, chPtr]) => {
+		for (let k = 0; k < 4; k++) pokeU64(mem, rangePtr, 0, k * 8);
+		pokeU64(mem, coPtr, 0);
+		pokeU64(mem, chPtr, 0);
+		if (!fn.EPDFSig_SealSpan(spanPtr, BigInt(spanLength), BigInt(objectOffset), BigInt(fileLength), rangePtr, coPtr, chPtr)) throw new EngineError(EngineErrorCode.Unknown, "failed to seal the signing candidate");
+		return {
+			byteRange: [
+				peekU64(mem, rangePtr, 0),
+				peekU64(mem, rangePtr, 8),
+				peekU64(mem, rangePtr, 16),
+				peekU64(mem, rangePtr, 24)
+			],
+			contentsOffset: peekU64(mem, coPtr),
+			contentsHexLength: peekU64(mem, chPtr)
+		};
+	});
+}
+/** Marshal `EPDFSig_WriteContents` over a buffer in the heap whose first byte is file offset `bufferOffset`. */
+function writeContentsInHeap(runtime, bufPtr, bufferLength, bufferOffset, sealed, cms) {
+	const { fn, mem } = runtime;
+	const cmsPtr = mem.alloc(cms.byteLength);
+	try {
+		mem.writeBytes(cmsPtr, cms);
+		if (!fn.EPDFSig_WriteContents(bufPtr, BigInt(bufferLength), BigInt(sealed.contentsOffset - bufferOffset), BigInt(sealed.contentsHexLength), cmsPtr, cms.byteLength)) throw new EngineError(EngineErrorCode.SignatureRefused, "the CMS is not one DER object that fits the reserved /Contents");
+	} finally {
+		mem.free(cmsPtr);
+	}
+}
+/**
+* Hex-encode `cms` into the /Contents hole of a candidate FILE, in place.
+* Only the hole (`<`, the hex digits, `>`) is read and written back; the
+* delimiters are checked so a wrong offset patches nothing.
+*/
+function writeContentsIntoFile(runtime, path, hole, cms) {
+	const { mem } = runtime;
+	const span = runtime.fileAccess.readRange(path, hole.holeOffset, hole.hexLength + 2);
+	if (span.byteLength !== hole.hexLength + 2 || span[0] !== 60 || span[span.byteLength - 1] !== 62) throw new EngineError(EngineErrorCode.InvalidArg, "the byteRange gap is not a <…> /Contents hole of the candidate");
+	const spanPtr = mem.alloc(span.byteLength);
+	try {
+		mem.writeBytes(spanPtr, span);
+		writeContentsInHeap(runtime, spanPtr, span.byteLength, hole.holeOffset, {
+			byteRange: [
+				0,
+				0,
+				0,
+				0
+			],
+			contentsOffset: hole.holeOffset + 1,
+			contentsHexLength: hole.hexLength,
+			digest: /* @__PURE__ */ new Uint8Array()
+		}, cms);
+		runtime.fileWrite.writeRange(path, hole.holeOffset, mem.readBytes(spanPtr, span.byteLength));
+	} finally {
+		mem.free(spanPtr);
+	}
+}
+var MemoryCandidateStore = class {
+	constructor(runtime, baseDocuments) {
+		this.runtime = runtime;
+		this.baseDocuments = baseDocuments;
+	}
+	save(candidateDocPtr, sigObjNum) {
+		const { mem, fn } = this.runtime;
+		return withScratchN(mem, [
+			8,
+			8,
+			8
+		], ([sizePtr, offPtr, lenPtr]) => {
+			pokeU64(mem, sizePtr, 0);
+			pokeU64(mem, offPtr, 0);
+			pokeU64(mem, lenPtr, 0);
+			const bufPtr = fn.EPDFSig_SaveCandidateToOwnedBuffer(candidateDocPtr, sigObjNum, sizePtr, offPtr, lenPtr);
+			if (!bufPtr) throw new EngineError(EngineErrorCode.Unknown, "failed to save the signing candidate");
+			try {
+				const size = peekU64(mem, sizePtr);
+				return {
+					kind: "memory",
+					bytes: copyOut(mem.readBytes(bufPtr, size)),
+					size,
+					objectOffset: peekU64(mem, offPtr),
+					objectLength: peekU64(mem, lenPtr)
+				};
+			} finally {
+				fn.EPDF_FreeBuffer(bufPtr);
+			}
+		});
+	}
+	seal(saved, algorithm) {
+		if (saved.kind !== "memory") throw new EngineError(EngineErrorCode.InvalidArg, "not a memory candidate");
+		const { mem, fn } = this.runtime;
+		const bufPtr = mem.alloc(saved.bytes.byteLength);
+		try {
+			mem.writeBytes(bufPtr, saved.bytes);
+			return withScratchN(mem, [
+				32,
+				8,
+				8,
+				64,
+				8
+			], ([rangePtr, coPtr, chPtr, digestPtr, lenPtr]) => {
+				for (let k = 0; k < 4; k++) pokeU64(mem, rangePtr, 0, k * 8);
+				pokeU64(mem, coPtr, 0);
+				pokeU64(mem, chPtr, 0);
+				pokeU64(mem, lenPtr, 64);
+				if (!fn.EPDFSig_Seal(bufPtr, BigInt(saved.bytes.byteLength), BigInt(saved.objectOffset), BigInt(saved.objectLength), DIGEST_CODE[algorithm], rangePtr, coPtr, chPtr, digestPtr, lenPtr)) throw new EngineError(EngineErrorCode.Unknown, "failed to seal the signing candidate");
+				saved.bytes = copyOut(mem.readBytes(bufPtr, saved.bytes.byteLength));
+				const digestLength = Number(mem.peek(lenPtr, "i32"));
+				return {
+					byteRange: [
+						peekU64(mem, rangePtr, 0),
+						peekU64(mem, rangePtr, 8),
+						peekU64(mem, rangePtr, 16),
+						peekU64(mem, rangePtr, 24)
+					],
+					contentsOffset: peekU64(mem, coPtr),
+					contentsHexLength: peekU64(mem, chPtr),
+					digest: copyOut(mem.readBytes(digestPtr, digestLength))
+				};
+			});
+		} finally {
+			mem.free(bufPtr);
+		}
+	}
+	writeContents(saved, sealed, cms) {
+		if (saved.kind !== "memory") throw new EngineError(EngineErrorCode.InvalidArg, "not a memory candidate");
+		const { mem } = this.runtime;
+		const bufPtr = mem.alloc(saved.bytes.byteLength);
+		try {
+			mem.writeBytes(bufPtr, saved.bytes);
+			writeContentsInHeap(this.runtime, bufPtr, saved.bytes.byteLength, 0, sealed, cms);
+			saved.bytes = copyOut(mem.readBytes(bufPtr, saved.bytes.byteLength));
+		} finally {
+			mem.free(bufPtr);
+		}
+	}
+	openSealed(saved, password) {
+		if (saved.kind !== "memory") throw new EngineError(EngineErrorCode.InvalidArg, "not a memory candidate");
+		const base = this.baseDocuments.acquireMemoryBase({
+			key: `signed:${generateUuid()}`,
+			bytes: saved.bytes,
+			password
+		});
+		return openLayerDocument(this.runtime, base, { kind: "fresh" }, password);
+	}
+	discard() {}
+};
+/**
+* A candidate written next to the session's base file, through the
+* runtime's local-file surface: the base streams through the writer, the
+* seal patches the object span in place, the digest streams the file, and
+* the sealed file becomes a file base. Only the object span and the CMS
+* are ever held in memory. Node runtimes only.
+*/
+var FileCandidateStore = class {
+	constructor(runtime, baseDocuments, basePath, candidatePath = defaultCandidatePath) {
+		this.runtime = runtime;
+		this.baseDocuments = baseDocuments;
+		this.basePath = basePath;
+		this.candidatePath = candidatePath;
+	}
+	save(candidateDocPtr, sigObjNum, signingId) {
+		const { mem, fn } = this.runtime;
+		const path = this.candidatePath(this.basePath, signingId);
+		this.runtime.fileWrite.removeFile(path);
+		const writer = this.runtime.fileWrite.toNodeFile(path);
+		try {
+			return withScratchN(mem, [
+				8,
+				8,
+				8
+			], ([sizePtr, offPtr, lenPtr]) => {
+				pokeU64(mem, sizePtr, 0);
+				pokeU64(mem, offPtr, 0);
+				pokeU64(mem, lenPtr, 0);
+				if (!fn.EPDFSig_SaveCandidate(candidateDocPtr, sigObjNum, writer.ptr, sizePtr, offPtr, lenPtr)) throw new EngineError(EngineErrorCode.Unknown, "failed to save the signing candidate");
+				return {
+					kind: "file",
+					path,
+					size: peekU64(mem, sizePtr),
+					objectOffset: peekU64(mem, offPtr),
+					objectLength: peekU64(mem, lenPtr)
+				};
+			});
+		} catch (error) {
+			writer.close();
+			this.runtime.fileWrite.removeFile(path);
+			throw error;
+		} finally {
+			writer.close();
+		}
+	}
+	seal(saved, algorithm) {
+		if (saved.kind !== "file") throw new EngineError(EngineErrorCode.InvalidArg, "not a file candidate");
+		const { mem, fn } = this.runtime;
+		const span = this.runtime.fileAccess.readRange(saved.path, saved.objectOffset, saved.objectLength);
+		if (span.byteLength !== saved.objectLength) throw new EngineError(EngineErrorCode.Unknown, "the signing candidate file is shorter than its object span");
+		const spanPtr = mem.alloc(span.byteLength);
+		let plan;
+		try {
+			mem.writeBytes(spanPtr, span);
+			plan = sealSpanInHeap(this.runtime, spanPtr, span.byteLength, saved.objectOffset, saved.size);
+			this.runtime.fileWrite.writeRange(saved.path, saved.objectOffset, mem.readBytes(spanPtr, span.byteLength));
+		} finally {
+			mem.free(spanPtr);
+		}
+		const access = this.runtime.fileAccess.fromNodeFile(saved.path);
+		try {
+			const digest = withScratchN(mem, [
+				32,
+				64,
+				8
+			], ([rangePtr, digestPtr, lenPtr]) => {
+				for (let k = 0; k < 4; k++) pokeU64(mem, rangePtr, plan.byteRange[k], k * 8);
+				pokeU64(mem, lenPtr, 64);
+				if (!fn.EPDFSig_DigestFileRange(access.ptr, rangePtr, DIGEST_CODE[algorithm], digestPtr, lenPtr)) throw new EngineError(EngineErrorCode.Unknown, "failed to digest the signing candidate file");
+				return copyOut(mem.readBytes(digestPtr, Number(mem.peek(lenPtr, "i32"))));
+			});
+			return {
+				...plan,
+				digest
+			};
+		} finally {
+			access.close();
+		}
+	}
+	writeContents(saved, sealed, cms) {
+		if (saved.kind !== "file") throw new EngineError(EngineErrorCode.InvalidArg, "not a file candidate");
+		const { mem } = this.runtime;
+		const span = this.runtime.fileAccess.readRange(saved.path, saved.objectOffset, saved.objectLength);
+		const spanPtr = mem.alloc(span.byteLength);
+		try {
+			mem.writeBytes(spanPtr, span);
+			writeContentsInHeap(this.runtime, spanPtr, span.byteLength, saved.objectOffset, sealed, cms);
+			this.runtime.fileWrite.writeRange(saved.path, saved.objectOffset, mem.readBytes(spanPtr, span.byteLength));
+		} finally {
+			mem.free(spanPtr);
+		}
+	}
+	openSealed(saved, password) {
+		if (saved.kind !== "file") throw new EngineError(EngineErrorCode.InvalidArg, "not a file candidate");
+		const base = this.baseDocuments.acquireFileBase({
+			key: `signed:${saved.path}`,
+			path: saved.path,
+			password
+		});
+		return openLayerDocument(this.runtime, base, { kind: "fresh" }, password);
+	}
+	discard(saved) {
+		if (saved.kind === "file") this.runtime.fileWrite.removeFile(saved.path);
+	}
+};
+/** Beside the base file, named by the signing; the host may override this (server storage layout). */
+function defaultCandidatePath(basePath, signingId) {
+	return `${basePath}.signing-${signingId}.pdf`;
+}
+/**
+* A scratch file beside the base: `<base>.<tag>-<id>.<ext>`. Unique per
+* id, so a file a document holds open is never rewritten; the caller that
+* names it registers its removal before anything writes it.
+*/
+function scratchPath(basePath, tag, id, ext) {
+	return `${basePath}.${tag}-${id}.${ext}`;
+}
+//#endregion
+//#region src/features/signature/internal/appearance.ts
+/** `EPDF_STAMP_FIT_CONTAIN`: uniform scale, letterboxed and centred in the rect. */
+const FIT_CONTAIN = 0;
+/**
+* Draw one page of a PDF into a widget annotation's normal appearance —
+* what a signature's mark is, whether the field is being signed
+* (`SignatureMutator`) or only filled visually (`FormMutator`).
+*
+* Two fork calls, the same pair the stamp path makes: `SetAppearanceFromPage`
+* clones the page into the document as a wrapped Form XObject (page content
+* and resources in a child form, the outer stream a placement matrix), then
+* `UpdateAppearanceToRect` writes that placement — the page fitted uniformly
+* into the widget's rect. Without the second call the page sits in its own
+* box and the viewer's BBox→/Rect mapping stretches it to the rect's aspect.
+*/
+function bakeWidgetAppearance(runtime, docPtr, widget, pdf, pageIndex) {
+	const { mem, fn } = runtime;
+	const stack = new CloseStack();
+	try {
+		const pagePtr = fn.EPDFDoc_LoadPageByObjectNumber(docPtr, widget.pageObjectNumber);
+		if (!pagePtr) throw new EngineError(EngineErrorCode.NotFound, "the widget page could not be loaded");
+		stack.push(() => fn.FPDF_ClosePage(pagePtr));
+		const annotPtr = fn.EPDFPage_GetAnnotByObjectNumber(pagePtr, widget.annotObjectNumber);
+		if (!annotPtr) throw new EngineError(EngineErrorCode.NotFound, "the signature widget could not be loaded");
+		stack.push(() => fn.FPDFPage_CloseAnnot(annotPtr));
+		const dataPtr = mem.alloc(pdf.byteLength);
+		stack.push(() => mem.free(dataPtr));
+		mem.writeBytes(dataPtr, pdf);
+		const artworkPtr = fn.FPDF_LoadMemDocument64(dataPtr, pdf.byteLength, "");
+		if (!artworkPtr) throw new EngineError(EngineErrorCode.MalformedPdf, "the appearance PDF could not be opened");
+		stack.push(() => fn.FPDF_CloseDocument(artworkPtr));
+		if (!fn.EPDFAnnot_SetAppearanceFromPage(annotPtr, artworkPtr, pageIndex)) throw new EngineError(EngineErrorCode.InvalidArg, "the appearance page could not be drawn into the widget");
+		if (!fn.EPDFAnnot_UpdateAppearanceToRect(annotPtr, FIT_CONTAIN)) throw new EngineError(EngineErrorCode.Unknown, "the appearance page could not be fitted into the widget");
+	} finally {
+		stack.close();
+	}
+}
+//#endregion
+//#region src/features/signature/internal/sealCheck.ts
+/**
+* The one check both signing paths make before sealed bytes become a
+* version — the in-session complete and the server's session-less
+* finalize. Reading the result back through the ordinary signature model
+* proves the bytes, not the writer: the field is signed, its signature
+* covers the whole LAST revision (the candidate's own, never an earlier
+* one), its /ByteRange is the one the digest was computed over, and the
+* /Contents decode to exactly the CMS installed. Anything else is refused
+* and the bytes are never installed.
+*/
+function assertSealedSignature(runtime, docPtr, model, expected) {
+	const refuse = (why) => new EngineError(EngineErrorCode.SignatureRefused, `the sealed bytes ${why}`);
+	const signatures = readSignaturesFromModel(runtime, model);
+	const signature = signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === expected.fieldObjectNumber);
+	if (!signature) throw refuse("lost the signature field");
+	if (!signature.signed || signature.coverage !== "whole-revision" || !signature.byteRange) throw refuse("do not carry a whole-revision signature on the field");
+	if (!sameRange(signature.byteRange, expected.byteRange)) throw refuse(`carry /ByteRange [${signature.byteRange.join(" ")}] where [${expected.byteRange.join(" ")}] was sealed`);
+	if (!runtime.fn.EPDFSig_IsRevisionChainValid(model)) throw refuse("have a broken cross-reference chain");
+	const revisions = readRevisions(runtime, docPtr, signatures);
+	if (signature.revisionIndex !== revisions.length - 1) throw refuse("seal an earlier revision than the candidate");
+	if (!bytesEqual(readContentsAt(runtime, model, signature.index), expected.cms)) throw refuse("carry /Contents that are not the CMS installed");
+	return signature;
+}
+function sameRange(a, b) {
+	return a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];
+}
+function bytesEqual(a, b) {
+	if (a.byteLength !== b.byteLength) return false;
+	for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+//#endregion
+//#region src/features/forms/internal/wideStringArray.ts
+/**
+* Marshal a `const FPDF_WIDESTRING*` array: encode every string into the
+* runtime heap, write the pointer table with the runtime's pointer width
+* (bigint pointers cannot be poked into the wasm 32-bit heap), run |body|,
+* free everything.
+*/
+function withWideStringArray(runtime, values, body) {
+	const { mem } = runtime;
+	const stringPtrs = values.map((value) => mem.writeU16String(value));
+	const isWasm = runtime.kind === "wasm";
+	const ptrSize = isWasm ? 4 : 8;
+	try {
+		return withScratch(mem, Math.max(1, stringPtrs.length * ptrSize), (arrayPtr) => {
+			stringPtrs.forEach((ptr, i) => isWasm ? mem.poke(arrayPtr, "i32", Number(ptr), i * 4) : mem.poke(arrayPtr, "i64", ptr, i * 8));
+			return body(arrayPtr, stringPtrs.length);
+		});
+	} finally {
+		for (let i = stringPtrs.length - 1; i >= 0; i--) mem.free(stringPtrs[i]);
+	}
+}
+//#endregion
+//#region src/features/signature/SignatureMutator.ts
+const SUBFILTER_CODE = {
+	"adbe.pkcs7.detached": 0,
+	"ETSI.CAdES.detached": 1,
+	"ETSI.RFC3161": 2
+};
+const FIELD_ACTION_CODE = {
+	all: 1,
+	include: 2,
+	exclude: 3
+};
+const DEFAULT_CONTENTS_SIZE = 8192;
+const MIN_CONTENTS_SIZE = 256;
+const MAX_CONTENTS_SIZE = 4 * 1024 * 1024;
+const PREPARE_ILP32 = {
+	bytes: 52,
+	ptrBytes: 4,
+	subfilter: 0,
+	digest: 4,
+	contentsSize: 8,
+	name: 12,
+	reason: 16,
+	location: 20,
+	contactInfo: 24,
+	signingTime: 28,
+	docmdpPermission: 32,
+	fieldmdpAction: 36,
+	fieldmdpFields: 40,
+	fieldmdpFieldCount: 44,
+	lockPermission: 48
+};
+const PREPARE_LP64 = {
+	bytes: 80,
+	ptrBytes: 8,
+	subfilter: 0,
+	digest: 4,
+	contentsSize: 8,
+	name: 16,
+	reason: 24,
+	location: 32,
+	contactInfo: 40,
+	signingTime: 48,
+	docmdpPermission: 56,
+	fieldmdpAction: 60,
+	fieldmdpFields: 64,
+	fieldmdpFieldCount: 72,
+	lockPermission: 76
+};
+/**
+* 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.
+*/
+var SignatureMutator = class {
+	constructor(runtime, session, baseDocuments, candidatePath) {
+		this.runtime = runtime;
+		this.session = session;
+		this.baseDocuments = baseDocuments;
+		this.candidatePath = candidatePath;
+	}
+	prepare(input) {
+		if (this.session.pendingSigning) throw new EngineError(EngineErrorCode.SigningPending, `a signing is pending (${this.session.pendingSigning.prepared.signingId}); complete or abort it first`);
+		const reader = new SignatureReader(this.runtime, this.session);
+		const field = reader.resolveField(input.field);
+		if (field.signed) throw new EngineError(EngineErrorCode.SignatureRefused, "the signature field is already signed");
+		if (input.appearance && !field.widget) throw new EngineError(EngineErrorCode.SignatureRefused, "the signature field has no widget to carry an appearance");
+		const algorithm = input.digest ?? "sha256";
+		if (!(algorithm in DIGEST_CODE) || algorithm === "sha1") throw new EngineError(EngineErrorCode.SignatureRefused, `unsupported digest '${algorithm}'`);
+		const subFilter = (input.kind ?? "signature") === "timestamp" ? "ETSI.RFC3161" : input.subFilter ?? "ETSI.CAdES.detached";
+		if (!(subFilter in SUBFILTER_CODE)) throw new EngineError(EngineErrorCode.SignatureRefused, `unsupported subFilter '${subFilter}'`);
+		const contentsSize = input.contentsSize ?? DEFAULT_CONTENTS_SIZE;
+		if (!Number.isInteger(contentsSize) || contentsSize < MIN_CONTENTS_SIZE || contentsSize > MAX_CONTENTS_SIZE) throw new EngineError(EngineErrorCode.SignatureRefused, `contentsSize must be an integer in [${MIN_CONTENTS_SIZE}, ${MAX_CONTENTS_SIZE}]`);
+		const expectedVersion = this.session.versionRef(reader.version().sha256);
+		const signingId = generateUuid();
+		const stack = new CloseStack();
+		try {
+			const candidate = this.openCandidate(signingId, stack);
+			stack.push(() => candidate.close());
+			const attribution = input.attribution ?? input.signer;
+			const valueObjNum = this.callPrepare(candidate.docPtr, field.fieldObjectNumber, {
+				subfilter: SUBFILTER_CODE[subFilter],
+				digest: DIGEST_CODE[algorithm],
+				contentsSize,
+				name: attribution?.name ?? null,
+				reason: attribution?.reason ?? null,
+				location: attribution?.location ?? null,
+				contactInfo: attribution?.contactInfo ?? null,
+				signingTime: input.signingTime ?? null,
+				docmdpPermission: input.certify?.permission ?? 0,
+				fieldmdpAction: input.lock ? FIELD_ACTION_CODE[input.lock.action] : 0,
+				fieldmdpFields: input.lock?.action === "all" ? [] : input.lock?.fields ?? [],
+				lockPermission: input.lock?.permission ?? 0
+			});
+			if (valueObjNum === 0) throw new EngineError(EngineErrorCode.SignatureRefused, "the engine refused to author the signature (the field is signed, read-only or locked, a certification is not allowed here, the seed value requires what is not implemented, or the request is inconsistent)");
+			if (input.appearance && field.widget) bakeWidgetAppearance(this.runtime, candidate.docPtr, field.widget, input.appearance.pdf, input.appearance.pageIndex ?? 0);
+			const store = this.storeFor();
+			const saved = store.save(candidate.docPtr, valueObjNum, signingId);
+			let sealed;
+			try {
+				sealed = store.seal(saved, algorithm);
+			} catch (error) {
+				store.discard(saved);
+				throw error;
+			}
+			const prepared = {
+				signingId,
+				digest: sealed.digest,
+				algorithm,
+				byteRange: sealed.byteRange,
+				contentsSize,
+				subFilter,
+				expectedVersion,
+				expiresAt: null
+			};
+			this.session.pendingSigning = {
+				prepared,
+				fieldObjectNumber: field.fieldObjectNumber,
+				saved,
+				contentsOffset: sealed.contentsOffset,
+				contentsHexLength: sealed.contentsHexLength
+			};
+			return prepared;
+		} finally {
+			stack.close();
+		}
+	}
+	complete(input) {
+		const pending = this.session.pendingSigning;
+		if (!pending || pending.prepared.signingId !== input.signingId) {
+			const last = this.session.lastCompletion;
+			if (last && last.signingId === input.signingId) {
+				if (!bytesEqual(last.cms, input.cms)) throw new EngineError(EngineErrorCode.SignatureRefused, "this signing already completed with a different CMS");
+				return {
+					...last.result,
+					status: "already-completed"
+				};
+			}
+			throw new EngineError(EngineErrorCode.NotFound, `no pending signing '${input.signingId}'`);
+		}
+		if (!sameVersion(pending.prepared.expectedVersion, input.expectedVersion)) throw new EngineError(EngineErrorCode.SigningVersionMismatch, "expectedVersion is not the version the candidate was prepared on");
+		if (input.cms.byteLength === 0 || input.cms[0] !== 48) throw new EngineError(EngineErrorCode.SignatureRefused, "the CMS is not a DER SEQUENCE");
+		if (input.cms.byteLength > pending.prepared.contentsSize) throw new EngineError(EngineErrorCode.SignatureRefused, `the CMS (${input.cms.byteLength} bytes) does not fit the reserved ${pending.prepared.contentsSize} bytes`);
+		const store = this.storeFor();
+		const sealed = {
+			byteRange: pending.prepared.byteRange,
+			contentsOffset: pending.contentsOffset,
+			contentsHexLength: pending.contentsHexLength,
+			digest: pending.prepared.digest
+		};
+		store.writeContents(pending.saved, sealed, input.cms);
+		const handle = store.openSealed(pending.saved, this.session.password);
+		this.verifySealed(handle, {
+			fieldObjectNumber: pending.fieldObjectNumber,
+			byteRange: pending.prepared.byteRange,
+			cms: input.cms
+		});
+		this.session.install(handle);
+		disposeFormModel(this.runtime, this.session);
+		disposeSignatureModel(this.runtime, this.session);
+		const reader = new SignatureReader(this.runtime, this.session);
+		const snapshot = reader.readSnapshot();
+		const signature = snapshot.signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === pending.fieldObjectNumber);
+		if (!signature) throw new EngineError(EngineErrorCode.Unknown, "the installed document lost the signature field");
+		const result = {
+			status: "completed",
+			signature,
+			version: reader.version(),
+			previous: pending.prepared.expectedVersion,
+			protection: snapshot.protection,
+			meta: {
+				affectedPages: this.session.allRecords().map((r) => this.session.pageState(r.pageObjectNumber)),
+				cacheDelta: null
+			}
+		};
+		this.session.lastCompletion = {
+			signingId: input.signingId,
+			cms: input.cms.slice(),
+			result
+		};
+		return result;
+	}
+	abort(signingId) {
+		const pending = this.session.pendingSigning;
+		if (pending && pending.prepared.signingId === signingId) {
+			this.session.pendingSigning = null;
+			this.storeFor().discard(pending.saved);
+			return { status: "aborted" };
+		}
+		if (this.session.lastCompletion?.signingId === signingId) return { status: "already-completed" };
+		return { status: "unknown" };
+	}
+	callPrepare(docPtr, fieldObjectNumber, opts) {
+		const { mem, fn } = this.runtime;
+		const layout = this.runtime.kind === "wasm" ? PREPARE_ILP32 : PREPARE_LP64;
+		const owned = [];
+		const wide = (value) => {
+			if (value === null) return NULL_PTR;
+			const ptr = mem.writeU16String(value);
+			owned.push(ptr);
+			return ptr;
+		};
+		const utf8 = (value) => {
+			if (value === null) return NULL_PTR;
+			const ptr = mem.writeU8String(value);
+			owned.push(ptr);
+			return ptr;
+		};
+		try {
+			return withWideStringArray(this.runtime, opts.fieldmdpFields, (fieldsPtr, fieldCount) => withScratch(mem, layout.bytes, (structPtr) => {
+				for (let off = 0; off < layout.bytes; off += 4) mem.poke(structPtr, "i32", 0, off);
+				const pokePtr = (offset, ptr) => {
+					if (layout.ptrBytes === 4) mem.poke(structPtr, "i32", Number(ptr), offset);
+					else mem.poke(structPtr, "i64", ptr, offset);
+				};
+				mem.poke(structPtr, "i32", opts.subfilter, layout.subfilter);
+				mem.poke(structPtr, "i32", opts.digest, layout.digest);
+				mem.poke(structPtr, "i32", opts.contentsSize, layout.contentsSize);
+				pokePtr(layout.name, wide(opts.name));
+				pokePtr(layout.reason, wide(opts.reason));
+				pokePtr(layout.location, wide(opts.location));
+				pokePtr(layout.contactInfo, wide(opts.contactInfo));
+				pokePtr(layout.signingTime, utf8(opts.signingTime));
+				mem.poke(structPtr, "i32", opts.docmdpPermission, layout.docmdpPermission);
+				mem.poke(structPtr, "i32", opts.fieldmdpAction, layout.fieldmdpAction);
+				pokePtr(layout.fieldmdpFields, fieldCount > 0 ? fieldsPtr : NULL_PTR);
+				mem.poke(structPtr, "i32", fieldCount, layout.fieldmdpFieldCount);
+				mem.poke(structPtr, "i32", opts.lockPermission, layout.lockPermission);
+				return fn.EPDFSig_Prepare(docPtr, fieldObjectNumber, structPtr);
+			}));
+		} finally {
+			for (let i = owned.length - 1; i >= 0; i--) mem.free(owned[i]);
+		}
+	}
+	/** 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.
+	*/
+	storeFor() {
+		const base = this.session.source.base;
+		if (base?.kind === "file") return new FileCandidateStore(this.runtime, this.baseDocuments, base.path, this.candidatePath);
+		return new MemoryCandidateStore(this.runtime, this.baseDocuments);
+	}
+	/**
+	* 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.
+	*/
+	verifySealed(handle, expected) {
+		const { fn } = this.runtime;
+		try {
+			const model = fn.EPDFSig_LoadModel(handle.docPtr);
+			if (!model) throw new EngineError(EngineErrorCode.Unknown, "the sealed bytes have no signature model");
+			try {
+				assertSealedSignature(this.runtime, handle.docPtr, model, expected);
+			} finally {
+				fn.EPDFSig_CloseModel(model);
+			}
+			if (this.session.kind !== "layer") this.session.persistLayerArtifact = false;
+		} catch (error) {
+			handle.close();
+			throw error;
+		}
+	}
+	/**
+	* 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).
+	*/
+	openCandidate(signingId, stack) {
+		const password = this.session.password;
+		const source = this.session.source;
+		const saver = new DocumentSaver(this.runtime, this.session);
+		const scratch = saver.canWriteScratchFiles() && source.base?.kind === "file" ? source.base.path : null;
+		if (this.session.kind === "layer" && source.base && !this.loadedDeltaHoldsSignedBytes()) {
+			const base = this.baseDocuments.retainByKey(source.base.key);
+			if (base) {
+				let layer = source.layer ?? { kind: "fresh" };
+				if (this.session.hasUnsavedEdits()) if (scratch) {
+					const path = scratchPath(scratch, "signing", signingId, "layer");
+					stack.push(() => this.runtime.fileWrite.removeFile(path));
+					if (saver.saveLayerArtifactToFileEx(path).changedSinceLoad) layer = {
+						kind: "artifact-file",
+						path
+					};
+				} else {
+					const artifact = saver.saveLayerArtifactEx();
+					if (artifact.changedSinceLoad) layer = {
+						kind: "artifact",
+						bytes: artifact.bytes
+					};
+				}
+				return openLayerDocument(this.runtime, base, layer, password);
+			}
+		}
+		if (scratch) {
+			const path = scratchPath(scratch, "signing", signingId, "base.pdf");
+			stack.push(() => this.runtime.fileWrite.removeFile(path));
+			saver.snapshotToFile(path);
+			const base = this.baseDocuments.acquireFileBase({
+				key: `candidate:${signingId}`,
+				path,
+				password
+			});
+			return openLayerDocument(this.runtime, base, { kind: "fresh" }, password);
+		}
+		const candidateBytes = saver.snapshot().bytes;
+		const base = this.baseDocuments.acquireMemoryBase({
+			key: `candidate:${signingId}`,
+			bytes: new Uint8Array(candidateBytes),
+			password
+		});
+		return openLayerDocument(this.runtime, base, { kind: "fresh" }, password);
+	}
+	/** Whether a signature's byte range reaches into the layer's loaded delta (past the base). */
+	loadedDeltaHoldsSignedBytes() {
+		const layer = this.session.source.layer;
+		if (!layer || layer.kind === "fresh") return false;
+		const baseSize = Number(this.runtime.fn.EPDFDoc_GetBaseBytesSize(this.session.requireDocPtr()));
+		return new SignatureReader(this.runtime, this.session).readSnapshot().signatures.some((s) => s.signed && s.byteRange !== null && s.byteRange[2] + s.byteRange[3] > baseSize);
+	}
+};
+function sameVersion(a, b) {
+	return a.baseSha256 === b.baseSha256 && a.editsVersion === b.editsVersion;
+}
+//#endregion
+//#region src/features/signature/SignatureAnalyzer.ts
+const CHANGE_BY_CODE = {
+	0: "added",
+	1: "modified",
+	2: "freed"
+};
+const KIND_BY_CODE = {
+	0: "dictionary",
+	1: "stream",
+	2: "array",
+	3: "scalar",
+	4: "xref",
+	5: "objstm",
+	6: "trailer"
+};
+const DIFF_OLD = 0;
+const DIFF_NEW = 1;
+/** EPDF_DIFF_READ_OK / FAILED / ABSENT. */
+const READ_BY_CODE = {
+	0: "ok",
+	1: "failed",
+	2: "absent"
+};
+/** The objects an edge may be anchored at: the trailer, the structure of the revision, and every changed object. */
+function anchorSet(s, changed) {
+	const out = /* @__PURE__ */ new Set([
+		0,
+		s.root,
+		s.pagesRoot,
+		...s.pages,
+		...changed
+	]);
+	if (s.acroForm) out.add(s.acroForm);
+	for (const f of s.fields) {
+		out.add(f.objectNumber);
+		for (const w of f.widgets) out.add(w);
+	}
+	return out;
+}
+/**
+* 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.
+*/
+var SignatureAnalyzer = class {
+	constructor(runtime, session) {
+		this.runtime = runtime;
+		this.session = session;
+	}
+	/**
+	* 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() {
+		const stack = new CloseStack();
+		try {
+			const copy = this.openWorkingCopy(stack);
+			if (copy.source === "loaded") return new SignatureReader(this.runtime, this.session).readSnapshot();
+			const target = copy.target;
+			return withSignatureModel(this.runtime, target, (model) => {
+				const chainValid = this.runtime.fn.EPDFSig_IsRevisionChainValid(model);
+				const signatures = readSignaturesFromModel(this.runtime, model);
+				return {
+					chainValid,
+					revisions: chainValid ? readRevisions(this.runtime, target, signatures) : [],
+					signatures,
+					protection: deriveProtection(signatures)
+				};
+			});
+		} finally {
+			stack.close();
+		}
+	}
+	analyze(input) {
+		const reader = new SignatureReader(this.runtime, this.session);
+		const snapshot = reader.readSnapshot();
+		const version = reader.version();
+		const mode = input.exploratoryLevel ? "exploratory" : "authoritative";
+		const detail = input.detail ?? "summary";
+		let basisSource = "persisted";
+		const editsVersion = this.session.mutationSeq();
+		let sinceRevision;
+		let sinceSignature = null;
+		if ("signatureIndex" in input.since) {
+			const sig = snapshot.signatures[input.since.signatureIndex];
+			if (!sig) throw new EngineError(EngineErrorCode.NotFound, `no signature ${input.since.signatureIndex}`);
+			if (!sig.signed || sig.revisionIndex === null) throw new EngineError(EngineErrorCode.InvalidArg, `signature ${input.since.signatureIndex} seals no whole revision; nothing to analyze from`);
+			sinceRevision = sig.revisionIndex;
+			sinceSignature = sig.index;
+		} else sinceRevision = input.since.revisionIndex;
+		if (!snapshot.chainValid) {
+			const current = {
+				verdict: "indeterminate",
+				complete: false,
+				findings: [{
+					rule: "revision-chain",
+					verdict: "incomplete",
+					objectNumber: 0,
+					detail: "the cross-reference chain is broken or was rebuilt: no revision can be told from another"
+				}],
+				method: "net-state"
+			};
+			return {
+				mode,
+				policyVersion: SIGNATURE_POLICY_VERSION,
+				basis: {
+					version,
+					editsVersion,
+					source: "persisted"
+				},
+				since: {
+					revisionIndex: sinceRevision,
+					signatureIndex: sinceSignature
+				},
+				until: { revisionIndex: sinceRevision },
+				restrictions: [],
+				current: {
+					...current,
+					primary: current.findings[0]
+				},
+				later: {
+					revisionCount: 0,
+					undoneObjectNumbers: []
+				},
+				verdict: "indeterminate",
+				steps: []
+			};
+		}
+		if (!Number.isInteger(sinceRevision) || sinceRevision < 0 || sinceRevision >= snapshot.revisions.length) throw new EngineError(EngineErrorCode.InvalidArg, `no revision ${sinceRevision}`);
+		const stack = new CloseStack();
+		try {
+			let target = this.session.requireDocPtr();
+			let revisions = snapshot.revisions;
+			const copy = input.until === "working-copy" ? this.openWorkingCopy(stack) : null;
+			if (copy && copy.source === "working-copy") {
+				basisSource = "working-copy";
+				target = copy.target;
+				const signatures = withSignatureModel(this.runtime, target, (m) => readSignaturesFromModel(this.runtime, m));
+				revisions = readRevisions(this.runtime, target, signatures);
+				if (revisions.length === 0) throw new EngineError(EngineErrorCode.MalformedPdf, "the working copy has no valid revision chain");
+			}
+			let untilRevision = revisions.length - 1;
+			if (typeof input.until === "object") {
+				untilRevision = input.until.revisionIndex;
+				if (!Number.isInteger(untilRevision) || untilRevision < sinceRevision || untilRevision >= revisions.length) throw new EngineError(EngineErrorCode.InvalidArg, `no revision ${untilRevision} at or after ${sinceRevision}`);
+			}
+			const pair = new CloseStack();
+			let before;
+			let after;
+			let changes = [];
+			let health;
+			try {
+				const sealed = this.openPrefix(target, revisions, sinceRevision, pair);
+				const judged = untilRevision === revisions.length - 1 ? target : this.openPrefix(target, revisions, untilRevision, pair);
+				before = readStructure(this.runtime, sealed);
+				after = untilRevision === sinceRevision ? before : readStructure(this.runtime, judged);
+				if (untilRevision > sinceRevision) ({changes, health} = this.compare(sealed, judged, before, after));
+			} finally {
+				pair.close();
+			}
+			const judgedSignature = sinceSignature === null ? null : before.signatures[sinceSignature] ?? null;
+			const restrictions = restrictionsFor(before, judgedSignature);
+			const levelOverride = input.exploratoryLevel;
+			const net = evaluateStep({
+				older: sinceRevision,
+				newer: untilRevision,
+				changes,
+				before,
+				after,
+				health,
+				restrictions: {
+					level: restrictions.level,
+					locks: restrictions.locks
+				},
+				levelOverride
+			});
+			const certifies = restrictions.anchors.some((r) => r.source === "docmdp" && r.own);
+			const intermediate = untilRevision - sinceRevision;
+			let steps;
+			if (intermediate <= 1) steps = intermediate === 1 ? [net] : [];
+			else if (certifies || detail === "full") steps = this.walkSteps(target, revisions, sinceRevision, untilRevision, before, {
+				level: restrictions.level,
+				locks: restrictions.locks,
+				levelOverride
+			});
+			else steps = [];
+			const current = certifies ? {
+				...combine(net, steps),
+				method: "net-state+replay"
+			} : {
+				...assessmentOf(net),
+				method: "net-state"
+			};
+			return {
+				mode,
+				policyVersion: SIGNATURE_POLICY_VERSION,
+				basis: {
+					version,
+					editsVersion,
+					source: basisSource
+				},
+				since: {
+					revisionIndex: sinceRevision,
+					signatureIndex: sinceSignature
+				},
+				until: { revisionIndex: untilRevision },
+				restrictions: restrictions.anchors,
+				current,
+				later: {
+					revisionCount: intermediate,
+					undoneObjectNumbers: changes.filter(sameEffectiveValue).map((c) => c.objectNumber)
+				},
+				verdict: current.verdict,
+				steps
+			};
+		} finally {
+			stack.close();
+		}
+	}
+	/** Revision `index` of `target`'s bytes as its own document, owned by `stack`. */
+	openPrefix(target, revisions, index, stack) {
+		const prefix = this.runtime.fn.EPDFDoc_OpenRevision(target, BigInt(revisions[index].end));
+		if (prefix === NULL_PTR) throw new EngineError(EngineErrorCode.MalformedPdf, `revision ${index} does not open as a document`);
+		stack.push(() => this.runtime.fn.FPDF_CloseDocument(prefix));
+		return prefix;
+	}
+	/**
+	* 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.
+	*/
+	walkSteps(target, revisions, since, until, sealedStructure, restrictions) {
+		const { fn } = this.runtime;
+		const steps = [];
+		let older = this.openPrefix(target, revisions, since, new CloseStack());
+		let olderStructure = sealedStructure;
+		try {
+			for (let r = since + 1; r <= until; r++) {
+				const newer = r === revisions.length - 1 ? target : this.openPrefix(target, revisions, r, new CloseStack());
+				try {
+					const newerStructure = readStructure(this.runtime, newer);
+					const { changes, health } = this.compare(older, newer, olderStructure, newerStructure);
+					steps.push(evaluateStep({
+						older: r - 1,
+						newer: r,
+						changes,
+						before: olderStructure,
+						after: newerStructure,
+						health,
+						restrictions: {
+							level: restrictions.level,
+							locks: restrictions.locks
+						},
+						levelOverride: restrictions.levelOverride
+					}));
+					olderStructure = newerStructure;
+				} finally {
+					fn.FPDF_CloseDocument(older);
+					older = newer;
+				}
+			}
+		} finally {
+			if (older !== target) fn.FPDF_CloseDocument(older);
+		}
+		return steps;
+	}
+	/**
+	* 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.
+	*/
+	openWorkingCopy(stack) {
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		if (!this.session.hasUnsavedEdits()) return {
+			target: docPtr,
+			source: "loaded"
+		};
+		const saver = new DocumentSaver(this.runtime, this.session);
+		if (this.session.kind === "layer") {
+			const base = this.session.source.base;
+			if (saver.canWriteScratchFiles() && base?.kind === "file") {
+				const path = scratchPath(base.path, "working-copy", generateUuid(), "delta");
+				stack.push(() => this.runtime.fileWrite.removeFile(path));
+				if (!saver.saveLayerDeltaToFileEx(path).changedSinceLoad) return {
+					target: docPtr,
+					source: "loaded"
+				};
+				if (this.runtime.fileAccess.sizeOf(path) === 0) return this.freshLayerOverBase(stack);
+				const overlay = withUtf8CString(mem, path, (pathPtr) => fn.EPDFDoc_OpenBaseOverlayFromPath(docPtr, pathPtr));
+				if (overlay === NULL_PTR) throw new EngineError(EngineErrorCode.MalformedPdf, "the working copy does not compose with its base");
+				stack.push(() => fn.FPDF_CloseDocument(overlay));
+				return {
+					target: overlay,
+					source: "working-copy"
+				};
+			}
+			const delta = saver.saveLayerDeltaEx();
+			if (!delta.changedSinceLoad) return {
+				target: docPtr,
+				source: "loaded"
+			};
+			if (delta.size === 0) return this.freshLayerOverBase(stack);
+			const bytes = new Uint8Array(delta.bytes);
+			const ptr = mem.alloc(bytes.byteLength);
+			try {
+				mem.writeBytes(ptr, bytes);
+				const overlay = fn.EPDFDoc_OpenBaseOverlay(docPtr, ptr, bytes.byteLength);
+				if (overlay === NULL_PTR) throw new EngineError(EngineErrorCode.MalformedPdf, "the working copy does not compose with its base");
+				stack.push(() => fn.FPDF_CloseDocument(overlay));
+				return {
+					target: overlay,
+					source: "working-copy"
+				};
+			} finally {
+				mem.free(ptr);
+			}
+		}
+		const saved = saver.saveStandaloneToBufferEx("incremental");
+		if (saved.unchangedSinceLoad) return {
+			target: docPtr,
+			source: "loaded"
+		};
+		const opened = openFatMemoryDocument(this.runtime, new Uint8Array(saved.bytes), this.session.password);
+		stack.push(() => opened.close());
+		return {
+			target: opened.docPtr,
+			source: "working-copy"
+		};
+	}
+	/** Changed since load, nothing to write: the layer equals its base, and a fresh layer over it IS that document. */
+	freshLayerOverBase(stack) {
+		const { fn, mem } = this.runtime;
+		const base = fn.EPDFLayer_GetBaseDocument(this.session.requireDocPtr());
+		const statusPtr = mem.alloc(4);
+		try {
+			mem.poke(statusPtr, "i32", -1);
+			const fresh = fn.EPDFLayer_OpenLayer(base, NULL_PTR, this.session.password ?? "", statusPtr);
+			if (fresh === NULL_PTR || Number(mem.peek(statusPtr, "i32")) !== 0) throw new EngineError(EngineErrorCode.MalformedPdf, "the working copy could not be opened over its base");
+			stack.push(() => fn.FPDF_CloseDocument(fresh));
+			return {
+				target: fresh,
+				source: "working-copy"
+			};
+		} finally {
+			mem.free(statusPtr);
+		}
+	}
+	/**
+	* 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).
+	*/
+	compare(older, newer, before, after) {
+		const { fn, mem } = this.runtime;
+		const diff = fn.EPDFDoc_CompareRevisions(older, newer);
+		if (diff === NULL_PTR) throw new EngineError(EngineErrorCode.MalformedPdf, "the revisions do not share a byte history");
 		try {
-			mem.poke(sizePtr, "i32", 0);
-			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(this.session.requireDocPtr(), pdfSaveModeFlags(mode), sizePtr);
-			const size = Number(mem.peek(sizePtr, "i32"));
-			if (!pdfPtr || size <= 0) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
-			const bytes = mem.readBytes(pdfPtr, size);
-			const buffer = new ArrayBuffer(bytes.byteLength);
-			new Uint8Array(buffer).set(bytes);
+			const count = fn.EPDFObjectDiff_GetCount(diff);
+			const changes = [];
+			withScratchN(mem, [
+				4,
+				4,
+				4,
+				4,
+				4,
+				4
+			], ([numPtr, changePtr, kindPtr, oldGenPtr, newGenPtr, streamPtr]) => {
+				for (let i = 0; i < count; i++) {
+					for (const p of [
+						numPtr,
+						changePtr,
+						kindPtr,
+						oldGenPtr,
+						newGenPtr,
+						streamPtr
+					]) mem.poke(p, "i32", 0);
+					if (!fn.EPDFObjectDiff_GetEntry(diff, i, numPtr, changePtr, kindPtr, oldGenPtr, newGenPtr, streamPtr)) throw new EngineError(EngineErrorCode.Unknown, `failed to read diff entry ${i}`);
+					const objectNumber = Number(mem.peek(numPtr, "i32")) >>> 0;
+					const oldGen = Number(mem.peek(oldGenPtr, "i32"));
+					const newGen = Number(mem.peek(newGenPtr, "i32"));
+					const oldValue = this.readValue(diff, i, DIFF_OLD);
+					const newValue = this.readValue(diff, i, DIFF_NEW);
+					let truncated = oldValue.truncated || newValue.truncated;
+					let oldParsed = null;
+					let newParsed = null;
+					try {
+						oldParsed = oldValue.text === null || oldValue.truncated ? null : parsePdfValue(oldValue.text);
+						newParsed = newValue.text === null || newValue.truncated ? null : parsePdfValue(newValue.text);
+					} catch {
+						truncated = true;
+					}
+					const change = CHANGE_BY_CODE[Number(mem.peek(changePtr, "i32"))] ?? "modified";
+					changes.push({
+						objectNumber,
+						change,
+						kind: KIND_BY_CODE[Number(mem.peek(kindPtr, "i32"))] ?? "scalar",
+						present: {
+							old: change !== "added",
+							new: change !== "freed"
+						},
+						generation: {
+							old: oldGen < 0 ? null : oldGen,
+							new: newGen < 0 ? null : newGen
+						},
+						value: {
+							old: oldParsed,
+							new: newParsed,
+							truncated
+						},
+						raw: {
+							old: oldValue.text,
+							new: newValue.text
+						},
+						read: {
+							old: READ_BY_CODE[fn.EPDFObjectDiff_GetReadStatus(diff, i, DIFF_OLD)] ?? "failed",
+							new: READ_BY_CODE[fn.EPDFObjectDiff_GetReadStatus(diff, i, DIFF_NEW)] ?? "failed"
+						},
+						streamDataChanged: Number(mem.peek(streamPtr, "i32")) !== 0,
+						usage: {
+							old: [],
+							new: []
+						}
+					});
+				}
+			});
 			return {
-				bytes: buffer,
-				size
+				changes: this.withAnchoredUsage(diff, changes, before, after),
+				health: {
+					old: this.readHealth(diff, DIFF_OLD),
+					new: this.readHealth(diff, DIFF_NEW)
+				}
 			};
 		} finally {
-			if (pdfPtr) fn.EPDF_FreeBuffer(pdfPtr);
-			mem.free(sizePtr);
+			fn.EPDFObjectDiff_Close(diff);
 		}
 	}
-	saveStandaloneToFile(path, mode) {
-		const writer = this.runtime.fileWrite.toNodeFile(path);
+	/** What the fork learned about one revision as a whole (see `RevisionHealth`). */
+	readHealth(diff, which) {
+		const { fn, mem } = this.runtime;
+		return withScratchN(mem, [
+			4,
+			4,
+			4
+		], ([sparsePtr, barePtr, completePtr]) => {
+			for (const p of [
+				sparsePtr,
+				barePtr,
+				completePtr
+			]) mem.poke(p, "i32", 0);
+			if (!fn.EPDFObjectDiff_GetRevisionHealth(diff, which, sparsePtr, barePtr, completePtr)) throw new EngineError(EngineErrorCode.Unknown, "failed to read revision health");
+			return {
+				sparseXref: Number(mem.peek(sparsePtr, "i32")) !== 0,
+				bareReferences: Number(mem.peek(barePtr, "i32")) >>> 0,
+				referrersComplete: Number(mem.peek(completePtr, "i32")) !== 0
+			};
+		});
+	}
+	/**
+	* 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.
+	*/
+	withAnchoredUsage(diff, changes, before, after) {
+		const changed = new Set(changes.map((c) => c.objectNumber));
+		const resolvers = {
+			old: new EdgeResolver((n) => this.readReferrers(diff, DIFF_OLD, n), anchorSet(before, changed)),
+			new: new EdgeResolver((n) => this.readReferrers(diff, DIFF_NEW, n), anchorSet(after, changed))
+		};
+		return changes.map((c) => {
+			const old = c.present.old ? resolvers.old.resolve(c.objectNumber) : [];
+			const now = c.present.new ? resolvers.new.resolve(c.objectNumber) : [];
+			const incomplete = old === USAGE_INCOMPLETE || now === USAGE_INCOMPLETE;
+			return {
+				...c,
+				usage: {
+					old: old === USAGE_INCOMPLETE ? [] : old,
+					new: now === USAGE_INCOMPLETE ? [] : now
+				},
+				...incomplete ? { usageIncomplete: true } : {}
+			};
+		});
+	}
+	readValue(diff, index, which) {
+		const { fn, mem } = this.runtime;
+		return withScratch(mem, 4, (truncPtr) => {
+			mem.poke(truncPtr, "i32", 0);
+			const length = fn.EPDFObjectDiff_GetValue(diff, index, which, NULL_PTR, 0, truncPtr);
+			const truncatedProbe = Number(mem.peek(truncPtr, "i32")) !== 0;
+			if (length <= 0) return {
+				text: null,
+				truncated: truncatedProbe
+			};
+			return withScratch(mem, length, (buf) => {
+				mem.poke(truncPtr, "i32", 0);
+				const written = fn.EPDFObjectDiff_GetValue(diff, index, which, buf, length, truncPtr);
+				const truncated = Number(mem.peek(truncPtr, "i32")) !== 0;
+				if (written <= 0) return {
+					text: null,
+					truncated
+				};
+				const bytes = mem.readBytes(buf, written - 1);
+				let text = "";
+				for (const b of bytes) text += String.fromCharCode(b);
+				return {
+					text,
+					truncated
+				};
+			});
+		});
+	}
+	readReferrers(diff, which, objectNumber) {
+		const { fn, mem } = this.runtime;
+		const count = fn.EPDFObjectDiff_GetReferrerCount(diff, which, objectNumber);
+		const out = [];
+		if (count <= 0) return out;
+		withScratch(mem, 4, (parentPtr) => {
+			for (let k = 0; k < count; k++) {
+				mem.poke(parentPtr, "i32", 0);
+				const length = fn.EPDFObjectDiff_GetReferrer(diff, which, objectNumber, k, parentPtr, NULL_PTR, 0);
+				const label = length <= 0 ? "" : withScratch(mem, length, (buf) => {
+					const written = fn.EPDFObjectDiff_GetReferrer(diff, which, objectNumber, k, parentPtr, buf, length);
+					if (written <= 0) return "";
+					const bytes = mem.readBytes(buf, written - 1);
+					let text = "";
+					for (const b of bytes) text += String.fromCharCode(b);
+					return text;
+				});
+				out.push({
+					parent: Number(mem.peek(parentPtr, "i32")) >>> 0,
+					label
+				});
+			}
+		});
+		return out;
+	}
+};
+//#endregion
+//#region src/features/signature/CandidateFinalizer.ts
+/**
+* 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.
+*/
+var CandidateFinalizer = class {
+	constructor(runtime, baseDocuments) {
+		this.runtime = runtime;
+		this.baseDocuments = baseDocuments;
+	}
+	finalize(input) {
+		const [r0, r1, r2, r3] = input.byteRange;
+		const size = this.runtime.fileAccess.sizeOf(input.path);
+		const isOffset = (n) => Number.isSafeInteger(n) && n >= 0;
+		if (!input.byteRange.every(isOffset) || r0 !== 0 || r1 >= r2 || r2 + r3 !== size) throw new EngineError(EngineErrorCode.InvalidArg, `byteRange [${input.byteRange.join(" ")}] does not span a ${size}-byte candidate`);
+		const hexLength = r2 - r1 - 2;
+		if (!Number.isSafeInteger(input.contentsSize) || hexLength !== 2 * input.contentsSize) throw new EngineError(EngineErrorCode.InvalidArg, `the /Contents hole holds ${hexLength} hex digits, not the ${2 * input.contentsSize} of contentsSize`);
+		if (input.cms.byteLength === 0 || input.cms[0] !== 48) throw new EngineError(EngineErrorCode.SignatureRefused, "the CMS is not a DER SEQUENCE");
+		if (input.cms.byteLength > input.contentsSize) throw new EngineError(EngineErrorCode.SignatureRefused, `the CMS (${input.cms.byteLength} bytes) does not fit the reserved ${input.contentsSize} bytes`);
+		writeContentsIntoFile(this.runtime, input.path, {
+			holeOffset: r1,
+			hexLength
+		}, input.cms);
+		const session = new DocumentSession(this.runtime);
+		const base = this.baseDocuments.acquireFileBase({
+			key: `finalize:${generateUuid()}`,
+			path: input.path,
+			password: input.password
+		});
 		try {
-			if (!this.runtime.fn.FPDF_SaveAsCopy(this.session.requireDocPtr(), writer.ptr, pdfSaveModeFlags(mode))) throw new EngineError(EngineErrorCode.DocOpenFailed, "failed to save document");
-			return { path };
+			session.openFromHandle(openLayerDocument(this.runtime, base, { kind: "fresh" }, input.password));
+			const model = acquireSignatureModel(this.runtime, session);
+			assertSealedSignature(this.runtime, session.requireDocPtr(), model, {
+				fieldObjectNumber: input.fieldObjectNumber,
+				byteRange: input.byteRange,
+				cms: input.cms
+			});
+			const reader = new SignatureReader(this.runtime, session);
+			const snapshot = reader.readSnapshot();
+			return {
+				signature: snapshot.signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === input.fieldObjectNumber),
+				protection: snapshot.protection,
+				version: reader.version()
+			};
 		} finally {
-			writer.close();
+			session.close();
 		}
 	}
-	requireLayer() {
-		if (this.session.kind !== "layer") throw new EngineError(EngineErrorCode.InvalidArg, "document session is not a layer");
-	}
 };
 //#endregion
 //#region src/features/fonts/FontRegistrar.ts
+/** `EPDF_FONT_EMBEDDING_*` codes. Restricted (3) and bitmap-only (4) are
+*  refused at registration, so they never reach a handle. */
+function permissionFromCode(code) {
+	switch (code) {
+		case 1: return "editable";
+		case 2: return "preview-and-print";
+		default: return "installable";
+	}
+}
+/** The engine's family comparison: no case, spaces, hyphens, underscores. */
+function familyKey(family) {
+	return family.toLowerCase().replace(/[\s\-_'"]/g, "");
+}
 /**
 * Thread-confined runtime font registry binding.
 *
@@ -8258,6 +10976,7 @@ var FontRegistrar = class {
 		this.runtime = runtime;
 		this.ids = ids;
 		_defineProperty(this, "fileHandles", []);
+		_defineProperty(this, "identities", /* @__PURE__ */ new Map());
 	}
 	/**
 	* Register a font from its bytes. Copies into the WASM heap, hands the
@@ -8276,6 +10995,11 @@ var FontRegistrar = class {
 			const id = fn.EPDFFont_RegisterMemFont64(familyName, weight, italic, ptr, bytes.byteLength);
 			if (id === 0) throw new EngineError(EngineErrorCode.InvalidArg, `font registration failed (unloadable or no glyphs): ${fontKey}`);
 			this.ids.set(fontKey, id);
+			this.identities.set(fontKey, this.readIdentity(id, {
+				familyName,
+				weight,
+				italic
+			}));
 		} finally {
 			mem.free(ptr);
 		}
@@ -8301,8 +11025,72 @@ var FontRegistrar = class {
 			throw new EngineError(EngineErrorCode.InvalidArg, `font registration failed (unloadable or no glyphs): ${fontKey} (${path})`);
 		}
 		this.ids.set(fontKey, id);
+		this.identities.set(fontKey, this.readIdentity(id, {
+			familyName,
+			weight,
+			italic
+		}));
 		this.fileHandles.push(access);
 	}
+	/** The identity and licence the runtime resolved for a key. Throws if unknown. */
+	describe(fontKey) {
+		const identity = this.identities.get(fontKey);
+		if (!identity) throw new EngineError(EngineErrorCode.InvalidArg, `font not registered on this thread: ${fontKey}`);
+		return identity;
+	}
+	/** {@link describe} for callers that treat an unknown key as "not a key". */
+	describeOrUndefined(fontKey) {
+		return this.identities.get(fontKey);
+	}
+	/**
+	* 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, weight, italic) {
+		const wanted = familyKey(family);
+		let best;
+		for (const [key, identity] of this.identities) {
+			if (familyKey(identity.familyName) !== wanted) continue;
+			const score = Math.abs(identity.weight - weight) + (identity.italic === italic ? 0 : 1e3);
+			if (!best || score < best.score) best = {
+				key,
+				score
+			};
+		}
+		return best?.key;
+	}
+	/** The application asserts a licence permitting editing with the font. */
+	authorizeEditing(fontKey) {
+		const id = this.requireId(fontKey);
+		if (!this.runtime.fn.EPDFFont_AuthorizeEditing(id)) throw new EngineError(EngineErrorCode.InvalidArg, `authorizeEditing failed: ${fontKey}`);
+		const previous = this.describe(fontKey);
+		const identity = this.readIdentity(id, {
+			familyName: previous.familyName,
+			weight: previous.weight,
+			italic: previous.italic ? 1 : 0
+		});
+		this.identities.set(fontKey, identity);
+		return identity;
+	}
+	readIdentity(id, given) {
+		const { fn, mem } = this.runtime;
+		const attempt = (read, fallback) => {
+			try {
+				return read();
+			} catch {
+				return fallback;
+			}
+		};
+		return {
+			familyName: attempt(() => readUtf8String(mem, (buf, cap) => fn.EPDFFont_GetFamilyName(id, buf, cap)) ?? given.familyName, given.familyName),
+			weight: attempt(() => fn.EPDFFont_GetWeight(id), given.weight || 400),
+			italic: attempt(() => fn.EPDFFont_IsItalic(id), given.italic === 1),
+			embeddingPermission: attempt(() => permissionFromCode(fn.EPDFFont_GetEmbeddingPermission(id)), "installable"),
+			editingAuthorized: attempt(() => fn.EPDFFont_IsEditingAuthorized(id), true),
+			instanced: attempt(() => fn.EPDFFont_IsInstanced(id), false)
+		};
+	}
 	/**
 	* Register host-owned startup fonts on this thread, in order, optionally
 	* adding each to the fallback chain. Order matters: it fixes both the native
@@ -8328,6 +11116,7 @@ var FontRegistrar = class {
 	clear() {
 		this.runtime.fn.EPDFFont_ClearRegisteredFonts();
 		this.ids.clear();
+		this.identities.clear();
 		for (const access of this.fileHandles) access.close();
 		this.fileHandles.length = 0;
 	}
@@ -8480,35 +11269,14 @@ function flagMasks(flags) {
 	};
 }
 //#endregion
-//#region src/features/forms/internal/wideStringArray.ts
-/**
-* Marshal a `const FPDF_WIDESTRING*` array: encode every string into the
-* runtime heap, write the pointer table with the runtime's pointer width
-* (bigint pointers cannot be poked into the wasm 32-bit heap), run |body|,
-* free everything.
-*/
-function withWideStringArray(runtime, values, body) {
-	const { mem } = runtime;
-	const stringPtrs = values.map((value) => mem.writeU16String(value));
-	const isWasm = runtime.kind === "wasm";
-	const ptrSize = isWasm ? 4 : 8;
-	try {
-		return withScratch(mem, Math.max(1, stringPtrs.length * ptrSize), (arrayPtr) => {
-			stringPtrs.forEach((ptr, i) => isWasm ? mem.poke(arrayPtr, "i32", Number(ptr), i * 4) : mem.poke(arrayPtr, "i64", ptr, i * 8));
-			return body(arrayPtr, stringPtrs.length);
-		});
-	} finally {
-		for (let i = stringPtrs.length - 1; i >= 0; i--) mem.free(stringPtrs[i]);
-	}
-}
-//#endregion
 //#region src/features/forms/FormMutator.ts
 const FAMILY_CODE = {
 	checkbox: 2,
 	radio: 3,
 	text: 4,
 	combobox: 5,
-	listbox: 6
+	listbox: 6,
+	signature: 7
 };
 /** Widgets a single value write can touch; far above any real form. */
 const CHANGED_WIDGETS_CAPACITY$1 = 256;
@@ -8541,7 +11309,7 @@ var FormMutator = class {
 		throwIfAborted(signal);
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, this.session.requireDocPtr());
 		if (!FAMILY_BY_VALUE_TYPE[value.type].includes(before.family)) throw new EngineError(EngineErrorCode.InvalidArg, `value type '${value.type}' does not apply to a '${before.family}' field`);
 		const changed = this.applyWrite(resolved.fieldObjectNumber, value);
@@ -8551,7 +11319,7 @@ var FormMutator = class {
 		throwIfAborted(signal);
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		const changed = this.withChangedWidgets((buf, cap, countPtr) => this.runtime.fn.EPDFForm_ResetField(this.session.requireDocPtr(), resolved.fieldObjectNumber, buf, cap, countPtr));
 		if (changed === null) throw new EngineError(EngineErrorCode.InvalidArg, "form field cannot be reset");
 		return this.readBack(resolved.fieldObjectNumber, changed);
@@ -8644,13 +11412,39 @@ var FormMutator = class {
 		this.session.noteMutation();
 		return { field: this.readBackField(fieldObjectNumber) };
 	}
+	/**
+	* 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, pdf, pageIndex, signal) {
+		throwIfAborted(signal);
+		const docPtr = this.session.requireDocPtr();
+		const model = acquireFormModel(this.runtime, this.session);
+		const resolved = resolveFieldRef(this.runtime, model, ref);
+		this.assertWritable(resolved);
+		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, docPtr);
+		if (before.family !== "signature") throw new EngineError(EngineErrorCode.InvalidArg, `'${before.name}' is a ${before.family} field, not a signature field`);
+		if (withSignatureModel(this.runtime, docPtr, (signatures) => readSignaturesFromModel(this.runtime, signatures).some((s) => s.signed && s.field.kind === "objectNumber" && s.field.fieldObjectNumber === resolved.fieldObjectNumber))) throw new EngineError(EngineErrorCode.InvalidArg, `'${before.name}' is signed; its appearance is sealed with the signature`);
+		if (before.widgets.length === 0) throw new EngineError(EngineErrorCode.InvalidArg, `'${before.name}' has no widget to draw into`);
+		for (const widget of before.widgets) bakeWidgetAppearance(this.runtime, docPtr, widget, pdf, pageIndex);
+		this.session.noteMutation();
+		const pages = [...new Set(before.widgets.map((w) => w.pageObjectNumber))];
+		for (const pon of pages) this.session.bumpRevision(pon);
+		return {
+			field: this.readBackField(resolved.fieldObjectNumber),
+			pages
+		};
+	}
 	updateField(ref, patch, signal) {
 		throwIfAborted(signal);
 		const { fn } = this.runtime;
 		const docPtr = this.session.requireDocPtr();
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, this.session.requireDocPtr());
 		if (before.family !== patch.family) throw new EngineError(EngineErrorCode.InvalidArg, `patch family '${patch.family}' does not match field family '${before.family}'`);
 		const fieldObjectNumber = resolved.fieldObjectNumber;
@@ -8681,7 +11475,7 @@ var FormMutator = class {
 		const { fn, mem } = this.runtime;
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, this.session.requireDocPtr());
 		if (!withScratchN(mem, [256 * 4, 4], ([buf, countPtr]) => {
 			mem.poke(countPtr, "i32", 0);
@@ -8701,7 +11495,7 @@ var FormMutator = class {
 		const { fn } = this.runtime;
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, this.session.requireDocPtr());
 		const toggle = before.family === "checkbox" || before.family === "radio";
 		const state = toggle ? onState ?? (before.family === "checkbox" ? "Yes" : "") : "";
@@ -8715,7 +11509,7 @@ var FormMutator = class {
 		const { fn } = this.runtime;
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
-		this.assertWritable(resolved.fieldObjectNumber);
+		this.assertWritable(resolved);
 		if (!fn.EPDFForm_DetachWidget(this.session.requireDocPtr(), resolved.fieldObjectNumber, widget.annotObjectNumber)) throw new EngineError(EngineErrorCode.InvalidArg, "widget is not attached to this field");
 		this.session.noteMutation();
 		return { field: this.readBackField(resolved.fieldObjectNumber) };
@@ -8750,8 +11544,30 @@ var FormMutator = class {
 		if (fieldIndex < 0) throw new EngineError(EngineErrorCode.Unknown, "form field vanished after write");
 		return readFieldAt(this.runtime, fresh, fieldIndex, this.session.requireDocPtr());
 	}
-	assertWritable(fieldObjectNumber) {
-		if (fieldObjectNumber === 0) throw new EngineError(EngineErrorCode.InvalidArg, "form field is stored as a direct object and cannot be written");
+	assertWritable(resolved) {
+		if (resolved.fieldObjectNumber === 0) throw new EngineError(EngineErrorCode.InvalidArg, "form field is stored as a direct object and cannot be written");
+		this.assertNotLockedBySignature(resolved);
+	}
+	/**
+	* 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.
+	*/
+	assertNotLockedBySignature(resolved) {
+		if (this.session.signedDocumentPolicy !== "protect") return;
+		let protection;
+		try {
+			protection = new SignatureReader(this.runtime, this.session).readProtection();
+		} catch {
+			return;
+		}
+		if (protection.fieldLocks.length === 0) return;
+		const model = acquireFormModel(this.runtime, this.session);
+		const name = readUtf16String(this.runtime.mem, (buf, cap) => this.runtime.fn.EPDFForm_GetFieldName(model, resolved.fieldIndex, buf, cap)) ?? "";
+		const lock = fieldLockFor(protection, name);
+		if (lock) throw new EngineError(EngineErrorCode.ProtectedDocument, `form field "${name}" is locked by signature ${lock.signatureIndex} (${lock.source === "fieldmdp" ? "FieldMDP" : "/Lock"})`);
 	}
 	/** Dispatch the typed native write. Returns the changed widget objnums. */
 	applyWrite(fieldObjectNumber, value) {
@@ -9598,6 +12414,7 @@ var WorkerHost = class {
 		this.aborts.set(msg.jobId, ctrl);
 		let resultPack;
 		try {
+			this.assertNoPendingSigning(msg);
 			switch (msg.kind) {
 				case "open.fatMem":
 				case "open.layerMemBase":
@@ -9637,6 +12454,36 @@ var WorkerHost = class {
 				case "annotations.move":
 					resultPack = this.handleAnnotationsMove(msg, ctrl.signal);
 					break;
+				case "signatures.list":
+					resultPack = this.handleSignaturesList(msg);
+					break;
+				case "signatures.contents":
+					resultPack = this.handleSignaturesContents(msg);
+					break;
+				case "signatures.digest":
+					resultPack = this.handleSignaturesDigest(msg);
+					break;
+				case "signatures.revisionBytes":
+					resultPack = this.handleSignaturesRevisionBytes(msg);
+					break;
+				case "document.version":
+					resultPack = this.handleDocumentVersion(msg);
+					break;
+				case "signatures.prepare":
+					resultPack = this.handleSignaturesPrepare(msg);
+					break;
+				case "signatures.complete":
+					resultPack = this.handleSignaturesComplete(msg);
+					break;
+				case "signatures.abort":
+					resultPack = this.handleSignaturesAbort(msg);
+					break;
+				case "signatures.analyze":
+					resultPack = this.handleSignaturesAnalyze(msg);
+					break;
+				case "signatures.finalizeCandidate":
+					resultPack = this.handleSignaturesFinalizeCandidate(msg);
+					break;
 				case "forms.list":
 					resultPack = this.handleFormsList(msg, ctrl.signal);
 					break;
@@ -9664,6 +12511,9 @@ var WorkerHost = class {
 				case "forms.updateField":
 					resultPack = this.handleFormsUpdateField(msg, ctrl.signal);
 					break;
+				case "forms.setSignatureAppearance":
+					resultPack = this.handleFormsSetSignatureAppearance(msg, ctrl.signal);
+					break;
 				case "forms.deleteField":
 					resultPack = this.handleFormsDeleteField(msg, ctrl.signal);
 					break;
@@ -9685,6 +12535,18 @@ var WorkerHost = class {
 				case "pages.delete":
 					resultPack = this.handlePagesDelete(msg, ctrl.signal);
 					break;
+				case "pages.setName":
+					resultPack = this.handlePagesSetName(msg, ctrl.signal);
+					break;
+				case "annotations.flatten":
+					resultPack = this.handleAnnotationsFlatten(msg, ctrl.signal);
+					break;
+				case "annotations.exportAppearance":
+					resultPack = this.handleAnnotationsExportAppearance(msg, ctrl.signal);
+					break;
+				case "pages.removeName":
+					resultPack = this.handlePagesRemoveName(msg, ctrl.signal);
+					break;
 				case "pages.flatten":
 					resultPack = this.handlePagesFlatten(msg, ctrl.signal);
 					break;
@@ -9769,6 +12631,12 @@ var WorkerHost = class {
 				case "fonts.clear":
 					resultPack = this.handleFontsClear(msg);
 					break;
+				case "fonts.authorizeEditing":
+					resultPack = this.handleFontsAuthorizeEditing(msg);
+					break;
+				case "document.setFontSettings":
+					resultPack = this.handleDocumentSetFontSettings(msg);
+					break;
 				case "layer.close":
 					resultPack = this.handleLayerClose(msg);
 					break;
@@ -9800,10 +12668,13 @@ var WorkerHost = class {
 		const key = sessionKey(req.docId, req.kind === "open.fatMem" ? void 0 : req.layerName);
 		if (this.sessions.has(key)) throw new EngineError(EngineErrorCode.InvalidArg, `document session already open: ${key}`);
 		const session = new DocumentSession(this.runtime);
+		session.signedDocumentPolicy = req.signedDocumentPolicy ?? "protect";
+		session.password = req.password;
 		if (req.kind === "open.fatMem") {
+			session.sessionKind = req.sessionKind ?? "layer";
 			const bytes = new Uint8Array(req.bytes);
 			try {
-				session.openFromHandle(openFatMemoryDocument(this.runtime, bytes, req.password));
+				this.openSignedAware(session, bytes, req.password);
 			} catch (error) {
 				if (!isPasswordOpenError(error)) throw error;
 				session.parkLocked(bytes);
@@ -9818,14 +12689,16 @@ var WorkerHost = class {
 			const base = this.baseDocuments.acquireMemoryBase({
 				key: req.baseKey,
 				bytes: new Uint8Array(req.baseBytes),
-				password: req.password
+				password: req.password,
+				knownSha256: req.baseSha256
 			});
 			session.openFromHandle(openLayerDocument(this.runtime, base, req.layer, req.password));
 		} else {
 			const base = this.baseDocuments.acquireFileBase({
 				key: req.baseKey,
 				path: req.basePath,
-				password: req.password
+				password: req.password,
+				knownSha256: req.baseSha256
 			});
 			session.openFromHandle(openLayerDocument(this.runtime, base, req.layer, req.password));
 		}
@@ -9833,9 +12706,160 @@ var WorkerHost = class {
 		return wirePack({
 			tag: "open",
 			docId: req.docId,
-			security: new SecurityReader(this.runtime).checkPasswordPermissions(session, req.password ?? "")
+			security: new SecurityReader(this.runtime).checkPasswordPermissions(session, req.password ?? ""),
+			protection: this.probeProtection(session)
+		});
+	}
+	/**
+	* 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.
+	*/
+	openSignedAware(session, bytes, password) {
+		if (session.sessionKind === "plain") {
+			const plain = openFatMemoryDocument(this.runtime, bytes, password);
+			let signed = false;
+			try {
+				signed = hasSignedSignature(this.runtime, plain.docPtr);
+			} catch {
+				signed = false;
+			}
+			if (!signed) {
+				session.openFromHandle(plain);
+				return;
+			}
+			plain.close();
+		}
+		const base = this.baseDocuments.acquireMemoryBase({
+			key: `signed-open:${generateUuid()}`,
+			bytes,
+			password
+		});
+		session.openFromHandle(openLayerDocument(this.runtime, base, { kind: "fresh" }, password));
+		session.persistLayerArtifact = false;
+	}
+	/**
+	* 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.
+	*/
+	probeProtection(session) {
+		try {
+			return new SignatureReader(this.runtime, session).readProtection();
+		} catch {
+			return null;
+		}
+	}
+	handleSignaturesList(req) {
+		const session = this.requireSession(req);
+		return wirePack({
+			tag: "signatures.list",
+			snapshot: req.workingCopy ? new SignatureAnalyzer(this.runtime, session).readWorkingCopySnapshot() : new SignatureReader(this.runtime, session).readSnapshot()
+		});
+	}
+	handleSignaturesContents(req) {
+		const session = this.requireSession(req);
+		const bytes = new SignatureReader(this.runtime, session).readContents(req.ref);
+		return wirePack({
+			tag: "signatures.contents",
+			bytes
+		}, [bytes]);
+	}
+	handleSignaturesDigest(req) {
+		const session = this.requireSession(req);
+		const digest = new SignatureReader(this.runtime, session).digest(req.ref, req.algorithm);
+		return wirePack({
+			tag: "signatures.digest",
+			digest
+		}, [digest]);
+	}
+	handleSignaturesRevisionBytes(req) {
+		const session = this.requireSession(req);
+		const bytes = new SignatureReader(this.runtime, session).revisionBytes(req.revisionIndex);
+		return wirePack({
+			tag: "signatures.revisionBytes",
+			bytes,
+			size: bytes.byteLength
+		}, [bytes]);
+	}
+	handleDocumentVersion(req) {
+		const session = this.requireSession(req);
+		return wirePack({
+			tag: "document.version",
+			version: new SignatureReader(this.runtime, session).version()
+		});
+	}
+	handleSignaturesPrepare(req) {
+		const session = this.requireSession(req);
+		return wirePack({
+			tag: "signatures.prepare",
+			result: new SignatureMutator(this.runtime, session, this.baseDocuments, this.options.signingCandidatePath).prepare(req.input)
+		});
+	}
+	handleSignaturesComplete(req) {
+		const session = this.requireSession(req);
+		const result = new SignatureMutator(this.runtime, session, this.baseDocuments, this.options.signingCandidatePath).complete(req.input);
+		if (result.status === "already-completed") return wirePack({
+			tag: "signatures.complete",
+			result
+		});
+		return this.finishMutation(session, {
+			tag: "signatures.complete",
+			result
+		}, req.artifactPath);
+	}
+	handleSignaturesAnalyze(req) {
+		const session = this.requireSession(req);
+		return wirePack({
+			tag: "signatures.analyze",
+			analysis: new SignatureAnalyzer(this.runtime, session).analyze(req.input)
+		});
+	}
+	/**
+	* 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`.
+	*/
+	handleSignaturesFinalizeCandidate(req) {
+		return wirePack({
+			tag: "signatures.finalizeCandidate",
+			...new CandidateFinalizer(this.runtime, this.baseDocuments).finalize({
+				path: req.path,
+				byteRange: req.byteRange,
+				contentsSize: req.contentsSize,
+				fieldObjectNumber: req.fieldObjectNumber,
+				cms: new Uint8Array(req.cms),
+				password: req.password ?? null
+			})
 		});
 	}
+	handleSignaturesAbort(req) {
+		const session = this.requireSession(req);
+		return wirePack({
+			tag: "signatures.abort",
+			result: new SignatureMutator(this.runtime, session, this.baseDocuments, this.options.signingCandidatePath).abort(req.signingId)
+		});
+	}
+	/**
+	* 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`.
+	*/
+	assertNoPendingSigning(msg) {
+		if (!MUTATING_KINDS.has(msg.kind) || !("docId" in msg)) return;
+		const layerName = "layerName" in msg ? msg.layerName : void 0;
+		const session = this.sessions.get(sessionKey(msg.docId, layerName));
+		if (session?.pendingSigning) throw new EngineError(EngineErrorCode.SigningPending, `a signing is pending (${session.pendingSigning.prepared.signingId}); complete or abort it before mutating the document`);
+	}
 	handleMetadataRead(req, signal) {
 		const session = this.requireSession(req);
 		return wirePack({
@@ -9862,21 +12886,21 @@ var WorkerHost = class {
 		const session = this.requireSession(req);
 		return wirePack({
 			tag: "annotations.listRawAll",
-			snapshot: new RawAnnotationReader(this.runtime, session).listAll(signal)
+			snapshot: new RawAnnotationReader(this.runtime, session, this.fonts).listAll(signal)
 		});
 	}
 	handleAnnotationsListRawPage(req, signal) {
 		const session = this.requireSession(req);
 		return wirePack({
 			tag: "annotations.listRawPage",
-			snapshot: new RawAnnotationReader(this.runtime, session).listOne(req.pageObjectNumber, signal)
+			snapshot: new RawAnnotationReader(this.runtime, session, this.fonts).listOne(req.pageObjectNumber, signal)
 		});
 	}
 	handleAnnotationsListFullPage(req, signal) {
 		const session = this.requireSession(req);
 		return wirePack({
 			tag: "annotations.listFullPage",
-			snapshot: new AnnotationReader(this.runtime, session).list(req.pageObjectNumber, signal)
+			snapshot: new AnnotationReader(this.runtime, session, this.fonts).list(req.pageObjectNumber, signal)
 		});
 	}
 	handleAnnotationsRenderAppearances(req, signal) {
@@ -9912,6 +12936,27 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handleAnnotationsFlatten(req, signal) {
+		const session = this.requireSession(req);
+		const result = new AnnotationFlattener(this.runtime, session).flatten(req.pageObjectNumber, req.refs, req.usage, signal);
+		if (result.meta === null) return wirePack({
+			tag: "annotations.flatten",
+			result
+		});
+		return this.finishMutation(session, {
+			tag: "annotations.flatten",
+			result
+		}, req.artifactPath);
+	}
+	handleAnnotationsExportAppearance(req, signal) {
+		const session = this.requireSession(req);
+		const exported = new AnnotationFlattener(this.runtime, session).exportAppearance(req.pageObjectNumber, req.refs, signal);
+		return wirePack({
+			tag: "annotations.exportAppearance",
+			bytes: exported.bytes,
+			size: exported.size
+		}, [exported.bytes]);
+	}
 	handleAnnotationsMove(req, signal) {
 		const session = this.requireSession(req);
 		const result = new AnnotationMutator(this.runtime, session).move(req.pageObjectNumber, req.refs, req.toIndex, signal);
@@ -9951,6 +12996,26 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handlePagesSetName(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesMutator(this.runtime, session).setName({
+			name: req.name,
+			pageObjectNumber: req.pageObjectNumber,
+			...req.replace !== void 0 ? { replace: req.replace } : {}
+		}, signal);
+		return this.finishMutation(session, {
+			tag: "pages.setName",
+			result
+		}, req.artifactPath);
+	}
+	handlePagesRemoveName(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesMutator(this.runtime, session).removeName({ name: req.name }, signal);
+		return this.finishMutation(session, {
+			tag: "pages.removeName",
+			result
+		}, req.artifactPath);
+	}
 	handlePagesFlatten(req, signal) {
 		const session = this.requireSession(req);
 		const result = new PagesFlattener(this.runtime, session).flatten(req.pageObjectNumbers, req.usage, signal);
@@ -10196,6 +13261,14 @@ var WorkerHost = class {
 	}
 	handleDocumentSaveBuffer(req) {
 		const session = this.requireSession(req);
+		if (req.mode === "incremental") {
+			const snap = new DocumentSaver(this.runtime, session).snapshot();
+			return wirePack({
+				tag: "document.saveBuffer",
+				bytes: snap.bytes,
+				size: snap.bytes.byteLength
+			}, [snap.bytes]);
+		}
 		const saved = new DocumentSaver(this.runtime, session).saveStandaloneToBuffer(req.mode);
 		return wirePack({
 			tag: "document.saveBuffer",
@@ -10205,6 +13278,17 @@ var WorkerHost = class {
 	}
 	handleDocumentSaveFile(req) {
 		const session = this.requireSession(req);
+		if (req.mode === "incremental" && (!session.hasUnsavedEdits() || new DocumentSaver(this.runtime, session).saveStandaloneToFileEx(req.path, req.mode).unchangedSinceLoad)) {
+			new DocumentSaver(this.runtime, session).copyLoadedBytesToFile(req.path);
+			return wirePack({
+				tag: "document.saveFile",
+				path: req.path
+			});
+		}
+		if (req.mode === "incremental") return wirePack({
+			tag: "document.saveFile",
+			path: req.path
+		});
 		return wirePack({
 			tag: "document.saveFile",
 			path: new DocumentSaver(this.runtime, session).saveStandaloneToFile(req.path, req.mode).path
@@ -10261,21 +13345,47 @@ var WorkerHost = class {
 		const parked = this.sessions.get(sessionKey(req.docId));
 		let session;
 		if (parked?.isLocked()) {
-			parked.openFromHandle(openFatMemoryDocument(this.runtime, parked.lockedBytes(), req.password));
+			this.openSignedAware(parked, parked.lockedBytes(), req.password);
+			parked.password = req.password;
 			session = parked;
 		} else session = this.requireSession(req);
 		return wirePack({
 			tag: "document.checkPasswordPermissions",
-			security: new SecurityReader(this.runtime).checkPasswordPermissions(session, req.password, req.mode ?? "any")
+			security: new SecurityReader(this.runtime).checkPasswordPermissions(session, req.password, req.mode ?? "any"),
+			protection: this.probeProtection(session)
 		});
 	}
 	handleFontsRegister(req) {
 		this.fonts.register(req.fontKey, req.familyName, req.weight, req.italic, new Uint8Array(req.data));
 		return wirePack({
 			tag: "fonts.register",
-			fontKey: req.fontKey
+			fontKey: req.fontKey,
+			identity: this.fonts.describe(req.fontKey)
+		});
+	}
+	handleFontsAuthorizeEditing(req) {
+		return wirePack({
+			tag: "fonts.authorizeEditing",
+			identity: this.fonts.authorizeEditing(req.fontKey)
 		});
 	}
+	/** Per-document font and text-layout settings (session state). */
+	handleDocumentSetFontSettings(req) {
+		const docPtr = this.requireSession(req).requireDocPtr();
+		const { fn } = this.runtime;
+		if (req.embeddingPolicy !== void 0) {
+			const code = {
+				default: 0,
+				subset: 1,
+				full: 2
+			}[req.embeddingPolicy];
+			if (!fn.EPDFDoc_SetFontEmbeddingPolicy(docPtr, code)) throw new EngineError(EngineErrorCode.InvalidArg, "EPDFDoc_SetFontEmbeddingPolicy failed");
+		}
+		if (req.typographicFeatures !== void 0) {
+			if (!fn.EPDFDoc_SetTypographicFeatures(docPtr, req.typographicFeatures)) throw new EngineError(EngineErrorCode.InvalidArg, "EPDFDoc_SetTypographicFeatures failed");
+		}
+		return wirePack({ tag: "document.setFontSettings" });
+	}
 	handleFontsAddFallback(req) {
 		this.fonts.addFallback(req.fontKey);
 		return wirePack({ tag: "fonts.addFallback" });
@@ -10301,6 +13411,7 @@ var WorkerHost = class {
 		const session = this.sessions.get(key);
 		if (session) {
 			disposeFormModel(this.runtime, session);
+			disposeSignatureModel(this.runtime, session);
 			session.close();
 			this.sessions.delete(key);
 		}
@@ -10310,6 +13421,7 @@ var WorkerHost = class {
 		for (const [key, session] of Array.from(this.sessions.entries())) {
 			if (!sessionKeyBelongsToDoc(key, req.docId)) continue;
 			disposeFormModel(this.runtime, session);
+			disposeSignatureModel(this.runtime, session);
 			session.close();
 			this.sessions.delete(key);
 		}
@@ -10320,6 +13432,7 @@ var WorkerHost = class {
 			this.destroyed = true;
 			for (const session of this.sessions.values()) {
 				disposeFormModel(this.runtime, session);
+				disposeSignatureModel(this.runtime, session);
 				session.close();
 			}
 			this.sessions.clear();
@@ -10425,6 +13538,21 @@ var WorkerHost = class {
 			}
 		}, req.artifactPath);
 	}
+	handleFormsSetSignatureAppearance(req, signal) {
+		const session = this.requireSession(req);
+		const { field, pages } = new FormMutator(this.runtime, session).setSignatureAppearance(req.ref, new Uint8Array(req.pdf), req.pageIndex, signal);
+		const meta = {
+			affectedPages: pages.map((pon) => session.pageState(pon)),
+			cacheDelta: null
+		};
+		return this.finishMutation(session, {
+			tag: "forms.setSignatureAppearance",
+			result: {
+				field,
+				meta
+			}
+		}, req.artifactPath);
+	}
 	handleFormsDeleteField(req, signal) {
 		const session = this.requireSession(req);
 		const { deletedFieldObjectNumber, detachedWidgets } = new FormMutator(this.runtime, session).deleteField(req.ref, signal);
@@ -10470,8 +13598,8 @@ var WorkerHost = class {
 		}, req.artifactPath);
 	}
 	finishMutation(session, payload, artifactPath) {
-		if (!payload.tag.startsWith("forms.") && payload.tag !== "pages.flatten" && payload.tag !== "redaction.apply") session.noteMutation();
-		if (session.kind !== "layer") return wirePack(payload);
+		if (!payload.tag.startsWith("forms.") && payload.tag !== "pages.flatten" && payload.tag !== "redaction.apply" && payload.tag !== "signatures.complete") session.noteMutation();
+		if (session.kind !== "layer" || !session.persistLayerArtifact) return wirePack(payload);
 		const saved = this.saveLayerArtifact(session, artifactPath);
 		return wirePack({
 			...payload,
@@ -10497,6 +13625,39 @@ const EMPTY_FORM_META = {
 	cacheDelta: null
 };
 const BASE_SESSION_SUFFIX = "__base__";
+/** Every request kind that writes to a session's document. */
+const MUTATING_KINDS = /* @__PURE__ */ new Set([
+	"metadata.update",
+	"annotations.create",
+	"annotations.update",
+	"annotations.delete",
+	"annotations.move",
+	"annotations.flatten",
+	"forms.setValue",
+	"forms.reset",
+	"forms.applyEffects",
+	"forms.import",
+	"forms.repair",
+	"forms.createField",
+	"forms.updateField",
+	"forms.setSignatureAppearance",
+	"forms.deleteField",
+	"forms.attachWidget",
+	"forms.detachWidget",
+	"pages.move",
+	"pages.rotate",
+	"pages.delete",
+	"pages.setName",
+	"pages.removeName",
+	"pages.flatten",
+	"pages.insert",
+	"pages.insertBlank",
+	"redaction.apply",
+	"attachments.create",
+	"attachments.delete",
+	"pieceInfo.update",
+	"pieceInfo.clear"
+]);
 function sessionKey(docId, layerName) {
 	return `${docId}::${layerName ? `layer:${layerName}` : BASE_SESSION_SUFFIX}`;
 }
@@ -10525,6 +13686,6 @@ function passwordRequiredProbe() {
 	};
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, LocalRevisionAuthority, MetadataMutator, MetadataReader, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, SearchReader, SecurityReader, SessionEventPublisher, WorkerHost, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+export { ALL_STANDARD_SECURITY_PERMISSIONS, 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, LocalRevisionAuthority, MetadataMutator, MetadataReader, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, SearchReader, SecurityReader, SessionEventPublisher, SignatureAnalyzer, SignatureMutator, SignatureReader, WorkerHost, acquireSignatureModel, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, disposeSignatureModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, hasSignedSignature, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, readRevisions, readSignaturesFromModel, readStructure, throwIfAborted, writeAttachmentFilePayload };
 
 //# sourceMappingURL=index.js.map