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

package/dist/index.cjs

@@ -1732,7 +1732,8 @@ var PagesReader = class {
 			});
 			return {
 				pageCount: pages.length,
-				pages
+				pages,
+				namedPages: readNamedPages(fn, mem, docPtr)
 			};
 		});
 	}
@@ -1797,6 +1798,41 @@ function readUserUnit(fn, mem, docPtr, index, userUnitPtr) {
 function readLabel(fn, mem, docPtr, index) {
 	return readUtf16String(mem, (buf, capacity) => fn.FPDF_GetPageLabel(docPtr, index, buf, capacity), null) || null;
 }
+const NAMED_PAGE_TREES = [0, 1];
+const NAMED_PAGE_KIND_PAGE = 0;
+const NAMED_PAGE_KIND_TEMPLATE = 1;
+/**
+* The catalog's `/Names /Pages` and `/Names /Templates` registrations, in
+* tree order, each value classified by the fork (page / template /
+* dangling). Page-identity data like `label`, so it ships inside the same
+* snapshot — a registration is only meaningful against the page set that
+* contains its target.
+*/
+function readNamedPages(fn, mem, docPtr) {
+	const entries = [];
+	withScratchN(mem, [4, 4], ([objNumPtr, kindPtr]) => {
+		for (const tree of NAMED_PAGE_TREES) {
+			const count = fn.EPDFDoc_GetNamedPageCount(docPtr, tree);
+			for (let index = 0; index < count; index++) {
+				const name = readUtf16String(mem, (buf, capacity) => fn.EPDFDoc_GetNamedPageAt(docPtr, tree, index, buf, capacity, objNumPtr, kindPtr), "");
+				if (name === null) continue;
+				const objectNumber = Number(mem.peek(objNumPtr, "i32")) >>> 0;
+				const kind = Number(mem.peek(kindPtr, "i32"));
+				entries.push({
+					name,
+					target: kind === NAMED_PAGE_KIND_PAGE ? {
+						kind: "page",
+						pageObjectNumber: objectNumber
+					} : kind === NAMED_PAGE_KIND_TEMPLATE ? {
+						kind: "template",
+						objectNumber
+					} : { kind: "dangling" }
+				});
+			}
+		}
+	});
+	return entries;
+}
 //#endregion
 //#region src/features/pages/PagesMutator.ts
 /**
@@ -1944,6 +1980,38 @@ var PagesMutator = class {
 			cache: null
 		};
 	}
+	/**
+	* Register `name` → page in `/Names /Pages` (create, or replace what the
+	* key points at); with `replace`, drop that other key first — a rename as
+	* one job. Named pages are LAYOUT: page identity and order are untouched
+	* (no registry refresh, no revision bumps) and the fresh snapshot is
+	* returned like `move()`.
+	*/
+	setName(input, signal) {
+		throwIfAborted(signal);
+		if (input.name.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "pages.setName requires a non-empty name");
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		this.session.recordByObjectNumber(input.pageObjectNumber);
+		if (input.replace !== void 0 && input.replace !== input.name && input.replace.length > 0) writeUtf16String(mem, input.replace, (ptr) => fn.EPDFDoc_RemoveNamedPage(docPtr, ptr));
+		if (!writeUtf16String(mem, input.name, (ptr) => fn.EPDFDoc_SetNamedPage(docPtr, ptr, input.pageObjectNumber))) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, `EPDFDoc_SetNamedPage rejected '${input.name}' for page ${input.pageObjectNumber}`);
+		return {
+			layout: new PagesReader(this.runtime, this.session).read(signal),
+			cache: null
+		};
+	}
+	/** Remove one `/Names /Pages` registration; the page stays. */
+	removeName(input, signal) {
+		throwIfAborted(signal);
+		if (input.name.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "pages.removeName requires a non-empty name");
+		const { fn, mem } = this.runtime;
+		const docPtr = this.session.requireDocPtr();
+		if (!writeUtf16String(mem, input.name, (ptr) => fn.EPDFDoc_RemoveNamedPage(docPtr, ptr))) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `pages.removeName: no /Names /Pages registration '${input.name}'`);
+		return {
+			layout: new PagesReader(this.runtime, this.session).read(signal),
+			cache: null
+		};
+	}
 	/** Shared input check: non-empty, no duplicate PONs. */
 	requireUniquePons(op, pageObjectNumbers) {
 		if (pageObjectNumbers.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} requires at least one page`);
@@ -1956,7 +2024,7 @@ var PagesMutator = class {
 };
 //#endregion
 //#region src/features/pages/PagesExtractor.ts
-const FPDF_NO_INCREMENTAL$1 = 2;
+const FPDF_NO_INCREMENTAL$2 = 2;
 /**
 * Export a subset of pages as a standalone PDF. A READ over the session:
 * `FPDF_ImportPagesByIndex` copies pages into a scratch document, so the
@@ -1995,7 +2063,7 @@ var PagesExtractor = class {
 			for (let i = 0; i < indices.length; i++) mem.poke(idxPtr, "i32", indices[i], 4 * i);
 			if (!fn.FPDF_ImportPagesByIndex(destPtr, srcPtr, idxPtr, indices.length, 0)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, `FPDF_ImportPagesByIndex rejected the request (indices=[${indices.join(",")}])`);
 			mem.poke(sizePtr, "i32", 0);
-			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(destPtr, FPDF_NO_INCREMENTAL$1, sizePtr);
+			pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(destPtr, FPDF_NO_INCREMENTAL$2, sizePtr);
 			const size = Number(mem.peek(sizePtr, "i32"));
 			if (!pdfPtr || size <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed, "failed to save extracted pages");
 			const bytes = mem.readBytes(pdfPtr, size);
@@ -2547,6 +2615,13 @@ function readQuadPoints(fn, mem, annotPtr) {
 		return out;
 	});
 }
+/**
+* `/Name` as text, whatever its value (`EPDFAnnot_GetName`): a standard
+* icon/stamp name or a custom identifier. `null` when absent.
+*/
+function readAnnotName(fn, mem, annotPtr) {
+	return readUtf8String(mem, (buf, capacity) => fn.EPDFAnnot_GetName(annotPtr, buf, capacity));
+}
 //#endregion
 //#region src/features/annotations/internal/read/readAnnotationTransformMetadata.ts
 /**
@@ -2796,29 +2871,29 @@ function normalizeChecksum(raw) {
 //#endregion
 //#region src/features/annotations/internal/annotationIcon.ts
 /**
-* `/Name` icon ↔ `FPDF_ANNOT_NAME` enum code mapping for text and
-* file-attachment annotations (`EPDFAnnot_SetName` / `EPDFAnnot_GetName`).
-* Codes mirror the `FPDF_ANNOT_NAME` enum in `public/fpdf_annot.h` —
-* same pattern as `stampName.ts` (whose stamp block starts at 13, right
-* after these) keeping engine-core PDFium-free.
-*/
-const NOTE_ICON_TO_CODE = Object.freeze({
-	comment: 0,
-	key: 1,
-	note: 2,
-	help: 3,
-	"new-paragraph": 4,
-	paragraph: 5,
-	insert: 6
+* `/Name` icon vocabulary ↔ PDF name mapping for text and file-attachment
+* annotations (ISO 32000-2 tables 175 and 184). The wire speaks the
+* kebab-case ids; `EPDFAnnot_SetName` / `EPDFAnnot_GetName` speak the PDF
+* names. An unknown PDF name reads as the subtype's default (the reader
+* draws the default glyph for names it does not know — spec behavior).
+*/
+const NOTE_ICON_TO_NAME = Object.freeze({
+	comment: "Comment",
+	key: "Key",
+	note: "Note",
+	help: "Help",
+	"new-paragraph": "NewParagraph",
+	paragraph: "Paragraph",
+	insert: "Insert"
 });
-const NOTE_CODE_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(NOTE_ICON_TO_CODE).map(([icon, code]) => [code, icon])));
-const FILE_ICON_TO_CODE = Object.freeze({
-	graph: 7,
-	"push-pin": 8,
-	paperclip: 9,
-	tag: 10
+const NOTE_NAME_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(NOTE_ICON_TO_NAME).map(([icon, name]) => [name, icon])));
+const FILE_ICON_TO_NAME = Object.freeze({
+	graph: "Graph",
+	"push-pin": "PushPin",
+	paperclip: "Paperclip",
+	tag: "Tag"
 });
-const FILE_CODE_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(FILE_ICON_TO_CODE).map(([icon, code]) => [code, icon])));
+const FILE_NAME_TO_ICON = Object.freeze(Object.fromEntries(Object.entries(FILE_ICON_TO_NAME).map(([icon, name]) => [name, icon])));
 //#endregion
 //#region src/features/annotations/internal/read/readFileAttachmentAnnotation.ts
 /** Default `/C` — matches the generator's default icon fill and the writer default. */
@@ -2840,7 +2915,7 @@ function readFileAttachment(fn, mem, annotPtr, base) {
 	const color = readAnnotColor(fn, mem, annotPtr) ?? { ...DEFAULT_FILE_ATTACHMENT_COLOR$1 };
 	const ca = readAnnotOpacity(fn, mem, annotPtr);
 	const opacity = ca == null ? 1 : Math.max(0, Math.min(1, ca));
-	const icon = FILE_CODE_TO_ICON[fn.EPDFAnnot_GetName(annotPtr)] ?? DEFAULT_FILE_ATTACHMENT_ICON;
+	const icon = FILE_NAME_TO_ICON[readAnnotName(fn, mem, annotPtr) ?? ""] ?? DEFAULT_FILE_ATTACHMENT_ICON;
 	const attachmentPtr = fn.FPDFAnnot_GetFileAttachment(annotPtr);
 	const file = attachmentPtr ? readAttachmentFileInfo(fn, mem, attachmentPtr) : { name: "" };
 	return {
@@ -3309,45 +3384,10 @@ function readSquare(fn, mem, annotPtr, base) {
 	};
 }
 //#endregion
-//#region src/features/annotations/internal/stampName.ts
-/**
-* Stamp `/Name` label ↔ `FPDF_ANNOT_NAME` enum code mapping for the
-* `EPDFAnnot_SetName` / `EPDFAnnot_GetName` fork helpers. Labels are the
-* PDF spec / Adobe literal name values (ISO 32000 §12.5.6.12 table 181
-* plus the Adobe SB/SH extended set the fork supports). Codes mirror the
-* `FPDF_ANNOT_NAME` enum in `public/fpdf_annot.h` — same pattern as
-* `lineEnding.ts` keeping engine-core PDFium-free.
-*/
-const STAMP_NAME_TO_CODE = Object.freeze({
-	Approved: 13,
-	Experimental: 14,
-	NotApproved: 15,
-	AsIs: 16,
-	Expired: 17,
-	NotForPublicRelease: 18,
-	Confidential: 19,
-	Final: 20,
-	Sold: 21,
-	Departmental: 22,
-	ForComment: 23,
-	TopSecret: 24,
-	Draft: 25,
-	ForPublicRelease: 26,
-	Completed: 27,
-	Void: 28,
-	PreliminaryResults: 29,
-	InformationOnly: 30,
-	Rejected: 31,
-	Witness: 32,
-	InitialHere: 33,
-	SignHere: 34,
-	Accepted: 35
-});
-const STAMP_CODE_TO_NAME = Object.freeze(Object.fromEntries(Object.entries(STAMP_NAME_TO_CODE).map(([name, code]) => [code, name])));
-//#endregion
 //#region src/features/annotations/internal/read/readStampAnnotation.ts
 /**
-* Stamp DTO: base + `/Name` label + transform metadata. The visual content
+* Stamp DTO: base + `/Name` (standard or custom identifier, verbatim) +
+* transform metadata. The visual content
 * stays in the `/AP` stream — rendered via `renderAppearanceImages()`,
 * never surfaced as DTO data.
 */
@@ -3357,16 +3397,11 @@ function readStamp(fn, mem, annotPtr, base) {
 	return {
 		...base,
 		subtype: "stamp",
-		name: readStampName(fn, mem, annotPtr),
+		name: readAnnotName(fn, mem, annotPtr),
 		...rotation != null ? { rotation } : {},
 		...unrotatedRect != null ? { unrotatedRect } : {}
 	};
 }
-function readStampName(fn, mem, annotPtr) {
-	const known = STAMP_CODE_TO_NAME[fn.EPDFAnnot_GetName(annotPtr)];
-	if (known !== void 0) return known;
-	return readAnnotString(fn, mem, annotPtr, "Name");
-}
 //#endregion
 //#region src/features/annotations/internal/annotationState.ts
 /**
@@ -3422,7 +3457,7 @@ function readText(fn, mem, annotPtr, base) {
 	const color = readAnnotColor(fn, mem, annotPtr) ?? { ...DEFAULT_NOTE_COLOR$1 };
 	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 icon = NOTE_NAME_TO_ICON[readAnnotName(fn, mem, annotPtr) ?? ""] ?? DEFAULT_NOTE_ICON;
 	const stateRaw = readAnnotString(fn, mem, annotPtr, "State");
 	const stateModelRaw = readAnnotString(fn, mem, annotPtr, "StateModel");
 	return {
@@ -5444,7 +5479,7 @@ 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");
+	if (!fn.EPDFAnnot_SetName(annotPtr, FILE_ICON_TO_NAME[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 function requireFileResource(file, ctx) {
 	const resource = ctx?.resources?.[file.resource];
@@ -6106,12 +6141,12 @@ const STAMP_FIT_TO_CODE = {
 * creating an annotation or strengthening a weak annotation id.
 */
 function preflightStampDraft(draft, ctx) {
-	if (draft.name !== void 0) requireStampNameCode(draft.name);
+	if (draft.name !== void 0) requireStampName(draft.name);
 	requireStampFit(draft.fit ?? "contain");
 	requireStampContent(draft.source, ctx);
 }
 function preflightStampPatch(patch, ctx) {
-	if (patch.name !== void 0) requireStampNameCode(patch.name);
+	if (patch.name !== void 0 && patch.name !== null) requireStampName(patch.name);
 	requireStampFit(patch.fit ?? "contain");
 	if (patch.source !== void 0) requireStampContent(patch.source, ctx);
 }
@@ -6137,7 +6172,8 @@ function applyStampDraft(fn, mem, annotPtr, draft, ctx) {
 }
 function applyStampPatch(fn, mem, annotPtr, patch, ctx) {
 	applyAnnotationBasePatch(fn, mem, annotPtr, patch);
-	if (patch.name !== void 0) setStampName(fn, annotPtr, patch.name);
+	if (patch.name === null) fn.EPDFAnnot_RemoveKey(annotPtr, "Name");
+	else if (patch.name !== void 0) setStampName(fn, annotPtr, patch.name);
 	if (patch.source !== void 0) {
 		const rect = patch.rect ?? readAnnotRect(fn, mem, annotPtr);
 		authorStampAppearance(fn, mem, annotPtr, patch.source, patch.fit ?? "contain", {
@@ -6157,15 +6193,14 @@ function applyStampPatch(fn, mem, annotPtr, patch, ctx) {
 function isStampSubtype(subtype) {
 	return subtype === "stamp";
 }
+/** Any non-empty name: standard ('Approved') or custom ('#LBGiYhk8V…') —
+*  the fork writes a name object and escapes it; predefined sets are a
+*  reader concern (ISO 32000-2 table 187 allows additional names). */
 function setStampName(fn, annotPtr, name) {
-	const code = STAMP_NAME_TO_CODE[name];
-	if (code === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "stamp name preflight invariant broken");
-	if (!fn.EPDFAnnot_SetName(annotPtr, code)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, name)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
-function requireStampNameCode(name) {
-	const code = STAMP_NAME_TO_CODE[name];
-	if (code === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `unknown stamp name '${name}'; supported names: ${Object.keys(STAMP_NAME_TO_CODE).join(", ")}`);
-	return code;
+function requireStampName(name) {
+	if (name.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "stamp name must be non-empty");
 }
 function requireStampFit(fit) {
 	if (STAMP_FIT_TO_CODE[fit] === void 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `unknown stamp fit '${String(fit)}'; expected contain, cover, or fill`);
@@ -6353,7 +6388,7 @@ function isTextSubtype(subtype) {
 	return subtype === "text";
 }
 function setNoteIcon(fn, annotPtr, icon) {
-	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_CODE[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
+	if (!fn.EPDFAnnot_SetName(annotPtr, NOTE_ICON_TO_NAME[icon])) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, "EPDFAnnot_SetName returned false");
 }
 //#endregion
 //#region src/features/annotations/internal/write/writeVertexAnnotation.ts
@@ -7080,6 +7115,141 @@ var AnnotationMutator = class {
 	}
 };
 //#endregion
+//#region src/features/annotations/AnnotationFlattener.ts
+const FLATTEN_FAIL$1 = 0;
+const FLATTEN_SUCCESS$1 = 1;
+const FLATTEN_NOTHING_TO_DO$1 = 2;
+const STATUS_APPLIED = 0;
+const STATUS_NOT_ON_PAGE = 2;
+const FPDF_NO_INCREMENTAL$1 = 2;
+/**
+* The annotation-plane flatten verbs — `pages.flatten` for a chosen set:
+* in place (`flatten`) or into a new single-page document
+* (`exportAppearance`). Both resolve refs to native handles on the page,
+* hand the SET to the fork (one candidate plan, one placement writer — the
+* same code whole-page flatten runs), and release every handle afterwards.
+*/
+var AnnotationFlattener = class {
+	constructor(runtime, session) {
+		this.runtime = runtime;
+		this.session = session;
+	}
+	flatten(pageObjectNumber, refs, usage, signal) {
+		throwIfAborted(signal);
+		this.requireRefs("annotations.flatten", pageObjectNumber, refs);
+		const { fn, mem } = this.runtime;
+		const pool = this.session.pagePool();
+		const pagePtr = pool.acquire(pageObjectNumber);
+		try {
+			const annotPtrs = this.resolveAll(pagePtr, refs);
+			let code;
+			let statuses;
+			try {
+				[code, statuses] = this.withHandleArray(annotPtrs, (arrayPtr) => withScratch(mem, 4 * refs.length, (statusPtr) => {
+					const rc = fn.EPDFPage_FlattenAnnotations(pagePtr, arrayPtr, refs.length, usage === "print" ? 1 : 0, statusPtr);
+					const out = [];
+					for (let i = 0; i < refs.length; i++) out.push(Number(mem.peek(statusPtr, "i32", 4 * i)));
+					return [rc, out];
+				}));
+			} finally {
+				for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+			if (code === FLATTEN_FAIL$1) {
+				const foreign = statuses.findIndex((status) => status === STATUS_NOT_ON_PAGE);
+				throw new _embedpdf_engine_core_runtime.EngineError(foreign >= 0 ? _embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg : _embedpdf_engine_core_runtime.EngineErrorCode.Unknown, foreign >= 0 ? `annotations.flatten: ref ${foreign} is not an annotation of page ${pageObjectNumber}` : "native annotation flatten failed after preflight");
+			}
+			const results = refs.map((ref, i) => ({
+				ref,
+				status: statuses[i] === STATUS_APPLIED ? "applied" : "skipped"
+			}));
+			if (code === FLATTEN_NOTHING_TO_DO$1 || code !== FLATTEN_SUCCESS$1) return {
+				pageObjectNumber,
+				usage,
+				results,
+				meta: null
+			};
+			this.session.noteMutation();
+			this.session.bumpRevision(pageObjectNumber);
+			try {
+				new AnnotationReader(this.runtime, this.session).list(pageObjectNumber, signal);
+			} catch {}
+			return {
+				pageObjectNumber,
+				usage,
+				results,
+				meta: {
+					affectedPages: [this.session.pageState(pageObjectNumber)],
+					cacheDelta: null
+				}
+			};
+		} finally {
+			pool.release(pageObjectNumber);
+		}
+	}
+	exportAppearance(pageObjectNumber, refs, signal) {
+		throwIfAborted(signal);
+		this.requireRefs("annotations.exportAppearance", pageObjectNumber, refs);
+		const { fn, mem } = this.runtime;
+		const pool = this.session.pagePool();
+		const pagePtr = pool.acquire(pageObjectNumber);
+		let exportedPtr = null;
+		let pdfPtr = null;
+		try {
+			const annotPtrs = this.resolveAll(pagePtr, refs);
+			try {
+				exportedPtr = this.withHandleArray(annotPtrs, (arrayPtr) => fn.EPDFPage_ExportAnnotationsAsDocument(pagePtr, arrayPtr, refs.length));
+			} finally {
+				for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			}
+			if (!exportedPtr) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "annotations.exportAppearance: every ref must be a visible annotation of this page with a normal appearance");
+			return withScratch(mem, 4, (sizePtr) => {
+				mem.poke(sizePtr, "i32", 0);
+				pdfPtr = fn.EPDF_SaveDocumentToOwnedBuffer(exportedPtr, FPDF_NO_INCREMENTAL$1, sizePtr);
+				const size = Number(mem.peek(sizePtr, "i32"));
+				if (!pdfPtr || size <= 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed, "failed to save exported appearances");
+				const bytes = mem.readBytes(pdfPtr, size);
+				const buffer = new ArrayBuffer(bytes.byteLength);
+				new Uint8Array(buffer).set(bytes);
+				return {
+					bytes: buffer,
+					size
+				};
+			});
+		} finally {
+			if (pdfPtr) fn.EPDF_FreeBuffer(pdfPtr);
+			if (exportedPtr) fn.FPDF_CloseDocument(exportedPtr);
+			pool.release(pageObjectNumber);
+		}
+	}
+	/** Resolve every ref on `pagePtr` (NotFound / InvalidReference from the
+	*  resolver on caller error); on any failure, close what was opened. */
+	resolveAll(pagePtr, refs) {
+		const { fn } = this.runtime;
+		const annotPtrs = [];
+		try {
+			for (const ref of refs) annotPtrs.push(resolveAnnotPtr(this.runtime, this.session, pagePtr, ref));
+			return annotPtrs;
+		} catch (error) {
+			for (const annotPtr of annotPtrs) fn.FPDFPage_CloseAnnot(annotPtr);
+			throw error;
+		}
+	}
+	/** Marshal an `FPDF_ANNOTATION*` array for the call's duration. */
+	withHandleArray(annotPtrs, body) {
+		const { mem } = this.runtime;
+		const isWasm = this.runtime.kind === "wasm";
+		const ptrSize = isWasm ? 4 : 8;
+		return withScratch(mem, Math.max(1, annotPtrs.length * ptrSize), (arrayPtr) => {
+			annotPtrs.forEach((ptr, i) => isWasm ? mem.poke(arrayPtr, "i32", Number(ptr), i * 4) : mem.poke(arrayPtr, "i64", ptr, i * 8));
+			return body(arrayPtr);
+		});
+	}
+	requireRefs(op, pageObjectNumber, refs) {
+		if (refs.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} requires at least one ref`);
+		for (const ref of refs) if (ref.pageObjectNumber !== pageObjectNumber) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `${op} refs must all target page ${pageObjectNumber}; got ref on page ${ref.pageObjectNumber}`);
+	}
+};
+//#endregion
 //#region src/features/pages/PagesFlattener.ts
 const FLATTEN_FAIL = 0;
 const FLATTEN_SUCCESS = 1;
@@ -9686,6 +9856,18 @@ var WorkerHost = class {
 				case "pages.delete":
 					resultPack = this.handlePagesDelete(msg, ctrl.signal);
 					break;
+				case "pages.setName":
+					resultPack = this.handlePagesSetName(msg, ctrl.signal);
+					break;
+				case "annotations.flatten":
+					resultPack = this.handleAnnotationsFlatten(msg, ctrl.signal);
+					break;
+				case "annotations.exportAppearance":
+					resultPack = this.handleAnnotationsExportAppearance(msg, ctrl.signal);
+					break;
+				case "pages.removeName":
+					resultPack = this.handlePagesRemoveName(msg, ctrl.signal);
+					break;
 				case "pages.flatten":
 					resultPack = this.handlePagesFlatten(msg, ctrl.signal);
 					break;
@@ -9913,6 +10095,27 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handleAnnotationsFlatten(req, signal) {
+		const session = this.requireSession(req);
+		const result = new AnnotationFlattener(this.runtime, session).flatten(req.pageObjectNumber, req.refs, req.usage, signal);
+		if (result.meta === null) return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "annotations.flatten",
+			result
+		});
+		return this.finishMutation(session, {
+			tag: "annotations.flatten",
+			result
+		}, req.artifactPath);
+	}
+	handleAnnotationsExportAppearance(req, signal) {
+		const session = this.requireSession(req);
+		const exported = new AnnotationFlattener(this.runtime, session).exportAppearance(req.pageObjectNumber, req.refs, signal);
+		return (0, _embedpdf_engine_core_runtime.wirePack)({
+			tag: "annotations.exportAppearance",
+			bytes: exported.bytes,
+			size: exported.size
+		}, [exported.bytes]);
+	}
 	handleAnnotationsMove(req, signal) {
 		const session = this.requireSession(req);
 		const result = new AnnotationMutator(this.runtime, session).move(req.pageObjectNumber, req.refs, req.toIndex, signal);
@@ -9952,6 +10155,26 @@ var WorkerHost = class {
 			result
 		}, req.artifactPath);
 	}
+	handlePagesSetName(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesMutator(this.runtime, session).setName({
+			name: req.name,
+			pageObjectNumber: req.pageObjectNumber,
+			...req.replace !== void 0 ? { replace: req.replace } : {}
+		}, signal);
+		return this.finishMutation(session, {
+			tag: "pages.setName",
+			result
+		}, req.artifactPath);
+	}
+	handlePagesRemoveName(req, signal) {
+		const session = this.requireSession(req);
+		const result = new PagesMutator(this.runtime, session).removeName({ name: req.name }, signal);
+		return this.finishMutation(session, {
+			tag: "pages.removeName",
+			result
+		}, req.artifactPath);
+	}
 	handlePagesFlatten(req, signal) {
 		const session = this.requireSession(req);
 		const result = new PagesFlattener(this.runtime, session).flatten(req.pageObjectNumbers, req.usage, signal);
@@ -10529,6 +10752,7 @@ function passwordRequiredProbe() {
 exports.ALL_STANDARD_SECURITY_PERMISSIONS = ALL_STANDARD_SECURITY_PERMISSIONS;
 exports.ActionReadBudgetTracker = ActionReadBudgetTracker;
 exports.AnnotationAppearanceReader = AnnotationAppearanceReader;
+exports.AnnotationFlattener = AnnotationFlattener;
 exports.AnnotationMutator = AnnotationMutator;
 exports.AnnotationReader = AnnotationReader;
 exports.AttachmentMutator = AttachmentMutator;