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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AbortError, EMPTY_TRANSFER, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, UNKNOWN_WEAK_ANNOTATION_STATE, appearanceImpactOf, buildSnippet, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, revisionTokensEqual, searchRectsForRange, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
+import { AbortError, EMPTY_TRANSFER, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PAGE_INSERT_BLANK_MAX_COUNT, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, UNKNOWN_WEAK_ANNOTATION_STATE, appearanceImpactOf, buildPageTextLayout, buildSnippet, charMapViolation, charRangeForTextOffsets, decodeSubmitFormFlags, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, pdfQuadBounds, revisionTokensEqual, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, textSegmentsForRange, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
 import { NULL_PTR } from "@embedpdf/engine-runtime";
 //#region src/runtime/lifecycle/bootstrap.ts
 const initialized = /* @__PURE__ */ new WeakSet();
@@ -225,8 +225,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) {
@@ -1163,13 +1165,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`. */
@@ -1188,11 +1211,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",
@@ -1220,22 +1375,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;
@@ -1246,11 +1399,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 EngineError(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 EngineError(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
 		} });
 	}
@@ -1258,8 +1423,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 === NULL_PTR) return null;
 	try {
 		const nodeCount = fn.EPDFAction_GetNodeCount(modelPtr);
@@ -1269,13 +1443,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(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,
@@ -1286,21 +1508,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 !== 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: 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);
@@ -1380,8 +1738,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;
@@ -1705,6 +2063,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 EngineError(EngineErrorCode.InvalidArg, `pages.insertBlank size must have positive finite dimensions, got ${size?.width}x${size?.height}`);
+		if (!Number.isInteger(count) || count < 1 || count > PAGE_INSERT_BLANK_MAX_COUNT) throw new EngineError(EngineErrorCode.InvalidArg, `pages.insertBlank count ${count} out of range [1, ${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 EngineError(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 EngineError(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
@@ -2153,6 +2547,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";
@@ -2187,13 +2624,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
@@ -2611,49 +3052,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 = {
@@ -2759,167 +3157,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 !== 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);
@@ -2930,43 +3228,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
@@ -3106,6 +3367,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 = {
@@ -3120,12 +3422,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
@@ -3431,7 +3737,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));
@@ -3439,7 +3745,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",
@@ -3538,12 +3844,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++) {
@@ -3579,7 +3885,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],
@@ -3589,7 +3895,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;
@@ -3835,18 +4141,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,
@@ -3856,6 +4163,7 @@ function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision
 		flags,
 		rect,
 		contents,
+		subject,
 		author,
 		created: createdRaw ? pdfDateToIso(createdRaw) : null,
 		modified: modifiedRaw ? pdfDateToIso(modifiedRaw) : null,
@@ -3869,7 +4177,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],
@@ -3885,7 +4193,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;
@@ -3916,7 +4224,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);
@@ -4130,19 +4438,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.
@@ -4241,13 +4561,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",
@@ -4362,7 +4684,9 @@ function setAnnotFlags(fn, annotPtr, partial) {
 	if (!fn.FPDFAnnot_SetFlags(annotPtr, next)) throw new EngineError(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) {
@@ -4372,12 +4696,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 EngineError(EngineErrorCode.Unknown, "FPDFAnnot_SetRect returned false");
+		if (!fn.EPDFAnnot_SetRect(annotPtr, buf)) throw new EngineError(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
@@ -4576,8 +4928,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
@@ -4588,13 +4940,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`.
@@ -4605,7 +4958,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);
 }
 /**
@@ -4616,7 +4970,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
@@ -4625,7 +4979,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
@@ -4642,22 +4996,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, 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
@@ -4823,32 +5162,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 EngineError(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));
@@ -4861,6 +5375,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));
@@ -4950,264 +5468,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 EngineError(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 EngineError(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 EngineError(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
@@ -5979,13 +6326,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 EngineError(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);
@@ -5993,6 +6345,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";
@@ -6970,17 +7324,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 EngineError(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 (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;
@@ -7006,23 +7378,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) {
@@ -7031,7 +7406,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 {
@@ -7040,10 +7415,18 @@ var PageTextReader = class {
 			if (!textPagePtr) throw new EngineError(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 = charMapViolation(charCount, text.length, charMap);
+				if (violation !== null) throw new EngineError(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);
@@ -7053,21 +7436,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, NULL_PTR, 0);
+	if (count < 0) throw new EngineError(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) {
@@ -7076,7 +7503,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 {
@@ -7086,12 +7513,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);
 			}
@@ -7099,96 +7541,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: normalizePdfRect(readRectF(mem, geometryPtr, offsets.looseBox)),
+			upright,
+			rotation: 0,
+			ascentFlip: false
+		};
+		if (native & bits.hasTightBox) raw.tightBox = 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: 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 = 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 ? 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
@@ -7828,13 +8380,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
@@ -7990,7 +8542,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 EngineError(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);
@@ -8026,7 +8578,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
 		};
 	}
@@ -8099,7 +8651,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 EngineError(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)`);
@@ -8130,7 +8682,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);
@@ -8150,7 +8702,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 EngineError(EngineErrorCode.InvalidArg, "attaching to a radio group needs a non-\"Off\" onState");
@@ -8196,7 +8748,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 EngineError(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 EngineError(EngineErrorCode.InvalidArg, "form field is stored as a direct object and cannot be written");
@@ -8242,7 +8794,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 EngineError(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,
@@ -8388,7 +8940,7 @@ var FormsEffectsApplier = class {
 			if (refs.length === 0) throw new EngineError(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,
@@ -8413,7 +8965,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 EngineError(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 = [];
@@ -8561,7 +9113,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
@@ -8586,19 +9138,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 = 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: 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
@@ -8707,19 +9260,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 = matchRegex(corpus.original, query);
-			else if (query.matchCase || query.matchDiacritics) ranges = matchLiteral(foldText(corpus.original, foldOptionsFor(query)), query);
-			else ranges = matchLiteral(corpus, query);
+			if (query.regex) ranges = matchRegex(text, query);
+			else if (query.matchCase || query.matchDiacritics) ranges = matchLiteral(foldText(text, foldOptionsFor(query)), query);
+			else ranges = 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: searchRectsForRange(geometry, range.start, range.length),
-					...mode === "full" ? { snippet: buildSnippet(corpus.original, range) } : {}
-				});
+				const layout = buildPageTextLayout(new PageGeometryReader(this.runtime, this.session).read(pon, signal));
+				for (const range of ranges) {
+					const chars = charRangeForTextOffsets(corpus.snapshot, range.start, range.start + range.length);
+					matches.push({
+						pageObjectNumber: pon,
+						charStart: chars.start,
+						charCount: chars.end - chars.start,
+						segments: textSegmentsForRange(layout, chars.start, chars.end - chars.start),
+						...mode === "full" ? { snippet: buildSnippet(text, range) } : {}
+					});
+				}
 			}
 			scanned++;
 			pagesThisSlice++;
@@ -8775,22 +9332,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 ? NULL_PTR : fn.EPDFDoc_GetOpenActionDest(docPtr);
+		const openDestination = openDestPtr !== 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
 		};
 	}
@@ -9000,9 +9561,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());
@@ -9028,6 +9590,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;
@@ -9131,6 +9697,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;
@@ -9423,6 +9992,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 wirePack({
@@ -9515,6 +10095,105 @@ var WorkerHost = class {
 			raster
 		}, [raster.data]);
 	}
+	async receiveEncoded(msg) {
+		if (!this.options.imageEncoder) {
+			this.post(wirePack({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: serializeError(new EngineError(EngineErrorCode.NotImplemented, "this engine has no image encoder (the *.renderEncoded kinds are cloud-server surface)"))
+			}, 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(wirePack({
+				kind: "resolve",
+				jobId: msg.jobId,
+				result: resultPack.payload
+			}, resultPack.transfer));
+		} catch (err) {
+			this.post(wirePack({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: serializeError(err)
+			}, EMPTY_TRANSFER));
+		} finally {
+			this.aborts.delete(msg.jobId);
+		}
+	}
+	async encodeRaster(raster, encode, signal) {
+		const encoder = this.options.imageEncoder;
+		if (!encoder) throw new EngineError(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 EngineError(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 EngineError(EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return 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 EngineError(EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return 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 EngineError(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 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);
@@ -9846,6 +10525,6 @@ function passwordRequiredProbe() {
 	};
 }
 //#endregion
-export { ALL_STANDARD_SECURITY_PERMISSIONS, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, LocalRevisionAuthority, MetadataMutator, MetadataReader, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, SearchReader, SecurityReader, SessionEventPublisher, WorkerHost, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
+export { ALL_STANDARD_SECURITY_PERMISSIONS, ActionReadBudgetTracker, AnnotationAppearanceReader, AnnotationMutator, AnnotationReader, AttachmentMutator, AttachmentReader, BaseDocumentRegistry, CloseStack, DocumentActionsReader, PagesMutator as DocumentPagesMutator, PagesMutator, DocumentSaver, DocumentSession, EPDF_CHAR_GEOMETRY_LAYOUT, EventHub, FontRegistrar, FormMutator, FormReader, FormsEffectsApplier, LocalRevisionAuthority, MetadataMutator, MetadataReader, PageGeometryReader, PagesReader as PageLayoutReader, PagesReader, PagePtrPool, PageRenderReader as PageRasterReader, PageRenderReader, PageTextReader, PagesExtractor, PagesFlattener, PagesInserter, RawAnnotationReader, RedactionApplier, SearchReader, SecurityReader, SessionEventPublisher, WorkerHost, buildRunsFromRawGlyphs, computeMutationImpact, destroyLibrary, disposeFormModel, ensureInitialized, formatPdfDate, generateUuid, hasAllStandardSecurityPermissions, normalizeU32, openFatMemoryDocument, openLayerDocument, pdfDateToIso, readActionModel, readAttachmentFileInfo, throwIfAborted, writeAttachmentFilePayload };
 
 //# sourceMappingURL=index.js.map