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

package/dist/index.cjs

@@ -226,8 +226,10 @@ var EventHub = class {
 		};
 	}
 	publish(event) {
-		const { serverId } = event.origin;
-		if (serverId !== null) this.serverId = this.serverId === null ? serverId : Math.max(this.serverId, serverId);
+		if ("origin" in event) {
+			const { serverId } = event.origin;
+			if (serverId !== null) this.serverId = this.serverId === null ? serverId : Math.max(this.serverId, serverId);
+		}
 		for (const listener of [...this.listeners]) try {
 			listener(event);
 		} catch (err) {
@@ -1164,13 +1166,34 @@ var MetadataMutator = class {
 };
 //#endregion
 //#region src/runtime/memory/structs.ts
+/** Generated from `EPDF_CHAR_GEOMETRY`; pinned by native static_asserts. */
+const EPDF_CHAR_GEOMETRY_LAYOUT = {
+	bytes: 124,
+	offsets: {
+		looseBox: 0,
+		tightBox: 16,
+		looseQuad: 32,
+		tightQuad: 64,
+		matrix: 96,
+		flags: 120
+	},
+	flags: {
+		hasTightBox: 1,
+		hasLooseQuad: 2,
+		hasTightQuad: 4,
+		upright: 8,
+		space: 16,
+		empty: 32,
+		synthesized: 64
+	}
+};
 /** Decode an `FS_RECTF` struct that a native call wrote into `ptr`. */
-function readRectF(mem, ptr) {
+function readRectF(mem, ptr, byteOffset = 0) {
 	return {
-		left: readF32(mem, ptr, 0),
-		top: readF32(mem, ptr, 4),
-		right: readF32(mem, ptr, 8),
-		bottom: readF32(mem, ptr, 12)
+		left: readF32(mem, ptr, byteOffset),
+		top: readF32(mem, ptr, byteOffset + 4),
+		right: readF32(mem, ptr, byteOffset + 8),
+		bottom: readF32(mem, ptr, byteOffset + 12)
 	};
 }
 /** Decode an `FS_SIZEF` struct that a native call wrote into `ptr`. */
@@ -1189,11 +1212,143 @@ function readI32(mem, ptr, byteOffset = 0) {
 	return Number(mem.peek(ptr, "i32", byteOffset));
 }
 //#endregion
+//#region src/features/destinations/destinationViewCodes.ts
+/**
+* `PDFDEST_VIEW_*` fit-type codes (public/fpdf_doc.h) — the shared
+* vocabulary of `FPDFDest_GetView` (read) and `EPDFDest_CreateView`
+* (write). XYZ is listed for completeness but never goes through
+* CreateView (it has its own null-aware constructor).
+*/
+const DEST_VIEW = {
+	unknown: 0,
+	xyz: 1,
+	fit: 2,
+	fitH: 3,
+	fitV: 4,
+	fitR: 5,
+	fitB: 6,
+	fitBH: 7,
+	fitBV: 8
+};
+/** Wire destination kind → PDFDEST_VIEW code, for the non-XYZ kinds. */
+const VIEW_CODE_BY_KIND = {
+	fit: DEST_VIEW.fit,
+	fitH: DEST_VIEW.fitH,
+	fitV: DEST_VIEW.fitV,
+	fitR: DEST_VIEW.fitR,
+	fitB: DEST_VIEW.fitB,
+	fitBH: DEST_VIEW.fitBH,
+	fitBV: DEST_VIEW.fitBV
+};
+//#endregion
+//#region src/features/destinations/readDestination.ts
+const MAX_VIEW_PARAMS = 4;
+/**
+* Materialise one explicit `PdfDestination` from a live `destPtr`. PDFium
+* already resolved named destinations before handing us the pointer, so
+* only explicit arrays arrive here (the rule `PdfDestination` documents).
+*
+* Returns `null` when the destination is unreadable: no visible indirect page
+* in the document, or an unknown fit type. Coordinates stay raw PDF user
+* space — no conversion at this layer.
+*
+* Shared by the link reader, `goto` action-node payloads, and the document
+* `openDestination`; the outline/bookmark port reuses it too.
+*/
+function readDestination(fn, mem, docPtr, destPtr) {
+	const pageObjectNumber = fn.EPDFDest_GetPageObjectNumber(docPtr, destPtr);
+	if (pageObjectNumber === 0) return null;
+	const view = withScratchN(mem, [4, MAX_VIEW_PARAMS * 4], ([countPtr, paramsPtr]) => {
+		const code = fn.FPDFDest_GetView(destPtr, countPtr, paramsPtr);
+		const count = Math.min(readI32(mem, countPtr), MAX_VIEW_PARAMS);
+		const params = [];
+		for (let i = 0; i < count; i++) params.push(readF32(mem, paramsPtr, i * 4));
+		return {
+			code,
+			params
+		};
+	});
+	const at = (i) => i < view.params.length ? view.params[i] : null;
+	switch (view.code) {
+		case DEST_VIEW.xyz: return {
+			kind: "xyz",
+			pageObjectNumber,
+			...readXyzLocation(fn, mem, destPtr)
+		};
+		case DEST_VIEW.fit: return {
+			kind: "fit",
+			pageObjectNumber
+		};
+		case DEST_VIEW.fitH: return {
+			kind: "fitH",
+			pageObjectNumber,
+			top: at(0)
+		};
+		case DEST_VIEW.fitV: return {
+			kind: "fitV",
+			pageObjectNumber,
+			left: at(0)
+		};
+		case DEST_VIEW.fitR:
+			if (view.params.length < 4) return {
+				kind: "fit",
+				pageObjectNumber
+			};
+			return {
+				kind: "fitR",
+				pageObjectNumber,
+				left: view.params[0],
+				bottom: view.params[1],
+				right: view.params[2],
+				top: view.params[3]
+			};
+		case DEST_VIEW.fitB: return {
+			kind: "fitB",
+			pageObjectNumber
+		};
+		case DEST_VIEW.fitBH: return {
+			kind: "fitBH",
+			pageObjectNumber,
+			top: at(0)
+		};
+		case DEST_VIEW.fitBV: return {
+			kind: "fitBV",
+			pageObjectNumber,
+			left: at(0)
+		};
+		default: return null;
+	}
+}
+/** `/XYZ` null-aware axes via `FPDFDest_GetLocationInPage` (FPDF_BOOL is 4 bytes). */
+function readXyzLocation(fn, mem, destPtr) {
+	return withScratchN(mem, [
+		4,
+		4,
+		4,
+		4,
+		4,
+		4
+	], ([hasLeft, hasTop, hasZoom, left, top, zoom]) => {
+		if (!fn.FPDFDest_GetLocationInPage(destPtr, hasLeft, hasTop, hasZoom, left, top, zoom)) return {
+			left: null,
+			top: null,
+			zoom: null
+		};
+		return {
+			left: readI32(mem, hasLeft) ? readF32(mem, left) : null,
+			top: readI32(mem, hasTop) ? readF32(mem, top) : null,
+			zoom: readI32(mem, hasZoom) ? readF32(mem, zoom) : null
+		};
+	});
+}
+//#endregion
 //#region src/features/actions/ActionModelReader.ts
 const DEFAULT_ACTION_READ_BUDGET = {
 	maxModels: 512,
 	maxNodes: 16384,
-	maxScriptCodeUnits: 16e6
+	maxScriptCodeUnits: 16e6,
+	maxTargetEntries: 4096,
+	maxPayloadCodeUnits: 262144
 };
 const ACTION_TYPE_BY_CODE = {
 	0: "unknown",
@@ -1221,22 +1376,20 @@ const WARNING_MALFORMED_NEXT = 2;
 const WARNING_INCOMPLETE = 4;
 const INVALID_NODE_U32 = 4294967295;
 /** Decode one `EPDF_ACTION_TYPE_*` code — the shared vocabulary consumers
-*  (the link-target projection) use so the two surfaces cannot drift. */
+*  use so action-shaped surfaces cannot drift. */
 function actionTypeFromCode(code) {
 	return ACTION_TYPE_BY_CODE[code] ?? "unknown";
 }
-/** Is this `EPDFAction_GetRootNode`/`GetNextAt` result a real node id?
-*  (`EPDF_ACTION_NODE_INVALID` may surface as -1 or u32 max via cwrap.) */
-function isValidActionNodeId(raw) {
-	return raw !== -1 && raw >>> 0 !== INVALID_NODE_U32;
-}
-/** Mutable aggregate budget shared by every action model in one read job. */
+/** Mutable aggregate budget shared by every action model in one read job.
+*  Payload budgets are RESERVED before the backing buffer is allocated. */
 var ActionReadBudgetTracker = class {
 	constructor(limits = DEFAULT_ACTION_READ_BUDGET) {
 		this.limits = limits;
 		_defineProperty(this, "models", 0);
 		_defineProperty(this, "nodes", 0);
 		_defineProperty(this, "scriptCodeUnits", 0);
+		_defineProperty(this, "targetEntries", 0);
+		_defineProperty(this, "payloadCodeUnits", 0);
 	}
 	addModel(nodeCount) {
 		this.models += 1;
@@ -1247,11 +1400,23 @@ var ActionReadBudgetTracker = class {
 		this.scriptCodeUnits += script.length;
 		this.assertWithinBudget();
 	}
+	/** Charge target entries BEFORE the target array is walked. */
+	reserveTargets(count) {
+		this.targetEntries += count;
+		this.assertWithinBudget();
+	}
+	/** Charge payload text BEFORE the scratch buffer for it is allocated. */
+	reservePayloadBytes(length) {
+		this.payloadCodeUnits += length;
+		this.assertWithinBudget();
+	}
 	assertWithinBudget() {
-		if (this.models > this.limits.maxModels || this.nodes > this.limits.maxNodes || this.scriptCodeUnits > this.limits.maxScriptCodeUnits) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.MalformedPdf, "aggregate PDF action read budget exceeded", { details: {
+		if (this.models > this.limits.maxModels || this.nodes > this.limits.maxNodes || this.scriptCodeUnits > this.limits.maxScriptCodeUnits || this.targetEntries > this.limits.maxTargetEntries || this.payloadCodeUnits > this.limits.maxPayloadCodeUnits) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.MalformedPdf, "aggregate PDF action read budget exceeded", { details: {
 			models: this.models,
 			nodes: this.nodes,
 			scriptCodeUnits: this.scriptCodeUnits,
+			targetEntries: this.targetEntries,
+			payloadCodeUnits: this.payloadCodeUnits,
 			limits: this.limits
 		} });
 	}
@@ -1259,8 +1424,17 @@ var ActionReadBudgetTracker = class {
 /**
 * Convert and close one detached native action model. This is the only
 * native-model walker used by document, page, field, and annotation reads.
+*
+* `docPtr` resolves `goto` destinations (page identity + named-destination
+* lookup); every caller reads within an open document session.
+*
+* Payload rule: a node whose payload cannot be materialised (a goto without
+* a resolvable destination, a javascript node with no `/JS`, a withheld
+* target list) degrades to `{ type: 'unknown' }` with its original `/S` on
+* `subtype`, and the tree gains the `'payload-dropped'` warning — impossible
+* states stay unrepresentable while malformed documents stay readable.
 */
-function readActionModel(fn, mem, modelPtr, budget) {
+function readActionModel(fn, mem, docPtr, modelPtr, budget) {
 	if (modelPtr === _embedpdf_engine_runtime.NULL_PTR) return null;
 	try {
 		const nodeCount = fn.EPDFAction_GetNodeCount(modelPtr);
@@ -1270,13 +1444,61 @@ function readActionModel(fn, mem, modelPtr, budget) {
 		const incomplete = !fn.EPDFAction_IsComplete(modelPtr);
 		const rootId = normalizeOptionalNodeId(fn.EPDFAction_GetRootNode(modelPtr), nodeCount);
 		const visiting = /* @__PURE__ */ new Set();
+		let payloadDropped = false;
+		/** Probe the two-call length first and charge the budget BEFORE the
+		*  scratch buffer for the value is allocated. */
+		const readPayloadString = (call) => {
+			const length = call(_embedpdf_engine_runtime.NULL_PTR, 0);
+			if (length <= 0) return null;
+			budget.reservePayloadBytes(length);
+			return readUtf8String(mem, call);
+		};
+		const readOutBool = (read) => withScratchN(mem, [4], ([outPtr]) => read(outPtr) ? readI32(mem, outPtr) !== 0 : null);
+		const readTargetObjectNumber = (nodeId, index) => withScratchN(mem, [4], ([outPtr]) => {
+			if (!fn.EPDFAction_GetNodeTargetObjectNumber(modelPtr, nodeId, index, outPtr)) return null;
+			const value = readI32(mem, outPtr) >>> 0;
+			return value === 0 ? null : value;
+		});
+		const readTargets = (nodeId, count) => {
+			const targets = [];
+			for (let index = 0; index < count; index++) {
+				const name = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeTargetName(modelPtr, nodeId, index, buf, capacity));
+				if (name !== null) {
+					targets.push({
+						kind: "name",
+						name
+					});
+					continue;
+				}
+				const objectNumber = readTargetObjectNumber(nodeId, index);
+				if (objectNumber === null) return null;
+				targets.push({
+					kind: "objectNumber",
+					objectNumber
+				});
+			}
+			return targets;
+		};
+		const readResetFormState = (nodeId) => withScratchN(mem, [4, 4], ([hasFieldsPtr, excludePtr]) => {
+			if (!fn.EPDFAction_GetNodeResetForm(modelPtr, nodeId, hasFieldsPtr, excludePtr)) return null;
+			return {
+				hasFields: readI32(mem, hasFieldsPtr) !== 0,
+				exclude: readI32(mem, excludePtr) !== 0
+			};
+		});
+		const readSubmitFormState = (nodeId) => withScratchN(mem, [4, 4], ([hasFieldsPtr, flagsPtr]) => {
+			if (!fn.EPDFAction_GetNodeSubmitForm(modelPtr, nodeId, hasFieldsPtr, flagsPtr)) return null;
+			return {
+				hasFields: readI32(mem, hasFieldsPtr) !== 0,
+				flags: readI32(mem, flagsPtr) >>> 0
+			};
+		});
 		const readNode = (nodeId) => {
 			if (visiting.has(nodeId)) throw malformedActionModel("native action model contains a cycle", { nodeId });
 			visiting.add(nodeId);
 			try {
+				const type = actionTypeFromCode(fn.EPDFAction_GetNodeType(modelPtr, nodeId));
 				const subtype = readUtf8String(mem, (buf, capacity) => fn.EPDFAction_GetNodeSubtype(modelPtr, nodeId, buf, capacity)) ?? "";
-				const script = fn.EPDFAction_NodeHasJavaScript(modelPtr, nodeId) ? readUtf16String(mem, (buf, capacity) => fn.EPDFAction_GetNodeJavaScript(modelPtr, nodeId, buf, capacity)) ?? "" : void 0;
-				if (script !== void 0) budget.addScript(script);
 				const nextCount = fn.EPDFAction_GetNextCount(modelPtr, nodeId);
 				if (!Number.isInteger(nextCount) || nextCount < 0) throw malformedActionModel("invalid action child count", {
 					nodeId,
@@ -1287,21 +1509,157 @@ function readActionModel(fn, mem, modelPtr, budget) {
 					const childId = normalizeNodeId(fn.EPDFAction_GetNextAt(modelPtr, nodeId, index), nodeCount);
 					next.push(readNode(childId));
 				}
-				return {
-					type: ACTION_TYPE_BY_CODE[fn.EPDFAction_GetNodeType(modelPtr, nodeId)] ?? "unknown",
-					subtype,
-					...script !== void 0 ? { script } : {},
-					next
+				const degraded = () => {
+					payloadDropped = true;
+					return {
+						type: "unknown",
+						subtype,
+						next
+					};
 				};
+				switch (type) {
+					case "javascript": {
+						if (!fn.EPDFAction_NodeHasJavaScript(modelPtr, nodeId)) return degraded();
+						const script = readUtf16String(mem, (buf, capacity) => fn.EPDFAction_GetNodeJavaScript(modelPtr, nodeId, buf, capacity)) ?? "";
+						budget.addScript(script);
+						return {
+							type,
+							subtype,
+							script,
+							next
+						};
+					}
+					case "rendition": {
+						if (!fn.EPDFAction_NodeHasJavaScript(modelPtr, nodeId)) return {
+							type,
+							subtype,
+							next
+						};
+						const script = readUtf16String(mem, (buf, capacity) => fn.EPDFAction_GetNodeJavaScript(modelPtr, nodeId, buf, capacity)) ?? "";
+						budget.addScript(script);
+						return {
+							type,
+							subtype,
+							script,
+							next
+						};
+					}
+					case "goto": {
+						const destPtr = fn.EPDFAction_GetNodeDest(docPtr, modelPtr, nodeId);
+						const destination = destPtr !== _embedpdf_engine_runtime.NULL_PTR ? readDestination(fn, mem, docPtr, destPtr) : null;
+						return destination ? {
+							type,
+							subtype,
+							destination,
+							next
+						} : degraded();
+					}
+					case "uri": {
+						const uri = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeURI(docPtr, modelPtr, nodeId, buf, capacity));
+						if (uri === null) return degraded();
+						return {
+							type,
+							subtype,
+							uri,
+							isMap: readOutBool((outPtr) => fn.EPDFAction_GetNodeURIIsMap(modelPtr, nodeId, outPtr)) ?? false,
+							next
+						};
+					}
+					case "named": {
+						const name = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeName(modelPtr, nodeId, buf, capacity));
+						return name === null ? degraded() : {
+							type,
+							subtype,
+							name,
+							next
+						};
+					}
+					case "hide": {
+						const count = fn.EPDFAction_GetNodeTargetCount(modelPtr, nodeId);
+						if (!Number.isInteger(count) || count < 0) return degraded();
+						budget.reserveTargets(count);
+						const targets = readTargets(nodeId, count);
+						if (targets === null) return degraded();
+						return {
+							type,
+							subtype,
+							targets,
+							hide: readOutBool((outPtr) => fn.EPDFAction_GetNodeHideFlag(modelPtr, nodeId, outPtr)) ?? true,
+							next
+						};
+					}
+					case "reset-form": {
+						const state = readResetFormState(nodeId);
+						const count = fn.EPDFAction_GetNodeTargetCount(modelPtr, nodeId);
+						if (state === null || !Number.isInteger(count) || count < 0) return degraded();
+						budget.reserveTargets(count);
+						const fields = state.hasFields ? readTargets(nodeId, count) : null;
+						if (state.hasFields && fields === null) return degraded();
+						return {
+							type,
+							subtype,
+							fields,
+							exclude: state.exclude,
+							next
+						};
+					}
+					case "submit-form": {
+						if (typeof fn.EPDFAction_GetNodeSubmitForm !== "function") return {
+							type,
+							subtype,
+							next
+						};
+						const state = readSubmitFormState(nodeId);
+						if (state === null) return degraded();
+						const url = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeSubmitFormURL(modelPtr, nodeId, buf, capacity));
+						if (url === null) return degraded();
+						const count = fn.EPDFAction_GetNodeTargetCount(modelPtr, nodeId);
+						if (!Number.isInteger(count) || count < 0) return degraded();
+						budget.reserveTargets(count);
+						const fields = state.hasFields ? readTargets(nodeId, count) : null;
+						if (state.hasFields && fields === null) return degraded();
+						const charSet = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeSubmitFormCharSet(modelPtr, nodeId, buf, capacity));
+						return {
+							type,
+							subtype,
+							payload: {
+								url,
+								fields,
+								flags: (0, _embedpdf_engine_core_runtime.decodeSubmitFormFlags)(state.flags),
+								...charSet === null ? {} : { charSet }
+							},
+							next
+						};
+					}
+					case "goto-remote":
+					case "goto-embedded":
+					case "launch": {
+						const filePath = readPayloadString((buf, capacity) => fn.EPDFAction_GetNodeFilePath(modelPtr, nodeId, buf, capacity));
+						return filePath === null ? degraded() : {
+							type,
+							subtype,
+							filePath,
+							next
+						};
+					}
+					default: return {
+						type,
+						subtype,
+						next
+					};
+				}
 			} finally {
 				visiting.delete(nodeId);
 			}
 		};
+		const root = rootId === null ? null : readNode(rootId);
+		const warnings = warningsFromFlags(warningFlags, incomplete);
+		if (payloadDropped) warnings.push("payload-dropped");
 		return {
-			root: rootId === null ? null : readNode(rootId),
+			root,
 			incomplete,
 			warningFlags,
-			warnings: warningsFromFlags(warningFlags, incomplete)
+			warnings
 		};
 	} finally {
 		fn.EPDFAction_CloseModel(modelPtr);
@@ -1381,8 +1739,8 @@ var PagesReader = class {
 };
 function readPageActions(fn, mem, docPtr, pageObjectNumber, budget) {
 	const actions = {};
-	const open = readActionModel(fn, mem, fn.EPDFDoc_GetPageActionModel(docPtr, pageObjectNumber, 0), budget);
-	const close = readActionModel(fn, mem, fn.EPDFDoc_GetPageActionModel(docPtr, pageObjectNumber, 1), budget);
+	const open = readActionModel(fn, mem, docPtr, fn.EPDFDoc_GetPageActionModel(docPtr, pageObjectNumber, 0), budget);
+	const close = readActionModel(fn, mem, docPtr, fn.EPDFDoc_GetPageActionModel(docPtr, pageObjectNumber, 1), budget);
 	if (open) actions.open = open;
 	if (close) actions.close = close;
 	return open || close ? actions : void 0;
@@ -1706,6 +2064,42 @@ var PagesInserter = class {
 			cache: null
 		};
 	}
+	/**
+	* Create `count` blank pages of `size` at `destIndex`. Same mutation
+	* contract as `insert`, but native creation (`FPDFPage_New`) instead of a
+	* deep copy: no source document, so none of the retain-until-close
+	* lifetime hazard above. Each page gets an empty content stream
+	* (`FPDFPage_GenerateContent`) so the saved PDF renders identically in
+	* third-party viewers.
+	*/
+	insertBlank(spec, destIndex, signal) {
+		throwIfAborted(signal);
+		const { size } = spec;
+		const count = spec.count ?? 1;
+		if (!Number.isFinite(size?.width) || !Number.isFinite(size?.height) || size.width <= 0 || size.height <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank size must have positive finite dimensions, got ${size?.width}x${size?.height}`);
+		if (!Number.isInteger(count) || count < 1 || count > _embedpdf_engine_core_runtime.PAGE_INSERT_BLANK_MAX_COUNT) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank count ${count} out of range [1, ${_embedpdf_engine_core_runtime.PAGE_INSERT_BLANK_MAX_COUNT}]`);
+		const { fn } = this.runtime;
+		const destPtr = this.session.requireDocPtr();
+		const beforeCount = fn.FPDF_GetPageCount(destPtr);
+		const at = destIndex ?? beforeCount;
+		if (!Number.isInteger(at) || at < 0 || at > beforeCount) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank destIndex ${at} out of range [0, ${beforeCount}]`);
+		for (let i = 0; i < count; i++) {
+			const pagePtr = fn.FPDFPage_New(destPtr, at + i, size.width, size.height);
+			if (!pagePtr) {
+				for (let j = 0; j < i; j++) fn.FPDFPage_Delete(destPtr, at);
+				throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, `FPDFPage_New rejected page ${i + 1}/${count} at index ${at + i}`);
+			}
+			fn.FPDFPage_GenerateContent(pagePtr);
+			fn.FPDF_ClosePage(pagePtr);
+		}
+		this.session.refreshPageRegistry();
+		const layout = new PagesReader(this.runtime, this.session).read(signal);
+		return {
+			insertedPageObjectNumbers: layout.pages.slice(at, at + count).map((page) => page.pageObjectNumber),
+			layout,
+			cache: null
+		};
+	}
 };
 //#endregion
 //#region src/features/annotations/internal/read/annotationReadContext.ts
@@ -2154,6 +2548,49 @@ function readQuadPoints(fn, mem, annotPtr) {
 	});
 }
 //#endregion
+//#region src/features/annotations/internal/read/readAnnotationTransformMetadata.ts
+/**
+* Read-side twin of `writers/.../writeAnnotationTransformMetadata.ts`. Decodes
+* the EmbedPDF rotation keys from /EMBD_Metadata back onto the DTO:
+*
+*   - `Rotation`      — degrees, PDF convention. Returned for EVERY rotatable
+*     kind (box AND vertex); the plugin converts it back to its CW-content
+*     `rot` once at the repository seam.
+*   - `UnrotatedRect` — the logical box. BOX kinds only (square/circle/
+*     free-text); a vertex annotation never carries one (its points are the
+*     visual), so vertex readers don't ask for it.
+*
+* Both are absent on un-rotated annotations (and on everything authored before
+* rotation shipped), so both reads return `undefined` and the DTO field stays
+* unset.
+*/
+const KEY_ROTATION$1 = "Rotation";
+const KEY_UNROTATED_RECT$1 = "UnrotatedRect";
+/** The advisory/portable rotation scalar (degrees, PDF convention), or
+*  `undefined` when absent or zero. */
+function readAnnotationRotation(fn, mem, annotPtr) {
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
+	return withScratch(mem, 4, (buf) => {
+		if (!fn.EPDFAnnot_GetEmbedMetadataNumber(annotPtr, KEY_ROTATION$1, buf)) return void 0;
+		const v = readF32(mem, buf);
+		return v ? v : void 0;
+	});
+}
+/** The logical (unrotated) box of a rotated BOX annotation, or `undefined`. */
+function readAnnotationUnrotatedRect(fn, mem, annotPtr) {
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
+	return withScratch(mem, 16, (buf) => {
+		if (!fn.EPDFAnnot_GetEmbedMetadataRect(annotPtr, KEY_UNROTATED_RECT$1, buf)) return void 0;
+		const r = readRectF(mem, buf);
+		return {
+			left: r.left,
+			bottom: r.bottom,
+			right: r.right,
+			top: r.top
+		};
+	});
+}
+//#endregion
 //#region src/features/annotations/internal/textEditIntent.ts
 /** Adobe-compatible `/IT` names, normalized at the engine-core boundary. */
 const IT_REPLACE = "Replace";
@@ -2188,13 +2625,17 @@ function readCaret(fn, mem, annotPtr, base) {
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
 	const rd = readRectangleDifferences(fn, mem, annotPtr);
 	const intent = caretIntentFromName(readIntent(fn, mem, annotPtr));
+	const rotation = readAnnotationRotation(fn, mem, annotPtr);
+	const unrotatedRect = readAnnotationUnrotatedRect(fn, mem, annotPtr);
 	return {
 		...base,
 		subtype: "caret",
 		intent,
 		color,
 		opacity,
-		rectDifferences: rd
+		rectDifferences: rd,
+		...rotation != null ? { rotation } : {},
+		...unrotatedRect ? { unrotatedRect } : {}
 	};
 }
 //#endregion
@@ -2612,49 +3053,6 @@ function readFilledStyleExtras(fn, mem, annotPtr) {
 	};
 }
 //#endregion
-//#region src/features/annotations/internal/read/readAnnotationTransformMetadata.ts
-/**
-* Read-side twin of `writers/.../writeAnnotationTransformMetadata.ts`. Decodes
-* the EmbedPDF rotation keys from /EMBD_Metadata back onto the DTO:
-*
-*   - `Rotation`      — degrees, PDF convention. Returned for EVERY rotatable
-*     kind (box AND vertex); the plugin converts it back to its CW-content
-*     `rot` once at the repository seam.
-*   - `UnrotatedRect` — the logical box. BOX kinds only (square/circle/
-*     free-text); a vertex annotation never carries one (its points are the
-*     visual), so vertex readers don't ask for it.
-*
-* Both are absent on un-rotated annotations (and on everything authored before
-* rotation shipped), so both reads return `undefined` and the DTO field stays
-* unset.
-*/
-const KEY_ROTATION$1 = "Rotation";
-const KEY_UNROTATED_RECT$1 = "UnrotatedRect";
-/** The advisory/portable rotation scalar (degrees, PDF convention), or
-*  `undefined` when absent or zero. */
-function readAnnotationRotation(fn, mem, annotPtr) {
-	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
-	return withScratch(mem, 4, (buf) => {
-		if (!fn.EPDFAnnot_GetEmbedMetadataNumber(annotPtr, KEY_ROTATION$1, buf)) return void 0;
-		const v = readF32(mem, buf);
-		return v ? v : void 0;
-	});
-}
-/** The logical (unrotated) box of a rotated BOX annotation, or `undefined`. */
-function readAnnotationUnrotatedRect(fn, mem, annotPtr) {
-	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
-	return withScratch(mem, 16, (buf) => {
-		if (!fn.EPDFAnnot_GetEmbedMetadataRect(annotPtr, KEY_UNROTATED_RECT$1, buf)) return void 0;
-		const r = readRectF(mem, buf);
-		return {
-			left: r.left,
-			bottom: r.bottom,
-			right: r.right,
-			top: r.top
-		};
-	});
-}
-//#endregion
 //#region src/features/annotations/internal/read/readFreeTextAnnotation.ts
 /** Default `/DA` colour (black) when an annotation has no default appearance. */
 const DEFAULT_FREETEXT_COLOR$1 = {
@@ -2760,167 +3158,67 @@ function readLine(fn, mem, annotPtr, base) {
 	};
 }
 //#endregion
-//#region src/features/annotations/internal/destinationViewCodes.ts
-/**
-* `PDFDEST_VIEW_*` fit-type codes (public/fpdf_doc.h) — the shared
-* vocabulary of `FPDFDest_GetView` (read) and `EPDFDest_CreateView`
-* (write). XYZ is listed for completeness but never goes through
-* CreateView (it has its own null-aware constructor).
-*/
-const DEST_VIEW = {
-	unknown: 0,
-	xyz: 1,
-	fit: 2,
-	fitH: 3,
-	fitV: 4,
-	fitR: 5,
-	fitB: 6,
-	fitBH: 7,
-	fitBV: 8
-};
-/** Wire destination kind → PDFDEST_VIEW code, for the non-XYZ kinds. */
-const VIEW_CODE_BY_KIND = {
-	fit: DEST_VIEW.fit,
-	fitH: DEST_VIEW.fitH,
-	fitV: DEST_VIEW.fitV,
-	fitR: DEST_VIEW.fitR,
-	fitB: DEST_VIEW.fitB,
-	fitBH: DEST_VIEW.fitBH,
-	fitBV: DEST_VIEW.fitBV
-};
-//#endregion
-//#region src/features/annotations/internal/read/readDestination.ts
-const MAX_VIEW_PARAMS = 4;
-/**
-* Materialise one explicit `PdfDestination` from a live `destPtr`. PDFium
-* already resolved named destinations before handing us the pointer, so
-* only explicit arrays arrive here (the rule `PdfDestination` documents).
-*
-* Returns `null` when the destination is unreadable: no visible indirect page
-* in the document, or an unknown fit type. Coordinates stay raw PDF user
-* space — no conversion at this layer.
-*
-* Shared by the link reader today; the outline/bookmark port reuses it.
-*/
-function readDestination(fn, mem, docPtr, destPtr) {
-	const pageObjectNumber = fn.EPDFDest_GetPageObjectNumber(docPtr, destPtr);
-	if (pageObjectNumber === 0) return null;
-	const view = withScratchN(mem, [4, MAX_VIEW_PARAMS * 4], ([countPtr, paramsPtr]) => {
-		const code = fn.FPDFDest_GetView(destPtr, countPtr, paramsPtr);
-		const count = Math.min(readI32(mem, countPtr), MAX_VIEW_PARAMS);
-		const params = [];
-		for (let i = 0; i < count; i++) params.push(readF32(mem, paramsPtr, i * 4));
-		return {
-			code,
-			params
-		};
-	});
-	const at = (i) => i < view.params.length ? view.params[i] : null;
-	switch (view.code) {
-		case DEST_VIEW.xyz: return {
-			kind: "xyz",
-			pageObjectNumber,
-			...readXyzLocation(fn, mem, destPtr)
-		};
-		case DEST_VIEW.fit: return {
-			kind: "fit",
-			pageObjectNumber
-		};
-		case DEST_VIEW.fitH: return {
-			kind: "fitH",
-			pageObjectNumber,
-			top: at(0)
-		};
-		case DEST_VIEW.fitV: return {
-			kind: "fitV",
-			pageObjectNumber,
-			left: at(0)
-		};
-		case DEST_VIEW.fitR:
-			if (view.params.length < 4) return {
-				kind: "fit",
-				pageObjectNumber
-			};
-			return {
-				kind: "fitR",
-				pageObjectNumber,
-				left: view.params[0],
-				bottom: view.params[1],
-				right: view.params[2],
-				top: view.params[3]
-			};
-		case DEST_VIEW.fitB: return {
-			kind: "fitB",
-			pageObjectNumber
-		};
-		case DEST_VIEW.fitBH: return {
-			kind: "fitBH",
-			pageObjectNumber,
-			top: at(0)
-		};
-		case DEST_VIEW.fitBV: return {
-			kind: "fitBV",
-			pageObjectNumber,
-			left: at(0)
-		};
-		default: return null;
-	}
-}
-/** `/XYZ` null-aware axes via `FPDFDest_GetLocationInPage` (FPDF_BOOL is 4 bytes). */
-function readXyzLocation(fn, mem, destPtr) {
-	return withScratchN(mem, [
-		4,
-		4,
-		4,
-		4,
-		4,
-		4
-	], ([hasLeft, hasTop, hasZoom, left, top, zoom]) => {
-		if (!fn.FPDFDest_GetLocationInPage(destPtr, hasLeft, hasTop, hasZoom, left, top, zoom)) return {
-			left: null,
-			top: null,
-			zoom: null
-		};
-		return {
-			left: readI32(mem, hasLeft) ? readF32(mem, left) : null,
-			top: readI32(mem, hasTop) ? readF32(mem, top) : null,
-			zoom: readI32(mem, hasZoom) ? readF32(mem, zoom) : null
-		};
-	});
-}
-//#endregion
 //#region src/features/annotations/internal/read/readLinkAnnotation.ts
 /**
 * Link reader: rect/flags/relationship ride the base (a link grouped to an
 * annotation is plain `inReplyTo` + `replyType: 'group'`); this module only
 * materialises the normalized target.
 *
-* ONE truth, two views: the target is projected off the SAME fork action
-* model the scripting plane reads (`base.actions`) — root classification
-* via the full `EPDF_ACTION_TYPE_*` vocabulary, payloads via the on-demand
-* node getters. The classic `FPDFAction_*` surface (5 types, JavaScript-
-* and Named-blind) is deliberately not consulted; `FPDFLink_GetDest`
-* remains only for the data-only direct `/Dest`, which is not an action.
+* ONE truth, one projection: the target is a pure function of the SAME
+* payload-carrying action tree the scripting plane reads
+* (`base.actions.activate`) — no second native read exists any more, so the
+* two action-shaped surfaces cannot drift by construction.
 *
-* `/A` wins over `/Dest` — the spec forbids carrying both, and when a
-* malformed file has both, Acrobat gives the action precedence. (Our own
-* writes can't produce that state: `EPDFAnnot_SetAction` strips `/Dest`.)
+* `/A` precedence, pinned: an activate action that exists but cannot be
+* executed (an `incomplete` tree, a degraded/unreadable root) projects
+* `unsupported` — a broken action is a dead link, never an invitation to
+* guess. The direct `/Dest` (which is data, not an action) is consulted
+* ONLY when no `/A` exists at all.
 */
 function readLink(fn, mem, annotPtr, base, _rawSubtypeCode, ctx) {
 	return {
 		...base,
 		subtype: "link",
-		target: readLinkTarget(fn, mem, annotPtr, ctx)
+		target: readLinkTarget(fn, mem, annotPtr, base, ctx)
 	};
 }
-function readLinkTarget(fn, mem, annotPtr, ctx) {
-	const modelPtr = fn.EPDFAnnot_GetActionModel(annotPtr, 0);
-	if (modelPtr !== _embedpdf_engine_runtime.NULL_PTR) try {
-		const root = fn.EPDFAction_GetRootNode(modelPtr);
-		if (isValidActionNodeId(root)) return readRootTarget(fn, mem, modelPtr, root, ctx);
-	} finally {
-		fn.EPDFAction_CloseModel(modelPtr);
+/**
+* Project the navigation view from a payload-carrying activate tree. Pure —
+* shared with any consumer that wants the root-level navigation reading of a
+* tree (the link plugin's no-actions-plugin fallback uses the same law).
+*/
+function linkTargetFromActionTree(tree) {
+	if (tree.incomplete) return { kind: "unsupported" };
+	const root = tree.root;
+	if (!root) return { kind: "unsupported" };
+	switch (root.type) {
+		case "goto": return {
+			kind: "goto",
+			destination: root.destination
+		};
+		case "uri": return {
+			kind: "uri",
+			uri: root.uri
+		};
+		case "goto-remote": return {
+			kind: "goto-remote",
+			file: root.filePath
+		};
+		case "launch": return {
+			kind: "launch",
+			path: root.filePath
+		};
+		case "javascript": return { kind: "javascript" };
+		case "named": return {
+			kind: "named",
+			name: root.name
+		};
+		default: return { kind: "unsupported" };
 	}
+}
+function readLinkTarget(fn, mem, annotPtr, base, ctx) {
+	const activate = base.actions?.activate;
+	if (activate) return linkTargetFromActionTree(activate);
 	const linkPtr = fn.FPDFAnnot_GetLink(annotPtr);
 	if (!linkPtr) return null;
 	const destPtr = fn.FPDFLink_GetDest(ctx.docPtr, linkPtr);
@@ -2931,43 +3229,6 @@ function readLinkTarget(fn, mem, annotPtr, ctx) {
 		destination
 	} : { kind: "unsupported" };
 }
-/** Classify the root action node and fetch its payload — the projection. */
-function readRootTarget(fn, mem, modelPtr, node, ctx) {
-	switch (actionTypeFromCode(fn.EPDFAction_GetNodeType(modelPtr, node))) {
-		case "goto": {
-			const destPtr = fn.EPDFAction_GetNodeDest(ctx.docPtr, modelPtr, node);
-			const destination = destPtr ? readDestination(fn, mem, ctx.docPtr, destPtr) : null;
-			return destination ? {
-				kind: "goto",
-				destination
-			} : { kind: "unsupported" };
-		}
-		case "uri": {
-			const uri = readUtf8String(mem, (buf, capacity) => fn.EPDFAction_GetNodeURI(ctx.docPtr, modelPtr, node, buf, capacity));
-			return uri == null ? { kind: "unsupported" } : {
-				kind: "uri",
-				uri
-			};
-		}
-		case "goto-remote": return {
-			kind: "goto-remote",
-			file: readUtf8String(mem, (buf, capacity) => fn.EPDFAction_GetNodeFilePath(modelPtr, node, buf, capacity)) ?? ""
-		};
-		case "launch": return {
-			kind: "launch",
-			path: readUtf8String(mem, (buf, capacity) => fn.EPDFAction_GetNodeFilePath(modelPtr, node, buf, capacity)) ?? ""
-		};
-		case "javascript": return { kind: "javascript" };
-		case "named": {
-			const name = readUtf8String(mem, (buf, capacity) => fn.EPDFAction_GetNodeName(modelPtr, node, buf, capacity));
-			return name == null ? { kind: "unsupported" } : {
-				kind: "named",
-				name
-			};
-		}
-		default: return { kind: "unsupported" };
-	}
-}
 //#endregion
 //#region src/features/annotations/internal/read/readRedactAnnotation.ts
 /** Default `/C` marking outline (red) — the redaction marking convention and
@@ -3107,6 +3368,47 @@ function readStampName(fn, mem, annotPtr) {
 	return readAnnotString(fn, mem, annotPtr, "Name");
 }
 //#endregion
+//#region src/features/annotations/internal/annotationState.ts
+/**
+* `/State` + `/StateModel` spelling maps — ISO 32000 §12.5.6.3, Table 174.
+*
+* Known values are wire-stable lowercase (the house vocabulary — same
+* rationale as `AnnotationReplyType` / `AnnotationBorderStyle`); the PDF
+* stores the capitalized Table 174 spellings. Unknown values — custom
+* Acrobat state models and their states — pass through VERBATIM in both
+* directions, so foreign review workflows survive a round trip.
+*/
+const STATE_MODEL_TO_PDF = {
+	review: "Review",
+	marked: "Marked"
+};
+const STATE_TO_PDF = {
+	accepted: "Accepted",
+	rejected: "Rejected",
+	cancelled: "Cancelled",
+	completed: "Completed",
+	none: "None",
+	marked: "Marked",
+	unmarked: "Unmarked"
+};
+const PDF_TO_STATE_MODEL = invert(STATE_MODEL_TO_PDF);
+const PDF_TO_STATE = invert(STATE_TO_PDF);
+function stateModelToPdf(value) {
+	return STATE_MODEL_TO_PDF[value] ?? value;
+}
+function stateModelFromPdf(value) {
+	return PDF_TO_STATE_MODEL[value] ?? value;
+}
+function stateToPdf(value) {
+	return STATE_TO_PDF[value] ?? value;
+}
+function stateFromPdf(value) {
+	return PDF_TO_STATE[value] ?? value;
+}
+function invert(map) {
+	return Object.fromEntries(Object.entries(map).map(([wire, pdf]) => [pdf, wire]));
+}
+//#endregion
 //#region src/features/annotations/internal/read/readTextAnnotation.ts
 /** Default `/C` — matches the generator's yellow note fill and the writer default. */
 const DEFAULT_NOTE_COLOR$1 = {
@@ -3121,12 +3423,16 @@ function readText(fn, mem, annotPtr, base) {
 	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 stateRaw = readAnnotString(fn, mem, annotPtr, "State");
+	const stateModelRaw = readAnnotString(fn, mem, annotPtr, "StateModel");
 	return {
 		...base,
 		subtype: "text",
 		icon,
 		color,
-		opacity
+		opacity,
+		state: stateRaw === null ? null : stateFromPdf(stateRaw),
+		stateModel: stateModelRaw === null ? null : stateModelFromPdf(stateModelRaw)
 	};
 }
 //#endregion
@@ -3432,7 +3738,7 @@ function readOptions(runtime, model, fieldIndex) {
 	return options;
 }
 /** Read one field of the native model into its per-family DTO. */
-function readFieldAt(runtime, model, fieldIndex, actionBudget = new ActionReadBudgetTracker()) {
+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));
@@ -3440,7 +3746,7 @@ function readFieldAt(runtime, model, fieldIndex, actionBudget = new ActionReadBu
 	const family = FAMILY_BY_CODE[fn.EPDFForm_GetFieldFamily(model, fieldIndex)] ?? "unknown";
 	const valueEntry = readValueEntry(runtime, model, fieldIndex, false);
 	const defaultValueEntry = readValueEntry(runtime, model, fieldIndex, true);
-	const actions = readFieldActions(runtime, model, fieldIndex, actionBudget);
+	const actions = readFieldActions(runtime, model, fieldIndex, docPtr, actionBudget);
 	const base = {
 		ref: fieldObjectNumber > 0 ? {
 			kind: "objectNumber",
@@ -3539,12 +3845,12 @@ function readFieldAt(runtime, model, fieldIndex, actionBudget = new ActionReadBu
 	}
 }
 /** Read the whole native model into a detached {@link FormSnapshot}. */
-function readFormSnapshot(runtime, model) {
+function readFormSnapshot(runtime, model, docPtr) {
 	const { fn } = runtime;
 	const count = fn.EPDFForm_CountFields(model);
 	const fields = [];
 	const actionBudget = new ActionReadBudgetTracker();
-	for (let i = 0; i < count; i++) fields.push(readFieldAt(runtime, model, i, actionBudget));
+	for (let i = 0; i < count; i++) fields.push(readFieldAt(runtime, model, i, docPtr, actionBudget));
 	const calculationOrder = [];
 	const calculationCount = fn.EPDFForm_CountCalculationOrder(model);
 	for (let index = 0; index < calculationCount; index++) {
@@ -3580,7 +3886,7 @@ function entryScalar(entry) {
 	if (entry.kind === "array") return entry.values[0] ?? "";
 	return "";
 }
-function readFieldActions(runtime, model, fieldIndex, budget) {
+function readFieldActions(runtime, model, fieldIndex, docPtr, budget) {
 	const { fn, mem } = runtime;
 	const entries = [
 		["keystroke", 0],
@@ -3590,7 +3896,7 @@ function readFieldActions(runtime, model, fieldIndex, budget) {
 	];
 	const actions = {};
 	for (const [key, event] of entries) {
-		const action = readActionModel(fn, mem, fn.EPDFForm_GetFieldActionModel(model, fieldIndex, event), budget);
+		const action = readActionModel(fn, mem, docPtr, fn.EPDFForm_GetFieldActionModel(model, fieldIndex, event), budget);
 		if (action) actions[key] = action;
 	}
 	return Object.keys(actions).length > 0 ? actions : void 0;
@@ -3836,18 +4142,19 @@ function blendModeFromCode(code) {
 * per-subtype reader builds its DTO by extending this with its own
 * fields and `subtype: '...'` discriminator.
 */
-function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision, actionBudget = new ActionReadBudgetTracker()) {
+function readAnnotationBase(fn, mem, docPtr, annotPtr, pageObjectNumber, index, revision, actionBudget = new ActionReadBudgetTracker()) {
 	const identity = readAnnotationIdentity(fn, mem, annotPtr, pageObjectNumber, index, revision);
 	const rect = readAnnotRect(fn, mem, annotPtr);
 	const flags = readAnnotFlags(fn, annotPtr);
 	const contents = readAnnotString(fn, mem, annotPtr, "Contents");
+	const subject = readAnnotString(fn, mem, annotPtr, "Subj");
 	const author = readAnnotString(fn, mem, annotPtr, "T");
 	const createdRaw = readAnnotString(fn, mem, annotPtr, "CreationDate");
 	const modifiedRaw = readAnnotString(fn, mem, annotPtr, "M");
 	const blendMode = blendModeFromCode(fn.EPDFAnnot_GetBlendMode(annotPtr));
 	const embd = readEmbedMetadata(fn, mem, annotPtr);
 	const relationship = readAnnotationRelationship(fn, mem, annotPtr, pageObjectNumber);
-	const actions = readAnnotationActions(fn, mem, annotPtr, actionBudget);
+	const actions = readAnnotationActions(fn, mem, docPtr, annotPtr, actionBudget);
 	return {
 		ref: identity.ref,
 		pageObjectNumber,
@@ -3857,6 +4164,7 @@ function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision
 		flags,
 		rect,
 		contents,
+		subject,
 		author,
 		created: createdRaw ? pdfDateToIso(createdRaw) : null,
 		modified: modifiedRaw ? pdfDateToIso(modifiedRaw) : null,
@@ -3870,7 +4178,7 @@ function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision
 		...actions ? { actions } : {}
 	};
 }
-function readAnnotationActions(fn, mem, annotPtr, budget) {
+function readAnnotationActions(fn, mem, docPtr, annotPtr, budget) {
 	const events = [
 		["activate", 0],
 		["cursorEnter", 1],
@@ -3886,7 +4194,7 @@ function readAnnotationActions(fn, mem, annotPtr, budget) {
 	];
 	const actions = {};
 	for (const [key, event] of events) {
-		const action = readActionModel(fn, mem, fn.EPDFAnnot_GetActionModel(annotPtr, event), budget);
+		const action = readActionModel(fn, mem, docPtr, fn.EPDFAnnot_GetActionModel(annotPtr, event), budget);
 		if (action) actions[key] = action;
 	}
 	return Object.keys(actions).length > 0 ? actions : void 0;
@@ -3917,7 +4225,7 @@ function collectPageAnnotations(input) {
 		const annotPtr = getAnnotPtrAt(i);
 		if (!annotPtr) continue;
 		try {
-			const base = readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, i, revision, actionBudget);
+			const base = readAnnotationBase(fn, mem, readCtx.docPtr, annotPtr, pageObjectNumber, i, revision, actionBudget);
 			const subtypeCode = fn.FPDFAnnot_GetSubtype(annotPtr);
 			const { reader } = pickReader(subtypeCode);
 			const dto = reader(fn, mem, annotPtr, base, subtypeCode, readCtx);
@@ -4131,19 +4439,31 @@ const ANNOT_SUBTYPE_WIDGET = 20;
 /** `FPDF_ANNOT_FREETEXT` — free-text annotation subtype code. */
 const ANNOT_SUBTYPE_FREETEXT = 3;
 /**
-* BOX-family subtypes (free-text 3, square 5, circle 6, stamp 13): the kinds
-* whose v3 writers put rotation in the AP `/Matrix` + `/EMBD_Metadata`
-* `/UnrotatedRect`. Only these are eligible for rotation-stripped appearance
-* rendering — vertex kinds (line/polyline/polygon/ink) pre-rotate their
-* geometry, so their rasters must stay on the classic path.
+* BOX-family subtypes (free-text 3, square 5, circle 6, stamp 13, caret 14):
+* the kinds whose v3 writers put rotation in the AP `/Matrix` +
+* `/EMBD_Metadata` `/UnrotatedRect`. Only these are eligible for
+* rotation-stripped appearance rendering — vertex kinds
+* (line/polyline/polygon/ink) pre-rotate their geometry, so their rasters must
+* stay on the classic path. This set MUST cover every kind whose reader
+* surfaces the rotation pair: `fromDTO` (plugin-annotation repository) mirrors
+* this exact condition to re-apply the stripped rotation as `apRot`.
 */
 const BOX_FAMILY_SUBTYPES = /* @__PURE__ */ new Set([
 	3,
 	5,
 	6,
-	13
+	13,
+	14
 ]);
 /**
+* Per-appearance output-pixel ceiling (see the clamp in `renderOne`).
+* 16 M px ≈ a 4000² raster ≈ 64 MB of transient RGBA — safely inside the
+* wasm heap for the one-at-a-time batch loop, while a page-sized annotation
+* stays crisp to roughly 5–6× before its appearance starts stretching.
+* Small annotations (the overwhelming majority) never come near it.
+*/
+const APPEARANCE_PIXEL_CLAMP = 16e6;
+/**
 * Maps an `AnnotationAppearanceMode` onto the PDFium appearance-mode int and
 * the `EPDFAnnot_GetAvailableAppearanceModes` bit it occupies.
 *   N -> mode 0 / bit 1, R -> mode 1 / bit 2, D -> mode 2 / bit 4.
@@ -4242,13 +4562,15 @@ var AnnotationAppearanceReader = class {
 			fn.EPDFAnnot_GenerateFormFieldAP(annotPtr);
 			if (!fn.EPDFAnnot_HasAppearanceStream(annotPtr, modeInt)) return null;
 		} else return null;
+		const rectArea = Math.max(1, (rect.right - rect.left) * (rect.top - rect.bottom));
+		const effScale = Math.min(scale, Math.sqrt(APPEARANCE_PIXEL_CLAMP / rectArea));
 		return rasterize(this.runtime, {
 			rect,
 			page,
 			rotation,
 			viewport: {
 				kind: "scale",
-				scale
+				scale: effScale
 			},
 			...maxOutputPixels !== void 0 ? { maxOutputPixels } : {},
 			background: "transparent",
@@ -4363,7 +4685,9 @@ function setAnnotFlags(fn, annotPtr, partial) {
 	if (!fn.FPDFAnnot_SetFlags(annotPtr, next)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "FPDFAnnot_SetFlags returned false");
 }
 /**
-* Write `/Rect` via `FPDFAnnot_SetRect`. FS_RECTF layout is
+* Write `/Rect` without touching `/AP`. Appearance preservation/regeneration
+* belongs to AnnotationMutator; a geometry primitive must not silently rewrite
+* an existing appearance `/BBox`. FS_RECTF layout is
 * `{ left, top, right, bottom }` (top > bottom in PDF coords).
 */
 function setAnnotRect(fn, mem, annotPtr, rect) {
@@ -4373,12 +4697,40 @@ function setAnnotRect(fn, mem, annotPtr, rect) {
 		mem.poke(buf, "f32", rect.top, 4);
 		mem.poke(buf, "f32", rect.right, 8);
 		mem.poke(buf, "f32", rect.bottom, 12);
-		if (!fn.FPDFAnnot_SetRect(annotPtr, buf)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "FPDFAnnot_SetRect returned false");
+		if (!fn.EPDFAnnot_SetRect(annotPtr, buf)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetRect returned false");
 	} finally {
 		mem.free(buf);
 	}
 }
 /**
+* Write a UTF-16 string entry into an annotation dictionary. The write
+* side of `readAnnotString`.
+*/
+function writeAnnotString(fn, mem, annotPtr, key, value) {
+	const ptr = mem.writeU16String(value);
+	try {
+		fn.FPDFAnnot_SetStringValue(annotPtr, key, ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+/**
+* Three-state string write: `null` REMOVES the dictionary entry.
+*
+* Clearing goes through `EPDFAnnot_RemoveKey` because
+* `FPDFAnnot_SetStringValue` with a NULL value writes an EMPTY string —
+* it never removes. True removal is what keeps the read side honest:
+* `readAnnotString` returns `null` iff the key is absent, so a cleared
+* field reads back as `null`, not `''`.
+*/
+function writeAnnotStringOrClear(fn, mem, annotPtr, key, value) {
+	if (value === null) {
+		fn.EPDFAnnot_RemoveKey(annotPtr, key);
+		return;
+	}
+	writeAnnotString(fn, mem, annotPtr, key, value);
+}
+/**
 * Set `/BS /S` (border style code) and `/BS /W` (width) in one call via
 * `EPDFAnnot_SetBorderStyle`. `styleCode` is a raw
 * `FPDF_ANNOT_BORDER_STYLE` enum value — the string<->code mapping lives
@@ -4577,8 +4929,8 @@ function setCalloutLine(fn, mem, annotPtr, points) {
 //#region src/features/annotations/internal/write/writeAnnotationBase.ts
 /**
 * Write the annotation-wide base fields shared by every Draft
-* (contents/nm). The kind-specific writer calls this BEFORE its own
-* field writes; order doesn't actually matter at the PDF level, but
+* (contents/subject/nm). The kind-specific writer calls this BEFORE its
+* own field writes; order doesn't actually matter at the PDF level, but
 * keeping the base first makes the writers symmetric with the readers.
 *
 * `/T` (author display) is stamped by the mutator from
@@ -4589,13 +4941,14 @@ function setCalloutLine(fn, mem, annotPtr, points) {
 * annotation; the writer does not.
 */
 function applyAnnotationBaseDraft(fn, mem, annotPtr, draft) {
-	if (draft.contents !== void 0) writeStringOrClear(fn, mem, annotPtr, "Contents", draft.contents);
-	if (draft.nm !== void 0 && draft.nm.length > 0) writeString(fn, mem, annotPtr, "NM", draft.nm);
+	if (draft.contents !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Contents", draft.contents);
+	if (draft.subject !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Subj", draft.subject);
+	if (draft.nm !== void 0 && draft.nm.length > 0) writeAnnotString(fn, mem, annotPtr, "NM", draft.nm);
 	if (draft.flags !== void 0) setAnnotFlags(fn, annotPtr, draft.flags);
 }
 /**
 * Write the annotation-wide base fields shared by every Patch
-* (contents). /T is bound at creation and not patchable — see
+* (contents/subject). /T is bound at creation and not patchable — see
 * `AnnotationPatchBase`. /NM is monotonic per annotation; the mutator
 * may stamp /NM opportunistically on a weak annotation via
 * `writeAnnotationNm`.
@@ -4606,7 +4959,8 @@ function applyAnnotationBaseDraft(fn, mem, annotPtr, draft) {
 *   "..."     -> set the entry to that value
 */
 function applyAnnotationBasePatch(fn, mem, annotPtr, patch) {
-	if (patch.contents !== void 0) writeStringOrClear(fn, mem, annotPtr, "Contents", patch.contents);
+	if (patch.contents !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Contents", patch.contents);
+	if (patch.subject !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Subj", patch.subject);
 	if (patch.flags !== void 0) setAnnotFlags(fn, annotPtr, patch.flags);
 }
 /**
@@ -4617,7 +4971,7 @@ function applyAnnotationBasePatch(fn, mem, annotPtr, patch) {
 */
 function writeAnnotationAuthor(fn, mem, annotPtr, displayName) {
 	if (displayName.length === 0) return;
-	writeString(fn, mem, annotPtr, "T", displayName);
+	writeAnnotString(fn, mem, annotPtr, "T", displayName);
 }
 /**
 * Stamp /NM on an annotation that didn't have one. Used by the mutator
@@ -4626,7 +4980,7 @@ function writeAnnotationAuthor(fn, mem, annotPtr, displayName) {
 */
 function writeAnnotationNm(fn, mem, annotPtr, nm) {
 	if (nm.length === 0) return;
-	writeString(fn, mem, annotPtr, "NM", nm);
+	writeAnnotString(fn, mem, annotPtr, "NM", nm);
 }
 /**
 * Stamp /M (modification date) on an annotation. /M is a standard
@@ -4643,22 +4997,7 @@ function writeAnnotationNm(fn, mem, annotPtr, nm) {
 * Format: `D:YYYYMMDDHHmmSSOHH'mm'` (see formatPdfDate).
 */
 function writeAnnotationModified(fn, mem, annotPtr, now = /* @__PURE__ */ new Date()) {
-	writeString(fn, mem, annotPtr, "M", formatPdfDate(now));
-}
-function writeString(fn, mem, annotPtr, key, value) {
-	const ptr = mem.writeU16String(value);
-	try {
-		fn.FPDFAnnot_SetStringValue(annotPtr, key, ptr);
-	} finally {
-		mem.free(ptr);
-	}
-}
-function writeStringOrClear(fn, mem, annotPtr, key, value) {
-	if (value === null) {
-		fn.FPDFAnnot_SetStringValue(annotPtr, key, _embedpdf_engine_runtime.NULL_PTR);
-		return;
-	}
-	writeString(fn, mem, annotPtr, key, value);
+	writeAnnotString(fn, mem, annotPtr, "M", formatPdfDate(now));
 }
 //#endregion
 //#region src/features/annotations/internal/identity/captureOrStampStableId.ts
@@ -4824,32 +5163,207 @@ function computeMutationImpact(inputs) {
 *     `AnnotationUpdateResult.updated`.
 */
 function readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, index, revision, ctx) {
-	const base = readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision);
+	const base = readAnnotationBase(fn, mem, ctx.docPtr, annotPtr, pageObjectNumber, index, revision);
 	const subtypeCode = fn.FPDFAnnot_GetSubtype(annotPtr);
 	const { reader } = pickReader(subtypeCode);
 	return reader(fn, mem, annotPtr, base, subtypeCode, ctx);
 }
 //#endregion
-//#region src/features/annotations/internal/write/writeCaretAnnotation.ts
-/** Default `/C` colour when a caret draft omits it (engine-wide default mark). */
-const DEFAULT_CARET_COLOR = {
-	r: 255,
-	g: 0,
-	b: 0
-};
-/** Default opacity, set explicitly so reads always round-trip the same value. */
-const DEFAULT_OPACITY$4 = 1;
+//#region src/features/annotations/internal/write/writeEmbedMetadata.ts
 /**
-* Apply a caret draft to a freshly-created annotation. Caret carries no
-* geometry of its own beyond `/Rect`. Order:
-*   1. base author-metadata (contents/nm/flags)
-*   2. `/Rect` (required — supplied by the caller; never derived)
-*   3. `/C` color + `/CA` opacity
-*   4. `/RD` rectangle differences (optional)
+* Write the EmbedPDF-namespaced /EMBD_Metadata annotation dictionary.
+*
+* This module owns ONLY the vendor-extension dictionary. Standard PDF
+* base fields (/T, /M, /NM, /Contents) are handled by
+* `writers/annotations/base.ts` — /EMBD_Metadata is a separate
+* dictionary nested under the annotation that carries cloud-side
+* identity bookkeeping which has no PDF-spec equivalent.
+*
+* Schema (v1):
+*   /EMBD_Metadata <<
+*     /SchemaVersion 1                       % EmbedPDF metadata schema version
+*     /UserID    (acme/alice)                % identity that created the annotation
+*     /GroupID   (engineering)               % group the annotation belongs to
+*     /CreatedBy (acme/alice)                % same as UserID on create
+*     /UpdatedBy (acme/alice)                % last editor; refreshed on every update
+*   >>
+*
+* Read side: see `readers/annotations/embed-metadata.ts` (commit 12).
+*
+* PDFium bindings used: the `EPDFAnnot_*EmbedMetadata*` extension API
+* shipped in the EmbedPDF PDFium fork. Values are written as UTF-16LE
+* strings via the same `mem.writeU16String` pattern the base writer
+* uses for /T.
 */
-function applyCaretDraft(fn, mem, annotPtr, draft) {
-	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
+const KEY_SCHEMA_VERSION = "SchemaVersion";
+const KEY_USER_ID = "UserID";
+const KEY_GROUP_ID = "GroupID";
+const KEY_CREATED_BY = "CreatedBy";
+const KEY_UPDATED_BY = "UpdatedBy";
+/**
+* Stamp /EMBD_Metadata on a freshly created annotation. No-op if the
+* actor has no identity fields — the worker still emits the standard
+* /M timestamp via the base writer; only the vendor dictionary is
+* skipped.
+*
+*   actor.userId    → /UserID, /CreatedBy, /UpdatedBy
+*   actor.groupId   → /GroupID
+*
+* /SchemaVersion is written whenever any field is written.
+*/
+function applyEmbedMetadataOnCreate(fn, mem, annotPtr, actor) {
+	if (!actor || !actor.userId && !actor.groupId) return;
+	fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_SCHEMA_VERSION, 1);
+	if (actor.userId) {
+		setMetadataString(fn, mem, annotPtr, KEY_USER_ID, actor.userId);
+		setMetadataString(fn, mem, annotPtr, KEY_CREATED_BY, actor.userId);
+		setMetadataString(fn, mem, annotPtr, KEY_UPDATED_BY, actor.userId);
+	}
+	if (actor.groupId) setMetadataString(fn, mem, annotPtr, KEY_GROUP_ID, actor.groupId);
+}
+/**
+* Apply /EMBD_Metadata refreshes on update. Two fields can change on
+* update; everything else (UserID, CreatedBy) is immutable.
+*
+*   actor.userId  → /UpdatedBy (refreshed every update where the
+*                   caller has an identity)
+*   actor.groupId → /GroupID   (reassigned only when the patch
+*                   explicitly contains a new groupId; route runs
+*                   `checkSetGroup` first)
+*
+* If the target annotation has no EMBD_Metadata yet (created before
+* the cloud started stamping, or by a non-cloud writer), we seed
+* /SchemaVersion so subsequent readers can find the marker.
+*
+* No-op when the actor has neither userId nor groupId.
+*/
+function applyEmbedMetadataOnUpdate(fn, mem, annotPtr, actor) {
+	if (!actor || !actor.userId && !actor.groupId) return;
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_SCHEMA_VERSION, 1);
+	if (actor.userId) setMetadataString(fn, mem, annotPtr, KEY_UPDATED_BY, actor.userId);
+	if (actor.groupId) setMetadataString(fn, mem, annotPtr, KEY_GROUP_ID, actor.groupId);
+}
+function setMetadataString(fn, mem, annotPtr, key, value) {
+	const ptr = mem.writeU16String(value);
+	try {
+		fn.EPDFAnnot_SetEmbedMetadataString(annotPtr, key, ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+//#endregion
+//#region src/features/annotations/internal/write/writeAnnotationTransformMetadata.ts
+/**
+* Write the EmbedPDF transform keys under /EMBD_Metadata. This is the seam
+* PDFium's native AP generator reads to bake a ROTATED appearance:
+*
+*   /EMBD_Metadata <<
+*     /Rotation      45                    % degrees, PDF convention (CCW)
+*     /UnrotatedRect [x0 y0 x1 y1]         % BOX kinds only — the logical box
+*   >>
+*
+* The family split (see the v3 plan):
+*   - BOX kinds (square/circle/free-text): `/Rotation` + `/UnrotatedRect`.
+*     With BOTH present the AP generator emits an `/AP /Matrix` that rotates a
+*     box-sized appearance about the box centre, and `/Rect` is the enclosing
+*     AABB. This is the portable, externally-correct rotation.
+*   - VERTEX kinds (line/polyline/polygon/ink): `/Rotation` ONLY (advisory).
+*     The points are already rotated (they are the visual), so a lone
+*     `/Rotation` is INERT for the AP generator (it ignores `/Rotation` with no
+*     `/UnrotatedRect`) — it just records the applied angle so EmbedPDF can
+*     reconstruct an oriented selection box + offer reset.
+*
+* Both fields follow the engine-wide tri-state law ("a patch touches what it
+* states, preserves what it omits"):
+*   - `undefined` → the key is UNTOUCHED (a rect-only move keeps its rotation).
+*   - `null` or `0` → CLEAR just that key via `EPDFAnnot_ClearEmbedMetadataKey`
+*     (0 ≡ no rotation is the canonical identity, not a sentinel; never clear
+*     the whole dict — identity fields UserID/GroupID/CreatedBy/UpdatedBy must
+*     survive).
+*   - a value → SET the key. Setting a nonzero rotation with no
+*     `/UnrotatedRect` (neither in the patch nor already on the annotation)
+*     is an unsatisfiable state for the AP generator and throws `InvalidArg`.
+*
+* MUST run BEFORE `EPDFAnnot_GenerateAppearance` so the bake sees the rotation.
+* `/SchemaVersion` is seeded (stays 1) if this is the first key in the dict.
+*/
+const KEY_ROTATION = "Rotation";
+const KEY_UNROTATED_RECT = "UnrotatedRect";
+/** Seed `/SchemaVersion` when we are about to create the dict by writing the
+*  first transform key, so the marker readers look for is always present. */
+function ensureSchemaVersion(fn, annotPtr) {
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, "SchemaVersion", 1);
+}
+function setRotation(fn, annotPtr, rotation) {
+	ensureSchemaVersion(fn, annotPtr);
+	fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_ROTATION, rotation);
+}
+function setUnrotatedRect(fn, mem, annotPtr, rect) {
+	ensureSchemaVersion(fn, annotPtr);
+	const buf = mem.alloc(16);
+	try {
+		mem.poke(buf, "f32", rect.left, 0);
+		mem.poke(buf, "f32", rect.top, 4);
+		mem.poke(buf, "f32", rect.right, 8);
+		mem.poke(buf, "f32", rect.bottom, 12);
+		fn.EPDFAnnot_SetEmbedMetadataRect(annotPtr, KEY_UNROTATED_RECT, buf);
+	} finally {
+		mem.free(buf);
+	}
+}
+/**
+* Write transform metadata for a BOX kind (square/circle/free-text/stamp),
+* tri-state per field: `undefined` never touches the document (safe to call on
+* every patch), `null`/`0` clears, a value sets. A nonzero rotation with no
+* unrotated box anywhere (patch or annotation) is unsatisfiable — the AP
+* generator needs the pair — and throws instead of writing a broken state.
+*/
+function writeBoxTransformMetadata(fn, mem, annotPtr, t) {
+	if (t.rotation !== void 0) if (t.rotation !== null && t.rotation !== 0) {
+		if (!(t.unrotatedRect != null || t.unrotatedRect === void 0 && readAnnotationUnrotatedRect(fn, mem, annotPtr) != null)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "rotation requires unrotatedRect: supply the pair together (or rely on an existing /EMBD_Metadata/UnrotatedRect)");
+		setRotation(fn, annotPtr, t.rotation);
+	} else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
+	if (t.unrotatedRect !== void 0) if (t.unrotatedRect !== null) setUnrotatedRect(fn, mem, annotPtr, t.unrotatedRect);
+	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+}
+/**
+* Write the advisory `/Rotation` scalar for a VERTEX kind
+* (line/polyline/polygon/ink), tri-state: `undefined` never touches the
+* document, `null`/`0` clears, a value sets. Whenever it does write, any
+* `/UnrotatedRect` is defensively cleared — that key is an impossible state on
+* a vertex kind and must never accidentally drive the AP generator.
+*/
+function writeVertexTransformMetadata(fn, annotPtr, t) {
+	if (t.rotation === void 0) return;
+	if (t.rotation !== null && t.rotation !== 0) setRotation(fn, annotPtr, t.rotation);
+	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
+	fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+}
+//#endregion
+//#region src/features/annotations/internal/write/writeCaretAnnotation.ts
+/** Default `/C` colour when a caret draft omits it (engine-wide default mark). */
+const DEFAULT_CARET_COLOR = {
+	r: 255,
+	g: 0,
+	b: 0
+};
+/** Default opacity, set explicitly so reads always round-trip the same value. */
+const DEFAULT_OPACITY$4 = 1;
+/**
+* Apply a caret draft to a freshly-created annotation. Caret carries no
+* geometry of its own beyond `/Rect`. Order:
+*   1. base author-metadata (contents/nm/flags)
+*   2. `/Rect` (required — supplied by the caller; never derived)
+*   3. `/C` color + `/CA` opacity
+*   4. `/RD` rectangle differences (optional)
+*/
+function applyCaretDraft(fn, mem, annotPtr, draft) {
+	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
 	setAnnotRect(fn, mem, annotPtr, draft.rect);
+	writeBoxTransformMetadata(fn, mem, annotPtr, {
+		rotation: draft.rotation,
+		unrotatedRect: draft.unrotatedRect
+	});
 	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_CARET_COLOR);
 	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY$4);
 	if (draft.intent !== void 0) setIntent(fn, annotPtr, caretIntentToName(draft.intent));
@@ -4862,6 +5376,10 @@ function applyCaretDraft(fn, mem, annotPtr, draft) {
 function applyCaretPatch(fn, mem, annotPtr, patch) {
 	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
 	if (patch.rect !== void 0) setAnnotRect(fn, mem, annotPtr, patch.rect);
+	if (patch.rotation !== void 0 || patch.unrotatedRect !== void 0) writeBoxTransformMetadata(fn, mem, annotPtr, {
+		rotation: patch.rotation,
+		unrotatedRect: patch.unrotatedRect
+	});
 	if (patch.color !== void 0) setAnnotColor(fn, annotPtr, patch.color);
 	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
 	if (patch.intent !== void 0) setIntent(fn, annotPtr, caretIntentToName(patch.intent));
@@ -4951,264 +5469,93 @@ function attachFile(fn, mem, annotPtr, file, resource, docPtr) {
 * path; anything else is treated as a registered-font `key` and resolved to
 * this thread's FontId. A key with no resolver wired (e.g. a host without a
 * font registry) is a programming error — fail loud rather than silently
-* downgrade to Helvetica and embed the wrong glyphs.
-*
-* Shared by the free-text and redact writers: `/DA` styles a free-text body
-* and a redaction `/OverlayText` label through the exact same triple.
-*/
-function applyDefaultAppearance(fn, annotPtr, fontFamily, fontSize, color, ctx) {
-	if (isStandardFont(fontFamily)) {
-		setDefaultAppearance(fn, annotPtr, standardFontToCode(fontFamily), fontSize, color);
-		return;
-	}
-	if (!ctx?.resolveRegisteredFontId) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `fontFamily '${fontFamily}' is not a standard font and no font registry is available on this host`);
-	setDefaultAppearanceRegisteredFont(fn, annotPtr, ctx.resolveRegisteredFontId(fontFamily), fontSize, color);
-}
-const DEFAULT_COLOR = {
-	r: 255,
-	g: 0,
-	b: 0
-};
-/**
-* Apply the geometry styling (`/C`, `/CA`, `/BS`, dash) from a draft to a
-* freshly-created annotation. This is the no-fill layer shared by ink and
-* the filled families; `interiorColor` (`/IC`) is layered on by
-* {@link applyFilledStyleDraft}. Geometry (`/Rect`, `/Vertices`, `/L`,
-* `/InkList`), cloudy borders, rect-differences, and line endings are
-* layered on by the family-specific writer around this call.
-*/
-function applyGeometryStyleDraft(fn, mem, annotPtr, draft) {
-	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_COLOR);
-	setAnnotOpacity(fn, annotPtr, draft.opacity ?? 1);
-	applyBorderDraft(fn, mem, annotPtr, draft);
-}
-/**
-* Write the `/BS` border (style + width, then dash) from a draft. This is
-* the border-only slice of {@link applyGeometryStyleDraft}, shared with the
-* free-text box border (which manages `/C` and `/DA` itself). A missing
-* `borderStyle`/`strokeWidth` falls back to a 1pt solid border.
-*/
-function applyBorderDraft(fn, mem, annotPtr, draft) {
-	setBorderStyle(fn, annotPtr, borderStyleToCode(draft.borderStyle ?? "solid"), draft.strokeWidth ?? 1);
-	if (draft.dashArray !== void 0 && draft.dashArray.length > 0) setBorderDashPattern(fn, mem, annotPtr, draft.dashArray);
-}
-/**
-* Apply the geometry styling from a patch to an existing annotation. Only
-* present fields are touched. Border style + width share the single
-* `EPDFAnnot_SetBorderStyle` call, so when only one is patched we read the
-* current pair first and preserve the other.
-*/
-function applyGeometryStylePatch(fn, mem, annotPtr, patch) {
-	if (patch.color !== void 0) setAnnotColor(fn, annotPtr, patch.color);
-	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
-	applyBorderPatch(fn, mem, annotPtr, patch);
-}
-/**
-* Write the `/BS` border from a patch, touching only present fields. Border
-* style + width share the single `EPDFAnnot_SetBorderStyle` call, so when
-* only one is patched we read the current pair first and preserve the other.
-* The border-only slice of {@link applyGeometryStylePatch}, shared with the
-* free-text box border.
-*/
-function applyBorderPatch(fn, mem, annotPtr, patch) {
-	if (patch.borderStyle !== void 0 || patch.strokeWidth !== void 0) {
-		const current = readBorderStyle(fn, mem, annotPtr);
-		const style = patch.borderStyle ?? borderStyleFromCode(current.styleCode);
-		const width = patch.strokeWidth ?? current.width;
-		setBorderStyle(fn, annotPtr, borderStyleToCode(style), width);
-	}
-	if (patch.dashArray !== void 0 && patch.dashArray.length > 0) setBorderDashPattern(fn, mem, annotPtr, patch.dashArray);
-}
-/**
-* Apply the full stroke/fill styling (geometry styling + `/IC`) from a
-* draft. A `null`/omitted fill clears `/IC` so the shape renders unfilled.
-* Used by the filled families (circle/square/polygon/polyline/line).
-*/
-function applyFilledStyleDraft(fn, mem, annotPtr, draft) {
-	const interior = draft.interiorColor ?? null;
-	if (interior === null) clearAnnotColor(fn, annotPtr, FPDFANNOT_COLORTYPE.InteriorColor);
-	else setAnnotColor(fn, annotPtr, interior, FPDFANNOT_COLORTYPE.InteriorColor);
-	applyGeometryStyleDraft(fn, mem, annotPtr, draft);
-}
-/**
-* Apply the full stroke/fill styling from a patch. Only present fields are
-* touched; `interiorColor: null` clears `/IC`.
-*/
-function applyFilledStylePatch(fn, mem, annotPtr, patch) {
-	if (patch.interiorColor !== void 0) if (patch.interiorColor === null) clearAnnotColor(fn, annotPtr, FPDFANNOT_COLORTYPE.InteriorColor);
-	else setAnnotColor(fn, annotPtr, patch.interiorColor, FPDFANNOT_COLORTYPE.InteriorColor);
-	applyGeometryStylePatch(fn, mem, annotPtr, patch);
-}
-//#endregion
-//#region src/features/annotations/internal/write/writeEmbedMetadata.ts
-/**
-* Write the EmbedPDF-namespaced /EMBD_Metadata annotation dictionary.
-*
-* This module owns ONLY the vendor-extension dictionary. Standard PDF
-* base fields (/T, /M, /NM, /Contents) are handled by
-* `writers/annotations/base.ts` — /EMBD_Metadata is a separate
-* dictionary nested under the annotation that carries cloud-side
-* identity bookkeeping which has no PDF-spec equivalent.
-*
-* Schema (v1):
-*   /EMBD_Metadata <<
-*     /SchemaVersion 1                       % EmbedPDF metadata schema version
-*     /UserID    (acme/alice)                % identity that created the annotation
-*     /GroupID   (engineering)               % group the annotation belongs to
-*     /CreatedBy (acme/alice)                % same as UserID on create
-*     /UpdatedBy (acme/alice)                % last editor; refreshed on every update
-*   >>
-*
-* Read side: see `readers/annotations/embed-metadata.ts` (commit 12).
-*
-* PDFium bindings used: the `EPDFAnnot_*EmbedMetadata*` extension API
-* shipped in the EmbedPDF PDFium fork. Values are written as UTF-16LE
-* strings via the same `mem.writeU16String` pattern the base writer
-* uses for /T.
-*/
-const KEY_SCHEMA_VERSION = "SchemaVersion";
-const KEY_USER_ID = "UserID";
-const KEY_GROUP_ID = "GroupID";
-const KEY_CREATED_BY = "CreatedBy";
-const KEY_UPDATED_BY = "UpdatedBy";
-/**
-* Stamp /EMBD_Metadata on a freshly created annotation. No-op if the
-* actor has no identity fields — the worker still emits the standard
-* /M timestamp via the base writer; only the vendor dictionary is
-* skipped.
-*
-*   actor.userId    → /UserID, /CreatedBy, /UpdatedBy
-*   actor.groupId   → /GroupID
-*
-* /SchemaVersion is written whenever any field is written.
-*/
-function applyEmbedMetadataOnCreate(fn, mem, annotPtr, actor) {
-	if (!actor || !actor.userId && !actor.groupId) return;
-	fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_SCHEMA_VERSION, 1);
-	if (actor.userId) {
-		setMetadataString(fn, mem, annotPtr, KEY_USER_ID, actor.userId);
-		setMetadataString(fn, mem, annotPtr, KEY_CREATED_BY, actor.userId);
-		setMetadataString(fn, mem, annotPtr, KEY_UPDATED_BY, actor.userId);
-	}
-	if (actor.groupId) setMetadataString(fn, mem, annotPtr, KEY_GROUP_ID, actor.groupId);
-}
-/**
-* Apply /EMBD_Metadata refreshes on update. Two fields can change on
-* update; everything else (UserID, CreatedBy) is immutable.
-*
-*   actor.userId  → /UpdatedBy (refreshed every update where the
-*                   caller has an identity)
-*   actor.groupId → /GroupID   (reassigned only when the patch
-*                   explicitly contains a new groupId; route runs
-*                   `checkSetGroup` first)
-*
-* If the target annotation has no EMBD_Metadata yet (created before
-* the cloud started stamping, or by a non-cloud writer), we seed
-* /SchemaVersion so subsequent readers can find the marker.
-*
-* No-op when the actor has neither userId nor groupId.
-*/
-function applyEmbedMetadataOnUpdate(fn, mem, annotPtr, actor) {
-	if (!actor || !actor.userId && !actor.groupId) return;
-	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_SCHEMA_VERSION, 1);
-	if (actor.userId) setMetadataString(fn, mem, annotPtr, KEY_UPDATED_BY, actor.userId);
-	if (actor.groupId) setMetadataString(fn, mem, annotPtr, KEY_GROUP_ID, actor.groupId);
-}
-function setMetadataString(fn, mem, annotPtr, key, value) {
-	const ptr = mem.writeU16String(value);
-	try {
-		fn.EPDFAnnot_SetEmbedMetadataString(annotPtr, key, ptr);
-	} finally {
-		mem.free(ptr);
-	}
-}
-//#endregion
-//#region src/features/annotations/internal/write/writeAnnotationTransformMetadata.ts
-/**
-* Write the EmbedPDF transform keys under /EMBD_Metadata. This is the seam
-* PDFium's native AP generator reads to bake a ROTATED appearance:
-*
-*   /EMBD_Metadata <<
-*     /Rotation      45                    % degrees, PDF convention (CCW)
-*     /UnrotatedRect [x0 y0 x1 y1]         % BOX kinds only — the logical box
-*   >>
-*
-* The family split (see the v3 plan):
-*   - BOX kinds (square/circle/free-text): `/Rotation` + `/UnrotatedRect`.
-*     With BOTH present the AP generator emits an `/AP /Matrix` that rotates a
-*     box-sized appearance about the box centre, and `/Rect` is the enclosing
-*     AABB. This is the portable, externally-correct rotation.
-*   - VERTEX kinds (line/polyline/polygon/ink): `/Rotation` ONLY (advisory).
-*     The points are already rotated (they are the visual), so a lone
-*     `/Rotation` is INERT for the AP generator (it ignores `/Rotation` with no
-*     `/UnrotatedRect`) — it just records the applied angle so EmbedPDF can
-*     reconstruct an oriented selection box + offer reset.
-*
-* Both fields follow the engine-wide tri-state law ("a patch touches what it
-* states, preserves what it omits"):
-*   - `undefined` → the key is UNTOUCHED (a rect-only move keeps its rotation).
-*   - `null` or `0` → CLEAR just that key via `EPDFAnnot_ClearEmbedMetadataKey`
-*     (0 ≡ no rotation is the canonical identity, not a sentinel; never clear
-*     the whole dict — identity fields UserID/GroupID/CreatedBy/UpdatedBy must
-*     survive).
-*   - a value → SET the key. Setting a nonzero rotation with no
-*     `/UnrotatedRect` (neither in the patch nor already on the annotation)
-*     is an unsatisfiable state for the AP generator and throws `InvalidArg`.
+* downgrade to Helvetica and embed the wrong glyphs.
 *
-* MUST run BEFORE `EPDFAnnot_GenerateAppearance` so the bake sees the rotation.
-* `/SchemaVersion` is seeded (stays 1) if this is the first key in the dict.
+* Shared by the free-text and redact writers: `/DA` styles a free-text body
+* and a redaction `/OverlayText` label through the exact same triple.
 */
-const KEY_ROTATION = "Rotation";
-const KEY_UNROTATED_RECT = "UnrotatedRect";
-/** Seed `/SchemaVersion` when we are about to create the dict by writing the
-*  first transform key, so the marker readers look for is always present. */
-function ensureSchemaVersion(fn, annotPtr) {
-	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, "SchemaVersion", 1);
+function applyDefaultAppearance(fn, annotPtr, fontFamily, fontSize, color, ctx) {
+	if (isStandardFont(fontFamily)) {
+		setDefaultAppearance(fn, annotPtr, standardFontToCode(fontFamily), fontSize, color);
+		return;
+	}
+	if (!ctx?.resolveRegisteredFontId) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `fontFamily '${fontFamily}' is not a standard font and no font registry is available on this host`);
+	setDefaultAppearanceRegisteredFont(fn, annotPtr, ctx.resolveRegisteredFontId(fontFamily), fontSize, color);
 }
-function setRotation(fn, annotPtr, rotation) {
-	ensureSchemaVersion(fn, annotPtr);
-	fn.EPDFAnnot_SetEmbedMetadataNumber(annotPtr, KEY_ROTATION, rotation);
+const DEFAULT_COLOR = {
+	r: 255,
+	g: 0,
+	b: 0
+};
+/**
+* Apply the geometry styling (`/C`, `/CA`, `/BS`, dash) from a draft to a
+* freshly-created annotation. This is the no-fill layer shared by ink and
+* the filled families; `interiorColor` (`/IC`) is layered on by
+* {@link applyFilledStyleDraft}. Geometry (`/Rect`, `/Vertices`, `/L`,
+* `/InkList`), cloudy borders, rect-differences, and line endings are
+* layered on by the family-specific writer around this call.
+*/
+function applyGeometryStyleDraft(fn, mem, annotPtr, draft) {
+	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_COLOR);
+	setAnnotOpacity(fn, annotPtr, draft.opacity ?? 1);
+	applyBorderDraft(fn, mem, annotPtr, draft);
 }
-function setUnrotatedRect(fn, mem, annotPtr, rect) {
-	ensureSchemaVersion(fn, annotPtr);
-	const buf = mem.alloc(16);
-	try {
-		mem.poke(buf, "f32", rect.left, 0);
-		mem.poke(buf, "f32", rect.top, 4);
-		mem.poke(buf, "f32", rect.right, 8);
-		mem.poke(buf, "f32", rect.bottom, 12);
-		fn.EPDFAnnot_SetEmbedMetadataRect(annotPtr, KEY_UNROTATED_RECT, buf);
-	} finally {
-		mem.free(buf);
+/**
+* Write the `/BS` border (style + width, then dash) from a draft. This is
+* the border-only slice of {@link applyGeometryStyleDraft}, shared with the
+* free-text box border (which manages `/C` and `/DA` itself). A missing
+* `borderStyle`/`strokeWidth` falls back to a 1pt solid border.
+*/
+function applyBorderDraft(fn, mem, annotPtr, draft) {
+	setBorderStyle(fn, annotPtr, borderStyleToCode(draft.borderStyle ?? "solid"), draft.strokeWidth ?? 1);
+	if (draft.dashArray !== void 0 && draft.dashArray.length > 0) setBorderDashPattern(fn, mem, annotPtr, draft.dashArray);
+}
+/**
+* Apply the geometry styling from a patch to an existing annotation. Only
+* present fields are touched. Border style + width share the single
+* `EPDFAnnot_SetBorderStyle` call, so when only one is patched we read the
+* current pair first and preserve the other.
+*/
+function applyGeometryStylePatch(fn, mem, annotPtr, patch) {
+	if (patch.color !== void 0) setAnnotColor(fn, annotPtr, patch.color);
+	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
+	applyBorderPatch(fn, mem, annotPtr, patch);
+}
+/**
+* Write the `/BS` border from a patch, touching only present fields. Border
+* style + width share the single `EPDFAnnot_SetBorderStyle` call, so when
+* only one is patched we read the current pair first and preserve the other.
+* The border-only slice of {@link applyGeometryStylePatch}, shared with the
+* free-text box border.
+*/
+function applyBorderPatch(fn, mem, annotPtr, patch) {
+	if (patch.borderStyle !== void 0 || patch.strokeWidth !== void 0) {
+		const current = readBorderStyle(fn, mem, annotPtr);
+		const style = patch.borderStyle ?? borderStyleFromCode(current.styleCode);
+		const width = patch.strokeWidth ?? current.width;
+		setBorderStyle(fn, annotPtr, borderStyleToCode(style), width);
 	}
+	if (patch.dashArray !== void 0 && patch.dashArray.length > 0) setBorderDashPattern(fn, mem, annotPtr, patch.dashArray);
 }
 /**
-* Write transform metadata for a BOX kind (square/circle/free-text/stamp),
-* tri-state per field: `undefined` never touches the document (safe to call on
-* every patch), `null`/`0` clears, a value sets. A nonzero rotation with no
-* unrotated box anywhere (patch or annotation) is unsatisfiable — the AP
-* generator needs the pair — and throws instead of writing a broken state.
+* Apply the full stroke/fill styling (geometry styling + `/IC`) from a
+* draft. A `null`/omitted fill clears `/IC` so the shape renders unfilled.
+* Used by the filled families (circle/square/polygon/polyline/line).
 */
-function writeBoxTransformMetadata(fn, mem, annotPtr, t) {
-	if (t.rotation !== void 0) if (t.rotation !== null && t.rotation !== 0) {
-		if (!(t.unrotatedRect != null || t.unrotatedRect === void 0 && readAnnotationUnrotatedRect(fn, mem, annotPtr) != null)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "rotation requires unrotatedRect: supply the pair together (or rely on an existing /EMBD_Metadata/UnrotatedRect)");
-		setRotation(fn, annotPtr, t.rotation);
-	} else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
-	if (t.unrotatedRect !== void 0) if (t.unrotatedRect !== null) setUnrotatedRect(fn, mem, annotPtr, t.unrotatedRect);
-	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+function applyFilledStyleDraft(fn, mem, annotPtr, draft) {
+	const interior = draft.interiorColor ?? null;
+	if (interior === null) clearAnnotColor(fn, annotPtr, FPDFANNOT_COLORTYPE.InteriorColor);
+	else setAnnotColor(fn, annotPtr, interior, FPDFANNOT_COLORTYPE.InteriorColor);
+	applyGeometryStyleDraft(fn, mem, annotPtr, draft);
 }
 /**
-* Write the advisory `/Rotation` scalar for a VERTEX kind
-* (line/polyline/polygon/ink), tri-state: `undefined` never touches the
-* document, `null`/`0` clears, a value sets. Whenever it does write, any
-* `/UnrotatedRect` is defensively cleared — that key is an impossible state on
-* a vertex kind and must never accidentally drive the AP generator.
+* Apply the full stroke/fill styling from a patch. Only present fields are
+* touched; `interiorColor: null` clears `/IC`.
 */
-function writeVertexTransformMetadata(fn, annotPtr, t) {
-	if (t.rotation === void 0) return;
-	if (t.rotation !== null && t.rotation !== 0) setRotation(fn, annotPtr, t.rotation);
-	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
-	fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+function applyFilledStylePatch(fn, mem, annotPtr, patch) {
+	if (patch.interiorColor !== void 0) if (patch.interiorColor === null) clearAnnotColor(fn, annotPtr, FPDFANNOT_COLORTYPE.InteriorColor);
+	else setAnnotColor(fn, annotPtr, patch.interiorColor, FPDFANNOT_COLORTYPE.InteriorColor);
+	applyGeometryStylePatch(fn, mem, annotPtr, patch);
 }
 //#endregion
 //#region src/features/annotations/internal/write/writeFreeTextAnnotation.ts
@@ -5980,13 +6327,18 @@ const DEFAULT_OPACITY = 1;
 * Apply a text (sticky-note) draft. The visual is entirely generator-owned:
 * the mutator's closing `regenerateAppearance` bakes the 20×20 note icon
 * from `/C` + `/Name` (GenerateTextAP), so this writer only records state.
+* `/State` + `/StateModel` are dictionary-only (ISO 32000 §12.5.6.3) and
+* never reach the generator.
 */
 function applyTextDraft(fn, mem, annotPtr, draft) {
+	if (draft.state !== void 0 && draft.stateModel === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "text draft: state requires stateModel (ISO 32000 §12.5.6.3)");
 	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
 	setAnnotRect(fn, mem, annotPtr, draft.rect);
 	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_NOTE_COLOR);
 	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY);
 	setNoteIcon(fn, annotPtr, draft.icon ?? "note");
+	if (draft.stateModel !== void 0) writeAnnotString(fn, mem, annotPtr, "StateModel", stateModelToPdf(draft.stateModel));
+	if (draft.state !== void 0) writeAnnotString(fn, mem, annotPtr, "State", stateToPdf(draft.state));
 }
 function applyTextPatch(fn, mem, annotPtr, patch) {
 	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
@@ -5994,6 +6346,8 @@ function applyTextPatch(fn, mem, annotPtr, patch) {
 	if (patch.color !== void 0) setAnnotColor(fn, annotPtr, patch.color);
 	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
 	if (patch.icon !== void 0) setNoteIcon(fn, annotPtr, patch.icon);
+	if (patch.stateModel !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "StateModel", patch.stateModel === null ? null : stateModelToPdf(patch.stateModel));
+	if (patch.state !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "State", patch.state === null ? null : stateToPdf(patch.state));
 }
 function isTextSubtype(subtype) {
 	return subtype === "text";
@@ -6971,17 +7325,35 @@ var RedactionApplier = class {
 	}
 	applyAllOnPage(pagePtr) {
 		const { fn, mem } = this.runtime;
+		const hasRedactions = this.pageHasRedactAnnotations(pagePtr);
 		return withScratch(mem, 4, (countPtr) => {
-			if (!fn.EPDFPage_ApplyRedactions(pagePtr, countPtr)) return {
-				status: "unchanged",
-				removed: 0
-			};
+			if (!fn.EPDFPage_ApplyRedactions(pagePtr, countPtr)) {
+				if (hasRedactions) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "native page redaction apply failed");
+				return {
+					status: "unchanged",
+					removed: 0
+				};
+			}
 			return {
 				status: "applied",
 				removed: readI32(mem, countPtr) >>> 0
 			};
 		});
 	}
+	pageHasRedactAnnotations(pagePtr) {
+		const { fn } = this.runtime;
+		const count = fn.FPDFPage_GetAnnotCount(pagePtr);
+		for (let index = 0; index < count; index++) {
+			const annotPtr = fn.FPDFPage_GetAnnot(pagePtr, index);
+			if (!annotPtr) continue;
+			try {
+				if ((0, _embedpdf_engine_core_runtime.subtypeFromCode)(fn.FPDFAnnot_GetSubtype(annotPtr)) === "redact") return true;
+			} finally {
+				fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+		}
+		return false;
+	}
 	applyRefsOnPage(pagePtr, refs) {
 		const { fn, mem } = this.runtime;
 		let removed = 0;
@@ -7007,23 +7379,26 @@ var RedactionApplier = class {
 //#region src/features/text/PageTextReader.ts
 /**
 * Per-page slow-path text reader. Acquires a `pagePtr` from the
-* `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
-* extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
-* and releases everything in reverse order.
-*
-* Memory model:
-*   - `count` is in UTF-16 code units (FPDFText's "char").
-*   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
-*     trailing NUL terminator).
-*   - `mem.readU16String` walks the buffer up to the NUL and decodes
-*     to a JS string, faithfully preserving surrogate pairs.
-*
-* Errors:
-*   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
-*     (raised by `PagePtrPool.acquire`).
-*   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
-*     not happen on a healthy page; treat it as a runtime bug rather
-*     than user error.
+* `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+* the page text, and releases everything in reverse order.
+*
+* Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+* CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+* `text` is the TEXT projection. The two diverge when a character
+* contributes zero text units (non-printing) or two (supplementary plane);
+* `charMap` anchors encode exactly those deviations.
+*
+* Both come from the fork's batched extension calls, which share one
+* encoding authority (`FX_UTF16Encode`) so text and map can never
+* disagree:
+*
+*   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+*     characters arrive as surrogate pairs instead of being silently
+*     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+*     upper-bound buffer (2 units per character + NUL), so no measure
+*     round-trip.
+*   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+*     anchors is the common (identity) page and skips the fill call.
 */
 var PageTextReader = class {
 	constructor(runtime, session) {
@@ -7032,7 +7407,7 @@ var PageTextReader = class {
 	}
 	read(pageObjectNumber, signal) {
 		throwIfAborted(signal);
-		const { fn, mem } = this.runtime;
+		const { fn } = this.runtime;
 		const pool = this.session.pagePool();
 		const pagePtr = pool.acquire(pageObjectNumber);
 		try {
@@ -7041,10 +7416,18 @@ var PageTextReader = class {
 			if (!textPagePtr) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `FPDFText_LoadPage returned null for page object ${pageObjectNumber}`);
 			try {
 				throwIfAborted(signal);
-				const charCount = fn.FPDFText_CountChars(textPagePtr);
-				return {
-					text: readPageText(fn, mem, textPagePtr, charCount),
-					charCount: Math.max(charCount, 0)
+				const charCount = Math.max(fn.FPDFText_CountChars(textPagePtr), 0);
+				const text = readTextFull(this.runtime, textPagePtr, charCount);
+				const charMap = readCharMap(this.runtime, textPagePtr, pageObjectNumber);
+				const violation = (0, _embedpdf_engine_core_runtime.charMapViolation)(charCount, text.length, charMap);
+				if (violation !== null) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `char map invariant violated for page object ${pageObjectNumber}: ${violation}`);
+				return charMap.length > 0 ? {
+					text,
+					charCount,
+					charMap
+				} : {
+					text,
+					charCount
 				};
 			} finally {
 				fn.FPDFText_ClosePage(textPagePtr);
@@ -7054,21 +7437,65 @@ var PageTextReader = class {
 		}
 	}
 };
-function readPageText(fn, mem, textPagePtr, charCount) {
+/**
+* Full-fidelity page text in one call: the buffer is sized at the maximum
+* possible expansion (every character a surrogate pair, plus the NUL), so
+* the returned requirement always fits and the measure round-trip is
+* skipped. The return value counts UTF-16 units INCLUDING the terminator.
+*/
+function readTextFull(runtime, textPagePtr, charCount) {
 	if (charCount <= 0) return "";
-	return withScratch(mem, (charCount + 1) * 2, (buf) => {
-		if (fn.FPDFText_GetText(textPagePtr, 0, charCount, buf) <= 0) return "";
-		return mem.readU16String(buf);
+	const { fn, mem } = runtime;
+	const bufUnits = charCount * 2 + 1;
+	return withScratch(mem, bufUnits * 2, (buf) => {
+		const written = fn.EPDFText_GetTextFull(textPagePtr, buf, bufUnits);
+		if (written <= 1) return "";
+		return decodeUtf16Le(mem.readBytes(buf, (written - 1) * 2));
+	});
+}
+function decodeUtf16Le(bytes) {
+	const units = new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
+	let out = "";
+	const CHUNK = 8192;
+	for (let i = 0; i < units.length; i += CHUNK) out += String.fromCharCode(...units.subarray(i, Math.min(i + CHUNK, units.length)));
+	return out;
+}
+/** Anchor struct layout: two little-endian i32s (see EPDF_CHAR_MAP_ANCHOR). */
+const ANCHOR_BYTES = 8;
+function readCharMap(runtime, textPagePtr, pageObjectNumber) {
+	const { fn, mem } = runtime;
+	const count = fn.EPDFText_GetCharToTextMap(textPagePtr, _embedpdf_engine_runtime.NULL_PTR, 0);
+	if (count < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `EPDFText_GetCharToTextMap failed for page object ${pageObjectNumber}`);
+	if (count === 0) return [];
+	return withScratch(mem, count * ANCHOR_BYTES, (buf) => {
+		fn.EPDFText_GetCharToTextMap(textPagePtr, buf, count);
+		const bytes = mem.readBytes(buf, count * ANCHOR_BYTES);
+		const words = new Int32Array(bytes.buffer, bytes.byteOffset, count * 2);
+		const anchors = new Array(count);
+		for (let i = 0; i < count; i++) anchors[i] = [words[i * 2], words[i * 2 + 1]];
+		return anchors;
 	});
 }
 //#endregion
 //#region src/features/geometry/PageGeometryReader.ts
 /**
+* Mid-object orientation drift that forces a run split (~0.5°). Real content
+* keeps one char matrix per text object; this guards the exotic cases so a
+* run's `rotation` is always representative of every glyph in it.
+*/
+const ROTATION_SPLIT_TOLERANCE = .0087;
+/**
 * Geometry-only text layout reader.
 *
 * Emits geometry in PDF user space (y-up edges) — the canonical engine
 * geometry. The viewer converts to content/view space via the page geometry
 * matrix; this reader applies NO Y-flip or device transform.
+*
+* One `EPDFText_GetCharGeometry` call per glyph supplies boxes, oriented
+* cells, and flags together; `buildRunsFromRawGlyphs` then groups glyphs
+* into the upright/rotated run union. Upright runs are byte-identical to the
+* pre-orientation reader (quads the native layer offers are deliberately
+* dropped — the dominant case never pays for orientation).
 */
 var PageGeometryReader = class {
 	constructor(runtime, session) {
@@ -7077,7 +7504,7 @@ var PageGeometryReader = class {
 	}
 	read(pageObjectNumber, signal) {
 		throwIfAborted(signal);
-		const { fn } = this.runtime;
+		const { fn, mem } = this.runtime;
 		const pool = this.session.pagePool();
 		const pagePtr = pool.acquire(pageObjectNumber);
 		try {
@@ -7087,12 +7514,27 @@ var PageGeometryReader = class {
 			try {
 				throwIfAborted(signal);
 				const glyphCount = Math.max(fn.FPDFText_CountChars(textPagePtr), 0);
-				const glyphs = [];
-				for (let i = 0; i < glyphCount; i++) {
-					throwIfAborted(signal);
-					glyphs.push(this.readGlyphInfo(textPagePtr, i));
+				const records = [];
+				const geometryPtr = mem.alloc(EPDF_CHAR_GEOMETRY_LAYOUT.bytes);
+				try {
+					let prevObjectKey = null;
+					for (let i = 0; i < glyphCount; i++) {
+						throwIfAborted(signal);
+						const objectKey = fn.FPDFText_GetTextObject(textPagePtr, i);
+						const record = {
+							objectKey,
+							...this.readGlyphRaw(textPagePtr, i, geometryPtr)
+						};
+						if (objectKey !== prevObjectKey) {
+							record.fontSize = fn.FPDFText_GetFontSize(textPagePtr, i);
+							prevObjectKey = objectKey;
+						}
+						records.push(record);
+					}
+				} finally {
+					mem.free(geometryPtr);
 				}
-				return { runs: this.buildRunsFromGlyphs(glyphs, textPagePtr) };
+				return { runs: buildRunsFromRawGlyphs(records) };
 			} finally {
 				fn.FPDFText_ClosePage(textPagePtr);
 			}
@@ -7100,96 +7542,206 @@ var PageGeometryReader = class {
 			pool.release(pageObjectNumber);
 		}
 	}
-	buildRunsFromGlyphs(glyphs, textPagePtr) {
-		const { fn } = this.runtime;
-		const runs = [];
-		let current = null;
-		let curObjPtr = null;
-		let bounds = null;
-		for (let i = 0; i < glyphs.length; i++) {
-			const glyph = glyphs[i];
-			const objPtr = fn.FPDFText_GetTextObject(textPagePtr, i);
-			if (objPtr !== curObjPtr) {
-				curObjPtr = objPtr;
-				current = {
-					rect: { ...glyph.looseBox },
-					charStart: i,
-					glyphs: [],
-					fontSize: fn.FPDFText_GetFontSize(textPagePtr, i)
-				};
-				bounds = { ...glyph.looseBox };
-				runs.push(current);
+	readGlyphRaw(textPagePtr, charIndex, geometryPtr) {
+		const { fn, mem } = this.runtime;
+		if (!fn.EPDFText_GetCharGeometry(textPagePtr, charIndex, geometryPtr)) return emptyRawGlyph();
+		const { offsets, flags: bits } = EPDF_CHAR_GEOMETRY_LAYOUT;
+		const native = readI32(mem, geometryPtr, offsets.flags) >>> 0;
+		if (native & bits.empty) return emptyRawGlyph();
+		const upright = Boolean(native & bits.upright);
+		const raw = {
+			flags: native & bits.space ? 1 : 0,
+			looseBox: (0, _embedpdf_engine_core_runtime.normalizePdfRect)(readRectF(mem, geometryPtr, offsets.looseBox)),
+			upright,
+			rotation: 0,
+			ascentFlip: false
+		};
+		if (native & bits.hasTightBox) raw.tightBox = (0, _embedpdf_engine_core_runtime.normalizePdfRect)(readRectF(mem, geometryPtr, offsets.tightBox));
+		if (native & bits.hasLooseQuad) {
+			raw.looseQuad = readQuad(mem, geometryPtr, offsets.looseQuad);
+			if (native & bits.hasTightQuad) raw.tightQuad = readQuad(mem, geometryPtr, offsets.tightQuad);
+			if (!upright) {
+				const a = readF32(mem, geometryPtr, offsets.matrix);
+				const b = readF32(mem, geometryPtr, offsets.matrix + 4);
+				const c = readF32(mem, geometryPtr, offsets.matrix + 8);
+				const d = readF32(mem, geometryPtr, offsets.matrix + 12);
+				raw.rotation = Math.atan2(b, a);
+				raw.ascentFlip = a * d - b * c < 0;
 			}
-			current.glyphs.push(toSlimGlyph(glyph));
-			if (glyph.isEmpty) continue;
-			bounds.left = Math.min(bounds.left, glyph.looseBox.left);
-			bounds.bottom = Math.min(bounds.bottom, glyph.looseBox.bottom);
-			bounds.right = Math.max(bounds.right, glyph.looseBox.right);
-			bounds.top = Math.max(bounds.top, glyph.looseBox.top);
-			current.rect = { ...bounds };
 		}
-		return runs;
+		return raw;
 	}
-	readGlyphInfo(textPagePtr, charIndex) {
-		const { fn, mem } = this.runtime;
-		const rectPtr = mem.alloc(16);
-		const tLeftPtr = mem.alloc(8);
-		const tRightPtr = mem.alloc(8);
-		const tBottomPtr = mem.alloc(8);
-		const tTopPtr = mem.alloc(8);
-		const ptrs = [
-			rectPtr,
-			tLeftPtr,
-			tRightPtr,
-			tBottomPtr,
-			tTopPtr
-		];
-		try {
-			if (!fn.FPDFText_GetLooseCharBox(textPagePtr, charIndex, rectPtr)) return emptyGlyph();
-			const left = Number(mem.peek(rectPtr, "f32", 0));
-			const top = Number(mem.peek(rectPtr, "f32", 4));
-			const right = Number(mem.peek(rectPtr, "f32", 8));
-			const bottom = Number(mem.peek(rectPtr, "f32", 12));
-			if (left === right || top === bottom) return emptyGlyph();
-			const glyph = { looseBox: (0, _embedpdf_engine_core_runtime.normalizePdfRect)({
-				left,
-				bottom,
-				right,
-				top
-			}) };
-			if (fn.FPDFText_GetCharBox(textPagePtr, charIndex, tLeftPtr, tRightPtr, tBottomPtr, tTopPtr)) {
-				const tLeft = Number(mem.peek(tLeftPtr, "f64"));
-				const tRight = Number(mem.peek(tRightPtr, "f64"));
-				glyph.tightBox = (0, _embedpdf_engine_core_runtime.normalizePdfRect)({
-					left: tLeft,
-					bottom: Number(mem.peek(tBottomPtr, "f64")),
-					right: tRight,
-					top: Number(mem.peek(tTopPtr, "f64"))
-				});
-			}
-			glyph.isSpace = fn.FPDFText_GetUnicode(textPagePtr, charIndex) === 32;
-			return glyph;
-		} finally {
-			for (const ptr of ptrs) mem.free(ptr);
+};
+/**
+* Group per-glyph records into the run union. Pure — exported for tests.
+*
+* Runs split on text-object change (the legacy rule) and on orientation
+* change between classifiable glyphs (θ drift / mixed orientation). A run's
+* variant is decided by its FIRST classifiable glyph:
+*   - empty glyphs never classify (they adopt the run's variant);
+*   - real glyphs WITHOUT an oriented cell (singular matrix, synthesized
+*     /ActualText pieces) classify as upright — box-only data degrades to
+*     exactly the legacy behavior;
+*   - real glyphs with a non-upright matrix classify as rotated.
+* Runs that never see a classifiable glyph emit as upright (degenerate,
+* legacy behavior).
+*/
+function buildRunsFromRawGlyphs(records) {
+	const runs = [];
+	let buffer = [];
+	let charStart = 0;
+	let fontSize;
+	let objectKey = null;
+	let cls;
+	const flush = (nextStart) => {
+		if (buffer.length > 0) {
+			runs.push(materializeRun(buffer, charStart, fontSize, cls));
+			buffer = [];
+			cls = void 0;
+		}
+		charStart = nextStart;
+	};
+	for (let i = 0; i < records.length; i++) {
+		const record = records[i];
+		if (record.objectKey !== objectKey) {
+			flush(i);
+			objectKey = record.objectKey;
+			fontSize = record.fontSize;
+		}
+		const recordClass = classOf(record);
+		if (recordClass) {
+			if (cls && !sameClass(cls, recordClass)) flush(i);
+			if (!cls) cls = recordClass;
 		}
+		buffer.push(record);
 	}
+	flush(records.length);
+	return runs;
+}
+function classOf(record) {
+	if (record.flags & 2) return void 0;
+	if (record.looseQuad && !record.upright) return {
+		upright: false,
+		rotation: record.rotation,
+		ascentFlip: record.ascentFlip
+	};
+	return { upright: true };
+}
+function sameClass(a, b) {
+	if (a.upright || b.upright) return a.upright === b.upright;
+	if (a.ascentFlip !== b.ascentFlip) return false;
+	const delta = a.rotation - b.rotation;
+	return Math.abs(Math.atan2(Math.sin(delta), Math.cos(delta))) <= ROTATION_SPLIT_TOLERANCE;
+}
+function materializeRun(buffer, charStart, fontSize, cls) {
+	if (cls && !cls.upright) {
+		const glyphs = buffer.map((g) => g.looseQuad ? {
+			looseQuad: g.looseQuad,
+			flags: g.flags,
+			...g.tightQuad ? { tightQuad: g.tightQuad } : {}
+		} : {
+			looseQuad: zeroQuad(),
+			flags: g.flags
+		});
+		return {
+			rect: runBounds(buffer, (g) => g.looseQuad ? (0, _embedpdf_engine_core_runtime.pdfQuadBounds)(g.looseQuad) : ZERO_RECT),
+			charStart,
+			glyphs,
+			rotation: cls.rotation,
+			ascentFlip: cls.ascentFlip,
+			...fontSize !== void 0 ? { fontSize } : {}
+		};
+	}
+	const glyphs = buffer.map((g) => ({
+		looseBox: g.looseBox,
+		flags: g.flags,
+		...g.tightBox ? { tightBox: g.tightBox } : {}
+	}));
+	return {
+		rect: runBounds(buffer, (g) => g.looseBox),
+		charStart,
+		glyphs,
+		...fontSize !== void 0 ? { fontSize } : {}
+	};
+}
+/** Legacy run-rect algorithm: seed from the first glyph, expand on non-empty. */
+function runBounds(buffer, boundsOf) {
+	const seed = boundsOf(buffer[0]);
+	const rect = {
+		left: seed.left,
+		bottom: seed.bottom,
+		right: seed.right,
+		top: seed.top
+	};
+	for (const g of buffer) {
+		if (g.flags & 2) continue;
+		const b = boundsOf(g);
+		rect.left = Math.min(rect.left, b.left);
+		rect.bottom = Math.min(rect.bottom, b.bottom);
+		rect.right = Math.max(rect.right, b.right);
+		rect.top = Math.max(rect.top, b.top);
+	}
+	return rect;
+}
+const ZERO_RECT = {
+	left: 0,
+	bottom: 0,
+	right: 0,
+	top: 0
 };
-function emptyGlyph() {
+function zeroQuad() {
+	return {
+		p1: {
+			x: 0,
+			y: 0
+		},
+		p2: {
+			x: 0,
+			y: 0
+		},
+		p3: {
+			x: 0,
+			y: 0
+		},
+		p4: {
+			x: 0,
+			y: 0
+		}
+	};
+}
+function emptyRawGlyph() {
 	return {
+		flags: 2,
 		looseBox: {
 			left: 0,
 			bottom: 0,
 			right: 0,
 			top: 0
 		},
-		isEmpty: true
+		upright: true,
+		rotation: 0,
+		ascentFlip: false
 	};
 }
-function toSlimGlyph(glyph) {
+function readQuad(mem, ptr, byteOffset) {
+	const f = (offset) => readF32(mem, ptr, byteOffset + offset);
 	return {
-		looseBox: glyph.looseBox,
-		flags: glyph.isEmpty ? 2 : glyph.isSpace ? 1 : 0,
-		...glyph.tightBox ? { tightBox: glyph.tightBox } : {}
+		p1: {
+			x: f(0),
+			y: f(4)
+		},
+		p2: {
+			x: f(8),
+			y: f(12)
+		},
+		p3: {
+			x: f(16),
+			y: f(20)
+		},
+		p4: {
+			x: f(24),
+			y: f(28)
+		}
 	};
 }
 //#endregion
@@ -7829,13 +8381,13 @@ var FormReader = class {
 	snapshot(signal) {
 		throwIfAborted(signal);
 		const model = acquireFormModel(this.runtime, this.session);
-		return readFormSnapshot(this.runtime, model);
+		return readFormSnapshot(this.runtime, model, this.session.requireDocPtr());
 	}
 	field(ref, signal) {
 		throwIfAborted(signal);
 		const model = acquireFormModel(this.runtime, this.session);
 		const { fieldIndex } = resolveFieldRef(this.runtime, model, ref);
-		return readFieldAt(this.runtime, model, fieldIndex);
+		return readFieldAt(this.runtime, model, fieldIndex, this.session.requireDocPtr());
 	}
 	/**
 	* Serialize form data. Exports read the reconciled view (recovered
@@ -7991,7 +8543,7 @@ var FormMutator = class {
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
 		this.assertWritable(resolved.fieldObjectNumber);
-		const before = readFieldAt(this.runtime, model, resolved.fieldIndex);
+		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);
 		return this.readBack(resolved.fieldObjectNumber, changed);
@@ -8027,7 +8579,7 @@ var FormMutator = class {
 		const fresh = acquireFormModel(this.runtime, this.session);
 		return {
 			...counters,
-			snapshot: readFormSnapshot(this.runtime, fresh),
+			snapshot: readFormSnapshot(this.runtime, fresh, this.session.requireDocPtr()),
 			meta: EMPTY_META$1
 		};
 	}
@@ -8100,7 +8652,7 @@ var FormMutator = class {
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
 		this.assertWritable(resolved.fieldObjectNumber);
-		const before = readFieldAt(this.runtime, model, resolved.fieldIndex);
+		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;
 		if (patch.name !== void 0) this.applyWideSetter(fn.EPDFForm_SetFieldName, fieldObjectNumber, patch.name, `cannot rename to "${patch.name}" (sibling conflict or invalid)`);
@@ -8131,7 +8683,7 @@ var FormMutator = class {
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
 		this.assertWritable(resolved.fieldObjectNumber);
-		const before = readFieldAt(this.runtime, model, resolved.fieldIndex);
+		const before = readFieldAt(this.runtime, model, resolved.fieldIndex, this.session.requireDocPtr());
 		if (!withScratchN(mem, [256 * 4, 4], ([buf, countPtr]) => {
 			mem.poke(countPtr, "i32", 0);
 			return fn.EPDFForm_DeleteField(this.session.requireDocPtr(), resolved.fieldObjectNumber, buf, 256, countPtr);
@@ -8151,7 +8703,7 @@ var FormMutator = class {
 		const model = acquireFormModel(this.runtime, this.session);
 		const resolved = resolveFieldRef(this.runtime, model, ref);
 		this.assertWritable(resolved.fieldObjectNumber);
-		const before = readFieldAt(this.runtime, model, resolved.fieldIndex);
+		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" : "") : "";
 		if (toggle && (!state || state === "Off")) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "attaching to a radio group needs a non-\"Off\" onState");
@@ -8197,7 +8749,7 @@ var FormMutator = class {
 		const fresh = acquireFormModel(this.runtime, this.session);
 		const fieldIndex = this.runtime.fn.EPDFForm_GetFieldIndexByObjNum(fresh, fieldObjectNumber);
 		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);
+		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");
@@ -8243,7 +8795,7 @@ var FormMutator = class {
 		const fresh = acquireFormModel(this.runtime, this.session);
 		const fieldIndex = this.runtime.fn.EPDFForm_GetFieldIndexByObjNum(fresh, fieldObjectNumber);
 		if (fieldIndex < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "form field vanished after write");
-		const field = readFieldAt(this.runtime, fresh, fieldIndex);
+		const field = readFieldAt(this.runtime, fresh, fieldIndex, this.session.requireDocPtr());
 		const changedSet = new Set(changedObjNums);
 		return {
 			field,
@@ -8389,7 +8941,7 @@ var FormsEffectsApplier = class {
 			if (refs.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "reset effect requires at least one field");
 			const model = acquireFormModel(this.runtime, this.session);
 			const resolved = refs.map((ref) => this.resolve(model, ref));
-			const fields = resolved.map(({ fieldIndex }) => readFieldAt(this.runtime, model, fieldIndex, actionBudget));
+			const fields = resolved.map(({ fieldIndex }) => readFieldAt(this.runtime, model, fieldIndex, this.session.requireDocPtr(), actionBudget));
 			validateEffect(effect, fields);
 			return {
 				effect,
@@ -8414,7 +8966,7 @@ var FormsEffectsApplier = class {
 		const model = acquireFormModel(this.runtime, this.session);
 		const index = this.runtime.fn.EPDFForm_GetFieldIndexByObjNum(model, fieldObjectNumber);
 		if (index < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidReference, "form field disappeared");
-		return readFieldAt(this.runtime, model, index, actionBudget);
+		return readFieldAt(this.runtime, model, index, this.session.requireDocPtr(), actionBudget);
 	}
 	readFieldsBestEffort(fieldObjectNumbers, actionBudget) {
 		const fields = [];
@@ -8562,7 +9114,7 @@ function emptyResult(index, status) {
 //#endregion
 //#region src/features/search/internal/pageCorpusCache.ts
 /**
-* Per-session, per-page search corpus: the page's extracted text plus its
+* Per-session, per-page search corpus: the page's text snapshot plus its
 * DEFAULT fold (the one literal queries with default options search).
 * This is the local engine's in-memory equivalent of the server's corpus
 * artifacts — same fold version, same shape, built lazily on first search
@@ -8587,19 +9139,20 @@ function acquirePageCorpus(runtime, session, pageObjectNumber, signal) {
 		cache.set(session, pages);
 	}
 	const hit = pages.get(pageObjectNumber);
-	if (hit && hit.seq === seq) return hit.folded;
-	const text = new PageTextReader(runtime, session).read(pageObjectNumber, signal).text;
-	const folded = (0, _embedpdf_engine_core_runtime.foldText)(text);
-	pages.delete(pageObjectNumber);
-	pages.set(pageObjectNumber, {
+	if (hit && hit.seq === seq) return hit;
+	const snapshot = new PageTextReader(runtime, session).read(pageObjectNumber, signal);
+	const entry = {
 		seq,
-		folded
-	});
+		folded: (0, _embedpdf_engine_core_runtime.foldText)(snapshot.text),
+		snapshot
+	};
+	pages.delete(pageObjectNumber);
+	pages.set(pageObjectNumber, entry);
 	if (pages.size > MAX_CACHED_PAGES) {
 		const oldest = pages.keys().next().value;
 		if (oldest !== void 0) pages.delete(oldest);
 	}
-	return folded;
+	return entry;
 }
 //#endregion
 //#region src/features/search/internal/searchCursor.ts
@@ -8708,19 +9261,23 @@ var SearchReader = class {
 			throwIfAborted(signal);
 			const pon = order[scanned].pageObjectNumber;
 			const corpus = acquirePageCorpus(this.runtime, this.session, pon, signal);
+			const text = corpus.snapshot.text;
 			let ranges;
-			if (query.regex) ranges = (0, _embedpdf_engine_core_runtime.matchRegex)(corpus.original, query);
-			else if (query.matchCase || query.matchDiacritics) ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)((0, _embedpdf_engine_core_runtime.foldText)(corpus.original, (0, _embedpdf_engine_core_runtime.foldOptionsFor)(query)), query);
-			else ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)(corpus, query);
+			if (query.regex) ranges = (0, _embedpdf_engine_core_runtime.matchRegex)(text, query);
+			else if (query.matchCase || query.matchDiacritics) ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)((0, _embedpdf_engine_core_runtime.foldText)(text, (0, _embedpdf_engine_core_runtime.foldOptionsFor)(query)), query);
+			else ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)(corpus.folded, query);
 			if (ranges.length > 0) {
-				const geometry = new PageGeometryReader(this.runtime, this.session).read(pon, signal);
-				for (const range of ranges) matches.push({
-					pageObjectNumber: pon,
-					charStart: range.start,
-					charCount: range.length,
-					rects: (0, _embedpdf_engine_core_runtime.searchRectsForRange)(geometry, range.start, range.length),
-					...mode === "full" ? { snippet: (0, _embedpdf_engine_core_runtime.buildSnippet)(corpus.original, range) } : {}
-				});
+				const layout = (0, _embedpdf_engine_core_runtime.buildPageTextLayout)(new PageGeometryReader(this.runtime, this.session).read(pon, signal));
+				for (const range of ranges) {
+					const chars = (0, _embedpdf_engine_core_runtime.charRangeForTextOffsets)(corpus.snapshot, range.start, range.start + range.length);
+					matches.push({
+						pageObjectNumber: pon,
+						charStart: chars.start,
+						charCount: chars.end - chars.start,
+						segments: (0, _embedpdf_engine_core_runtime.textSegmentsForRange)(layout, chars.start, chars.end - chars.start),
+						...mode === "full" ? { snippet: (0, _embedpdf_engine_core_runtime.buildSnippet)(text, range) } : {}
+					});
+				}
 			}
 			scanned++;
 			pagesThisSlice++;
@@ -8776,22 +9333,26 @@ var DocumentActionsReader = class {
 			} finally {
 				fn.FPDFDoc_CloseJavaScriptAction(namedPtr);
 			}
-			const action = requireAction(readActionModel(fn, mem, fn.EPDFDoc_GetNamedJavaScriptActionModel(docPtr, index), budget), "name-tree script", index);
+			budget.reservePayloadBytes(name.length);
+			const action = requireAction(readActionModel(fn, mem, docPtr, fn.EPDFDoc_GetNamedJavaScriptActionModel(docPtr, index), budget), "name-tree script", index);
 			nameTreeScripts.push({
 				name,
 				action
 			});
 		}
-		const openAction = readActionModel(fn, mem, fn.EPDFDoc_GetOpenActionModel(docPtr), budget);
+		const openAction = readActionModel(fn, mem, docPtr, fn.EPDFDoc_GetOpenActionModel(docPtr), budget);
+		const openDestPtr = openAction ? _embedpdf_engine_runtime.NULL_PTR : fn.EPDFDoc_GetOpenActionDest(docPtr);
+		const openDestination = openDestPtr !== _embedpdf_engine_runtime.NULL_PTR ? readDestination(fn, mem, docPtr, openDestPtr) : null;
 		const additional = {};
 		for (const [key, event] of DOCUMENT_ACTION_EVENTS) {
 			throwIfAborted(signal);
-			const action = readActionModel(fn, mem, fn.EPDFDoc_GetAdditionalActionModel(docPtr, event), budget);
+			const action = readActionModel(fn, mem, docPtr, fn.EPDFDoc_GetAdditionalActionModel(docPtr, event), budget);
 			if (action) additional[key] = action;
 		}
 		return {
 			nameTreeScripts,
 			openAction,
+			openDestination,
 			...additional
 		};
 	}
@@ -9001,9 +9562,10 @@ function validatePatchValue(key, value) {
 * worker wire shape from @embedpdf/engine-core.
 */
 var WorkerHost = class {
-	constructor(runtime, post) {
+	constructor(runtime, post, options = {}) {
 		this.runtime = runtime;
 		this.post = post;
+		this.options = options;
 		_defineProperty(this, "sessions", /* @__PURE__ */ new Map());
 		_defineProperty(this, "baseDocuments", void 0);
 		_defineProperty(this, "aborts", /* @__PURE__ */ new Map());
@@ -9029,6 +9591,10 @@ var WorkerHost = class {
 			this.aborts.get(msg.jobId)?.abort();
 			return;
 		}
+		if (msg.kind === "pages.renderEncoded" || msg.kind === "document.renderPageFileEncoded" || msg.kind === "annotations.renderAppearancesEncoded") {
+			this.receiveEncoded(msg);
+			return;
+		}
 		const ctrl = new AbortController();
 		this.aborts.set(msg.jobId, ctrl);
 		let resultPack;
@@ -9132,6 +9698,9 @@ var WorkerHost = class {
 				case "pages.insert":
 					resultPack = this.handlePagesInsert(msg, ctrl.signal);
 					break;
+				case "pages.insertBlank":
+					resultPack = this.handlePagesInsertBlank(msg, ctrl.signal);
+					break;
 				case "attachments.list":
 					resultPack = this.handleAttachmentsList(msg, ctrl.signal);
 					break;
@@ -9424,6 +9993,17 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handlePagesInsertBlank(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesInserter(this.runtime, session).insertBlank({
+			size: req.size,
+			count: req.count
+		}, req.destIndex, signal);
+		return this.finishMutation(session, {
+			tag: "pages.insertBlank",
+			result
+		}, req.artifactPath);
+	}
 	handleAttachmentsList(req, signal) {
 		const session = this.requireSession(req);
 		return (0, _embedpdf_engine_core_runtime.wirePack)({
@@ -9516,6 +10096,105 @@ var WorkerHost = class {
 			raster
 		}, [raster.data]);
 	}
+	async receiveEncoded(msg) {
+		if (!this.options.imageEncoder) {
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: (0, _embedpdf_engine_core_runtime.serializeError)(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "this engine has no image encoder (the *.renderEncoded kinds are cloud-server surface)"))
+			}, _embedpdf_engine_core_runtime.EMPTY_TRANSFER));
+			return;
+		}
+		const ctrl = new AbortController();
+		this.aborts.set(msg.jobId, ctrl);
+		try {
+			let resultPack;
+			switch (msg.kind) {
+				case "pages.renderEncoded":
+					resultPack = await this.handlePagesRenderEncoded(msg, ctrl.signal);
+					break;
+				case "document.renderPageFileEncoded":
+					resultPack = await this.handleDocumentRenderPageFileEncoded(msg, ctrl.signal);
+					break;
+				case "annotations.renderAppearancesEncoded":
+					resultPack = await this.handleAnnotationsRenderAppearancesEncoded(msg, ctrl.signal);
+					break;
+			}
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "resolve",
+				jobId: msg.jobId,
+				result: resultPack.payload
+			}, resultPack.transfer));
+		} catch (err) {
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: (0, _embedpdf_engine_core_runtime.serializeError)(err)
+			}, _embedpdf_engine_core_runtime.EMPTY_TRANSFER));
+		} finally {
+			this.aborts.delete(msg.jobId);
+		}
+	}
+	async encodeRaster(raster, encode, signal) {
+		const encoder = this.options.imageEncoder;
+		if (!encoder) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "this engine has no image encoder (the *.renderEncoded kinds are cloud-server surface)");
+		const { bytes, contentType } = await encoder.encode(raster, encode);
+		if (signal.aborted) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Aborted, "aborted during image encode");
+		return {
+			contentType,
+			width: raster.width,
+			height: raster.height,
+			bytes
+		};
+	}
+	async handlePagesRenderEncoded(req, signal) {
+		const inner = this.handlePagesRender({
+			...req,
+			kind: "pages.render"
+		}, signal);
+		if (inner.payload.tag !== "pages.render") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "pages.renderEncoded",
+			image
+		}, [image.bytes.buffer]);
+	}
+	async handleDocumentRenderPageFileEncoded(req, signal) {
+		const inner = this.handleDocumentRenderPageFile({
+			...req,
+			kind: "document.renderPageFile"
+		}, signal);
+		if (inner.payload.tag !== "document.renderPageFile") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "document.renderPageFileEncoded",
+			pageObjectNumber: inner.payload.pageObjectNumber,
+			pageCount: inner.payload.pageCount,
+			image
+		}, [image.bytes.buffer]);
+	}
+	async handleAnnotationsRenderAppearancesEncoded(req, signal) {
+		const inner = this.handleAnnotationsRenderAppearances({
+			...req,
+			kind: "annotations.renderAppearances"
+		}, signal);
+		if (inner.payload.tag !== "annotations.renderAppearances") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const { pageState, appearances } = inner.payload.result;
+		const encoded = [];
+		for (const a of appearances) encoded.push({
+			ref: a.ref,
+			mode: a.mode,
+			rect: a.rect,
+			image: await this.encodeRaster(a.raster, req.encode, signal)
+		});
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "annotations.renderAppearancesEncoded",
+			result: {
+				pageState,
+				appearances: encoded
+			}
+		}, encoded.map((e) => e.image.bytes.buffer));
+	}
 	handleDocumentSaveBuffer(req) {
 		const session = this.requireSession(req);
 		const saved = new DocumentSaver(this.runtime, session).saveStandaloneToBuffer(req.mode);
@@ -9860,6 +10539,7 @@ exports.DocumentActionsReader = DocumentActionsReader;
 exports.DocumentPagesMutator = PagesMutator;
 exports.DocumentSaver = DocumentSaver;
 exports.DocumentSession = DocumentSession;
+exports.EPDF_CHAR_GEOMETRY_LAYOUT = EPDF_CHAR_GEOMETRY_LAYOUT;
 exports.EventHub = EventHub;
 exports.FontRegistrar = FontRegistrar;
 exports.FormMutator = FormMutator;
@@ -9885,6 +10565,7 @@ exports.SearchReader = SearchReader;
 exports.SecurityReader = SecurityReader;
 exports.SessionEventPublisher = SessionEventPublisher;
 exports.WorkerHost = WorkerHost;
+exports.buildRunsFromRawGlyphs = buildRunsFromRawGlyphs;
 exports.computeMutationImpact = computeMutationImpact;
 exports.destroyLibrary = destroyLibrary;
 exports.disposeFormModel = disposeFormModel;