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

package/dist/index.cjs

@@ -271,8 +271,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(_embedpdf_engine_runtime.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(_embedpdf_engine_runtime.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", []);
@@ -307,7 +407,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordRequired, "document requires a password");
+			if (fn.FPDF_GetLastError() === FPDF_ERR_PASSWORD$2) throw password ? new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordRequired, "document requires a password");
 			throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed, "failed to open document");
 		}
 		setRuntimeOwnerPermissionsIfEncrypted(runtime, docPtr);
@@ -315,6 +415,11 @@ function openFatMemoryDocument(runtime, bytes, password = null) {
 		return {
 			kind: "fat-memory",
 			docPtr,
+			source: {
+				base: null,
+				layer: null,
+				password
+			},
 			close: () => stack.close()
 		};
 	} catch (error) {
@@ -332,6 +437,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, _embedpdf_engine_runtime.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());
@@ -341,9 +447,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) {
@@ -496,22 +615,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());
@@ -519,6 +629,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();
@@ -529,6 +692,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, "document is not open");
+		return this._source;
+	}
 	isOpen() {
 		return this.docPtr !== null;
 	}
@@ -543,9 +715,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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
@@ -705,6 +944,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) {
@@ -713,7 +957,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();
@@ -739,6 +986,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordIncorrect, "incorrect document password") : new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordRequired, "document requires a password");
+	return new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed, "failed to open base document");
+}
 var BaseDocumentRegistry = class {
 	constructor(runtime) {
 		this.runtime = runtime;
@@ -754,10 +1012,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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;
@@ -773,15 +1038,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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();
@@ -803,20 +1103,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;
@@ -832,90 +1128,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(_embedpdf_engine_runtime.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(_embedpdf_engine_runtime.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
@@ -1732,7 +1944,8 @@ var PagesReader = class {
 			});
 			return {
 				pageCount: pages.length,
-				pages
+				pages,
+				namedPages: readNamedPages(fn, mem, docPtr)
 			};
 		});
 	}
@@ -1797,6 +2010,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
 /**
@@ -1944,19 +2192,51 @@ var PagesMutator = class {
 			cache: null
 		};
 	}
-	/** Shared input check: non-empty, no duplicate PONs. */
-	requireUniquePons(op, pageObjectNumbers) {
-		if (pageObjectNumbers.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} requires at least one page`);
-		const seen = /* @__PURE__ */ new Set();
-		for (const pon of pageObjectNumbers) {
-			if (seen.has(pon)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} requires at least one page`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const pon of pageObjectNumbers) {
+			if (seen.has(pon)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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
@@ -1995,7 +2275,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed, "failed to save extracted pages");
 			const bytes = mem.readBytes(pdfPtr, size);
@@ -2104,8 +2384,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
@@ -2547,6 +2830,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
 /**
@@ -2796,29 +3086,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. */
@@ -2840,7 +3130,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 {
@@ -2939,6 +3229,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 !== (0, _embedpdf_engine_core_runtime.richTextPlainText)(input.richText)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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
@@ -3065,17 +3555,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 ? [
@@ -3094,6 +3603,7 @@ function readFreeText(fn, mem, annotPtr, base) {
 		fontFamily,
 		fontSize,
 		textAlign,
+		richText,
 		color,
 		...fontColor !== void 0 ? { fontColor } : {},
 		interiorColor: background ?? null,
@@ -3309,45 +3819,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.
 */
@@ -3357,16 +3832,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
 /**
@@ -3422,7 +3892,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 {
@@ -3646,18 +4116,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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "failed to build form model");
-	cache$1.set(session, {
+	cache$2.set(session, {
 		seq,
 		ptr
 	});
@@ -3665,10 +4135,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
@@ -3697,7 +4167,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) {
@@ -3711,7 +4181,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;
@@ -3731,8 +4201,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;
@@ -3741,7 +4211,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);
@@ -3872,7 +4342,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] ?? ""
@@ -4213,13 +4683,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);
@@ -4255,9 +4725,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);
@@ -4272,7 +4743,8 @@ var AnnotationReader = class {
 				pageObjectNumber,
 				count,
 				getAnnotPtrAt: (i) => fn.FPDFPage_GetAnnot(pagePtr, i),
-				signal
+				signal,
+				...this.fonts ? { fonts: this.fonts } : {}
 			});
 		} finally {
 			pool.release(pageObjectNumber);
@@ -4601,9 +5073,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);
@@ -4629,7 +5102,8 @@ var RawAnnotationReader = class {
 			pageObjectNumber,
 			count,
 			getAnnotPtrAt: (i) => fn.EPDFPage_GetAnnotRaw(docPtr, record.pageIndex, i),
-			signal
+			signal,
+			...this.fonts ? { fonts: this.fonts } : {}
 		});
 	}
 };
@@ -5444,7 +5918,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, FILE_ICON_TO_NAME[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 function requireFileResource(file, ctx) {
 	const resource = ctx?.resources?.[file.resource];
@@ -5570,6 +6044,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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;
@@ -5611,6 +6099,7 @@ function applyFreeTextDraft(fn, mem, annotPtr, draft, ctx) {
 		rotation: draft.rotation,
 		unrotatedRect: draft.unrotatedRect
 	});
+	writeRichText(fn, annotPtr, draft.richText ?? { paragraphs: (0, _embedpdf_engine_core_runtime.richTextParagraphsFromPlainText)(draft.contents ?? "") }, ctx);
 }
 /**
 * Apply a free-text patch to an existing annotation. Only present fields are
@@ -5637,11 +6126,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: (0, _embedpdf_engine_core_runtime.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);
@@ -6106,12 +6614,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);
 }
@@ -6137,7 +6645,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", {
@@ -6157,15 +6666,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "stamp name preflight invariant broken");
-	if (!fn.EPDFAnnot_SetName(annotPtr, code)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, name)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
-function requireStampNameCode(name) {
-	const code = STAMP_NAME_TO_CODE[name];
-	if (code === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "stamp name must be non-empty");
 }
 function requireStampFit(fit) {
 	if (STAMP_FIT_TO_CODE[fit] === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `unknown stamp fit '${String(fit)}'; expected contain, cover, or fill`);
@@ -6353,7 +6861,7 @@ function isTextSubtype(subtype) {
 	return subtype === "text";
 }
 function setNoteIcon(fn, annotPtr, icon) {
-	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_CODE[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_NAME[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 //#endregion
 //#region src/features/annotations/internal/write/writeVertexAnnotation.ts
@@ -6691,7 +7199,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 } : {}
@@ -6707,6 +7218,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);
@@ -6729,7 +7241,7 @@ var AnnotationMutator = class {
 				if (newObjNum <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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);
@@ -6764,6 +7276,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);
@@ -6771,7 +7284,7 @@ var AnnotationMutator = class {
 			const previousBlendMode = blendModeFromCode(fn.EPDFAnnot_GetBlendMode(annotPtr));
 			const preIndex = fn.FPDFPage_GetAnnotIndex(pagePtr, annotPtr);
 			if (preIndex < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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, {
@@ -6798,7 +7311,7 @@ var AnnotationMutator = class {
 			annotPtr = resolveAnnotPtr(this.runtime, this.session, pagePtr, ref);
 			const newIndex = fn.FPDFPage_GetAnnotIndex(pagePtr, annotPtr);
 			if (newIndex < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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({
@@ -7011,7 +7524,7 @@ var AnnotationMutator = class {
 				const annotPtr = fn.FPDFPage_GetAnnot(pagePtr, newIdx);
 				if (!annotPtr) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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);
 				}
@@ -7080,6 +7593,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 _embedpdf_engine_core_runtime.EngineError(foreign >= 0 ? _embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg : _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} requires at least one ref`);
+		for (const ref of refs) if (ref.pageObjectNumber !== pageObjectNumber) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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;
@@ -8138,104 +8786,2174 @@ function layerSaveError(status) {
 	return new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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, _embedpdf_engine_runtime.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, _embedpdf_engine_runtime.NULL_PTR, 0);
+	if (length <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 !== _embedpdf_engine_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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: (0, _embedpdf_engine_core_runtime.deriveProtection)(signatures)
+		};
+	}
+	/** The protection alone, for the open probe and the form write guard. */
+	readProtection() {
+		const model = acquireSignatureModel(this.runtime, this.session);
+		return (0, _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.MalformedPdf, "revision chain is not valid");
+		const revision = snapshot.revisions[revisionIndex];
+		if (!revision) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.MalformedPdf, "the appearance PDF could not be opened");
+		stack.push(() => fn.FPDF_CloseDocument(artworkPtr));
+		if (!fn.EPDFAnnot_SetAppearanceFromPage(annotPtr, artworkPtr, pageIndex)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "the appearance page could not be drawn into the widget");
+		if (!fn.EPDFAnnot_UpdateAppearanceToRect(annotPtr, FIT_CONTAIN)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.SignatureRefused, "the signature field is already signed");
+		if (input.appearance && !field.widget) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.SignatureRefused, "this signing already completed with a different CMS");
+				return {
+					...last.result,
+					status: "already-completed"
+				};
+			}
+			throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no pending signing '${input.signingId}'`);
+		}
+		if (!sameVersion(pending.prepared.expectedVersion, input.expectedVersion)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.SigningVersionMismatch, "expectedVersion is not the version the candidate was prepared on");
+		if (input.cms.byteLength === 0 || input.cms[0] !== 48) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.SignatureRefused, "the CMS is not a DER SEQUENCE");
+		if (input.cms.byteLength > pending.prepared.contentsSize) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_runtime.NULL_PTR;
+			const ptr = mem.writeU16String(value);
+			owned.push(ptr);
+			return ptr;
+		};
+		const utf8 = (value) => {
+			if (value === null) return _embedpdf_engine_runtime.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 : _embedpdf_engine_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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: (0, _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no signature ${input.since.signatureIndex}`);
+			if (!sig.signed || sig.revisionIndex === null) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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: _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 = (0, _embedpdf_engine_core_runtime.restrictionsFor)(before, judgedSignature);
+			const levelOverride = input.exploratoryLevel;
+			const net = (0, _embedpdf_engine_core_runtime.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 ? {
+				...(0, _embedpdf_engine_core_runtime.combine)(net, steps),
+				method: "net-state+replay"
+			} : {
+				...(0, _embedpdf_engine_core_runtime.assessmentOf)(net),
+				method: "net-state"
+			};
+			return {
+				mode,
+				policyVersion: _embedpdf_engine_core_runtime.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(_embedpdf_engine_core_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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((0, _embedpdf_engine_core_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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, _embedpdf_engine_runtime.NULL_PTR, this.session.password ?? "", statusPtr);
+			if (fresh === _embedpdf_engine_runtime.NULL_PTR || Number(mem.peek(statusPtr, "i32")) !== 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 === _embedpdf_engine_runtime.NULL_PTR) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 : (0, _embedpdf_engine_core_runtime.parsePdfValue)(oldValue.text);
+						newParsed = newValue.text === null || newValue.truncated ? null : (0, _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EdgeResolver((n) => this.readReferrers(diff, DIFF_OLD, n), anchorSet(before, changed)),
+			new: new _embedpdf_engine_core_runtime.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 === _embedpdf_engine_core_runtime.USAGE_INCOMPLETE || now === _embedpdf_engine_core_runtime.USAGE_INCOMPLETE;
+			return {
+				...c,
+				usage: {
+					old: old === _embedpdf_engine_core_runtime.USAGE_INCOMPLETE ? [] : old,
+					new: now === _embedpdf_engine_core_runtime.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, _embedpdf_engine_runtime.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, _embedpdf_engine_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.SignatureRefused, "the CMS is not a DER SEQUENCE");
+		if (input.cms.byteLength > input.contentsSize) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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.
 *
@@ -8259,6 +10977,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
@@ -8277,6 +10996,11 @@ var FontRegistrar = class {
 			const id = fn.EPDFFont_RegisterMemFont64(familyName, weight, italic, ptr, bytes.byteLength);
 			if (id === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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);
 		}
@@ -8302,8 +11026,72 @@ var FontRegistrar = class {
 			throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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
@@ -8329,6 +11117,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;
 	}
@@ -8481,35 +11270,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;
@@ -8542,7 +11310,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `value type '${value.type}' does not apply to a '${before.family}' field`);
 		const changed = this.applyWrite(resolved.fieldObjectNumber, value);
@@ -8552,7 +11320,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "form field cannot be reset");
 		return this.readBack(resolved.fieldObjectNumber, changed);
@@ -8645,13 +11413,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `'${before.name}' is signed; its appearance is sealed with the signature`);
+		if (before.widgets.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `patch family '${patch.family}' does not match field family '${before.family}'`);
 		const fieldObjectNumber = resolved.fieldObjectNumber;
@@ -8682,7 +11476,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);
@@ -8702,7 +11496,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" : "") : "";
@@ -8716,7 +11510,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "widget is not attached to this field");
 		this.session.noteMutation();
 		return { field: this.readBackField(resolved.fieldObjectNumber) };
@@ -8751,8 +11545,30 @@ var FormMutator = class {
 		if (fieldIndex < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "form field vanished after write");
 		return readFieldAt(this.runtime, fresh, fieldIndex, this.session.requireDocPtr());
 	}
-	assertWritable(fieldObjectNumber) {
-		if (fieldObjectNumber === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "form field is stored as a direct object and cannot be written");
+	assertWritable(resolved) {
+		if (resolved.fieldObjectNumber === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 = (0, _embedpdf_engine_core_runtime.fieldLockFor)(protection, name);
+		if (lock) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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) {
@@ -9599,6 +12415,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":
@@ -9638,6 +12455,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;
@@ -9665,6 +12512,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;
@@ -9686,6 +12536,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;
@@ -9770,6 +12632,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;
@@ -9801,10 +12669,13 @@ var WorkerHost = class {
 		const key = sessionKey(req.docId, req.kind === "open.fatMem" ? void 0 : req.layerName);
 		if (this.sessions.has(key)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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);
@@ -9819,14 +12690,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));
 		}
@@ -9834,9 +12707,160 @@ var WorkerHost = class {
 		return (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "signatures.digest",
+			digest
+		}, [digest]);
+	}
+	handleSignaturesRevisionBytes(req) {
+		const session = this.requireSession(req);
+		const bytes = new SignatureReader(this.runtime, session).revisionBytes(req.revisionIndex);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "signatures.revisionBytes",
+			bytes,
+			size: bytes.byteLength
+		}, [bytes]);
+	}
+	handleDocumentVersion(req) {
+		const session = this.requireSession(req);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "document.version",
+			version: new SignatureReader(this.runtime, session).version()
+		});
+	}
+	handleSignaturesPrepare(req) {
+		const session = this.requireSession(req);
+		return (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "signatures.complete",
+			result
+		});
+		return this.finishMutation(session, {
+			tag: "signatures.complete",
+			result
+		}, req.artifactPath);
+	}
+	handleSignaturesAnalyze(req) {
+		const session = this.requireSession(req);
+		return (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.wirePack)({
@@ -9863,21 +12887,21 @@ var WorkerHost = class {
 		const session = this.requireSession(req);
 		return (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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) {
@@ -9913,6 +12937,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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.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);
@@ -9952,6 +12997,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);
@@ -10197,6 +13262,14 @@ var WorkerHost = class {
 	}
 	handleDocumentSaveBuffer(req) {
 		const session = this.requireSession(req);
+		if (req.mode === "incremental") {
+			const snap = new DocumentSaver(this.runtime, session).snapshot();
+			return (0, _embedpdf_engine_core_runtime.wirePack)({
+				tag: "document.saveBuffer",
+				bytes: snap.bytes,
+				size: snap.bytes.byteLength
+			}, [snap.bytes]);
+		}
 		const saved = new DocumentSaver(this.runtime, session).saveStandaloneToBuffer(req.mode);
 		return (0, _embedpdf_engine_core_runtime.wirePack)({
 			tag: "document.saveBuffer",
@@ -10206,6 +13279,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 (0, _embedpdf_engine_core_runtime.wirePack)({
+				tag: "document.saveFile",
+				path: req.path
+			});
+		}
+		if (req.mode === "incremental") return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "document.saveFile",
+			path: req.path
+		});
 		return (0, _embedpdf_engine_core_runtime.wirePack)({
 			tag: "document.saveFile",
 			path: new DocumentSaver(this.runtime, session).saveStandaloneToFile(req.path, req.mode).path
@@ -10262,21 +13346,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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.wirePack)({
 			tag: "fonts.register",
-			fontKey: req.fontKey
+			fontKey: req.fontKey,
+			identity: this.fonts.describe(req.fontKey)
+		});
+	}
+	handleFontsAuthorizeEditing(req) {
+		return (0, _embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "EPDFDoc_SetFontEmbeddingPolicy failed");
+		}
+		if (req.typographicFeatures !== void 0) {
+			if (!fn.EPDFDoc_SetTypographicFeatures(docPtr, req.typographicFeatures)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "EPDFDoc_SetTypographicFeatures failed");
+		}
+		return (0, _embedpdf_engine_core_runtime.wirePack)({ tag: "document.setFontSettings" });
+	}
 	handleFontsAddFallback(req) {
 		this.fonts.addFallback(req.fontKey);
 		return (0, _embedpdf_engine_core_runtime.wirePack)({ tag: "fonts.addFallback" });
@@ -10302,6 +13412,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);
 		}
@@ -10311,6 +13422,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);
 		}
@@ -10321,6 +13433,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();
@@ -10426,6 +13539,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);
@@ -10471,8 +13599,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 (0, _embedpdf_engine_core_runtime.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 (0, _embedpdf_engine_core_runtime.wirePack)(payload);
 		const saved = this.saveLayerArtifact(session, artifactPath);
 		return (0, _embedpdf_engine_core_runtime.wirePack)({
 			...payload,
@@ -10498,6 +13626,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}`;
 }
@@ -10529,12 +13690,15 @@ function passwordRequiredProbe() {
 exports.ALL_STANDARD_SECURITY_PERMISSIONS = ALL_STANDARD_SECURITY_PERMISSIONS;
 exports.ActionReadBudgetTracker = ActionReadBudgetTracker;
 exports.AnnotationAppearanceReader = AnnotationAppearanceReader;
+exports.AnnotationFlattener = AnnotationFlattener;
 exports.AnnotationMutator = AnnotationMutator;
 exports.AnnotationReader = AnnotationReader;
 exports.AttachmentMutator = AttachmentMutator;
 exports.AttachmentReader = AttachmentReader;
 exports.BaseDocumentRegistry = BaseDocumentRegistry;
+exports.CandidateFinalizer = CandidateFinalizer;
 exports.CloseStack = CloseStack;
+exports.DIGEST_CODE = DIGEST_CODE;
 exports.DocumentActionsReader = DocumentActionsReader;
 exports.DocumentPagesMutator = PagesMutator;
 exports.DocumentSaver = DocumentSaver;
@@ -10564,21 +13728,30 @@ exports.RedactionApplier = RedactionApplier;
 exports.SearchReader = SearchReader;
 exports.SecurityReader = SecurityReader;
 exports.SessionEventPublisher = SessionEventPublisher;
+exports.SignatureAnalyzer = SignatureAnalyzer;
+exports.SignatureMutator = SignatureMutator;
+exports.SignatureReader = SignatureReader;
 exports.WorkerHost = WorkerHost;
+exports.acquireSignatureModel = acquireSignatureModel;
 exports.buildRunsFromRawGlyphs = buildRunsFromRawGlyphs;
 exports.computeMutationImpact = computeMutationImpact;
 exports.destroyLibrary = destroyLibrary;
 exports.disposeFormModel = disposeFormModel;
+exports.disposeSignatureModel = disposeSignatureModel;
 exports.ensureInitialized = ensureInitialized;
 exports.formatPdfDate = formatPdfDate;
 exports.generateUuid = generateUuid;
 exports.hasAllStandardSecurityPermissions = hasAllStandardSecurityPermissions;
+exports.hasSignedSignature = hasSignedSignature;
 exports.normalizeU32 = normalizeU32;
 exports.openFatMemoryDocument = openFatMemoryDocument;
 exports.openLayerDocument = openLayerDocument;
 exports.pdfDateToIso = pdfDateToIso;
 exports.readActionModel = readActionModel;
 exports.readAttachmentFileInfo = readAttachmentFileInfo;
+exports.readRevisions = readRevisions;
+exports.readSignaturesFromModel = readSignaturesFromModel;
+exports.readStructure = readStructure;
 exports.throwIfAborted = throwIfAborted;
 exports.writeAttachmentFilePayload = writeAttachmentFilePayload;