@cloudpdf/engine 3.0.0-next.7 → 3.0.0-next.9

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
+import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
 import { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
 import { SessionEventPublisher } from "@embedpdf/engine-services";
 //#region src/transport/HttpClient.d.ts
@@ -21,6 +21,30 @@ interface HttpClientOptions {
   sessionId?: string;
   /** Replace the global fetch (e.g. in Node tests with undici). */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Document affinity key: `X-CloudPDF-Doc` is sent BY DEFAULT on
+   * origin-bound doc requests so consistent-hash load balancers can pin
+   * a document's traffic to one warm replica. Routing hints are
+   * unconditional client behavior — whether they are USED is the
+   * operator's choice at the load balancer, never the app's. Derived
+   * from the request path (`/v1/docs/:docId/…` — the same extraction
+   * the Helm chart's uri-mode fallback uses); never sent on
+   * CDN-rewritten requests.
+   *
+   * `false` is an ESCAPE HATCH, not a feature toggle: use it only
+   * against a stale server whose CORS allowlist predates the header
+   * (browser preflights would fail) or behind a proxy that rejects
+   * unknown request headers.
+   */
+  docAffinityHeader?: boolean;
+  /** Observability: fired once per transport-level retry (engine busy /
+   *  restarting). Lets apps count sheds without wrapping every call. */
+  onRetry?: (info: {
+    path: string;
+    code: string;
+    attempt: number;
+    waitMs: number;
+  }) => void;
 }
 /**
  * Per-document binding for CDN URL rewriting. `CloudDocumentHandle`
@@ -51,6 +75,11 @@ declare class HttpClient {
   private readonly base;
   private readonly tokenFn;
   private readonly fetchFn;
+  private readonly docAffinityHeader;
+  private readonly onRetry;
+  private static readonly MAX_RETRIES;
+  private static readonly RETRY_AFTER_CAP_MS;
+  private static readonly RETRY_AFTER_DEFAULT_MS;
   private readonly sessionId;
   private cdnBinding;
   constructor(opts: HttpClientOptions);
@@ -150,6 +179,8 @@ declare class HttpClient {
   /** PATCH counterpart of {@link postMultipartJson} (binary-carrying mutations). */
   patchMultipartJson<T>(path: string, body: FormData, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
   postJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  /** POST a JSON body and return the raw binary response (pages.extract). */
+  postJsonBytes(path: string, body: unknown, signal: AbortSignal): Promise<Uint8Array>;
   /** POST a raw binary body (FDF/XFDF import) and parse the JSON response. */
   postBytesJson<T>(path: string, bytes: Uint8Array, contentType: string, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
   patchJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
@@ -158,6 +189,7 @@ declare class HttpClient {
   postEmpty(path: string, body: unknown, signal: AbortSignal): Promise<void>;
   private requestJson;
   private request;
+  private execute;
   private parseJsonResponse;
   /**
    * Decide where this request actually goes. With no CDN binding (or
@@ -264,6 +296,10 @@ interface ManifestAccessor {
   /** Same advance for a page delete, additionally dropping the deleted
    *  pages' manifest rows so per-page leaf URLs stop resolving locally. */
   applyPageDelete(cache: PageStructureCache, deletedPages: PageObjectNumber[]): void;
+  /** Page insert: the cached manifest has no rows for the fresh PONs (the
+   *  result carries only their object numbers), so the absorb drops the
+   *  cache for a lazy refetch instead of patching. */
+  applyPageInsert(cache: PageStructureCache): void;
   /** Advance the cached manifest's docVersion + metadataVersion after a metadata write. */
   applyMetadata(cache: MetadataCache): void;
   /** Advance the cached manifest's docVersion + attachmentsVersion after an
@@ -365,6 +401,18 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
    * 404 anyway — this keeps the failure local and instant).
    */
   private absorbPageDelete;
+  /**
+   * 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.
+   */
+  private absorbPageInsert;
   /**
    * Patch the cached manifest after a metadata write. Symmetric with
    * {@link absorbPageMove}: a metadata edit advances `docVersion` (so leaf
@@ -448,6 +496,9 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
   move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise$1<PageMoveResult>;
   rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation): AbortablePromise$1<PageRotateResult>;
   delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<PageDeleteResult>;
+  insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise$1<PageInsertResult>;
+  insertBlank(spec: PageInsertBlankSpec, destIndex?: number): AbortablePromise$1<PageInsertResult>;
+  extract(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<Uint8Array>;
   flatten(pageObjectNumbers: PageObjectNumber[], usage?: PageFlattenUsage): AbortablePromise$1<PageFlattenResult>;
 }
 //#endregion

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
+import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationListPageSnapshot, AnnotationListSnapshotAllPages, AnnotationMoveResult, AnnotationPatch, AnnotationRef, AnnotationUpdateResult, AttachmentContent, AttachmentsCache, DocumentAccessInfo, DocumentActionsService, DocumentAnnotationsService, DocumentAnnotationsService as DocumentAnnotationsService$1, DocumentAttachmentsService, DocumentCapabilities, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentHandle as DocumentHandle$1, DocumentIdentity, DocumentMetadata, DocumentPagesService, DocumentPagesService as DocumentPagesService$1, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSecurityService as DocumentSecurityService$1, DocumentSecurityState, DocumentUnlockInput, DocumentUnlockResult, Engine, Engine as Engine$1, EngineError, EngineError as EngineError$1, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, OpenInputShare, OpenOptions, OpenOptions as OpenOptions$1, PageAnnotationsService, PageAnnotationsService as PageAnnotationsService$1, PageDeleteResult, PageFlattenResult, PageFlattenUsage, PageGeometryService, PageGeometryService as PageGeometryService$1, PageGeometrySnapshot, PageHandle, PageHandle as PageHandle$1, PageImageHandle, PageImageOptions, PageInsertBlankSpec, PageInsertResult, PageListSnapshot, PageMoveResult, PageObjectNumber, PageRaster, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
 import { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
 import { SessionEventPublisher } from "@embedpdf/engine-services";
 //#region src/transport/HttpClient.d.ts
@@ -21,6 +21,30 @@ interface HttpClientOptions {
   sessionId?: string;
   /** Replace the global fetch (e.g. in Node tests with undici). */
   fetch?: typeof globalThis.fetch;
+  /**
+   * Document affinity key: `X-CloudPDF-Doc` is sent BY DEFAULT on
+   * origin-bound doc requests so consistent-hash load balancers can pin
+   * a document's traffic to one warm replica. Routing hints are
+   * unconditional client behavior — whether they are USED is the
+   * operator's choice at the load balancer, never the app's. Derived
+   * from the request path (`/v1/docs/:docId/…` — the same extraction
+   * the Helm chart's uri-mode fallback uses); never sent on
+   * CDN-rewritten requests.
+   *
+   * `false` is an ESCAPE HATCH, not a feature toggle: use it only
+   * against a stale server whose CORS allowlist predates the header
+   * (browser preflights would fail) or behind a proxy that rejects
+   * unknown request headers.
+   */
+  docAffinityHeader?: boolean;
+  /** Observability: fired once per transport-level retry (engine busy /
+   *  restarting). Lets apps count sheds without wrapping every call. */
+  onRetry?: (info: {
+    path: string;
+    code: string;
+    attempt: number;
+    waitMs: number;
+  }) => void;
 }
 /**
  * Per-document binding for CDN URL rewriting. `CloudDocumentHandle`
@@ -51,6 +75,11 @@ declare class HttpClient {
   private readonly base;
   private readonly tokenFn;
   private readonly fetchFn;
+  private readonly docAffinityHeader;
+  private readonly onRetry;
+  private static readonly MAX_RETRIES;
+  private static readonly RETRY_AFTER_CAP_MS;
+  private static readonly RETRY_AFTER_DEFAULT_MS;
   private readonly sessionId;
   private cdnBinding;
   constructor(opts: HttpClientOptions);
@@ -150,6 +179,8 @@ declare class HttpClient {
   /** PATCH counterpart of {@link postMultipartJson} (binary-carrying mutations). */
   patchMultipartJson<T>(path: string, body: FormData, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
   postJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  /** POST a JSON body and return the raw binary response (pages.extract). */
+  postJsonBytes(path: string, body: unknown, signal: AbortSignal): Promise<Uint8Array>;
   /** POST a raw binary body (FDF/XFDF import) and parse the JSON response. */
   postBytesJson<T>(path: string, bytes: Uint8Array, contentType: string, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
   patchJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
@@ -158,6 +189,7 @@ declare class HttpClient {
   postEmpty(path: string, body: unknown, signal: AbortSignal): Promise<void>;
   private requestJson;
   private request;
+  private execute;
   private parseJsonResponse;
   /**
    * Decide where this request actually goes. With no CDN binding (or
@@ -264,6 +296,10 @@ interface ManifestAccessor {
   /** Same advance for a page delete, additionally dropping the deleted
    *  pages' manifest rows so per-page leaf URLs stop resolving locally. */
   applyPageDelete(cache: PageStructureCache, deletedPages: PageObjectNumber[]): void;
+  /** Page insert: the cached manifest has no rows for the fresh PONs (the
+   *  result carries only their object numbers), so the absorb drops the
+   *  cache for a lazy refetch instead of patching. */
+  applyPageInsert(cache: PageStructureCache): void;
   /** Advance the cached manifest's docVersion + metadataVersion after a metadata write. */
   applyMetadata(cache: MetadataCache): void;
   /** Advance the cached manifest's docVersion + attachmentsVersion after an
@@ -365,6 +401,18 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
    * 404 anyway — this keeps the failure local and instant).
    */
   private absorbPageDelete;
+  /**
+   * 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.
+   */
+  private absorbPageInsert;
   /**
    * Patch the cached manifest after a metadata write. Symmetric with
    * {@link absorbPageMove}: a metadata edit advances `docVersion` (so leaf
@@ -448,6 +496,9 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
   move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise$1<PageMoveResult>;
   rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation): AbortablePromise$1<PageRotateResult>;
   delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<PageDeleteResult>;
+  insert(bytes: Uint8Array | ArrayBuffer, destIndex?: number): AbortablePromise$1<PageInsertResult>;
+  insertBlank(spec: PageInsertBlankSpec, destIndex?: number): AbortablePromise$1<PageInsertResult>;
+  extract(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<Uint8Array>;
   flatten(pageObjectNumbers: PageObjectNumber[], usage?: PageFlattenUsage): AbortablePromise$1<PageFlattenResult>;
 }
 //#endregion

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 { 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, 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
 /**
@@ -449,6 +449,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 +548,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) => {
@@ -809,9 +856,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);
@@ -1341,6 +1386,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 +1634,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)
 		};
@@ -1748,6 +1800,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),
@@ -1883,6 +1956,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 +2010,7 @@ function fallbackUnknownHead(id) {
 		access: {
 			required: true,
 			reasons: ["permissions-unknown"],
-			endpoint: wirePaths.access
+			endpoint: wirePaths.access(id, DEFAULT_LAYER_NAME)
 		}
 	};
 }
@@ -2042,6 +2118,8 @@ var HttpClient = class HttpClient {
 		_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.base = opts.baseUrl.replace(/\/$/, "");
@@ -2049,6 +2127,8 @@ var HttpClient = class HttpClient {
 		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() {
@@ -2279,6 +2359,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 });
@@ -2325,7 +2411,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();
@@ -2334,11 +2420,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);
@@ -2364,7 +2471,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,
@@ -2375,7 +2483,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) {
@@ -2395,6 +2504,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;
@@ -2409,6 +2521,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
 /**