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

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, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, 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`
@@ -48,12 +72,26 @@ interface HttpFileResponse {
   headers: Headers;
 }
 declare class HttpClient {
-  private readonly baseUrl;
+  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);
+  /** Normalized server base URL (no trailing slash). */
+  get baseUrl(): string;
+  /**
+   * 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(): typeof globalThis.fetch;
   /**
    * Return a clone of this client bound to a different bearer. Used
    * by `CloudEngine.open` to mint a per-handle client carrying the
@@ -141,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>;
@@ -149,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
@@ -255,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
@@ -356,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
@@ -396,10 +453,29 @@ declare class CloudDocumentAnnotationsService implements DocumentAnnotationsServ
   private readonly isClosed;
   private readonly manifest;
   constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor);
+  /**
+   * 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(): AbortablePromise$1<AnnotationListSnapshotAllPages>;
+  /** 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. */
+  private readBulkAt;
   listRaw(pageObjectNumber: PageObjectNumber): AbortablePromise$1<AnnotationListPageSnapshot>;
+  /** 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. */
+  private pagePathAt;
+  private versionedPagePath;
   beginWeakEdit(pageObjectNumbers: readonly PageObjectNumber[]): AbortablePromise$1<WeakAnnotationEditSession>;
-  private readCurrentPage;
 }
 //#endregion
 //#region src/document/CloudDocumentPagesService.d.ts
@@ -439,6 +515,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
@@ -572,6 +651,69 @@ interface UnverifiedClaims {
 }
 declare function decodeUnverifiedClaims(token: string): UnverifiedClaims;
 //#endregion
+//#region src/share.d.ts
+/**
+ * Share-session exchange: the client half of the no-backend embed flow.
+ *
+ * A share token (`shr_…`) is a REFERENCE to a stored grant on the
+ * server, not a credential — `exchangeShareToken` trades it for an
+ * ordinary short-lived doc JWT, and `shareSessionSource` wraps that in
+ * a self-renewing token source. Because the engine's transport
+ * invokes its token source on every request (and SSE reconnects call
+ * it again), renewal is nothing more than "exchange again when the
+ * cached session is nearly out" — no timers, no listeners.
+ *
+ * The endpoint requires a browser `Origin` header (the server checks
+ * it against the grant's allowlist). Browsers attach it automatically;
+ * non-browser callers (tests, SSR) must supply a `fetch` that does.
+ */
+interface ShareSession {
+  /** Doc-scoped session JWT carrying the grant's capabilities. */
+  token: string;
+  docId: string;
+  layerName: string;
+  /** Unix seconds when `token` expires. */
+  expiresAt: number;
+}
+interface ShareExchangeOptions {
+  /** Passphrase for protected grants (`SharePasswordRequired` otherwise). */
+  password?: string;
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * 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`.
+ */
+declare class ShareExchangeError extends Error {
+  readonly code: string;
+  readonly status: number;
+  constructor(code: string, message: string, status: number);
+}
+declare function exchangeShareToken(baseUrl: string, shareToken: string, opts?: ShareExchangeOptions): Promise<ShareSession>;
+/**
+ * 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.
+ */
+declare function engineErrorFromShareExchange(error: ShareExchangeError): EngineError$1;
+/**
+ * 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.
+ */
+declare function shareSessionSource(baseUrl: string, shareToken: string, opts?: ShareExchangeOptions): () => Promise<string>;
+//#endregion
 //#region src/index.d.ts
 declare function createCloudEngine(opts: CloudEngineOptions): CloudEngine;
 /**
@@ -596,5 +738,5 @@ declare function createCloudEngine(opts: CloudEngineOptions): CloudEngine;
  */
 declare function cloudEngine(opts: CloudEngineOptions): CloudEngine;
 //#endregion
-export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, type CloudEngineOptions, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, type DocumentAccessInfo, type DocumentAnnotationsService, type DocumentCapabilities, type DocumentHandle, type DocumentIdentity, type DocumentPagesService, type DocumentSecurityService, type DocumentSecurityState, type DocumentUnlockInput, type DocumentUnlockResult, type Engine, EngineError, EngineErrorCode, type EngineFactory, HttpClient, type HttpClientOptions, type MetadataService, type OpenInput, type OpenOptions, type PageAnnotationsService, type PageGeometryService, type PageHandle, type PageRenderService, type PageTextService, type PdfSaveMode, type TokenSource, type UnverifiedClaims, cloudEngine, createCloudEngine, decodeUnverifiedClaims };
+export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, type CloudEngineOptions, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, type DocumentAccessInfo, type DocumentAnnotationsService, type DocumentCapabilities, type DocumentHandle, type DocumentIdentity, type DocumentPagesService, type DocumentSecurityService, type DocumentSecurityState, type DocumentUnlockInput, type DocumentUnlockResult, type Engine, EngineError, EngineErrorCode, type EngineFactory, HttpClient, type HttpClientOptions, type MetadataService, type OpenInput, type OpenInputShare, type OpenOptions, type PageAnnotationsService, type PageGeometryService, type PageHandle, type PageRenderService, type PageTextService, type PdfSaveMode, ShareExchangeError, type ShareExchangeOptions, type ShareSession, type TokenSource, type UnverifiedClaims, cloudEngine, createCloudEngine, decodeUnverifiedClaims, engineErrorFromShareExchange, exchangeShareToken, shareSessionSource };
 //# sourceMappingURL=index.d.cts.map

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, EngineErrorCode, EngineFactory, MetadataCache, MetadataPatch, MetadataService, MetadataService as MetadataService$1, MetadataUpdateResult, MutationMeta, OpenInput, OpenInput as OpenInput$1, 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`
@@ -48,12 +72,26 @@ interface HttpFileResponse {
   headers: Headers;
 }
 declare class HttpClient {
-  private readonly baseUrl;
+  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);
+  /** Normalized server base URL (no trailing slash). */
+  get baseUrl(): string;
+  /**
+   * 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(): typeof globalThis.fetch;
   /**
    * Return a clone of this client bound to a different bearer. Used
    * by `CloudEngine.open` to mint a per-handle client carrying the
@@ -141,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>;
@@ -149,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
@@ -255,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
@@ -356,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
@@ -396,10 +453,29 @@ declare class CloudDocumentAnnotationsService implements DocumentAnnotationsServ
   private readonly isClosed;
   private readonly manifest;
   constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor);
+  /**
+   * 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(): AbortablePromise$1<AnnotationListSnapshotAllPages>;
+  /** 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. */
+  private readBulkAt;
   listRaw(pageObjectNumber: PageObjectNumber): AbortablePromise$1<AnnotationListPageSnapshot>;
+  /** 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. */
+  private pagePathAt;
+  private versionedPagePath;
   beginWeakEdit(pageObjectNumbers: readonly PageObjectNumber[]): AbortablePromise$1<WeakAnnotationEditSession>;
-  private readCurrentPage;
 }
 //#endregion
 //#region src/document/CloudDocumentPagesService.d.ts
@@ -439,6 +515,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
@@ -572,6 +651,69 @@ interface UnverifiedClaims {
 }
 declare function decodeUnverifiedClaims(token: string): UnverifiedClaims;
 //#endregion
+//#region src/share.d.ts
+/**
+ * Share-session exchange: the client half of the no-backend embed flow.
+ *
+ * A share token (`shr_…`) is a REFERENCE to a stored grant on the
+ * server, not a credential — `exchangeShareToken` trades it for an
+ * ordinary short-lived doc JWT, and `shareSessionSource` wraps that in
+ * a self-renewing token source. Because the engine's transport
+ * invokes its token source on every request (and SSE reconnects call
+ * it again), renewal is nothing more than "exchange again when the
+ * cached session is nearly out" — no timers, no listeners.
+ *
+ * The endpoint requires a browser `Origin` header (the server checks
+ * it against the grant's allowlist). Browsers attach it automatically;
+ * non-browser callers (tests, SSR) must supply a `fetch` that does.
+ */
+interface ShareSession {
+  /** Doc-scoped session JWT carrying the grant's capabilities. */
+  token: string;
+  docId: string;
+  layerName: string;
+  /** Unix seconds when `token` expires. */
+  expiresAt: number;
+}
+interface ShareExchangeOptions {
+  /** Passphrase for protected grants (`SharePasswordRequired` otherwise). */
+  password?: string;
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * 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`.
+ */
+declare class ShareExchangeError extends Error {
+  readonly code: string;
+  readonly status: number;
+  constructor(code: string, message: string, status: number);
+}
+declare function exchangeShareToken(baseUrl: string, shareToken: string, opts?: ShareExchangeOptions): Promise<ShareSession>;
+/**
+ * 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.
+ */
+declare function engineErrorFromShareExchange(error: ShareExchangeError): EngineError$1;
+/**
+ * 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.
+ */
+declare function shareSessionSource(baseUrl: string, shareToken: string, opts?: ShareExchangeOptions): () => Promise<string>;
+//#endregion
 //#region src/index.d.ts
 declare function createCloudEngine(opts: CloudEngineOptions): CloudEngine;
 /**
@@ -596,5 +738,5 @@ declare function createCloudEngine(opts: CloudEngineOptions): CloudEngine;
  */
 declare function cloudEngine(opts: CloudEngineOptions): CloudEngine;
 //#endregion
-export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, type CloudEngineOptions, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, type DocumentAccessInfo, type DocumentAnnotationsService, type DocumentCapabilities, type DocumentHandle, type DocumentIdentity, type DocumentPagesService, type DocumentSecurityService, type DocumentSecurityState, type DocumentUnlockInput, type DocumentUnlockResult, type Engine, EngineError, EngineErrorCode, type EngineFactory, HttpClient, type HttpClientOptions, type MetadataService, type OpenInput, type OpenOptions, type PageAnnotationsService, type PageGeometryService, type PageHandle, type PageRenderService, type PageTextService, type PdfSaveMode, type TokenSource, type UnverifiedClaims, cloudEngine, createCloudEngine, decodeUnverifiedClaims };
+export { AbortError, AbortablePromise, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, type CloudEngineOptions, CloudMetadataService, CloudPageAnnotationsService, CloudPageGeometryService, CloudPageHandle, CloudPageRenderService, type DocumentAccessInfo, type DocumentAnnotationsService, type DocumentCapabilities, type DocumentHandle, type DocumentIdentity, type DocumentPagesService, type DocumentSecurityService, type DocumentSecurityState, type DocumentUnlockInput, type DocumentUnlockResult, type Engine, EngineError, EngineErrorCode, type EngineFactory, HttpClient, type HttpClientOptions, type MetadataService, type OpenInput, type OpenInputShare, type OpenOptions, type PageAnnotationsService, type PageGeometryService, type PageHandle, type PageRenderService, type PageTextService, type PdfSaveMode, ShareExchangeError, type ShareExchangeOptions, type ShareSession, type TokenSource, type UnverifiedClaims, cloudEngine, createCloudEngine, decodeUnverifiedClaims, engineErrorFromShareExchange, exchangeShareToken, shareSessionSource };
 //# sourceMappingURL=index.d.ts.map