@embedpdf/engine-services 3.0.0-next.3 → 3.0.0-next.5

package/dist/index.cjs

@@ -1164,13 +1164,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`. */
@@ -2154,6 +2175,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 +2252,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 +2680,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 = {
@@ -4131,17 +4156,21 @@ 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
 ]);
 /**
 * Maps an `AnnotationAppearanceMode` onto the PDFium appearance-mode int and
@@ -4830,102 +4859,281 @@ 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);
 }
-//#endregion
-//#region src/features/annotations/internal/write/writeFileAttachmentAnnotation.ts
-/** Default `/C` — the generator's default icon fill, set explicitly so reads round-trip. */
-const DEFAULT_FILE_ATTACHMENT_COLOR = {
-	r: 255,
-	g: 255,
-	b: 0
-};
-const DEFAULT_OPACITY$3 = 1;
-/**
-* Validate a file-attachment draft before any native write: the wire
-* `file.resource` ref must have arrived with the mutation. No format
-* sniffing — unlike stamps, ANY bytes are a valid attachment.
-*/
-function preflightFileAttachmentDraft(draft, ctx) {
-	requireFileResource(draft.file, ctx);
-	if (ctx?.docPtr === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "file-attachment writer requires docPtr on the write context");
+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
 /**
-* Apply a file-attachment draft. Order:
-*   1. base author-metadata (contents/nm/flags)
-*   2. `/Rect` + `/C` + `/CA` + `/Name` icon
-*   3. the embedded file: `/FS` filespec via `FPDFAnnot_AddFileAttachment`,
-*      bytes via `FPDFAttachment_SetFile` (which also writes `/Params`
-*      Size/CheckSum/CreationDate), declared mime via
-*      `EPDFAttachment_SetSubtype`, optional `/Desc`.
+* Write the EmbedPDF transform keys under /EMBD_Metadata. This is the seam
+* PDFium's native AP generator reads to bake a ROTATED appearance:
 *
-* The icon appearance itself is generator-owned: the mutator's closing
-* `regenerateAppearance` bakes it from `/C` + `/Name`
-* (GenerateFileAttachmentAP), exactly like the text note.
-*/
-function applyFileAttachmentDraft(fn, mem, annotPtr, draft, ctx) {
-	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
-	setAnnotRect(fn, mem, annotPtr, draft.rect);
-	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_FILE_ATTACHMENT_COLOR);
-	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY$3);
-	setFileAttachmentIcon(fn, annotPtr, draft.icon ?? "paperclip");
-	attachFile(fn, mem, annotPtr, draft.file, requireFileResource(draft.file, ctx), ctx.docPtr);
-}
-/** Patch: presentation only — the attached file is create-only by design. */
-function applyFileAttachmentPatch(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.icon !== void 0) setFileAttachmentIcon(fn, annotPtr, patch.icon);
-}
-function isFileAttachmentSubtype(subtype) {
-	return subtype === "file-attachment";
-}
-function setFileAttachmentIcon(fn, annotPtr, icon) {
+*   /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
+/** Default `/C` — the generator's default icon fill, set explicitly so reads round-trip. */
+const DEFAULT_FILE_ATTACHMENT_COLOR = {
+	r: 255,
+	g: 255,
+	b: 0
+};
+const DEFAULT_OPACITY$3 = 1;
+/**
+* Validate a file-attachment draft before any native write: the wire
+* `file.resource` ref must have arrived with the mutation. No format
+* sniffing — unlike stamps, ANY bytes are a valid attachment.
+*/
+function preflightFileAttachmentDraft(draft, ctx) {
+	requireFileResource(draft.file, ctx);
+	if (ctx?.docPtr === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "file-attachment writer requires docPtr on the write context");
+}
+/**
+* Apply a file-attachment draft. Order:
+*   1. base author-metadata (contents/nm/flags)
+*   2. `/Rect` + `/C` + `/CA` + `/Name` icon
+*   3. the embedded file: `/FS` filespec via `FPDFAnnot_AddFileAttachment`,
+*      bytes via `FPDFAttachment_SetFile` (which also writes `/Params`
+*      Size/CheckSum/CreationDate), declared mime via
+*      `EPDFAttachment_SetSubtype`, optional `/Desc`.
+*
+* The icon appearance itself is generator-owned: the mutator's closing
+* `regenerateAppearance` bakes it from `/C` + `/Name`
+* (GenerateFileAttachmentAP), exactly like the text note.
+*/
+function applyFileAttachmentDraft(fn, mem, annotPtr, draft, ctx) {
+	applyAnnotationBaseDraft(fn, mem, annotPtr, draft);
+	setAnnotRect(fn, mem, annotPtr, draft.rect);
+	setAnnotColor(fn, annotPtr, draft.color ?? DEFAULT_FILE_ATTACHMENT_COLOR);
+	setAnnotOpacity(fn, annotPtr, draft.opacity ?? DEFAULT_OPACITY$3);
+	setFileAttachmentIcon(fn, annotPtr, draft.icon ?? "paperclip");
+	attachFile(fn, mem, annotPtr, draft.file, requireFileResource(draft.file, ctx), ctx.docPtr);
+}
+/** Patch: presentation only — the attached file is create-only by design. */
+function applyFileAttachmentPatch(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.icon !== void 0) setFileAttachmentIcon(fn, annotPtr, patch.icon);
+}
+function isFileAttachmentSubtype(subtype) {
+	return subtype === "file-attachment";
+}
+function setFileAttachmentIcon(fn, annotPtr, icon) {
 	if (!fn.EPDFAnnot_SetName(annotPtr, FILE_ICON_TO_CODE[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 function requireFileResource(file, ctx) {
@@ -5040,177 +5248,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
@@ -6971,17 +7008,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 +7062,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.
 *
-* 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.
+* 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.
 *
-* 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.
+* Both come from the fork's batched extension calls, which share one
+* encoding authority (`FX_UTF16Encode`) so text and map can never
+* disagree:
+*
+*   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+*     characters arrive as surrogate pairs instead of being silently
+*     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+*     upper-bound buffer (2 units per character + NUL), so no measure
+*     round-trip.
+*   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+*     anchors is the common (identity) page and skips the fill call.
 */
 var PageTextReader = class {
 	constructor(runtime, session) {
@@ -7032,7 +7090,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 +7099,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 +7120,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 +7187,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 +7197,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 +7225,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 +8797,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 +8822,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 +8944,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++;
@@ -9860,6 +10100,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 +10126,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;