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

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, 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`. */
@@ -1705,6 +1728,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 +2212,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 +2289,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 +2717,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 = {
@@ -3106,6 +3169,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 +3224,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
@@ -3840,6 +3948,7 @@ function readAnnotationBase(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");
@@ -3856,6 +3965,7 @@ function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision
 		flags,
 		rect,
 		contents,
+		subject,
 		author,
 		created: createdRaw ? pdfDateToIso(createdRaw) : null,
 		modified: modifiedRaw ? pdfDateToIso(modifiedRaw) : null,
@@ -4130,19 +4240,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 +4363,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 +4486,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 +4498,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 +4730,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 +4742,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 +4760,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 +4772,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 +4781,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 +4798,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
@@ -4829,50 +4970,229 @@ function readAnnotationFromPtr(fn, mem, annotPtr, pageObjectNumber, index, revis
 	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);
-	setAnnotRect(fn, mem, annotPtr, draft.rect);
-	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));
-	if (draft.rectDifferences != null) setRectangleDifferences(fn, annotPtr, draft.rectDifferences);
-}
+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";
 /**
-* Apply a caret patch to an existing annotation. Only present fields are
-* touched.
+* 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 applyCaretPatch(fn, mem, annotPtr, patch) {
-	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
-	if (patch.rect !== void 0) setAnnotRect(fn, mem, annotPtr, patch.rect);
-	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));
-	if (patch.rectDifferences === null) clearRectangleDifferences(fn, annotPtr);
-	else if (patch.rectDifferences !== void 0) setRectangleDifferences(fn, annotPtr, patch.rectDifferences);
+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);
 }
 /**
-* Type-narrowing predicate used by the writer registry to pick the caret
-* writer for a draft/patch's `subtype`.
+* 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 isCaretSubtype(subtype) {
-	return subtype === "caret";
+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));
+	if (draft.rectDifferences != null) setRectangleDifferences(fn, annotPtr, draft.rectDifferences);
+}
+/**
+* Apply a caret patch to an existing annotation. Only present fields are
+* touched.
+*/
+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));
+	if (patch.rectDifferences === null) clearRectangleDifferences(fn, annotPtr);
+	else if (patch.rectDifferences !== void 0) setRectangleDifferences(fn, annotPtr, patch.rectDifferences);
+}
+/**
+* Type-narrowing predicate used by the writer registry to pick the caret
+* writer for a draft/patch's `subtype`.
+*/
+function isCaretSubtype(subtype) {
+	return subtype === "caret";
 }
 //#endregion
 //#region src/features/annotations/internal/write/writeFileAttachmentAnnotation.ts
@@ -5039,177 +5359,6 @@ function applyFilledStylePatch(fn, mem, annotPtr, patch) {
 	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`.
-*
-* 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/writeFreeTextAnnotation.ts
 /**
 * Default `/DA` colour for free text: black (border + default text). Unlike
@@ -5979,13 +6128,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 +6147,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 +7126,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 +7180,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.
+* `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.
 *
-* 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.
+* Both come from the fork's batched extension calls, which share one
+* encoding authority (`FX_UTF16Encode`) so text and map can never
+* disagree:
 *
-* 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.
+*   - `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 +7208,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 +7217,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 +7238,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 +7305,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 +7315,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 +7343,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
@@ -8561,7 +8915,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 +8940,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 +9062,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++;
@@ -9000,9 +9359,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 +9388,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 +9495,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 +9790,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 +9893,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 +10323,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