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

package/dist/index.cjs

@@ -226,8 +226,10 @@ var EventHub = class {
 		};
 	}
 	publish(event) {
-		const { serverId } = event.origin;
-		if (serverId !== null) this.serverId = this.serverId === null ? serverId : Math.max(this.serverId, serverId);
+		if ("origin" in event) {
+			const { serverId } = event.origin;
+			if (serverId !== null) this.serverId = this.serverId === null ? serverId : Math.max(this.serverId, serverId);
+		}
 		for (const listener of [...this.listeners]) try {
 			listener(event);
 		} catch (err) {
@@ -1164,13 +1166,34 @@ var MetadataMutator = class {
 };
 //#endregion
 //#region src/runtime/memory/structs.ts
+/** Generated from `EPDF_CHAR_GEOMETRY`; pinned by native static_asserts. */
+const EPDF_CHAR_GEOMETRY_LAYOUT = {
+	bytes: 124,
+	offsets: {
+		looseBox: 0,
+		tightBox: 16,
+		looseQuad: 32,
+		tightQuad: 64,
+		matrix: 96,
+		flags: 120
+	},
+	flags: {
+		hasTightBox: 1,
+		hasLooseQuad: 2,
+		hasTightQuad: 4,
+		upright: 8,
+		space: 16,
+		empty: 32,
+		synthesized: 64
+	}
+};
 /** Decode an `FS_RECTF` struct that a native call wrote into `ptr`. */
-function readRectF(mem, ptr) {
+function readRectF(mem, ptr, byteOffset = 0) {
 	return {
-		left: readF32(mem, ptr, 0),
-		top: readF32(mem, ptr, 4),
-		right: readF32(mem, ptr, 8),
-		bottom: readF32(mem, ptr, 12)
+		left: readF32(mem, ptr, byteOffset),
+		top: readF32(mem, ptr, byteOffset + 4),
+		right: readF32(mem, ptr, byteOffset + 8),
+		bottom: readF32(mem, ptr, byteOffset + 12)
 	};
 }
 /** Decode an `FS_SIZEF` struct that a native call wrote into `ptr`. */
@@ -1706,6 +1729,42 @@ var PagesInserter = class {
 			cache: null
 		};
 	}
+	/**
+	* Create `count` blank pages of `size` at `destIndex`. Same mutation
+	* contract as `insert`, but native creation (`FPDFPage_New`) instead of a
+	* deep copy: no source document, so none of the retain-until-close
+	* lifetime hazard above. Each page gets an empty content stream
+	* (`FPDFPage_GenerateContent`) so the saved PDF renders identically in
+	* third-party viewers.
+	*/
+	insertBlank(spec, destIndex, signal) {
+		throwIfAborted(signal);
+		const { size } = spec;
+		const count = spec.count ?? 1;
+		if (!Number.isFinite(size?.width) || !Number.isFinite(size?.height) || size.width <= 0 || size.height <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank size must have positive finite dimensions, got ${size?.width}x${size?.height}`);
+		if (!Number.isInteger(count) || count < 1 || count > _embedpdf_engine_core_runtime.PAGE_INSERT_BLANK_MAX_COUNT) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank count ${count} out of range [1, ${_embedpdf_engine_core_runtime.PAGE_INSERT_BLANK_MAX_COUNT}]`);
+		const { fn } = this.runtime;
+		const destPtr = this.session.requireDocPtr();
+		const beforeCount = fn.FPDF_GetPageCount(destPtr);
+		const at = destIndex ?? beforeCount;
+		if (!Number.isInteger(at) || at < 0 || at > beforeCount) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `pages.insertBlank destIndex ${at} out of range [0, ${beforeCount}]`);
+		for (let i = 0; i < count; i++) {
+			const pagePtr = fn.FPDFPage_New(destPtr, at + i, size.width, size.height);
+			if (!pagePtr) {
+				for (let j = 0; j < i; j++) fn.FPDFPage_Delete(destPtr, at);
+				throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, `FPDFPage_New rejected page ${i + 1}/${count} at index ${at + i}`);
+			}
+			fn.FPDFPage_GenerateContent(pagePtr);
+			fn.FPDF_ClosePage(pagePtr);
+		}
+		this.session.refreshPageRegistry();
+		const layout = new PagesReader(this.runtime, this.session).read(signal);
+		return {
+			insertedPageObjectNumbers: layout.pages.slice(at, at + count).map((page) => page.pageObjectNumber),
+			layout,
+			cache: null
+		};
+	}
 };
 //#endregion
 //#region src/features/annotations/internal/read/annotationReadContext.ts
@@ -2154,6 +2213,49 @@ function readQuadPoints(fn, mem, annotPtr) {
 	});
 }
 //#endregion
+//#region src/features/annotations/internal/read/readAnnotationTransformMetadata.ts
+/**
+* Read-side twin of `writers/.../writeAnnotationTransformMetadata.ts`. Decodes
+* the EmbedPDF rotation keys from /EMBD_Metadata back onto the DTO:
+*
+*   - `Rotation`      — degrees, PDF convention. Returned for EVERY rotatable
+*     kind (box AND vertex); the plugin converts it back to its CW-content
+*     `rot` once at the repository seam.
+*   - `UnrotatedRect` — the logical box. BOX kinds only (square/circle/
+*     free-text); a vertex annotation never carries one (its points are the
+*     visual), so vertex readers don't ask for it.
+*
+* Both are absent on un-rotated annotations (and on everything authored before
+* rotation shipped), so both reads return `undefined` and the DTO field stays
+* unset.
+*/
+const KEY_ROTATION$1 = "Rotation";
+const KEY_UNROTATED_RECT$1 = "UnrotatedRect";
+/** The advisory/portable rotation scalar (degrees, PDF convention), or
+*  `undefined` when absent or zero. */
+function readAnnotationRotation(fn, mem, annotPtr) {
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
+	return withScratch(mem, 4, (buf) => {
+		if (!fn.EPDFAnnot_GetEmbedMetadataNumber(annotPtr, KEY_ROTATION$1, buf)) return void 0;
+		const v = readF32(mem, buf);
+		return v ? v : void 0;
+	});
+}
+/** The logical (unrotated) box of a rotated BOX annotation, or `undefined`. */
+function readAnnotationUnrotatedRect(fn, mem, annotPtr) {
+	if (!fn.EPDFAnnot_HasEmbedMetadata(annotPtr)) return void 0;
+	return withScratch(mem, 16, (buf) => {
+		if (!fn.EPDFAnnot_GetEmbedMetadataRect(annotPtr, KEY_UNROTATED_RECT$1, buf)) return void 0;
+		const r = readRectF(mem, buf);
+		return {
+			left: r.left,
+			bottom: r.bottom,
+			right: r.right,
+			top: r.top
+		};
+	});
+}
+//#endregion
 //#region src/features/annotations/internal/textEditIntent.ts
 /** Adobe-compatible `/IT` names, normalized at the engine-core boundary. */
 const IT_REPLACE = "Replace";
@@ -2188,13 +2290,17 @@ function readCaret(fn, mem, annotPtr, base) {
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
 	const rd = readRectangleDifferences(fn, mem, annotPtr);
 	const intent = caretIntentFromName(readIntent(fn, mem, annotPtr));
+	const rotation = readAnnotationRotation(fn, mem, annotPtr);
+	const unrotatedRect = readAnnotationUnrotatedRect(fn, mem, annotPtr);
 	return {
 		...base,
 		subtype: "caret",
 		intent,
 		color,
 		opacity,
-		rectDifferences: rd
+		rectDifferences: rd,
+		...rotation != null ? { rotation } : {},
+		...unrotatedRect ? { unrotatedRect } : {}
 	};
 }
 //#endregion
@@ -2612,49 +2718,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 = {
@@ -3107,6 +3170,47 @@ function readStampName(fn, mem, annotPtr) {
 	return readAnnotString(fn, mem, annotPtr, "Name");
 }
 //#endregion
+//#region src/features/annotations/internal/annotationState.ts
+/**
+* `/State` + `/StateModel` spelling maps — ISO 32000 §12.5.6.3, Table 174.
+*
+* Known values are wire-stable lowercase (the house vocabulary — same
+* rationale as `AnnotationReplyType` / `AnnotationBorderStyle`); the PDF
+* stores the capitalized Table 174 spellings. Unknown values — custom
+* Acrobat state models and their states — pass through VERBATIM in both
+* directions, so foreign review workflows survive a round trip.
+*/
+const STATE_MODEL_TO_PDF = {
+	review: "Review",
+	marked: "Marked"
+};
+const STATE_TO_PDF = {
+	accepted: "Accepted",
+	rejected: "Rejected",
+	cancelled: "Cancelled",
+	completed: "Completed",
+	none: "None",
+	marked: "Marked",
+	unmarked: "Unmarked"
+};
+const PDF_TO_STATE_MODEL = invert(STATE_MODEL_TO_PDF);
+const PDF_TO_STATE = invert(STATE_TO_PDF);
+function stateModelToPdf(value) {
+	return STATE_MODEL_TO_PDF[value] ?? value;
+}
+function stateModelFromPdf(value) {
+	return PDF_TO_STATE_MODEL[value] ?? value;
+}
+function stateToPdf(value) {
+	return STATE_TO_PDF[value] ?? value;
+}
+function stateFromPdf(value) {
+	return PDF_TO_STATE[value] ?? value;
+}
+function invert(map) {
+	return Object.fromEntries(Object.entries(map).map(([wire, pdf]) => [pdf, wire]));
+}
+//#endregion
 //#region src/features/annotations/internal/read/readTextAnnotation.ts
 /** Default `/C` — matches the generator's yellow note fill and the writer default. */
 const DEFAULT_NOTE_COLOR$1 = {
@@ -3121,12 +3225,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
@@ -3841,6 +3949,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");
@@ -3857,6 +3966,7 @@ function readAnnotationBase(fn, mem, annotPtr, pageObjectNumber, index, revision
 		flags,
 		rect,
 		contents,
+		subject,
 		author,
 		created: createdRaw ? pdfDateToIso(createdRaw) : null,
 		modified: modifiedRaw ? pdfDateToIso(modifiedRaw) : null,
@@ -4131,19 +4241,31 @@ const ANNOT_SUBTYPE_WIDGET = 20;
 /** `FPDF_ANNOT_FREETEXT` — free-text annotation subtype code. */
 const ANNOT_SUBTYPE_FREETEXT = 3;
 /**
-* BOX-family subtypes (free-text 3, square 5, circle 6, stamp 13): the kinds
-* whose v3 writers put rotation in the AP `/Matrix` + `/EMBD_Metadata`
-* `/UnrotatedRect`. Only these are eligible for rotation-stripped appearance
-* rendering — vertex kinds (line/polyline/polygon/ink) pre-rotate their
-* geometry, so their rasters must stay on the classic path.
+* BOX-family subtypes (free-text 3, square 5, circle 6, stamp 13, caret 14):
+* the kinds whose v3 writers put rotation in the AP `/Matrix` +
+* `/EMBD_Metadata` `/UnrotatedRect`. Only these are eligible for
+* rotation-stripped appearance rendering — vertex kinds
+* (line/polyline/polygon/ink) pre-rotate their geometry, so their rasters must
+* stay on the classic path. This set MUST cover every kind whose reader
+* surfaces the rotation pair: `fromDTO` (plugin-annotation repository) mirrors
+* this exact condition to re-apply the stripped rotation as `apRot`.
 */
 const BOX_FAMILY_SUBTYPES = /* @__PURE__ */ new Set([
 	3,
 	5,
 	6,
-	13
+	13,
+	14
 ]);
 /**
+* Per-appearance output-pixel ceiling (see the clamp in `renderOne`).
+* 16 M px ≈ a 4000² raster ≈ 64 MB of transient RGBA — safely inside the
+* wasm heap for the one-at-a-time batch loop, while a page-sized annotation
+* stays crisp to roughly 5–6× before its appearance starts stretching.
+* Small annotations (the overwhelming majority) never come near it.
+*/
+const APPEARANCE_PIXEL_CLAMP = 16e6;
+/**
 * Maps an `AnnotationAppearanceMode` onto the PDFium appearance-mode int and
 * the `EPDFAnnot_GetAvailableAppearanceModes` bit it occupies.
 *   N -> mode 0 / bit 1, R -> mode 1 / bit 2, D -> mode 2 / bit 4.
@@ -4242,13 +4364,15 @@ var AnnotationAppearanceReader = class {
 			fn.EPDFAnnot_GenerateFormFieldAP(annotPtr);
 			if (!fn.EPDFAnnot_HasAppearanceStream(annotPtr, modeInt)) return null;
 		} else return null;
+		const rectArea = Math.max(1, (rect.right - rect.left) * (rect.top - rect.bottom));
+		const effScale = Math.min(scale, Math.sqrt(APPEARANCE_PIXEL_CLAMP / rectArea));
 		return rasterize(this.runtime, {
 			rect,
 			page,
 			rotation,
 			viewport: {
 				kind: "scale",
-				scale
+				scale: effScale
 			},
 			...maxOutputPixels !== void 0 ? { maxOutputPixels } : {},
 			background: "transparent",
@@ -4363,7 +4487,9 @@ function setAnnotFlags(fn, annotPtr, partial) {
 	if (!fn.FPDFAnnot_SetFlags(annotPtr, next)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "FPDFAnnot_SetFlags returned false");
 }
 /**
-* Write `/Rect` via `FPDFAnnot_SetRect`. FS_RECTF layout is
+* Write `/Rect` without touching `/AP`. Appearance preservation/regeneration
+* belongs to AnnotationMutator; a geometry primitive must not silently rewrite
+* an existing appearance `/BBox`. FS_RECTF layout is
 * `{ left, top, right, bottom }` (top > bottom in PDF coords).
 */
 function setAnnotRect(fn, mem, annotPtr, rect) {
@@ -4373,12 +4499,40 @@ function setAnnotRect(fn, mem, annotPtr, rect) {
 		mem.poke(buf, "f32", rect.top, 4);
 		mem.poke(buf, "f32", rect.right, 8);
 		mem.poke(buf, "f32", rect.bottom, 12);
-		if (!fn.FPDFAnnot_SetRect(annotPtr, buf)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "FPDFAnnot_SetRect returned false");
+		if (!fn.EPDFAnnot_SetRect(annotPtr, buf)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetRect returned false");
 	} finally {
 		mem.free(buf);
 	}
 }
 /**
+* Write a UTF-16 string entry into an annotation dictionary. The write
+* side of `readAnnotString`.
+*/
+function writeAnnotString(fn, mem, annotPtr, key, value) {
+	const ptr = mem.writeU16String(value);
+	try {
+		fn.FPDFAnnot_SetStringValue(annotPtr, key, ptr);
+	} finally {
+		mem.free(ptr);
+	}
+}
+/**
+* Three-state string write: `null` REMOVES the dictionary entry.
+*
+* Clearing goes through `EPDFAnnot_RemoveKey` because
+* `FPDFAnnot_SetStringValue` with a NULL value writes an EMPTY string —
+* it never removes. True removal is what keeps the read side honest:
+* `readAnnotString` returns `null` iff the key is absent, so a cleared
+* field reads back as `null`, not `''`.
+*/
+function writeAnnotStringOrClear(fn, mem, annotPtr, key, value) {
+	if (value === null) {
+		fn.EPDFAnnot_RemoveKey(annotPtr, key);
+		return;
+	}
+	writeAnnotString(fn, mem, annotPtr, key, value);
+}
+/**
 * Set `/BS /S` (border style code) and `/BS /W` (width) in one call via
 * `EPDFAnnot_SetBorderStyle`. `styleCode` is a raw
 * `FPDF_ANNOT_BORDER_STYLE` enum value — the string<->code mapping lives
@@ -4577,8 +4731,8 @@ function setCalloutLine(fn, mem, annotPtr, points) {
 //#region src/features/annotations/internal/write/writeAnnotationBase.ts
 /**
 * Write the annotation-wide base fields shared by every Draft
-* (contents/nm). The kind-specific writer calls this BEFORE its own
-* field writes; order doesn't actually matter at the PDF level, but
+* (contents/subject/nm). The kind-specific writer calls this BEFORE its
+* own field writes; order doesn't actually matter at the PDF level, but
 * keeping the base first makes the writers symmetric with the readers.
 *
 * `/T` (author display) is stamped by the mutator from
@@ -4589,13 +4743,14 @@ function setCalloutLine(fn, mem, annotPtr, points) {
 * annotation; the writer does not.
 */
 function applyAnnotationBaseDraft(fn, mem, annotPtr, draft) {
-	if (draft.contents !== void 0) writeStringOrClear(fn, mem, annotPtr, "Contents", draft.contents);
-	if (draft.nm !== void 0 && draft.nm.length > 0) writeString(fn, mem, annotPtr, "NM", draft.nm);
+	if (draft.contents !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Contents", draft.contents);
+	if (draft.subject !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Subj", draft.subject);
+	if (draft.nm !== void 0 && draft.nm.length > 0) writeAnnotString(fn, mem, annotPtr, "NM", draft.nm);
 	if (draft.flags !== void 0) setAnnotFlags(fn, annotPtr, draft.flags);
 }
 /**
 * Write the annotation-wide base fields shared by every Patch
-* (contents). /T is bound at creation and not patchable — see
+* (contents/subject). /T is bound at creation and not patchable — see
 * `AnnotationPatchBase`. /NM is monotonic per annotation; the mutator
 * may stamp /NM opportunistically on a weak annotation via
 * `writeAnnotationNm`.
@@ -4606,7 +4761,8 @@ function applyAnnotationBaseDraft(fn, mem, annotPtr, draft) {
 *   "..."     -> set the entry to that value
 */
 function applyAnnotationBasePatch(fn, mem, annotPtr, patch) {
-	if (patch.contents !== void 0) writeStringOrClear(fn, mem, annotPtr, "Contents", patch.contents);
+	if (patch.contents !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Contents", patch.contents);
+	if (patch.subject !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "Subj", patch.subject);
 	if (patch.flags !== void 0) setAnnotFlags(fn, annotPtr, patch.flags);
 }
 /**
@@ -4617,7 +4773,7 @@ function applyAnnotationBasePatch(fn, mem, annotPtr, patch) {
 */
 function writeAnnotationAuthor(fn, mem, annotPtr, displayName) {
 	if (displayName.length === 0) return;
-	writeString(fn, mem, annotPtr, "T", displayName);
+	writeAnnotString(fn, mem, annotPtr, "T", displayName);
 }
 /**
 * Stamp /NM on an annotation that didn't have one. Used by the mutator
@@ -4626,7 +4782,7 @@ function writeAnnotationAuthor(fn, mem, annotPtr, displayName) {
 */
 function writeAnnotationNm(fn, mem, annotPtr, nm) {
 	if (nm.length === 0) return;
-	writeString(fn, mem, annotPtr, "NM", nm);
+	writeAnnotString(fn, mem, annotPtr, "NM", nm);
 }
 /**
 * Stamp /M (modification date) on an annotation. /M is a standard
@@ -4643,22 +4799,7 @@ function writeAnnotationNm(fn, mem, annotPtr, nm) {
 * Format: `D:YYYYMMDDHHmmSSOHH'mm'` (see formatPdfDate).
 */
 function writeAnnotationModified(fn, mem, annotPtr, now = /* @__PURE__ */ new Date()) {
-	writeString(fn, mem, annotPtr, "M", formatPdfDate(now));
-}
-function writeString(fn, mem, annotPtr, key, value) {
-	const ptr = mem.writeU16String(value);
-	try {
-		fn.FPDFAnnot_SetStringValue(annotPtr, key, ptr);
-	} finally {
-		mem.free(ptr);
-	}
-}
-function writeStringOrClear(fn, mem, annotPtr, key, value) {
-	if (value === null) {
-		fn.FPDFAnnot_SetStringValue(annotPtr, key, _embedpdf_engine_runtime.NULL_PTR);
-		return;
-	}
-	writeString(fn, mem, annotPtr, key, value);
+	writeAnnotString(fn, mem, annotPtr, "M", formatPdfDate(now));
 }
 //#endregion
 //#region src/features/annotations/internal/identity/captureOrStampStableId.ts
@@ -4830,50 +4971,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "rotation requires unrotatedRect: supply the pair together (or rely on an existing /EMBD_Metadata/UnrotatedRect)");
+		setRotation(fn, annotPtr, t.rotation);
+	} else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
+	if (t.unrotatedRect !== void 0) if (t.unrotatedRect !== null) setUnrotatedRect(fn, mem, annotPtr, t.unrotatedRect);
+	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+}
+/**
+* Write the advisory `/Rotation` scalar for a VERTEX kind
+* (line/polyline/polygon/ink), tri-state: `undefined` never touches the
+* document, `null`/`0` clears, a value sets. Whenever it does write, any
+* `/UnrotatedRect` is defensively cleared — that key is an impossible state on
+* a vertex kind and must never accidentally drive the AP generator.
+*/
+function writeVertexTransformMetadata(fn, annotPtr, t) {
+	if (t.rotation === void 0) return;
+	if (t.rotation !== null && t.rotation !== 0) setRotation(fn, annotPtr, t.rotation);
+	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
+	fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
+}
+//#endregion
+//#region src/features/annotations/internal/write/writeCaretAnnotation.ts
+/** Default `/C` colour when a caret draft omits it (engine-wide default mark). */
+const DEFAULT_CARET_COLOR = {
+	r: 255,
+	g: 0,
+	b: 0
+};
+/** Default opacity, set explicitly so reads always round-trip the same value. */
+const DEFAULT_OPACITY$4 = 1;
+/**
+* Apply a caret draft to a freshly-created annotation. Caret carries no
+* geometry of its own beyond `/Rect`. Order:
+*   1. base author-metadata (contents/nm/flags)
+*   2. `/Rect` (required — supplied by the caller; never derived)
+*   3. `/C` color + `/CA` opacity
+*   4. `/RD` rectangle differences (optional)
+*/
+function applyCaretDraft(fn, mem, annotPtr, draft) {
+	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
+	setAnnotRect(fn, mem, annotPtr, draft.rect);
+	writeBoxTransformMetadata(fn, mem, annotPtr, {
+		rotation: draft.rotation,
+		unrotatedRect: draft.unrotatedRect
+	});
+	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_CARET_COLOR);
+	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY$4);
+	if (draft.intent !== void 0) setIntent(fn, annotPtr, caretIntentToName(draft.intent));
+	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
@@ -5040,177 +5360,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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "rotation requires unrotatedRect: supply the pair together (or rely on an existing /EMBD_Metadata/UnrotatedRect)");
-		setRotation(fn, annotPtr, t.rotation);
-	} else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
-	if (t.unrotatedRect !== void 0) if (t.unrotatedRect !== null) setUnrotatedRect(fn, mem, annotPtr, t.unrotatedRect);
-	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
-}
-/**
-* Write the advisory `/Rotation` scalar for a VERTEX kind
-* (line/polyline/polygon/ink), tri-state: `undefined` never touches the
-* document, `null`/`0` clears, a value sets. Whenever it does write, any
-* `/UnrotatedRect` is defensively cleared — that key is an impossible state on
-* a vertex kind and must never accidentally drive the AP generator.
-*/
-function writeVertexTransformMetadata(fn, annotPtr, t) {
-	if (t.rotation === void 0) return;
-	if (t.rotation !== null && t.rotation !== 0) setRotation(fn, annotPtr, t.rotation);
-	else fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_ROTATION);
-	fn.EPDFAnnot_ClearEmbedMetadataKey(annotPtr, KEY_UNROTATED_RECT);
-}
-//#endregion
 //#region src/features/annotations/internal/write/writeFreeTextAnnotation.ts
 /**
 * Default `/DA` colour for free text: black (border + default text). Unlike
@@ -5980,13 +6129,18 @@ const DEFAULT_OPACITY = 1;
 * Apply a text (sticky-note) draft. The visual is entirely generator-owned:
 * the mutator's closing `regenerateAppearance` bakes the 20×20 note icon
 * from `/C` + `/Name` (GenerateTextAP), so this writer only records state.
+* `/State` + `/StateModel` are dictionary-only (ISO 32000 §12.5.6.3) and
+* never reach the generator.
 */
 function applyTextDraft(fn, mem, annotPtr, draft) {
+	if (draft.state !== void 0 && draft.stateModel === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "text draft: state requires stateModel (ISO 32000 §12.5.6.3)");
 	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
 	setAnnotRect(fn, mem, annotPtr, draft.rect);
 	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_NOTE_COLOR);
 	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY);
 	setNoteIcon(fn, annotPtr, draft.icon ?? "note");
+	if (draft.stateModel !== void 0) writeAnnotString(fn, mem, annotPtr, "StateModel", stateModelToPdf(draft.stateModel));
+	if (draft.state !== void 0) writeAnnotString(fn, mem, annotPtr, "State", stateToPdf(draft.state));
 }
 function applyTextPatch(fn, mem, annotPtr, patch) {
 	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
@@ -5994,6 +6148,8 @@ function applyTextPatch(fn, mem, annotPtr, patch) {
 	if (patch.color !== void 0) setAnnotColor(fn, annotPtr, patch.color);
 	if (patch.opacity !== void 0) setAnnotOpacity(fn, annotPtr, patch.opacity);
 	if (patch.icon !== void 0) setNoteIcon(fn, annotPtr, patch.icon);
+	if (patch.stateModel !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "StateModel", patch.stateModel === null ? null : stateModelToPdf(patch.stateModel));
+	if (patch.state !== void 0) writeAnnotStringOrClear(fn, mem, annotPtr, "State", patch.state === null ? null : stateToPdf(patch.state));
 }
 function isTextSubtype(subtype) {
 	return subtype === "text";
@@ -6971,17 +7127,35 @@ var RedactionApplier = class {
 	}
 	applyAllOnPage(pagePtr) {
 		const { fn, mem } = this.runtime;
+		const hasRedactions = this.pageHasRedactAnnotations(pagePtr);
 		return withScratch(mem, 4, (countPtr) => {
-			if (!fn.EPDFPage_ApplyRedactions(pagePtr, countPtr)) return {
-				status: "unchanged",
-				removed: 0
-			};
+			if (!fn.EPDFPage_ApplyRedactions(pagePtr, countPtr)) {
+				if (hasRedactions) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "native page redaction apply failed");
+				return {
+					status: "unchanged",
+					removed: 0
+				};
+			}
 			return {
 				status: "applied",
 				removed: readI32(mem, countPtr) >>> 0
 			};
 		});
 	}
+	pageHasRedactAnnotations(pagePtr) {
+		const { fn } = this.runtime;
+		const count = fn.FPDFPage_GetAnnotCount(pagePtr);
+		for (let index = 0; index < count; index++) {
+			const annotPtr = fn.FPDFPage_GetAnnot(pagePtr, index);
+			if (!annotPtr) continue;
+			try {
+				if ((0, _embedpdf_engine_core_runtime.subtypeFromCode)(fn.FPDFAnnot_GetSubtype(annotPtr)) === "redact") return true;
+			} finally {
+				fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+		}
+		return false;
+	}
 	applyRefsOnPage(pagePtr, refs) {
 		const { fn, mem } = this.runtime;
 		let removed = 0;
@@ -7007,23 +7181,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) {
@@ -7032,7 +7209,7 @@ var PageTextReader = class {
 	}
 	read(pageObjectNumber, signal) {
 		throwIfAborted(signal);
-		const { fn, mem } = this.runtime;
+		const { fn } = this.runtime;
 		const pool = this.session.pagePool();
 		const pagePtr = pool.acquire(pageObjectNumber);
 		try {
@@ -7041,10 +7218,18 @@ var PageTextReader = class {
 			if (!textPagePtr) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `FPDFText_LoadPage returned null for page object ${pageObjectNumber}`);
 			try {
 				throwIfAborted(signal);
-				const charCount = fn.FPDFText_CountChars(textPagePtr);
-				return {
-					text: readPageText(fn, mem, textPagePtr, charCount),
-					charCount: Math.max(charCount, 0)
+				const charCount = Math.max(fn.FPDFText_CountChars(textPagePtr), 0);
+				const text = readTextFull(this.runtime, textPagePtr, charCount);
+				const charMap = readCharMap(this.runtime, textPagePtr, pageObjectNumber);
+				const violation = (0, _embedpdf_engine_core_runtime.charMapViolation)(charCount, text.length, charMap);
+				if (violation !== null) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `char map invariant violated for page object ${pageObjectNumber}: ${violation}`);
+				return charMap.length > 0 ? {
+					text,
+					charCount,
+					charMap
+				} : {
+					text,
+					charCount
 				};
 			} finally {
 				fn.FPDFText_ClosePage(textPagePtr);
@@ -7054,21 +7239,65 @@ var PageTextReader = class {
 		}
 	}
 };
-function readPageText(fn, mem, textPagePtr, charCount) {
+/**
+* Full-fidelity page text in one call: the buffer is sized at the maximum
+* possible expansion (every character a surrogate pair, plus the NUL), so
+* the returned requirement always fits and the measure round-trip is
+* skipped. The return value counts UTF-16 units INCLUDING the terminator.
+*/
+function readTextFull(runtime, textPagePtr, charCount) {
 	if (charCount <= 0) return "";
-	return withScratch(mem, (charCount + 1) * 2, (buf) => {
-		if (fn.FPDFText_GetText(textPagePtr, 0, charCount, buf) <= 0) return "";
-		return mem.readU16String(buf);
+	const { fn, mem } = runtime;
+	const bufUnits = charCount * 2 + 1;
+	return withScratch(mem, bufUnits * 2, (buf) => {
+		const written = fn.EPDFText_GetTextFull(textPagePtr, buf, bufUnits);
+		if (written <= 1) return "";
+		return decodeUtf16Le(mem.readBytes(buf, (written - 1) * 2));
+	});
+}
+function decodeUtf16Le(bytes) {
+	const units = new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
+	let out = "";
+	const CHUNK = 8192;
+	for (let i = 0; i < units.length; i += CHUNK) out += String.fromCharCode(...units.subarray(i, Math.min(i + CHUNK, units.length)));
+	return out;
+}
+/** Anchor struct layout: two little-endian i32s (see EPDF_CHAR_MAP_ANCHOR). */
+const ANCHOR_BYTES = 8;
+function readCharMap(runtime, textPagePtr, pageObjectNumber) {
+	const { fn, mem } = runtime;
+	const count = fn.EPDFText_GetCharToTextMap(textPagePtr, _embedpdf_engine_runtime.NULL_PTR, 0);
+	if (count < 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, `EPDFText_GetCharToTextMap failed for page object ${pageObjectNumber}`);
+	if (count === 0) return [];
+	return withScratch(mem, count * ANCHOR_BYTES, (buf) => {
+		fn.EPDFText_GetCharToTextMap(textPagePtr, buf, count);
+		const bytes = mem.readBytes(buf, count * ANCHOR_BYTES);
+		const words = new Int32Array(bytes.buffer, bytes.byteOffset, count * 2);
+		const anchors = new Array(count);
+		for (let i = 0; i < count; i++) anchors[i] = [words[i * 2], words[i * 2 + 1]];
+		return anchors;
 	});
 }
 //#endregion
 //#region src/features/geometry/PageGeometryReader.ts
 /**
+* Mid-object orientation drift that forces a run split (~0.5°). Real content
+* keeps one char matrix per text object; this guards the exotic cases so a
+* run's `rotation` is always representative of every glyph in it.
+*/
+const ROTATION_SPLIT_TOLERANCE = .0087;
+/**
 * Geometry-only text layout reader.
 *
 * Emits geometry in PDF user space (y-up edges) — the canonical engine
 * geometry. The viewer converts to content/view space via the page geometry
 * matrix; this reader applies NO Y-flip or device transform.
+*
+* One `EPDFText_GetCharGeometry` call per glyph supplies boxes, oriented
+* cells, and flags together; `buildRunsFromRawGlyphs` then groups glyphs
+* into the upright/rotated run union. Upright runs are byte-identical to the
+* pre-orientation reader (quads the native layer offers are deliberately
+* dropped — the dominant case never pays for orientation).
 */
 var PageGeometryReader = class {
 	constructor(runtime, session) {
@@ -7077,7 +7306,7 @@ var PageGeometryReader = class {
 	}
 	read(pageObjectNumber, signal) {
 		throwIfAborted(signal);
-		const { fn } = this.runtime;
+		const { fn, mem } = this.runtime;
 		const pool = this.session.pagePool();
 		const pagePtr = pool.acquire(pageObjectNumber);
 		try {
@@ -7087,12 +7316,27 @@ var PageGeometryReader = class {
 			try {
 				throwIfAborted(signal);
 				const glyphCount = Math.max(fn.FPDFText_CountChars(textPagePtr), 0);
-				const glyphs = [];
-				for (let i = 0; i < glyphCount; i++) {
-					throwIfAborted(signal);
-					glyphs.push(this.readGlyphInfo(textPagePtr, i));
+				const records = [];
+				const geometryPtr = mem.alloc(EPDF_CHAR_GEOMETRY_LAYOUT.bytes);
+				try {
+					let prevObjectKey = null;
+					for (let i = 0; i < glyphCount; i++) {
+						throwIfAborted(signal);
+						const objectKey = fn.FPDFText_GetTextObject(textPagePtr, i);
+						const record = {
+							objectKey,
+							...this.readGlyphRaw(textPagePtr, i, geometryPtr)
+						};
+						if (objectKey !== prevObjectKey) {
+							record.fontSize = fn.FPDFText_GetFontSize(textPagePtr, i);
+							prevObjectKey = objectKey;
+						}
+						records.push(record);
+					}
+				} finally {
+					mem.free(geometryPtr);
 				}
-				return { runs: this.buildRunsFromGlyphs(glyphs, textPagePtr) };
+				return { runs: buildRunsFromRawGlyphs(records) };
 			} finally {
 				fn.FPDFText_ClosePage(textPagePtr);
 			}
@@ -7100,96 +7344,206 @@ var PageGeometryReader = class {
 			pool.release(pageObjectNumber);
 		}
 	}
-	buildRunsFromGlyphs(glyphs, textPagePtr) {
-		const { fn } = this.runtime;
-		const runs = [];
-		let current = null;
-		let curObjPtr = null;
-		let bounds = null;
-		for (let i = 0; i < glyphs.length; i++) {
-			const glyph = glyphs[i];
-			const objPtr = fn.FPDFText_GetTextObject(textPagePtr, i);
-			if (objPtr !== curObjPtr) {
-				curObjPtr = objPtr;
-				current = {
-					rect: { ...glyph.looseBox },
-					charStart: i,
-					glyphs: [],
-					fontSize: fn.FPDFText_GetFontSize(textPagePtr, i)
-				};
-				bounds = { ...glyph.looseBox };
-				runs.push(current);
+	readGlyphRaw(textPagePtr, charIndex, geometryPtr) {
+		const { fn, mem } = this.runtime;
+		if (!fn.EPDFText_GetCharGeometry(textPagePtr, charIndex, geometryPtr)) return emptyRawGlyph();
+		const { offsets, flags: bits } = EPDF_CHAR_GEOMETRY_LAYOUT;
+		const native = readI32(mem, geometryPtr, offsets.flags) >>> 0;
+		if (native & bits.empty) return emptyRawGlyph();
+		const upright = Boolean(native & bits.upright);
+		const raw = {
+			flags: native & bits.space ? 1 : 0,
+			looseBox: (0, _embedpdf_engine_core_runtime.normalizePdfRect)(readRectF(mem, geometryPtr, offsets.looseBox)),
+			upright,
+			rotation: 0,
+			ascentFlip: false
+		};
+		if (native & bits.hasTightBox) raw.tightBox = (0, _embedpdf_engine_core_runtime.normalizePdfRect)(readRectF(mem, geometryPtr, offsets.tightBox));
+		if (native & bits.hasLooseQuad) {
+			raw.looseQuad = readQuad(mem, geometryPtr, offsets.looseQuad);
+			if (native & bits.hasTightQuad) raw.tightQuad = readQuad(mem, geometryPtr, offsets.tightQuad);
+			if (!upright) {
+				const a = readF32(mem, geometryPtr, offsets.matrix);
+				const b = readF32(mem, geometryPtr, offsets.matrix + 4);
+				const c = readF32(mem, geometryPtr, offsets.matrix + 8);
+				const d = readF32(mem, geometryPtr, offsets.matrix + 12);
+				raw.rotation = Math.atan2(b, a);
+				raw.ascentFlip = a * d - b * c < 0;
 			}
-			current.glyphs.push(toSlimGlyph(glyph));
-			if (glyph.isEmpty) continue;
-			bounds.left = Math.min(bounds.left, glyph.looseBox.left);
-			bounds.bottom = Math.min(bounds.bottom, glyph.looseBox.bottom);
-			bounds.right = Math.max(bounds.right, glyph.looseBox.right);
-			bounds.top = Math.max(bounds.top, glyph.looseBox.top);
-			current.rect = { ...bounds };
 		}
-		return runs;
+		return raw;
 	}
-	readGlyphInfo(textPagePtr, charIndex) {
-		const { fn, mem } = this.runtime;
-		const rectPtr = mem.alloc(16);
-		const tLeftPtr = mem.alloc(8);
-		const tRightPtr = mem.alloc(8);
-		const tBottomPtr = mem.alloc(8);
-		const tTopPtr = mem.alloc(8);
-		const ptrs = [
-			rectPtr,
-			tLeftPtr,
-			tRightPtr,
-			tBottomPtr,
-			tTopPtr
-		];
-		try {
-			if (!fn.FPDFText_GetLooseCharBox(textPagePtr, charIndex, rectPtr)) return emptyGlyph();
-			const left = Number(mem.peek(rectPtr, "f32", 0));
-			const top = Number(mem.peek(rectPtr, "f32", 4));
-			const right = Number(mem.peek(rectPtr, "f32", 8));
-			const bottom = Number(mem.peek(rectPtr, "f32", 12));
-			if (left === right || top === bottom) return emptyGlyph();
-			const glyph = { looseBox: (0, _embedpdf_engine_core_runtime.normalizePdfRect)({
-				left,
-				bottom,
-				right,
-				top
-			}) };
-			if (fn.FPDFText_GetCharBox(textPagePtr, charIndex, tLeftPtr, tRightPtr, tBottomPtr, tTopPtr)) {
-				const tLeft = Number(mem.peek(tLeftPtr, "f64"));
-				const tRight = Number(mem.peek(tRightPtr, "f64"));
-				glyph.tightBox = (0, _embedpdf_engine_core_runtime.normalizePdfRect)({
-					left: tLeft,
-					bottom: Number(mem.peek(tBottomPtr, "f64")),
-					right: tRight,
-					top: Number(mem.peek(tTopPtr, "f64"))
-				});
-			}
-			glyph.isSpace = fn.FPDFText_GetUnicode(textPagePtr, charIndex) === 32;
-			return glyph;
-		} finally {
-			for (const ptr of ptrs) mem.free(ptr);
+};
+/**
+* Group per-glyph records into the run union. Pure — exported for tests.
+*
+* Runs split on text-object change (the legacy rule) and on orientation
+* change between classifiable glyphs (θ drift / mixed orientation). A run's
+* variant is decided by its FIRST classifiable glyph:
+*   - empty glyphs never classify (they adopt the run's variant);
+*   - real glyphs WITHOUT an oriented cell (singular matrix, synthesized
+*     /ActualText pieces) classify as upright — box-only data degrades to
+*     exactly the legacy behavior;
+*   - real glyphs with a non-upright matrix classify as rotated.
+* Runs that never see a classifiable glyph emit as upright (degenerate,
+* legacy behavior).
+*/
+function buildRunsFromRawGlyphs(records) {
+	const runs = [];
+	let buffer = [];
+	let charStart = 0;
+	let fontSize;
+	let objectKey = null;
+	let cls;
+	const flush = (nextStart) => {
+		if (buffer.length > 0) {
+			runs.push(materializeRun(buffer, charStart, fontSize, cls));
+			buffer = [];
+			cls = void 0;
+		}
+		charStart = nextStart;
+	};
+	for (let i = 0; i < records.length; i++) {
+		const record = records[i];
+		if (record.objectKey !== objectKey) {
+			flush(i);
+			objectKey = record.objectKey;
+			fontSize = record.fontSize;
+		}
+		const recordClass = classOf(record);
+		if (recordClass) {
+			if (cls && !sameClass(cls, recordClass)) flush(i);
+			if (!cls) cls = recordClass;
 		}
+		buffer.push(record);
+	}
+	flush(records.length);
+	return runs;
+}
+function classOf(record) {
+	if (record.flags & 2) return void 0;
+	if (record.looseQuad && !record.upright) return {
+		upright: false,
+		rotation: record.rotation,
+		ascentFlip: record.ascentFlip
+	};
+	return { upright: true };
+}
+function sameClass(a, b) {
+	if (a.upright || b.upright) return a.upright === b.upright;
+	if (a.ascentFlip !== b.ascentFlip) return false;
+	const delta = a.rotation - b.rotation;
+	return Math.abs(Math.atan2(Math.sin(delta), Math.cos(delta))) <= ROTATION_SPLIT_TOLERANCE;
+}
+function materializeRun(buffer, charStart, fontSize, cls) {
+	if (cls && !cls.upright) {
+		const glyphs = buffer.map((g) => g.looseQuad ? {
+			looseQuad: g.looseQuad,
+			flags: g.flags,
+			...g.tightQuad ? { tightQuad: g.tightQuad } : {}
+		} : {
+			looseQuad: zeroQuad(),
+			flags: g.flags
+		});
+		return {
+			rect: runBounds(buffer, (g) => g.looseQuad ? (0, _embedpdf_engine_core_runtime.pdfQuadBounds)(g.looseQuad) : ZERO_RECT),
+			charStart,
+			glyphs,
+			rotation: cls.rotation,
+			ascentFlip: cls.ascentFlip,
+			...fontSize !== void 0 ? { fontSize } : {}
+		};
+	}
+	const glyphs = buffer.map((g) => ({
+		looseBox: g.looseBox,
+		flags: g.flags,
+		...g.tightBox ? { tightBox: g.tightBox } : {}
+	}));
+	return {
+		rect: runBounds(buffer, (g) => g.looseBox),
+		charStart,
+		glyphs,
+		...fontSize !== void 0 ? { fontSize } : {}
+	};
+}
+/** Legacy run-rect algorithm: seed from the first glyph, expand on non-empty. */
+function runBounds(buffer, boundsOf) {
+	const seed = boundsOf(buffer[0]);
+	const rect = {
+		left: seed.left,
+		bottom: seed.bottom,
+		right: seed.right,
+		top: seed.top
+	};
+	for (const g of buffer) {
+		if (g.flags & 2) continue;
+		const b = boundsOf(g);
+		rect.left = Math.min(rect.left, b.left);
+		rect.bottom = Math.min(rect.bottom, b.bottom);
+		rect.right = Math.max(rect.right, b.right);
+		rect.top = Math.max(rect.top, b.top);
 	}
+	return rect;
+}
+const ZERO_RECT = {
+	left: 0,
+	bottom: 0,
+	right: 0,
+	top: 0
 };
-function emptyGlyph() {
+function zeroQuad() {
+	return {
+		p1: {
+			x: 0,
+			y: 0
+		},
+		p2: {
+			x: 0,
+			y: 0
+		},
+		p3: {
+			x: 0,
+			y: 0
+		},
+		p4: {
+			x: 0,
+			y: 0
+		}
+	};
+}
+function emptyRawGlyph() {
 	return {
+		flags: 2,
 		looseBox: {
 			left: 0,
 			bottom: 0,
 			right: 0,
 			top: 0
 		},
-		isEmpty: true
+		upright: true,
+		rotation: 0,
+		ascentFlip: false
 	};
 }
-function toSlimGlyph(glyph) {
+function readQuad(mem, ptr, byteOffset) {
+	const f = (offset) => readF32(mem, ptr, byteOffset + offset);
 	return {
-		looseBox: glyph.looseBox,
-		flags: glyph.isEmpty ? 2 : glyph.isSpace ? 1 : 0,
-		...glyph.tightBox ? { tightBox: glyph.tightBox } : {}
+		p1: {
+			x: f(0),
+			y: f(4)
+		},
+		p2: {
+			x: f(8),
+			y: f(12)
+		},
+		p3: {
+			x: f(16),
+			y: f(20)
+		},
+		p4: {
+			x: f(24),
+			y: f(28)
+		}
 	};
 }
 //#endregion
@@ -8562,7 +8916,7 @@ function emptyResult(index, status) {
 //#endregion
 //#region src/features/search/internal/pageCorpusCache.ts
 /**
-* Per-session, per-page search corpus: the page's extracted text plus its
+* Per-session, per-page search corpus: the page's text snapshot plus its
 * DEFAULT fold (the one literal queries with default options search).
 * This is the local engine's in-memory equivalent of the server's corpus
 * artifacts — same fold version, same shape, built lazily on first search
@@ -8587,19 +8941,20 @@ function acquirePageCorpus(runtime, session, pageObjectNumber, signal) {
 		cache.set(session, pages);
 	}
 	const hit = pages.get(pageObjectNumber);
-	if (hit && hit.seq === seq) return hit.folded;
-	const text = new PageTextReader(runtime, session).read(pageObjectNumber, signal).text;
-	const folded = (0, _embedpdf_engine_core_runtime.foldText)(text);
-	pages.delete(pageObjectNumber);
-	pages.set(pageObjectNumber, {
+	if (hit && hit.seq === seq) return hit;
+	const snapshot = new PageTextReader(runtime, session).read(pageObjectNumber, signal);
+	const entry = {
 		seq,
-		folded
-	});
+		folded: (0, _embedpdf_engine_core_runtime.foldText)(snapshot.text),
+		snapshot
+	};
+	pages.delete(pageObjectNumber);
+	pages.set(pageObjectNumber, entry);
 	if (pages.size > MAX_CACHED_PAGES) {
 		const oldest = pages.keys().next().value;
 		if (oldest !== void 0) pages.delete(oldest);
 	}
-	return folded;
+	return entry;
 }
 //#endregion
 //#region src/features/search/internal/searchCursor.ts
@@ -8708,19 +9063,23 @@ var SearchReader = class {
 			throwIfAborted(signal);
 			const pon = order[scanned].pageObjectNumber;
 			const corpus = acquirePageCorpus(this.runtime, this.session, pon, signal);
+			const text = corpus.snapshot.text;
 			let ranges;
-			if (query.regex) ranges = (0, _embedpdf_engine_core_runtime.matchRegex)(corpus.original, query);
-			else if (query.matchCase || query.matchDiacritics) ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)((0, _embedpdf_engine_core_runtime.foldText)(corpus.original, (0, _embedpdf_engine_core_runtime.foldOptionsFor)(query)), query);
-			else ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)(corpus, query);
+			if (query.regex) ranges = (0, _embedpdf_engine_core_runtime.matchRegex)(text, query);
+			else if (query.matchCase || query.matchDiacritics) ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)((0, _embedpdf_engine_core_runtime.foldText)(text, (0, _embedpdf_engine_core_runtime.foldOptionsFor)(query)), query);
+			else ranges = (0, _embedpdf_engine_core_runtime.matchLiteral)(corpus.folded, query);
 			if (ranges.length > 0) {
-				const geometry = new PageGeometryReader(this.runtime, this.session).read(pon, signal);
-				for (const range of ranges) matches.push({
-					pageObjectNumber: pon,
-					charStart: range.start,
-					charCount: range.length,
-					rects: (0, _embedpdf_engine_core_runtime.searchRectsForRange)(geometry, range.start, range.length),
-					...mode === "full" ? { snippet: (0, _embedpdf_engine_core_runtime.buildSnippet)(corpus.original, range) } : {}
-				});
+				const layout = (0, _embedpdf_engine_core_runtime.buildPageTextLayout)(new PageGeometryReader(this.runtime, this.session).read(pon, signal));
+				for (const range of ranges) {
+					const chars = (0, _embedpdf_engine_core_runtime.charRangeForTextOffsets)(corpus.snapshot, range.start, range.start + range.length);
+					matches.push({
+						pageObjectNumber: pon,
+						charStart: chars.start,
+						charCount: chars.end - chars.start,
+						segments: (0, _embedpdf_engine_core_runtime.textSegmentsForRange)(layout, chars.start, chars.end - chars.start),
+						...mode === "full" ? { snippet: (0, _embedpdf_engine_core_runtime.buildSnippet)(text, range) } : {}
+					});
+				}
 			}
 			scanned++;
 			pagesThisSlice++;
@@ -9001,9 +9360,10 @@ function validatePatchValue(key, value) {
 * worker wire shape from @embedpdf/engine-core.
 */
 var WorkerHost = class {
-	constructor(runtime, post) {
+	constructor(runtime, post, options = {}) {
 		this.runtime = runtime;
 		this.post = post;
+		this.options = options;
 		_defineProperty(this, "sessions", /* @__PURE__ */ new Map());
 		_defineProperty(this, "baseDocuments", void 0);
 		_defineProperty(this, "aborts", /* @__PURE__ */ new Map());
@@ -9029,6 +9389,10 @@ var WorkerHost = class {
 			this.aborts.get(msg.jobId)?.abort();
 			return;
 		}
+		if (msg.kind === "pages.renderEncoded" || msg.kind === "document.renderPageFileEncoded" || msg.kind === "annotations.renderAppearancesEncoded") {
+			this.receiveEncoded(msg);
+			return;
+		}
 		const ctrl = new AbortController();
 		this.aborts.set(msg.jobId, ctrl);
 		let resultPack;
@@ -9132,6 +9496,9 @@ var WorkerHost = class {
 				case "pages.insert":
 					resultPack = this.handlePagesInsert(msg, ctrl.signal);
 					break;
+				case "pages.insertBlank":
+					resultPack = this.handlePagesInsertBlank(msg, ctrl.signal);
+					break;
 				case "attachments.list":
 					resultPack = this.handleAttachmentsList(msg, ctrl.signal);
 					break;
@@ -9424,6 +9791,17 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handlePagesInsertBlank(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesInserter(this.runtime, session).insertBlank({
+			size: req.size,
+			count: req.count
+		}, req.destIndex, signal);
+		return this.finishMutation(session, {
+			tag: "pages.insertBlank",
+			result
+		}, req.artifactPath);
+	}
 	handleAttachmentsList(req, signal) {
 		const session = this.requireSession(req);
 		return (0, _embedpdf_engine_core_runtime.wirePack)({
@@ -9516,6 +9894,105 @@ var WorkerHost = class {
 			raster
 		}, [raster.data]);
 	}
+	async receiveEncoded(msg) {
+		if (!this.options.imageEncoder) {
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: (0, _embedpdf_engine_core_runtime.serializeError)(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "this engine has no image encoder (the *.renderEncoded kinds are cloud-server surface)"))
+			}, _embedpdf_engine_core_runtime.EMPTY_TRANSFER));
+			return;
+		}
+		const ctrl = new AbortController();
+		this.aborts.set(msg.jobId, ctrl);
+		try {
+			let resultPack;
+			switch (msg.kind) {
+				case "pages.renderEncoded":
+					resultPack = await this.handlePagesRenderEncoded(msg, ctrl.signal);
+					break;
+				case "document.renderPageFileEncoded":
+					resultPack = await this.handleDocumentRenderPageFileEncoded(msg, ctrl.signal);
+					break;
+				case "annotations.renderAppearancesEncoded":
+					resultPack = await this.handleAnnotationsRenderAppearancesEncoded(msg, ctrl.signal);
+					break;
+			}
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "resolve",
+				jobId: msg.jobId,
+				result: resultPack.payload
+			}, resultPack.transfer));
+		} catch (err) {
+			this.post((0, _embedpdf_engine_core_runtime.wirePack)({
+				kind: "reject",
+				jobId: msg.jobId,
+				error: (0, _embedpdf_engine_core_runtime.serializeError)(err)
+			}, _embedpdf_engine_core_runtime.EMPTY_TRANSFER));
+		} finally {
+			this.aborts.delete(msg.jobId);
+		}
+	}
+	async encodeRaster(raster, encode, signal) {
+		const encoder = this.options.imageEncoder;
+		if (!encoder) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "this engine has no image encoder (the *.renderEncoded kinds are cloud-server surface)");
+		const { bytes, contentType } = await encoder.encode(raster, encode);
+		if (signal.aborted) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Aborted, "aborted during image encode");
+		return {
+			contentType,
+			width: raster.width,
+			height: raster.height,
+			bytes
+		};
+	}
+	async handlePagesRenderEncoded(req, signal) {
+		const inner = this.handlePagesRender({
+			...req,
+			kind: "pages.render"
+		}, signal);
+		if (inner.payload.tag !== "pages.render") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "pages.renderEncoded",
+			image
+		}, [image.bytes.buffer]);
+	}
+	async handleDocumentRenderPageFileEncoded(req, signal) {
+		const inner = this.handleDocumentRenderPageFile({
+			...req,
+			kind: "document.renderPageFile"
+		}, signal);
+		if (inner.payload.tag !== "document.renderPageFile") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const image = await this.encodeRaster(inner.payload.raster, req.encode, signal);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "document.renderPageFileEncoded",
+			pageObjectNumber: inner.payload.pageObjectNumber,
+			pageCount: inner.payload.pageCount,
+			image
+		}, [image.bytes.buffer]);
+	}
+	async handleAnnotationsRenderAppearancesEncoded(req, signal) {
+		const inner = this.handleAnnotationsRenderAppearances({
+			...req,
+			kind: "annotations.renderAppearances"
+		}, signal);
+		if (inner.payload.tag !== "annotations.renderAppearances") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `unexpected ${inner.payload.tag}`);
+		const { pageState, appearances } = inner.payload.result;
+		const encoded = [];
+		for (const a of appearances) encoded.push({
+			ref: a.ref,
+			mode: a.mode,
+			rect: a.rect,
+			image: await this.encodeRaster(a.raster, req.encode, signal)
+		});
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "annotations.renderAppearancesEncoded",
+			result: {
+				pageState,
+				appearances: encoded
+			}
+		}, encoded.map((e) => e.image.bytes.buffer));
+	}
 	handleDocumentSaveBuffer(req) {
 		const session = this.requireSession(req);
 		const saved = new DocumentSaver(this.runtime, session).saveStandaloneToBuffer(req.mode);
@@ -9860,6 +10337,7 @@ exports.DocumentActionsReader = DocumentActionsReader;
 exports.DocumentPagesMutator = PagesMutator;
 exports.DocumentSaver = DocumentSaver;
 exports.DocumentSession = DocumentSession;
+exports.EPDF_CHAR_GEOMETRY_LAYOUT = EPDF_CHAR_GEOMETRY_LAYOUT;
 exports.EventHub = EventHub;
 exports.FontRegistrar = FontRegistrar;
 exports.FormMutator = FormMutator;
@@ -9885,6 +10363,7 @@ exports.SearchReader = SearchReader;
 exports.SecurityReader = SecurityReader;
 exports.SessionEventPublisher = SessionEventPublisher;
 exports.WorkerHost = WorkerHost;
+exports.buildRunsFromRawGlyphs = buildRunsFromRawGlyphs;
 exports.computeMutationImpact = computeMutationImpact;
 exports.destroyLibrary = destroyLibrary;
 exports.disposeFormModel = disposeFormModel;