@cloudpdf/engine 3.0.0-next.14 → 3.0.0-next.15

package/dist/index.cjs

@@ -1,11 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
 let _embedpdf_engine_core_wire = require("@embedpdf/engine-core/wire");
-let _embedpdf_engine_services = require("@embedpdf/engine-services");
 //#region src/document/planes.ts
 /**
-* Plane-scope resolution — THE one rule every cloud service uses to pick a
-* path family: a read resolves at the DOC-LEVEL (shared base) path iff EVERY
+* Plane-scope resolution — the one rule every cloud service uses to pick a
+* path family: a read resolves at the doc-level (shared base) path iff every
 * plane it depends on is inherited (`'base'`) by this layer. One owned plane
 * → the layer-scoped path.
 *
@@ -27,7 +26,7 @@ var CloudDocumentActionsService = class {
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 	}
-	read() {
+	get() {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJsonWithRefresh(async (currentSignal) => {
 			const manifest = await this.manifest.get(currentSignal);
@@ -38,42 +37,48 @@ var CloudDocumentActionsService = class {
 	}
 };
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
-function _typeof(o) {
-	"@babel/helpers - typeof";
-	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
-		return typeof o;
-	} : function(o) {
-		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
-	}, _typeof(o);
-}
-//#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
-function toPrimitive(t, r) {
-	if ("object" != _typeof(t) || !t) return t;
-	var e = t[Symbol.toPrimitive];
-	if (void 0 !== e) {
-		var i = e.call(t, r || "default");
-		if ("object" != _typeof(i)) return i;
-		throw new TypeError("@@toPrimitive must return a primitive value.");
+//#region src/transport/bundleMultipart.ts
+/** The server holds the bundle limits; the client only checks what arrived. */
+const NO_BUNDLE_LIMITS = {
+	bundleBytes: Infinity,
+	manifestBytes: Infinity,
+	items: Infinity,
+	pages: Infinity,
+	resources: Infinity,
+	resourceBytes: Infinity,
+	imagePixels: Infinity
+};
+/**
+* An exported bundle as the server sends it: the `body` part (the bundle
+* without its bytes, as JSON) and one `resource:<id>` part per resource.
+* The caller checks the bundle.
+*/
+async function readBundleParts(kind, form) {
+	const body = form.get("body");
+	if (typeof body !== "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `${kind} export has no body part`);
+	const resources = {};
+	const parts = [];
+	form.forEach((value, name) => parts.push([name, value]));
+	for (const [name, value] of parts) {
+		if (!name.startsWith("resource:")) continue;
+		if (typeof value === "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `${kind} export part ${name} is text`);
+		resources[name.slice(9)] = new Uint8Array(await value.arrayBuffer());
 	}
-	return ("string" === r ? String : Number)(t);
-}
-//#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
-function toPropertyKey(t) {
-	var i = toPrimitive(t, "string");
-	return "symbol" == _typeof(i) ? i : i + "";
+	return {
+		body: JSON.parse(body),
+		resources
+	};
 }
-//#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/defineProperty.js
-function _defineProperty(e, r, t) {
-	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
-		value: t,
-		enumerable: !0,
-		configurable: !0,
-		writable: !0
-	}) : e[r] = t, e;
+/**
+* A bundle import as one multipart body: the `body` part (the bundle
+* without its bytes, and the options), then each resource once, as a
+* `resource:<id>` part.
+*/
+function bundleImportForm(body, resources) {
+	const form = new FormData();
+	form.append("body", JSON.stringify(body));
+	for (const [id, bytes] of Object.entries(resources)) form.append(`resource:${id}`, new Blob([bytes]), id);
+	return form;
 }
 //#endregion
 //#region src/document/CloudDocumentAnnotationsService.ts
@@ -81,29 +86,41 @@ function _defineProperty(e, r, t) {
 *  version (404 on the immutable leaf → refresh the manifest → retry). */
 const MAX_COHERENCE_RESTARTS = 2;
 var CloudDocumentAnnotationsService = class {
-	constructor(http, docId, layerName, isClosed, manifest) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes, importLimits) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
+		this.publisher = publisher;
+		this.writes = writes;
+		this.importLimits = importLimits;
 	}
 	/**
-	* One COHERENT whole-document snapshot: a single read of the immutable
-	* `annotations/items@annotationsVersion=N` leaf at the manifest's pin —
-	* materialized server-side by one raw (no page-load) sweep, CDN-cacheable
-	* because the pin bumps only when annotation list bodies actually change.
-	* A stale pin mid-read (a concurrent mutation → 404) refreshes the
-	* manifest and retries, so the result always belongs to one document
-	* moment (the torn read this method exists to prevent).
+	* Every page: one coherent whole-document snapshot, a single read of the
+	* immutable `annotations/items@annotationsVersion=N` leaf at the
+	* manifest's pin — materialized server-side by one raw (no page-load)
+	* sweep, CDN-cacheable because the pin bumps only when annotation list
+	* bodies actually change. A stale pin mid-read (a concurrent mutation →
+	* 404) refreshes the manifest and retries, so the result always belongs
+	* to one document moment (the torn read this method exists to prevent).
+	*
+	* Some pages: each page's versioned leaf, the same read as
+	* `page.annotations.list()`, in the order asked.
 	*/
-	listRawAll() {
+	list(options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
+		const { pages } = options;
+		if (pages !== void 0) return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => (0, _embedpdf_engine_core_runtime.concatAnnotationLists)(await Promise.all(pages.map((page) => this.readPage(page, signal)))));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			for (let attempt = 0;; attempt++) {
 				const manifest = attempt === 0 ? await this.manifest.get(signal) : await this.manifest.refresh(signal);
 				try {
-					return await this.readBulkAt(manifest, signal);
+					const list = await this.readBulkAt(manifest, signal);
+					return {
+						...list,
+						auditHead: list.auditHead ?? manifest.auditHead
+					};
 				} catch (err) {
 					if (!_embedpdf_engine_core_runtime.EngineError.is(err, _embedpdf_engine_core_runtime.EngineErrorCode.NotFound) || attempt >= MAX_COHERENCE_RESTARTS) throw err;
 				}
@@ -117,90 +134,120 @@ var CloudDocumentAnnotationsService = class {
 	*  that window over the body is all no-ops. */
 	async readBulkAt(manifest, signal) {
 		const path = planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docAnnotationsAll(this.docId, manifest.annotationsVersion) : _embedpdf_engine_core_wire.wirePaths.layerAnnotationsAll(this.docId, this.layerName, manifest.annotationsVersion);
-		const body = await this.http.getJson(path, (raw) => _embedpdf_engine_core_wire.AnnotationListSnapshotAllPagesSchema.parse(raw), signal);
-		return {
-			...body,
-			auditHead: body.auditHead ?? manifest.auditHead
-		};
+		return this.http.getJson(path, (raw) => _embedpdf_engine_core_wire.AnnotationListSchema.parse(raw), signal);
 	}
-	listRaw(pageObjectNumber) {
-		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJsonWithRefresh(async (s) => this.versionedPagePath(await this.manifest.get(s), pageObjectNumber), (raw) => _embedpdf_engine_core_wire.AnnotationListPageSnapshotSchema.parse(raw), async (s) => {
+	/** One page's versioned leaf, with the standard stale-pin retry
+	*  (404 → refresh the manifest → once). */
+	readPage(page, signal) {
+		return this.http.getJsonWithRefresh(async (s) => this.versionedPagePath(await this.manifest.get(s), page.objectNumber), (raw) => _embedpdf_engine_core_wire.AnnotationListSchema.parse(raw), async (s) => {
 			await this.manifest.refresh(s);
-		}, signal));
-	}
-	/** Versioned leaf URL for one manifest page entry, with the same
-	*  plane routing as `CloudPageAnnotationsService.list()`: an inherited
-	*  `annotations` plane reads the doc-level base leaf. */
-	pagePathAt(manifest, page) {
-		return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotations(this.docId, page.state.pageObjectNumber, page.cache.annotationVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotations(this.docId, this.layerName, page.state.pageObjectNumber, page.cache.annotationVersion);
-	}
-	versionedPagePath(manifest, pageObjectNumber) {
-		const page = manifest.pages.find((p) => p.state.pageObjectNumber === pageObjectNumber);
-		if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
-		return this.pagePathAt(manifest, page);
+		}, signal);
 	}
-	beginWeakEdit(pageObjectNumbers) {
+	/**
+	* One versioned, CDN-cacheable read at the manifest's annotation and
+	* layout pins, with the stale-pin retry (404 → refresh the manifest →
+	* once). The response is the bundle without its bytes and one part per
+	* resource; every part is checked against its id before it is returned.
+	*/
+	export(selection = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const response = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerWeakAnnotationSession(this.docId, this.layerName), { pageObjectNumbers }, (raw) => _embedpdf_engine_core_wire.WeakAnnotationSessionResponseSchema.parse(raw), signal);
-			return new CloudWeakAnnotationEditSession(this.http, this.docId, this.layerName, () => this.isClosed(), response);
+			const read = async (s) => {
+				const manifest = await this.manifest.get(s);
+				const path = this.exportPathAt(manifest, selection);
+				if (path) return this.http.getFormData(path, s);
+				return this.http.postJsonFormData(_embedpdf_engine_core_wire.wirePaths.layerAnnotationsExportRequest(this.docId, this.layerName), {
+					annotationsVersion: manifest.annotationsVersion,
+					layoutVersion: manifest.layoutVersion,
+					selection
+				}, s);
+			};
+			let form;
+			try {
+				form = await read(signal);
+			} catch (error) {
+				if (!_embedpdf_engine_core_runtime.EngineError.is(error, _embedpdf_engine_core_runtime.EngineErrorCode.NotFound)) throw error;
+				await this.manifest.refresh(signal);
+				form = await read(signal);
+			}
+			const { body, resources } = await readBundleParts("annotation", form);
+			const bundle = {
+				...body,
+				resources
+			};
+			await (0, _embedpdf_engine_core_runtime.assertAnnotationBundle)(bundle, NO_BUNDLE_LIMITS);
+			return bundle;
 		});
 	}
-};
-var CloudWeakAnnotationEditSession = class {
-	constructor(http, docId, layerName, isClosed, response) {
-		this.http = http;
-		this.docId = docId;
-		this.layerName = layerName;
-		this.isClosed = isClosed;
-		_defineProperty(this, "response", void 0);
-		_defineProperty(this, "released", false);
-		this.response = response;
-	}
-	get id() {
-		return this.response.sessionId;
-	}
-	get expiresAt() {
-		return this.response.expiresAt;
-	}
-	get heartbeatIntervalMs() {
-		return this.response.heartbeatIntervalMs;
-	}
-	get pageObjectNumbers() {
-		return this.response.pageObjectNumbers;
-	}
-	covers(pageObjectNumber) {
-		return this.response.pageObjectNumbers.includes(pageObjectNumber);
-	}
-	updatePages(pageObjectNumbers) {
-		if (this.isClosed() || this.released) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `weak annotation session ${this.id} is closed`));
+	/**
+	* One request: the bundle's manifest and each resource once, as parts of
+	* one multipart POST under the import's `opId` as `Idempotency-Key`, so a
+	* retry applies once. The server holds the limits; the same numbers are checked
+	* here first, so a bundle past one fails before its bytes move.
+	*/
+	import(bundle, options = {}) {
+		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			this.response = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerWeakAnnotationSessionPages(this.docId, this.layerName, this.id), { pageObjectNumbers }, (raw) => _embedpdf_engine_core_wire.WeakAnnotationSessionResponseSchema.parse(raw), signal);
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const { resources, ...rest } = bundle;
+				(0, _embedpdf_engine_core_runtime.assertAnnotationBundleManifest)(bundle, new Map(Object.entries(resources).map(([id, bytes]) => [id, bytes.length])), await this.importLimits());
+				const form = bundleImportForm({
+					bundle: rest,
+					options: {
+						...options.pages !== void 0 ? { pages: options.pages } : {},
+						...options.attribution !== void 0 ? { attribution: options.attribution } : {}
+					}
+				}, resources);
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerAnnotationsImport(this.docId, this.layerName), form, (raw) => _embedpdf_engine_core_wire.AnnotationImportResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["annotations"]);
+				this.publisher.publishWrite(opId, ...(0, _embedpdf_engine_core_runtime.annotationImportFacts)(result).map((fact) => ({
+					type: "annotations.created",
+					...fact
+				})));
+				return result;
+			});
 		});
 	}
-	heartbeat() {
-		if (this.isClosed() || this.released) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `weak annotation session ${this.id} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			this.response = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerWeakAnnotationSessionHeartbeat(this.docId, this.layerName, this.id), {}, (raw) => _embedpdf_engine_core_wire.WeakAnnotationSessionResponseSchema.parse(raw), signal);
-		});
+	/**
+	* The cacheable export URL for `selection` at the manifest's pins — the
+	* base leaf while the layer inherits both planes the bundle depends on —
+	* or `null` when a URL can't carry it: a URL has room for a few hundred
+	* refs.
+	*/
+	exportPathAt(manifest, selection) {
+		const token = {
+			annotationsVersion: manifest.annotationsVersion,
+			layoutVersion: manifest.layoutVersion,
+			selection
+		};
+		try {
+			return planesInherited(manifest, ["annotations", "layout"]) ? _embedpdf_engine_core_wire.wirePaths.docAnnotationsExport(this.docId, token) : _embedpdf_engine_core_wire.wirePaths.layerAnnotationsExport(this.docId, this.layerName, token);
+		} catch {
+			return null;
+		}
+	}
+	/** Versioned leaf URL for one manifest page entry, with the same
+	*  plane routing as `CloudPageAnnotationsService.list()`: an inherited
+	*  `annotations` plane reads the doc-level base leaf. */
+	pagePathAt(manifest, page) {
+		const ref = page.page;
+		return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotations(this.docId, ref, page.cache.annotationVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotations(this.docId, this.layerName, ref, page.cache.annotationVersion);
 	}
-	release() {
-		if (this.released) return _embedpdf_engine_core_runtime.AbortablePromise.resolveValue(void 0);
-		this.released = true;
-		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.deleteEmpty(_embedpdf_engine_core_wire.wirePaths.layerWeakAnnotationSessionRelease(this.docId, this.layerName, this.id), signal));
+	versionedPagePath(manifest, pageObjectNumber) {
+		const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+		if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+		return this.pagePathAt(manifest, page);
 	}
 };
 //#endregion
 //#region src/document/buildMutationForm.ts
 /**
-* Multipart envelope for mutations that carry binaries: part `body` holds
-* the exact JSON the plain request would have been, plus one
-* `resource:{key}` file part per binary payload. Mirrors the appearance
-* response protocol (`manifest` part + named image parts) in reverse.
-* Shared by the annotation mutations (stamp images, attachment files) and
-* the document-level `attachments.create` — one envelope, one parser on
-* the server side.
+* The multipart envelope of a write that carries files, in the shape every
+* multipart message has: the `body` part holds the JSON the plain request
+* would have been, which names each file by role
+* (`resources: { <role>: <key> }`), and each file is the part
+* `resource:<key>`.
 */
 function buildMutationForm(body, resources) {
 	const form = new FormData();
@@ -208,21 +255,46 @@ function buildMutationForm(body, resources) {
 	for (const [key, resource] of Object.entries(resources)) form.append(`resource:${key}`, new Blob([resource.bytes], { type: resource.mimeType ?? "application/octet-stream" }), resource.name ?? key);
 	return form;
 }
-function hasResources(resources) {
-	return Object.keys(resources).length > 0;
+/**
+* The envelope of a write with at most one file per role (an annotation's
+* drawing or attached file, a page insert's source PDF, a signature's
+* mark): each file's key is its role's name, and the body names it so,
+* `resources: { <role>: '<role>' }`.
+*/
+function buildRoleMutationForm(body, files) {
+	const parts = {};
+	const resources = {};
+	for (const [role, file] of Object.entries(files)) {
+		if (!file) continue;
+		parts[role] = file;
+		resources[role] = role;
+	}
+	return buildMutationForm(Object.keys(resources).length > 0 ? {
+		...body,
+		resources
+	} : body, parts);
+}
+/** An annotation write's envelope: its drawing and attached file, by role. */
+function buildAnnotationMutationForm(body, resources) {
+	return buildRoleMutationForm(body, {
+		appearance: resources.appearance && { bytes: resources.appearance },
+		file: resources.file && { bytes: resources.file }
+	});
 }
 //#endregion
 //#region src/document/parseAttachmentContent.ts
 /** Header carrying the file's name, token-text encoded (names are
 *  arbitrary UTF-8; HTTP header values are not). */
 const FILE_NAME_HEADER = "X-EmbedPDF-File-Name";
+/** Header carrying the file's declared type; absent when it has none. */
+const FILE_TYPE_HEADER = "X-EmbedPDF-File-Type";
 /**
 * Project an attachment-file response into `AttachmentContent`. The body
-* IS the decoded bytes; the metadata rides as headers — `Content-Type`
-* for the declared mime type, `X-EmbedPDF-File-Name` for the file name.
-* Shared by the document-level `attachments.download()` and the
-* annotation-level `annotations.downloadFile()` reads — one wire shape
-* for both homes a file can live in.
+* is the decoded bytes; the metadata rides as headers — `X-EmbedPDF-File-Type`
+* for the declared type (`Content-Type` is only what HTTP needs), and
+* `X-EmbedPDF-File-Name` for the file name.
+* Used by the document-level `attachments.download()`; the annotation-level
+* `annotations.downloadResource(ref, 'file')` reads the same response's bytes.
 */
 function parseAttachmentContent(file) {
 	const encodedName = file.headers.get(FILE_NAME_HEADER);
@@ -233,17 +305,15 @@ function parseAttachmentContent(file) {
 	} catch (err) {
 		throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `malformed ${FILE_NAME_HEADER} header: ${err?.message ?? err}`, { cause: err });
 	}
-	const mimeType = file.headers.get("Content-Type");
 	return {
 		bytes: file.bytes,
 		name,
-		...mimeType !== null ? { mimeType } : {}
+		mimeType: file.headers.get(FILE_TYPE_HEADER)
 	};
 }
 //#endregion
 //#region src/document/CloudDocumentAttachmentsService.ts
 /** The `/attachments@…` listing leaf is a bare array of name-tree entries. */
-const EmbeddedFileListSchema = _embedpdf_engine_core_wire.EmbeddedFileItemSchema.array();
 /**
 * Cloud-side document-level attachments (the catalog's `/EmbeddedFiles`
 * name tree). Reads use immutable leaves pinned by the manifest's
@@ -254,13 +324,14 @@ const EmbeddedFileListSchema = _embedpdf_engine_core_wire.EmbeddedFileItemSchema
 * never cached.
 */
 var CloudDocumentAttachmentsService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
 	}
 	/**
 	* Snapshot of the name tree, in tree (key-sorted) order. Pulls
@@ -276,7 +347,7 @@ var CloudDocumentAttachmentsService = class {
 				const manifest = await this.manifest.get(s);
 				return planesInherited(manifest, ["attachments"]) ? _embedpdf_engine_core_wire.wirePaths.docAttachments(this.docId, manifest.attachmentsVersion) : _embedpdf_engine_core_wire.wirePaths.layerAttachments(this.docId, this.layerName, manifest.attachmentsVersion);
 			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => EmbeddedFileListSchema.parse(raw), async (s) => {
+			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.AttachmentListSchema.parse(raw), async (s) => {
 				await this.manifest.refresh(s);
 			}, signal);
 		});
@@ -300,195 +371,585 @@ var CloudDocumentAttachmentsService = class {
 		});
 	}
 	/**
-	* Create an embedded file in the name tree. Same splitter the
-	* file-attachment annotation draft uses — metadata into the `body`
-	* JSON part, bytes into the `resource:r0` file part — POSTed as the
-	* standard multipart mutation envelope.
+	* Create an embedded file in the name tree: metadata into the `body`
+	* part, naming its file `resources: { file: 'file' }`, and the bytes in
+	* the part `resource:file`.
 	*/
-	create(file) {
+	create(file, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const { wireFile, resource } = await (0, _embedpdf_engine_core_runtime.normalizeAttachmentFileSource)(file, "r0");
-			const result = await this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerAttachmentsCollection(this.docId, this.layerName), buildMutationForm(wireFile, { r0: resource }), (raw) => _embedpdf_engine_core_wire.AttachmentCreateResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyAttachments(result.cache);
-			this.publisher.publishLocal({
-				type: "attachment.created",
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const { wireFile, resource } = await (0, _embedpdf_engine_core_runtime.normalizeAttachmentFileSource)(file, "file");
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerAttachmentsCollection(this.docId, this.layerName), buildMutationForm(wireFile, { file: resource }), (raw) => _embedpdf_engine_core_wire.AttachmentCreateResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["attachments"]);
+				this.publisher.publishWrite(opId, {
+					type: "attachments.created",
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
 	/** Delete an embedded file from the name tree by its durable key. */
-	delete(ref) {
+	delete(ref, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerAttachmentItem(this.docId, this.layerName, ref.key), (raw) => _embedpdf_engine_core_wire.AttachmentDeleteResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyAttachments(result.cache);
-			this.publisher.publishLocal({
-				type: "attachment.deleted",
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerAttachmentItem(this.docId, this.layerName, ref.key), (raw) => _embedpdf_engine_core_wire.AttachmentDeleteResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["attachments"]);
+				this.publisher.publishWrite(opId, {
+					type: "attachments.deleted",
+					deleted: (0, _embedpdf_engine_core_runtime.deletedAttachmentOf)(result),
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
 };
 //#endregion
-//#region src/document/CloudDocumentFormsService.ts
-/** Content types the import POST body may carry; the server sniffs the
-*  actual format from the bytes, so this is advisory only. */
-const IMPORT_CONTENT_TYPE = {
-	fdf: "application/vnd.fdf",
-	xfdf: "application/vnd.adobe.xfdf"
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPrimitive.js
+function toPrimitive(t, r) {
+	if ("object" != _typeof(t) || !t) return t;
+	var e = t[Symbol.toPrimitive];
+	if (void 0 !== e) {
+		var i = e.call(t, r || "default");
+		if ("object" != _typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === r ? String : Number)(t);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = toPrimitive(t, "string");
+	return "symbol" == _typeof(i) ? i : i + "";
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.140.0/helpers/esm/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
+//#endregion
+//#region src/document/CloudDocumentChanges.ts
+/** How many `opId`s a handle remembers having published: far more than any retry spans. */
+const PUBLISHED_MEMORY = 4096;
+/**
+* `doc.apply` on the cloud: each change takes its place in the document's
+* line of writes, and goes out with the changes called right after it, as
+* one `POST …/changes` (see {@link CloudWrites.change}). The server checks
+* every op against the caller inside the write, so nothing about the ops is
+* checked here beyond what the request must hold.
+*
+* A change's events are published once its answer arrives, all sharing its
+* `opId`. A change asked again gets the first answer and publishes nothing:
+* this handle remembers the `opId`s it published.
+*/
+var CloudDocumentChanges = class {
+	constructor(isClosed, manifest, publisher, writes) {
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+		this.publisher = publisher;
+		this.writes = writes;
+		_defineProperty(this, "published", /* @__PURE__ */ new Set());
+	}
+	apply(change, options) {
+		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, "document is closed"));
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
+		}
+		if (!(0, _embedpdf_engine_core_runtime.isUndoChange)(change) && change.ops.length === 0) return _embedpdf_engine_core_runtime.AbortablePromise.resolveValue({
+			items: [],
+			meta: {
+				affectedPages: [],
+				cacheDelta: null,
+				opId,
+				undoable: false
+			}
+		});
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const answer = await this.writes.change(signal, sentChangeOf(opId, change), {
+				named: (0, _embedpdf_engine_core_runtime.objectNumbersNamedBy)(change),
+				alone: carriesBytes(change)
+			});
+			if (answer.status === "refused") throw (0, _embedpdf_engine_core_runtime.deserializeError)(answer.error);
+			this.absorb(opId, change, answer.result);
+			return answer.result;
+		});
+	}
+	/**
+	* Patch the cached manifest, then publish the change's events (in that
+	* order: listeners reading the manifest see the change), unless this
+	* handle published them already.
+	*/
+	absorb(opId, change, result) {
+		this.manifest.apply(result.meta, planesOf(result));
+		if (this.published.has(opId)) return;
+		this.published.add(opId);
+		if (this.published.size > PUBLISHED_MEMORY) this.published.delete(this.published.values().next().value);
+		const undoOf = (0, _embedpdf_engine_core_runtime.isUndoChange)(change) ? change.undoOf : void 0;
+		this.publisher.publishChange(opId, (0, _embedpdf_engine_core_runtime.changeEvents)(result), undoOf);
+	}
 };
 /**
+* The sender of a document's requests of changes: JSON, or multipart when
+* any change carries bytes, each op naming its parts by key.
+*/
+function changeSender(http, docId, layerName) {
+	const path = _embedpdf_engine_core_wire.wirePaths.layerChanges(docId, layerName);
+	const parse = (raw) => _embedpdf_engine_core_wire.ChangeResponseSchema.parse(raw).changes;
+	return (changes, options) => {
+		const { body, parts } = changeRequestOf(changes);
+		const signal = new AbortController().signal;
+		return Object.keys(parts).length > 0 ? http.postMultipartJson(path, buildMutationForm(body, parts), parse, signal, options) : http.postJson(path, body, parse, signal, options);
+	};
+}
+/**
+* A change ready to send: its bytes read, and checked against what a request
+* may hold, so a malformed change is refused alone rather than refusing the
+* request it would share.
+*/
+async function sentChangeOf(opId, change) {
+	if (!(0, _embedpdf_engine_core_runtime.isUndoChange)(change) && change.ops.length > _embedpdf_engine_core_wire.CHANGE_REQUEST_LIMITS.ops) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.PayloadTooLarge, `a change holds at most ${_embedpdf_engine_core_wire.CHANGE_REQUEST_LIMITS.ops} ops`, { details: {
+		limit: "ops",
+		max: _embedpdf_engine_core_wire.CHANGE_REQUEST_LIMITS.ops,
+		value: change.ops.length
+	} });
+	const sent = {
+		opId,
+		change: (await (0, _embedpdf_engine_core_runtime.resolveChangeResources)(change)).change
+	};
+	const { body } = changeRequestOf([sent]);
+	const checked = _embedpdf_engine_core_wire.ChangeRequestSchema.safeParse(JSON.parse(JSON.stringify(body)));
+	if (!checked.success) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `invalid change: ${checked.error.message}`, { details: { issues: checked.error.issues } });
+	return sent;
+}
+/** A request's JSON and its parts: each op's bytes become a part the op names by key. */
+function changeRequestOf(changes) {
+	const parts = {};
+	const part = (bytes) => {
+		const key = `r${Object.keys(parts).length}`;
+		parts[key] = { bytes };
+		return key;
+	};
+	const opOf = (op) => {
+		switch (op.type) {
+			case "annotations.create":
+			case "annotations.update": {
+				if (!op.resources) return op;
+				const { appearance, file } = op.resources;
+				return {
+					...op,
+					resources: {
+						...appearance ? { appearance: part(appearance) } : {},
+						...file ? { file: part(file) } : {}
+					}
+				};
+			}
+			case "forms.setSignatureAppearance": {
+				const { appearance, ...rest } = op;
+				return {
+					...rest,
+					resources: { appearance: part(appearance.pdf.slice().buffer) }
+				};
+			}
+			default: return op;
+		}
+	};
+	return {
+		body: { changes: changes.map(({ opId, change }) => (0, _embedpdf_engine_core_runtime.isUndoChange)(change) ? {
+			opId,
+			undoOf: change.undoOf
+		} : {
+			opId,
+			ops: change.ops.map(opOf)
+		}) },
+		parts
+	};
+}
+/** Whether a change carries bytes: a drawing, an attached file, a signature's artwork. */
+function carriesBytes(change) {
+	if ((0, _embedpdf_engine_core_runtime.isUndoChange)(change)) return false;
+	return change.ops.some((op) => op.type === "forms.setSignatureAppearance" || (op.type === "annotations.create" || op.type === "annotations.update") && op.resources !== void 0 && Object.values(op.resources).some((resource) => resource !== void 0));
+}
+/** The planes a change's writes took over from the base, each op by its family. */
+function planesOf(result) {
+	const planes = /* @__PURE__ */ new Set();
+	for (const item of result.items) {
+		if ((0, _embedpdf_engine_core_runtime.isSkippedItem)(item)) continue;
+		if (item.type.startsWith("metadata.")) planes.add("metadata");
+		else if (item.type.startsWith("forms.")) planes.add("forms");
+		else planes.add("annotations");
+	}
+	return [...planes];
+}
+//#endregion
+//#region src/shared/withObjectNumbers.ts
+/**
+* `path` with the object numbers a create names, in its query string: one
+* (`objectNumber=42`) or a comma list (`objectNumbers=42,43`). The body
+* stays the data. Names whose value is absent are left out.
+*/
+function withObjectNumbers(path, numbers) {
+	const query = Object.entries(numbers).filter(([, value]) => value !== void 0 && (!Array.isArray(value) || value.length > 0)).map(([name, value]) => `${name}=${Array.isArray(value) ? value.join(",") : String(value)}`);
+	if (query.length === 0) return path;
+	return `${path}${path.includes("?") ? "&" : "?"}${query.join("&")}`;
+}
+//#endregion
+//#region src/document/CloudDocumentFormsService.ts
+/**
 * Cloud-side document forms service. Mirrors the local wiring: each call
 * produces an `AbortablePromise` that propagates `signal.abort()` down to
 * `fetch` and validates the JSON response with the wire-stable Zod schema.
 *
-* Forms are document-scoped, so reads use the unversioned `/form` URLs
-* (always `no-store` — there is no content-addressed variant). Mutation
-* results carry the per-page `cacheDelta` for pages whose widget
-* appearances changed; `absorbMutation` folds it into the cached manifest
-* so annotation/render reads stay coherent.
+* The form is its own read family: `list()` reads the immutable `form@`
+* leaf at the manifest's `formsVersion`. Mutation results carry the
+* `cacheDelta` of the form's pins (`formsVersion`, and each changed widget
+* page's `widgetVersion`); `absorbMutation` folds it into the cached
+* manifest and owns the `forms` plane.
 */
 var CloudDocumentFormsService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes, importLimits) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
+		this.importLimits = importLimits;
 	}
+	/**
+	* The form: one read of the immutable `form@formsVersion=N` leaf at the
+	* manifest's pin, at the base's URL while the layer inherits the `forms`
+	* plane, CDN-cacheable because the pin moves only when the form does. A
+	* stale pin (a write landed → 404) refreshes the manifest and reads again,
+	* once.
+	*/
 	list() {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
-		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJson(_embedpdf_engine_core_wire.wirePaths.layerForm(this.docId, this.layerName), (raw) => _embedpdf_engine_core_wire.FormSnapshotSchema.parse(raw), signal));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJsonWithRefresh(async (s) => {
+			const manifest = await this.manifest.get(s);
+			return planesInherited(manifest, ["forms"]) ? _embedpdf_engine_core_wire.wirePaths.docForm(this.docId, manifest.formsVersion) : _embedpdf_engine_core_wire.wirePaths.layerForm(this.docId, this.layerName, manifest.formsVersion);
+		}, (raw) => _embedpdf_engine_core_wire.FormSnapshotSchema.parse(raw), async (s) => {
+			await this.manifest.refresh(s);
+		}, signal));
 	}
 	get(ref) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldByKey(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), (raw) => _embedpdf_engine_core_wire.FormFieldDTOSchema.parse(raw), signal));
 	}
-	setValue(ref, value) {
+	setValue(ref, value, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldValue(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), { value }, (raw) => _embedpdf_engine_core_wire.FormSetValueResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.valueChanged");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldValue(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), { value }, (raw) => _embedpdf_engine_core_wire.FormSetValueResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.valueSet");
+			});
 		});
 	}
-	reset(ref) {
+	reset(fields, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
+		const refs = fields === void 0 ? void 0 : Array.isArray(fields) ? fields : [fields];
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldReset(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), {}, (raw) => _embedpdf_engine_core_wire.FormSetValueResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.valueChanged");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormReset(this.docId, this.layerName), refs ? { refs } : {}, (raw) => _embedpdf_engine_core_wire.FormResetResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["forms"]);
+				this.publisher.publishWrite(opId, ...(0, _embedpdf_engine_core_runtime.formResetFacts)(result).map((fact) => ({
+					type: "forms.valueSet",
+					...fact
+				})));
+				return result;
+			});
 		});
 	}
-	applyEffects(effects) {
+	/**
+	* One versioned, CDN-cacheable read at the manifest's form and layout
+	* pins, with the stale-pin retry (404 → refresh the manifest → once). The
+	* response is the bundle without its bytes and one part per resource;
+	* every part is checked against its id before it is returned.
+	*/
+	export(selection = {}) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormEffects(this.docId, this.layerName), { effects }, (raw) => _embedpdf_engine_core_wire.FormEffectsResultSchema.parse(raw), signal);
-			if (result.meta === null) return result;
-			this.manifest.apply(result.meta, ["annotations"]);
-			this.publisher.publishLocal({
-				type: "form.effectsApplied",
-				...result
+			const read = async (s) => {
+				const manifest = await this.manifest.get(s);
+				const path = this.exportPathAt(manifest, selection);
+				if (path) return this.http.getFormData(path, s);
+				return this.http.postJsonFormData(_embedpdf_engine_core_wire.wirePaths.layerFormExportRequest(this.docId, this.layerName), {
+					formsVersion: manifest.formsVersion,
+					layoutVersion: manifest.layoutVersion,
+					selection
+				}, s);
+			};
+			let form;
+			try {
+				form = await read(signal);
+			} catch (error) {
+				if (!_embedpdf_engine_core_runtime.EngineError.is(error, _embedpdf_engine_core_runtime.EngineErrorCode.NotFound)) throw error;
+				await this.manifest.refresh(signal);
+				form = await read(signal);
+			}
+			const { body, resources } = await readBundleParts("form", form);
+			const bundle = {
+				...body,
+				resources
+			};
+			await (0, _embedpdf_engine_core_runtime.assertFormBundle)(bundle, NO_BUNDLE_LIMITS);
+			return bundle;
+		});
+	}
+	/**
+	* One request: the bundle's manifest and each resource once, as parts of
+	* one multipart POST under the import's `opId` as `Idempotency-Key`, so a
+	* retry applies once. The server holds the limits; the same numbers are
+	* checked here first, so a bundle past one fails before its bytes move.
+	*/
+	import(bundle, options = {}) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const body = {
+					bundle: await this.checkedManifest(bundle),
+					options: {
+						...options.pages !== void 0 ? { pages: options.pages } : {},
+						...options.attribution !== void 0 ? { attribution: options.attribution } : {},
+						...options.values !== void 0 ? { values: options.values } : {}
+					}
+				};
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerFormImport(this.docId, this.layerName), bundleImportForm(body, bundle.resources), (raw) => _embedpdf_engine_core_wire.FormImportResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["forms"]);
+				this.publisher.publishWrite(opId, ...(0, _embedpdf_engine_core_runtime.formImportFacts)(result).map((fact) => ({
+					type: "forms.created",
+					...fact
+				})));
+				return result;
 			});
-			return result;
 		});
 	}
-	exportData(format = "xfdf") {
+	/** One request, as {@link import} sends it. */
+	importValues(bundle, options = {}) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			return {
-				format,
-				bytes: await this.http.getBytes(_embedpdf_engine_core_wire.wirePaths.layerFormData(this.docId, this.layerName, format), signal)
-			};
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const body = {
+					bundle: await this.checkedManifest(bundle),
+					options: options.attribution !== void 0 ? { attribution: options.attribution } : {}
+				};
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerFormImportValues(this.docId, this.layerName), bundleImportForm(body, bundle.resources), (raw) => _embedpdf_engine_core_wire.FormValuesImportResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["forms"]);
+				this.publisher.publishWrite(opId, ...(0, _embedpdf_engine_core_runtime.formValuesImportFacts)(result).map((fact) => ({
+					type: "forms.valueSet",
+					...fact
+				})));
+				return result;
+			});
 		});
 	}
-	importData(data, format) {
+	create(draft, options = {}) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
-		const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postBytesJson(_embedpdf_engine_core_wire.wirePaths.layerFormData(this.docId, this.layerName, format), bytes, format ? IMPORT_CONTENT_TYPE[format] : "application/octet-stream", (raw) => _embedpdf_engine_core_wire.FormImportResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.imported");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			const { objectNumber, widgetObjectNumbers } = options;
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(withObjectNumbers(_embedpdf_engine_core_wire.wirePaths.layerFormFields(this.docId, this.layerName), {
+					objectNumber,
+					widgetObjectNumbers
+				}), draft, (raw) => _embedpdf_engine_core_wire.FormFieldCreateResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.created");
+			}, [objectNumber, ...widgetObjectNumbers ?? []]);
 		});
 	}
-	createField(draft) {
+	update(ref, patch, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFields(this.docId, this.layerName), draft, (raw) => _embedpdf_engine_core_wire.FormFieldCreateResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.fieldCreated");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.patchJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldByKey(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), patch, (raw) => _embedpdf_engine_core_wire.FormFieldUpdateResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.updated");
+			});
 		});
 	}
-	updateField(ref, patch) {
+	setSignatureAppearance(ref, appearance, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.patchJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldByKey(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), patch, (raw) => _embedpdf_engine_core_wire.FormFieldUpdateResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.fieldUpdated");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const bytes = new ArrayBuffer(appearance.pdf.byteLength);
+				new Uint8Array(bytes).set(appearance.pdf);
+				const form = buildRoleMutationForm({}, { appearance: {
+					bytes,
+					mimeType: "application/pdf",
+					name: "appearance.pdf"
+				} });
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldSignatureAppearance(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), form, (raw) => _embedpdf_engine_core_wire.FormFieldUpdateResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.updated");
+			});
 		});
 	}
-	setSignatureAppearance(ref, appearance) {
+	delete(ref, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const bytes = new ArrayBuffer(appearance.pdf.byteLength);
-			new Uint8Array(bytes).set(appearance.pdf);
-			const form = buildMutationForm({
-				resource: "r0",
-				pageIndex: appearance.pageIndex ?? 0
-			}, { r0: {
-				bytes,
-				mimeType: "application/pdf",
-				name: "appearance.pdf"
-			} });
-			const result = await this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldSignatureAppearance(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), form, (raw) => _embedpdf_engine_core_wire.FormFieldUpdateResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.fieldUpdated");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldByKey(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), (raw) => _embedpdf_engine_core_wire.FormFieldDeleteResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["forms"]);
+				this.publisher.publishWrite(opId, {
+					type: "forms.deleted",
+					deleted: (0, _embedpdf_engine_core_runtime.deletedFieldOf)(result),
+					...result
+				});
+				return result;
+			});
 		});
 	}
-	deleteField(ref) {
+	addWidget(ref, placement, options = {}) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldByKey(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), (raw) => _embedpdf_engine_core_wire.FormFieldDeleteResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.fieldDeleted");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			const { objectNumber, splitObjectNumber } = options;
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(withObjectNumbers(_embedpdf_engine_core_wire.wirePaths.layerFormFieldWidgets(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), {
+					objectNumber,
+					splitObjectNumber
+				}), placement, (raw) => _embedpdf_engine_core_wire.FormWidgetLinkResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.widgetAdded");
+			}, [objectNumber, splitObjectNumber]);
 		});
 	}
-	attachWidget(ref, widget, options) {
+	removeWidget(ref, widget, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
-		const onState = options?.onState;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldWidgets(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), {
-				widget,
-				...onState ? { onState } : {}
-			}, (raw) => _embedpdf_engine_core_wire.FormWidgetLinkResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.widgetAttached");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldWidgetsDetach(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), { widget }, (raw) => _embedpdf_engine_core_wire.FormWidgetLinkResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.widgetRemoved");
+			});
 		});
 	}
-	detachWidget(ref, widget) {
+	updateWidget(widget, patch, options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormFieldWidgetsDetach(this.docId, this.layerName, (0, _embedpdf_engine_core_runtime.encodeFieldRefKey)(ref)), { widget }, (raw) => _embedpdf_engine_core_wire.FormWidgetLinkResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.widgetDetached");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.patchJson(_embedpdf_engine_core_wire.wirePaths.layerFormWidget(this.docId, this.layerName, widget.page, (0, _embedpdf_engine_core_runtime.encodeAnnotKey)(widget)), { patch }, (raw) => _embedpdf_engine_core_wire.FormWidgetUpdateResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.widgetUpdated");
+			});
+		});
+	}
+	deleteWidget(widget, options) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerFormWidget(this.docId, this.layerName, widget.page, (0, _embedpdf_engine_core_runtime.encodeAnnotKey)(widget)), (raw) => _embedpdf_engine_core_wire.FormWidgetDeleteResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.widgetDeleted");
+			});
+		});
+	}
+	reorderCalculations(fields, position, options) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormCalculationsReorder(this.docId, this.layerName), {
+					fields,
+					position
+				}, (raw) => _embedpdf_engine_core_wire.FormCalculationsReorderResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.calculationsReordered");
+			});
+		});
+	}
+	reorderWidgets(widgets, position, options) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		const page = widgets[0]?.page;
+		if (!page) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "a reorder names at least one widget", { details: { field: "widgets" } }));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormWidgetsReorder(this.docId, this.layerName, page), {
+					widgets,
+					position
+				}, (raw) => _embedpdf_engine_core_wire.FormWidgetsReorderResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.widgetsReordered");
+			});
 		});
 	}
 	repair(options) {
 		const rejected = this.rejectIfClosed();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormRepair(this.docId, this.layerName), { bakeAppearances: options?.bakeAppearances ?? false }, (raw) => _embedpdf_engine_core_wire.FormRepairResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "form.repaired");
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerFormRepair(this.docId, this.layerName), { bakeAppearances: options?.bakeAppearances ?? false }, (raw) => _embedpdf_engine_core_wire.FormRepairResultSchema.parse(raw), signal, sent));
+				return this.absorbMutation(opId, result, "forms.repaired");
+			});
 		});
 	}
+	/** The bundle without its bytes, checked against the server's limits first. */
+	async checkedManifest(bundle) {
+		const { resources, ...manifest } = bundle;
+		(0, _embedpdf_engine_core_runtime.assertFormBundleManifest)(bundle, new Map(Object.entries(resources).map(([id, bytes]) => [id, bytes.length])), await this.importLimits());
+		return manifest;
+	}
+	/**
+	* The cacheable export URL for `selection` at the manifest's pins — the
+	* base leaf while the layer inherits both planes the bundle depends on —
+	* or `null` when a URL can't carry it.
+	*/
+	exportPathAt(manifest, selection) {
+		const token = {
+			formsVersion: manifest.formsVersion,
+			layoutVersion: manifest.layoutVersion,
+			selection
+		};
+		try {
+			return planesInherited(manifest, ["forms", "layout"]) ? _embedpdf_engine_core_wire.wirePaths.docFormExport(this.docId, token) : _embedpdf_engine_core_wire.wirePaths.layerFormExport(this.docId, this.layerName, token);
+		} catch {
+			return null;
+		}
+	}
 	rejectIfClosed() {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return null;
@@ -498,9 +959,9 @@ var CloudDocumentFormsService = class {
 	* event stream (in that order — listeners reading the manifest in their
 	* callback must see post-mutation state). Same rails as annotations.
 	*/
-	absorbMutation(result, type) {
-		this.manifest.apply(result.meta, ["annotations"]);
-		this.publisher.publishLocal({
+	absorbMutation(opId, result, type) {
+		this.manifest.apply(result.meta, ["forms"]);
+		this.publisher.publishWrite(opId, {
 			type,
 			...result
 		});
@@ -508,6 +969,28 @@ var CloudDocumentFormsService = class {
 	}
 };
 //#endregion
+//#region src/shared/awaitSignal.ts
+/**
+* Wait for a shared promise under one caller's signal: an abort rejects
+* this caller only and leaves the shared work running for the others.
+*/
+function awaitSignal(promise, signal) {
+	if (signal.aborted) return Promise.reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (reason) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(reason);
+		});
+	});
+}
+//#endregion
 //#region src/document/CloudDocumentPagesService.ts
 /** Detach a Uint8Array view into a standalone ArrayBuffer (the resource-map
 *  shape) without disturbing a larger buffer the caller still owns. */
@@ -518,26 +1001,28 @@ function copyToExactBuffer(view) {
 }
 /**
 * Cloud-side document pages service. Mirrors `LocalDocumentPagesService`
-* over HTTP: GET /pages for `list`, POST /pages/move for the reorder.
+* over HTTP: GET /pages for `list`, POST /pages/reorder for the reorder.
 *
 * Page identity rule (locked with the user, do not change):
-*   - Pages are addressed exclusively by their indirect
-*     `pageObjectNumber`. The wire never sends a page index for a
-*     mutation. This keeps multi-call client logic from having to
-*     account for index drift between requests.
-*   - Successful `move()` returns the new `layout` (order + geometry) plus
-*     cloud coherence pins. The server does NOT bump per-page revisions on a
-*     page move (page reorder is intentionally outside the weak-ref staleness
-*     model), only `docVersion` + `layoutVersion`.
+*   - Pages are addressed exclusively by `PageRef` (their indirect
+*     `pageObjectNumber`); mutation bodies ship `{ pages: PageRef[] }`.
+*     The wire never sends a page index for a mutation. This keeps
+*     multi-call client logic from having to account for index drift
+*     between requests.
+*   - Successful `reorder()` returns the new `layout` (order + geometry) plus
+*     cloud coherence pins. A page reorder bumps only `docVersion` +
+*     `layoutVersion`; every per-page pin stays warm.
 */
 var CloudDocumentPagesService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
+		_defineProperty(this, "layoutMemo", null);
 	}
 	/**
 	* Page-geometry list. The geometry bytes live at the content-addressed
@@ -551,142 +1036,195 @@ var CloudDocumentPagesService = class {
 	*/
 	list() {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const buildPath = async (s) => {
-				const manifest = await this.manifest.get(s);
-				return planesInherited(manifest, ["layout"]) ? _embedpdf_engine_core_wire.wirePaths.docLayout(this.docId, manifest.layoutVersion) : _embedpdf_engine_core_wire.wirePaths.layerLayout(this.docId, this.layerName, manifest.layoutVersion);
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.fetchLayout(signal));
+	}
+	/**
+	* One page's layout, for renders to size their image without a round
+	* trip per tile. The layout leaf never changes at a given URL, so the
+	* last one read is kept and shared until the manifest points elsewhere.
+	*/
+	async pageLayout(ref, signal) {
+		const path = await this.layoutPath(signal);
+		let memo = this.layoutMemo;
+		if (memo?.path !== path) {
+			const snapshot = this.fetchLayout(new AbortController().signal);
+			const next = {
+				path,
+				snapshot
 			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.PageListSnapshotSchema.parse(raw), async (s) => {
-				await this.manifest.refresh(s);
-			}, signal);
-		});
+			snapshot.catch(() => {
+				if (this.layoutMemo === next) this.layoutMemo = null;
+			});
+			this.layoutMemo = memo = next;
+		}
+		const page = (await awaitSignal(memo.snapshot, signal)).pages.find((p) => (0, _embedpdf_engine_core_runtime.pageRefsEqual)(p.ref, ref));
+		if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${ref.objectNumber} in document ${this.docId}`);
+		return page;
+	}
+	/**
+	* Plane-scope rule: the layout leaf depends on the `layout` plane —
+	* while inherited (no reorder/rotate/insert/delete ever ran), every
+	* visitor's page list is one doc-level URL served from the base
+	* session; the SDK open sequence creates no layer session.
+	*/
+	async layoutPath(signal) {
+		const manifest = await this.manifest.get(signal);
+		return planesInherited(manifest, ["layout"]) ? _embedpdf_engine_core_wire.wirePaths.docLayout(this.docId, manifest.layoutVersion) : _embedpdf_engine_core_wire.wirePaths.layerLayout(this.docId, this.layerName, manifest.layoutVersion);
 	}
-	move(pageObjectNumbers, destIndex) {
+	fetchLayout(signal) {
+		return this.http.getJsonWithRefresh((s) => this.layoutPath(s), (raw) => _embedpdf_engine_core_wire.PageListSnapshotSchema.parse(raw), async (s) => {
+			await this.manifest.refresh(s);
+		}, signal);
+	}
+	reorder(pages, position, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesMove(this.docId, this.layerName), {
-				pageObjectNumbers,
-				destIndex
-			}, (raw) => _embedpdf_engine_core_wire.PageMoveResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageStructure(result.cache);
-			this.publisher.publishLocal({
-				type: "pages.moved",
-				pageObjectNumbers,
-				destIndex,
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesReorder(this.docId, this.layerName), {
+					pages,
+					position
+				}, (raw) => _embedpdf_engine_core_wire.PageReorderResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["layout"]);
+				this.publisher.publishWrite(opId, {
+					type: "pages.reordered",
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
-	setName(input) {
-		return this.runNameMutation(_embedpdf_engine_core_wire.wirePaths.layerPagesNames(this.docId, this.layerName), input, input.name, input.pageObjectNumber);
+	setName(input, options) {
+		return this.runNameMutation(_embedpdf_engine_core_wire.wirePaths.layerPagesNames(this.docId, this.layerName), input, input.name, input.page, options);
 	}
-	removeName(input) {
-		return this.runNameMutation(_embedpdf_engine_core_wire.wirePaths.layerPagesNamesDelete(this.docId, this.layerName), input, input.name, null);
+	removeName(input, options) {
+		return this.runNameMutation(_embedpdf_engine_core_wire.wirePaths.layerPagesNamesDelete(this.docId, this.layerName), input, input.name, null, options);
 	}
 	/**
-	* Named pages are LAYOUT: both verbs share the page-move patch exactly —
+	* Named pages are layout: both verbs share the page-reorder patch exactly —
 	* docVersion + layoutVersion advance, no per-page pin changes, so the
 	* cached manifest is patched in place and the fresh layout is published.
 	*/
-	runNameMutation(path, body, name, pageObjectNumber) {
+	runNameMutation(path, body, name, page, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(path, body, (raw) => _embedpdf_engine_core_wire.PageNameResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageStructure(result.cache);
-			this.publisher.publishLocal({
-				type: "pages.named",
-				name,
-				pageObjectNumber,
-				...result
-			});
-			return result;
-		});
-	}
-	rotate(pageObjectNumbers, rotation) {
-		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesRotate(this.docId, this.layerName), {
-				pageObjectNumbers,
-				rotation
-			}, (raw) => _embedpdf_engine_core_wire.PageRotateResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageStructure(result.cache);
-			this.publisher.publishLocal({
-				type: "pages.rotated",
-				pageObjectNumbers,
-				rotation,
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(path, body, (raw) => _embedpdf_engine_core_wire.PageNameResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["layout"]);
+				this.publisher.publishWrite(opId, {
+					type: "pages.named",
+					name,
+					page,
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
-	delete(pageObjectNumbers) {
+	rotate(pages, rotation, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesDelete(this.docId, this.layerName), { pageObjectNumbers }, (raw) => _embedpdf_engine_core_wire.PageDeleteResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageDelete(result.cache, pageObjectNumbers);
-			this.publisher.publishLocal({
-				type: "pages.deleted",
-				pageObjectNumbers,
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesRotate(this.docId, this.layerName), {
+					pages,
+					rotation
+				}, (raw) => _embedpdf_engine_core_wire.PageRotateResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, ["layout"]);
+				this.publisher.publishWrite(opId, {
+					type: "pages.rotated",
+					pages,
+					rotation,
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
-	insert(bytes, destIndex) {
+	delete(pages, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const buffer = bytes instanceof ArrayBuffer ? bytes : copyToExactBuffer(bytes);
-			const form = buildMutationForm(destIndex !== void 0 ? { destIndex } : {}, { source: {
-				bytes: buffer,
-				mimeType: "application/pdf",
-				name: "source.pdf"
-			} });
-			const result = await this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerPagesInsert(this.docId, this.layerName), form, (raw) => _embedpdf_engine_core_wire.PageInsertResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageInsert(result.cache);
-			this.publisher.publishLocal({
-				type: "pages.inserted",
-				destIndex,
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesDelete(this.docId, this.layerName), { pages }, (raw) => _embedpdf_engine_core_wire.PageDeleteResultSchema.parse(raw), signal, sent));
+				this.manifest.applyPageDelete(result.meta, pages);
+				this.publisher.publishWrite(opId, {
+					type: "pages.deleted",
+					pages,
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
-	insertBlank(spec, destIndex) {
+	insert(bytes, position = "end", options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesInsertBlank(this.docId, this.layerName), {
-				size: spec.size,
-				...spec.count !== void 0 ? { count: spec.count } : {},
-				...destIndex !== void 0 ? { destIndex } : {}
-			}, (raw) => _embedpdf_engine_core_wire.PageInsertResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyPageInsert(result.cache);
-			this.publisher.publishLocal({
-				type: "pages.inserted",
-				destIndex,
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const buffer = bytes instanceof ArrayBuffer ? bytes : copyToExactBuffer(bytes);
+				const form = buildRoleMutationForm({ position }, { source: {
+					bytes: buffer,
+					mimeType: "application/pdf",
+					name: "source.pdf"
+				} });
+				const result = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerPagesInsert(this.docId, this.layerName), form, (raw) => _embedpdf_engine_core_wire.PageInsertResultSchema.parse(raw), signal, sent));
+				this.manifest.applyPageInsert(result.meta);
+				this.publisher.publishWrite(opId, {
+					type: "pages.inserted",
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
-	extract(pageObjectNumbers) {
+	insertBlank(spec, position = "end", options = {}) {
+		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			const { objectNumbers } = options;
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(withObjectNumbers(_embedpdf_engine_core_wire.wirePaths.layerPagesInsertBlank(this.docId, this.layerName), { objectNumbers }), {
+					size: spec.size,
+					...spec.count !== void 0 ? { count: spec.count } : {},
+					position
+				}, (raw) => _embedpdf_engine_core_wire.PageInsertResultSchema.parse(raw), signal, sent));
+				this.manifest.applyPageInsert(result.meta);
+				this.publisher.publishWrite(opId, {
+					type: "pages.inserted",
+					...result
+				});
+				return result;
+			}, objectNumbers ?? []);
+		});
+	}
+	extract(pages) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => this.http.postJsonBytes(_embedpdf_engine_core_wire.wirePaths.layerPagesExtract(this.docId, this.layerName), { pageObjectNumbers }, signal));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => this.http.postJsonBytes(_embedpdf_engine_core_wire.wirePaths.layerPagesExtract(this.docId, this.layerName), { pages }, signal));
 	}
-	flatten(pageObjectNumbers, usage = "display") {
+	flatten(pages, options) {
+		const usage = options?.usage ?? "display";
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesFlatten(this.docId, this.layerName), {
-				pageObjectNumbers,
-				usage
-			}, (raw) => _embedpdf_engine_core_wire.PageFlattenResultSchema.parse(raw), signal);
-			if (result.meta === null) return result;
-			this.manifest.apply(result.meta, ["content", "annotations"]);
-			this.publisher.publishLocal({
-				type: "pages.flattened",
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerPagesFlatten(this.docId, this.layerName), {
+					pages,
+					usage
+				}, (raw) => _embedpdf_engine_core_wire.PageFlattenResultSchema.parse(raw), signal, sent));
+				if (result.meta.cacheDelta === null) return result;
+				this.manifest.apply(result.meta, [
+					"content",
+					"annotations",
+					"forms"
+				]);
+				this.publisher.publishWrite(opId, {
+					type: "pages.flattened",
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
 };
@@ -697,29 +1235,37 @@ var CloudDocumentPagesService = class {
 * HTTP (POST /redactions/apply); the server enforces the capability gate
 * (`doc.pages.modify` + `doc.annotate.modify` + `doc.redact`) and persists
 * the rewritten layer artifact. See `DocumentRedactionService` for the
-* two-stage model and the layer trust boundary — an apply rewrites THIS
-* LAYER's bytes; the immutable base keeps the original.
+* two-stage model and the layer trust boundary — an apply rewrites this
+* layer's bytes; the immutable base keeps the original.
 */
 var CloudDocumentRedactionService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
 	}
-	apply(scope) {
+	apply(scope, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerRedactionsApply(this.docId, this.layerName), { scope }, (raw) => _embedpdf_engine_core_wire.RedactionApplyResultSchema.parse(raw), signal);
-			if (result.meta === null) return result;
-			this.manifest.apply(result.meta, ["content", "annotations"]);
-			this.publisher.publishLocal({
-				type: "redaction.applied",
-				...result
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerRedactionsApply(this.docId, this.layerName), scope, (raw) => _embedpdf_engine_core_wire.RedactionApplyResultSchema.parse(raw), signal, sent));
+				if (result.meta.cacheDelta === null) return result;
+				this.manifest.apply(result.meta, [
+					"content",
+					"annotations",
+					"forms"
+				]);
+				this.publisher.publishWrite(opId, {
+					type: "redaction.applied",
+					...result
+				});
+				return result;
 			});
-			return result;
 		});
 	}
 };
@@ -730,14 +1276,14 @@ var CloudDocumentRedactionService = class {
 *
 * Every slice URL is a canonical cache key — the search token pins the
 * layer's content epoch (computed from the cached manifest), the
-* CANONICAL query (default-fold literals collapse case/diacritic
+* canonical query (default-fold literals collapse case/diacritic
 * variants into one entry), and the resume position. Identical searches
 * from any reader of the document hit the same CDN entry; matches are
 * all that ever crosses the trust boundary, and the rects/full endpoint
 * split keeps permission tiers in disjoint cache namespaces.
 *
 * Staleness rides the standard versioned-read signal: a first slice
-* answered `NotFound` means OUR manifest is stale → refresh and retry
+* answered `NotFound` means our manifest is stale → refresh and retry
 * once; a continuation answered `NotFound` means the document changed
 * mid-search → `InvalidArg`, same contract as the local engine's cursor.
 */
@@ -752,9 +1298,10 @@ var CloudDocumentSearchService = class {
 	query(request) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document not open: ${this.docId}`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const path = (request.mode ?? "full") === "rects" ? _embedpdf_engine_core_wire.wirePaths.layerSearchRects : _embedpdf_engine_core_wire.wirePaths.layerSearchFull;
+			const path = request.snippets ? _embedpdf_engine_core_wire.wirePaths.layerSearchFull : _embedpdf_engine_core_wire.wirePaths.layerSearchRects;
 			const get = (token) => this.http.getJson(path(this.docId, this.layerName, token), (raw) => _embedpdf_engine_core_wire.SearchSliceSchema.parse(raw), signal);
-			const query = (0, _embedpdf_engine_core_runtime.canonicalSearchQuery)(request.query);
+			const query = (0, _embedpdf_engine_core_runtime.canonicalSearchQuery)(request);
+			const from = request.from?.objectNumber;
 			if (request.cursor !== void 0) {
 				let token;
 				try {
@@ -763,7 +1310,7 @@ var CloudDocumentSearchService = class {
 					throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "malformed search cursor");
 				}
 				if (queryIdentity(token.query) !== queryIdentity(query)) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "search cursor belongs to a different query — restart the search");
-				if (request.startPage !== void 0 && request.startPage !== token.startPage) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "startPage conflicts with the cursor — omit startPage when resuming");
+				if (from !== void 0 && from !== token.from) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "`from` conflicts with the cursor — omit it when resuming");
 				try {
 					return await get(request.cursor);
 				} catch (err) {
@@ -774,9 +1321,9 @@ var CloudDocumentSearchService = class {
 			const mint = (epoch) => (0, _embedpdf_engine_core_wire.encodeSearchToken)({
 				epoch,
 				query,
-				...request.startPage !== void 0 ? { startPage: request.startPage } : {},
+				...from !== void 0 ? { from } : {},
 				skip: 0,
-				...request.budget !== void 0 ? { budget: request.budget } : {}
+				...request.limit !== void 0 ? { limit: request.limit } : {}
 			});
 			try {
 				return await get(mint((0, _embedpdf_engine_core_runtime.searchContentEpoch)(await this.manifest.get(signal))));
@@ -842,22 +1389,39 @@ function base64UrlDecode(b64url) {
 //#endregion
 //#region src/document/CloudDocumentSecurityService.ts
 var CloudDocumentSecurityService = class {
-	constructor(http, docId, layerName, initialHead, view, initialToken = null) {
+	constructor(http, docId, layerName, initialHead, view, initialToken = null, editing = null) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.view = view;
-		_defineProperty(this, "state", void 0);
+		this.editing = editing;
+		_defineProperty(this, "securityState", void 0);
 		_defineProperty(this, "access", null);
 		_defineProperty(this, "tokenScope", void 0);
 		_defineProperty(this, "tokenIdentity", void 0);
-		this.state = (0, _embedpdf_engine_core_runtime.securityStateFromHead)(initialHead);
+		_defineProperty(this, "tokenHasDocScope", void 0);
+		_defineProperty(this, "protection", null);
+		_defineProperty(this, "passwordRejected", false);
+		this.securityState = (0, _embedpdf_engine_core_runtime.securityStateFromHead)(initialHead);
 		const claims = initialToken ? safeDecodeClaims(initialToken) : null;
 		this.tokenScope = Array.isArray(claims?.scope) ? claims.scope : [];
 		this.tokenIdentity = claims ? identityFromClaims(claims) : null;
+		this.tokenHasDocScope = typeof claims?.doc_id === "string" && Array.isArray(claims?.scope);
+	}
+	/**
+	* What the caller may read of a page picture, when the client can know it:
+	* once `/access` answered, or from a document token's scope. Null without
+	* either (no token, a tenant or API token): the server decides.
+	*/
+	pageLayerRights() {
+		if (!this.access && !this.tokenHasDocScope) return null;
+		return {
+			annotations: this.allows("doc.annotate.read"),
+			formFields: this.allows("doc.forms.read")
+		};
 	}
-	get current() {
-		return this.state;
+	get state() {
+		return this.securityState;
 	}
 	get currentAccess() {
 		return this.access;
@@ -865,52 +1429,60 @@ var CloudDocumentSecurityService = class {
 	/**
 	* Expanded capability set. Cloud-canonical post-/access; otherwise
 	* computed locally from the JWT scope + /head's pdf bits using the
-	* SAME `expandRawScope` helper engine-local calls — so the value
+	* same `expandRawScope` helper engine-local calls — so the value
 	* matches across engines bit-for-bit on the same inputs.
 	*/
-	get effectiveScope() {
+	get scope() {
 		if (this.access) return this.access.effectiveScope;
-		const bits = (0, _embedpdf_engine_core_runtime.decodePdfBits)(this.state.permissions.bits);
-		return Array.from((0, _embedpdf_engine_core_runtime.expandRawScope)(this.tokenScope, bits)).sort();
+		return Array.from((0, _embedpdf_engine_core_runtime.expandRawScope)(this.tokenScope, this.pdfBits(), this.protection)).sort();
 	}
 	/**
-	* Wildcard-aware authorization check — mirrors what the server route layer
-	* enforces with. `effectiveScope` alone can't gate UI: it enumerates concrete
-	* grants and drops the `*` admin wildcard. So we honor a server-canonical
-	* concrete grant when present, then fall back to the same `checkCapability`
-	* predicate (which short-circuits `*`) against the JWT scope + /head bits.
+	* The server route guards' own predicate over the same inputs: what the
+	* document's signatures forbid first, then the scope (the server's copy
+	* once `/access` answered, else the JWT's), wildcard included, against the
+	* PDF bits. `scope` alone can't gate UI: it enumerates concrete grants and
+	* drops the `*` admin wildcard.
 	*/
 	allows(cap) {
-		if (this.access?.effectiveScope.includes(cap)) return true;
-		const bits = (0, _embedpdf_engine_core_runtime.decodePdfBits)(this.state.permissions.bits);
-		return (0, _embedpdf_engine_core_runtime.checkCapability)(cap, this.tokenScope, bits);
+		return (0, _embedpdf_engine_core_runtime.checkCapability)(cap, this.rawScope(), this.pdfBits(), this.protection);
 	}
 	/**
-	* Per-record annotation authorization mirrors — the same
-	* `checkCollab`/`checkSetGroup` resolvers the server's route layer
-	* enforces with, over the same inputs: the raw scope
-	* (server-canonical post-/access, else the JWT's own claim), the
-	* caller's identity, and /head's PDF bits. A control gated on these
-	* matches the server's allow/deny for the same mutation. False
-	* before any token/access context exists — fail closed, same rule
-	* as `allows`.
+	* Cloud-internal: what the document's signatures forbid, from the latest
+	* manifest (it changes only when a signature publishes a new version).
 	*/
-	allowsAnnotationCreate() {
+	setProtection(protection) {
+		this.protection = protection;
+	}
+	allowsAnnotation(action, target) {
 		const id = this.identity ?? {};
-		return (0, _embedpdf_engine_core_runtime.checkCollab)("create", selfTarget(id), this.rawScope(), id, this.pdfBits());
+		const annotationsProtected = (0, _embedpdf_engine_core_runtime.protectedCapabilities)(this.protection).has("doc.annotate.modify");
+		switch (action) {
+			case "create":
+				if (annotationsProtected) return false;
+				return (0, _embedpdf_engine_core_runtime.checkCollab)("create", selfTarget(id), this.rawScope(), id, this.pdfBits());
+			case "set-group": return (0, _embedpdf_engine_core_runtime.checkSetGroup)("annotations", target.groupId, id.groupId, this.rawScope());
+			default: {
+				const annotation = target ?? {};
+				if (annotation.subtype === "widget") return this.allows("doc.forms.modify");
+				if (annotationsProtected) return false;
+				return (0, _embedpdf_engine_core_runtime.checkCollab)(action, (0, _embedpdf_engine_core_runtime.collabTargetOf)(annotation), this.rawScope(), id, this.pdfBits());
+			}
+		}
 	}
-	allowsAnnotationMutation(action, target) {
-		return (0, _embedpdf_engine_core_runtime.checkCollab)(action, target, this.rawScope(), this.identity ?? {}, this.pdfBits());
+	allowsField(action, target) {
+		if (action === "set-group") return (0, _embedpdf_engine_core_runtime.checkSetGroup)("fields", target.groupId ?? "", this.identity?.groupId, this.rawScope());
+		return (0, _embedpdf_engine_core_runtime.checkFieldAction)(action, target.groupId, this.rawScope(), this.pdfBits(), this.protection);
 	}
-	allowsAnnotationGroupAssignment(groupId) {
-		return (0, _embedpdf_engine_core_runtime.checkSetGroup)(groupId, this.identity?.group_id, this.rawScope(), this.pdfBits());
+	/** The same inputs as `allowsField`, as lists. */
+	fieldRights() {
+		return (0, _embedpdf_engine_core_runtime.fieldRightsOf)(this.rawScope(), this.pdfBits(), this.protection, this.identity?.groupId);
 	}
 	/** Raw scope for the collab resolver: server-canonical post-/access, else the JWT claim. */
 	rawScope() {
 		return this.access?.scope ?? this.tokenScope;
 	}
 	pdfBits() {
-		return (0, _embedpdf_engine_core_runtime.decodePdfBits)(this.state.permissions.bits);
+		return (0, _embedpdf_engine_core_runtime.decodePdfBits)(this.securityState.permissions.bits);
 	}
 	/**
 	* Identity of the current caller, or null when anonymous.
@@ -930,21 +1502,28 @@ var CloudDocumentSecurityService = class {
 	* security state. See `passwordPromptFromState` for the rules.
 	*/
 	get passwordPrompt() {
-		return (0, _embedpdf_engine_core_runtime.passwordPromptFromState)(this.state);
+		return (0, _embedpdf_engine_core_runtime.passwordPromptFromState)(this.securityState, this.passwordRejected);
 	}
 	unlock(input) {
 		if (this.view.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			return await this.postAccess(signal, {
-				password: input.password,
-				mode: input.mode ?? "any"
-			});
+			try {
+				const result = await this.postAccess(signal, {
+					password: input.password,
+					mode: input.mode ?? "any"
+				});
+				this.passwordRejected = false;
+				return result;
+			} catch (error) {
+				if (_embedpdf_engine_core_runtime.EngineError.is(error, _embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordIncorrect)) this.passwordRejected = true;
+				throw error;
+			}
 		});
 	}
 	/**
 	* Cloud-internal: call /v1/access with no password to establish
 	* a CDN-credentialed session. Used by `CloudEngine.open` when
-	* /head's `access.reasons` includes 'cdn' but NOT 'password' —
+	* /head's `access.reasons` includes 'cdn' but not 'password' —
 	* the server accepts an authenticated /access POST without a
 	* password and returns the signed-URL block.
 	*
@@ -963,7 +1542,9 @@ var CloudDocumentSecurityService = class {
 	* password) and `establishAccess()` (no password). Updates cached
 	* security state, caches the access block, and pushes the CDN
 	* binding into the HttpClient so subsequent fetches apply CDN
-	* tokens via `applyCdnAccess`.
+	* tokens via `applyCdnAccess`. It goes as the editing session, and a
+	* caller that may create gets the session's object numbers with it
+	* (`edit`).
 	*
 	* `none` CDN adapter → the access block has null overrides/policies
 	* and `applyCdnAccess` short-circuits to origin; safe to call always.
@@ -971,27 +1552,33 @@ var CloudDocumentSecurityService = class {
 	async postAccess(signal, body) {
 		const response = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.access(this.docId, this.layerName), {
 			...body.password ? { password: body.password } : {},
-			mode: body.mode
-		}, (raw) => _embedpdf_engine_core_wire.AccessResponseSchema.parse(raw), signal);
-		this.state = response.security;
+			mode: body.mode,
+			...this.editing ? { objectNumbers: this.editing.wanted() } : {}
+		}, (raw) => _embedpdf_engine_core_wire.AccessResponseSchema.parse(raw), signal, { session: true });
+		this.securityState = response.security;
+		this.protection = response.protection;
 		this.access = {
 			cdn: response.cdn,
 			passwordGrant: response.passwordGrant,
 			pdfPermissions: response.pdfPermissions,
 			scope: response.scope,
 			effectiveScope: response.effectiveScope,
+			protection: response.protection,
 			identity: response.identity,
 			originPasswordPolicy: response.originPasswordPolicy,
 			expiresAt: response.expiresAt,
-			...response.renderPolicy ? { renderPolicy: response.renderPolicy } : {}
+			...response.renderPolicy ? { renderPolicy: response.renderPolicy } : {},
+			bundleLimits: response.bundleLimits,
+			...response.edit ? { edit: response.edit } : {}
 		};
+		if (response.edit) this.editing?.opened(response.edit);
 		this.http.setCdnAccess({
 			cdn: response.cdn,
 			docId: this.docId,
 			layerName: this.layerName
 		});
 		return {
-			security: this.state,
+			security: this.securityState,
 			access: this.access ?? void 0
 		};
 	}
@@ -1011,25 +1598,39 @@ function safeDecodeClaims(token) {
 	}
 }
 /**
-* CREATE's CollabTarget is the caller's own identity — the same
+* Create's CollabTarget is the caller's own identity — the same
 * derivation as engine-local's `ScopeGuard.targetForSelfCreate`, so
 * `:self` trivially passes and `:group=X` matches the caller's
 * default group.
 */
 function selfTarget(id) {
 	return {
-		...id.user_id !== void 0 ? { userId: id.user_id } : {},
-		...id.group_id !== void 0 ? { groupId: id.group_id } : {}
+		...id.userId !== void 0 ? { userId: id.userId } : {},
+		...id.groupId !== void 0 ? { groupId: id.groupId } : {}
 	};
 }
+const IDENTITY_STRING_FIELDS = [
+	"userId",
+	"displayName",
+	"email",
+	"title",
+	"organization",
+	"organizationalUnit",
+	"groupId"
+];
+/**
+* The token's `identity` claim, read the way the server reads it: string
+* fields, empty values absent. The server rejects a
+* malformed claim; unverified here, anything else is skipped.
+*/
 function identityFromClaims(claims) {
+	const claim = claims["identity"];
+	if (!claim || typeof claim !== "object" || Array.isArray(claim)) return null;
+	const record = claim;
 	const out = {};
-	if (typeof claims["user_id"] === "string") out.user_id = claims["user_id"];
-	if (typeof claims["group_id"] === "string") out.group_id = claims["group_id"];
-	if (typeof claims["display_name"] === "string") out.display_name = claims["display_name"];
-	if (Array.isArray(claims["groups"])) {
-		const groups = claims["groups"].filter((g) => typeof g === "string");
-		if (groups.length > 0) out.groups = groups;
+	for (const key of IDENTITY_STRING_FIELDS) {
+		const value = record[key];
+		if (typeof value === "string" && value.length > 0) out[key] = value;
 	}
 	return Object.keys(out).length > 0 ? out : null;
 }
@@ -1038,11 +1639,11 @@ function identityFromClaims(claims) {
 /**
 * Cloud-side digital signatures. Two kinds of read, two kinds of URL:
 *
-*   - The LAYER view (`list`, and `analyze` of the working copy) is pinned
+*   - The layer view (`list`, and `analyze` of the working copy) is pinned
 *     by the manifest's `docVersion`, like every other layer read: a
 *     signature is a layer state change, the immutable URL moves with it.
-*   - Signed BYTES (`contents`, `digest`, `revisionBytes`, and `analyze`
-*     of history) belong to a base VERSION and are content-addressed by
+*   - Signed bytes (`contents`, `digest`, `revisionBytes`, and `analyze`
+*     of history) belong to a base version and are content-addressed by
 *     the manifest's `baseSha`: immutable forever, shared by every layer
 *     and every caller.
 *
@@ -1052,13 +1653,14 @@ function identityFromClaims(claims) {
 * refresh it before returning.
 */
 var CloudDocumentSignaturesService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
 	}
 	list() {
 		const rejected = this.closedRejection();
@@ -1070,7 +1672,7 @@ var CloudDocumentSignaturesService = class {
 			await this.manifest.refresh(s);
 		}, signal));
 	}
-	contents(field) {
+	getContents(field) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
@@ -1079,7 +1681,7 @@ var CloudDocumentSignaturesService = class {
 			return this.http.getBytes(_embedpdf_engine_core_wire.wirePaths.docVersionSignatureContents(this.docId, manifest.baseSha, name), signal);
 		});
 	}
-	digest(field, algorithm) {
+	getDigest(field, algorithm) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
@@ -1088,7 +1690,7 @@ var CloudDocumentSignaturesService = class {
 			return this.http.getBytes(_embedpdf_engine_core_wire.wirePaths.docVersionSignatureDigest(this.docId, manifest.baseSha, name, algorithm), signal);
 		});
 	}
-	revisionBytes(revisionIndex) {
+	downloadRevision(revisionIndex) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
@@ -1097,16 +1699,17 @@ var CloudDocumentSignaturesService = class {
 		});
 	}
 	/**
-	* `until: 'working-copy'` (or unset while the layer holds edits) judges
-	* the layer's pending edits against the base at the layer URL; anything
-	* else is history of the base version and resolves at the version URL.
+	* `until: 'working-copy'` judges the layer's pending edits against the
+	* base at the layer URL; anything else, the default `'persisted'`
+	* included, is history of the base version and resolves at the version
+	* URL (the saved file, as the local engine judges by default).
 	*/
 	analyze(input) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			const manifest = await this.manifest.get(signal);
-			if (input.until === "working-copy" || input.until === void 0 && manifest.working) return this.http.getJsonWithRefresh(async (s) => {
+			if (input.until === "working-copy") return this.http.getJsonWithRefresh(async (s) => {
 				const current = await this.manifest.get(s);
 				return _embedpdf_engine_core_wire.wirePaths.layerSignaturesAnalysis(this.docId, this.layerName, {
 					docVersion: current.docVersion,
@@ -1125,65 +1728,65 @@ var CloudDocumentSignaturesService = class {
 			}), (raw) => _embedpdf_engine_core_wire.ChangeAnalysisSchema.parse(raw), signal);
 		});
 	}
-	prepare(input) {
+	prepare(input, options) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const { appearance, ...rest } = input;
-			const form = buildMutationForm({
-				...rest,
-				...appearance ? { appearance: {
-					resource: "appearance",
-					...appearance.pageIndex !== void 0 ? { pageIndex: appearance.pageIndex } : {}
-				} } : {}
-			}, appearance ? { appearance: {
-				bytes: appearance.pdf.slice().buffer,
-				mimeType: "application/pdf",
-				name: "appearance.pdf"
-			} } : {});
-			const prepared = await this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerSignaturesPrepare(this.docId, this.layerName), form, (raw) => (0, _embedpdf_engine_core_wire.decodePrepared)(_embedpdf_engine_core_wire.SignaturePreparedWireSchema.parse(raw)), signal);
-			await this.manifest.refresh(signal);
-			this.publisher.publishLocal({
-				type: "signature.prepared",
-				signingId: prepared.signingId,
-				field: input.field
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const { appearance, ...rest } = input;
+				const form = buildRoleMutationForm(rest, { appearance: appearance && {
+					bytes: appearance.pdf.slice().buffer,
+					mimeType: "application/pdf",
+					name: "appearance.pdf"
+				} });
+				const prepared = await write.send((sent) => this.http.postMultipartJson(_embedpdf_engine_core_wire.wirePaths.layerSignaturesPrepare(this.docId, this.layerName), form, (raw) => (0, _embedpdf_engine_core_wire.decodePrepared)(_embedpdf_engine_core_wire.SignaturePreparedWireSchema.parse(raw)), signal, sent));
+				await this.manifest.refresh(signal);
+				this.publisher.publishWrite(opId, {
+					type: "signatures.prepared",
+					field: input.field,
+					...prepared
+				});
+				return prepared;
 			});
-			return prepared;
 		});
 	}
-	complete(input) {
+	complete(input, options) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerSignatureComplete(this.docId, this.layerName, input.signingId), {
-				cms: (0, _embedpdf_engine_core_wire.toBase64)(input.cms),
-				expectedVersion: input.expectedVersion
-			}, (raw) => _embedpdf_engine_core_wire.SignatureCompleteResultSchema.parse(raw), signal);
-			await this.manifest.refresh(signal);
-			if (result.status === "completed") {
-				this.publisher.publishLocal({
-					type: "signature.completed",
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerSignatureComplete(this.docId, this.layerName, input.signingId), {
+					cms: (0, _embedpdf_engine_core_wire.toBase64)(input.cms),
+					expectedVersion: input.expectedVersion
+				}, (raw) => _embedpdf_engine_core_wire.SignatureCompleteResultSchema.parse(raw), signal, sent));
+				await this.manifest.refresh(signal);
+				if (result.status === "completed") this.publisher.publishWrite(opId, {
+					type: "signatures.completed",
 					signingId: input.signingId,
 					...result
-				});
-				this.publisher.publishLocal({
+				}, {
 					type: "document.versioned",
 					version: result.version
 				});
-			}
-			return result;
+				return result;
+			});
 		});
 	}
-	abort(signingId) {
+	cancel(signingId, options) {
 		const rejected = this.closedRejection();
 		if (rejected) return rejected;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerSignatureAbort(this.docId, this.layerName, signingId), (raw) => _embedpdf_engine_core_wire.SignatureAbortResultSchema.parse(raw), signal);
-			if (result.status === "aborted") this.publisher.publishLocal({
-				type: "signature.aborted",
-				signingId
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.deleteJson(_embedpdf_engine_core_wire.wirePaths.layerSignatureCancel(this.docId, this.layerName, signingId), (raw) => _embedpdf_engine_core_wire.SignatureCancelResultSchema.parse(raw), signal, sent));
+				if (result.status === "cancelled") this.publisher.publishWrite(opId, {
+					type: "signatures.cancelled",
+					signingId
+				});
+				return result;
 			});
-			return result;
 		});
 	}
 	/** Version routes address a field by its fully qualified name; an object-number ref is resolved through the snapshot. */
@@ -1194,8 +1797,8 @@ var CloudDocumentSignaturesService = class {
 			return _embedpdf_engine_core_wire.wirePaths.layerSignatures(this.docId, this.layerName, manifest.docVersion);
 		}, (raw) => _embedpdf_engine_core_wire.SignatureSnapshotSchema.parse(raw), async (s) => {
 			await this.manifest.refresh(s);
-		}, signal)).signatures.find((s) => s.field.kind === "objectNumber" && s.field.fieldObjectNumber === field.fieldObjectNumber);
-		if (!match) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no signature field #${field.fieldObjectNumber}`);
+		}, signal)).signatures.find((s) => s.field.kind === "objectNumber" && s.field.objectNumber === field.objectNumber);
+		if (!match) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no signature field #${field.objectNumber}`);
 		return match.fieldName;
 	}
 	closedRejection() {
@@ -1205,50 +1808,330 @@ var CloudDocumentSignaturesService = class {
 };
 //#endregion
 //#region src/document/CloudMetadataService.ts
+const STANDARD = {
+	docPath: _embedpdf_engine_core_wire.wirePaths.docMetadata,
+	layerPath: _embedpdf_engine_core_wire.wirePaths.layerMetadata,
+	updatePath: _embedpdf_engine_core_wire.wirePaths.layerMetadataUpdate,
+	parse: (raw) => _embedpdf_engine_core_wire.DocumentMetadataSchema.parse(raw),
+	parseResult: (raw) => _embedpdf_engine_core_wire.MetadataUpdateResultSchema.parse(raw)
+};
+const CUSTOM = {
+	docPath: _embedpdf_engine_core_wire.wirePaths.docCustomMetadata,
+	layerPath: _embedpdf_engine_core_wire.wirePaths.layerCustomMetadata,
+	updatePath: _embedpdf_engine_core_wire.wirePaths.layerCustomMetadataUpdate,
+	parse: (raw) => _embedpdf_engine_core_wire.CustomMetadataSchema.parse(raw),
+	parseResult: (raw) => _embedpdf_engine_core_wire.CustomMetadataUpdateResultSchema.parse(raw)
+};
+function closedError(docId) {
+	return new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${docId} is closed`);
+}
+/**
+* The read. The JSON lives at a content-addressed `…@metadataVersion=N` leaf
+* (not in the manifest); the manifest only publishes the `metadataVersion`
+* pointer, which both halves of the dict share. So the read pulls it from
+* the cached manifest, fetches the leaf, and on a 404 (stale pointer)
+* transparently refreshes the manifest and retries once. `metadataVersion`
+* bumps only on metadata writes, so the leaf stays cached across page and
+* annotation edits.
+*/
+function readLeaf(deps, leaf) {
+	if (deps.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(closedError(deps.docId));
+	return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+		const buildPath = async (s) => {
+			const manifest = await deps.manifest.get(s);
+			return planesInherited(manifest, ["metadata"]) ? leaf.docPath(deps.docId, manifest.metadataVersion) : leaf.layerPath(deps.docId, deps.layerName, manifest.metadataVersion);
+		};
+		return deps.http.getJsonWithRefresh(buildPath, leaf.parse, async (s) => {
+			await deps.manifest.refresh(s);
+		}, signal);
+	});
+}
+/**
+* The write. It only advances docVersion + metadataVersion (no per-page pin
+* changes, no layoutVersion), so the cached manifest is patched in place —
+* no refetch. `publish` gets the write's `opId`.
+*/
+function writeLeaf(deps, leaf, patch, options, publish) {
+	if (deps.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(closedError(deps.docId));
+	return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+		const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		return deps.writes.run(opId, signal, async (write) => {
+			const result = await write.send((sent) => deps.http.postJson(leaf.updatePath(deps.docId, deps.layerName), patch, leaf.parseResult, signal, sent));
+			deps.manifest.apply(result.meta, ["metadata"]);
+			publish(result, opId);
+			return result;
+		});
+	});
+}
+var CloudCustomMetadataService = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	get() {
+		return readLeaf(this.deps, CUSTOM);
+	}
+	update(patch, options) {
+		return writeLeaf(this.deps, CUSTOM, patch, options, (result, opId) => this.deps.publisher.publishWrite(opId, {
+			type: "metadata.customUpdated",
+			...result
+		}));
+	}
+};
 var CloudMetadataService = class {
-	constructor(http, docId, layerName, isClosed, manifest, publisher) {
-		this.http = http;
-		this.docId = docId;
-		this.layerName = layerName;
-		this.isClosed = isClosed;
-		this.manifest = manifest;
-		this.publisher = publisher;
+	constructor(http, docId, layerName, isClosed, manifest, publisher, writes) {
+		_defineProperty(this, "custom", void 0);
+		_defineProperty(this, "deps", void 0);
+		this.deps = {
+			http,
+			docId,
+			layerName,
+			isClosed,
+			manifest,
+			publisher,
+			writes
+		};
+		this.custom = new CloudCustomMetadataService(this.deps);
 	}
-	/**
-	* Document metadata read. The Info-dict JSON lives at the
-	* content-addressed `/metadata@metadataVersion=N` leaf (not in the
-	* manifest); the manifest only publishes the `metadataVersion` pointer.
-	* So `read()` pulls `metadataVersion` from the cached manifest, fetches
-	* the leaf, and on a 404 (stale pointer) transparently refreshes the
-	* manifest and retries once. `metadataVersion` bumps only on metadata
-	* writes, so this leaf stays cached across page and annotation edits.
-	*/
-	read() {
-		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const buildPath = async (s) => {
-				const manifest = await this.manifest.get(s);
-				return planesInherited(manifest, ["metadata"]) ? _embedpdf_engine_core_wire.wirePaths.docMetadata(this.docId, manifest.metadataVersion) : _embedpdf_engine_core_wire.wirePaths.layerMetadata(this.docId, this.layerName, manifest.metadataVersion);
-			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.DocumentMetadataSchema.parse(raw), async (s) => {
-				await this.manifest.refresh(s);
-			}, signal);
-		});
+	get() {
+		return readLeaf(this.deps, STANDARD);
 	}
-	update(patch) {
-		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
+	update(patch, options) {
+		return writeLeaf(this.deps, STANDARD, patch, options, (result, opId) => this.deps.publisher.publishWrite(opId, {
+			type: "metadata.updated",
+			...result
+		}));
+	}
+};
+//#endregion
+//#region src/document/CloudObjectNumberPool.ts
+/** Below this many held numbers, a write asks for a top-up… */
+const LOW_WATER = 8;
+/** …of up to this many, the most the server tops up by. */
+const TOP_UP = 32;
+/** The most one bulk reservation asks for. */
+const MAX_RESERVATION = 1e3;
+/** An editing session's lifetime (ms) until the server states one: the protocol's 15 minutes. */
+const DEFAULT_LIFETIME_MS = 15 * 6e4;
+/**
+* The cloud engine's object numbers: what the server handed this editing
+* session (the engine's `X-Engine-Session-Id` with the token's subject).
+*
+* Numbers arrive with `/access`, with a write's response (the top-up a
+* write asks for when fewer than 8 are held), with the event stream's
+* `session` events, and from `reserve`'s bulk reservation. A number
+* `take` hands out is the caller's until a write naming it commits.
+*
+* The session lives while the event stream is connected or something
+* keeps it alive; without that it expires, and its numbers may go to
+* another session. So once its expiry has passed while the stream is down,
+* the pool hands out nothing until the server says again what it holds.
+* The stream's `session` event lists everything the session holds: any
+* number this pool held or handed out that isn't on it, and that no write
+* in flight names, is lost (`onLost`, `'reclaimed'`). A new version of the
+* document numbers objects anew: everything is lost (`'versioned'`).
+*/
+var CloudObjectNumberPool = class {
+	constructor(opts) {
+		this.opts = opts;
+		_defineProperty(this, "now", void 0);
+		_defineProperty(this, "available", []);
+		_defineProperty(this, "taken", /* @__PURE__ */ new Set());
+		_defineProperty(this, "writing", /* @__PURE__ */ new Map());
+		_defineProperty(this, "expiresAt", 0);
+		_defineProperty(this, "halfLifetimeMs", DEFAULT_LIFETIME_MS / 2);
+		_defineProperty(this, "streamConnected", false);
+		_defineProperty(this, "listeners", /* @__PURE__ */ new Set());
+		_defineProperty(this, "reserving", Promise.resolve());
+		_defineProperty(this, "version", null);
+		this.now = opts.now ?? Date.now;
+	}
+	get held() {
+		return this.usable() ? this.available.length : 0;
+	}
+	take() {
+		if (!this.usable()) return null;
+		const objectNumber = this.available.shift();
+		if (objectNumber === void 0) return null;
+		this.taken.add(objectNumber);
+		return objectNumber;
+	}
+	reserve(count) {
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(_embedpdf_engine_core_wire.wirePaths.layerMetadataUpdate(this.docId, this.layerName), patch, (raw) => _embedpdf_engine_core_wire.MetadataUpdateResultSchema.parse(raw), signal);
-			if (result.cache) this.manifest.applyMetadata(result.cache);
-			this.publisher.publishLocal({
-				type: "metadata.updated",
-				...result
+			const turn = this.reserving.then(async () => {
+				while (this.held < count) {
+					const wanted = Math.min(count - this.held, MAX_RESERVATION);
+					const reserved = await this.opts.reserve(wanted, signal);
+					this.receive(reserved.objectNumbers, reserved.expiresIn);
+				}
 			});
-			return result;
+			this.reserving = turn.catch(() => void 0);
+			await turn;
 		});
 	}
+	onLost(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** How many numbers a write should ask the server for: 0 while enough are held. */
+	topUp() {
+		const held = this.held;
+		return held < LOW_WATER ? TOP_UP - held : 0;
+	}
+	/** How many numbers `/access` should ask for: enough to make up the first block. */
+	wantedAtAccess() {
+		return Math.max(0, LOW_WATER - this.held);
+	}
+	/**
+	* `/access` answered for the editing session. A session the server made
+	* anew holds nothing of what this pool had.
+	*/
+	opened(edit) {
+		if (edit.session === "new") this.lose(this.unspent(), "reclaimed");
+		this.receive(edit.objectNumbers, edit.expiresIn);
+	}
+	/**
+	* Numbers handed to the session: by `/access`, a write's top-up or the
+	* bulk reservation; `expiresIn` (seconds) when the answer told it. Numbers
+	* held from before an expiry the server can't vouch for any more are
+	* dropped: only a `session` event says which survived.
+	*/
+	receive(ranges, expiresIn) {
+		if (expiresIn !== void 0) {
+			if (!this.usable()) this.lose(this.available.splice(0), "reclaimed");
+			this.expiresIn(expiresIn);
+		}
+		this.add((0, _embedpdf_engine_core_runtime.objectNumbersIn)(ranges));
+	}
+	/**
+	* The event stream's `session` event: everything the session holds now.
+	* What this pool held or handed out and the list doesn't name, unless a
+	* write in flight names it, is lost.
+	*/
+	sync(status) {
+		this.expiresIn(status.expiresIn);
+		const held = new Set((0, _embedpdf_engine_core_runtime.objectNumbersIn)(status.held));
+		const lost = this.unspent().filter((n) => !held.has(n));
+		for (const n of lost) this.taken.delete(n);
+		this.available = [...held].filter((n) => !this.taken.has(n) && !this.writing.has(n)).sort((a, b) => a - b);
+		this.emit(lost, "reclaimed");
+	}
+	/**
+	* Version `sha256` was published: it numbers objects anew, so every number
+	* held or handed out is gone. Told once per version (the stream and this
+	* engine's own completion both tell it, in either order).
+	*/
+	versioned(sha256) {
+		if (sha256 === this.version) return;
+		this.version = sha256;
+		this.lose(this.unspent(), "versioned");
+	}
+	/** The event stream connected or dropped: while it's up, the server keeps the session alive. */
+	connected(connected) {
+		this.streamConnected = connected;
+	}
+	/** A write that names `numbers` was called. */
+	beginWrite(numbers) {
+		for (const n of numbers) this.writing.set(n, (this.writing.get(n) ?? 0) + 1);
+	}
+	/**
+	* The write that named `numbers` settled. A committed write also kept the
+	* session alive: at least half its lifetime is left.
+	*/
+	endWrite(numbers, outcome) {
+		for (const n of numbers) {
+			const left = (this.writing.get(n) ?? 1) - 1;
+			if (left > 0) this.writing.set(n, left);
+			else this.writing.delete(n);
+			if (outcome !== "failed") this.taken.delete(n);
+		}
+		if (outcome === "committed") this.expiresAt = Math.max(this.expiresAt, this.now() + this.halfLifetimeMs);
+	}
+	usable() {
+		return this.streamConnected || this.now() < this.expiresAt;
+	}
+	expiresIn(seconds) {
+		const ms = seconds * 1e3;
+		this.expiresAt = this.now() + ms;
+		this.halfLifetimeMs = Math.max(this.halfLifetimeMs, ms / 2);
+	}
+	add(numbers) {
+		const known = /* @__PURE__ */ new Set([...this.available, ...this.taken]);
+		const fresh = numbers.filter((n) => !known.has(n) && !this.writing.has(n));
+		if (fresh.length === 0) return;
+		this.available = [...this.available, ...fresh].sort((a, b) => a - b);
+	}
+	/** Held or handed out, and named by no write in flight. */
+	unspent() {
+		return [...this.available, ...this.taken].filter((n) => !this.writing.has(n));
+	}
+	lose(numbers, reason) {
+		const gone = new Set(numbers);
+		this.available = this.available.filter((n) => !gone.has(n));
+		for (const n of gone) this.taken.delete(n);
+		this.emit([...gone], reason);
+	}
+	emit(numbers, reason) {
+		if (numbers.length === 0) return;
+		const lost = {
+			numbers: [...numbers].sort((a, b) => a - b),
+			reason
+		};
+		for (const listener of [...this.listeners]) listener(lost);
+	}
 };
 //#endregion
+//#region src/document/appearanceForm.ts
+/**
+* Parse the appearance `multipart/form-data` response into the same
+* `AnnotationAppearanceImagesResult` shape the local engine produces. The
+* `body` part is validated against the wire schema; each image (the part
+* `resource:<key>` its entry names) is wrapped in a `PageImageHandle`
+* backed by the in-memory blob we already downloaded.
+*/
+async function parseAppearanceForm(form) {
+	const raw = form.get("body");
+	if (typeof raw !== "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, "appearance response missing its body part");
+	let parsedJson;
+	try {
+		parsedJson = JSON.parse(raw);
+	} catch (err) {
+		throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `appearance body is not valid JSON: ${err?.message ?? err}`);
+	}
+	const body = _embedpdf_engine_core_wire.AnnotationAppearanceBatchSchema.parse(parsedJson);
+	const appearances = await Promise.all(body.appearances.map(async (entry) => {
+		const name = `resource:${entry.resources.image}`;
+		const partValue = form.get(name);
+		if (partValue === null || typeof partValue === "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `appearance response missing image part "${name}"`);
+		const blob = partValue;
+		const bytes = new Uint8Array(await blob.arrayBuffer());
+		const image = (0, _embedpdf_engine_core_runtime.createPageImageHandle)({
+			width: entry.width,
+			height: entry.height,
+			format: entry.format,
+			contentType: entry.contentType,
+			source: {
+				kind: "bytes",
+				bytes
+			}
+		}, { async blob() {
+			return blob;
+		} });
+		return {
+			ref: entry.ref,
+			mode: entry.mode,
+			state: entry.state,
+			rect: entry.rect,
+			image
+		};
+	}));
+	return {
+		page: body.page,
+		appearances
+	};
+}
+//#endregion
 //#region src/document/CloudPageAnnotationsService.ts
 /**
 * Cloud-side page annotation service. Mirrors the local wiring: each
@@ -1260,45 +2143,46 @@ var CloudMetadataService = class {
 * manifest. Mutations use unversioned layer URLs and are never cached.
 */
 var CloudPageAnnotationsService = class {
-	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, pageRef, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
-		this.pageObjectNumber = pageObjectNumber;
+		this.pageRef = pageRef;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
 	}
 	list() {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			const buildPath = async (s) => {
 				const manifest = await this.manifest.get(s);
-				const page = manifest.pages.find((p) => p.state.pageObjectNumber === this.pageObjectNumber);
-				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
-				return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotations(this.docId, this.pageObjectNumber, page.cache.annotationVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotations(this.docId, this.layerName, this.pageObjectNumber, page.cache.annotationVersion);
+				const pageObjectNumber = this.pageRef.objectNumber;
+				const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+				return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotations(this.docId, this.pageRef, page.cache.annotationVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotations(this.docId, this.layerName, this.pageRef, page.cache.annotationVersion);
 			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.AnnotationListPageSnapshotSchema.parse(raw), async (s) => {
+			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.AnnotationListSchema.parse(raw), async (s) => {
 				await this.manifest.refresh(s);
 			}, signal);
 		});
 	}
-	renderAppearances(_options) {
-		return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "annotations.renderAppearances() raw rasters are not available in the cloud engine; use renderAppearanceImages()"));
-	}
-	renderAppearanceImages(options = {}) {
+	renderAppearances(options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			(0, _embedpdf_engine_core_runtime.checkImageQuality)(options.quality);
 			const format = options.format ?? "webp";
 			const buildPath = async (s) => {
 				const manifest = await this.manifest.get(s);
-				const page = manifest.pages.find((p) => p.state.pageObjectNumber === this.pageObjectNumber);
-				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				const pageObjectNumber = this.pageRef.objectNumber;
+				const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
 				const wireToken = (0, _embedpdf_engine_core_wire.annotationAppearancesImageOptionsToWire)({
 					...options,
 					format
 				}, { annotationVersion: page.cache.annotationVersion });
-				return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotationAppearances(this.docId, this.pageObjectNumber, wireToken) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationAppearances(this.docId, this.layerName, this.pageObjectNumber, wireToken);
+				return planesInherited(manifest, ["annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageAnnotationAppearances(this.docId, this.pageRef, wireToken) : _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationAppearances(this.docId, this.layerName, this.pageRef, wireToken);
 			};
 			return parseAppearanceForm(await this.http.getFormDataWithRefresh(buildPath, async (s) => {
 				await this.manifest.refresh(s);
@@ -1306,121 +2190,140 @@ var CloudPageAnnotationsService = class {
 		});
 	}
 	/**
-	* Decode and return the file embedded in a FileAttachment annotation.
-	* A read over the immutable `attachment-files` leaf, pinned by the
-	* manifest's `attachmentsVersion` (annotation-level files re-key on the
-	* same pin as document-level ones), with the same stale-404 refresh
-	* retry as {@link list}. Weak `index` refs cannot be spliced into a GET
-	* URL (no body to carry the revision), so bytes reads require a stable
-	* id — the same `:annotKey` routing update()/delete() use.
+	* One of the annotation's resources. `file` is a read over the immutable
+	* `attachment-files` leaf, pinned by the manifest's `attachmentsVersion`
+	* (annotation-level files re-key on the same pin as document-level ones),
+	* with the same stale-404 refresh retry as {@link list}. `appearance` is a
+	* derived read (no-store), like {@link exportAppearance}. Both address the
+	* annotation by the same `:annotKey` update()/delete() use.
 	*/
-	downloadFile(ref) {
+	downloadResource(ref, role) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		if (ref.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
-		if (ref.kind === "index") return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "downloadFile requires a stable ref (objectNumber or nm); index refs cannot address the content-addressed file leaf"));
-		const annotKey = (0, _embedpdf_engine_core_runtime.encodeStableIdKey)(refToStableId(ref));
+		if (ref.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`));
+		const annotKey = (0, _embedpdf_engine_core_runtime.encodeAnnotKey)(ref);
+		if (role === "appearance") return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => this.http.getBytes(_embedpdf_engine_core_wire.wirePaths.layerAnnotationAppearanceResource(this.docId, this.layerName, this.pageRef, annotKey), signal));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			const buildPath = async (s) => {
 				const manifest = await this.manifest.get(s);
-				return planesInherited(manifest, ["annotations", "attachments"]) ? _embedpdf_engine_core_wire.wirePaths.docAnnotationFile(this.docId, this.pageObjectNumber, annotKey, manifest.attachmentsVersion) : _embedpdf_engine_core_wire.wirePaths.layerAnnotationFile(this.docId, this.layerName, this.pageObjectNumber, annotKey, manifest.attachmentsVersion);
+				return planesInherited(manifest, ["annotations", "attachments"]) ? _embedpdf_engine_core_wire.wirePaths.docAnnotationFile(this.docId, this.pageRef, annotKey, manifest.attachmentsVersion) : _embedpdf_engine_core_wire.wirePaths.layerAnnotationFile(this.docId, this.layerName, this.pageRef, annotKey, manifest.attachmentsVersion);
 			};
-			return parseAttachmentContent(await this.http.getFileWithRefresh(buildPath, async (s) => {
+			return (await this.http.getFileWithRefresh(buildPath, async (s) => {
 				await this.manifest.refresh(s);
-			}, signal));
+			}, signal)).bytes;
 		});
 	}
-	create(draft) {
+	create(draft, options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const { wire, resources } = await (0, _embedpdf_engine_core_runtime.normalizeAnnotationDraft)(draft);
-			const path = _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsCreate(this.docId, this.layerName, this.pageObjectNumber);
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
+		}
+		const { resources, objectNumber } = options;
+		const data = (0, _embedpdf_engine_core_runtime.withFileFromResource)(draft, resources);
+		const path = withObjectNumbers(_embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsCreate(this.docId, this.layerName, this.pageRef), { objectNumber });
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => {
+			const wireResources = await (0, _embedpdf_engine_core_runtime.resolveAnnotationResources)(resources);
 			const parse = (raw) => _embedpdf_engine_core_wire.AnnotationCreateResultSchema.parse(raw);
-			const result = hasResources(resources) ? await this.http.postMultipartJson(path, buildMutationForm(wire, resources), parse, signal) : await this.http.postJson(path, wire, parse, signal);
-			return this.absorbMutation(result, "annotation.created");
-		});
+			const result = await write.send((sent) => (0, _embedpdf_engine_core_runtime.hasAnnotationResources)(wireResources) ? this.http.postMultipartJson(path, buildAnnotationMutationForm(data, wireResources), parse, signal, sent) : this.http.postJson(path, data, parse, signal, sent));
+			return this.absorbMutation(opId, result, "annotations.created");
+		}, [objectNumber]));
 	}
-	update(ref, patch) {
+	update(ref, patch, options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		if (ref.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
-		if (ref.kind === "index") {
-			const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, "index");
-			return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-				const { wire, resources } = await (0, _embedpdf_engine_core_runtime.normalizeAnnotationPatch)(patch);
-				const result = await this.patchMutation(path, {
-					ref,
-					patch: wire
-				}, resources, signal);
-				return this.absorbMutation(result, "annotation.updated");
-			});
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
 		}
-		const stableKey = (0, _embedpdf_engine_core_runtime.encodeStableIdKey)(refToStableId(ref));
-		const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, stableKey);
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const { wire, resources } = await (0, _embedpdf_engine_core_runtime.normalizeAnnotationPatch)(patch);
-			const result = await this.patchMutation(path, { patch: wire }, resources, signal);
-			return this.absorbMutation(result, "annotation.updated");
-		});
+		const { resources } = options;
+		if (ref.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`));
+		const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, this.pageRef, (0, _embedpdf_engine_core_runtime.encodeAnnotKey)(ref));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => {
+			const wireResources = await (0, _embedpdf_engine_core_runtime.resolveAnnotationResources)(resources);
+			const result = await this.patchMutation(write, path, { patch }, wireResources, signal);
+			return this.absorbMutation(opId, result, "annotations.updated");
+		}));
 	}
-	/** PATCH as plain JSON, or as multipart when the patch carried binaries. */
-	patchMutation(path, body, resources, signal) {
+	/** PATCH as plain JSON, or as multipart when resources came with the patch. */
+	patchMutation(write, path, body, resources, signal) {
 		const parse = (raw) => _embedpdf_engine_core_wire.AnnotationUpdateResultSchema.parse(raw);
-		if (hasResources(resources)) return this.http.patchMultipartJson(path, buildMutationForm(body, resources), parse, signal);
-		return this.http.patchJson(path, body, parse, signal);
+		return write.send((sent) => (0, _embedpdf_engine_core_runtime.hasAnnotationResources)(resources) ? this.http.patchMultipartJson(path, buildAnnotationMutationForm(body, resources), parse, signal, sent) : this.http.patchJson(path, body, parse, signal, sent));
 	}
-	delete(ref) {
+	delete(ref, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		if (ref.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
-		if (ref.kind === "index") {
-			const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, "index");
-			return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-				const result = await this.http.patchJson(path, {
-					ref,
-					op: "delete"
-				}, (raw) => _embedpdf_engine_core_wire.AnnotationDeleteResultSchema.parse(raw), signal);
-				return this.absorbMutation(result, "annotation.deleted");
-			});
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
 		}
-		const stableKey = (0, _embedpdf_engine_core_runtime.encodeStableIdKey)(refToStableId(ref));
-		const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, stableKey);
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.deleteJson(path, (raw) => _embedpdf_engine_core_wire.AnnotationDeleteResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "annotation.deleted");
-		});
+		if (ref.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`));
+		const path = _embedpdf_engine_core_wire.wirePaths.layerAnnotationByKey(this.docId, this.layerName, this.pageRef, (0, _embedpdf_engine_core_runtime.encodeAnnotKey)(ref));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => {
+			const result = await write.send((sent) => this.http.deleteJson(path, (raw) => _embedpdf_engine_core_wire.AnnotationDeleteResultSchema.parse(raw), signal, sent));
+			return this.absorbDelete(opId, result);
+		}));
 	}
-	move(refs, toIndex) {
+	reorder(refs, position, options) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `move ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
-		const path = _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsMove(this.docId, this.layerName, this.pageObjectNumber);
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(path, {
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
+		}
+		for (const r of refs) if (r.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `reorder ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`));
+		const path = _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsReorder(this.docId, this.layerName, this.pageRef);
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => {
+			const result = await write.send((sent) => this.http.postJson(path, {
 				refs,
-				toIndex
-			}, (raw) => _embedpdf_engine_core_wire.AnnotationMoveResultSchema.parse(raw), signal);
-			return this.absorbMutation(result, "annotation.moved");
-		});
+				position
+			}, (raw) => _embedpdf_engine_core_wire.AnnotationReorderResultSchema.parse(raw), signal, sent));
+			this.manifest.apply(result.meta, ["annotations"]);
+			this.publisher.publishWrite(opId, {
+				type: "annotations.reordered",
+				page: this.pageRef,
+				...result
+			});
+			return result;
+		}));
 	}
-	flatten(refs, usage = "display") {
+	flatten(refs, options) {
+		const usage = options?.usage ?? "display";
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `flatten ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
-		const path = _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsFlatten(this.docId, this.layerName, this.pageObjectNumber);
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const result = await this.http.postJson(path, {
+		let opId;
+		try {
+			opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
+		} catch (err) {
+			return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(err);
+		}
+		for (const r of refs) if (r.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `flatten ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`));
+		const path = _embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsFlatten(this.docId, this.layerName, this.pageRef);
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => {
+			const result = await write.send((sent) => this.http.postJson(path, {
 				refs,
 				usage
-			}, (raw) => _embedpdf_engine_core_wire.AnnotationFlattenResultSchema.parse(raw), signal);
-			if (result.meta === null) return result;
-			this.manifest.apply(result.meta, ["content", "annotations"]);
-			this.publisher.publishLocal({
+			}, (raw) => _embedpdf_engine_core_wire.AnnotationFlattenResultSchema.parse(raw), signal, sent));
+			if (result.meta.cacheDelta === null) return result;
+			this.manifest.apply(result.meta, [
+				"content",
+				"annotations",
+				"forms"
+			]);
+			this.publisher.publishWrite(opId, {
 				type: "annotations.flattened",
 				...result
 			});
 			return result;
-		});
+		}));
 	}
 	exportAppearance(refs) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `exportAppearance ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => this.http.postJsonBytes(_embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsAppearance(this.docId, this.layerName, this.pageObjectNumber), { refs }, signal));
+		for (const r of refs) if (r.page.objectNumber !== this.pageRef.objectNumber) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `exportAppearance ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`));
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => this.http.postJsonBytes(_embedpdf_engine_core_wire.wirePaths.layerPageAnnotationsAppearance(this.docId, this.layerName, this.pageRef), { refs }, signal));
 	}
 	/**
 	* Patch the cached manifest, then publish the mutation to the document's
@@ -1429,148 +2332,130 @@ var CloudPageAnnotationsService = class {
 	* `type` with the matching result by construction; the cast localizes that
 	* pairing here instead of widening every site.
 	*/
-	absorbMutation(result, type) {
+	/** A delete's event names what went, for listeners that didn't delete it. */
+	absorbDelete(opId, result) {
 		this.manifest.apply(result.meta, ["annotations"]);
-		this.publisher.publishLocal({
+		this.publisher.publishWrite(opId, {
+			type: "annotations.deleted",
+			page: this.pageRef,
+			deleted: (0, _embedpdf_engine_core_runtime.deletedAnnotationsOf)(result),
+			...result
+		});
+		return result;
+	}
+	absorbMutation(opId, result, type) {
+		this.manifest.apply(result.meta, ["annotations"]);
+		this.publisher.publishWrite(opId, {
 			type,
-			pageObjectNumber: this.pageObjectNumber,
+			page: this.pageRef,
 			...result
 		});
 		return result;
 	}
 };
+//#endregion
+//#region src/document/CloudPageFormsService.ts
 /**
-* Parse the appearance `multipart/form-data` response into the same
-* `AnnotationAppearanceImagesResult` shape the local engine produces. The
-* `manifest` part is validated against the wire schema; each image part is
-* wrapped in a `PageImageHandle` backed by the in-memory blob we already
-* downloaded.
-*/
-async function parseAppearanceForm(form) {
-	const manifestRaw = form.get("manifest");
-	if (typeof manifestRaw !== "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, "appearance response missing JSON manifest part");
-	let parsedJson;
-	try {
-		parsedJson = JSON.parse(manifestRaw);
-	} catch (err) {
-		throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `appearance manifest is not valid JSON: ${err?.message ?? err}`);
-	}
-	const manifest = _embedpdf_engine_core_wire.AnnotationAppearanceManifestSchema.parse(parsedJson);
-	const appearances = await Promise.all(manifest.appearances.map(async (entry) => {
-		const partValue = form.get(entry.part);
-		if (partValue === null || typeof partValue === "string") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `appearance response missing image part "${entry.part}"`);
-		const blob = partValue;
-		const bytes = new Uint8Array(await blob.arrayBuffer());
-		const image = (0, _embedpdf_engine_core_runtime.createPageImageHandle)({
-			width: entry.width,
-			height: entry.height,
-			format: entry.format,
-			contentType: entry.contentType,
-			source: {
-				kind: "bytes",
-				bytes
-			}
-		}, { async blob() {
-			return blob;
-		} });
-		return {
-			ref: entry.ref,
-			mode: entry.mode,
-			rect: entry.rect,
-			image
-		};
-	}));
-	return {
-		pageState: manifest.pageState,
-		appearances
-	};
-}
-/**
-* Local helper: project a non-index `AnnotationRef` into the matching
-* `AnnotationStableId` shape so we can route by stable key. The compiler
-* narrows on `ref.kind` here so we can't accidentally pass an index ref.
+* Cloud page form service: the page's widget images, one read of the
+* immutable `form/pages/{p}/appearances@` leaf at the page's `widgetVersion`,
+* at the base's URL while the layer inherits the `forms` plane.
 */
-function refToStableId(ref) {
-	if (ref.kind === "objectNumber") return {
-		kind: "objectNumber",
-		value: ref.annotObjectNumber
-	};
-	return {
-		kind: "nm",
-		value: ref.nm
-	};
-}
-//#endregion
-//#region src/document/CloudPageGeometryService.ts
-var CloudPageGeometryService = class {
-	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest) {
+var CloudPageFormsService = class {
+	constructor(http, docId, layerName, pageRef, isClosed, manifest) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
-		this.pageObjectNumber = pageObjectNumber;
+		this.pageRef = pageRef;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 	}
-	read() {
+	renderAppearances(options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			(0, _embedpdf_engine_core_runtime.checkImageQuality)(options.quality);
+			const format = options.format ?? "webp";
 			const buildPath = async (s) => {
 				const manifest = await this.manifest.get(s);
-				const page = manifest.pages.find((p) => p.state.pageObjectNumber === this.pageObjectNumber);
-				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
-				return planesInherited(manifest, ["content"]) ? _embedpdf_engine_core_wire.wirePaths.docPageGeometry(this.docId, this.pageObjectNumber, page.cache.contentVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageGeometry(this.docId, this.layerName, this.pageObjectNumber, page.cache.contentVersion);
+				const pageObjectNumber = this.pageRef.objectNumber;
+				const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+				const token = (0, _embedpdf_engine_core_wire.widgetAppearancesImageOptionsToWire)({
+					...options,
+					format
+				}, { widgetVersion: page.cache.widgetVersion });
+				return planesInherited(manifest, ["forms"]) ? _embedpdf_engine_core_wire.wirePaths.docPageFormAppearances(this.docId, this.pageRef, token) : _embedpdf_engine_core_wire.wirePaths.layerPageFormAppearances(this.docId, this.layerName, this.pageRef, token);
 			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.PageGeometrySnapshotSchema.parse(raw), async (s) => {
+			return parseAppearanceForm(await this.http.getFormDataWithRefresh(buildPath, async (s) => {
 				await this.manifest.refresh(s);
-			}, signal);
+			}, signal));
 		});
 	}
 };
 //#endregion
 //#region src/document/CloudPageRenderService.ts
 var CloudPageRenderService = class {
-	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest) {
+	constructor(http, docId, layerName, pageRef, isClosed, manifest, layout, layerRights) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
-		this.pageObjectNumber = pageObjectNumber;
+		this.pageRef = pageRef;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
+		this.layout = layout;
+		this.layerRights = layerRights;
 	}
 	image(options = {}) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
+			(0, _embedpdf_engine_core_runtime.checkImageQuality)(options.quality);
 			const format = normalizeFormat(options.format);
-			const includeAnnotations = options.includeAnnotations ?? true;
+			const family = _embedpdf_engine_core_wire.PAGE_RENDER_FAMILIES[(0, _embedpdf_engine_core_wire.pageRenderFamilyOf)((0, _embedpdf_engine_core_runtime.resolvePageLayers)(options, this.layerRights() ?? {
+				annotations: true,
+				formFields: true
+			}))];
 			const buildPath = async (s) => {
 				const manifest = await this.manifest.get(s);
-				const page = manifest.pages.find((p) => p.state.pageObjectNumber === this.pageObjectNumber);
-				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				const pageObjectNumber = this.pageRef.objectNumber;
+				const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+				const pins = { contentVersion: page.cache.contentVersion };
+				for (const pin of family.pins) pins[pin] = page.cache[pin];
 				const wireToken = (0, _embedpdf_engine_core_wire.renderImageOptionsToWire)({
 					...options,
 					format
-				}, {
-					contentVersion: page.cache.contentVersion,
-					...includeAnnotations ? { annotationVersion: page.cache.annotationVersion } : {}
-				});
-				if (includeAnnotations) return planesInherited(manifest, ["content", "annotations"]) ? _embedpdf_engine_core_wire.wirePaths.docPageRenderAnnotated(this.docId, this.pageObjectNumber, wireToken) : _embedpdf_engine_core_wire.wirePaths.layerPageRenderAnnotated(this.docId, this.layerName, this.pageObjectNumber, wireToken);
-				return planesInherited(manifest, ["content"]) ? _embedpdf_engine_core_wire.wirePaths.docPageRender(this.docId, this.pageObjectNumber, wireToken) : _embedpdf_engine_core_wire.wirePaths.layerPageRender(this.docId, this.layerName, this.pageObjectNumber, wireToken);
+				}, pins);
+				return planesInherited(manifest, family.planes) ? _embedpdf_engine_core_wire.wirePaths.docPageRender(this.docId, family.family, this.pageRef, wireToken) : _embedpdf_engine_core_wire.wirePaths.layerPageRender(this.docId, this.layerName, family.family, this.pageRef, wireToken);
+			};
+			const [requestPath, transform] = await Promise.all([buildPath(signal), this.transformOf(options, signal)]);
+			return {
+				...createCloudPageImageHandle({
+					width: transform.width,
+					height: transform.height,
+					format,
+					contentType: `image/${format}`,
+					source: {
+						kind: "url",
+						url: this.http.absoluteUrl(requestPath)
+					}
+				}, this.http, buildPath, async (s) => {
+					await this.manifest.refresh(s);
+				}),
+				transform
 			};
-			const requestPath = await buildPath(signal);
-			return createCloudPageImageHandle({
-				format,
-				contentType: `image/${format}`,
-				source: {
-					kind: "url",
-					url: this.http.absoluteUrl(requestPath)
-				}
-			}, this.http, buildPath, async (s) => {
-				await this.manifest.refresh(s);
-			});
 		});
 	}
-	raw(_options) {
-		return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "render.raw() is not available in the cloud engine; use render.image()"));
+	/**
+	* The image's transform, computed like the server's render (the same
+	* `renderSize` and matrix), so the handle knows its size and its pixels
+	* before any are fetched. Only a full page needs the page's layout.
+	*/
+	async transformOf(options, signal) {
+		const target = options.target;
+		return (0, _embedpdf_engine_core_runtime.renderAreaTransform)(target?.kind === "rect" ? (0, _embedpdf_engine_core_runtime.renderTargetArea)(target.rect) : {
+			x: 0,
+			y: 0,
+			...(await this.layout(signal)).size
+		}, options);
 	}
 };
 function createCloudPageImageHandle(result, http, buildPath, onStaleVersion) {
@@ -1584,65 +2469,78 @@ function normalizeFormat(format) {
 //#endregion
 //#region src/document/CloudPageTextService.ts
 /**
-* Cloud-side per-page text service. `read()` fetches the
-* content-addressed URL `/v1/docs/:id/text/pages/:pon/data@contentVersion=N`, where
-* `:P` is the page's current `contentVersion` from the cached
-* manifest. On a 404 (stale version) the SDK transparently refreshes
-* `/head` + `/manifest@docVersion=N`, rebuilds the URL with the fresh `cN`,
-* and retries exactly once.
+* Cloud-side per-page text service. `get()` fetches the content-addressed
+* URL `/v1/docs/:id/text/pages/:pon/data@contentVersion=N` and `layout()`
+* its geometry twin, where `N` is the page's current `contentVersion` from
+* the cached manifest. On a 404 (stale version) the SDK transparently
+* refreshes `/head` + `/manifest@docVersion=N`, rebuilds the URL with the
+* fresh version, and retries exactly once.
 */
 var CloudPageTextService = class {
-	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest) {
+	constructor(http, docId, layerName, pageRef, isClosed, manifest) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
-		this.pageObjectNumber = pageObjectNumber;
+		this.pageRef = pageRef;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 	}
-	read() {
+	get() {
+		return this.readLeaf("text", (raw) => _embedpdf_engine_core_wire.PageTextSnapshotSchema.parse(raw));
+	}
+	slice(range) {
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => (0, _embedpdf_engine_core_runtime.sliceText)(await this.get().abortWith(signal), range));
+	}
+	layout() {
+		return this.readLeaf("geometry", (raw) => (0, _embedpdf_engine_core_runtime.createTextLayout)(_embedpdf_engine_core_wire.PageGeometrySnapshotSchema.parse(raw)));
+	}
+	/** One of the page's content leaves at the manifest's pin, with the stale-pin retry. */
+	readLeaf(leaf, parse) {
 		if (this.isClosed()) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`));
-		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			const buildPath = async (s) => {
-				const manifest = await this.manifest.get(s);
-				const page = manifest.pages.find((p) => p.state.pageObjectNumber === this.pageObjectNumber);
-				if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
-				return planesInherited(manifest, ["content"]) ? _embedpdf_engine_core_wire.wirePaths.docPageText(this.docId, this.pageObjectNumber, page.cache.contentVersion) : _embedpdf_engine_core_wire.wirePaths.layerPageText(this.docId, this.layerName, this.pageObjectNumber, page.cache.contentVersion);
-			};
-			return this.http.getJsonWithRefresh(buildPath, (raw) => _embedpdf_engine_core_wire.PageTextSnapshotSchema.parse(raw), async (s) => {
-				await this.manifest.refresh(s);
-			}, signal);
-		});
+		return _embedpdf_engine_core_runtime.AbortablePromise.run((signal) => this.http.getJsonWithRefresh(async (s) => this.leafPath(leaf, await this.manifest.get(s)), parse, async (s) => {
+			await this.manifest.refresh(s);
+		}, signal));
+	}
+	leafPath(leaf, manifest) {
+		const pageObjectNumber = this.pageRef.objectNumber;
+		const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber);
+		if (!page) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+		const version = page.cache.contentVersion;
+		if (planesInherited(manifest, ["content"])) return leaf === "text" ? _embedpdf_engine_core_wire.wirePaths.docPageText(this.docId, this.pageRef, version) : _embedpdf_engine_core_wire.wirePaths.docPageGeometry(this.docId, this.pageRef, version);
+		return leaf === "text" ? _embedpdf_engine_core_wire.wirePaths.layerPageText(this.docId, this.layerName, this.pageRef, version) : _embedpdf_engine_core_wire.wirePaths.layerPageGeometry(this.docId, this.layerName, this.pageRef, version);
 	}
 };
 //#endregion
 //#region src/document/CloudPageMeasureService.ts
 var CloudPageMeasureService = class {
-	constructor(http, docId, layerName, pon, isClosed, manifest, publisher) {
+	constructor(http, docId, layerName, pageRef, isClosed, manifest, publisher, writes) {
 		this.http = http;
 		this.docId = docId;
 		this.layerName = layerName;
-		this.pon = pon;
+		this.pageRef = pageRef;
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 		this.publisher = publisher;
+		this.writes = writes;
 	}
-	viewports() {
+	listViewports() {
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			this.check();
-			return this.http.getJson(_embedpdf_engine_core_wire.wirePaths.layerPageViewports(this.docId, this.layerName, this.pon), (raw) => _embedpdf_engine_core_wire.PageMeasurementViewportSchema.array().parse(raw), signal);
+			return this.http.getJson(_embedpdf_engine_core_wire.wirePaths.layerPageViewports(this.docId, this.layerName, this.pageRef), (raw) => _embedpdf_engine_core_wire.PageMeasurementViewportListSchema.parse(raw), signal);
 		});
 	}
-	setScale(measure) {
+	setScale(measure, options) {
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-			await Promise.resolve();
-			signal.throwIfAborted();
+			const opId = (0, _embedpdf_engine_core_runtime.opIdOf)(options);
 			this.check();
-			const result = await this.http.putJson(_embedpdf_engine_core_wire.wirePaths.layerPageScale(this.docId, this.layerName, this.pon), { measure }, (raw) => _embedpdf_engine_core_wire.PageScaleResultSchema.parse(raw), signal);
-			this.manifest.apply(result.meta, []);
-			this.publisher.publishLocal({
-				type: "page.viewportsChanged",
-				...result
+			return this.writes.run(opId, signal, async (write) => {
+				const result = await write.send((sent) => this.http.putJson(_embedpdf_engine_core_wire.wirePaths.layerPageScale(this.docId, this.layerName, this.pageRef), { measure }, (raw) => _embedpdf_engine_core_wire.PageScaleResultSchema.parse(raw), signal, sent));
+				this.manifest.apply(result.meta, []);
+				this.publisher.publishWrite(opId, {
+					type: "pages.scaleSet",
+					...result
+				});
+				return result;
 			});
 		});
 	}
@@ -1652,89 +2550,298 @@ var CloudPageMeasureService = class {
 };
 //#endregion
 //#region src/document/CloudPageHandle.ts
+/**
+* Cloud page handle, keyed on `ref` — the page's durable address (its
+* object number). Every service below addresses the wire by it
+* (`/pages/obj:N/…`), keys the manifest by its number, and publishes
+* that number in events.
+*/
 var CloudPageHandle = class {
-	constructor(pageObjectNumber, pageIndex, http, docId, layerName, isClosed, manifest, publisher) {
-		this.pageObjectNumber = pageObjectNumber;
-		this.pageIndex = pageIndex;
+	constructor(ref, http, docId, layerName, isClosed, manifest, publisher, writes, layout, layerRights) {
+		this.ref = ref;
 		_defineProperty(this, "annotations", void 0);
+		_defineProperty(this, "forms", void 0);
 		_defineProperty(this, "text", void 0);
-		_defineProperty(this, "geometry", void 0);
 		_defineProperty(this, "render", void 0);
 		_defineProperty(this, "measure", void 0);
-		this.measure = new CloudPageMeasureService(http, docId, layerName, pageObjectNumber, isClosed, manifest, publisher);
-		this.annotations = new CloudPageAnnotationsService(http, docId, layerName, pageObjectNumber, isClosed, manifest, publisher);
-		this.text = new CloudPageTextService(http, docId, layerName, pageObjectNumber, isClosed, manifest);
-		this.geometry = new CloudPageGeometryService(http, docId, layerName, pageObjectNumber, isClosed, manifest);
-		this.render = new CloudPageRenderService(http, docId, layerName, pageObjectNumber, isClosed, manifest);
+		this.measure = new CloudPageMeasureService(http, docId, layerName, ref, isClosed, manifest, publisher, writes);
+		this.annotations = new CloudPageAnnotationsService(http, docId, layerName, ref, isClosed, manifest, publisher, writes);
+		this.forms = new CloudPageFormsService(http, docId, layerName, ref, isClosed, manifest);
+		this.text = new CloudPageTextService(http, docId, layerName, ref, isClosed, manifest);
+		this.render = new CloudPageRenderService(http, docId, layerName, ref, isClosed, manifest, layout, layerRights);
+	}
+};
+//#endregion
+//#region src/document/CloudWrites.ts
+/**
+* A document's writes, sent one at a time in the order they were called,
+* so the server applies them in that order: a create, then an update of
+* what it made, never the other way round. Reads don't wait.
+*
+* A write takes its place when it is called: `run` must be the first thing
+* a write does, before anything it awaits. What it does before `send`
+* (reading a file to upload, say) happens meanwhile; its turn ends when it
+* settles, after the event it publishes.
+*
+* Changes (`doc.apply`) called one after another share a place: while the
+* write before them is in flight they wait together, and go out as one
+* request when their turn comes, each answered on its own.
+*/
+var CloudWrites = class {
+	constructor(pool, sendChanges = () => {
+		throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "this line sends no changes");
+	}) {
+		this.pool = pool;
+		this.sendChanges = sendChanges;
+		_defineProperty(this, "last", Promise.resolve());
+		_defineProperty(this, "open", null);
+	}
+	run(opId, signal, body, named = []) {
+		this.open = null;
+		const before = this.last;
+		const numbers = named.filter((n) => n !== void 0);
+		this.pool.beginWrite(numbers);
+		const settled = body({ send: async (request) => {
+			await untilTurn(before, signal);
+			const reserve = this.pool.topUp();
+			return request({ write: {
+				opId,
+				...reserve > 0 ? { reserveObjectNumbers: reserve } : {},
+				onObjectNumbers: (ranges) => this.pool.receive(ranges)
+			} });
+		} }).then((result) => {
+			this.pool.endWrite(numbers, "committed");
+			return result;
+		}, (error) => {
+			this.pool.endWrite(numbers, outcomeOf(error));
+			throw error;
+		});
+		this.last = before.then(() => settled.then(noop, noop));
+		return settled;
+	}
+	/**
+	* Take a change's place in the line: it joins the changes waiting for
+	* their turn, and goes out with them. `ready` is what the request sends
+	* for it, which it may still be preparing (reading bytes). A change aborted
+	* before its request goes out is left out of it; once out, it is answered.
+	*/
+	change(signal, ready, { named = [], alone = false } = {}) {
+		this.pool.beginWrite(named);
+		ready.catch(noop);
+		return new Promise((resolve, reject) => {
+			const lined = {
+				ready,
+				signal,
+				numbers: named,
+				resolve,
+				reject
+			};
+			(!alone && this.open !== null && this.open.changes.length < _embedpdf_engine_core_wire.CHANGE_REQUEST_LIMITS.changes ? this.open : this.queue()).changes.push(lined);
+			if (alone) this.open = null;
+		}).then((settled) => {
+			this.pool.endWrite(named, settledOutcomeOf(settled));
+			return settled;
+		}, (error) => {
+			this.pool.endWrite(named, outcomeOf(error));
+			throw error;
+		});
+	}
+	/** A new batch at the end of the line, open for the changes that follow. */
+	queue() {
+		const before = this.last;
+		const batch = { changes: [] };
+		this.open = batch;
+		const sent = before.then(() => this.send(batch));
+		this.last = sent.then(noop, noop);
+		return batch;
+	}
+	/** A batch's turn: nothing joins it any more, and what's ready goes out. */
+	async send(batch) {
+		if (this.open === batch) this.open = null;
+		const prepared = await Promise.allSettled(batch.changes.map((lined) => lined.ready));
+		const going = [];
+		batch.changes.forEach((lined, index) => {
+			const ready = prepared[index];
+			if (lined.signal.aborted) lined.reject(new _embedpdf_engine_core_runtime.AbortError(lined.signal.reason ?? "aborted"));
+			else if (ready.status === "rejected") lined.reject(ready.reason);
+			else going.push({
+				lined,
+				sent: ready.value
+			});
+		});
+		if (going.length === 0) return;
+		const reserve = this.pool.topUp();
+		try {
+			const answers = await this.sendChanges(going.map(({ sent }) => sent), { write: {
+				...reserve > 0 ? { reserveObjectNumbers: reserve } : {},
+				onObjectNumbers: (ranges) => this.pool.receive(ranges)
+			} });
+			if (answers.length !== going.length) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.WireFormat, `${going.length} changes sent, ${answers.length} answered`);
+			going.forEach(({ lined }, index) => lined.resolve(answers[index]));
+		} catch (error) {
+			for (const { lined } of going) lined.reject(error);
+		}
 	}
 };
+function noop() {}
+/** What a write that failed with `error` did with the numbers it named. */
+function outcomeOf(error) {
+	return _embedpdf_engine_core_runtime.EngineError.is(error, _embedpdf_engine_core_runtime.EngineErrorCode.ObjectNumberUnavailable) ? "refused" : "failed";
+}
+/** What an answered change did with the numbers it named, as a single write's outcome. */
+function settledOutcomeOf(answer) {
+	if (answer.status === "applied") return "committed";
+	return answer.error.code === _embedpdf_engine_core_runtime.EngineErrorCode.ObjectNumberUnavailable ? "refused" : "failed";
+}
+/** `before`, or an `AbortError` once `signal` aborts. */
+function untilTurn(before, signal) {
+	if (signal.aborted) return Promise.reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason ?? "aborted"));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason ?? "aborted"));
+		signal.addEventListener("abort", onAbort, { once: true });
+		before.then(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		});
+	});
+}
 //#endregion
-//#region src/realtime/auditRowToEvent.ts
+//#region src/realtime/auditRowToEvents.ts
 /**
-* Translate a remote audit row into a `DocumentEvent` — pure, so the
-* exactly-once and verbatim-payload invariants are unit-testable without a
-* server. Returns `null` for kinds this engine version doesn't know
-* (a NEWER server's events degrade to "ignored", never to a crash).
+* Translate a remote audit row into the `DocumentEvent`s it records — pure,
+* so the exactly-once and verbatim-payload invariants are unit-testable
+* without a server. Most rows are one fact; a change is the events of its
+* items, a form reset is one `forms.valueSet` per field it changed, an
+* import is one `annotations.created` per annotation, and a completed
+* signing is the signature and the new version. An undo's events name the
+* change it undid (`origin.undoOf`). Every event of a row shares `origin.tx`,
+* its id the request's `Idempotency-Key`. Returns none for an own echo and for kinds
+* this engine version doesn't know (a newer server's events degrade to
+* "ignored", never to a crash).
 *
 * Context-field fidelity differs by op, by design of the audit row:
 *   - rotate/delete: `affectedPages` is exactly the op's page set; rotation
 *     is recovered from the layout (it's absolute — every affected page
 *     carries the value).
-*   - move: the originator knows which block it moved; the audit row only
-*     records the resulting order, so `pageObjectNumbers` is the full new
-*     order and `destIndex` is absent (remote consumers use `layout`).
+*   - reorder: the payload is the result, as the originator got it: the
+*     pages that moved and the new `layout`.
+*
+* The audit row keys pages by object number (its storage identity); the
+* event carries them as `PageRef` addresses, like every other event.
 */
-function auditRowToEvent(row, mySessionId) {
-	if (row.originSessionId === mySessionId) return null;
+function auditRowToEvents(row, mySessionId) {
+	if (row.originSessionId === mySessionId) return [];
+	if (row.withheld) return [];
 	const origin = {
 		kind: "remote",
 		sessionId: row.originSessionId ?? `unknown:${row.sub}`,
 		sub: row.sub,
 		ts: row.ts,
-		serverId: row.id
+		serverId: row.id,
+		...row.undoOf ? { undoOf: row.undoOf } : {}
 	};
+	const id = row.idempotencyKey ?? `audit:${row.id}`;
+	const events = factsOf(row, origin);
+	return events.map((event, index) => ({
+		...event,
+		origin: {
+			...origin,
+			tx: {
+				id,
+				index,
+				count: events.length
+			}
+		}
+	}));
+}
+/** The events a row records, in order, or none for a kind this version doesn't know. */
+function factsOf(row, origin) {
+	if (row.kind === "change") return (0, _embedpdf_engine_core_runtime.changeEvents)(row.payload).map((event) => ({
+		...event,
+		origin
+	}));
+	if (row.kind === "annot.import") return (0, _embedpdf_engine_core_runtime.annotationImportFacts)(row.payload).map((fact) => ({
+		type: "annotations.created",
+		origin,
+		...fact
+	}));
+	if (row.kind === "form.import") return (0, _embedpdf_engine_core_runtime.formImportFacts)(row.payload).map((fact) => ({
+		type: "forms.created",
+		origin,
+		...fact
+	}));
+	if (row.kind === "form.importValues") return (0, _embedpdf_engine_core_runtime.formValuesImportFacts)(row.payload).map((fact) => ({
+		type: "forms.valueSet",
+		origin,
+		...fact
+	}));
+	if (row.kind === "form.reset") return (0, _embedpdf_engine_core_runtime.formResetFacts)(row.payload).map((fact) => ({
+		type: "forms.valueSet",
+		origin,
+		...fact
+	}));
+	if (row.kind === "signature.complete") {
+		const { signingId, ...result } = row.payload;
+		return [{
+			type: "signatures.completed",
+			origin,
+			signingId,
+			...result
+		}, {
+			type: "document.versioned",
+			origin,
+			version: result.version
+		}];
+	}
+	const event = eventOf(row, origin);
+	return event ? [event] : [];
+}
+/** The one event a single-fact row records, or `null` for a kind this version doesn't know. */
+function eventOf(row, origin) {
+	const rowPage = () => (0, _embedpdf_engine_core_runtime.toPageRef)(row.pageObjectNumber ?? row.affectedPages[0] ?? 0);
+	const affectedPages = () => row.affectedPages.map((pageObjectNumber) => (0, _embedpdf_engine_core_runtime.toPageRef)(pageObjectNumber));
 	switch (row.kind) {
 		case "measure.setScale": return {
-			type: "page.viewportsChanged",
+			type: "pages.scaleSet",
 			origin,
 			...row.payload
 		};
 		case "annot.create": return {
-			type: "annotation.created",
-			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			type: "annotations.created",
+			page: rowPage(),
 			origin,
 			...row.payload
 		};
 		case "annot.update": return {
-			type: "annotation.updated",
-			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			type: "annotations.updated",
+			page: rowPage(),
 			origin,
 			...row.payload
 		};
 		case "annot.delete": return {
-			type: "annotation.deleted",
-			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			type: "annotations.deleted",
+			page: rowPage(),
 			origin,
+			deleted: (0, _embedpdf_engine_core_runtime.deletedAnnotationsOf)(row.payload),
 			...row.payload
 		};
-		case "annot.move": return {
-			type: "annotation.moved",
-			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+		case "annot.reorder": return {
+			type: "annotations.reordered",
+			page: rowPage(),
 			origin,
 			...row.payload
 		};
-		case "pages.move": return {
-			type: "pages.moved",
-			pageObjectNumbers: row.affectedPages,
+		case "pages.reorder": return {
+			type: "pages.reordered",
 			origin,
 			...row.payload
 		};
 		case "pages.rotate": {
 			const payload = row.payload;
-			const rotation = payload.layout.pages.find((page) => page.pageObjectNumber === row.affectedPages[0])?.rotation ?? 0;
+			const rotation = payload.layout.pages.find((page) => page.ref.objectNumber === row.affectedPages[0])?.rotation ?? 0;
 			return {
 				type: "pages.rotated",
-				pageObjectNumbers: row.affectedPages,
+				pages: affectedPages(),
 				rotation,
 				origin,
 				...payload
@@ -1742,7 +2849,7 @@ function auditRowToEvent(row, mySessionId) {
 		}
 		case "pages.delete": return {
 			type: "pages.deleted",
-			pageObjectNumbers: row.affectedPages,
+			pages: affectedPages(),
 			origin,
 			...row.payload
 		};
@@ -1762,63 +2869,96 @@ function auditRowToEvent(row, mySessionId) {
 			origin,
 			...row.payload
 		};
-		case "attachment.create": return {
-			type: "attachment.created",
+		case "metadata.updateCustom": return {
+			type: "metadata.customUpdated",
 			origin,
 			...row.payload
 		};
-		case "attachment.delete": return {
-			type: "attachment.deleted",
+		case "attachment.create": return {
+			type: "attachments.created",
 			origin,
 			...row.payload
 		};
-		case "form.setValue":
-		case "form.reset": return {
-			type: "form.valueChanged",
+		case "attachment.delete": return {
+			type: "attachments.deleted",
 			origin,
+			deleted: (0, _embedpdf_engine_core_runtime.deletedAttachmentOf)(row.payload),
 			...row.payload
 		};
-		case "form.import": return {
-			type: "form.imported",
+		case "form.setValue": return {
+			type: "forms.valueSet",
 			origin,
 			...row.payload
 		};
 		case "form.repair": return {
-			type: "form.repaired",
+			type: "forms.repaired",
 			origin,
 			...row.payload
 		};
 		case "form.createField": return {
-			type: "form.fieldCreated",
+			type: "forms.created",
 			origin,
 			...row.payload
 		};
 		case "form.updateField":
 		case "form.setSignatureAppearance": return {
-			type: "form.fieldUpdated",
+			type: "forms.updated",
+			origin,
+			...row.payload
+		};
+		case "form.deleteField": {
+			const result = row.payload;
+			return {
+				type: "forms.deleted",
+				origin,
+				deleted: (0, _embedpdf_engine_core_runtime.deletedFieldOf)(result),
+				...result
+			};
+		}
+		case "form.addWidget": return {
+			type: "forms.widgetAdded",
 			origin,
 			...row.payload
 		};
-		case "form.deleteField": return {
-			type: "form.fieldDeleted",
+		case "form.detachWidget": return {
+			type: "forms.widgetRemoved",
 			origin,
 			...row.payload
 		};
-		case "form.attachWidget": return {
-			type: "form.widgetAttached",
+		case "form.updateWidget": return {
+			type: "forms.widgetUpdated",
 			origin,
 			...row.payload
 		};
-		case "form.detachWidget": return {
-			type: "form.widgetDetached",
+		case "form.deleteWidget": return {
+			type: "forms.widgetDeleted",
 			origin,
 			...row.payload
 		};
-		case "form.applyEffects": return {
-			type: "form.effectsApplied",
+		case "form.reorderWidgets": return {
+			type: "forms.widgetsReordered",
 			origin,
 			...row.payload
 		};
+		case "form.reorderCalculations": return {
+			type: "forms.calculationsReordered",
+			origin,
+			...row.payload
+		};
+		case "signature.prepare": {
+			const { field, ...wire } = row.payload;
+			return {
+				type: "signatures.prepared",
+				origin,
+				field,
+				...(0, _embedpdf_engine_core_wire.decodePrepared)(wire)
+			};
+		}
+		case "signature.cancel": return {
+			type: "signatures.cancelled",
+			origin,
+			signingId: row.payload.signingId
+		};
 		default: return null;
 	}
 }
@@ -1874,7 +3014,12 @@ var SseClient = class {
 				return;
 			}
 			if (!res.ok || !res.body) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Network, `events stream HTTP ${res.status}`);
-			await this.consume(res.body);
+			this.opts.onConnected?.(true);
+			try {
+				await this.consume(res.body);
+			} finally {
+				this.opts.onConnected?.(false);
+			}
 			if (Date.now() - startedAt >= 3e4) this.retryDelayMs = 500;
 		} catch {}
 		if (this.closed) return;
@@ -1911,7 +3056,11 @@ var SseClient = class {
 		if (event === "mutation") try {
 			this.opts.onRow(JSON.parse(data.join("\n")));
 		} catch {}
-		else if (event === "full-refresh") this.opts.onFullRefresh();
+		else if (event === "session") {
+			const parsed = safeJson(data.join("\n"));
+			const status = _embedpdf_engine_core_wire.EditSessionStatusSchema.safeParse(parsed);
+			if (status.success) this.opts.onSession?.(status.data);
+		} else if (event === "full-refresh") this.opts.onFullRefresh();
 		else if (event === "auth-revoked") {
 			this.closed = true;
 			this.abort?.abort();
@@ -1919,17 +3068,21 @@ var SseClient = class {
 		}
 	}
 };
+function safeJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
 //#endregion
 //#region src/document/CloudDocumentHandle.ts
 var CloudDocumentHandle = class {
-	constructor(http, id, layerName = _embedpdf_engine_core_wire.DEFAULT_LAYER_NAME, initialHead, initialToken = null, sessionId = `cloud:anon:${id}`) {
+	constructor(http, id, layerName = _embedpdf_engine_core_wire.DEFAULT_LAYER_NAME, initialHead, initialToken = null, onClose = () => {}) {
 		this.http = http;
 		this.layerName = layerName;
+		this.onClose = onClose;
 		_defineProperty(this, "id", void 0);
-		_defineProperty(this, "capabilities", {
-			weakAnnotationEditSessions: "required",
-			pageEditSessions: "unsupported"
-		});
 		_defineProperty(this, "metadata", void 0);
 		_defineProperty(this, "annotations", void 0);
 		_defineProperty(this, "actions", void 0);
@@ -1942,6 +3095,10 @@ var CloudDocumentHandle = class {
 		_defineProperty(this, "security", void 0);
 		_defineProperty(this, "render", void 0);
 		_defineProperty(this, "events", void 0);
+		_defineProperty(this, "objectNumbers", void 0);
+		_defineProperty(this, "pool", void 0);
+		_defineProperty(this, "writes", void 0);
+		_defineProperty(this, "changes", void 0);
 		_defineProperty(this, "publisher", void 0);
 		_defineProperty(this, "hub", void 0);
 		_defineProperty(this, "sessionId", void 0);
@@ -1953,11 +3110,20 @@ var CloudDocumentHandle = class {
 		_defineProperty(this, "manifestFloorVersion", 0);
 		_defineProperty(this, "pendingInitialHead", void 0);
 		_defineProperty(this, "manifestAccessor", void 0);
+		_defineProperty(this, "cloudSecurity", void 0);
 		this.id = id;
 		this.pendingInitialHead = initialHead ?? null;
-		const security = new CloudDocumentSecurityService(http, id, layerName, initialHead ?? fallbackUnknownHead(id), { isClosed: () => this.closed }, initialToken);
+		const pool = new CloudObjectNumberPool({ reserve: (count, signal) => http.postJson(_embedpdf_engine_core_wire.wirePaths.objectNumbers(id, layerName), { count }, (raw) => _embedpdf_engine_core_wire.ObjectNumberReservationResponseSchema.parse(raw), signal, { session: true }) });
+		this.pool = pool;
+		this.objectNumbers = pool;
+		this.writes = new CloudWrites(pool, changeSender(http, id, layerName));
+		const security = new CloudDocumentSecurityService(http, id, layerName, initialHead ?? fallbackUnknownHead(id), { isClosed: () => this.closed }, initialToken, {
+			wanted: () => pool.wantedAtAccess(),
+			opened: (edit) => pool.opened(edit)
+		});
 		this.security = security;
-		this.render = { policy: async () => {
+		this.cloudSecurity = security;
+		this.render = { getPolicy: () => _embedpdf_engine_core_runtime.AbortablePromise.run(async () => {
 			const advertised = (security.currentAccess ?? (await security.establishAccess()).access ?? null)?.renderPolicy;
 			if (!advertised) return _embedpdf_engine_core_runtime.CONTINUOUS_RENDER_POLICY;
 			return {
@@ -1970,52 +3136,71 @@ var CloudDocumentHandle = class {
 				background: advertised.background,
 				enforced: advertised.enforced
 			};
-		} };
-		const hub = new _embedpdf_engine_services.EventHub();
+		}) };
+		const hub = new _embedpdf_engine_core_runtime.EventHub();
 		this.hub = hub;
+		const sessionId = http.sessionId ?? `cloud:anon:${id}`;
 		this.sessionId = sessionId;
+		const subscribe = (listener) => {
+			const unsubscribe = hub.subscribe(listener);
+			this.retainRemoteStream();
+			let released = false;
+			return () => {
+				unsubscribe();
+				if (!released) {
+					released = true;
+					this.releaseRemoteStream();
+				}
+			};
+		};
 		this.events = {
-			subscribe: (listener) => {
-				const unsubscribe = hub.subscribe(listener);
-				this.retainRemoteStream();
-				let released = false;
-				return () => {
-					unsubscribe();
-					if (!released) {
-						released = true;
-						this.releaseRemoteStream();
-					}
-				};
-			},
+			subscribe,
+			on: (type, listener) => (0, _embedpdf_engine_core_runtime.subscribeToType)(subscribe, type, listener),
 			lastServerId: () => hub.lastServerId()
 		};
-		this.publisher = new _embedpdf_engine_services.SessionEventPublisher(hub, sessionId);
+		this.publisher = new _embedpdf_engine_core_runtime.SessionEventPublisher(hub, sessionId);
+		hub.subscribe((event) => {
+			if (event.type === "document.versioned") pool.versioned(event.version.sha256);
+		});
 		this.manifestAccessor = {
 			get: (signal) => this.getManifest(signal),
 			refresh: (signal) => this.refreshManifest(signal),
 			apply: (meta, owns) => this.absorbMutation(meta, owns),
-			applyPageStructure: (cache) => this.absorbPageStructure(cache),
-			applyPageDelete: (cache, deletedPages) => this.absorbPageDelete(cache, deletedPages),
-			applyPageInsert: (cache) => this.absorbPageInsert(cache),
-			applyMetadata: (cache) => this.absorbMetadata(cache),
-			applyAttachments: (cache) => this.absorbAttachments(cache)
+			applyPageDelete: (meta, deletedPages) => this.absorbPageDelete(meta, deletedPages),
+			applyPageInsert: (meta) => this.absorbPageInsert(meta)
 		};
-		this.metadata = new CloudMetadataService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
-		this.annotations = new CloudDocumentAnnotationsService(http, id, layerName, () => this.closed, this.manifestAccessor);
+		this.changes = new CloudDocumentChanges(() => this.closed, this.manifestAccessor, this.publisher, this.writes);
+		this.metadata = new CloudMetadataService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes);
+		const importLimits = async () => (security.currentAccess ?? (await security.establishAccess()).access)?.bundleLimits ?? _embedpdf_engine_core_runtime.DEFAULT_BUNDLE_LIMITS;
+		this.annotations = new CloudDocumentAnnotationsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes, importLimits);
 		this.actions = new CloudDocumentActionsService(http, id, layerName, () => this.closed, this.manifestAccessor);
-		this.attachments = new CloudDocumentAttachmentsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
-		this.signatures = new CloudDocumentSignaturesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
-		this.forms = new CloudDocumentFormsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
+		this.attachments = new CloudDocumentAttachmentsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes);
+		this.signatures = new CloudDocumentSignaturesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes);
+		this.forms = new CloudDocumentFormsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes, importLimits);
 		this.search = new CloudDocumentSearchService(http, id, layerName, () => this.closed, this.manifestAccessor);
-		this.pages = new CloudDocumentPagesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
-		this.redaction = new CloudDocumentRedactionService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
+		this.pages = new CloudDocumentPagesService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes);
+		this.redaction = new CloudDocumentRedactionService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes);
+	}
+	page(ref) {
+		return new CloudPageHandle(ref, this.http, this.id, this.layerName, () => this.closed, this.manifestAccessor, this.publisher, this.writes, (signal) => this.pages.pageLayout(ref, signal), () => this.cloudSecurity.pageLayerRights());
+	}
+	/**
+	* This handle: the cloud engine sends every call as it's made, in
+	* parallel, and the server runs them in arrival order, so a call's facts
+	* change nothing here.
+	*/
+	with(_facts) {
+		return this;
 	}
-	page(pageObjectNumber) {
-		return new CloudPageHandle(pageObjectNumber, -1, this.http, this.id, this.layerName, () => this.closed, this.manifestAccessor, this.publisher);
+	/** One change as one transaction, or the undo of one (see `DocumentHandle.apply`). */
+	apply(change, options) {
+		return this.changes.apply(change, options);
 	}
-	download(opts = {}) {
+	/** Ignored: the server learns what's needed from what is asked of it. */
+	setWorkingSet(_view, _pages) {}
+	download(options = {}) {
 		if (this.closed) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.DocNotOpen, `document ${this.id} is closed`));
-		const mode = opts.mode ?? _embedpdf_engine_core_runtime.DEFAULT_PDF_SAVE_MODE;
+		const mode = options.mode ?? _embedpdf_engine_core_runtime.DEFAULT_PDF_SAVE_MODE;
 		return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 			const buildPath = async () => {
 				const manifest = await this.getManifest(signal);
@@ -2034,6 +3219,20 @@ var CloudDocumentHandle = class {
 		});
 	}
 	/**
+	* Learn what the document's signatures forbid before the caller's first
+	* question: the manifest carries it, so `open()` fetches it up front and
+	* `security.allows()` answers as the server would from the start. A locked
+	* document, which the server won't describe yet, learns it from `unlock()`.
+	*/
+	async learnProtection(signal) {
+		try {
+			await this.getManifest(signal);
+		} catch (error) {
+			if (_embedpdf_engine_core_runtime.EngineError.is(error, _embedpdf_engine_core_runtime.EngineErrorCode.DocPasswordRequired)) return;
+			throw error;
+		}
+	}
+	/**
 	* Return the cached manifest, fetching cold-cache once if needed.
 	* Concurrent callers share a single inflight request (singleflight)
 	* so an N-page handle that opens N services in parallel still
@@ -2055,9 +3254,9 @@ var CloudDocumentHandle = class {
 		return awaitSignal(this.startManifestFetch({ allowInitialHead: false }), signal);
 	}
 	/**
-	* Monotone plane-scope flip: mark the planes a mutation OWNS as layer-scoped in
+	* Monotone plane-scope flip: mark the planes a mutation owns as layer-scoped in
 	* the cached manifest. Scopes only ever move base → layer (no revert op
-	* exists), so flipping is safe under ANY event ordering — a duplicate or
+	* exists), so flipping is safe under any event ordering — a duplicate or
 	* out-of-order event still proves the plane diverged at some point — and
 	* the manifest fetch stays the authoritative source (the 404 → refresh
 	* rail heals any miss, e.g. a future mutation kind this client doesn't
@@ -2088,17 +3287,10 @@ var CloudDocumentHandle = class {
 				return;
 			}
 		}
-		const byPageObjectNumber = new Map(this.manifestCache.pages.map((page) => [page.state.pageObjectNumber, page]));
-		for (const pageState of meta.affectedPages) {
-			const existing = byPageObjectNumber.get(pageState.pageObjectNumber);
-			if (existing) byPageObjectNumber.set(pageState.pageObjectNumber, {
-				...existing,
-				state: pageState
-			});
-		}
+		const byPageObjectNumber = new Map(this.manifestCache.pages.map((page) => [page.page.objectNumber, page]));
 		if (delta) for (const page of delta.pages) {
-			const existing = byPageObjectNumber.get(page.pageObjectNumber);
-			if (existing) byPageObjectNumber.set(page.pageObjectNumber, {
+			const existing = byPageObjectNumber.get(page.page.objectNumber);
+			if (existing) byPageObjectNumber.set(page.page.objectNumber, {
 				...existing,
 				cache: page.cache
 			});
@@ -2107,140 +3299,68 @@ var CloudDocumentHandle = class {
 			...this.manifestCache,
 			docVersion: delta?.docVersion ?? this.manifestCache.docVersion,
 			...delta?.annotationsVersion !== void 0 ? { annotationsVersion: delta.annotationsVersion } : {},
+			...delta?.formsVersion !== void 0 ? { formsVersion: delta.formsVersion } : {},
+			...delta?.layoutVersion !== void 0 ? { layoutVersion: delta.layoutVersion } : {},
+			...delta?.metadataVersion !== void 0 ? { metadataVersion: delta.metadataVersion } : {},
+			...delta?.attachmentsVersion !== void 0 ? { attachmentsVersion: delta.attachmentsVersion } : {},
 			...delta?.layerVersion !== void 0 ? { layerVersion: delta.layerVersion } : {},
 			...delta?.working !== void 0 ? { working: delta.working } : {},
-			pages: Array.from(byPageObjectNumber.values()).sort((a, b) => a.state.pageObjectNumber - b.state.pageObjectNumber)
-		};
-	}
-	/**
-	* Patch the cached manifest after a set-preserving page-structure op (move,
-	* rotate). Both are purely structural: they advance `docVersion` (so leaf
-	* URLs re-resolve) and `layoutVersion` (so the /layout leaf re-fetches),
-	* but leave every per-page pin untouched — a rotate renders the SAME
-	* normalized bitmaps, a move the same pages. We raise the floor
-	* unconditionally and, when our cache is exactly one version behind,
-	* advance it in place; otherwise we drop it and refetch lazily.
-	*/
-	absorbPageStructure(cache) {
-		this.flipScopes(["layout"]);
-		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
-		this.inflightManifest = null;
-		if (!this.manifestCache) return;
-		if (cache.docVersion <= this.manifestCache.docVersion) return;
-		if (cache.previousDocVersion !== this.manifestCache.docVersion) {
-			this.manifestCache = null;
-			return;
-		}
-		this.manifestCache = {
-			...this.manifestCache,
-			docVersion: cache.docVersion,
-			layoutVersion: cache.layoutVersion
+			pages: Array.from(byPageObjectNumber.values()).sort((a, b) => a.page.objectNumber - b.page.objectNumber)
 		};
 	}
 	/**
-	* Patch the cached manifest after a page delete: the shared structural
-	* advance plus dropping the deleted pages' manifest rows, so no leaf URL
-	* for a retired PON can be built from the cache (a stale request would
-	* 404 anyway — this keeps the failure local and instant).
+	* Patch the cached manifest after a page delete: the shared advance plus
+	* dropping the deleted pages' manifest rows, so no leaf URL for a retired
+	* page object number can be built from the cache (a stale request would
+	* 404 anyway — this keeps the failure local and instant). Delete changes
+	* the page set: a view that removed content must never resolve base
+	* artifacts again, so content, annotations and forms flip with layout.
 	*/
-	absorbPageDelete(cache, deletedPages) {
-		this.flipScopes([
+	absorbPageDelete(meta, deletedPages) {
+		this.absorbMutation(meta, [
 			"layout",
 			"content",
-			"annotations"
+			"annotations",
+			"forms"
 		]);
-		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
-		this.inflightManifest = null;
 		if (!this.manifestCache) return;
-		if (cache.docVersion <= this.manifestCache.docVersion) return;
-		if (cache.previousDocVersion !== this.manifestCache.docVersion) {
-			this.manifestCache = null;
-			return;
-		}
-		const deleted = new Set(deletedPages);
+		const deleted = new Set(deletedPages.map((page) => page.objectNumber));
 		this.manifestCache = {
 			...this.manifestCache,
-			docVersion: cache.docVersion,
-			layoutVersion: cache.layoutVersion,
-			pages: this.manifestCache.pages.filter((page) => !deleted.has(page.state.pageObjectNumber))
+			pages: this.manifestCache.pages.filter((page) => !deleted.has(page.page.objectNumber))
 		};
 	}
 	/**
 	* Patch bookkeeping after a page insert — the mirror of
 	* {@link absorbPageDelete}, with one asymmetry: delete can patch the
-	* cached manifest losslessly (it only REMOVES rows), but an insert needs
-	* manifest rows for the fresh PONs and the result doesn't carry them. So
-	* this absorb flips the planes (insert changes the page SET, so like
-	* delete it owns content + annotations alongside layout), raises the
-	* version floor, and DROPS the cache — the next read refetches a manifest
+	* cached manifest losslessly (it only removes rows), but an insert needs
+	* manifest rows for the fresh page object numbers and the result doesn't carry them. So
+	* this absorb flips the planes (insert changes the page set, so like
+	* delete it owns content, annotations and forms alongside layout), raises the
+	* version floor, and drops the cache — the next read refetches a manifest
 	* that includes the new pages' rows. The UI never waits on that refetch:
 	* the mutation result / event already carries the full new layout.
 	*/
-	absorbPageInsert(cache) {
+	absorbPageInsert(meta) {
 		this.flipScopes([
 			"layout",
 			"content",
-			"annotations"
+			"annotations",
+			"forms"
 		]);
-		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
+		if (meta.cacheDelta) this.manifestFloorVersion = Math.max(this.manifestFloorVersion, meta.cacheDelta.docVersion);
 		this.inflightManifest = null;
 		this.manifestCache = null;
 	}
-	/**
-	* Patch the cached manifest after a metadata write. Symmetric with
-	* {@link absorbPageMove}: a metadata edit advances `docVersion` (so leaf
-	* URLs re-resolve) and `metadataVersion` (so the /metadata leaf re-fetches),
-	* but leaves `layoutVersion` and every per-page pin untouched. Raise the
-	* floor unconditionally and, when our cache is exactly one version behind,
-	* advance it in place; otherwise drop it and refetch lazily.
-	*/
-	absorbMetadata(cache) {
-		this.flipScopes(["metadata"]);
-		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
-		this.inflightManifest = null;
-		if (!this.manifestCache) return;
-		if (cache.docVersion <= this.manifestCache.docVersion) return;
-		if (cache.previousDocVersion !== this.manifestCache.docVersion) {
-			this.manifestCache = null;
-			return;
-		}
-		this.manifestCache = {
-			...this.manifestCache,
-			docVersion: cache.docVersion,
-			metadataVersion: cache.metadataVersion
-		};
-	}
-	/**
-	* Patch the cached manifest after an attachment create/delete. Symmetric
-	* with {@link absorbMetadata}: an attachment write advances `docVersion`
-	* (so leaf URLs re-resolve) and `attachmentsVersion` (so the /attachments
-	* listing and /attachment-files leaves re-fetch), but leaves
-	* `layoutVersion` and every per-page pin untouched. Raise the floor
-	* unconditionally and, when our cache is exactly one version behind,
-	* advance it in place; otherwise drop it and refetch lazily.
-	*/
-	absorbAttachments(cache) {
-		this.flipScopes(["attachments"]);
-		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
-		this.inflightManifest = null;
-		if (!this.manifestCache) return;
-		if (cache.docVersion <= this.manifestCache.docVersion) return;
-		if (cache.previousDocVersion !== this.manifestCache.docVersion) {
-			this.manifestCache = null;
-			return;
-		}
-		this.manifestCache = {
-			...this.manifestCache,
-			docVersion: cache.docVersion,
-			attachmentsVersion: cache.attachmentsVersion
-		};
-	}
 	startManifestFetch(opts) {
 		const ctrl = new AbortController();
 		const promise = this.fetchManifest(ctrl.signal, opts);
 		this.inflightManifest = promise;
 		promise.then((manifest) => {
-			if (manifest.docVersion >= this.manifestFloorVersion && (!this.manifestCache || manifest.docVersion >= this.manifestCache.docVersion)) this.manifestCache = manifest;
+			if (manifest.docVersion >= this.manifestFloorVersion && (!this.manifestCache || manifest.docVersion >= this.manifestCache.docVersion)) {
+				this.manifestCache = manifest;
+				this.cloudSecurity.setProtection(manifest.protection);
+			}
 		}).catch(() => void 0).finally(() => {
 			if (this.inflightManifest === promise) this.inflightManifest = null;
 		});
@@ -2272,6 +3392,7 @@ var CloudDocumentHandle = class {
 		this.sseClient = null;
 		this.manifestCache = null;
 		this.inflightManifest = null;
+		this.onClose();
 		return _embedpdf_engine_core_runtime.AbortablePromise.resolveValue(void 0);
 	}
 	retainRemoteStream() {
@@ -2286,10 +3407,19 @@ var CloudDocumentHandle = class {
 					...this.manifestCache,
 					auditHead: row.id
 				};
-				const event = auditRowToEvent(row, this.sessionId);
-				if (!event) return;
-				this.absorbRemoteEvent(event);
-				this.hub.publish(event);
+				if (row.withheld) {
+					const meta = row.payload?.meta;
+					if (meta && row.originSessionId !== this.sessionId) this.absorbMutation(meta, ["annotations", "forms"]);
+					return;
+				}
+				if (row.kind === "signature.complete") {
+					const sha = row.payload.version?.sha256;
+					if (typeof sha === "string") this.pool.versioned(sha);
+				}
+				for (const event of auditRowToEvents(row, this.sessionId)) {
+					this.absorbRemoteEvent(event);
+					this.hub.publish(event);
+				}
 			},
 			onFullRefresh: () => {
 				this.manifestCache = null;
@@ -2302,7 +3432,9 @@ var CloudDocumentHandle = class {
 			},
 			onAuthLost: () => {
 				this.sseClient = null;
-			}
+			},
+			onSession: (status) => this.pool.sync(status),
+			onConnected: (connected) => this.pool.connected(connected)
 		});
 		this.sseClient.open();
 	}
@@ -2313,55 +3445,73 @@ var CloudDocumentHandle = class {
 			this.sseClient = null;
 		}
 	}
-	/** Patch the cached manifest from a REMOTE event's coherence pins — the
+	/** Patch the cached manifest from a remote event's coherence pins — the
 	*  same absorb rails local mutations use, so reads stay warm no matter
 	*  whose hand caused the change. */
 	absorbRemoteEvent(event) {
 		switch (event.type) {
-			case "page.viewportsChanged":
+			case "pages.scaleSet":
 				this.absorbMutation(event.meta, []);
 				return;
-			case "annotation.created":
-			case "annotation.updated":
-			case "annotation.deleted":
-			case "annotation.moved":
+			case "annotations.created":
+			case "annotations.updated":
+			case "annotations.deleted":
+			case "annotations.reordered":
 				this.absorbMutation(event.meta, ["annotations"]);
 				return;
-			case "pages.moved":
+			case "pages.reordered":
 			case "pages.rotated":
-				if (event.cache) this.absorbPageStructure(event.cache);
+			case "pages.named":
+				this.absorbMutation(event.meta, ["layout"]);
 				return;
 			case "pages.deleted":
-				if (event.cache) this.absorbPageDelete(event.cache, event.pageObjectNumbers);
+				this.absorbPageDelete(event.meta, event.pages);
 				return;
 			case "pages.inserted":
-				if (event.cache) this.absorbPageInsert(event.cache);
+				this.absorbPageInsert(event.meta);
 				return;
 			case "metadata.updated":
-				if (event.cache) this.absorbMetadata(event.cache);
-				return;
-			case "attachment.created":
-			case "attachment.deleted":
-				if (event.cache) this.absorbAttachments(event.cache);
+			case "metadata.customUpdated":
+				this.absorbMutation(event.meta, ["metadata"]);
 				return;
-			case "form.valueChanged":
-			case "form.imported":
-			case "form.repaired":
-			case "form.fieldCreated":
-			case "form.fieldUpdated":
-			case "form.fieldDeleted":
-			case "form.widgetAttached":
-			case "form.widgetDetached":
-				this.absorbMutation(event.meta, ["annotations"]);
+			case "attachments.created":
+			case "attachments.deleted":
+				this.absorbMutation(event.meta, ["attachments"]);
 				return;
-			case "form.effectsApplied":
-				if (event.meta) this.absorbMutation(event.meta, ["annotations"]);
+			case "forms.valueSet":
+			case "forms.repaired":
+			case "forms.created":
+			case "forms.updated":
+			case "forms.deleted":
+			case "forms.restored":
+			case "forms.widgetAdded":
+			case "forms.widgetRemoved":
+			case "forms.widgetUpdated":
+			case "forms.widgetDeleted":
+			case "forms.widgetRestored":
+			case "forms.widgetsReordered":
+			case "forms.calculationsReordered":
+				this.absorbMutation(event.meta, ["forms"]);
 				return;
 			case "pages.flattened":
-				if (event.meta) this.absorbMutation(event.meta, ["content", "annotations"]);
+			case "annotations.flattened":
+				this.absorbMutation(event.meta, [
+					"content",
+					"annotations",
+					"forms"
+				]);
+				return;
+			case "signatures.prepared":
+			case "document.versioned":
+				this.manifestCache = null;
+				this.inflightManifest = null;
 				return;
 			case "redaction.applied":
-				if (event.meta) this.absorbMutation(event.meta, ["content", "annotations"]);
+				this.absorbMutation(event.meta, [
+					"content",
+					"annotations",
+					"forms"
+				]);
 				return;
 		}
 	}
@@ -2392,22 +3542,6 @@ function fallbackUnknownHead(id) {
 		}
 	};
 }
-function awaitSignal(promise, signal) {
-	if (signal.aborted) return Promise.reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason));
-	return new Promise((resolve, reject) => {
-		const onAbort = () => {
-			reject(new _embedpdf_engine_core_runtime.AbortError(signal.reason));
-		};
-		signal.addEventListener("abort", onAbort, { once: true });
-		promise.then((value) => {
-			signal.removeEventListener("abort", onAbort);
-			resolve(value);
-		}, (reason) => {
-			signal.removeEventListener("abort", onAbort);
-			reject(reason);
-		});
-	});
-}
 //#endregion
 //#region src/share.ts
 /**
@@ -2491,8 +3625,11 @@ function shareSessionSource(baseUrl, shareToken, opts = {}) {
 }
 //#endregion
 //#region src/transport/HttpClient.ts
+/** CloudPDF SaaS: where an engine connects when it names no server of its own. */
+const CLOUDPDF_SAAS_URL = "https://engine.cloudpdf.com";
 var HttpClient = class HttpClient {
-	constructor(opts) {
+	constructor(options) {
+		this.options = options;
 		_defineProperty(this, "base", void 0);
 		_defineProperty(this, "tokenFn", void 0);
 		_defineProperty(this, "fetchFn", void 0);
@@ -2500,13 +3637,13 @@ var HttpClient = class HttpClient {
 		_defineProperty(this, "onRetry", void 0);
 		_defineProperty(this, "sessionId", void 0);
 		_defineProperty(this, "cdnBinding", null);
-		this.base = opts.baseUrl.replace(/\/$/, "");
-		const token = opts.token;
+		this.base = (options.baseUrl ?? "https://engine.cloudpdf.com").replace(/\/$/, "");
+		const token = options.token;
 		this.tokenFn = token === void 0 ? null : typeof token === "function" ? token : () => token;
-		this.sessionId = opts.sessionId ?? null;
-		this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
-		this.docAffinityHeader = opts.docAffinityHeader ?? true;
-		this.onRetry = opts.onRetry;
+		this.sessionId = options.sessionId ?? null;
+		this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+		this.docAffinityHeader = options.docAffinityHeader ?? true;
+		this.onRetry = options.onRetry;
 	}
 	/** Normalized server base URL (no trailing slash). */
 	get baseUrl() {
@@ -2522,18 +3659,17 @@ var HttpClient = class HttpClient {
 		return this.fetchFn;
 	}
 	/**
-	* Return a clone of this client bound to a different bearer. Used
-	* by `CloudEngine.open` to mint a per-handle client carrying the
-	* per-open token, so each opened document's RPCs go out under
-	* the right authorization without disturbing the engine-level
-	* token.
+	* A client for one open document: this client's settings, the document's
+	* own editing session, its own CDN binding, and `token` as its bearer
+	* when the open names one (else this client's). Two open documents never
+	* share object numbers, event echoes or a CDN binding, even two opens of
+	* the same document on one engine.
 	*/
-	withToken(token) {
+	forDocument({ sessionId, token }) {
 		return new HttpClient({
-			baseUrl: this.baseUrl,
-			token,
-			...this.sessionId ? { sessionId: this.sessionId } : {},
-			fetch: this.fetchFn
+			...this.options,
+			...token !== void 0 ? { token } : {},
+			sessionId
 		});
 	}
 	/**
@@ -2548,20 +3684,20 @@ var HttpClient = class HttpClient {
 				...headers
 			}),
 			signal
-		});
+		}, { session: true });
 	}
 	/**
 	* Install (or clear) the per-session CDN binding. Pass `null` to
 	* route everything to origin again — useful on session close or
 	* when an adapter swap happens mid-session (rare).
 	*
-	* The HttpClient stays dumb about WHEN to do this; the cloud
+	* The HttpClient stays dumb about when to do this; the cloud
 	* document handle pushes the binding in after /access succeeds.
 	*
 	* Side effect: in the browser, signedCookies are written to
 	* `document.cookie` once per setCdnAccess call so the CDN edge
-	* receives them on subsequent fetches. Node side ignores cookies
-	* for now (cookie jar wiring deferred until needed for tests).
+	* receives them on subsequent fetches. Outside the browser signed
+	* cookies are ignored: this client keeps no cookie jar.
 	*/
 	setCdnAccess(binding) {
 		this.cdnBinding = binding;
@@ -2716,29 +3852,43 @@ var HttpClient = class HttpClient {
 			return await this.getFile(retryPath, signal);
 		}
 	}
-	async postMultipartJson(path, body, parser, signal) {
+	async postMultipartJson(path, body, parser, signal, options = {}) {
 		const res = await this.request(path, {
 			method: "POST",
 			body,
 			signal
-		});
+		}, options);
 		return await this.parseJsonResponse(res, parser);
 	}
 	/** PATCH counterpart of {@link postMultipartJson} (binary-carrying mutations). */
-	async patchMultipartJson(path, body, parser, signal) {
+	async patchMultipartJson(path, body, parser, signal, options = {}) {
 		const res = await this.request(path, {
 			method: "PATCH",
 			body,
 			signal
-		});
+		}, options);
 		return await this.parseJsonResponse(res, parser);
 	}
-	async postJson(path, body, parser, signal) {
-		const res = await this.requestJson(path, "POST", body, signal);
+	async postJson(path, body, parser, signal, options = {}) {
+		const res = await this.requestJson(path, "POST", body, signal, options);
 		return await this.parseJsonResponse(res, parser);
 	}
-	async putJson(path, body, parser, signal) {
-		return this.parseJsonResponse(await this.requestJson(path, "PUT", body, signal), parser);
+	async putJson(path, body, parser, signal, options = {}) {
+		return this.parseJsonResponse(await this.requestJson(path, "PUT", body, signal, options), parser);
+	}
+	/** POST a JSON body and parse a `multipart/form-data` response (a large annotation export). */
+	async postJsonFormData(path, body, signal) {
+		const res = await this.request(path, {
+			method: "POST",
+			body: JSON.stringify(body),
+			headers: new Headers({
+				"Content-Type": "application/json",
+				Accept: "multipart/form-data"
+			}),
+			signal
+		});
+		if (!res.ok) await this.throwFromBody(res);
+		return await res.formData();
 	}
 	/** POST a JSON body and return the raw binary response (pages.extract). */
 	async postJsonBytes(path, body, signal) {
@@ -2747,7 +3897,7 @@ var HttpClient = class HttpClient {
 		return new Uint8Array(await res.arrayBuffer());
 	}
 	/** POST a raw binary body (FDF/XFDF import) and parse the JSON response. */
-	async postBytesJson(path, bytes, contentType, parser, signal) {
+	async postBytesJson(path, bytes, contentType, parser, signal, options = {}) {
 		const headers = new Headers({ "Content-Type": contentType });
 		const body = new Uint8Array(bytes).buffer;
 		const res = await this.request(path, {
@@ -2755,61 +3905,73 @@ var HttpClient = class HttpClient {
 			body,
 			headers,
 			signal
-		});
+		}, options);
 		return await this.parseJsonResponse(res, parser);
 	}
-	async patchJson(path, body, parser, signal) {
-		const res = await this.requestJson(path, "PATCH", body, signal);
+	async patchJson(path, body, parser, signal, options = {}) {
+		const res = await this.requestJson(path, "PATCH", body, signal, options);
 		return await this.parseJsonResponse(res, parser);
 	}
-	async deleteJson(path, parser, signal) {
+	async deleteJson(path, parser, signal, options = {}) {
 		const res = await this.request(path, {
 			method: "DELETE",
 			signal
-		});
+		}, options);
 		return await this.parseJsonResponse(res, parser);
 	}
-	async deleteEmpty(path, signal) {
-		const res = await this.request(path, {
-			method: "DELETE",
-			signal
-		});
-		if (res.status === 204) return;
-		if (!res.ok) await this.throwFromBody(res);
-	}
-	async postEmpty(path, body, signal) {
-		const res = await this.requestJson(path, "POST", body, signal);
-		if (res.status === 204) return;
-		if (!res.ok) await this.throwFromBody(res);
-	}
-	requestJson(path, method, body, signal) {
+	requestJson(path, method, body, signal, options = {}) {
 		const headers = new Headers({ "Content-Type": "application/json" });
 		return this.request(path, {
 			method,
 			body: JSON.stringify(body ?? {}),
 			headers,
 			signal
-		});
+		}, options);
 	}
-	async request(path, init) {
-		const { url, extraHeader, routedToCdn } = this.resolveOutgoing(path);
+	async request(path, init, options = {}) {
+		const { url, extraHeader, routedToCdn } = this.resolveOutgoing(path, init.method ?? "GET");
 		const headers = new Headers(init.headers ?? {});
 		if (this.tokenFn) {
 			const token = await this.tokenFn();
 			headers.set("Authorization", `Bearer ${token}`);
 		}
 		if (!headers.has("Accept")) headers.set("Accept", "application/json");
-		if (this.sessionId) headers.set("X-Engine-Session-Id", this.sessionId);
+		const { write } = options;
+		if (this.sessionId && (write || options.session)) headers.set("X-Engine-Session-Id", this.sessionId);
+		if (write) {
+			if (write.opId !== void 0) headers.set("Idempotency-Key", write.opId);
+			if (write.reserveObjectNumbers && write.reserveObjectNumbers > 0) headers.set("EmbedPDF-Reserve-Object-Numbers", String(write.reserveObjectNumbers));
+		}
 		if (extraHeader) headers.set(extraHeader.name, extraHeader.value);
 		if (this.docAffinityHeader && !routedToCdn) {
 			const doc = /^\/v1\/docs\/([^/]+)\//.exec(path);
 			if (doc) headers.set("X-CloudPDF-Doc", decodeURIComponent(doc[1]));
 		}
-		for (let attempt = 0;; attempt++) {
-			const res = await this.execute(url, {
-				...init,
-				headers
-			});
+		for (let attempt = 0, networkFailures = 0;; attempt++) {
+			let res;
+			try {
+				res = await this.execute(url, {
+					...init,
+					headers
+				});
+			} catch (err) {
+				const wait = HttpClient.NETWORK_RETRY_MS[networkFailures];
+				if (!write || wait === void 0 || !_embedpdf_engine_core_runtime.EngineError.is(err, _embedpdf_engine_core_runtime.EngineErrorCode.Network) || isStreamBody(init.body ?? null)) throw err;
+				networkFailures++;
+				const waitMs = wait * (.9 + .2 * Math.random());
+				this.onRetry?.({
+					path,
+					code: _embedpdf_engine_core_runtime.EngineErrorCode.Network,
+					attempt,
+					waitMs
+				});
+				await sleepRacingAbort(waitMs, init.signal ?? null);
+				continue;
+			}
+			if (res.ok && write?.onObjectNumbers) {
+				const ranges = (0, _embedpdf_engine_core_runtime.parseObjectNumberRanges)(res.headers.get("EmbedPDF-Object-Numbers"));
+				if (ranges.length > 0) write.onObjectNumbers(ranges);
+			}
 			if (res.status !== 503 || attempt >= HttpClient.MAX_RETRIES || isStreamBody(init.body ?? null)) return res;
 			const code = await peekErrorCode(res);
 			if (code === null || !RETRYABLE_503.has(code)) return res;
@@ -2844,13 +4006,15 @@ var HttpClient = class HttpClient {
 	}
 	/**
 	* Decide where this request actually goes. With no CDN binding (or
-	* binding's `cdn` is null) every request stays on origin. Otherwise
+	* binding's `cdn` is null) every request stays on origin, and so does
+	* every request that isn't a read (`GET`, `HEAD`): a write must reach the
+	* server itself, whatever read its path looks like. Otherwise
 	* `applyCdnAccess` decides per-request based on the resource the
 	* path resolves to (and whether the caller's scope granted CDN
 	* access to it).
 	*/
-	resolveOutgoing(path) {
-		if (!this.cdnBinding || !this.cdnBinding.cdn) return {
+	resolveOutgoing(path, method) {
+		if (!(method === "GET" || method === "HEAD") || !this.cdnBinding || !this.cdnBinding.cdn) return {
 			url: `${this.baseUrl}${path}`,
 			extraHeader: null,
 			routedToCdn: false
@@ -2888,11 +4052,17 @@ var HttpClient = class HttpClient {
 _defineProperty(HttpClient, "MAX_RETRIES", 2);
 _defineProperty(HttpClient, "RETRY_AFTER_CAP_MS", 5e3);
 _defineProperty(HttpClient, "RETRY_AFTER_DEFAULT_MS", 1e3);
+_defineProperty(HttpClient, "NETWORK_RETRY_MS", [
+	250,
+	1e3,
+	3e3
+]);
 function mapStatusToCode(status) {
 	if (status === 401) return _embedpdf_engine_core_runtime.EngineErrorCode.Unauthenticated;
 	if (status === 403) return _embedpdf_engine_core_runtime.EngineErrorCode.Forbidden;
-	if (status === 409) return _embedpdf_engine_core_runtime.EngineErrorCode.WeakAnnotationSessionConflict;
+	if (status === 409) return _embedpdf_engine_core_runtime.EngineErrorCode.LayerVersionConflict;
 	if (status === 404) return _embedpdf_engine_core_runtime.EngineErrorCode.NotFound;
+	if (status === 413) return _embedpdf_engine_core_runtime.EngineErrorCode.PayloadTooLarge;
 	if (status === 422) return _embedpdf_engine_core_runtime.EngineErrorCode.DocOpenFailed;
 	if (status === 499) return _embedpdf_engine_core_runtime.EngineErrorCode.Aborted;
 	if (status === 400) return _embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg;
@@ -2941,22 +4111,19 @@ function sleepRacingAbort(ms, signal) {
 */
 var CloudEngine = class CloudEngine {
 	static fromOptions(opts) {
-		const sessionId = `cloud:${(0, _embedpdf_engine_services.generateUuid)()}`;
-		return new CloudEngine(new HttpClient({
-			...opts,
-			sessionId
-		}), sessionId);
+		return new CloudEngine(new HttpClient(opts));
 	}
-	constructor(http, sessionId) {
+	constructor(http) {
 		this.http = http;
-		this.sessionId = sessionId;
+		_defineProperty(this, "canOpenFiles", false);
 		_defineProperty(this, "destroyed", false);
+		_defineProperty(this, "handles", /* @__PURE__ */ new Set());
 	}
 	open(input, options) {
 		if (this.destroyed) return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.RuntimeUnavailable, "engine destroyed"));
 		options?.scope;
 		options?.identity;
-		const effectivePassword = options && "password" in options ? options.password ?? null : input.password ?? null;
+		const effectivePassword = options?.password ?? null;
 		if (input.kind === "share") {
 			const raw = shareSessionSource(this.http.baseUrl, input.shareToken, {
 				...input.sharePassword !== void 0 ? { password: input.sharePassword } : {},
@@ -2971,28 +4138,39 @@ var CloudEngine = class CloudEngine {
 			};
 			return this.open({
 				kind: "token",
-				token,
-				password: input.password ?? null
+				token
 			}, options);
 		}
 		if (input.kind === "token") {
 			const tokenSource = input.token;
 			return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
-				const docHttp = this.http.withToken(tokenSource);
+				const docHttp = this.http.forDocument({
+					sessionId: newSessionId(),
+					token: tokenSource
+				});
 				const token = await docHttp.currentToken();
 				const claims = decodeUnverifiedClaims(token);
 				const docId = claims.doc_id;
 				if (typeof docId !== "string" || docId.length === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "cloud engine: token has no doc_id claim — mint a doc-scoped JWT");
 				const layerName = typeof claims.layer_name === "string" && claims.layer_name.length > 0 ? claims.layer_name : _embedpdf_engine_core_wire.DEFAULT_LAYER_NAME;
 				const head = await docHttp.getJson(_embedpdf_engine_core_wire.wirePaths.layerHead(docId, layerName), (raw) => _embedpdf_engine_core_wire.DocumentHeadSchema.parse(raw), signal);
-				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, token, this.sessionId);
-				await maybeAutoEstablishAccess(handle, head, signal, effectivePassword);
+				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, token, () => this.handles.delete(handle));
+				this.handles.add(handle);
+				try {
+					await establishOnOpen(handle, head, signal, effectivePassword, false);
+				} catch (error) {
+					await handle.close();
+					throw error;
+				}
 				return handle;
 			});
 		}
 		if (input.kind === "id") {
 			const id = input.id;
-			const docHttp = input.token ? this.http.withToken(input.token) : this.http;
+			const docHttp = this.http.forDocument({
+				sessionId: newSessionId(),
+				...input.token ? { token: input.token } : {}
+			});
 			return _embedpdf_engine_core_runtime.AbortablePromise.run(async (signal) => {
 				let layerName = input.layerName ?? _embedpdf_engine_core_wire.DEFAULT_LAYER_NAME;
 				let resolvedToken = null;
@@ -3006,46 +4184,97 @@ var CloudEngine = class CloudEngine {
 					if (typeof claims.layer_name === "string" && claims.layer_name.length > 0) layerName = claims.layer_name;
 				}
 				const head = await docHttp.getJson(_embedpdf_engine_core_wire.wirePaths.layerHead(id, layerName), (raw) => _embedpdf_engine_core_wire.DocumentHeadSchema.parse(raw), signal);
-				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, resolvedToken, this.sessionId);
-				await maybeAutoEstablishAccess(handle, head, signal, effectivePassword);
+				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, resolvedToken, () => this.handles.delete(handle));
+				this.handles.add(handle);
+				const tenant = resolvedToken !== null && typeof decodeUnverifiedClaims(resolvedToken).doc_id !== "string";
+				try {
+					await establishOnOpen(handle, head, signal, effectivePassword, tenant);
+				} catch (error) {
+					await handle.close();
+					throw error;
+				}
 				return handle;
 			});
 		}
 		return _embedpdf_engine_core_runtime.AbortablePromise.rejectReason(new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, `cloud engine supports OpenInput.kind === 'token', 'id', or 'share' (got '${input.kind}')`));
 	}
+	/**
+	* Close every document this engine opened (their event streams stop), then
+	* refuse new opens. As on the local engine, a handle is unusable after.
+	*/
 	destroy() {
 		if (this.destroyed) return _embedpdf_engine_core_runtime.AbortablePromise.resolveValue(void 0);
 		this.destroyed = true;
-		return _embedpdf_engine_core_runtime.AbortablePromise.resolveValue(void 0);
+		const open = [...this.handles];
+		this.handles.clear();
+		return _embedpdf_engine_core_runtime.AbortablePromise.run(async () => {
+			await Promise.all(open.map((handle) => handle.close()));
+		});
 	}
 };
 /**
+* A session id for a document being opened. Every open is its own session,
+* even a second open of the same document on this engine. The id stamps the
+* document's own events' origins and travels as `X-Engine-Session-Id`: the
+* server keeps the session's object numbers under it and marks its audit
+* rows with it, so the document's stream drops its own echoes and hears
+* every other open as remote.
+*/
+function newSessionId() {
+	return `cloud:${(0, _embedpdf_engine_core_runtime.generateUuid)()}`;
+}
+/**
+* What `open()` learns before handing the document over: access when the
+* password or a CDN needs it (see {@link maybeAutoEstablishAccess}), then
+* what the document's signatures forbid (the manifest). A caller that may
+* create objects calls `/access` anyway, beside the manifest fetch, for its
+* editing session's first object numbers; on a document locked by a
+* password, `unlock()` brings them. A failed `/access` doesn't fail the
+* open: creates then go without numbers until the pool gets some.
+*/
+async function establishOnOpen(handle, head, signal, password, tenant) {
+	const accessed = await maybeAutoEstablishAccess(handle, head, signal, password);
+	const security = handle.security;
+	const locked = !accessed && head.access.reasons.includes("password");
+	await Promise.all([!accessed && !locked && (tenant || mayCreateObjects(security)) ? settleLinked(security.establishAccess(), signal) : void 0, handle.learnProtection(signal)]);
+}
+/**
+* Whether the caller may make new objects (annotations as itself, pages,
+* form fields): the server's own test for handing out object numbers, from
+* what the client knows before `/access`.
+*/
+function mayCreateObjects(security) {
+	return security.allowsAnnotation("create") || security.allows("doc.pages.assemble") || security.allows("doc.forms.modify");
+}
+/**
 * Post-/head access establishment, in two layers:
 *
-* 1. **Supplied password** — a password given at open is always TRIED
+* 1. **Supplied password** — a password given at open is always tried
 *    (PDFium parity: the local engine feeds it to the loader no matter
 *    what). Two triggers, because `/head` only carries the `password`
-*    reason when a password is needed to READ:
+*    reason when a password is needed to read:
 *      - `reasons` has `'password'` → required-to-read case
 *      - `head.permissions.canUpgradeToOwner` → permission-only encrypted
 *        doc; the password can still upgrade to owner. Skipping this arm
-*        would silently drop supplied OWNER passwords — and diverge from
+*        would silently drop supplied owner passwords — and diverge from
 *        the local engine on identical input.
 *    Outcomes follow "a password failure may only block what the password
 *    was needed for": a rejection in the required case leaves the handle
-*    locked (the caller's prompt takes over, showing "incorrect"); in the
+*    locked (the prompt says `incorrect`, as on the local engine); in the
 *    upgrade case the document stays readable and the failure is
 *    non-fatal. The one /access POST also installs the CDN binding, so a
 *    successful unlock covers the `password + cdn` combined case.
 *
 * 2. **CDN-only** — unchanged: `/access` without a password, transparently.
-*    A required password with NO supplied password never auto-calls; the
+*    A required password with no supplied password never auto-calls; the
 *    dev prompts and `unlock()` runs the same POST.
 *
 * Non-password /access failures never break `open()` (the first real
 * request still tries origin, where the JWT check produces a regular
 * Forbidden) — but they are also never mistaken for a wrong password:
 * only a DocPasswordRequired/Incorrect rejection means "wrong password".
+*
+* Returns whether `/access` answered.
 */
 async function maybeAutoEstablishAccess(handle, head, signal, password) {
 	const reasons = new Set(head.access.reasons);
@@ -3054,13 +4283,13 @@ async function maybeAutoEstablishAccess(handle, head, signal, password) {
 		if (await settleLinked(security.unlock({
 			password,
 			mode: "any"
-		}), signal)) return;
-		if (reasons.has("password")) return;
+		}), signal)) return true;
+		if (reasons.has("password")) return false;
 	}
-	if (!head.access.required) return;
-	if (reasons.has("password")) return;
-	if (!reasons.has("cdn")) return;
-	await settleLinked(security.establishAccess(), signal);
+	if (!head.access.required) return false;
+	if (reasons.has("password")) return false;
+	if (!reasons.has("cdn")) return false;
+	return settleLinked(security.establishAccess(), signal);
 }
 /** Await an /access attempt with open()-abort linkage. Returns whether it
 *  succeeded; failures are contained (see maybeAutoEstablishAccess). */
@@ -3079,9 +4308,6 @@ async function settleLinked(pending, signal) {
 }
 //#endregion
 //#region src/index.ts
-function createCloudEngine(opts) {
-	return CloudEngine.fromOptions(opts);
-}
 /**
 * Create a cloud {@link CloudEngine} — the drop-in counterpart of
 * `localEngine()`, so swapping local for cloud is a one-import change.
@@ -3093,59 +4319,46 @@ function createCloudEngine(opts) {
 * to let a `<Viewer>` own the lifetime instead.
 *
 * Note the deliberate asymmetry with `localEngine()`: there is no `fonts`
-* option. Fallback fonts are a SERVER policy on the cloud (`Engine.fonts` is
+* option. Fallback fonts are a server policy on the cloud (`Engine.fonts` is
 * `undefined` cloud-side), so they cannot be configured from the client. This
 * is the local-vs-cloud split, surfaced in the API.
 *
+* Without a `baseUrl` it connects to CloudPDF SaaS; your own server names itself:
+*
 * ```ts
-* const engine = cloudEngine({ baseUrl: 'https://pdf.example.com', token });
+* const engine = cloudEngine();                                    // CloudPDF SaaS
+* const own = cloudEngine({ baseUrl: 'https://pdf.example.com' }); // your @cloudpdf/server
 * <Viewer engine={engine} plugins={[stagePlugin(), renderPlugin()]} />
 * ```
 */
-function cloudEngine(opts) {
+function cloudEngine(opts = {}) {
 	return CloudEngine.fromOptions(opts);
 }
 //#endregion
-Object.defineProperty(exports, "AbortError", {
-	enumerable: true,
-	get: function() {
-		return _embedpdf_engine_core_runtime.AbortError;
-	}
-});
-Object.defineProperty(exports, "AbortablePromise", {
-	enumerable: true,
-	get: function() {
-		return _embedpdf_engine_core_runtime.AbortablePromise;
-	}
-});
+exports.CLOUDPDF_SAAS_URL = CLOUDPDF_SAAS_URL;
 exports.CloudDocumentAnnotationsService = CloudDocumentAnnotationsService;
 exports.CloudDocumentHandle = CloudDocumentHandle;
 exports.CloudDocumentPagesService = CloudDocumentPagesService;
 exports.CloudEngine = CloudEngine;
 exports.CloudMetadataService = CloudMetadataService;
 exports.CloudPageAnnotationsService = CloudPageAnnotationsService;
-exports.CloudPageGeometryService = CloudPageGeometryService;
 exports.CloudPageHandle = CloudPageHandle;
 exports.CloudPageRenderService = CloudPageRenderService;
-Object.defineProperty(exports, "EngineError", {
-	enumerable: true,
-	get: function() {
-		return _embedpdf_engine_core_runtime.EngineError;
-	}
-});
-Object.defineProperty(exports, "EngineErrorCode", {
-	enumerable: true,
-	get: function() {
-		return _embedpdf_engine_core_runtime.EngineErrorCode;
-	}
-});
 exports.HttpClient = HttpClient;
 exports.ShareExchangeError = ShareExchangeError;
 exports.cloudEngine = cloudEngine;
-exports.createCloudEngine = createCloudEngine;
 exports.decodeUnverifiedClaims = decodeUnverifiedClaims;
 exports.engineErrorFromShareExchange = engineErrorFromShareExchange;
 exports.exchangeShareToken = exchangeShareToken;
 exports.shareSessionSource = shareSessionSource;
+var _embedpdf_engine_core_public = require("@embedpdf/engine-core/public");
+Object.keys(_embedpdf_engine_core_public).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _embedpdf_engine_core_public[k];
+		}
+	});
+});
 
 //# sourceMappingURL=index.cjs.map