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

package/dist/conformance.js

@@ -1,7 +1,7 @@
 import { f as pdfQuadBounds, i as EngineError, n as foldText, u as isRotatedGeometryRun } from "./fold-BfyxxwS6.js";
 import { f as EngineErrorCode, o as sliceTextByChars } from "./PageInsertBlankInput-WKY0tr6S.js";
 import { t as AbortError } from "./AbortError-8-9JAX1Y.js";
-import { A as FormSetValueResultSchema, B as PageDeleteResultSchema, O as FormImportResultSchema, Ot as FormSnapshotSchema, Pt as AnnotationDTOSchema, U as PageFlattenResultSchema, W as PageGeometrySnapshotSchema, Y as PageListSnapshotSchema, Z as PageMoveResultSchema, a as AnnotationCreateResultSchema, at as PageTextSnapshotSchema, c as AnnotationListPageSnapshotSchema, d as AnnotationUpdateResultSchema, k as FormRepairResultSchema, l as AnnotationListSnapshotAllPagesSchema, mt as SearchSliceSchema, nt as PageRotateResultSchema, o as AnnotationDeleteResultSchema, pr as DocumentActionsSnapshotSchema, st as RedactionApplyResultSchema, u as AnnotationMoveResultSchema } from "./schemas-XGrNVMDd.js";
+import { $ as PageListSnapshotSchema, Ft as FormSnapshotSchema, J as PageGeometrySnapshotSchema, M as FormRepairResultSchema, N as FormSetValueResultSchema, Vt as AnnotationDTOSchema, W as PageDeleteResultSchema, br as DocumentActionsSnapshotSchema, d as AnnotationListPageSnapshotSchema, f as AnnotationListSnapshotAllPagesSchema, ft as PageTextSnapshotSchema, j as FormImportResultSchema, l as AnnotationFlattenResultSchema, lt as PageRotateResultSchema, m as AnnotationUpdateResultSchema, mt as RedactionApplyResultSchema, o as AnnotationCreateResultSchema, p as AnnotationMoveResultSchema, q as PageFlattenResultSchema, rt as PageNameResultSchema, s as AnnotationDeleteResultSchema, tt as PageMoveResultSchema, xt as SearchSliceSchema } from "./schemas-DOyVEPk7.js";
 //#region src/conformance/runMetadataConformance.ts
 /**
 * The conformance harness is transport-agnostic. It takes the test runner as
@@ -18,7 +18,7 @@ function runMetadataConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("reads metadata from sample fixture", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			try {
 				const meta = await doc.metadata.read();
 				expect(meta).toMatchObject(opts.fixture.expected);
@@ -28,7 +28,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("abort() before completion rejects with AbortError", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			try {
 				const p = doc.metadata.read();
 				p.abort("test");
@@ -38,7 +38,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("aborting one read does not affect a concurrent one", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			try {
 				const a = doc.metadata.read();
 				const b = doc.metadata.read();
@@ -50,7 +50,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("metadata after close throws DocNotOpen", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			await doc.close();
 			let caught;
 			try {
@@ -62,7 +62,7 @@ function runMetadataConformance(runner, opts) {
 			expect(EngineError.is(caught, EngineErrorCode.DocNotOpen)).toBe(true);
 		});
 		test("update() sets standard + custom fields and a subsequent read observes them", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			try {
 				const result = await doc.metadata.update({
 					title: "Conformance Title",
@@ -81,7 +81,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("update() clears a field with null", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			try {
 				await doc.metadata.update({ title: "To Be Cleared" });
 				const set = await doc.metadata.read();
@@ -94,7 +94,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("update() after close throws DocNotOpen", async () => {
-			const doc = await openFixture$17(engine, opts);
+			const doc = await openFixture$20(engine, opts);
 			await doc.close();
 			let caught;
 			try {
@@ -107,7 +107,7 @@ function runMetadataConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$17(engine, opts) {
+async function openFixture$20(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -134,7 +134,7 @@ function runAnnotationReadConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("listRawAll returns one entry per page with valid PageState", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const snap = await doc.annotations.listRawAll();
 				expect(AnnotationListSnapshotAllPagesSchema.safeParse(snap).success).toBe(true);
@@ -148,7 +148,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("listRaw on the test page returns the expected counts and DTO shape", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				expect(AnnotationListPageSnapshotSchema.safeParse(snap).success).toBe(true);
@@ -178,7 +178,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("shape/vertex/line annotations expose their family fields", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				for (const a of snap.annotations) {
@@ -237,7 +237,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("full page list dispatches per-subtype and matches raw counts", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const full = await doc.page(opts.fixture.pageObjectNumber).annotations.list();
 				expect(AnnotationListPageSnapshotSchema.safeParse(full).success).toBe(true);
@@ -247,7 +247,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("every annotation DTO satisfies AnnotationDTOSchema (discriminated union)", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				for (const a of snap.annotations) {
@@ -287,7 +287,7 @@ function runAnnotationReadConformance(runner, opts) {
 		});
 		if (opts.fixture.expectsWeakAnnotation) {
 			test("weak annotations carry identityQuality: weak and ref.kind: index", async () => {
-				const doc = await openFixture$16(engine, opts);
+				const doc = await openFixture$19(engine, opts);
 				try {
 					const weak = (await doc.annotations.listRaw(opts.fixture.pageObjectNumber)).annotations.find((a) => a.identityQuality === "weak");
 					expect(weak !== void 0).toBe(true);
@@ -297,7 +297,7 @@ function runAnnotationReadConformance(runner, opts) {
 				}
 			});
 			test("a stale revision token throws InvalidReference", async () => {
-				const doc = await openFixture$16(engine, opts);
+				const doc = await openFixture$19(engine, opts);
 				try {
 					const snap = await doc.page(opts.fixture.pageObjectNumber).annotations.list();
 					const weak = snap.annotations.find((a) => a.identityQuality === "weak");
@@ -313,7 +313,7 @@ function runAnnotationReadConformance(runner, opts) {
 			});
 		}
 		test("abort() on listRaw rejects with AbortError", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				const p = doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				p.abort("test");
@@ -323,7 +323,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("listRaw on an unknown pageObjectNumber throws NotFound", async () => {
-			const doc = await openFixture$16(engine, opts);
+			const doc = await openFixture$19(engine, opts);
 			try {
 				let caught;
 				try {
@@ -339,7 +339,7 @@ function runAnnotationReadConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$16(engine, opts) {
+async function openFixture$19(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -808,7 +808,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("create appends without shifting indices and leaves weak refs valid", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -844,7 +844,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create + update honor annotation flags (set on create, merge on patch)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -879,7 +879,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create shape annotations (circle + square) round-trip shape fields", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const circleDraft = {
@@ -960,7 +960,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("cloudy border (/BE) + rect differences (/RD) are tri-state", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const plainDraft = {
@@ -1039,7 +1039,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update echoes the appearance verdict: moves preserve /AP, restyles re-bake", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1114,7 +1114,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a partial /DA patch preserves the unpatched font members", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1170,7 +1170,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("box transform is tri-state: rect-only moves keep rotation, null flattens", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1231,7 +1231,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create vertex + line annotations (polygon/polyline/line) round-trip geometry", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const polygonDraft = {
@@ -1362,7 +1362,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create free-text + callout round-trip text/colour/intent fields", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const freeTextDraft = {
@@ -1458,7 +1458,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a free-text patches alignment + colours and is non-structural", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1519,7 +1519,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create redact (area + text) round-trips label + colour fields", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const areaDraft = {
@@ -1599,7 +1599,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a redact patches the label and clears it, non-structurally", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1676,7 +1676,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create + update a caret round-trips color/opacity/rect differences", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const caretDraft = {
@@ -1756,7 +1756,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update an ink annotation patches strokes + color and is non-structural", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1807,7 +1807,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("ink highlight intent + blend round-trip and unrelated patches preserve blend", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1850,7 +1850,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a polyline patches vertices + line endings and is non-structural", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1899,7 +1899,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a shape annotation patches color and is non-structural", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1948,7 +1948,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		if (opts.supportsAppearanceRasters) test("creating a shape bakes an /AP appearance the reader can rasterize", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1978,7 +1978,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update on a durable annotation is non-structural and never touches /NM", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -2004,7 +2004,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		if (fix.expectsWeakAnnotation) test("update on a weak annotation stamps a UUID v4 /NM and upgrades the ref", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -2034,7 +2034,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("delete by objectNumber removes the annotation and reports a stable id", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -2064,7 +2064,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		if (fix.expectsWeakAnnotation) test("delete by index of a weak annotation reports deleted: null and refetch reason", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const weak = (await page.annotations.list()).annotations.find((a) => a.identityQuality === "weak");
@@ -2087,7 +2087,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("abort on create rejects with AbortError", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -2103,7 +2103,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update with a stale index revision throws InvalidReference", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const weak = (await page.annotations.list()).annotations.find((a) => a.identityQuality === "weak");
@@ -2130,7 +2130,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move single durable annotation reorders within the page (single-as-batch)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const aDraft = {
@@ -2174,7 +2174,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move multi-block preserves caller-supplied order at the destination", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const ids = await Promise.all([
@@ -2213,7 +2213,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		if (fix.expectsWeakAnnotation) test("move on a weak annotation upgrades it to durable /NM (one rev bump for batch)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -2238,7 +2238,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move with a stale index revision rejects (locked rev-token guard)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2276,7 +2276,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move with out-of-range toIndex rejects with InvalidArg", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2300,7 +2300,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move with duplicate refs rejects with InvalidArg", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2323,7 +2323,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("abort on move rejects with AbortError", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2344,7 +2344,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a page move does NOT bump per-page RevisionTokens (weak refs survive reorder)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -2359,7 +2359,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create a reply links /IRT and defaults /RT to \"reply\", reporting the parent", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2393,7 +2393,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create a grouped subordinate writes /RT /Group", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const primary = await page.annotations.create({
@@ -2424,7 +2424,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create link annotations round-trip uri, goto/xyz, goto/fitH, and dead targets", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const uri = await page.annotations.create({
@@ -2501,7 +2501,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a link patch retargets in both directions (uri→goto, goto→uri) and moves the rect", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -2556,7 +2556,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a link patch clears the target with null — a dead link on re-read", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -2595,7 +2595,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a link grouped to a highlight round-trips /IRT + /RT /Group with its target", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2629,7 +2629,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("replace-text round-trips /IT and groups StrikeOut under its Caret", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const caret = await page.annotations.create({
@@ -2681,7 +2681,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("patch inReplyTo: null clears /IRT and /RT (back to top-level)", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2708,7 +2708,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create with a cross-page /IRT parent throws InvalidArg", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2739,7 +2739,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a review-status reply round-trips /State + /StateModel + /Subj", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const target = await page.annotations.create({
@@ -2773,7 +2773,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a draft /State without /StateModel is rejected with InvalidArg", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				let caught;
@@ -2792,7 +2792,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("null-clear patches truly remove /State, /StateModel, /Subj and /Contents", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const note = await page.annotations.create({
@@ -2839,7 +2839,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("custom state models round-trip verbatim", async () => {
-			const doc = await openFixture$15(engine, opts);
+			const doc = await openFixture$18(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const custom = await page.annotations.create({
@@ -2867,7 +2867,7 @@ async function beginWeakEditIfRequired(doc, pageObjectNumber, fix) {
 	if (doc.capabilities.weakAnnotationEditSessions !== "required" || !fix.expectsWeakAnnotation) return null;
 	return doc.annotations.beginWeakEdit([pageObjectNumber]);
 }
-async function openFixture$15(engine, opts) {
+async function openFixture$18(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3457,7 +3457,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("renders the expected set of appearances with valid output", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const { pageState, appearances } = await collect(doc, opts, useRaw);
 				expect(pageState.pageObjectNumber).toBe(opts.fixture.pageObjectNumber);
@@ -3484,7 +3484,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		if (opts.fixture.expectsWeakAppearance) test("weak (index-only) annotations are emitted, not dropped", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const { appearances } = await collect(doc, opts, useRaw);
 				const weak = appearances.find((a) => a.ref.kind === "index");
@@ -3494,7 +3494,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		if (useRaw) test("rendered appearances are not blank (non-zero alpha)", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const { appearances } = await collect(doc, opts, useRaw);
 				const anyVisible = appearances.some((a) => a.raster !== null && hasOpaquePixel(a.raster));
@@ -3504,7 +3504,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		test("abort() rejects with AbortError", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const page = doc.page(opts.fixture.pageObjectNumber);
 				const p = useRaw ? page.annotations.renderAppearances({ scale: 1 }) : page.annotations.renderAppearanceImages({
@@ -3559,7 +3559,7 @@ function hasOpaquePixel(raster) {
 	}
 	return false;
 }
-async function openFixture$14(engine, opts) {
+async function openFixture$17(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3628,7 +3628,7 @@ function runPageReorderConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("pages.list() returns every page in display order, durable PONs only", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				expect(PageListSnapshotSchema.safeParse(list).success).toBe(true);
@@ -3647,7 +3647,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() reorders pages and returns the full post-move order", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 3) return;
@@ -3671,7 +3671,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("weak index-based annotation refs survive a page reorder", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3708,7 +3708,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3725,7 +3725,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() rejects out-of-range destIndex with InvalidArg", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3742,7 +3742,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -3760,7 +3760,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("abort on pages.move() rejects with AbortError", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3774,7 +3774,7 @@ function runPageReorderConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$13(engine, opts) {
+async function openFixture$16(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3848,7 +3848,7 @@ function runPageRotateConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("pages.rotate() sets the absolute rotation and returns the full layout", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				const target = before.pages[0];
@@ -3867,7 +3867,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("absolute rotation is idempotent: setting the same value twice is a no-op", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const first = await doc.pages.rotate([pon], 180);
@@ -3878,7 +3878,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("one rotation applies to EVERY listed page (the multi-select gesture)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3890,7 +3890,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("weak index-based annotation refs survive a rotate (no revision bump)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const hostPon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const hostPage = doc.page(hostPon);
@@ -3920,7 +3920,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("pages.rotate() rejects an invalid rotation value with InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -3935,7 +3935,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("pages.rotate() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -3950,7 +3950,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("pages.rotate() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -3968,7 +3968,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("abort on pages.rotate() rejects with AbortError", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const p = doc.pages.rotate([pon], 90);
@@ -3980,7 +3980,7 @@ function runPageRotateConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$12(engine, opts) {
+async function openFixture$15(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4043,7 +4043,7 @@ function runPageDeleteConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("pages.delete() removes the page and returns the surviving layout", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 2) return;
@@ -4064,7 +4064,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("addressing a deleted page afterwards is a clean NotFound", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 2) return;
@@ -4082,7 +4082,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("surviving pages keep their weak index-based annotation refs", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -4115,7 +4115,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("deleting EVERY page is rejected with InvalidArg", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let caught;
@@ -4130,7 +4130,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("pages.delete() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -4145,7 +4145,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("pages.delete() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -4163,7 +4163,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("abort on pages.delete() rejects with AbortError", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -4177,7 +4177,224 @@ function runPageDeleteConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$11(engine, opts) {
+async function openFixture$14(engine, opts) {
+	if (opts.openKind === "bytes") {
+		const bytes = await opts.fixture.bytes();
+		return engine.open({
+			kind: "bytes",
+			id: opts.fixture.id,
+			bytes
+		});
+	}
+	return engine.open({
+		kind: "id",
+		id: opts.fixture.cloudId ?? opts.fixture.id
+	});
+}
+//#endregion
+//#region src/conformance/runNamedPagesConformance.ts
+/**
+* Named-pages conformance: the catalog's `/Names /Pages` registry as LAYOUT
+* data. Locks the invariants both engines must share — do not loosen
+* without re-reading `NamedPageEntry` and `PageNameResult`:
+*
+*   1. `pages.list().namedPages` is present (possibly empty) and every
+*      registration resolves to a page in `pages`, a template, or is
+*      reported dangling — never silently dropped.
+*   2. `pages.setName()` creates or replaces by decoded key (idempotent),
+*      `replace` renames in one job, and the result IS the new layout.
+*   3. `pages.removeName()` drops the registration and nothing else.
+*   4. Deleting a page removes every registration pointing at it — inside
+*      the delete, with no plugin in the loop.
+*   5. Non-ASCII keys round-trip unchanged (Acrobat writes UTF-16 + BOM).
+*
+* Skips cleanly when the engine does not implement the optional members.
+*/
+function runNamedPagesConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	describe(`named pages conformance: ${opts.label}`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		test("pages.list() carries namedPages and every entry resolves", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				const layout = await doc.pages.list();
+				PageListSnapshotSchema.parse(layout);
+				expect(Array.isArray(layout.namedPages)).toBe(true);
+				const pons = new Set(layout.pages.map((page) => page.pageObjectNumber));
+				for (const entry of layout.namedPages ?? []) {
+					expect(entry.name.length > 0).toBe(true);
+					if (entry.target.kind === "page") expect(pons.has(entry.target.pageObjectNumber)).toBe(true);
+				}
+			} finally {
+				await doc.close();
+			}
+		});
+		test("pages.setName() registers, replaces by key, and renames via `replace`", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName) return;
+				const before = await doc.pages.list();
+				const [first, second] = before.pages;
+				const baseline = (before.namedPages ?? []).length;
+				const created = await doc.pages.setName({
+					name: "Approved=Goedgekeurd",
+					pageObjectNumber: first.pageObjectNumber
+				});
+				PageNameResultSchema.parse(created);
+				expect(created.layout.pages.length).toBe(before.pages.length);
+				expect(find(created, "Approved=Goedgekeurd")).toEqual({
+					kind: "page",
+					pageObjectNumber: first.pageObjectNumber
+				});
+				expect((created.layout.namedPages ?? []).length).toBe(baseline + 1);
+				if (created.cache) {
+					expect(created.cache.docVersion > created.cache.previousDocVersion).toBe(true);
+					expect(created.cache.layoutVersion > 0).toBe(true);
+				}
+				const listed = await doc.pages.list();
+				expect(listed.namedPages).toEqual(created.layout.namedPages);
+				const replaced = await doc.pages.setName({
+					name: "Approved=Goedgekeurd",
+					pageObjectNumber: second.pageObjectNumber
+				});
+				expect(find(replaced, "Approved=Goedgekeurd")).toEqual({
+					kind: "page",
+					pageObjectNumber: second.pageObjectNumber
+				});
+				expect((replaced.layout.namedPages ?? []).length).toBe(baseline + 1);
+				const renamed = await doc.pages.setName({
+					name: "Approved=Approved",
+					pageObjectNumber: second.pageObjectNumber,
+					replace: "Approved=Goedgekeurd"
+				});
+				expect(find(renamed, "Approved=Goedgekeurd")).toBe(void 0);
+				expect(find(renamed, "Approved=Approved")).toEqual({
+					kind: "page",
+					pageObjectNumber: second.pageObjectNumber
+				});
+				expect((renamed.layout.namedPages ?? []).length).toBe(baseline + 1);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("non-ASCII keys round-trip through set → list", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName) return;
+				const before = await doc.pages.list();
+				const key = "Stämpel=Stämpel 日本";
+				const result = await doc.pages.setName({
+					name: key,
+					pageObjectNumber: before.pages[0].pageObjectNumber
+				});
+				expect(find(result, key)).toEqual({
+					kind: "page",
+					pageObjectNumber: before.pages[0].pageObjectNumber
+				});
+				const listed = await doc.pages.list();
+				expect((listed.namedPages ?? []).some((entry) => entry.name === key)).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("pages.removeName() drops the registration and keeps the page", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName || !doc.pages.removeName) return;
+				const before = await doc.pages.list();
+				await doc.pages.setName({
+					name: "Draft=Concept",
+					pageObjectNumber: before.pages[0].pageObjectNumber
+				});
+				const removed = await doc.pages.removeName({ name: "Draft=Concept" });
+				PageNameResultSchema.parse(removed);
+				expect(find(removed, "Draft=Concept")).toBe(void 0);
+				expect(removed.layout.pages.length).toBe(before.pages.length);
+				await expect(doc.pages.removeName({ name: "Draft=Concept" })).rejects.toMatchObject({ code: EngineErrorCode.NotFound });
+			} finally {
+				await doc.close();
+			}
+		});
+		test("pages.setName() rejects an empty name and an unknown page", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName) return;
+				const before = await doc.pages.list();
+				await expect(doc.pages.setName({
+					name: "",
+					pageObjectNumber: before.pages[0].pageObjectNumber
+				})).rejects.toMatchObject({ code: EngineErrorCode.InvalidArg });
+				let unknownPage = null;
+				try {
+					await doc.pages.setName({
+						name: "Ghost=Ghost",
+						pageObjectNumber: 987654321
+					});
+				} catch (error) {
+					unknownPage = error;
+				}
+				expect(EngineError.is(unknownPage, EngineErrorCode.NotFound) || EngineError.is(unknownPage, EngineErrorCode.InvalidArg)).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("deleting a page removes every registration pointing at it", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName) return;
+				const before = await doc.pages.list();
+				if (before.pages.length < 2) return;
+				const victim = before.pages[1].pageObjectNumber;
+				const survivor = before.pages[0].pageObjectNumber;
+				await doc.pages.setName({
+					name: "Victim=One",
+					pageObjectNumber: victim
+				});
+				await doc.pages.setName({
+					name: "Victim=Two",
+					pageObjectNumber: victim
+				});
+				await doc.pages.setName({
+					name: "Survivor",
+					pageObjectNumber: survivor
+				});
+				const deleted = await doc.pages.delete([victim]);
+				const names = (deleted.layout.namedPages ?? []).map((entry) => entry.name);
+				expect(names.includes("Victim=One")).toBe(false);
+				expect(names.includes("Victim=Two")).toBe(false);
+				expect(names).toContain("Survivor");
+				expect((deleted.layout.namedPages ?? []).some((entry) => entry.target.kind === "dangling")).toBe(false);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("abort on pages.setName() rejects with AbortError", async () => {
+			const doc = await openFixture$13(engine, opts);
+			try {
+				if (!doc.pages.setName) return;
+				const before = await doc.pages.list();
+				const promise = doc.pages.setName({
+					name: "Aborted=Aborted",
+					pageObjectNumber: before.pages[0].pageObjectNumber
+				});
+				promise.abort();
+				await expect(promise).rejects.toBeInstanceOf(AbortError);
+			} finally {
+				await doc.close();
+			}
+		});
+	});
+}
+function find(result, name) {
+	return (result.layout.namedPages ?? []).find((entry) => entry.name === name)?.target;
+}
+async function openFixture$13(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4192,6 +4409,243 @@ async function openFixture$11(engine, opts) {
 	});
 }
 //#endregion
+//#region src/conformance/runAnnotationFlattenConformance.ts
+const square$1 = (left, bottom) => ({
+	subtype: "square",
+	rect: {
+		left,
+		bottom,
+		right: left + 40,
+		top: bottom + 40
+	},
+	color: {
+		r: 20,
+		g: 40,
+		b: 220
+	},
+	strokeWidth: 2
+});
+/**
+* Selective annotation flatten: `page(pon).annotations.flatten(refs)` is
+* `pages.flatten` for a chosen set. Locks, on every engine:
+*   1. only the given refs are painted and removed; the rest of the page's
+*      annotations are untouched;
+*   2. per-ref status (`applied` / `skipped`), one `annotations.flattened`
+*      event, a `meta` with that page's new pins, layout unchanged;
+*   3. a hidden ref is `skipped`; a ref on another page rejects `InvalidArg`
+*      with nothing mutated.
+* Skips cleanly when the engine does not implement the optional member.
+*/
+function runAnnotationFlattenConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	describe(`annotation flatten conformance: ${opts.label}`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		test("flattens exactly the given refs and reports per-ref status", async () => {
+			const doc = await openFixture$12(engine, opts);
+			try {
+				const layoutBefore = await doc.pages.list();
+				const pon = layoutBefore.pages[0].pageObjectNumber;
+				const page = doc.page(pon);
+				if (!page.annotations.flatten) return;
+				const a = (await page.annotations.create(square$1(20, 20))).created.ref;
+				const b = (await page.annotations.create(square$1(80, 20))).created.ref;
+				const c = (await page.annotations.create(square$1(140, 20))).created.ref;
+				await page.annotations.update(c, {
+					subtype: "square",
+					flags: { hidden: true }
+				});
+				const before = await page.annotations.list();
+				const events = [];
+				const unsubscribe = doc.events.subscribe((event) => {
+					if (event.type === "annotations.flattened") events.push(event);
+				});
+				const result = await page.annotations.flatten([a, c], "display");
+				unsubscribe();
+				expect(AnnotationFlattenResultSchema.safeParse(result).success).toBe(true);
+				expect(result.pageObjectNumber).toBe(pon);
+				expect(result.usage).toBe("display");
+				expect(result.results.map((item) => item.status)).toEqual(["applied", "skipped"]);
+				expect(result.meta === null).toBe(false);
+				expect(events).toHaveLength(1);
+				expect(await doc.pages.list()).toEqual(layoutBefore);
+				const after = await page.annotations.list();
+				expect(after.annotations.length).toBe(before.annotations.length - 1);
+				expect(after.annotations.some((dto) => sameRef(dto.ref, b))).toBe(true);
+				expect(after.annotations.some((dto) => sameRef(dto.ref, c))).toBe(true);
+				expect(after.annotations.some((dto) => sameRef(dto.ref, a))).toBe(false);
+				expect(after.pageState.revision.generation > before.pageState.revision.generation).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("a ref on another page rejects InvalidArg and mutates nothing", async () => {
+			const doc = await openFixture$12(engine, opts);
+			try {
+				const layout = await doc.pages.list();
+				if (layout.pages.length < 2) return;
+				const page0 = doc.page(layout.pages[0].pageObjectNumber);
+				const page1 = doc.page(layout.pages[1].pageObjectNumber);
+				if (!page0.annotations.flatten) return;
+				const own = (await page0.annotations.create(square$1(20, 100))).created.ref;
+				const foreign = (await page1.annotations.create(square$1(20, 100))).created.ref;
+				const countBefore = (await page0.annotations.list()).annotations.length;
+				await expect(page0.annotations.flatten([own, foreign])).rejects.toMatchObject({ code: EngineErrorCode.InvalidArg });
+				expect((await page0.annotations.list()).annotations.length).toBe(countBefore);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("an empty ref list rejects InvalidArg; an unknown ref rejects", async () => {
+			const doc = await openFixture$12(engine, opts);
+			try {
+				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
+				const page = doc.page(pon);
+				if (!page.annotations.flatten) return;
+				await expect(page.annotations.flatten([])).rejects.toMatchObject({ code: EngineErrorCode.InvalidArg });
+				let unknown = null;
+				try {
+					await page.annotations.flatten([{
+						kind: "objectNumber",
+						pageObjectNumber: pon,
+						annotObjectNumber: 987654321
+					}]);
+				} catch (error) {
+					unknown = error;
+				}
+				expect(EngineError.is(unknown, EngineErrorCode.NotFound) || EngineError.is(unknown, EngineErrorCode.InvalidArg) || EngineError.is(unknown, EngineErrorCode.InvalidReference)).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+	});
+}
+function sameRef(left, right) {
+	if (left.kind === "objectNumber" && right.kind === "objectNumber") return left.annotObjectNumber === right.annotObjectNumber;
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+async function openFixture$12(engine, opts) {
+	if (opts.openKind === "bytes") return engine.open({
+		kind: "bytes",
+		id: opts.fixture.id,
+		bytes: await opts.fixture.bytes()
+	});
+	return engine.open({
+		kind: "id",
+		id: opts.fixture.cloudId ?? opts.fixture.id
+	});
+}
+//#endregion
+//#region src/conformance/runAnnotationAppearanceExportConformance.ts
+const PDF_MAGIC$1 = [
+	37,
+	80,
+	68,
+	70
+];
+const square = (left, bottom, size = 40) => ({
+	subtype: "square",
+	rect: {
+		left,
+		bottom,
+		right: left + size,
+		top: bottom + size
+	},
+	color: {
+		r: 220,
+		g: 20,
+		b: 20
+	},
+	strokeWidth: 2
+});
+/**
+* `page(pon).annotations.exportAppearance(refs)`: the chosen annotations'
+* appearances as ONE single-page PDF sized to their union /Rect. Locks:
+*   1. bytes are a PDF; the source page is untouched (no mutation, no
+*      revision bump);
+*   2. re-opened (local engines), the page is exactly the union size and the
+*      requested count of annotations is gone — they are content now;
+*   3. a ref on another page rejects `InvalidArg`; an empty list rejects.
+* Skips cleanly when the engine does not implement the optional member.
+*/
+function runAnnotationAppearanceExportConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	describe(`annotation appearance export conformance: ${opts.label}`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		test("returns a single-page PDF sized to the union rect; source untouched", async () => {
+			const doc = await openFixture$11(engine, opts);
+			let exported = null;
+			try {
+				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
+				const page = doc.page(pon);
+				if (!page.annotations.exportAppearance) return;
+				const a = (await page.annotations.create(square(20, 20))).created.ref;
+				const b = (await page.annotations.create(square(100, 60, 30))).created.ref;
+				const before = await page.annotations.list();
+				const bytes = await page.annotations.exportAppearance([a, b]);
+				expect(bytes.length > 4).toBe(true);
+				expect([...bytes.subarray(0, 4)]).toEqual(PDF_MAGIC$1);
+				const after = await page.annotations.list();
+				expect(after.annotations.length).toBe(before.annotations.length);
+				expect(after.pageState.revision.generation).toBe(before.pageState.revision.generation);
+				if (opts.openKind !== "bytes") return;
+				exported = await engine.open({
+					kind: "bytes",
+					id: `${opts.fixture.id}-appearance`,
+					bytes
+				});
+				const layout = await exported.pages.list();
+				expect(layout.pageCount).toBe(1);
+				expect(Math.round(layout.pages[0].size.width)).toBe(110);
+				expect(Math.round(layout.pages[0].size.height)).toBe(70);
+				const exportedPage = exported.page(layout.pages[0].pageObjectNumber);
+				expect((await exportedPage.annotations.list()).annotations).toHaveLength(0);
+			} finally {
+				if (exported) await exported.close();
+				await doc.close();
+			}
+		});
+		test("a ref on another page and an empty list reject InvalidArg", async () => {
+			const doc = await openFixture$11(engine, opts);
+			try {
+				const layout = await doc.pages.list();
+				const page0 = doc.page(layout.pages[0].pageObjectNumber);
+				if (!page0.annotations.exportAppearance) return;
+				await expect(page0.annotations.exportAppearance([])).rejects.toMatchObject({ code: EngineErrorCode.InvalidArg });
+				if (layout.pages.length < 2) return;
+				const page1 = doc.page(layout.pages[1].pageObjectNumber);
+				const own = (await page0.annotations.create(square(20, 100))).created.ref;
+				const foreign = (await page1.annotations.create(square(20, 100))).created.ref;
+				await expect(page0.annotations.exportAppearance([own, foreign])).rejects.toMatchObject({ code: EngineErrorCode.InvalidArg });
+			} finally {
+				await doc.close();
+			}
+		});
+	});
+}
+async function openFixture$11(engine, opts) {
+	if (opts.openKind === "bytes") return engine.open({
+		kind: "bytes",
+		id: opts.fixture.id,
+		bytes: await opts.fixture.bytes()
+	});
+	return engine.open({
+		kind: "id",
+		id: opts.fixture.cloudId ?? opts.fixture.id
+	});
+}
+//#endregion
 //#region src/conformance/runPageFlattenConformance.ts
 /** Transport-neutral coverage for the content + annotation flatten rail. */
 function runPageFlattenConformance(runner, opts) {
@@ -6220,6 +6674,6 @@ function diffAnnotation(i, a, b, errs) {
 	if (a.nm !== b.nm) errs.push(`annotations[${i}].nm mismatch: ${a.nm} vs ${b.nm}`);
 }
 //#endregion
-export { TEXT_DIVERGENCE_CASES, diffAnnotationListSnapshot, diffAnnotationListSnapshotAll, runActionsConformance, runAnnotationAppearanceConformance, runAnnotationMutationConformance, runAnnotationReadConformance, runAttachmentConformance, runDocumentEventsConformance, runFormConformance, runMetadataConformance, runPageDeleteConformance, runPageExtractConformance, runPageFlattenConformance, runPageGeometryOrientationConformance, runPageInsertBlankConformance, runPageInsertConformance, runPageReorderConformance, runPageRotateConformance, runPageTextConformance, runPieceInfoConformance, runRedactionApplyConformance, runSearchConformance, runTextDivergenceConformance };
+export { TEXT_DIVERGENCE_CASES, diffAnnotationListSnapshot, diffAnnotationListSnapshotAll, runActionsConformance, runAnnotationAppearanceConformance, runAnnotationAppearanceExportConformance, runAnnotationFlattenConformance, runAnnotationMutationConformance, runAnnotationReadConformance, runAttachmentConformance, runDocumentEventsConformance, runFormConformance, runMetadataConformance, runNamedPagesConformance, runPageDeleteConformance, runPageExtractConformance, runPageFlattenConformance, runPageGeometryOrientationConformance, runPageInsertBlankConformance, runPageInsertConformance, runPageReorderConformance, runPageRotateConformance, runPageTextConformance, runPieceInfoConformance, runRedactionApplyConformance, runSearchConformance, runTextDivergenceConformance };
 
 //# sourceMappingURL=conformance.js.map