@embedpdf/engine-core 3.0.0-next.0 → 3.0.0-next.10

package/dist/conformance.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_subtype = require("./subtype-qejjVr6h.cjs");
-const require_fold = require("./fold-IaMph3CO.cjs");
-const require_AbortError = require("./AbortError-ByBflvEl.cjs");
-const require_schemas = require("./schemas-B_1VyFsm.cjs");
+const require_fold = require("./fold-C7I5GpBz.cjs");
+const require_PageInsertBlankInput = require("./PageInsertBlankInput-CzShuSJI.cjs");
+const require_AbortError = require("./AbortError-CRSooKsk.cjs");
+const require_schemas = require("./schemas-D1pxEv3t.cjs");
 //#region src/conformance/runMetadataConformance.ts
 /**
 * The conformance harness is transport-agnostic. It takes the test runner as
@@ -19,7 +19,7 @@ function runMetadataConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("reads metadata from sample fixture", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const meta = await doc.metadata.read();
 				expect(meta).toMatchObject(opts.fixture.expected);
@@ -29,7 +29,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("abort() before completion rejects with AbortError", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const p = doc.metadata.read();
 				p.abort("test");
@@ -39,7 +39,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("aborting one read does not affect a concurrent one", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const a = doc.metadata.read();
 				const b = doc.metadata.read();
@@ -51,7 +51,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("metadata after close throws DocNotOpen", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			await doc.close();
 			let caught;
 			try {
@@ -60,10 +60,10 @@ function runMetadataConformance(runner, opts) {
 				caught = err;
 			}
 			expect(caught).toBeTruthy();
-			expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.DocNotOpen)).toBe(true);
+			expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.DocNotOpen)).toBe(true);
 		});
 		test("update() sets standard + custom fields and a subsequent read observes them", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				const result = await doc.metadata.update({
 					title: "Conformance Title",
@@ -82,7 +82,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("update() clears a field with null", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			try {
 				await doc.metadata.update({ title: "To Be Cleared" });
 				const set = await doc.metadata.read();
@@ -95,7 +95,7 @@ function runMetadataConformance(runner, opts) {
 			}
 		});
 		test("update() after close throws DocNotOpen", async () => {
-			const doc = await openFixture$14(engine, opts);
+			const doc = await openFixture$17(engine, opts);
 			await doc.close();
 			let caught;
 			try {
@@ -104,11 +104,11 @@ function runMetadataConformance(runner, opts) {
 				caught = err;
 			}
 			expect(caught).toBeTruthy();
-			expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.DocNotOpen)).toBe(true);
+			expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.DocNotOpen)).toBe(true);
 		});
 	});
 }
-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({
@@ -135,11 +135,12 @@ function runAnnotationReadConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("listRawAll returns one entry per page with valid PageState", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const snap = await doc.annotations.listRawAll();
 				expect(require_schemas.AnnotationListSnapshotAllPagesSchema.safeParse(snap).success).toBe(true);
 				expect(snap.pages.length >= 1).toBe(true);
+				if (snap.auditHead !== void 0) expect(Number.isInteger(snap.auditHead) && snap.auditHead >= 0).toBe(true);
 				const target = snap.pages.find((p) => p.pageState.pageObjectNumber === opts.fixture.pageObjectNumber);
 				expect(target !== void 0).toBe(true);
 				expect(target.annotations.length).toBe(opts.fixture.expectedAnnotationCount);
@@ -148,7 +149,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("listRaw on the test page returns the expected counts and DTO shape", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				expect(require_schemas.AnnotationListPageSnapshotSchema.safeParse(snap).success).toBe(true);
@@ -178,7 +179,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("shape/vertex/line annotations expose their family fields", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				for (const a of snap.annotations) {
@@ -237,7 +238,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("full page list dispatches per-subtype and matches raw counts", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const full = await doc.page(opts.fixture.pageObjectNumber).annotations.list();
 				expect(require_schemas.AnnotationListPageSnapshotSchema.safeParse(full).success).toBe(true);
@@ -247,7 +248,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("every annotation DTO satisfies AnnotationDTOSchema (discriminated union)", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const snap = await doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				for (const a of snap.annotations) {
@@ -287,7 +288,7 @@ function runAnnotationReadConformance(runner, opts) {
 		});
 		if (opts.fixture.expectsWeakAnnotation) {
 			test("weak annotations carry identityQuality: weak and ref.kind: index", async () => {
-				const doc = await openFixture$13(engine, opts);
+				const doc = await openFixture$16(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 +298,7 @@ function runAnnotationReadConformance(runner, opts) {
 				}
 			});
 			test("a stale revision token throws InvalidReference", async () => {
-				const doc = await openFixture$13(engine, opts);
+				const doc = await openFixture$16(engine, opts);
 				try {
 					const snap = await doc.page(opts.fixture.pageObjectNumber).annotations.list();
 					const weak = snap.annotations.find((a) => a.identityQuality === "weak");
@@ -313,7 +314,7 @@ function runAnnotationReadConformance(runner, opts) {
 			});
 		}
 		test("abort() on listRaw rejects with AbortError", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				const p = doc.annotations.listRaw(opts.fixture.pageObjectNumber);
 				p.abort("test");
@@ -323,7 +324,7 @@ function runAnnotationReadConformance(runner, opts) {
 			}
 		});
 		test("listRaw on an unknown pageObjectNumber throws NotFound", async () => {
-			const doc = await openFixture$13(engine, opts);
+			const doc = await openFixture$16(engine, opts);
 			try {
 				let caught;
 				try {
@@ -332,14 +333,14 @@ function runAnnotationReadConformance(runner, opts) {
 					caught = err;
 				}
 				expect(caught).toBeTruthy();
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 	});
 }
-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({
@@ -597,7 +598,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -633,7 +634,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create + update honor annotation flags (set on create, merge on patch)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -668,7 +669,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create shape annotations (circle + square) round-trip shape fields", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const circleDraft = {
@@ -749,7 +750,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("cloudy border (/BE) + rect differences (/RD) are tri-state", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const plainDraft = {
@@ -828,7 +829,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update echoes the appearance verdict: moves preserve /AP, restyles re-bake", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -903,7 +904,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a partial /DA patch preserves the unpatched font members", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -959,7 +960,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("box transform is tri-state: rect-only moves keep rotation, null flattens", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1020,7 +1021,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create vertex + line annotations (polygon/polyline/line) round-trip geometry", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const polygonDraft = {
@@ -1151,7 +1152,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create free-text + callout round-trip text/colour/intent fields", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const freeTextDraft = {
@@ -1247,7 +1248,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a free-text patches alignment + colours and is non-structural", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1308,7 +1309,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create redact (area + text) round-trips label + colour fields", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const areaDraft = {
@@ -1388,7 +1389,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a redact patches the label and clears it, non-structurally", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1465,7 +1466,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create + update a caret round-trips color/opacity/rect differences", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const caretDraft = {
@@ -1545,7 +1546,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update an ink annotation patches strokes + color and is non-structural", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1596,7 +1597,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("ink highlight intent + blend round-trip and unrelated patches preserve blend", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1639,7 +1640,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a polyline patches vertices + line endings and is non-structural", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1688,7 +1689,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update a shape annotation patches color and is non-structural", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1737,7 +1738,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -1767,7 +1768,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update on a durable annotation is non-structural and never touches /NM", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -1793,7 +1794,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -1823,7 +1824,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("delete by objectNumber removes the annotation and reports a stable id", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1853,7 +1854,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const weak = (await page.annotations.list()).annotations.find((a) => a.identityQuality === "weak");
@@ -1876,7 +1877,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("abort on create rejects with AbortError", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const draft = {
@@ -1892,7 +1893,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("update with a stale index revision throws InvalidReference", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const weak = (await page.annotations.list()).annotations.find((a) => a.identityQuality === "weak");
@@ -1913,13 +1914,13 @@ function runAnnotationMutationConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidReference)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidReference)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("move single durable annotation reorders within the page (single-as-batch)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const aDraft = {
@@ -1963,7 +1964,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move multi-block preserves caller-supplied order at the destination", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const ids = await Promise.all([
@@ -2002,7 +2003,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const before = await page.annotations.list();
@@ -2027,7 +2028,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("move with a stale index revision rejects (locked rev-token guard)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2059,13 +2060,13 @@ function runAnnotationMutationConformance(runner, opts) {
 				} finally {
 					await weakSession?.release();
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidReference)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidReference)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("move with out-of-range toIndex rejects with InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2083,13 +2084,13 @@ function runAnnotationMutationConformance(runner, opts) {
 				} finally {
 					await weakSession?.release();
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("move with duplicate refs rejects with InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2106,13 +2107,13 @@ function runAnnotationMutationConformance(runner, opts) {
 				} finally {
 					await weakSession?.release();
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort on move rejects with AbortError", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const a = await page.annotations.create({
@@ -2133,7 +2134,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("a page move does NOT bump per-page RevisionTokens (weak refs survive reorder)", 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 < 1) return;
@@ -2148,7 +2149,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create a reply links /IRT and defaults /RT to \"reply\", reporting the parent", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2182,7 +2183,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create a grouped subordinate writes /RT /Group", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const primary = await page.annotations.create({
@@ -2213,7 +2214,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create link annotations round-trip uri, goto/xyz, goto/fitH, and dead targets", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const uri = await page.annotations.create({
@@ -2290,7 +2291,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -2345,7 +2346,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const created = await page.annotations.create({
@@ -2384,7 +2385,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$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2418,7 +2419,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("replace-text round-trips /IT and groups StrikeOut under its Caret", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const caret = await page.annotations.create({
@@ -2470,7 +2471,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("patch inReplyTo: null clears /IRT and /RT (back to top-level)", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2497,7 +2498,7 @@ function runAnnotationMutationConformance(runner, opts) {
 			}
 		});
 		test("create with a cross-page /IRT parent throws InvalidArg", async () => {
-			const doc = await openFixture$12(engine, opts);
+			const doc = await openFixture$15(engine, opts);
 			try {
 				const page = doc.page(fix.pageObjectNumber);
 				const parent = await page.annotations.create({
@@ -2522,7 +2523,130 @@ function runAnnotationMutationConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("a review-status reply round-trips /State + /StateModel + /Subj", async () => {
+			const doc = await openFixture$15(engine, opts);
+			try {
+				const page = doc.page(fix.pageObjectNumber);
+				const target = await page.annotations.create({
+					subtype: "highlight",
+					contents: "status target",
+					subject: "Pricing question",
+					quadPoints: quad
+				});
+				expect(target.created.subject).toBe("Pricing question");
+				const status = await page.annotations.create({
+					subtype: "text",
+					rect: shapeRect,
+					inReplyTo: target.created.ref,
+					state: "accepted",
+					stateModel: "review"
+				});
+				expect(require_schemas.AnnotationCreateResultSchema.safeParse(status).success).toBe(true);
+				expect(status.created.subtype).toBe("text");
+				if (status.created.subtype !== "text") return;
+				expect(status.created.state).toBe("accepted");
+				expect(status.created.stateModel).toBe("review");
+				expect(status.created.replyType).toBe("reply");
+				const read = (await page.annotations.list()).annotations.find((a) => a.ref.kind === "objectNumber" && status.created.ref.kind === "objectNumber" && a.ref.annotObjectNumber === status.created.ref.annotObjectNumber);
+				expect(read?.subtype).toBe("text");
+				if (read?.subtype === "text") {
+					expect(read.state).toBe("accepted");
+					expect(read.stateModel).toBe("review");
+				}
+			} finally {
+				await doc.close();
+			}
+		});
+		test("a draft /State without /StateModel is rejected with InvalidArg", async () => {
+			const doc = await openFixture$15(engine, opts);
+			try {
+				const page = doc.page(fix.pageObjectNumber);
+				let caught;
+				try {
+					await page.annotations.create({
+						subtype: "text",
+						rect: shapeRect,
+						state: "accepted"
+					});
+				} catch (err) {
+					caught = err;
+				}
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("null-clear patches truly remove /State, /StateModel, /Subj and /Contents", async () => {
+			const doc = await openFixture$15(engine, opts);
+			try {
+				const page = doc.page(fix.pageObjectNumber);
+				const note = await page.annotations.create({
+					subtype: "text",
+					rect: shapeRect,
+					contents: "work in progress",
+					subject: "Draft",
+					state: "none",
+					stateModel: "review"
+				});
+				const cycled = await page.annotations.update(note.created.ref, {
+					subtype: "text",
+					state: "rejected"
+				});
+				expect(cycled.appearance.changed).toBe(false);
+				expect(cycled.updated.subtype).toBe("text");
+				if (cycled.updated.subtype === "text") {
+					expect(cycled.updated.state).toBe("rejected");
+					expect(cycled.updated.stateModel).toBe("review");
+				}
+				const cleared = await page.annotations.update(note.created.ref, {
+					subtype: "text",
+					contents: null,
+					subject: null,
+					state: null,
+					stateModel: null
+				});
+				expect(cleared.appearance.changed).toBe(false);
+				expect(cleared.updated.contents).toBe(null);
+				expect(cleared.updated.subject).toBe(null);
+				if (cleared.updated.subtype === "text") {
+					expect(cleared.updated.state).toBe(null);
+					expect(cleared.updated.stateModel).toBe(null);
+				}
+				const read = (await page.annotations.list()).annotations.find((a) => a.ref.kind === "objectNumber" && note.created.ref.kind === "objectNumber" && a.ref.annotObjectNumber === note.created.ref.annotObjectNumber);
+				expect(read?.contents).toBe(null);
+				expect(read?.subject).toBe(null);
+				if (read?.subtype === "text") {
+					expect(read.state).toBe(null);
+					expect(read.stateModel).toBe(null);
+				}
+			} finally {
+				await doc.close();
+			}
+		});
+		test("custom state models round-trip verbatim", async () => {
+			const doc = await openFixture$15(engine, opts);
+			try {
+				const page = doc.page(fix.pageObjectNumber);
+				const custom = await page.annotations.create({
+					subtype: "text",
+					rect: shapeRect,
+					state: "in-progress",
+					stateModel: "X-ReviewWorkflow"
+				});
+				expect(custom.created.subtype).toBe("text");
+				if (custom.created.subtype !== "text") return;
+				expect(custom.created.state).toBe("in-progress");
+				expect(custom.created.stateModel).toBe("X-ReviewWorkflow");
+				const read = (await page.annotations.list()).annotations.find((a) => a.ref.kind === "objectNumber" && custom.created.ref.kind === "objectNumber" && a.ref.annotObjectNumber === custom.created.ref.annotObjectNumber);
+				if (read?.subtype === "text") {
+					expect(read.state).toBe("in-progress");
+					expect(read.stateModel).toBe("X-ReviewWorkflow");
+				}
 			} finally {
 				await doc.close();
 			}
@@ -2533,7 +2657,7 @@ async function beginWeakEditIfRequired(doc, pageObjectNumber, fix) {
 	if (doc.capabilities.weakAnnotationEditSessions !== "required" || !fix.expectsWeakAnnotation) return null;
 	return doc.annotations.beginWeakEdit([pageObjectNumber]);
 }
-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({
@@ -2699,7 +2823,7 @@ function runFormConformance(runner, opts) {
 				await expect(doc.forms.setValue(radioRef, {
 					type: "toggle",
 					state: null
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 				const check = await doc.forms.setValue({
 					kind: "fqn",
 					name: "opt_check"
@@ -2727,7 +2851,7 @@ function runFormConformance(runner, opts) {
 				}, {
 					type: "toggle",
 					state: "On"
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 				const field = await doc.forms.get({
 					kind: "fqn",
 					name: "maxlen_text"
@@ -2831,7 +2955,7 @@ function runFormConformance(runner, opts) {
 				}, {
 					type: "choice",
 					values: ["foo", "bar"]
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 			} finally {
 				await doc.close();
 			}
@@ -2901,7 +3025,7 @@ function runFormConformance(runner, opts) {
 		test("rejects garbage import payloads", async () => {
 			const doc = await open(opts.fixtures.toggleFields);
 			try {
-				await expect(doc.forms.importData(new TextEncoder().encode("not a form payload"))).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				await expect(doc.forms.importData(new TextEncoder().encode("not a form payload"))).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 			} finally {
 				await doc.close();
 			}
@@ -3008,7 +3132,7 @@ function runFormConformance(runner, opts) {
 					g: 247,
 					b: 219
 				});
-				await expect(page.annotations.delete(widgetRef)).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				await expect(page.annotations.delete(widgetRef)).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 				await doc.forms.detachWidget(field.field.ref, {
 					annotObjectNumber: widgetRef.annotObjectNumber,
 					pageObjectNumber: pon
@@ -3072,7 +3196,7 @@ function runFormConformance(runner, opts) {
 				await expect(doc.forms.updateField(created.field.ref, {
 					family: "radio",
 					name: "unison_radio"
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 				const before = await doc.page(pon).annotations.list();
 				const removed = await doc.forms.deleteField(created.field.ref);
 				expect(removed.removedWidgets.length).toBe(2);
@@ -3081,7 +3205,7 @@ function runFormConformance(runner, opts) {
 				await expect(doc.forms.get({
 					kind: "fqn",
 					name: "renamed_radio"
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.NotFound });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.NotFound });
 			} finally {
 				await doc.close();
 			}
@@ -3092,7 +3216,7 @@ function runFormConformance(runner, opts) {
 				await expect(doc.forms.get({
 					kind: "fqn",
 					name: "no.such.field"
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.NotFound });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.NotFound });
 			} finally {
 				await doc.close();
 			}
@@ -3123,7 +3247,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$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const { pageState, appearances } = await collect(doc, opts, useRaw);
 				expect(pageState.pageObjectNumber).toBe(opts.fixture.pageObjectNumber);
@@ -3150,7 +3274,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		if (opts.fixture.expectsWeakAppearance) test("weak (index-only) annotations are emitted, not dropped", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const { appearances } = await collect(doc, opts, useRaw);
 				const weak = appearances.find((a) => a.ref.kind === "index");
@@ -3160,7 +3284,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		if (useRaw) test("rendered appearances are not blank (non-zero alpha)", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const { appearances } = await collect(doc, opts, useRaw);
 				const anyVisible = appearances.some((a) => a.raster !== null && hasOpaquePixel(a.raster));
@@ -3170,7 +3294,7 @@ function runAnnotationAppearanceConformance(runner, opts) {
 			}
 		});
 		test("abort() rejects with AbortError", async () => {
-			const doc = await openFixture$11(engine, opts);
+			const doc = await openFixture$14(engine, opts);
 			try {
 				const page = doc.page(opts.fixture.pageObjectNumber);
 				const p = useRaw ? page.annotations.renderAppearances({ scale: 1 }) : page.annotations.renderAppearanceImages({
@@ -3225,7 +3349,7 @@ function hasOpaquePixel(raster) {
 	}
 	return false;
 }
-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({
@@ -3294,7 +3418,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$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				expect(require_schemas.PageListSnapshotSchema.safeParse(list).success).toBe(true);
@@ -3313,7 +3437,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() reorders pages and returns the full post-move order", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 3) return;
@@ -3337,7 +3461,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("weak index-based annotation refs survive a page reorder", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3374,7 +3498,7 @@ function runPageReorderConformance(runner, opts) {
 			}
 		});
 		test("pages.move() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3385,13 +3509,13 @@ function runPageReorderConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.move() rejects out-of-range destIndex with InvalidArg", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3402,13 +3526,13 @@ function runPageReorderConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.move() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -3420,13 +3544,13 @@ function runPageReorderConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort on pages.move() rejects with AbortError", async () => {
-			const doc = await openFixture$10(engine, opts);
+			const doc = await openFixture$13(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 1) return;
@@ -3440,7 +3564,7 @@ function runPageReorderConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$10(engine, opts) {
+async function openFixture$13(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3514,7 +3638,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$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				const target = before.pages[0];
@@ -3533,7 +3657,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("absolute rotation is idempotent: setting the same value twice is a no-op", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const first = await doc.pages.rotate([pon], 180);
@@ -3544,7 +3668,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("one rotation applies to EVERY listed page (the multi-select gesture)", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3556,7 +3680,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("weak index-based annotation refs survive a rotate (no revision bump)", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const hostPon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const hostPage = doc.page(hostPon);
@@ -3586,7 +3710,7 @@ function runPageRotateConformance(runner, opts) {
 			}
 		});
 		test("pages.rotate() rejects an invalid rotation value with InvalidArg", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -3595,13 +3719,13 @@ function runPageRotateConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.rotate() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -3610,13 +3734,13 @@ function runPageRotateConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.rotate() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -3628,13 +3752,13 @@ function runPageRotateConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort on pages.rotate() rejects with AbortError", async () => {
-			const doc = await openFixture$9(engine, opts);
+			const doc = await openFixture$12(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				const p = doc.pages.rotate([pon], 90);
@@ -3646,7 +3770,7 @@ function runPageRotateConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$9(engine, opts) {
+async function openFixture$12(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3709,7 +3833,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$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 2) return;
@@ -3730,7 +3854,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("addressing a deleted page afterwards is a clean NotFound", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 2) return;
@@ -3742,13 +3866,13 @@ function runPageDeleteConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("surviving pages keep their weak index-based annotation refs", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3781,7 +3905,7 @@ function runPageDeleteConformance(runner, opts) {
 			}
 		});
 		test("deleting EVERY page is rejected with InvalidArg", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let caught;
@@ -3790,13 +3914,13 @@ function runPageDeleteConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.delete() rejects duplicate PONs with InvalidArg", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -3805,13 +3929,13 @@ function runPageDeleteConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.delete() rejects unknown PON with NotFound or InvalidArg", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -3823,13 +3947,13 @@ function runPageDeleteConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort on pages.delete() rejects with AbortError", async () => {
-			const doc = await openFixture$8(engine, opts);
+			const doc = await openFixture$11(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				if (list.pages.length < 2) return;
@@ -3843,7 +3967,7 @@ function runPageDeleteConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$8(engine, opts) {
+async function openFixture$11(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -3871,7 +3995,7 @@ function runPageFlattenConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("flattens eligible appearances once without changing layout", async () => {
-			const doc = await openFixture$7(engine, opts);
+			const doc = await openFixture$10(engine, opts);
 			try {
 				if (!doc.pages.flatten) return;
 				const layoutBefore = await doc.pages.list();
@@ -3898,14 +4022,14 @@ function runPageFlattenConformance(runner, opts) {
 				expect(noOp.meta).toBeNull();
 				expect(events).toHaveLength(1);
 				unsubscribe();
-				await expect(doc.pages.flatten([pageObjectNumber, pageObjectNumber])).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				await expect(doc.pages.flatten([pageObjectNumber, pageObjectNumber])).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 			} finally {
 				await doc.close();
 			}
 		});
 	});
 }
-async function openFixture$7(engine, opts) {
+async function openFixture$10(engine, opts) {
 	if (opts.openKind === "bytes") return engine.open({
 		kind: "bytes",
 		id: opts.fixture.id,
@@ -3960,7 +4084,7 @@ function runRedactionApplyConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("annotations scope applies the marked redaction and counts collateral", async () => {
-			const doc = await openFixture$6(engine, opts);
+			const doc = await openFixture$9(engine, opts);
 			try {
 				if (!doc.redaction) return;
 				const layoutBefore = await doc.pages.list();
@@ -4014,7 +4138,7 @@ function runRedactionApplyConformance(runner, opts) {
 			}
 		});
 		test("pages scope applies everything once and validates its input", async () => {
-			const doc = await openFixture$6(engine, opts);
+			const doc = await openFixture$9(engine, opts);
 			try {
 				if (!doc.redaction) return;
 				const pageObjectNumber = (await doc.pages.list()).pages[0].pageObjectNumber;
@@ -4050,7 +4174,7 @@ function runRedactionApplyConformance(runner, opts) {
 				await expect(doc.redaction.apply({
 					kind: "pages",
 					pageObjectNumbers: [pageObjectNumber, pageObjectNumber]
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 				const notRedact = await page.annotations.create({
 					subtype: "highlight",
 					quadPoints: COLLATERAL_QUAD
@@ -4058,14 +4182,14 @@ function runRedactionApplyConformance(runner, opts) {
 				await expect(doc.redaction.apply({
 					kind: "annotations",
 					refs: [notRedact.created.ref]
-				})).rejects.toMatchObject({ code: require_subtype.EngineErrorCode.InvalidArg });
+				})).rejects.toMatchObject({ code: require_PageInsertBlankInput.EngineErrorCode.InvalidArg });
 			} finally {
 				await doc.close();
 			}
 		});
 	});
 }
-async function openFixture$6(engine, opts) {
+async function openFixture$9(engine, opts) {
 	if (opts.openKind === "bytes") return engine.open({
 		kind: "bytes",
 		id: opts.fixture.id,
@@ -4105,19 +4229,14 @@ function runPageExtractConformance(runner, opts) {
 	const { describe, test, beforeAll, afterAll, expect } = runner;
 	describe(`page extract conformance: ${opts.label}`, () => {
 		let engine;
-		let supported = false;
 		beforeAll(async () => {
 			engine = await opts.makeEngine();
-			const probe = await openFixture$5(engine, opts);
-			supported = probe.pages.extract !== void 0;
-			await probe.close();
 		});
 		afterAll(async () => {
 			if (engine) await engine.destroy();
 		});
 		test("pages.extract() returns standalone PDF bytes and leaves the source untouched", async () => {
-			if (!supported) return;
-			const doc = await openFixture$5(engine, opts);
+			const doc = await openFixture$8(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				const target = before.pages[before.pages.length - 1];
@@ -4132,8 +4251,8 @@ function runPageExtractConformance(runner, opts) {
 			}
 		});
 		test("extracted bytes re-open as a document with the requested pages, in caller order", async () => {
-			if (!supported || opts.openKind !== "bytes") return;
-			const doc = await openFixture$5(engine, opts);
+			if (opts.openKind !== "bytes") return;
+			const doc = await openFixture$8(engine, opts);
 			let extracted = null;
 			try {
 				const list = await doc.pages.list();
@@ -4156,8 +4275,7 @@ function runPageExtractConformance(runner, opts) {
 			}
 		});
 		test("pages.extract() rejects empty input with InvalidArg", async () => {
-			if (!supported) return;
-			const doc = await openFixture$5(engine, opts);
+			const doc = await openFixture$8(engine, opts);
 			try {
 				let caught;
 				try {
@@ -4165,14 +4283,13 @@ function runPageExtractConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.extract() rejects duplicate PONs with InvalidArg", async () => {
-			if (!supported) return;
-			const doc = await openFixture$5(engine, opts);
+			const doc = await openFixture$8(engine, opts);
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
 				let caught;
@@ -4181,14 +4298,13 @@ function runPageExtractConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("pages.extract() rejects unknown PON with NotFound or InvalidArg", async () => {
-			if (!supported) return;
-			const doc = await openFixture$5(engine, opts);
+			const doc = await openFixture$8(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				let bogus = 0;
@@ -4200,14 +4316,13 @@ function runPageExtractConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound) || require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort on pages.extract() rejects with AbortError", async () => {
-			if (!supported) return;
-			const doc = await openFixture$5(engine, opts);
+			const doc = await openFixture$8(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				const p = doc.pages.extract([list.pages[0].pageObjectNumber]);
@@ -4219,7 +4334,7 @@ function runPageExtractConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$5(engine, opts) {
+async function openFixture$8(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4481,9 +4596,9 @@ function runAttachmentConformance(runner, opts) {
 //#endregion
 //#region src/conformance/runPageInsertConformance.ts
 /**
-* Page insert conformance. `pages.insert?` is optional only until the cloud
-* endpoint ships (it is slated REQUIRED-parity — a cloud viewer must be able
-* to add pages); the suite runs wherever the implementation exists.
+* Page insert conformance. `pages.insert` is a REQUIRED member — this suite
+* runs unconditionally on every engine, so an implementation that loses the
+* verb fails loudly instead of being skipped past.
 *
 * Invariants:
 *   1. Every page of the source bytes is COPIED in at `destIndex` (omitted →
@@ -4499,19 +4614,14 @@ function runPageInsertConformance(runner, opts) {
 	const { describe, test, beforeAll, afterAll, expect } = runner;
 	describe(`page insert conformance: ${opts.label}`, () => {
 		let engine;
-		let supported = false;
 		beforeAll(async () => {
 			engine = await opts.makeEngine();
-			const probe = await openFixture$4(engine, opts);
-			supported = probe.pages.insert !== void 0 && probe.pages.extract !== void 0;
-			await probe.close();
 		});
 		afterAll(async () => {
 			if (engine) await engine.destroy();
 		});
 		test("appends every source page with fresh PONs; existing pages keep identity", async () => {
-			if (!supported) return;
-			const doc = await openFixture$4(engine, opts);
+			const doc = await openFixture$7(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				const beforePons = before.pages.map((p) => p.pageObjectNumber);
@@ -4529,8 +4639,7 @@ function runPageInsertConformance(runner, opts) {
 			}
 		});
 		test("destIndex places the block mid-document, in source order", async () => {
-			if (!supported) return;
-			const doc = await openFixture$4(engine, opts);
+			const doc = await openFixture$7(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				if (before.pages.length < 2) return;
@@ -4547,8 +4656,8 @@ function runPageInsertConformance(runner, opts) {
 			}
 		});
 		test("the inserted pages persist through save → re-open", async () => {
-			if (!supported || opts.openKind !== "bytes") return;
-			const doc = await openFixture$4(engine, opts);
+			if (opts.openKind !== "bytes") return;
+			const doc = await openFixture$7(engine, opts);
 			let reopened = null;
 			try {
 				const before = await doc.pages.list();
@@ -4568,8 +4677,7 @@ function runPageInsertConformance(runner, opts) {
 			}
 		});
 		test("empty bytes reject with InvalidArg; garbage rejects with MalformedPdf", async () => {
-			if (!supported) return;
-			const doc = await openFixture$4(engine, opts);
+			const doc = await openFixture$7(engine, opts);
 			try {
 				let caught;
 				try {
@@ -4577,14 +4685,14 @@ function runPageInsertConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 				caught = void 0;
 				try {
 					await doc.pages.insert(new TextEncoder().encode("not a pdf at all"));
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.MalformedPdf)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.MalformedPdf)).toBe(true);
 				const list = await doc.pages.list();
 				expect(list.pageCount > 0).toBe(true);
 			} finally {
@@ -4592,8 +4700,7 @@ function runPageInsertConformance(runner, opts) {
 			}
 		});
 		test("out-of-range destIndex rejects with InvalidArg", async () => {
-			if (!supported) return;
-			const doc = await openFixture$4(engine, opts);
+			const doc = await openFixture$7(engine, opts);
 			try {
 				const before = await doc.pages.list();
 				const single = await doc.pages.extract([before.pages[0].pageObjectNumber]);
@@ -4603,14 +4710,167 @@ function runPageInsertConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 	});
 }
-async function openFixture$4(engine, opts) {
+async function openFixture$7(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/runPageInsertBlankConformance.ts
+/** An on-purpose non-default size so the assertions can't pass by accident. */
+const SIZE = {
+	width: 396,
+	height: 612
+};
+/**
+* Blank-page insert conformance. `pages.insertBlank` is a REQUIRED member —
+* the suite runs unconditionally on every engine (no fixture bytes are
+* needed at all, which is the point of the verb), so an implementation that
+* loses the verb fails loudly instead of being skipped past.
+*
+* Invariants:
+*   1. `count` blank pages of exactly `size` appear at `destIndex` (omitted
+*      → append), rotation 0; the result lists their fresh PONs in insertion
+*      order and they agree with the returned layout.
+*   2. Pre-existing pages keep their identity: same PONs before and after,
+*      in the expected positions (an insert never invalidates neighbours).
+*   3. The mutation persists through save → re-open (bytes engines only).
+*   4. Non-positive size / count outside [1, PAGE_INSERT_BLANK_MAX_COUNT] /
+*      out-of-range destIndex reject with InvalidArg, leaving the document
+*      untouched.
+*/
+function runPageInsertBlankConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	describe(`page insert-blank conformance: ${opts.label}`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		test("appends one blank page of the requested size with a fresh PON", async () => {
+			const doc = await openFixture$6(engine, opts);
+			try {
+				const before = await doc.pages.list();
+				const beforePons = before.pages.map((p) => p.pageObjectNumber);
+				const result = await doc.pages.insertBlank({ size: SIZE });
+				expect(result.insertedPageObjectNumbers.length).toBe(1);
+				expect(result.layout.pageCount).toBe(before.pageCount + 1);
+				expect(result.layout.pages.slice(0, before.pageCount).map((p) => p.pageObjectNumber)).toEqual(beforePons);
+				const newPon = result.insertedPageObjectNumbers[0];
+				expect(beforePons.includes(newPon)).toBe(false);
+				const appended = result.layout.pages[before.pageCount];
+				expect(appended.pageObjectNumber).toBe(newPon);
+				expect(appended.size).toEqual(SIZE);
+				expect(appended.rotation).toBe(0);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("destIndex + count places the blank block mid-document", async () => {
+			const doc = await openFixture$6(engine, opts);
+			try {
+				const before = await doc.pages.list();
+				if (before.pages.length < 2) return;
+				const beforePons = before.pages.map((p) => p.pageObjectNumber);
+				const result = await doc.pages.insertBlank({
+					size: SIZE,
+					count: 2
+				}, 1);
+				expect(result.insertedPageObjectNumbers.length).toBe(2);
+				expect(result.insertedPageObjectNumbers[0] === result.insertedPageObjectNumbers[1]).toBe(false);
+				const pons = result.layout.pages.map((p) => p.pageObjectNumber);
+				expect(pons[0]).toBe(beforePons[0]);
+				expect(pons.slice(1, 3)).toEqual(result.insertedPageObjectNumbers);
+				expect(pons.slice(3)).toEqual(beforePons.slice(1));
+				expect(result.layout.pages[1].size).toEqual(SIZE);
+				expect(result.layout.pages[2].size).toEqual(SIZE);
+			} finally {
+				await doc.close();
+			}
+		});
+		test("the blank pages persist through save → re-open", async () => {
+			if (opts.openKind !== "bytes") return;
+			const doc = await openFixture$6(engine, opts);
+			let reopened = null;
+			try {
+				const before = await doc.pages.list();
+				await doc.pages.insertBlank({ size: SIZE });
+				const bytes = await doc.download();
+				reopened = await engine.open({
+					kind: "bytes",
+					id: `${opts.fixture.id}-insert-blank-reopen`,
+					bytes
+				});
+				const after = await reopened.pages.list();
+				expect(after.pageCount).toBe(before.pageCount + 1);
+				const tail = after.pages[after.pageCount - 1];
+				expect(Math.round(tail.size.width)).toBe(SIZE.width);
+				expect(Math.round(tail.size.height)).toBe(SIZE.height);
+			} finally {
+				if (reopened) await reopened.close();
+				await doc.close();
+			}
+		});
+		test("non-positive size, bad count, and out-of-range destIndex reject with InvalidArg", async () => {
+			const doc = await openFixture$6(engine, opts);
+			try {
+				const before = await doc.pages.list();
+				const rejects = [
+					() => doc.pages.insertBlank({ size: {
+						width: 0,
+						height: 612
+					} }),
+					() => doc.pages.insertBlank({ size: {
+						width: 396,
+						height: -10
+					} }),
+					() => doc.pages.insertBlank({
+						size: SIZE,
+						count: 0
+					}),
+					() => doc.pages.insertBlank({
+						size: SIZE,
+						count: 101
+					}),
+					() => doc.pages.insertBlank({ size: SIZE }, before.pageCount + 1)
+				];
+				for (const attempt of rejects) {
+					let caught;
+					try {
+						await attempt();
+					} catch (err) {
+						caught = err;
+					}
+					expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
+				}
+				const list = await doc.pages.list();
+				expect(list.pageCount).toBe(before.pageCount);
+				expect(list.pages.map((p) => p.pageObjectNumber)).toEqual(before.pages.map((p) => p.pageObjectNumber));
+			} finally {
+				await doc.close();
+			}
+		});
+	});
+}
+async function openFixture$6(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4651,7 +4911,7 @@ function runPieceInfoConformance(runner, opts) {
 		let supported = false;
 		beforeAll(async () => {
 			engine = await opts.makeEngine();
-			const probe = await openFixture$3(engine, opts);
+			const probe = await openFixture$5(engine, opts);
 			supported = probe.pieceInfo !== void 0;
 			await probe.close();
 		});
@@ -4660,7 +4920,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 		test("doc-level: the full value vocabulary round-trips with tags intact", async () => {
 			if (!supported) return;
-			const doc = await openFixture$3(engine, opts);
+			const doc = await openFixture$5(engine, opts);
 			try {
 				await doc.pieceInfo.update(APP, {
 					name: "Standard Stamps",
@@ -4700,7 +4960,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 		test("page-level: the stamp schema round-trips on a page", async () => {
 			if (!supported) return;
-			const doc = await openFixture$3(engine, opts);
+			const doc = await openFixture$5(engine, opts);
 			try {
 				const list = await doc.pages.list();
 				const page = doc.page(list.pages[0].pageObjectNumber);
@@ -4726,7 +4986,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 		test("writes persist through save → re-open", async () => {
 			if (!supported || opts.openKind !== "bytes") return;
-			const doc = await openFixture$3(engine, opts);
+			const doc = await openFixture$5(engine, opts);
 			let reopened = null;
 			try {
 				const pon = (await doc.pages.list()).pages[0].pageObjectNumber;
@@ -4759,7 +5019,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 		test("null deletes a key; clear removes an entry; siblings survive", async () => {
 			if (!supported) return;
-			const doc = await openFixture$3(engine, opts);
+			const doc = await openFixture$5(engine, opts);
 			try {
 				await doc.pieceInfo.update(APP, {
 					name: "A",
@@ -4785,7 +5045,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 		test("an application that was never written reads as null", async () => {
 			if (!supported) return;
-			const doc = await openFixture$3(engine, opts);
+			const doc = await openFixture$5(engine, opts);
 			try {
 				expect(await doc.pieceInfo.read("EMBD_NeverWritten")).toBe(null);
 				const list = await doc.pages.list();
@@ -4796,7 +5056,7 @@ function runPieceInfoConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$3(engine, opts) {
+async function openFixture$5(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4859,7 +5119,7 @@ function runDocumentEventsConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("every confirmed mutation publishes exactly one event, results verbatim", async () => {
-			const doc = await openFixture$2(engine, opts);
+			const doc = await openFixture$4(engine, opts);
 			try {
 				const events = [];
 				doc.events.subscribe((event) => events.push(event));
@@ -4906,19 +5166,46 @@ function runDocumentEventsConformance(runner, opts) {
 					expect(evDeleted.layout).toEqual(deleted.layout);
 				}
 				if (evMeta.type === "metadata.updated") expect(evMeta.metadata).toEqual(meta.metadata);
+				const first = events[0];
+				expect(first !== void 0 && "origin" in first).toBe(true);
+				if (first === void 0 || !("origin" in first)) return;
 				for (const event of events) {
+					expect("origin" in event).toBe(true);
+					if (!("origin" in event)) continue;
 					expect(event.origin.kind).toBe("local");
 					expect(typeof event.origin.sessionId).toBe("string");
 					expect(event.origin.sessionId.length > 0).toBe(true);
-					expect(event.origin.sessionId).toBe(events[0].origin.sessionId);
+					expect(event.origin.sessionId).toBe(first.origin.sessionId);
 					expect(typeof event.origin.ts).toBe("number");
 				}
 			} finally {
 				await doc.close();
 			}
 		});
+		test("pages.inserted rides verbatim", async () => {
+			const doc = await openFixture$4(engine, opts);
+			try {
+				const events = [];
+				doc.events.subscribe((event) => events.push(event));
+				const inserted = await doc.pages.insertBlank({ size: {
+					width: 396,
+					height: 612
+				} }, 0);
+				expect(events.map((event) => event.type)).toEqual(["pages.inserted"]);
+				const [evInserted] = events;
+				if (evInserted.type === "pages.inserted") {
+					expect(evInserted.insertedPageObjectNumbers).toEqual(inserted.insertedPageObjectNumbers);
+					expect(evInserted.layout).toEqual(inserted.layout);
+					expect(evInserted.cache).toEqual(inserted.cache);
+					expect(evInserted.destIndex).toBe(0);
+					expect(evInserted.origin.kind).toBe("local");
+				}
+			} finally {
+				await doc.close();
+			}
+		});
 		test("a FAILED mutation publishes nothing (events are ground truth)", async () => {
-			const doc = await openFixture$2(engine, opts);
+			const doc = await openFixture$4(engine, opts);
 			try {
 				const events = [];
 				doc.events.subscribe((event) => events.push(event));
@@ -4936,7 +5223,7 @@ function runDocumentEventsConformance(runner, opts) {
 			}
 		});
 		test("unsubscribe stops delivery", async () => {
-			const doc = await openFixture$2(engine, opts);
+			const doc = await openFixture$4(engine, opts);
 			try {
 				const events = [];
 				doc.events.subscribe((event) => events.push(event))();
@@ -4949,7 +5236,7 @@ function runDocumentEventsConformance(runner, opts) {
 		});
 	});
 }
-async function openFixture$2(engine, opts) {
+async function openFixture$4(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
 		return engine.open({
@@ -4976,7 +5263,7 @@ function runPageTextConformance(runner, opts) {
 			if (engine) await engine.destroy();
 		});
 		test("read() returns a PageTextSnapshot with non-empty text", async () => {
-			const doc = await openFixture$1(engine, opts);
+			const doc = await openFixture$3(engine, opts);
 			try {
 				const snap = await doc.page(opts.fixture.pageObjectNumber).text.read();
 				expect(require_schemas.PageTextSnapshotSchema.safeParse(snap).success).toBe(true);
@@ -4987,7 +5274,7 @@ function runPageTextConformance(runner, opts) {
 			}
 		});
 		test("extracted text contains the expected substring", async () => {
-			const doc = await openFixture$1(engine, opts);
+			const doc = await openFixture$3(engine, opts);
 			try {
 				const snap = await doc.page(opts.fixture.pageObjectNumber).text.read();
 				expect(snap.text.includes(opts.fixture.expectedSubstring)).toBe(true);
@@ -4996,7 +5283,7 @@ function runPageTextConformance(runner, opts) {
 			}
 		});
 		test("read() on an unknown pageObjectNumber throws NotFound", async () => {
-			const doc = await openFixture$1(engine, opts);
+			const doc = await openFixture$3(engine, opts);
 			try {
 				let caught;
 				try {
@@ -5005,13 +5292,13 @@ function runPageTextConformance(runner, opts) {
 					caught = err;
 				}
 				expect(caught).toBeTruthy();
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.NotFound)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.NotFound)).toBe(true);
 			} finally {
 				await doc.close();
 			}
 		});
 		test("abort() on read rejects with AbortError", async () => {
-			const doc = await openFixture$1(engine, opts);
+			const doc = await openFixture$3(engine, opts);
 			try {
 				const p = doc.page(opts.fixture.pageObjectNumber).text.read();
 				p.abort("test");
@@ -5021,7 +5308,7 @@ function runPageTextConformance(runner, opts) {
 			}
 		});
 		test("read after close throws DocNotOpen", async () => {
-			const doc = await openFixture$1(engine, opts);
+			const doc = await openFixture$3(engine, opts);
 			const page = doc.page(opts.fixture.pageObjectNumber);
 			await doc.close();
 			let caught;
@@ -5031,10 +5318,324 @@ function runPageTextConformance(runner, opts) {
 				caught = err;
 			}
 			expect(caught).toBeTruthy();
-			expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.DocNotOpen)).toBe(true);
+			expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.DocNotOpen)).toBe(true);
+		});
+	});
+}
+async function openFixture$3(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/runTextDivergenceConformance.ts
+function runTextDivergenceConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	const fixture = opts.fixture;
+	describe(`text divergence conformance: ${opts.label} [${fixture.id}]`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		test("snapshot is schema-valid with the exact text, charCount, and charMap", async () => {
+			const doc = await openFixture$2(engine, opts);
+			try {
+				const snap = await doc.page(fixture.pageObjectNumber).text.read();
+				expect(require_schemas.PageTextSnapshotSchema.safeParse(snap).success).toBe(true);
+				expect(snap.text).toBe(fixture.exactText);
+				expect(snap.charCount).toBe(fixture.expectedCharCount);
+				const anchors = snap.charMap ?? null;
+				if (fixture.expectedCharMap === null) expect(anchors === null || anchors.length === 0).toBe(true);
+				else expect(anchors === null ? null : anchors.map((a) => [a[0], a[1]])).toEqual(fixture.expectedCharMap.map((a) => [a[0], a[1]]));
+			} finally {
+				await doc.close();
+			}
+		});
+		test("char-space slicing round-trips through the map", async () => {
+			const doc = await openFixture$2(engine, opts);
+			try {
+				const snap = await doc.page(fixture.pageObjectNumber).text.read();
+				expect(require_PageInsertBlankInput.sliceTextByChars(snap, 0, snap.charCount)).toBe(snap.text);
+				for (const s of fixture.slices ?? []) expect(require_PageInsertBlankInput.sliceTextByChars(snap, s.from, s.to)).toBe(s.text);
+			} finally {
+				await doc.close();
+			}
+		});
+		if (fixture.search) {
+			const probe = fixture.search;
+			test("search hits address character space and join the text by slicing", async () => {
+				const doc = await openFixture$2(engine, opts);
+				try {
+					const hit = (await doc.search.query({
+						query: { text: probe.query },
+						mode: "rects"
+					})).matches.find((m) => m.pageObjectNumber === fixture.pageObjectNumber);
+					expect(hit === void 0).toBe(false);
+					expect(hit.charStart).toBe(probe.charStart);
+					expect(hit.charCount).toBe(probe.charCount);
+					expect(hit.segments.length > 0).toBe(true);
+					const snap = await doc.page(fixture.pageObjectNumber).text.read();
+					expect(require_PageInsertBlankInput.sliceTextByChars(snap, hit.charStart, hit.charStart + hit.charCount)).toBe(probe.matchedText);
+				} finally {
+					await doc.close();
+				}
+			});
+		}
+	});
+}
+async function openFixture$2(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
 	});
 }
+/**
+* THE pinned divergence cases — one table, consumed by both engines' suites
+* so expected values cannot drift. Values verified against the wasm runtime
+* (see each case). All fixtures are single-page; the page's indirect object
+* number is 3 in each.
+*/
+const TEXT_DIVERGENCE_CASES = {
+	/** Leading NON-PRINTING character: 31 character slots, 30 text units —
+	*  every text offset shifts by one, encoded by the single anchor [1, 0].
+	*  The searchex embeddertest for this fixture pins the same +1 shift. */
+	bug1139: {
+		resource: "bug_1139.pdf",
+		pageObjectNumber: 3,
+		exactText: "Hello, world!\r\nGoodbye, world!",
+		expectedCharCount: 31,
+		expectedCharMap: [[1, 0]],
+		slices: [
+			{
+				from: 0,
+				to: 1,
+				text: ""
+			},
+			{
+				from: 1,
+				to: 7,
+				text: "Hello,"
+			},
+			{
+				from: 16,
+				to: 23,
+				text: "Goodbye"
+			}
+		],
+		search: {
+			query: "Goodbye",
+			charStart: 16,
+			charCount: 7,
+			matchedText: "Goodbye"
+		}
+	},
+	/** `/ActualText` replacement: the span's real glyphs are REPLACED by one
+	*  synthetic kPiece character per ActualText character, lockstep with the
+	*  text (identity map), with synthesized evenly-divided boxes — so search
+	*  segments exist and extraction yields the ActualText, not the glyphs. */
+	actualText: {
+		resource: "bug_384770169.pdf",
+		pageObjectNumber: 3,
+		exactText: "What is my favorite food?",
+		expectedCharCount: 25,
+		expectedCharMap: null,
+		slices: [{
+			from: 11,
+			to: 19,
+			text: "favorite"
+		}],
+		search: {
+			query: "favorite",
+			charStart: 11,
+			charCount: 8,
+			matchedText: "favorite"
+		}
+	},
+	/** Supplementary-plane text via a ToUnicode surrogate pair: PDFium stores
+	*  one character-list entry PER SURROGATE HALF in lockstep with the text
+	*  (identity map, no divergence in this representation) — and the emoji
+	*  SURVIVES extraction end to end. The combined-astral representation
+	*  (font-cmap path, one entry per code point → a [+2] anchor) is covered
+	*  by the charmap unit tests and the reader's divergent walk. */
+	astralToUnicode: {
+		resource: "embedpdf_astral_tounicode.pdf",
+		pageObjectNumber: 3,
+		exactText: "😀B!",
+		expectedCharCount: 4,
+		expectedCharMap: null,
+		slices: [{
+			from: 0,
+			to: 2,
+			text: "😀"
+		}, {
+			from: 2,
+			to: 3,
+			text: "B"
+		}],
+		search: {
+			query: "B!",
+			charStart: 2,
+			charCount: 2,
+			matchedText: "B!"
+		}
+	}
+};
+//#endregion
+//#region src/conformance/runPageGeometryOrientationConformance.ts
+const FLAG_EMPTY = 2;
+/** Absolute tolerance for coordinate assertions (PDF points). */
+const COORD_TOLERANCE = .001;
+/** Tolerance for baseline-angle assertions (radians). */
+const ANGLE_TOLERANCE = .001;
+function runPageGeometryOrientationConformance(runner, opts) {
+	const { describe, test, beforeAll, afterAll, expect } = runner;
+	describe(`page geometry orientation conformance: ${opts.label} [${opts.fixture.id}]`, () => {
+		let engine;
+		beforeAll(async () => {
+			engine = await opts.makeEngine();
+		});
+		afterAll(async () => {
+			if (engine) await engine.destroy();
+		});
+		const readSnapshot = async () => {
+			const doc = await openFixture$1(engine, opts);
+			return {
+				snapshot: await doc.page(opts.fixture.pageObjectNumber).geometry.read(),
+				close: () => doc.close()
+			};
+		};
+		test("snapshot round-trips the wire schema", async () => {
+			const { snapshot, close } = await readSnapshot();
+			try {
+				const parsed = require_schemas.PageGeometrySnapshotSchema.safeParse(snapshot);
+				expect(parsed.success).toBe(true);
+				if (parsed.success) expect(parsed.data).toEqual(snapshot);
+			} finally {
+				await close();
+			}
+		});
+		test("run charStart indices tile the page glyph sequence", async () => {
+			const { snapshot, close } = await readSnapshot();
+			try {
+				let next = 0;
+				for (const run of snapshot.runs) {
+					expect(run.charStart).toBe(next);
+					next += run.glyphs.length;
+				}
+			} finally {
+				await close();
+			}
+		});
+		test("runs match the fixture orientation expectation", async () => {
+			const { snapshot, close } = await readSnapshot();
+			try {
+				const expectation = opts.fixture.expectation;
+				if (expectation.kind === "upright") {
+					for (const run of snapshot.runs) {
+						expect(require_fold.isRotatedGeometryRun(run)).toBe(false);
+						if (require_fold.isRotatedGeometryRun(run)) continue;
+						for (const glyph of run.glyphs) {
+							expect("looseQuad" in glyph).toBe(false);
+							if (glyph.flags & FLAG_EMPTY) expect(glyph.looseBox).toEqual({
+								left: 0,
+								bottom: 0,
+								right: 0,
+								top: 0
+							});
+						}
+					}
+					return;
+				}
+				if (expectation.kind === "empty-only") {
+					for (const run of snapshot.runs) {
+						expect(require_fold.isRotatedGeometryRun(run)).toBe(false);
+						if (require_fold.isRotatedGeometryRun(run)) continue;
+						for (const glyph of run.glyphs) {
+							expect(glyph.flags & FLAG_EMPTY).toBe(FLAG_EMPTY);
+							expect(glyph.looseBox).toEqual({
+								left: 0,
+								bottom: 0,
+								right: 0,
+								top: 0
+							});
+						}
+					}
+					return;
+				}
+				const rotatedRuns = snapshot.runs.filter(require_fold.isRotatedGeometryRun);
+				expect(rotatedRuns.length >= (expectation.minRotatedRuns ?? 1)).toBe(true);
+				for (const run of rotatedRuns) {
+					expect(expectation.rotations.some((angle) => angleClose(run.rotation, angle, ANGLE_TOLERANCE))).toBe(true);
+					expect(run.ascentFlip).toBe(expectation.ascentFlip);
+					assertRotatedRunGeometry(run);
+				}
+				if (expectation.sheared) {
+					const shearedGlyphs = rotatedRuns.flatMap((run) => run.glyphs).filter((glyph) => (glyph.flags & FLAG_EMPTY) === 0 && Math.abs(glyph.looseQuad.p3.x - glyph.looseQuad.p1.x) > 1);
+					expect(shearedGlyphs.length > 0).toBe(true);
+				}
+			} finally {
+				await close();
+			}
+		});
+		function assertRotatedRunGeometry(run) {
+			for (const glyph of run.glyphs) {
+				if (glyph.flags & FLAG_EMPTY) {
+					expect(glyph.looseQuad).toEqual({
+						p1: {
+							x: 0,
+							y: 0
+						},
+						p2: {
+							x: 0,
+							y: 0
+						},
+						p3: {
+							x: 0,
+							y: 0
+						},
+						p4: {
+							x: 0,
+							y: 0
+						}
+					});
+					continue;
+				}
+				const q = glyph.looseQuad;
+				expect(Math.abs(q.p2.x - q.p1.x - (q.p4.x - q.p3.x)) <= COORD_TOLERANCE).toBe(true);
+				expect(Math.abs(q.p2.y - q.p1.y - (q.p4.y - q.p3.y)) <= COORD_TOLERANCE).toBe(true);
+				const bounds = require_fold.pdfQuadBounds(q);
+				expect(bounds.left >= run.rect.left - COORD_TOLERANCE).toBe(true);
+				expect(bounds.right <= run.rect.right + COORD_TOLERANCE).toBe(true);
+				expect(bounds.bottom >= run.rect.bottom - COORD_TOLERANCE).toBe(true);
+				expect(bounds.top <= run.rect.top + COORD_TOLERANCE).toBe(true);
+			}
+		}
+	});
+}
+function angleClose(a, b, tolerance) {
+	const delta = a - b;
+	return Math.abs(Math.atan2(Math.sin(delta), Math.cos(delta))) <= tolerance;
+}
 async function openFixture$1(engine, opts) {
 	if (opts.openKind === "bytes") {
 		const bytes = await opts.fixture.bytes();
@@ -5090,10 +5691,27 @@ function runSearchConformance(runner, opts) {
 				expect(matches.some((m) => m.pageObjectNumber === fixture.presentPageObjectNumber)).toBe(true);
 				for (const m of matches) {
 					expect(m.charCount > 0).toBe(true);
-					expect(m.rects.length > 0).toBe(true);
-					for (const r of m.rects) {
-						expect(r.right > r.left).toBe(true);
-						expect(r.top > r.bottom).toBe(true);
+					expect(m.segments.length > 0).toBe(true);
+					for (const s of m.segments) {
+						expect(s.rect.right > s.rect.left).toBe(true);
+						expect(s.rect.top > s.rect.bottom).toBe(true);
+						const xs = [
+							s.quad.p1.x,
+							s.quad.p2.x,
+							s.quad.p3.x,
+							s.quad.p4.x
+						];
+						const ys = [
+							s.quad.p1.y,
+							s.quad.p2.y,
+							s.quad.p3.y,
+							s.quad.p4.y
+						];
+						expect(Math.abs(s.rect.left - Math.min(...xs)) < .001).toBe(true);
+						expect(Math.abs(s.rect.right - Math.max(...xs)) < .001).toBe(true);
+						expect(Math.abs(s.rect.bottom - Math.min(...ys)) < .001).toBe(true);
+						expect(Math.abs(s.rect.top - Math.max(...ys)) < .001).toBe(true);
+						expect(s.advance === 1 || s.advance === -1).toBe(true);
 					}
 				}
 			} finally {
@@ -5193,7 +5811,7 @@ function runSearchConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
@@ -5210,7 +5828,7 @@ function runSearchConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
@@ -5225,7 +5843,7 @@ function runSearchConformance(runner, opts) {
 				expect(matches.length > 0).toBe(true);
 				for (const m of matches) {
 					expect(m.charCount > 0).toBe(true);
-					expect(m.rects.length > 0).toBe(true);
+					expect(m.segments.length > 0).toBe(true);
 				}
 			} finally {
 				await doc.close();
@@ -5266,7 +5884,7 @@ function runSearchConformance(runner, opts) {
 				} catch (err) {
 					caught = err;
 				}
-				expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+				expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 			} finally {
 				await doc.close();
 			}
@@ -5288,7 +5906,7 @@ function runSearchConformance(runner, opts) {
 					} catch (err) {
 						caught = err;
 					}
-					expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.InvalidArg)).toBe(true);
+					expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.InvalidArg)).toBe(true);
 				}
 			} finally {
 				await doc.close();
@@ -5323,7 +5941,7 @@ function runSearchConformance(runner, opts) {
 			} catch (err) {
 				caught = err;
 			}
-			expect(require_fold.EngineError.is(caught, require_subtype.EngineErrorCode.DocNotOpen)).toBe(true);
+			expect(require_fold.EngineError.is(caught, require_PageInsertBlankInput.EngineErrorCode.DocNotOpen)).toBe(true);
 		});
 	});
 }
@@ -5352,6 +5970,8 @@ async function openFixture(engine, opts) {
 * are disjoint. We do compare `pageObjectNumber` and `generation` (which
 * should be 0 for fresh reads on both sides). Page order is no longer part
 * of `PageState`; it lives in `PageLayout.index` (see `pages.list()`).
+* `auditHead` is likewise not compared: it is a cloud-only reconciliation
+* cursor, absent on local snapshots by design.
 */
 function diffAnnotationListSnapshot(a, b) {
 	const errs = [];
@@ -5390,6 +6010,7 @@ function diffAnnotation(i, a, b, errs) {
 	if (a.nm !== b.nm) errs.push(`annotations[${i}].nm mismatch: ${a.nm} vs ${b.nm}`);
 }
 //#endregion
+exports.TEXT_DIVERGENCE_CASES = TEXT_DIVERGENCE_CASES;
 exports.diffAnnotationListSnapshot = diffAnnotationListSnapshot;
 exports.diffAnnotationListSnapshotAll = diffAnnotationListSnapshotAll;
 exports.runActionsConformance = runActionsConformance;
@@ -5403,6 +6024,8 @@ exports.runMetadataConformance = runMetadataConformance;
 exports.runPageDeleteConformance = runPageDeleteConformance;
 exports.runPageExtractConformance = runPageExtractConformance;
 exports.runPageFlattenConformance = runPageFlattenConformance;
+exports.runPageGeometryOrientationConformance = runPageGeometryOrientationConformance;
+exports.runPageInsertBlankConformance = runPageInsertBlankConformance;
 exports.runPageInsertConformance = runPageInsertConformance;
 exports.runPageReorderConformance = runPageReorderConformance;
 exports.runPageRotateConformance = runPageRotateConformance;
@@ -5410,5 +6033,6 @@ exports.runPageTextConformance = runPageTextConformance;
 exports.runPieceInfoConformance = runPieceInfoConformance;
 exports.runRedactionApplyConformance = runRedactionApplyConformance;
 exports.runSearchConformance = runSearchConformance;
+exports.runTextDivergenceConformance = runTextDivergenceConformance;
 
 //# sourceMappingURL=conformance.cjs.map