@cloudpdf/engine 3.0.0-next.0

package/dist/index.js

@@ -0,0 +1,2476 @@
+import { AbortError, AbortError as AbortError$1, AbortablePromise, AbortablePromise as AbortablePromise$1, CONTINUOUS_RENDER_POLICY, DEFAULT_PDF_SAVE_MODE, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineErrorCode as EngineErrorCode$1, canonicalSearchQuery, checkCapability, createPageImageHandle, decodePdfBits, encodeFieldRefKey, encodeStableIdKey, expandRawScope, normalizeAnnotationDraft, normalizeAnnotationPatch, normalizeAttachmentFileSource, passwordPromptFromState, searchContentEpoch, securityStateFromHead } from "@embedpdf/engine-core/runtime";
+import { AccessResponseSchema, AnnotationAppearanceManifestSchema, AnnotationCreateResultSchema, AnnotationDeleteResultSchema, AnnotationListPageSnapshotSchema, AnnotationMoveResultSchema, AnnotationUpdateResultSchema, AttachmentCreateResultSchema, AttachmentDeleteResultSchema, DEFAULT_LAYER_NAME, DocumentActionsSnapshotSchema, DocumentHeadSchema, DocumentManifestSchema, DocumentMetadataSchema, EmbeddedFileItemSchema, EngineErrorPayloadSchema, FormEffectsResultSchema, FormFieldCreateResultSchema, FormFieldDTOSchema, FormFieldDeleteResultSchema, FormFieldUpdateResultSchema, FormImportResultSchema, FormRepairResultSchema, FormSetValueResultSchema, FormSnapshotSchema, FormWidgetLinkResultSchema, MetadataUpdateResultSchema, PageDeleteResultSchema, PageFlattenResultSchema, PageGeometrySnapshotSchema, PageListSnapshotSchema, PageMoveResultSchema, PageRotateResultSchema, PageTextSnapshotSchema, RedactionApplyResultSchema, SearchSliceSchema, WeakAnnotationSessionResponseSchema, annotationAppearancesImageOptionsToWire, applyCdnAccess, decodeSearchToken, decodeTokenText, encodeSearchToken, renderImageOptionsToWire, wirePaths } from "@embedpdf/engine-core/wire";
+import { EventHub, SessionEventPublisher, generateUuid } from "@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 it depends on is inherited (`'base'`) by this layer. One owned plane
+* → the layer-scoped path.
+*
+* Absent `scopes` (base manifests never carry it; pre-plane servers omit
+* it) means layer paths — never wrong, only unshared.
+*/
+function planesInherited(manifest, planes) {
+	const scopes = manifest.scopes;
+	if (!scopes) return false;
+	return planes.every((plane) => scopes[plane] === "base");
+}
+//#endregion
+//#region src/document/CloudDocumentActionsService.ts
+var CloudDocumentActionsService = class {
+	constructor(http, docId, layerName, isClosed, manifest) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	read() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run((signal) => this.http.getJsonWithRefresh(async (currentSignal) => {
+			const manifest = await this.manifest.get(currentSignal);
+			return planesInherited(manifest, ["actions"]) ? wirePaths.docActions(this.docId, manifest.actionsVersion) : wirePaths.layerActions(this.docId, this.layerName, manifest.actionsVersion);
+		}, (raw) => DocumentActionsSnapshotSchema.parse(raw), async (currentSignal) => {
+			await this.manifest.refresh(currentSignal);
+		}, signal));
+	}
+};
+//#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.");
+	}
+	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/CloudDocumentAnnotationsService.ts
+var CloudDocumentAnnotationsService = class {
+	constructor(http, docId, layerName, isClosed, manifest) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	listRawAll() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const manifest = await this.manifest.get(signal);
+			return { pages: await Promise.all(manifest.pages.map((page) => this.readCurrentPage(page.state.pageObjectNumber, signal))) };
+		});
+	}
+	listRaw(pageObjectNumber) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run((signal) => this.readCurrentPage(pageObjectNumber, signal));
+	}
+	beginWeakEdit(pageObjectNumbers) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const response = await this.http.postJson(wirePaths.layerWeakAnnotationSession(this.docId, this.layerName), { pageObjectNumbers }, (raw) => WeakAnnotationSessionResponseSchema.parse(raw), signal);
+			return new CloudWeakAnnotationEditSession(this.http, this.docId, this.layerName, () => this.isClosed(), response);
+		});
+	}
+	async readCurrentPage(pageObjectNumber, signal) {
+		return this.http.getJson(wirePaths.layerPageAnnotationsCurrent(this.docId, this.layerName, pageObjectNumber), (raw) => AnnotationListPageSnapshotSchema.parse(raw), signal);
+	}
+};
+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 AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `weak annotation session ${this.id} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			this.response = await this.http.postJson(wirePaths.layerWeakAnnotationSessionPages(this.docId, this.layerName, this.id), { pageObjectNumbers }, (raw) => WeakAnnotationSessionResponseSchema.parse(raw), signal);
+		});
+	}
+	heartbeat() {
+		if (this.isClosed() || this.released) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `weak annotation session ${this.id} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			this.response = await this.http.postJson(wirePaths.layerWeakAnnotationSessionHeartbeat(this.docId, this.layerName, this.id), {}, (raw) => WeakAnnotationSessionResponseSchema.parse(raw), signal);
+		});
+	}
+	release() {
+		if (this.released) return AbortablePromise$1.resolveValue(void 0);
+		this.released = true;
+		return AbortablePromise$1.run((signal) => this.http.deleteEmpty(wirePaths.layerWeakAnnotationSessionRelease(this.docId, this.layerName, this.id), signal));
+	}
+};
+//#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.
+*/
+function buildMutationForm(body, resources) {
+	const form = new FormData();
+	form.append("body", JSON.stringify(body));
+	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;
+}
+//#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";
+/**
+* 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.
+*/
+function parseAttachmentContent(file) {
+	const encodedName = file.headers.get(FILE_NAME_HEADER);
+	if (encodedName === null) throw new EngineError$1(EngineErrorCode$1.WireFormat, `attachment response missing ${FILE_NAME_HEADER} header`);
+	let name;
+	try {
+		name = decodeTokenText(encodedName);
+	} catch (err) {
+		throw new EngineError$1(EngineErrorCode$1.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 } : {}
+	};
+}
+//#endregion
+//#region src/document/CloudDocumentAttachmentsService.ts
+/** The `/attachments@…` listing leaf is a bare array of name-tree entries. */
+const EmbeddedFileListSchema = EmbeddedFileItemSchema.array();
+/**
+* Cloud-side document-level attachments (the catalog's `/EmbeddedFiles`
+* name tree). Reads use immutable leaves pinned by the manifest's
+* `attachmentsVersion`: `/attachments@…` for the metadata listing and
+* `/attachment-files/…@…` for one file's decoded bytes — a separate
+* capability tier, so a CDN credential for the listing can never egress
+* content. Mutations use unversioned collection/member URLs and are
+* never cached.
+*/
+var CloudDocumentAttachmentsService = 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;
+	}
+	/**
+	* Snapshot of the name tree, in tree (key-sorted) order. Pulls
+	* `attachmentsVersion` from the cached manifest and, on a 404 (stale
+	* pointer), transparently refreshes the manifest and retries once.
+	* The pin bumps only on attachment writes, so this leaf stays cached
+	* across page and annotation edits.
+	*/
+	list() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async (s) => {
+				const manifest = await this.manifest.get(s);
+				return planesInherited(manifest, ["attachments"]) ? wirePaths.docAttachments(this.docId, manifest.attachmentsVersion) : wirePaths.layerAttachments(this.docId, this.layerName, manifest.attachmentsVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => EmbeddedFileListSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+	/**
+	* Decode and return one embedded file's bytes. The body is the decoded
+	* stream; the name and mime type ride as response headers (see
+	* `parseAttachmentContent`). Same versioned-leaf + refresh-retry rails
+	* as {@link list}.
+	*/
+	download(ref) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async (s) => {
+				const manifest = await this.manifest.get(s);
+				return planesInherited(manifest, ["attachments"]) ? wirePaths.docAttachmentFile(this.docId, ref.key, manifest.attachmentsVersion) : wirePaths.layerAttachmentFile(this.docId, this.layerName, ref.key, manifest.attachmentsVersion);
+			};
+			return parseAttachmentContent(await this.http.getFileWithRefresh(buildPath, async (s) => {
+				await this.manifest.refresh(s);
+			}, signal));
+		});
+	}
+	/**
+	* 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(file) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const { wireFile, resource } = await normalizeAttachmentFileSource(file, "r0");
+			const result = await this.http.postMultipartJson(wirePaths.layerAttachmentsCollection(this.docId, this.layerName), buildMutationForm(wireFile, { r0: resource }), (raw) => AttachmentCreateResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyAttachments(result.cache);
+			this.publisher.publishLocal({
+				type: "attachment.created",
+				...result
+			});
+			return result;
+		});
+	}
+	/** Delete an embedded file from the name tree by its durable key. */
+	delete(ref) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.deleteJson(wirePaths.layerAttachmentItem(this.docId, this.layerName, ref.key), (raw) => AttachmentDeleteResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyAttachments(result.cache);
+			this.publisher.publishLocal({
+				type: "attachment.deleted",
+				...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"
+};
+/**
+* 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.
+*/
+var CloudDocumentFormsService = 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;
+	}
+	list() {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run((signal) => this.http.getJson(wirePaths.layerForm(this.docId, this.layerName), (raw) => FormSnapshotSchema.parse(raw), signal));
+	}
+	get(ref) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run((signal) => this.http.getJson(wirePaths.layerFormFieldByKey(this.docId, this.layerName, encodeFieldRefKey(ref)), (raw) => FormFieldDTOSchema.parse(raw), signal));
+	}
+	setValue(ref, value) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormFieldValue(this.docId, this.layerName, encodeFieldRefKey(ref)), { value }, (raw) => FormSetValueResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.valueChanged");
+		});
+	}
+	reset(ref) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormFieldReset(this.docId, this.layerName, encodeFieldRefKey(ref)), {}, (raw) => FormSetValueResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.valueChanged");
+		});
+	}
+	applyEffects(effects) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormEffects(this.docId, this.layerName), { effects }, (raw) => FormEffectsResultSchema.parse(raw), signal);
+			if (result.meta === null) return result;
+			this.manifest.apply(result.meta, ["annotations"]);
+			this.publisher.publishLocal({
+				type: "form.effectsApplied",
+				...result
+			});
+			return result;
+		});
+	}
+	exportData(format = "xfdf") {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			return {
+				format,
+				bytes: await this.http.getBytes(wirePaths.layerFormData(this.docId, this.layerName, format), signal)
+			};
+		});
+	}
+	importData(data, format) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postBytesJson(wirePaths.layerFormData(this.docId, this.layerName, format), bytes, format ? IMPORT_CONTENT_TYPE[format] : "application/octet-stream", (raw) => FormImportResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.imported");
+		});
+	}
+	createField(draft) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormFields(this.docId, this.layerName), draft, (raw) => FormFieldCreateResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.fieldCreated");
+		});
+	}
+	updateField(ref, patch) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.patchJson(wirePaths.layerFormFieldByKey(this.docId, this.layerName, encodeFieldRefKey(ref)), patch, (raw) => FormFieldUpdateResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.fieldUpdated");
+		});
+	}
+	deleteField(ref) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.deleteJson(wirePaths.layerFormFieldByKey(this.docId, this.layerName, encodeFieldRefKey(ref)), (raw) => FormFieldDeleteResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.fieldDeleted");
+		});
+	}
+	attachWidget(ref, widget, options) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		const onState = options?.onState;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormFieldWidgets(this.docId, this.layerName, encodeFieldRefKey(ref)), {
+				widget,
+				...onState ? { onState } : {}
+			}, (raw) => FormWidgetLinkResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.widgetAttached");
+		});
+	}
+	detachWidget(ref, widget) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormFieldWidgetsDetach(this.docId, this.layerName, encodeFieldRefKey(ref)), { widget }, (raw) => FormWidgetLinkResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.widgetDetached");
+		});
+	}
+	repair(options) {
+		const rejected = this.rejectIfClosed();
+		if (rejected) return rejected;
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerFormRepair(this.docId, this.layerName), { bakeAppearances: options?.bakeAppearances ?? false }, (raw) => FormRepairResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "form.repaired");
+		});
+	}
+	rejectIfClosed() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return null;
+	}
+	/**
+	* Patch the cached manifest, then publish the mutation to the document's
+	* 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({
+			type,
+			...result
+		});
+		return result;
+	}
+};
+//#endregion
+//#region src/document/CloudDocumentPagesService.ts
+/**
+* Cloud-side document pages service. Mirrors `LocalDocumentPagesService`
+* over HTTP: GET /pages for `list`, POST /pages/move 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`.
+*/
+var CloudDocumentPagesService = 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;
+	}
+	/**
+	* Page-geometry list. The geometry bytes live at the content-addressed
+	* `/layout@layoutVersion=N` leaf (not in the manifest); the manifest only
+	* publishes the `layoutVersion` pointer. So `list()` reads `layoutVersion`
+	* from the cached manifest, fetches the layout leaf, and on a 404 (stale
+	* pointer) transparently refreshes the manifest and retries once — the
+	* same ladder the per-page text/geometry reads use. `layoutVersion` bumps
+	* only on structural page ops, so this leaf stays cached across content
+	* and annotation edits.
+	*/
+	list() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async (s) => {
+				const manifest = await this.manifest.get(s);
+				return planesInherited(manifest, ["layout"]) ? wirePaths.docLayout(this.docId, manifest.layoutVersion) : wirePaths.layerLayout(this.docId, this.layerName, manifest.layoutVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => PageListSnapshotSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+	move(pageObjectNumbers, destIndex) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerPagesMove(this.docId, this.layerName), {
+				pageObjectNumbers,
+				destIndex
+			}, (raw) => PageMoveResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageStructure(result.cache);
+			this.publisher.publishLocal({
+				type: "pages.moved",
+				pageObjectNumbers,
+				destIndex,
+				...result
+			});
+			return result;
+		});
+	}
+	rotate(pageObjectNumbers, rotation) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerPagesRotate(this.docId, this.layerName), {
+				pageObjectNumbers,
+				rotation
+			}, (raw) => PageRotateResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageStructure(result.cache);
+			this.publisher.publishLocal({
+				type: "pages.rotated",
+				pageObjectNumbers,
+				rotation,
+				...result
+			});
+			return result;
+		});
+	}
+	delete(pageObjectNumbers) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerPagesDelete(this.docId, this.layerName), { pageObjectNumbers }, (raw) => PageDeleteResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageDelete(result.cache, pageObjectNumbers);
+			this.publisher.publishLocal({
+				type: "pages.deleted",
+				pageObjectNumbers,
+				...result
+			});
+			return result;
+		});
+	}
+	flatten(pageObjectNumbers, usage = "display") {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerPagesFlatten(this.docId, this.layerName), {
+				pageObjectNumbers,
+				usage
+			}, (raw) => PageFlattenResultSchema.parse(raw), signal);
+			if (result.meta === null) return result;
+			this.manifest.apply(result.meta, ["content", "annotations"]);
+			this.publisher.publishLocal({
+				type: "pages.flattened",
+				...result
+			});
+			return result;
+		});
+	}
+};
+//#endregion
+//#region src/document/CloudDocumentRedactionService.ts
+/**
+* Cloud-side redaction apply. Mirrors `LocalDocumentRedactionService` over
+* 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.
+*/
+var CloudDocumentRedactionService = 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;
+	}
+	apply(scope) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerRedactionsApply(this.docId, this.layerName), { scope }, (raw) => RedactionApplyResultSchema.parse(raw), signal);
+			if (result.meta === null) return result;
+			this.manifest.apply(result.meta, ["content", "annotations"]);
+			this.publisher.publishLocal({
+				type: "redaction.applied",
+				...result
+			});
+			return result;
+		});
+	}
+};
+//#endregion
+//#region src/document/CloudDocumentSearchService.ts
+/**
+* Cloud search transport: versioned GETs, one per budgeted slice.
+*
+* 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
+* 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
+* once; a continuation answered `NotFound` means the document changed
+* mid-search → `InvalidArg`, same contract as the local engine's cursor.
+*/
+var CloudDocumentSearchService = class {
+	constructor(http, docId, layerName, isClosed, manifest) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	query(request) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document not open: ${this.docId}`));
+		return AbortablePromise$1.run(async (signal) => {
+			const path = (request.mode ?? "full") === "rects" ? wirePaths.layerSearchRects : wirePaths.layerSearchFull;
+			const get = (token) => this.http.getJson(path(this.docId, this.layerName, token), (raw) => SearchSliceSchema.parse(raw), signal);
+			const query = canonicalSearchQuery(request.query);
+			if (request.cursor !== void 0) {
+				let token;
+				try {
+					token = decodeSearchToken(request.cursor);
+				} catch {
+					throw new EngineError$1(EngineErrorCode$1.InvalidArg, "malformed search cursor");
+				}
+				if (queryIdentity(token.query) !== queryIdentity(query)) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "search cursor belongs to a different query — restart the search");
+				if (request.startPage !== void 0 && request.startPage !== token.startPage) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "startPage conflicts with the cursor — omit startPage when resuming");
+				try {
+					return await get(request.cursor);
+				} catch (err) {
+					if (EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "document changed since this search cursor was issued — restart the search");
+					throw err;
+				}
+			}
+			const mint = (epoch) => encodeSearchToken({
+				epoch,
+				query,
+				...request.startPage !== void 0 ? { startPage: request.startPage } : {},
+				skip: 0,
+				...request.budget !== void 0 ? { budget: request.budget } : {}
+			});
+			try {
+				return await get(mint(searchContentEpoch(await this.manifest.get(signal))));
+			} catch (err) {
+				if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+				return await get(mint(searchContentEpoch(await this.manifest.refresh(signal))));
+			}
+		});
+	}
+};
+/** Query identity for cursor validation (option order pinned by hand). */
+function queryIdentity(query) {
+	return JSON.stringify([
+		query.regex ? "r" : "l",
+		query.text,
+		query.matchCase ? 1 : 0,
+		query.matchDiacritics ? 1 : 0,
+		query.wholeWord ? 1 : 0
+	]);
+}
+//#endregion
+//#region src/transport/decodeUnverifiedClaims.ts
+function decodeUnverifiedClaims(token) {
+	const parts = token.split(".");
+	if (parts.length !== 3) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "malformed jwt: expected 3 segments");
+	const payloadB64Url = parts[1];
+	let bytes;
+	try {
+		bytes = base64UrlDecode(payloadB64Url);
+	} catch (err) {
+		throw new EngineError$1(EngineErrorCode$1.InvalidArg, `malformed jwt payload: ${err.message ?? err}`);
+	}
+	let json;
+	try {
+		json = new TextDecoder().decode(bytes);
+	} catch (err) {
+		throw new EngineError$1(EngineErrorCode$1.InvalidArg, `jwt payload is not valid utf-8: ${err.message ?? err}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch (err) {
+		throw new EngineError$1(EngineErrorCode$1.InvalidArg, `jwt payload is not valid json: ${err.message ?? err}`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "jwt payload must be a json object");
+	return parsed;
+}
+/**
+* Decode a base64url string into a `Uint8Array`. Works in both Node
+* and modern browsers; we avoid `Buffer` so the SDK stays
+* browser-friendly. `atob` lives on the global in Node 16+ as well.
+*/
+function base64UrlDecode(b64url) {
+	const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+	const pad = b64.length % 4;
+	const padded = pad === 0 ? b64 : b64 + "=".repeat(4 - pad);
+	const bin = atob(padded);
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+//#endregion
+//#region src/document/CloudDocumentSecurityService.ts
+var CloudDocumentSecurityService = class {
+	constructor(http, docId, layerName, initialHead, view, initialToken = null) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.view = view;
+		_defineProperty(this, "state", void 0);
+		_defineProperty(this, "access", null);
+		_defineProperty(this, "tokenScope", void 0);
+		_defineProperty(this, "tokenIdentity", void 0);
+		this.state = securityStateFromHead(initialHead);
+		const claims = initialToken ? safeDecodeClaims(initialToken) : null;
+		this.tokenScope = Array.isArray(claims?.scope) ? claims.scope : [];
+		this.tokenIdentity = claims ? identityFromClaims(claims) : null;
+	}
+	get current() {
+		return this.state;
+	}
+	get currentAccess() {
+		return this.access;
+	}
+	/**
+	* 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
+	* matches across engines bit-for-bit on the same inputs.
+	*/
+	get effectiveScope() {
+		if (this.access) return this.access.effectiveScope;
+		const bits = decodePdfBits(this.state.permissions.bits);
+		return Array.from(expandRawScope(this.tokenScope, bits)).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.
+	*/
+	allows(cap) {
+		if (this.access?.effectiveScope.includes(cap)) return true;
+		const bits = decodePdfBits(this.state.permissions.bits);
+		return checkCapability(cap, this.tokenScope, bits);
+	}
+	/**
+	* Identity of the current caller, or null when anonymous.
+	*
+	* Cloud-canonical post-/access; otherwise the identity claims from
+	* the JWT itself. Both are the same shape — the post-/access
+	* version is just refreshed to reflect any server-side identity
+	* augmentation (rare; reserved for future tenant hooks).
+	*/
+	get identity() {
+		return this.access?.identity ?? this.tokenIdentity;
+	}
+	/**
+	* High-level "should I prompt for a password?" — single source of
+	* truth, computed via `passwordPromptFromState` so the answer is
+	* identical to what the local engine would say for the same
+	* security state. See `passwordPromptFromState` for the rules.
+	*/
+	get passwordPrompt() {
+		return passwordPromptFromState(this.state);
+	}
+	unlock(input) {
+		if (this.view.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			return await this.postAccess(signal, {
+				password: input.password,
+				mode: input.mode ?? "any"
+			});
+		});
+	}
+	/**
+	* 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' —
+	* the server accepts an authenticated /access POST without a
+	* password and returns the signed-URL block.
+	*
+	* Not on the public `DocumentSecurityService` interface — the
+	* "unlock" verb implies user action, and this path is automatic.
+	* Local engine has no equivalent (there's no CDN concept).
+	*/
+	establishAccess() {
+		if (this.view.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			return await this.postAccess(signal, { mode: "any" });
+		});
+	}
+	/**
+	* Single POST /v1/access implementation shared by `unlock()` (with
+	* 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`.
+	*
+	* `none` CDN adapter → the access block has null overrides/policies
+	* and `applyCdnAccess` short-circuits to origin; safe to call always.
+	*/
+	async postAccess(signal, body) {
+		const response = await this.http.postJson(wirePaths.access, {
+			docId: this.docId,
+			layerName: this.layerName,
+			...body.password ? { password: body.password } : {},
+			mode: body.mode
+		}, (raw) => AccessResponseSchema.parse(raw), signal);
+		this.state = response.security;
+		this.access = {
+			cdn: response.cdn,
+			passwordGrant: response.passwordGrant,
+			pdfPermissions: response.pdfPermissions,
+			scope: response.scope,
+			effectiveScope: response.effectiveScope,
+			identity: response.identity,
+			originPasswordPolicy: response.originPasswordPolicy,
+			expiresAt: response.expiresAt,
+			...response.renderPolicy ? { renderPolicy: response.renderPolicy } : {}
+		};
+		this.http.setCdnAccess({
+			cdn: response.cdn,
+			docId: this.docId,
+			layerName: this.layerName
+		});
+		return {
+			security: this.state,
+			access: this.access ?? void 0
+		};
+	}
+};
+/**
+* Decode the JWT's payload without verifying. The SDK never verifies
+* tokens client-side — the server is the verifier of record — but it
+* needs the `scope` and identity claims for the local-fallback path
+* of `effectiveScope` / `identity`. Returns null if the token is
+* malformed; the security service treats that as "no claims known".
+*/
+function safeDecodeClaims(token) {
+	try {
+		return decodeUnverifiedClaims(token);
+	} catch {
+		return null;
+	}
+}
+function identityFromClaims(claims) {
+	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;
+	}
+	return Object.keys(out).length > 0 ? out : null;
+}
+//#endregion
+//#region src/document/CloudMetadataService.ts
+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;
+	}
+	/**
+	* 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 AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async (s) => {
+				const manifest = await this.manifest.get(s);
+				return planesInherited(manifest, ["metadata"]) ? wirePaths.docMetadata(this.docId, manifest.metadataVersion) : wirePaths.layerMetadata(this.docId, this.layerName, manifest.metadataVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => DocumentMetadataSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+	update(patch) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(wirePaths.layerMetadataUpdate(this.docId, this.layerName), patch, (raw) => MetadataUpdateResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyMetadata(result.cache);
+			this.publisher.publishLocal({
+				type: "metadata.updated",
+				...result
+			});
+			return result;
+		});
+	}
+};
+//#endregion
+//#region src/document/CloudPageAnnotationsService.ts
+/**
+* Cloud-side page annotation 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.
+*
+* Reads use immutable versioned layer URLs discovered from the
+* manifest. Mutations use unversioned layer URLs and are never cached.
+*/
+var CloudPageAnnotationsService = class {
+	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest, publisher) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.pageObjectNumber = pageObjectNumber;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+		this.publisher = publisher;
+	}
+	list() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.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 EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				return planesInherited(manifest, ["annotations"]) ? wirePaths.docPageAnnotations(this.docId, this.pageObjectNumber, page.cache.annotationVersion) : wirePaths.layerPageAnnotations(this.docId, this.layerName, this.pageObjectNumber, page.cache.annotationVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => AnnotationListPageSnapshotSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+	renderAppearances(_options) {
+		return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.NotImplemented, "annotations.renderAppearances() raw rasters are not available in the cloud engine; use renderAppearanceImages()"));
+	}
+	renderAppearanceImages(options = {}) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			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 EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				const wireToken = annotationAppearancesImageOptionsToWire({
+					...options,
+					format
+				}, { annotationVersion: page.cache.annotationVersion });
+				return planesInherited(manifest, ["annotations"]) ? wirePaths.docPageAnnotationAppearances(this.docId, this.pageObjectNumber, wireToken) : wirePaths.layerPageAnnotationAppearances(this.docId, this.layerName, this.pageObjectNumber, wireToken);
+			};
+			return parseAppearanceForm(await this.http.getFormDataWithRefresh(buildPath, async (s) => {
+				await this.manifest.refresh(s);
+			}, signal));
+		});
+	}
+	/**
+	* 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.
+	*/
+	downloadFile(ref) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		if (ref.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
+		if (ref.kind === "index") return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, "downloadFile requires a stable ref (objectNumber or nm); index refs cannot address the content-addressed file leaf"));
+		const annotKey = encodeStableIdKey(refToStableId(ref));
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async (s) => {
+				const manifest = await this.manifest.get(s);
+				return planesInherited(manifest, ["annotations", "attachments"]) ? wirePaths.docAnnotationFile(this.docId, this.pageObjectNumber, annotKey, manifest.attachmentsVersion) : wirePaths.layerAnnotationFile(this.docId, this.layerName, this.pageObjectNumber, annotKey, manifest.attachmentsVersion);
+			};
+			return parseAttachmentContent(await this.http.getFileWithRefresh(buildPath, async (s) => {
+				await this.manifest.refresh(s);
+			}, signal));
+		});
+	}
+	create(draft) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const { wire, resources } = await normalizeAnnotationDraft(draft);
+			const path = wirePaths.layerPageAnnotationsCreate(this.docId, this.layerName, this.pageObjectNumber);
+			const parse = (raw) => 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");
+		});
+	}
+	update(ref, patch) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		if (ref.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
+		if (ref.kind === "index") {
+			const path = wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, "index");
+			return AbortablePromise$1.run(async (signal) => {
+				const { wire, resources } = await normalizeAnnotationPatch(patch);
+				const result = await this.patchMutation(path, {
+					ref,
+					patch: wire
+				}, resources, signal);
+				return this.absorbMutation(result, "annotation.updated");
+			});
+		}
+		const stableKey = encodeStableIdKey(refToStableId(ref));
+		const path = wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, stableKey);
+		return AbortablePromise$1.run(async (signal) => {
+			const { wire, resources } = await normalizeAnnotationPatch(patch);
+			const result = await this.patchMutation(path, { patch: wire }, resources, signal);
+			return this.absorbMutation(result, "annotation.updated");
+		});
+	}
+	/** PATCH as plain JSON, or as multipart when the patch carried binaries. */
+	patchMutation(path, body, resources, signal) {
+		const parse = (raw) => AnnotationUpdateResultSchema.parse(raw);
+		if (hasResources(resources)) return this.http.patchMultipartJson(path, buildMutationForm(body, resources), parse, signal);
+		return this.http.patchJson(path, body, parse, signal);
+	}
+	delete(ref) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		if (ref.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `ref.pageObjectNumber ${ref.pageObjectNumber} != page ${this.pageObjectNumber}`));
+		if (ref.kind === "index") {
+			const path = wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, "index");
+			return AbortablePromise$1.run(async (signal) => {
+				const result = await this.http.patchJson(path, {
+					ref,
+					op: "delete"
+				}, (raw) => AnnotationDeleteResultSchema.parse(raw), signal);
+				return this.absorbMutation(result, "annotation.deleted");
+			});
+		}
+		const stableKey = encodeStableIdKey(refToStableId(ref));
+		const path = wirePaths.layerAnnotationByKey(this.docId, this.layerName, ref.pageObjectNumber, stableKey);
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.deleteJson(path, (raw) => AnnotationDeleteResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "annotation.deleted");
+		});
+	}
+	move(refs, toIndex) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		for (const r of refs) if (r.pageObjectNumber !== this.pageObjectNumber) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `move ref points at page ${r.pageObjectNumber}; service is bound to page ${this.pageObjectNumber}`));
+		const path = wirePaths.layerPageAnnotationsMove(this.docId, this.layerName, this.pageObjectNumber);
+		return AbortablePromise$1.run(async (signal) => {
+			const result = await this.http.postJson(path, {
+				refs,
+				toIndex
+			}, (raw) => AnnotationMoveResultSchema.parse(raw), signal);
+			return this.absorbMutation(result, "annotation.moved");
+		});
+	}
+	/**
+	* Patch the cached manifest, then publish the mutation to the document's
+	* event stream (in that order — listeners reading the manifest in their
+	* callback must see post-mutation state). Each call site pairs the event
+	* `type` with the matching result by construction; the cast localizes that
+	* pairing here instead of widening every site.
+	*/
+	absorbMutation(result, type) {
+		this.manifest.apply(result.meta, ["annotations"]);
+		this.publisher.publishLocal({
+			type,
+			pageObjectNumber: this.pageObjectNumber,
+			...result
+		});
+		return result;
+	}
+};
+/**
+* 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 EngineError$1(EngineErrorCode$1.WireFormat, "appearance response missing JSON manifest part");
+	let parsedJson;
+	try {
+		parsedJson = JSON.parse(manifestRaw);
+	} catch (err) {
+		throw new EngineError$1(EngineErrorCode$1.WireFormat, `appearance manifest is not valid JSON: ${err?.message ?? err}`);
+	}
+	const manifest = 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 EngineError$1(EngineErrorCode$1.WireFormat, `appearance response missing image part "${entry.part}"`);
+		const blob = partValue;
+		const bytes = new Uint8Array(await blob.arrayBuffer());
+		const image = 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.
+*/
+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) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.pageObjectNumber = pageObjectNumber;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	read() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.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 EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				return planesInherited(manifest, ["content"]) ? wirePaths.docPageGeometry(this.docId, this.pageObjectNumber, page.cache.contentVersion) : wirePaths.layerPageGeometry(this.docId, this.layerName, this.pageObjectNumber, page.cache.contentVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => PageGeometrySnapshotSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+};
+//#endregion
+//#region src/document/CloudPageRenderService.ts
+var CloudPageRenderService = class {
+	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.pageObjectNumber = pageObjectNumber;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	image(options = {}) {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.run(async (signal) => {
+			const format = normalizeFormat(options.format);
+			const includeAnnotations = options.includeAnnotations ?? 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 EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				const wireToken = renderImageOptionsToWire({
+					...options,
+					format
+				}, {
+					contentVersion: page.cache.contentVersion,
+					...includeAnnotations ? { annotationVersion: page.cache.annotationVersion } : {}
+				});
+				if (includeAnnotations) return planesInherited(manifest, ["content", "annotations"]) ? wirePaths.docPageRenderAnnotated(this.docId, this.pageObjectNumber, wireToken) : wirePaths.layerPageRenderAnnotated(this.docId, this.layerName, this.pageObjectNumber, wireToken);
+				return planesInherited(manifest, ["content"]) ? wirePaths.docPageRender(this.docId, this.pageObjectNumber, wireToken) : wirePaths.layerPageRender(this.docId, this.layerName, this.pageObjectNumber, wireToken);
+			};
+			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 AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.NotImplemented, "render.raw() is not available in the cloud engine; use render.image()"));
+	}
+};
+function createCloudPageImageHandle(result, http, buildPath, onStaleVersion) {
+	return createPageImageHandle(result, { blob: (signal) => http.getBlobWithRefresh(buildPath, onStaleVersion, signal ?? new AbortController().signal) });
+}
+function normalizeFormat(format) {
+	if (format === void 0) return "webp";
+	if (format === "png" || format === "webp") return format;
+	throw new EngineError$1(EngineErrorCode$1.InvalidArg, `cloud render.image() supports only "png" and "webp" (got "${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.
+*/
+var CloudPageTextService = class {
+	constructor(http, docId, layerName, pageObjectNumber, isClosed, manifest) {
+		this.http = http;
+		this.docId = docId;
+		this.layerName = layerName;
+		this.pageObjectNumber = pageObjectNumber;
+		this.isClosed = isClosed;
+		this.manifest = manifest;
+	}
+	read() {
+		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
+		return AbortablePromise$1.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 EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${this.pageObjectNumber} in document ${this.docId}`);
+				return planesInherited(manifest, ["content"]) ? wirePaths.docPageText(this.docId, this.pageObjectNumber, page.cache.contentVersion) : wirePaths.layerPageText(this.docId, this.layerName, this.pageObjectNumber, page.cache.contentVersion);
+			};
+			return this.http.getJsonWithRefresh(buildPath, (raw) => PageTextSnapshotSchema.parse(raw), async (s) => {
+				await this.manifest.refresh(s);
+			}, signal);
+		});
+	}
+};
+//#endregion
+//#region src/document/CloudPageHandle.ts
+var CloudPageHandle = class {
+	constructor(pageObjectNumber, pageIndex, http, docId, layerName, isClosed, manifest, publisher) {
+		this.pageObjectNumber = pageObjectNumber;
+		this.pageIndex = pageIndex;
+		_defineProperty(this, "annotations", void 0);
+		_defineProperty(this, "text", void 0);
+		_defineProperty(this, "geometry", void 0);
+		_defineProperty(this, "render", void 0);
+		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);
+	}
+};
+//#endregion
+//#region src/realtime/auditRowToEvent.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).
+*
+* 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`).
+*/
+function auditRowToEvent(row, mySessionId) {
+	if (row.originSessionId === mySessionId) return null;
+	const origin = {
+		kind: "remote",
+		sessionId: row.originSessionId ?? `unknown:${row.sub}`,
+		sub: row.sub,
+		ts: row.ts,
+		serverId: row.id
+	};
+	switch (row.kind) {
+		case "annot.create": return {
+			type: "annotation.created",
+			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			origin,
+			...row.payload
+		};
+		case "annot.update": return {
+			type: "annotation.updated",
+			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			origin,
+			...row.payload
+		};
+		case "annot.delete": return {
+			type: "annotation.deleted",
+			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			origin,
+			...row.payload
+		};
+		case "annot.move": return {
+			type: "annotation.moved",
+			pageObjectNumber: row.pageObjectNumber ?? row.affectedPages[0] ?? 0,
+			origin,
+			...row.payload
+		};
+		case "pages.move": return {
+			type: "pages.moved",
+			pageObjectNumbers: row.affectedPages,
+			origin,
+			...row.payload
+		};
+		case "pages.rotate": {
+			const payload = row.payload;
+			const rotation = payload.layout.pages.find((page) => page.pageObjectNumber === row.affectedPages[0])?.rotation ?? 0;
+			return {
+				type: "pages.rotated",
+				pageObjectNumbers: row.affectedPages,
+				rotation,
+				origin,
+				...payload
+			};
+		}
+		case "pages.delete": return {
+			type: "pages.deleted",
+			pageObjectNumbers: row.affectedPages,
+			origin,
+			...row.payload
+		};
+		case "pages.flatten": return {
+			type: "pages.flattened",
+			origin,
+			...row.payload
+		};
+		case "metadata.update": return {
+			type: "metadata.updated",
+			origin,
+			...row.payload
+		};
+		case "attachment.create": return {
+			type: "attachment.created",
+			origin,
+			...row.payload
+		};
+		case "attachment.delete": return {
+			type: "attachment.deleted",
+			origin,
+			...row.payload
+		};
+		case "form.setValue":
+		case "form.reset": return {
+			type: "form.valueChanged",
+			origin,
+			...row.payload
+		};
+		case "form.import": return {
+			type: "form.imported",
+			origin,
+			...row.payload
+		};
+		case "form.repair": return {
+			type: "form.repaired",
+			origin,
+			...row.payload
+		};
+		case "form.createField": return {
+			type: "form.fieldCreated",
+			origin,
+			...row.payload
+		};
+		case "form.updateField": return {
+			type: "form.fieldUpdated",
+			origin,
+			...row.payload
+		};
+		case "form.deleteField": return {
+			type: "form.fieldDeleted",
+			origin,
+			...row.payload
+		};
+		case "form.attachWidget": return {
+			type: "form.widgetAttached",
+			origin,
+			...row.payload
+		};
+		case "form.detachWidget": return {
+			type: "form.widgetDetached",
+			origin,
+			...row.payload
+		};
+		case "form.applyEffects": return {
+			type: "form.effectsApplied",
+			origin,
+			...row.payload
+		};
+		default: return null;
+	}
+}
+//#endregion
+//#region src/realtime/SseClient.ts
+/**
+* Fetch-based SSE consumer. Browser-native `EventSource` cannot send an
+* `Authorization` header, so the stream rides the same `HttpClient` as
+* every other request (same token provider, same session header).
+*
+* Resilience model: the cursor is the only state that matters. Every
+* (re)connect sends `Last-Event-ID: cursor`; the server replays the gap
+* from the audit log. So a dropped stream costs latency, never events —
+* the client needs no buffering and no acknowledgements.
+*
+*   - network drop / server close / `auth-expiring` → reconnect with
+*     jittered exponential backoff (500ms → 30s; reset after a stream
+*     that lived ≥30s). `auth-expiring` reconnects pick up a fresh token
+*     from the HttpClient's provider automatically.
+*   - 401/403 → permanent: `onAuthLost`, no retry loop against a dead
+*     credential.
+*/
+var SseClient = class {
+	constructor(opts) {
+		this.opts = opts;
+		_defineProperty(this, "cursor", void 0);
+		_defineProperty(this, "closed", false);
+		_defineProperty(this, "abort", null);
+		_defineProperty(this, "retryTimer", null);
+		_defineProperty(this, "retryDelayMs", 500);
+		this.cursor = opts.initialCursor;
+	}
+	open() {
+		if (this.closed) return;
+		this.run();
+	}
+	close() {
+		this.closed = true;
+		if (this.retryTimer) clearTimeout(this.retryTimer);
+		this.abort?.abort();
+	}
+	get lastEventId() {
+		return this.cursor;
+	}
+	async run() {
+		const startedAt = Date.now();
+		this.abort = new AbortController();
+		try {
+			const res = await this.opts.http.stream(this.opts.path, this.cursor !== null ? { "Last-Event-ID": String(this.cursor) } : {}, this.abort.signal);
+			if (res.status === 401 || res.status === 403) {
+				this.closed = true;
+				this.opts.onAuthLost();
+				return;
+			}
+			if (!res.ok || !res.body) throw new EngineError$1(EngineErrorCode$1.Network, `events stream HTTP ${res.status}`);
+			await this.consume(res.body);
+			if (Date.now() - startedAt >= 3e4) this.retryDelayMs = 500;
+		} catch {}
+		if (this.closed) return;
+		const jitter = this.retryDelayMs * (.5 + Math.random() * .5);
+		this.retryTimer = setTimeout(() => void this.run(), jitter);
+		this.retryDelayMs = Math.min(this.retryDelayMs * 2, 3e4);
+	}
+	async consume(body) {
+		const reader = body.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done || this.closed) return;
+			buffer += decoder.decode(value, { stream: true });
+			for (;;) {
+				const sep = buffer.indexOf("\n\n");
+				if (sep < 0) break;
+				const block = buffer.slice(0, sep);
+				buffer = buffer.slice(sep + 2);
+				this.dispatch(block);
+			}
+		}
+	}
+	dispatch(block) {
+		if (block.startsWith(":")) return;
+		let id = null;
+		let event = "message";
+		const data = [];
+		for (const line of block.split("\n")) if (line.startsWith("id:")) id = Number(line.slice(3).trim());
+		else if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) data.push(line.slice(5).trim());
+		if (id !== null && Number.isFinite(id)) this.cursor = id;
+		if (event === "mutation") try {
+			this.opts.onRow(JSON.parse(data.join("\n")));
+		} catch {}
+		else if (event === "full-refresh") this.opts.onFullRefresh();
+		else if (event === "auth-revoked") {
+			this.closed = true;
+			this.abort?.abort();
+			this.opts.onAuthLost();
+		}
+	}
+};
+//#endregion
+//#region src/document/CloudDocumentHandle.ts
+var CloudDocumentHandle = class {
+	constructor(http, id, layerName = DEFAULT_LAYER_NAME, initialHead, initialToken = null, sessionId = `cloud:anon:${id}`) {
+		this.http = http;
+		this.layerName = layerName;
+		_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);
+		_defineProperty(this, "attachments", void 0);
+		_defineProperty(this, "forms", void 0);
+		_defineProperty(this, "search", void 0);
+		_defineProperty(this, "pages", void 0);
+		_defineProperty(this, "redaction", void 0);
+		_defineProperty(this, "security", void 0);
+		_defineProperty(this, "render", void 0);
+		_defineProperty(this, "events", void 0);
+		_defineProperty(this, "publisher", void 0);
+		_defineProperty(this, "hub", void 0);
+		_defineProperty(this, "sessionId", void 0);
+		_defineProperty(this, "sseClient", null);
+		_defineProperty(this, "sseSubscribers", 0);
+		_defineProperty(this, "closed", false);
+		_defineProperty(this, "manifestCache", null);
+		_defineProperty(this, "inflightManifest", null);
+		_defineProperty(this, "manifestFloorVersion", 0);
+		_defineProperty(this, "pendingInitialHead", void 0);
+		_defineProperty(this, "manifestAccessor", void 0);
+		this.id = id;
+		this.pendingInitialHead = initialHead ?? null;
+		const security = new CloudDocumentSecurityService(http, id, layerName, initialHead ?? fallbackUnknownHead(id), { isClosed: () => this.closed }, initialToken);
+		this.security = security;
+		this.render = { policy: async () => {
+			const advertised = (security.currentAccess ?? (await security.establishAccess()).access ?? null)?.renderPolicy;
+			if (!advertised) return CONTINUOUS_RENDER_POLICY;
+			return {
+				kind: "lattice",
+				fullPage: { widths: advertised.fullPage.widths },
+				...advertised.tiles ? { tiles: advertised.tiles } : {},
+				...advertised.appearances ? { appearances: advertised.appearances } : {},
+				...advertised.maxRenderPixels !== void 0 ? { maxRenderPixels: advertised.maxRenderPixels } : {},
+				formats: advertised.formats,
+				background: advertised.background,
+				enforced: advertised.enforced
+			};
+		} };
+		const hub = new EventHub();
+		this.hub = hub;
+		this.sessionId = sessionId;
+		this.events = {
+			subscribe: (listener) => {
+				const unsubscribe = hub.subscribe(listener);
+				this.retainRemoteStream();
+				let released = false;
+				return () => {
+					unsubscribe();
+					if (!released) {
+						released = true;
+						this.releaseRemoteStream();
+					}
+				};
+			},
+			lastServerId: () => hub.lastServerId()
+		};
+		this.publisher = new SessionEventPublisher(hub, sessionId);
+		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),
+			applyMetadata: (cache) => this.absorbMetadata(cache),
+			applyAttachments: (cache) => this.absorbAttachments(cache)
+		};
+		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.actions = new CloudDocumentActionsService(http, id, layerName, () => this.closed, this.manifestAccessor);
+		this.attachments = new CloudDocumentAttachmentsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
+		this.forms = new CloudDocumentFormsService(http, id, layerName, () => this.closed, this.manifestAccessor, this.publisher);
+		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);
+	}
+	page(pageObjectNumber) {
+		return new CloudPageHandle(pageObjectNumber, -1, this.http, this.id, this.layerName, () => this.closed, this.manifestAccessor, this.publisher);
+	}
+	download(opts = {}) {
+		if (this.closed) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.id} is closed`));
+		const mode = opts.mode ?? DEFAULT_PDF_SAVE_MODE;
+		return AbortablePromise$1.run(async (signal) => {
+			const buildPath = async () => {
+				const manifest = await this.getManifest(signal);
+				return wirePaths.layerDownloadVersioned(this.id, this.layerName, {
+					docVersion: manifest.docVersion,
+					mode
+				});
+			};
+			try {
+				return await this.http.getBytes(await buildPath(), signal);
+			} catch (err) {
+				if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+				await this.refreshManifest(signal);
+				return this.http.getBytes(await buildPath(), signal);
+			}
+		});
+	}
+	/**
+	* 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
+	* triggers exactly one `/head` + `/manifest@docVersion=N` round-trip.
+	*/
+	async getManifest(signal) {
+		if (this.manifestCache) return this.manifestCache;
+		if (!this.inflightManifest) this.startManifestFetch({ allowInitialHead: true });
+		const promise = this.inflightManifest;
+		if (!promise) throw new EngineError$1(EngineErrorCode$1.Unknown, `manifest fetch was not started for document ${this.id}`);
+		return awaitSignal(promise, signal);
+	}
+	/**
+	* Force re-fetch. Used by the transparent-retry path when a leaf
+	* URL returns 404 (stale version). Replaces `manifestCache`
+	* wholesale so the next `getManifest()` is a Map lookup.
+	*/
+	async refreshManifest(signal) {
+		return awaitSignal(this.startManifestFetch({ allowInitialHead: false }), signal);
+	}
+	/**
+	* 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
+	* 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
+	* know about).
+	*/
+	flipScopes(owns) {
+		const cache = this.manifestCache;
+		const scopes = cache?.scopes;
+		if (!cache || !scopes) return;
+		if (owns.every((plane) => scopes[plane] === "layer")) return;
+		const next = { ...scopes };
+		for (const plane of owns) next[plane] = "layer";
+		this.manifestCache = {
+			...cache,
+			scopes: next
+		};
+	}
+	absorbMutation(meta, owns) {
+		this.flipScopes(owns);
+		const delta = meta.cacheDelta;
+		if (delta) this.manifestFloorVersion = Math.max(this.manifestFloorVersion, delta.docVersion);
+		this.inflightManifest = null;
+		if (!this.manifestCache) return;
+		if (delta) {
+			if (delta.docVersion <= this.manifestCache.docVersion) return;
+			if (delta.previousDocVersion !== this.manifestCache.docVersion) {
+				this.manifestCache = null;
+				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
+			});
+		}
+		if (delta) for (const page of delta.pages) {
+			const existing = byPageObjectNumber.get(page.pageObjectNumber);
+			if (existing) byPageObjectNumber.set(page.pageObjectNumber, {
+				...existing,
+				cache: page.cache
+			});
+		}
+		this.manifestCache = {
+			...this.manifestCache,
+			docVersion: delta?.docVersion ?? this.manifestCache.docVersion,
+			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
+		};
+	}
+	/**
+	* 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).
+	*/
+	absorbPageDelete(cache, deletedPages) {
+		this.flipScopes([
+			"layout",
+			"content",
+			"annotations"
+		]);
+		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);
+		this.manifestCache = {
+			...this.manifestCache,
+			docVersion: cache.docVersion,
+			layoutVersion: cache.layoutVersion,
+			pages: this.manifestCache.pages.filter((page) => !deleted.has(page.state.pageObjectNumber))
+		};
+	}
+	/**
+	* 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;
+		}).catch(() => void 0).finally(() => {
+			if (this.inflightManifest === promise) this.inflightManifest = null;
+		});
+		return promise;
+	}
+	async fetchManifest(signal, opts) {
+		if (this.closed) throw new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.id} is closed`);
+		const head = opts.allowInitialHead ? this.consumeInitialHead() : null;
+		if (head) try {
+			return await this.fetchManifestForHead(head, signal);
+		} catch (err) {
+			if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+		}
+		const freshHead = await this.http.getJson(wirePaths.layerHead(this.id, this.layerName), (raw) => DocumentHeadSchema.parse(raw), signal);
+		return this.fetchManifestForHead(freshHead, signal);
+	}
+	consumeInitialHead() {
+		const head = this.pendingInitialHead;
+		this.pendingInitialHead = null;
+		return head;
+	}
+	fetchManifestForHead(head, signal) {
+		return this.http.getJson(wirePaths.layerManifest(this.id, this.layerName, head.docVersion), (raw) => DocumentManifestSchema.parse(raw), signal);
+	}
+	close() {
+		if (this.closed) return AbortablePromise$1.resolveValue(void 0);
+		this.closed = true;
+		this.sseClient?.close();
+		this.sseClient = null;
+		this.manifestCache = null;
+		this.inflightManifest = null;
+		return AbortablePromise$1.resolveValue(void 0);
+	}
+	retainRemoteStream() {
+		this.sseSubscribers += 1;
+		if (this.sseSubscribers > 1 || this.closed || this.sseClient) return;
+		this.sseClient = new SseClient({
+			http: this.http,
+			path: wirePaths.layerEvents(this.id, this.layerName),
+			initialCursor: this.hub.lastServerId() ?? this.manifestCache?.auditHead ?? null,
+			onRow: (row) => {
+				const event = auditRowToEvent(row, this.sessionId);
+				if (!event) return;
+				this.absorbRemoteEvent(event);
+				this.hub.publish(event);
+			},
+			onFullRefresh: () => {
+				this.manifestCache = null;
+				this.inflightManifest = null;
+			},
+			onAuthLost: () => {
+				this.sseClient = null;
+			}
+		});
+		this.sseClient.open();
+	}
+	releaseRemoteStream() {
+		this.sseSubscribers = Math.max(0, this.sseSubscribers - 1);
+		if (this.sseSubscribers === 0 && this.sseClient) {
+			this.sseClient.close();
+			this.sseClient = null;
+		}
+	}
+	/** 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 "annotation.created":
+			case "annotation.updated":
+			case "annotation.deleted":
+			case "annotation.moved":
+				this.absorbMutation(event.meta, ["annotations"]);
+				return;
+			case "pages.moved":
+			case "pages.rotated":
+				if (event.cache) this.absorbPageStructure(event.cache);
+				return;
+			case "pages.deleted":
+				if (event.cache) this.absorbPageDelete(event.cache, event.pageObjectNumbers);
+				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);
+				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"]);
+				return;
+			case "form.effectsApplied":
+				if (event.meta) this.absorbMutation(event.meta, ["annotations"]);
+				return;
+			case "pages.flattened":
+				if (event.meta) this.absorbMutation(event.meta, ["content", "annotations"]);
+				return;
+			case "redaction.applied":
+				if (event.meta) this.absorbMutation(event.meta, ["content", "annotations"]);
+				return;
+		}
+	}
+};
+function fallbackUnknownHead(id) {
+	return {
+		id,
+		baseSha: "",
+		storageSizeBytes: 0,
+		docVersion: 1,
+		state: "ready",
+		encryption: {
+			state: "unknown",
+			requiresPassword: null
+		},
+		permissions: {
+			known: false,
+			bits: null,
+			allAllowed: null,
+			openedAs: null,
+			securityHandlerRevision: null,
+			canUpgradeToOwner: false
+		},
+		access: {
+			required: true,
+			reasons: ["permissions-unknown"],
+			endpoint: wirePaths.access
+		}
+	};
+}
+function awaitSignal(promise, signal) {
+	if (signal.aborted) return Promise.reject(new AbortError$1(signal.reason));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(new AbortError$1(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/transport/HttpClient.ts
+var HttpClient = class HttpClient {
+	constructor(opts) {
+		_defineProperty(this, "baseUrl", void 0);
+		_defineProperty(this, "tokenFn", void 0);
+		_defineProperty(this, "fetchFn", void 0);
+		_defineProperty(this, "sessionId", void 0);
+		_defineProperty(this, "cdnBinding", null);
+		this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+		const token = opts.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);
+	}
+	/**
+	* 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.
+	*/
+	withToken(token) {
+		return new HttpClient({
+			baseUrl: this.baseUrl,
+			token,
+			...this.sessionId ? { sessionId: this.sessionId } : {},
+			fetch: this.fetchFn
+		});
+	}
+	/**
+	* Raw streaming GET (the SSE channel). Same auth/session headers and
+	* error mapping as every other request; the caller owns the body stream.
+	*/
+	async stream(path, headers, signal) {
+		return this.request(path, {
+			method: "GET",
+			headers: new Headers({
+				Accept: "text/event-stream",
+				...headers
+			}),
+			signal
+		});
+	}
+	/**
+	* 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
+	* 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).
+	*/
+	setCdnAccess(binding) {
+		this.cdnBinding = binding;
+		if (binding?.cdn?.signedCookies && typeof globalThis.document !== "undefined") for (const cookie of binding.cdn.signedCookies) {
+			const parts = [`${cookie.name}=${cookie.value}`];
+			parts.push(`Path=${cookie.path ?? "/"}`);
+			if (cookie.domain) parts.push(`Domain=${cookie.domain}`);
+			if (cookie.expires) parts.push(`Expires=${(/* @__PURE__ */ new Date(cookie.expires * 1e3)).toUTCString()}`);
+			parts.push("SameSite=None", "Secure");
+			globalThis.document.cookie = parts.join("; ");
+		}
+	}
+	/** Current CDN binding (or null). Exposed for diagnostics/tests. */
+	get currentCdnBinding() {
+		return this.cdnBinding;
+	}
+	absoluteUrl(path) {
+		return `${this.baseUrl}${path}`;
+	}
+	async getBlob(path, signal) {
+		const res = await this.request(path, {
+			method: "GET",
+			signal
+		});
+		if (!res.ok) await this.throwFromBody(res);
+		return await res.blob();
+	}
+	async getBytes(path, signal) {
+		const res = await this.request(path, {
+			method: "GET",
+			headers: new Headers({ Accept: "application/pdf" }),
+			signal
+		});
+		if (!res.ok) await this.throwFromBody(res);
+		return new Uint8Array(await res.arrayBuffer());
+	}
+	/**
+	* Resolve the current bearer token. Awaits the user-supplied
+	* token factory if it returns a promise. Used by the cloud
+	* engine to read doc-scoped claims **without** verifying — the
+	* server is the verifier of record. Throws when no token is
+	* configured.
+	*/
+	async currentToken() {
+		if (!this.tokenFn) throw new EngineError$1(EngineErrorCode$1.InvalidArg, "http client has no token configured");
+		return await this.tokenFn();
+	}
+	async getJson(path, parser, signal) {
+		const res = await this.request(path, {
+			method: "GET",
+			signal
+		});
+		return await this.parseJsonResponse(res, parser);
+	}
+	/**
+	* GET a versioned URL with transparent stale-version recovery. If
+	* the server returns 404 (the well-known "this version is gone"
+	* signal for content-addressed reads), call `onStaleVersion` (which
+	* the caller wires to a manifest refresh), then re-resolve `buildPath`
+	* and retry the GET exactly once. Any non-404 error propagates.
+	*
+	* The retry budget is hard-capped at 1: after a refresh, if the
+	* server's idea of the current version is still ahead of the
+	* client's view, the second request fails normally — this matches
+	* the CDN cache invariant ("a versioned URL's bytes are immutable
+	* for its lifetime").
+	*/
+	async getJsonWithRefresh(buildPath, parser, onStaleVersion, signal) {
+		const initialPath = await buildPath(signal);
+		try {
+			return await this.getJson(initialPath, parser, signal);
+		} catch (err) {
+			if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+			await onStaleVersion(signal);
+			const retryPath = await buildPath(signal);
+			return await this.getJson(retryPath, parser, signal);
+		}
+	}
+	/**
+	* GET a `multipart/form-data` body and parse it with the platform's
+	* `Response.formData()` (works in browsers and undici). Text parts come
+	* back as strings, parts with a filename as `Blob`s.
+	*/
+	async getFormData(path, signal) {
+		const res = await this.request(path, {
+			method: "GET",
+			headers: new Headers({ Accept: "multipart/form-data" }),
+			signal
+		});
+		if (!res.ok) await this.throwFromBody(res);
+		return await res.formData();
+	}
+	/**
+	* `getFormData` with the same single-retry stale-version recovery as
+	* {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+	* `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+	*/
+	async getFormDataWithRefresh(buildPath, onStaleVersion, signal) {
+		const initialPath = await buildPath(signal);
+		try {
+			return await this.getFormData(initialPath, signal);
+		} catch (err) {
+			if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+			await onStaleVersion(signal);
+			const retryPath = await buildPath(signal);
+			return await this.getFormData(retryPath, signal);
+		}
+	}
+	/**
+	* `getBlob` with the same single-retry stale-version recovery as
+	* {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+	* `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+	* Render blobs ride this rail: a scope flip re-resolves the
+	* doc-vs-layer path family instead of failing on a stale URL.
+	*/
+	async getBlobWithRefresh(buildPath, onStaleVersion, signal) {
+		const initialPath = await buildPath(signal);
+		try {
+			return await this.getBlob(initialPath, signal);
+		} catch (err) {
+			if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+			await onStaleVersion(signal);
+			const retryPath = await buildPath(signal);
+			return await this.getBlob(retryPath, signal);
+		}
+	}
+	/** GET raw bytes plus the response headers (attachment-file leaves). */
+	async getFile(path, signal) {
+		const res = await this.request(path, {
+			method: "GET",
+			signal
+		});
+		if (!res.ok) await this.throwFromBody(res);
+		return {
+			bytes: new Uint8Array(await res.arrayBuffer()),
+			headers: res.headers
+		};
+	}
+	/**
+	* `getFile` with the same single-retry stale-version recovery as
+	* {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+	* `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+	*/
+	async getFileWithRefresh(buildPath, onStaleVersion, signal) {
+		const initialPath = await buildPath(signal);
+		try {
+			return await this.getFile(initialPath, signal);
+		} catch (err) {
+			if (!EngineError$1.is(err, EngineErrorCode$1.NotFound)) throw err;
+			await onStaleVersion(signal);
+			const retryPath = await buildPath(signal);
+			return await this.getFile(retryPath, signal);
+		}
+	}
+	async postMultipartJson(path, body, parser, signal) {
+		const res = await this.request(path, {
+			method: "POST",
+			body,
+			signal
+		});
+		return await this.parseJsonResponse(res, parser);
+	}
+	/** PATCH counterpart of {@link postMultipartJson} (binary-carrying mutations). */
+	async patchMultipartJson(path, body, parser, signal) {
+		const res = await this.request(path, {
+			method: "PATCH",
+			body,
+			signal
+		});
+		return await this.parseJsonResponse(res, parser);
+	}
+	async postJson(path, body, parser, signal) {
+		const res = await this.requestJson(path, "POST", body, signal);
+		return await this.parseJsonResponse(res, parser);
+	}
+	/** POST a raw binary body (FDF/XFDF import) and parse the JSON response. */
+	async postBytesJson(path, bytes, contentType, parser, signal) {
+		const headers = new Headers({ "Content-Type": contentType });
+		const body = new Uint8Array(bytes).buffer;
+		const res = await this.request(path, {
+			method: "POST",
+			body,
+			headers,
+			signal
+		});
+		return await this.parseJsonResponse(res, parser);
+	}
+	async patchJson(path, body, parser, signal) {
+		const res = await this.requestJson(path, "PATCH", body, signal);
+		return await this.parseJsonResponse(res, parser);
+	}
+	async deleteJson(path, parser, signal) {
+		const res = await this.request(path, {
+			method: "DELETE",
+			signal
+		});
+		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) {
+		const headers = new Headers({ "Content-Type": "application/json" });
+		return this.request(path, {
+			method,
+			body: JSON.stringify(body ?? {}),
+			headers,
+			signal
+		});
+	}
+	async request(path, init) {
+		const { url, extraHeader } = this.resolveOutgoing(path);
+		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);
+		if (extraHeader) headers.set(extraHeader.name, extraHeader.value);
+		try {
+			return await this.fetchFn(url, {
+				...init,
+				headers
+			});
+		} catch (err) {
+			if (init.signal?.aborted) throw new AbortError$1(init.signal.reason ?? err);
+			if (err?.name === "AbortError") throw new AbortError$1(err.message);
+			throw new EngineError$1(EngineErrorCode$1.Network, `network error: ${err?.message ?? err}`, { cause: err });
+		}
+	}
+	async parseJsonResponse(res, parser) {
+		if (!res.ok) await this.throwFromBody(res);
+		const json = await res.json().catch(() => ({}));
+		try {
+			return parser(json);
+		} catch (err) {
+			throw new EngineError$1(EngineErrorCode$1.WireFormat, `unexpected response shape: ${err?.message ?? err}`, { cause: err });
+		}
+	}
+	/**
+	* Decide where this request actually goes. With no CDN binding (or
+	* binding's `cdn` is null) every request stays on origin. 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 {
+			url: `${this.baseUrl}${path}`,
+			extraHeader: null
+		};
+		const applied = applyCdnAccess({
+			path,
+			originUrl: this.baseUrl,
+			docId: this.cdnBinding.docId,
+			layerName: this.cdnBinding.layerName,
+			cdn: this.cdnBinding.cdn
+		});
+		return {
+			url: applied.url,
+			extraHeader: applied.routedToCdn && applied.authHeader ? applied.authHeader : null
+		};
+	}
+	async throwFromBody(res) {
+		let payload;
+		try {
+			payload = await res.json();
+		} catch {
+			payload = null;
+		}
+		const code = mapStatusToCode(res.status);
+		if (payload && typeof payload === "object" && "error" in payload) {
+			const inner = payload.error;
+			const parsed = trySerialized(inner);
+			if (parsed) throw new EngineError$1(parsed.code, parsed.message, { details: parsed.details });
+			throw new EngineError$1(code, typeof inner === "object" && inner && "message" in inner ? String(inner.message) : `HTTP ${res.status}`, { details: { status: res.status } });
+		}
+		throw new EngineError$1(code, `HTTP ${res.status}`, { details: { status: res.status } });
+	}
+};
+function mapStatusToCode(status) {
+	if (status === 401) return EngineErrorCode$1.Unauthenticated;
+	if (status === 403) return EngineErrorCode$1.Forbidden;
+	if (status === 409) return EngineErrorCode$1.WeakAnnotationSessionConflict;
+	if (status === 404) return EngineErrorCode$1.NotFound;
+	if (status === 422) return EngineErrorCode$1.DocOpenFailed;
+	if (status === 499) return EngineErrorCode$1.Aborted;
+	if (status === 400) return EngineErrorCode$1.InvalidArg;
+	return EngineErrorCode$1.Unknown;
+}
+function trySerialized(value) {
+	const result = EngineErrorPayloadSchema.safeParse(value);
+	return result.success ? result.data : null;
+}
+//#endregion
+//#region src/CloudEngine.ts
+/**
+* Cloud engine: speaks the same Engine interface as @embedpdf/engine
+* but routes everything through HTTPS to a remote @cloudpdf/server (or
+* CloudPDF SaaS). Identical observable contract; only the transport differs.
+*/
+var CloudEngine = class CloudEngine {
+	static fromOptions(opts) {
+		const sessionId = `cloud:${generateUuid()}`;
+		return new CloudEngine(new HttpClient({
+			...opts,
+			sessionId
+		}), sessionId);
+	}
+	constructor(http, sessionId) {
+		this.http = http;
+		this.sessionId = sessionId;
+		_defineProperty(this, "destroyed", false);
+	}
+	open(input, options) {
+		if (this.destroyed) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.RuntimeUnavailable, "engine destroyed"));
+		options?.scope;
+		options?.identity;
+		const effectivePassword = options && "password" in options ? options.password ?? null : input.password ?? null;
+		if (input.kind === "token") {
+			const tokenSource = input.token;
+			return AbortablePromise$1.run(async (signal) => {
+				const docHttp = this.http.withToken(tokenSource);
+				const token = await docHttp.currentToken();
+				const claims = decodeUnverifiedClaims(token);
+				const docId = claims.doc_id;
+				if (typeof docId !== "string" || docId.length === 0) throw new EngineError$1(EngineErrorCode$1.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 : DEFAULT_LAYER_NAME;
+				const head = await docHttp.getJson(wirePaths.layerHead(docId, layerName), (raw) => DocumentHeadSchema.parse(raw), signal);
+				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, token, this.sessionId);
+				await maybeAutoEstablishAccess(handle, head, signal, effectivePassword);
+				return handle;
+			});
+		}
+		if (input.kind === "id") {
+			const id = input.id;
+			const docHttp = input.token ? this.http.withToken(input.token) : this.http;
+			return AbortablePromise$1.run(async (signal) => {
+				let layerName = input.layerName ?? DEFAULT_LAYER_NAME;
+				let resolvedToken = null;
+				try {
+					resolvedToken = await docHttp.currentToken();
+				} catch {
+					resolvedToken = null;
+				}
+				if (!input.layerName && resolvedToken) {
+					const claims = decodeUnverifiedClaims(resolvedToken);
+					if (typeof claims.layer_name === "string" && claims.layer_name.length > 0) layerName = claims.layer_name;
+				}
+				const head = await docHttp.getJson(wirePaths.layerHead(id, layerName), (raw) => DocumentHeadSchema.parse(raw), signal);
+				const handle = new CloudDocumentHandle(docHttp, head.id, layerName, head, resolvedToken, this.sessionId);
+				await maybeAutoEstablishAccess(handle, head, signal, effectivePassword);
+				return handle;
+			});
+		}
+		return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `cloud engine supports OpenInput.kind === 'token' or 'id' (got '${input.kind}')`));
+	}
+	destroy() {
+		if (this.destroyed) return AbortablePromise$1.resolveValue(void 0);
+		this.destroyed = true;
+		return AbortablePromise$1.resolveValue(void 0);
+	}
+};
+/**
+* Post-/head access establishment, in two layers:
+*
+* 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:
+*      - `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
+*        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
+*    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
+*    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".
+*/
+async function maybeAutoEstablishAccess(handle, head, signal, password) {
+	const reasons = new Set(head.access.reasons);
+	const security = handle.security;
+	if (password != null && (reasons.has("password") || head.permissions.canUpgradeToOwner)) {
+		if (await settleLinked(security.unlock({
+			password,
+			mode: "any"
+		}), signal)) return;
+		if (reasons.has("password")) return;
+	}
+	if (!head.access.required) return;
+	if (reasons.has("password")) return;
+	if (!reasons.has("cdn")) return;
+	await settleLinked(security.establishAccess(), signal);
+}
+/** Await an /access attempt with open()-abort linkage. Returns whether it
+*  succeeded; failures are contained (see maybeAutoEstablishAccess). */
+async function settleLinked(pending, signal) {
+	const onAbort = () => pending.abort(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+	if (signal.aborted) onAbort();
+	else signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		await pending;
+		return true;
+	} catch {
+		return false;
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+//#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.
+*
+* Synchronous and cheap: no WASM to compile, no worker to spawn — the engine
+* holds an HTTP client and nothing else. Like `localEngine()`, the returned
+* instance is yours (call `destroy()` when done, usually never for a
+* module-scope singleton); pass a thunk (`engine={() => cloudEngine(...)}`)
+* 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
+* `undefined` cloud-side), so they cannot be configured from the client. This
+* is the local-vs-cloud split, surfaced in the API.
+*
+* ```ts
+* const engine = cloudEngine({ baseUrl: 'https://pdf.example.com', token });
+* <Viewer engine={engine} plugins={[stagePlugin(), renderPlugin()]} />
+* ```
+*/
+function cloudEngine(opts) {
+	return CloudEngine.fromOptions(opts);
+}
+//#endregion
+export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, EngineError, EngineErrorCode, HttpClient, cloudEngine, createCloudEngine, decodeUnverifiedClaims };
+
+//# sourceMappingURL=index.js.map