@cloudpdf/engine 3.0.0-next.0 → 3.0.0-next.10

package/dist/index.js

@@ -1,5 +1,5 @@
-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 { 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, checkCollab, checkSetGroup, createPageImageHandle, decodePdfBits, encodeFieldRefKey, encodeStableIdKey, expandRawScope, normalizeAnnotationDraft, normalizeAnnotationPatch, normalizeAttachmentFileSource, passwordPromptFromState, searchContentEpoch, securityStateFromHead } from "@embedpdf/engine-core/runtime";
+import { AccessResponseSchema, AnnotationAppearanceManifestSchema, AnnotationCreateResultSchema, AnnotationDeleteResultSchema, AnnotationListPageSnapshotSchema, AnnotationListSnapshotAllPagesSchema, 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, PageInsertResultSchema, 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
 /**
@@ -76,6 +76,9 @@ function _defineProperty(e, r, t) {
 }
 //#endregion
 //#region src/document/CloudDocumentAnnotationsService.ts
+/** Bulk-read restarts after a mid-flight mutation staled the pinned
+*  version (404 on the immutable leaf → refresh the manifest → retry). */
+const MAX_COHERENCE_RESTARTS = 2;
 var CloudDocumentAnnotationsService = class {
 	constructor(http, docId, layerName, isClosed, manifest) {
 		this.http = http;
@@ -84,16 +87,57 @@ var CloudDocumentAnnotationsService = class {
 		this.isClosed = isClosed;
 		this.manifest = manifest;
 	}
+	/**
+	* One COHERENT whole-document snapshot: a single read of the immutable
+	* `annotations/items@annotationsVersion=N` leaf at the manifest's pin —
+	* materialized server-side by one raw (no page-load) sweep, CDN-cacheable
+	* because the pin bumps only when annotation list bodies actually change.
+	* A stale pin mid-read (a concurrent mutation → 404) refreshes the
+	* manifest and retries, so the result always belongs to one document
+	* moment (the torn read this method exists to prevent).
+	*/
 	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))) };
+			for (let attempt = 0;; attempt++) {
+				const manifest = attempt === 0 ? await this.manifest.get(signal) : await this.manifest.refresh(signal);
+				try {
+					return await this.readBulkAt(manifest, signal);
+				} catch (err) {
+					if (!EngineError$1.is(err, EngineErrorCode$1.NotFound) || attempt >= MAX_COHERENCE_RESTARTS) throw err;
+				}
+			}
 		});
 	}
+	/** One bulk leaf read at the manifest's pin. The server stamps the body's
+	*  `auditHead` at materialization time; a CDN-cached body may carry a
+	*  cursor older than the current manifest's, which is still safe — the
+	*  pin proves no items-affecting mutation landed in between, so replaying
+	*  that window over the body is all no-ops. */
+	async readBulkAt(manifest, signal) {
+		const path = planesInherited(manifest, ["annotations"]) ? wirePaths.docAnnotationsAll(this.docId, manifest.annotationsVersion) : wirePaths.layerAnnotationsAll(this.docId, this.layerName, manifest.annotationsVersion);
+		const body = await this.http.getJson(path, (raw) => AnnotationListSnapshotAllPagesSchema.parse(raw), signal);
+		return {
+			...body,
+			auditHead: body.auditHead ?? manifest.auditHead
+		};
+	}
 	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));
+		return AbortablePromise$1.run((signal) => this.http.getJsonWithRefresh(async (s) => this.versionedPagePath(await this.manifest.get(s), pageObjectNumber), (raw) => AnnotationListPageSnapshotSchema.parse(raw), async (s) => {
+			await this.manifest.refresh(s);
+		}, signal));
+	}
+	/** Versioned leaf URL for one manifest page entry, with the same
+	*  plane routing as `CloudPageAnnotationsService.list()`: an inherited
+	*  `annotations` plane reads the doc-level base leaf. */
+	pagePathAt(manifest, page) {
+		return planesInherited(manifest, ["annotations"]) ? wirePaths.docPageAnnotations(this.docId, page.state.pageObjectNumber, page.cache.annotationVersion) : wirePaths.layerPageAnnotations(this.docId, this.layerName, page.state.pageObjectNumber, page.cache.annotationVersion);
+	}
+	versionedPagePath(manifest, pageObjectNumber) {
+		const page = manifest.pages.find((p) => p.state.pageObjectNumber === pageObjectNumber);
+		if (!page) throw new EngineError$1(EngineErrorCode$1.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`);
+		return this.pagePathAt(manifest, page);
 	}
 	beginWeakEdit(pageObjectNumbers) {
 		if (this.isClosed()) return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.DocNotOpen, `document ${this.docId} is closed`));
@@ -102,9 +146,6 @@ var CloudDocumentAnnotationsService = class {
 			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) {
@@ -449,6 +490,13 @@ var CloudDocumentFormsService = class {
 };
 //#endregion
 //#region src/document/CloudDocumentPagesService.ts
+/** Detach a Uint8Array view into a standalone ArrayBuffer (the resource-map
+*  shape) without disturbing a larger buffer the caller still owns. */
+function copyToExactBuffer(view) {
+	const copy = new ArrayBuffer(view.byteLength);
+	new Uint8Array(copy).set(view);
+	return copy;
+}
 /**
 * Cloud-side document pages service. Mirrors `LocalDocumentPagesService`
 * over HTTP: GET /pages for `list`, POST /pages/move for the reorder.
@@ -541,6 +589,46 @@ var CloudDocumentPagesService = class {
 			return result;
 		});
 	}
+	insert(bytes, 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 buffer = bytes instanceof ArrayBuffer ? bytes : copyToExactBuffer(bytes);
+			const form = buildMutationForm(destIndex !== void 0 ? { destIndex } : {}, { source: {
+				bytes: buffer,
+				mimeType: "application/pdf",
+				name: "source.pdf"
+			} });
+			const result = await this.http.postMultipartJson(wirePaths.layerPagesInsert(this.docId, this.layerName), form, (raw) => PageInsertResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageInsert(result.cache);
+			this.publisher.publishLocal({
+				type: "pages.inserted",
+				destIndex,
+				...result
+			});
+			return result;
+		});
+	}
+	insertBlank(spec, 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.layerPagesInsertBlank(this.docId, this.layerName), {
+				size: spec.size,
+				...spec.count !== void 0 ? { count: spec.count } : {},
+				...destIndex !== void 0 ? { destIndex } : {}
+			}, (raw) => PageInsertResultSchema.parse(raw), signal);
+			if (result.cache) this.manifest.applyPageInsert(result.cache);
+			this.publisher.publishLocal({
+				type: "pages.inserted",
+				destIndex,
+				...result
+			});
+			return result;
+		});
+	}
+	extract(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) => this.http.postJsonBytes(wirePaths.layerPagesExtract(this.docId, this.layerName), { pageObjectNumbers }, signal));
+	}
 	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) => {
@@ -753,6 +841,33 @@ var CloudDocumentSecurityService = class {
 		return checkCapability(cap, this.tokenScope, bits);
 	}
 	/**
+	* Per-record annotation authorization mirrors — the same
+	* `checkCollab`/`checkSetGroup` resolvers the server's route layer
+	* enforces with, over the same inputs: the raw scope
+	* (server-canonical post-/access, else the JWT's own claim), the
+	* caller's identity, and /head's PDF bits. A control gated on these
+	* matches the server's allow/deny for the same mutation. False
+	* before any token/access context exists — fail closed, same rule
+	* as `allows`.
+	*/
+	allowsAnnotationCreate() {
+		const id = this.identity ?? {};
+		return checkCollab("create", selfTarget(id), this.rawScope(), id, this.pdfBits());
+	}
+	allowsAnnotationMutation(action, target) {
+		return checkCollab(action, target, this.rawScope(), this.identity ?? {}, this.pdfBits());
+	}
+	allowsAnnotationGroupAssignment(groupId) {
+		return checkSetGroup(groupId, this.identity?.group_id, this.rawScope(), this.pdfBits());
+	}
+	/** Raw scope for the collab resolver: server-canonical post-/access, else the JWT claim. */
+	rawScope() {
+		return this.access?.scope ?? this.tokenScope;
+	}
+	pdfBits() {
+		return decodePdfBits(this.state.permissions.bits);
+	}
+	/**
 	* Identity of the current caller, or null when anonymous.
 	*
 	* Cloud-canonical post-/access; otherwise the identity claims from
@@ -809,9 +924,7 @@ var CloudDocumentSecurityService = class {
 	* 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,
+		const response = await this.http.postJson(wirePaths.access(this.docId, this.layerName), {
 			...body.password ? { password: body.password } : {},
 			mode: body.mode
 		}, (raw) => AccessResponseSchema.parse(raw), signal);
@@ -852,6 +965,18 @@ function safeDecodeClaims(token) {
 		return null;
 	}
 }
+/**
+* CREATE's CollabTarget is the caller's own identity — the same
+* derivation as engine-local's `ScopeGuard.targetForSelfCreate`, so
+* `:self` trivially passes and `:group=X` matches the caller's
+* default group.
+*/
+function selfTarget(id) {
+	return {
+		...id.user_id !== void 0 ? { userId: id.user_id } : {},
+		...id.group_id !== void 0 ? { groupId: id.group_id } : {}
+	};
+}
 function identityFromClaims(claims) {
 	const out = {};
 	if (typeof claims["user_id"] === "string") out.user_id = claims["user_id"];
@@ -1341,6 +1466,12 @@ function auditRowToEvent(row, mySessionId) {
 			origin,
 			...row.payload
 		};
+		case "pages.insert":
+		case "pages.insertBlank": return {
+			type: "pages.inserted",
+			origin,
+			...row.payload
+		};
 		case "pages.flatten": return {
 			type: "pages.flattened",
 			origin,
@@ -1583,6 +1714,7 @@ var CloudDocumentHandle = class {
 			apply: (meta, owns) => this.absorbMutation(meta, owns),
 			applyPageStructure: (cache) => this.absorbPageStructure(cache),
 			applyPageDelete: (cache, deletedPages) => this.absorbPageDelete(cache, deletedPages),
+			applyPageInsert: (cache) => this.absorbPageInsert(cache),
 			applyMetadata: (cache) => this.absorbMetadata(cache),
 			applyAttachments: (cache) => this.absorbAttachments(cache)
 		};
@@ -1691,6 +1823,7 @@ var CloudDocumentHandle = class {
 		this.manifestCache = {
 			...this.manifestCache,
 			docVersion: delta?.docVersion ?? this.manifestCache.docVersion,
+			...delta?.annotationsVersion !== void 0 ? { annotationsVersion: delta.annotationsVersion } : {},
 			pages: Array.from(byPageObjectNumber.values()).sort((a, b) => a.state.pageObjectNumber - b.state.pageObjectNumber)
 		};
 	}
@@ -1748,6 +1881,27 @@ var CloudDocumentHandle = class {
 		};
 	}
 	/**
+	* Patch bookkeeping after a page insert — the mirror of
+	* {@link absorbPageDelete}, with one asymmetry: delete can patch the
+	* cached manifest losslessly (it only REMOVES rows), but an insert needs
+	* manifest rows for the fresh PONs and the result doesn't carry them. So
+	* this absorb flips the planes (insert changes the page SET, so like
+	* delete it owns content + annotations alongside layout), raises the
+	* version floor, and DROPS the cache — the next read refetches a manifest
+	* that includes the new pages' rows. The UI never waits on that refetch:
+	* the mutation result / event already carries the full new layout.
+	*/
+	absorbPageInsert(cache) {
+		this.flipScopes([
+			"layout",
+			"content",
+			"annotations"
+		]);
+		this.manifestFloorVersion = Math.max(this.manifestFloorVersion, cache.docVersion);
+		this.inflightManifest = null;
+		this.manifestCache = null;
+	}
+	/**
 	* Patch the cached manifest after a metadata write. Symmetric with
 	* {@link absorbPageMove}: a metadata edit advances `docVersion` (so leaf
 	* URLs re-resolve) and `metadataVersion` (so the /metadata leaf re-fetches),
@@ -1843,6 +1997,10 @@ var CloudDocumentHandle = class {
 			path: wirePaths.layerEvents(this.id, this.layerName),
 			initialCursor: this.hub.lastServerId() ?? this.manifestCache?.auditHead ?? null,
 			onRow: (row) => {
+				if (this.manifestCache && row.id > this.manifestCache.auditHead) this.manifestCache = {
+					...this.manifestCache,
+					auditHead: row.id
+				};
 				const event = auditRowToEvent(row, this.sessionId);
 				if (!event) return;
 				this.absorbRemoteEvent(event);
@@ -1851,6 +2009,11 @@ var CloudDocumentHandle = class {
 			onFullRefresh: () => {
 				this.manifestCache = null;
 				this.inflightManifest = null;
+				this.hub.publish({
+					type: "stream.desynced",
+					reason: "backlog-overflow",
+					ts: Date.now()
+				});
 			},
 			onAuthLost: () => {
 				this.sseClient = null;
@@ -1883,6 +2046,9 @@ var CloudDocumentHandle = class {
 			case "pages.deleted":
 				if (event.cache) this.absorbPageDelete(event.cache, event.pageObjectNumbers);
 				return;
+			case "pages.inserted":
+				if (event.cache) this.absorbPageInsert(event.cache);
+				return;
 			case "metadata.updated":
 				if (event.cache) this.absorbMetadata(event.cache);
 				return;
@@ -1934,7 +2100,7 @@ function fallbackUnknownHead(id) {
 		access: {
 			required: true,
 			reasons: ["permissions-unknown"],
-			endpoint: wirePaths.access
+			endpoint: wirePaths.access(id, DEFAULT_LAYER_NAME)
 		}
 	};
 }
@@ -1955,19 +2121,117 @@ function awaitSignal(promise, signal) {
 	});
 }
 //#endregion
+//#region src/share.ts
+/**
+* Thrown on a non-OK exchange. `code` is the server's wire code:
+* `SharePasswordRequired` (prompt and retry with a password),
+* `OriginNotAllowed` / `OriginRequired`, `ShareExpired`, `NotFound`
+* (unknown or revoked — indistinguishable by design), or
+* `TooManyRequests`.
+*/
+var ShareExchangeError = class extends Error {
+	constructor(code, message, status) {
+		super(message);
+		this.code = code;
+		this.status = status;
+		this.name = "ShareExchangeError";
+	}
+};
+async function exchangeShareToken(baseUrl, shareToken, opts = {}) {
+	const res = await (opts.fetch ?? globalThis.fetch)(`${baseUrl.replace(/\/$/, "")}/v1/share-sessions`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			shareToken,
+			...opts.password !== void 0 ? { password: opts.password } : {}
+		})
+	});
+	if (!res.ok) {
+		let code = "Unknown";
+		let message = `share exchange failed with status ${res.status}`;
+		try {
+			const payload = await res.json();
+			if (payload.error?.code) code = payload.error.code;
+			if (payload.error?.message) message = payload.error.message;
+		} catch {}
+		throw new ShareExchangeError(code, message, res.status);
+	}
+	return await res.json();
+}
+/**
+* Lift a {@link ShareExchangeError} into the engine's error taxonomy, so
+* `open({ kind: 'share' })` and every later renewal fail with the same
+* `EngineError` family as all other engine calls. The wire code and HTTP
+* status survive in `details`; the original error rides as `cause`.
+*
+* `SharePasswordRequired` gets its own engine code — it is the one outcome
+* callers branch on programmatically (prompt for the grant passphrase and
+* retry). Everything else maps by meaning, with the HTTP status as the
+* fallback discriminator.
+*/
+function engineErrorFromShareExchange(error) {
+	return new EngineError$1(error.code === "SharePasswordRequired" ? EngineErrorCode$1.SharePasswordRequired : error.code === "NotFound" ? EngineErrorCode$1.NotFound : error.code === "ShareExpired" || error.code === "OriginNotAllowed" || error.code === "OriginRequired" ? EngineErrorCode$1.Forbidden : error.status === 401 ? EngineErrorCode$1.Unauthenticated : error.status === 400 ? EngineErrorCode$1.InvalidArg : EngineErrorCode$1.Unknown, `share exchange failed: ${error.message}`, {
+		details: {
+			shareCode: error.code,
+			status: error.status
+		},
+		cause: error
+	});
+}
+/** Renew this many seconds before `expiresAt` so in-flight requests never race expiry. */
+const RENEW_MARGIN_SECONDS = 60;
+/**
+* A caching, self-renewing token source over the exchange — the callable
+* member of the engine's `TokenSource` union, assignable wherever one is
+* taken.
+* Concurrent callers share one in-flight exchange; a failed exchange
+* clears it so the next request retries rather than caching the error.
+*/
+function shareSessionSource(baseUrl, shareToken, opts = {}) {
+	let session = null;
+	let inflight = null;
+	return async () => {
+		if (session && session.expiresAt - Date.now() / 1e3 > RENEW_MARGIN_SECONDS) return session.token;
+		inflight ?? (inflight = exchangeShareToken(baseUrl, shareToken, opts).then((next) => {
+			session = next;
+			return next.token;
+		}).finally(() => {
+			inflight = null;
+		}));
+		return inflight;
+	};
+}
+//#endregion
 //#region src/transport/HttpClient.ts
 var HttpClient = class HttpClient {
 	constructor(opts) {
-		_defineProperty(this, "baseUrl", void 0);
+		_defineProperty(this, "base", void 0);
 		_defineProperty(this, "tokenFn", void 0);
 		_defineProperty(this, "fetchFn", void 0);
+		_defineProperty(this, "docAffinityHeader", void 0);
+		_defineProperty(this, "onRetry", void 0);
 		_defineProperty(this, "sessionId", void 0);
 		_defineProperty(this, "cdnBinding", null);
-		this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+		this.base = 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);
+		this.docAffinityHeader = opts.docAffinityHeader ?? true;
+		this.onRetry = opts.onRetry;
+	}
+	/** Normalized server base URL (no trailing slash). */
+	get baseUrl() {
+		return this.base;
+	}
+	/**
+	* The fetch implementation this client sends requests through (injected
+	* or global). Exposed so sibling transports spawned per-open — the
+	* share-session exchange, most of all — ride the same fetch the engine
+	* was configured with (test doubles, SSR `Origin`-attaching wrappers).
+	*/
+	get fetchImpl() {
+		return this.fetchFn;
 	}
 	/**
 	* Return a clone of this client bound to a different bearer. Used
@@ -2185,6 +2449,12 @@ var HttpClient = class HttpClient {
 		const res = await this.requestJson(path, "POST", body, signal);
 		return await this.parseJsonResponse(res, parser);
 	}
+	/** POST a JSON body and return the raw binary response (pages.extract). */
+	async postJsonBytes(path, body, signal) {
+		const res = await this.requestJson(path, "POST", body, signal);
+		if (!res.ok) await this.throwFromBody(res);
+		return new Uint8Array(await res.arrayBuffer());
+	}
 	/** POST a raw binary body (FDF/XFDF import) and parse the JSON response. */
 	async postBytesJson(path, bytes, contentType, parser, signal) {
 		const headers = new Headers({ "Content-Type": contentType });
@@ -2231,7 +2501,7 @@ var HttpClient = class HttpClient {
 		});
 	}
 	async request(path, init) {
-		const { url, extraHeader } = this.resolveOutgoing(path);
+		const { url, extraHeader, routedToCdn } = this.resolveOutgoing(path);
 		const headers = new Headers(init.headers ?? {});
 		if (this.tokenFn) {
 			const token = await this.tokenFn();
@@ -2240,11 +2510,32 @@ var HttpClient = class HttpClient {
 		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, {
+		if (this.docAffinityHeader && !routedToCdn) {
+			const doc = /^\/v1\/docs\/([^/]+)\//.exec(path);
+			if (doc) headers.set("X-CloudPDF-Doc", decodeURIComponent(doc[1]));
+		}
+		for (let attempt = 0;; attempt++) {
+			const res = await this.execute(url, {
 				...init,
 				headers
 			});
+			if (res.status !== 503 || attempt >= HttpClient.MAX_RETRIES || isStreamBody(init.body ?? null)) return res;
+			const code = await peekErrorCode(res);
+			if (code === null || !RETRYABLE_503.has(code)) return res;
+			const hinted = Number(res.headers.get("retry-after"));
+			const waitMs = (Number.isFinite(hinted) ? Math.min(Math.max(hinted, 0) * 1e3, HttpClient.RETRY_AFTER_CAP_MS) : HttpClient.RETRY_AFTER_DEFAULT_MS) * (.9 + .2 * Math.random());
+			this.onRetry?.({
+				path,
+				code,
+				attempt,
+				waitMs
+			});
+			await sleepRacingAbort(waitMs, init.signal ?? null);
+		}
+	}
+	async execute(url, init) {
+		try {
+			return await this.fetchFn(url, init);
 		} catch (err) {
 			if (init.signal?.aborted) throw new AbortError$1(init.signal.reason ?? err);
 			if (err?.name === "AbortError") throw new AbortError$1(err.message);
@@ -2270,7 +2561,8 @@ var HttpClient = class HttpClient {
 	resolveOutgoing(path) {
 		if (!this.cdnBinding || !this.cdnBinding.cdn) return {
 			url: `${this.baseUrl}${path}`,
-			extraHeader: null
+			extraHeader: null,
+			routedToCdn: false
 		};
 		const applied = applyCdnAccess({
 			path,
@@ -2281,7 +2573,8 @@ var HttpClient = class HttpClient {
 		});
 		return {
 			url: applied.url,
-			extraHeader: applied.routedToCdn && applied.authHeader ? applied.authHeader : null
+			extraHeader: applied.routedToCdn && applied.authHeader ? applied.authHeader : null,
+			routedToCdn: applied.routedToCdn
 		};
 	}
 	async throwFromBody(res) {
@@ -2301,6 +2594,9 @@ var HttpClient = class HttpClient {
 		throw new EngineError$1(code, `HTTP ${res.status}`, { details: { status: res.status } });
 	}
 };
+_defineProperty(HttpClient, "MAX_RETRIES", 2);
+_defineProperty(HttpClient, "RETRY_AFTER_CAP_MS", 5e3);
+_defineProperty(HttpClient, "RETRY_AFTER_DEFAULT_MS", 1e3);
 function mapStatusToCode(status) {
 	if (status === 401) return EngineErrorCode$1.Unauthenticated;
 	if (status === 403) return EngineErrorCode$1.Forbidden;
@@ -2315,6 +2611,36 @@ function trySerialized(value) {
 	const result = EngineErrorPayloadSchema.safeParse(value);
 	return result.success ? result.data : null;
 }
+const RETRYABLE_503 = /* @__PURE__ */ new Set(["EngineBusy", "EngineRestarting"]);
+function isStreamBody(body) {
+	return typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+/** Read the error code from a 503 body without consuming the response. */
+async function peekErrorCode(res) {
+	try {
+		const code = (await res.clone().json())?.error?.code;
+		return typeof code === "string" ? code : null;
+	} catch {
+		return null;
+	}
+}
+function sleepRacingAbort(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new AbortError$1(signal.reason ?? "aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new AbortError$1(signal?.reason ?? "aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
 //#endregion
 //#region src/CloudEngine.ts
 /**
@@ -2340,6 +2666,24 @@ var CloudEngine = class CloudEngine {
 		options?.scope;
 		options?.identity;
 		const effectivePassword = options && "password" in options ? options.password ?? null : input.password ?? null;
+		if (input.kind === "share") {
+			const raw = shareSessionSource(this.http.baseUrl, input.shareToken, {
+				...input.sharePassword !== void 0 ? { password: input.sharePassword } : {},
+				fetch: this.http.fetchImpl
+			});
+			const token = async () => {
+				try {
+					return await raw();
+				} catch (error) {
+					throw error instanceof ShareExchangeError ? engineErrorFromShareExchange(error) : error;
+				}
+			};
+			return this.open({
+				kind: "token",
+				token,
+				password: input.password ?? null
+			}, options);
+		}
 		if (input.kind === "token") {
 			const tokenSource = input.token;
 			return AbortablePromise$1.run(async (signal) => {
@@ -2376,7 +2720,7 @@ var CloudEngine = class CloudEngine {
 				return handle;
 			});
 		}
-		return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `cloud engine supports OpenInput.kind === 'token' or 'id' (got '${input.kind}')`));
+		return AbortablePromise$1.rejectReason(new EngineError$1(EngineErrorCode$1.InvalidArg, `cloud engine supports OpenInput.kind === 'token', 'id', or 'share' (got '${input.kind}')`));
 	}
 	destroy() {
 		if (this.destroyed) return AbortablePromise$1.resolveValue(void 0);
@@ -2471,6 +2815,6 @@ 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 };
+export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, EngineError, EngineErrorCode, HttpClient, ShareExchangeError, cloudEngine, createCloudEngine, decodeUnverifiedClaims, engineErrorFromShareExchange, exchangeShareToken, shareSessionSource };
 
 //# sourceMappingURL=index.js.map