@cloudpdf/engine 3.0.0-next.0

package/dist/index.d.ts

@@ -0,0 +1,600 @@
+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 { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
+import { SessionEventPublisher } from "@embedpdf/engine-services";
+//#region src/transport/HttpClient.d.ts
+interface HttpClientOptions {
+  baseUrl: string;
+  /**
+   * Optional bearer token. Either a string or a function that
+   * returns a fresh token on every call (so callers can rotate
+   * without re-creating the engine). When absent, requests go out
+   * without an `Authorization` header — useful for the public-share
+   * scenario where the doc-scoped token is provided per-`open` and
+   * the engine itself has no engine-level credentials.
+   */
+  token?: string | (() => string | Promise<string>);
+  /**
+   * Engine-instance session id, sent as `X-Engine-Session-Id` on every
+   * request. The server stores it on mutation audit rows so this
+   * instance's SSE stream can drop its own echoes (exactly-once events).
+   */
+  sessionId?: string;
+  /** Replace the global fetch (e.g. in Node tests with undici). */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * Per-document binding for CDN URL rewriting. `CloudDocumentHandle`
+ * calls `setCdnAccess` after `/v1/access` succeeds; the HttpClient
+ * then runs every outgoing request through `applyCdnAccess` so
+ * granted resources are routed to the CDN with the matching signed
+ * query params (or cookies/auth header for the cookie/header
+ * adapter modes).
+ *
+ * Set to `null` when the session is reset or when `/access` was
+ * never called (public-share with no CDN configured).
+ */
+interface CdnBinding {
+  readonly cdn: CdnAccessInfoForApply | null;
+  readonly docId: string;
+  readonly layerName: string;
+}
+/**
+ * A raw-bytes response plus its headers. The attachment-file leaves carry
+ * their metadata as headers (`Content-Type`, `X-EmbedPDF-File-Name`), so
+ * unlike `getBytes` the caller needs the `Headers` object back.
+ */
+interface HttpFileResponse {
+  bytes: Uint8Array;
+  headers: Headers;
+}
+declare class HttpClient {
+  private readonly baseUrl;
+  private readonly tokenFn;
+  private readonly fetchFn;
+  private readonly sessionId;
+  private cdnBinding;
+  constructor(opts: HttpClientOptions);
+  /**
+   * Return a clone of this client bound to a different bearer. Used
+   * by `CloudEngine.open` to mint a per-handle client carrying the
+   * per-open token, so each opened document's RPCs go out under
+   * the right authorization without disturbing the engine-level
+   * token.
+   */
+  withToken(token: string | (() => string | Promise<string>)): HttpClient;
+  /**
+   * Raw streaming GET (the SSE channel). Same auth/session headers and
+   * error mapping as every other request; the caller owns the body stream.
+   */
+  stream(path: string, headers: Record<string, string>, signal: AbortSignal): Promise<Response>;
+  /**
+   * Install (or clear) the per-session CDN binding. Pass `null` to
+   * route everything to origin again — useful on session close or
+   * when an adapter swap happens mid-session (rare).
+   *
+   * The HttpClient stays dumb about WHEN to do this; the cloud
+   * document handle pushes the binding in after /access succeeds.
+   *
+   * Side effect: in the browser, signedCookies are written to
+   * `document.cookie` once per setCdnAccess call so the CDN edge
+   * receives them on subsequent fetches. Node side ignores cookies
+   * for now (cookie jar wiring deferred until needed for tests).
+   */
+  setCdnAccess(binding: CdnBinding | null): void;
+  /** Current CDN binding (or null). Exposed for diagnostics/tests. */
+  get currentCdnBinding(): CdnBinding | null;
+  absoluteUrl(path: string): string;
+  getBlob(path: string, signal: AbortSignal): Promise<Blob>;
+  getBytes(path: string, signal: AbortSignal): Promise<Uint8Array>;
+  /**
+   * Resolve the current bearer token. Awaits the user-supplied
+   * token factory if it returns a promise. Used by the cloud
+   * engine to read doc-scoped claims **without** verifying — the
+   * server is the verifier of record. Throws when no token is
+   * configured.
+   */
+  currentToken(): Promise<string>;
+  getJson<T>(path: string, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  /**
+   * GET a versioned URL with transparent stale-version recovery. If
+   * the server returns 404 (the well-known "this version is gone"
+   * signal for content-addressed reads), call `onStaleVersion` (which
+   * the caller wires to a manifest refresh), then re-resolve `buildPath`
+   * and retry the GET exactly once. Any non-404 error propagates.
+   *
+   * The retry budget is hard-capped at 1: after a refresh, if the
+   * server's idea of the current version is still ahead of the
+   * client's view, the second request fails normally — this matches
+   * the CDN cache invariant ("a versioned URL's bytes are immutable
+   * for its lifetime").
+   */
+  getJsonWithRefresh<T>(buildPath: (signal: AbortSignal) => Promise<string>, parser: (raw: unknown) => T, onStaleVersion: (signal: AbortSignal) => Promise<void>, signal: AbortSignal): Promise<T>;
+  /**
+   * GET a `multipart/form-data` body and parse it with the platform's
+   * `Response.formData()` (works in browsers and undici). Text parts come
+   * back as strings, parts with a filename as `Blob`s.
+   */
+  getFormData(path: string, signal: AbortSignal): Promise<FormData>;
+  /**
+   * `getFormData` with the same single-retry stale-version recovery as
+   * {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+   * `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+   */
+  getFormDataWithRefresh(buildPath: (signal: AbortSignal) => Promise<string>, onStaleVersion: (signal: AbortSignal) => Promise<void>, signal: AbortSignal): Promise<FormData>;
+  /**
+   * `getBlob` with the same single-retry stale-version recovery as
+   * {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+   * `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+   * Render blobs ride this rail: a scope flip re-resolves the
+   * doc-vs-layer path family instead of failing on a stale URL.
+   */
+  getBlobWithRefresh(buildPath: (signal: AbortSignal) => Promise<string>, onStaleVersion: (signal: AbortSignal) => Promise<void>, signal: AbortSignal): Promise<Blob>;
+  /** GET raw bytes plus the response headers (attachment-file leaves). */
+  getFile(path: string, signal: AbortSignal): Promise<HttpFileResponse>;
+  /**
+   * `getFile` with the same single-retry stale-version recovery as
+   * {@link getJsonWithRefresh}: a 404 on a versioned URL triggers
+   * `onStaleVersion` (a manifest refresh) and one re-resolve + retry.
+   */
+  getFileWithRefresh(buildPath: (signal: AbortSignal) => Promise<string>, onStaleVersion: (signal: AbortSignal) => Promise<void>, signal: AbortSignal): Promise<HttpFileResponse>;
+  postMultipartJson<T>(path: string, body: FormData, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  /** 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 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>;
+  deleteJson<T>(path: string, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  deleteEmpty(path: string, signal: AbortSignal): Promise<void>;
+  postEmpty(path: string, body: unknown, signal: AbortSignal): Promise<void>;
+  private requestJson;
+  private request;
+  private parseJsonResponse;
+  /**
+   * Decide where this request actually goes. With no CDN binding (or
+   * binding's `cdn` is null) every request stays on origin. Otherwise
+   * `applyCdnAccess` decides per-request based on the resource the
+   * path resolves to (and whether the caller's scope granted CDN
+   * access to it).
+   */
+  private resolveOutgoing;
+  private throwFromBody;
+}
+//#endregion
+//#region src/CloudEngine.d.ts
+interface CloudEngineOptions extends HttpClientOptions {}
+/**
+ * Cloud engine: speaks the same Engine interface as @embedpdf/engine
+ * but routes everything through HTTPS to a remote @cloudpdf/server (or
+ * CloudPDF SaaS). Identical observable contract; only the transport differs.
+ */
+declare class CloudEngine implements Engine$1 {
+  private readonly http;
+  /** This engine instance's identity on every event's `origin.sessionId`. */
+  private readonly sessionId;
+  static fromOptions(opts: CloudEngineOptions): CloudEngine;
+  private destroyed;
+  private constructor();
+  open(input: OpenInput$1, options?: OpenOptions$1): AbortablePromise$1<DocumentHandle$1>;
+  destroy(): AbortablePromise$1<void>;
+}
+//#endregion
+//#region src/document/CloudDocumentSearchService.d.ts
+/**
+ * Cloud search transport: versioned GETs, one per budgeted slice.
+ *
+ * Every slice URL is a canonical cache key — the search token pins the
+ * layer's content epoch (computed from the cached manifest), the
+ * CANONICAL query (default-fold literals collapse case/diacritic
+ * variants into one entry), and the resume position. Identical searches
+ * from any reader of the document hit the same CDN entry; matches are
+ * all that ever crosses the trust boundary, and the rects/full endpoint
+ * split keeps permission tiers in disjoint cache namespaces.
+ *
+ * Staleness rides the standard versioned-read signal: a first slice
+ * answered `NotFound` means OUR manifest is stale → refresh and retry
+ * once; a continuation answered `NotFound` means the document changed
+ * mid-search → `InvalidArg`, same contract as the local engine's cursor.
+ */
+declare class CloudDocumentSearchService implements DocumentSearchService {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly isClosed;
+  private readonly manifest;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor);
+  query(request: SearchRequest): AbortablePromise$1<SearchSlice>;
+}
+//#endregion
+//#region src/document/CloudMetadataService.d.ts
+declare class CloudMetadataService implements MetadataService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly isClosed;
+  private readonly manifest;
+  private readonly publisher;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
+  /**
+   * Document metadata read. The Info-dict JSON lives at the
+   * content-addressed `/metadata@metadataVersion=N` leaf (not in the
+   * manifest); the manifest only publishes the `metadataVersion` pointer.
+   * So `read()` pulls `metadataVersion` from the cached manifest, fetches
+   * the leaf, and on a 404 (stale pointer) transparently refreshes the
+   * manifest and retries once. `metadataVersion` bumps only on metadata
+   * writes, so this leaf stays cached across page and annotation edits.
+   */
+  read(): AbortablePromise$1<DocumentMetadata>;
+  update(patch: MetadataPatch): AbortablePromise$1<MetadataUpdateResult>;
+}
+//#endregion
+//#region src/document/CloudDocumentHandle.d.ts
+/**
+ * Read accessor handed to every `CloudPage…Service`. The closure
+ * captures `this` so the services don't carry a direct reference
+ * back to the document handle (smaller circular-ref surface, easier
+ * to mock in unit tests).
+ */
+interface ManifestAccessor {
+  /** Cached manifest (cold-fetched once, kept across requests). */
+  get(signal: AbortSignal): Promise<DocumentManifest>;
+  /** Force re-fetch of `/head` + `/manifest@docVersion=N`; replaces the cache. */
+  refresh(signal: AbortSignal): Promise<DocumentManifest>;
+  /**
+   * Absorb mutation-returned state/cache deltas when safe. `owns` names the
+   * planes this mutation kind takes ownership of (the monotone-flip
+   * rule): annotation/form writes own `annotations`; flatten and
+   * redaction-apply own `content + annotations`. The flip runs even when
+   * the version-gated delta merge is skipped — scopes only ever move
+   * base → layer, so any observed mutation proves the plane diverged.
+   */
+  apply(meta: MutationMeta, owns: readonly LayerScopePlane[]): void;
+  /** Advance the cached manifest's docVersion + layoutVersion after a page
+   *  STRUCTURE op that keeps the page set intact (move, rotate). */
+  applyPageStructure(cache: PageStructureCache): void;
+  /** 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;
+  /** Advance the cached manifest's docVersion + metadataVersion after a metadata write. */
+  applyMetadata(cache: MetadataCache): void;
+  /** Advance the cached manifest's docVersion + attachmentsVersion after an
+   *  attachment create/delete. */
+  applyAttachments(cache: AttachmentsCache): void;
+}
+declare class CloudDocumentHandle implements DocumentHandle$1 {
+  private readonly http;
+  private readonly layerName;
+  readonly id: string;
+  readonly capabilities: {
+    readonly weakAnnotationEditSessions: "required";
+    readonly pageEditSessions: "unsupported";
+  };
+  readonly metadata: CloudMetadataService;
+  readonly annotations: DocumentAnnotationsService$1;
+  readonly actions: DocumentActionsService;
+  readonly attachments: DocumentAttachmentsService;
+  readonly forms: DocumentFormsService;
+  readonly search: CloudDocumentSearchService;
+  readonly pages: DocumentPagesService$1;
+  readonly redaction: DocumentRedactionService;
+  readonly security: DocumentSecurityService$1;
+  readonly render: DocumentRenderService;
+  readonly events: DocumentEventStream;
+  private readonly publisher;
+  private readonly hub;
+  private readonly sessionId;
+  private sseClient;
+  private sseSubscribers;
+  private closed;
+  /**
+   * Cached current manifest. Populated on first read by `getManifest`
+   * (or any `page().*` call that needs to know a version). Replaced
+   * wholesale on `refreshManifest`. Cleared on `close`.
+   *
+   * Memory model: one DocumentManifest per open handle. Per-page
+   * version reads are O(pages.length) `.find(...)` lookups; if a
+   * profiling pass ever shows that as hot, swap for a Map keyed by
+   * `pageObjectNumber`. Today's documents are page-sparse so the
+   * scan is cheaper than the hash overhead.
+   */
+  private manifestCache;
+  private inflightManifest;
+  private manifestFloorVersion;
+  private pendingInitialHead;
+  private readonly manifestAccessor;
+  constructor(http: HttpClient, id: string, layerName?: string, initialHead?: DocumentHead,
+  /**
+   * The doc-scoped JWT the engine was opened with, decoded
+   * unverified to populate the security service's local-fallback
+   * `effectiveScope` / `identity` accessors. Optional for backward
+   * compatibility; without it the local-fallback path returns an
+   * empty scope and null identity until /access is called.
+   */
+  initialToken?: string | null, sessionId?: string);
+  page(pageObjectNumber: PageObjectNumber): PageHandle$1;
+  download(opts?: {
+    mode?: PdfSaveMode$1;
+  }): AbortablePromise$1<Uint8Array>;
+  /**
+   * Return the cached manifest, fetching cold-cache once if needed.
+   * Concurrent callers share a single inflight request (singleflight)
+   * so an N-page handle that opens N services in parallel still
+   * triggers exactly one `/head` + `/manifest@docVersion=N` round-trip.
+   */
+  getManifest(signal: AbortSignal): Promise<DocumentManifest>;
+  /**
+   * Force re-fetch. Used by the transparent-retry path when a leaf
+   * URL returns 404 (stale version). Replaces `manifestCache`
+   * wholesale so the next `getManifest()` is a Map lookup.
+   */
+  refreshManifest(signal: AbortSignal): Promise<DocumentManifest>;
+  /**
+   * Monotone plane-scope flip: mark the planes a mutation OWNS as layer-scoped in
+   * the cached manifest. Scopes only ever move base → layer (no revert op
+   * exists), so flipping is safe under ANY event ordering — a duplicate or
+   * out-of-order event still proves the plane diverged at some point — and
+   * the manifest fetch stays the authoritative source (the 404 → refresh
+   * rail heals any miss, e.g. a future mutation kind this client doesn't
+   * know about).
+   */
+  private flipScopes;
+  absorbMutation(meta: MutationMeta, owns: readonly LayerScopePlane[]): void;
+  /**
+   * Patch the cached manifest after a set-preserving page-structure op (move,
+   * rotate). Both are purely structural: they advance `docVersion` (so leaf
+   * URLs re-resolve) and `layoutVersion` (so the /layout leaf re-fetches),
+   * but leave every per-page pin untouched — a rotate renders the SAME
+   * normalized bitmaps, a move the same pages. We raise the floor
+   * unconditionally and, when our cache is exactly one version behind,
+   * advance it in place; otherwise we drop it and refetch lazily.
+   */
+  private absorbPageStructure;
+  /**
+   * Patch the cached manifest after a page delete: the shared structural
+   * advance plus dropping the deleted pages' manifest rows, so no leaf URL
+   * for a retired PON can be built from the cache (a stale request would
+   * 404 anyway — this keeps the failure local and instant).
+   */
+  private absorbPageDelete;
+  /**
+   * Patch the cached manifest after a metadata write. Symmetric with
+   * {@link absorbPageMove}: a metadata edit advances `docVersion` (so leaf
+   * URLs re-resolve) and `metadataVersion` (so the /metadata leaf re-fetches),
+   * but leaves `layoutVersion` and every per-page pin untouched. Raise the
+   * floor unconditionally and, when our cache is exactly one version behind,
+   * advance it in place; otherwise drop it and refetch lazily.
+   */
+  private absorbMetadata;
+  /**
+   * Patch the cached manifest after an attachment create/delete. Symmetric
+   * with {@link absorbMetadata}: an attachment write advances `docVersion`
+   * (so leaf URLs re-resolve) and `attachmentsVersion` (so the /attachments
+   * listing and /attachment-files leaves re-fetch), but leaves
+   * `layoutVersion` and every per-page pin untouched. Raise the floor
+   * unconditionally and, when our cache is exactly one version behind,
+   * advance it in place; otherwise drop it and refetch lazily.
+   */
+  private absorbAttachments;
+  private startManifestFetch;
+  private fetchManifest;
+  private consumeInitialHead;
+  private fetchManifestForHead;
+  close(): AbortablePromise$1<void>;
+  private retainRemoteStream;
+  private releaseRemoteStream;
+  /** Patch the cached manifest from a REMOTE event's coherence pins — the
+   *  same absorb rails local mutations use, so reads stay warm no matter
+   *  whose hand caused the change. */
+  private absorbRemoteEvent;
+}
+//#endregion
+//#region src/document/CloudDocumentAnnotationsService.d.ts
+declare class CloudDocumentAnnotationsService implements DocumentAnnotationsService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly isClosed;
+  private readonly manifest;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor);
+  listRawAll(): AbortablePromise$1<AnnotationListSnapshotAllPages>;
+  listRaw(pageObjectNumber: PageObjectNumber): AbortablePromise$1<AnnotationListPageSnapshot>;
+  beginWeakEdit(pageObjectNumbers: readonly PageObjectNumber[]): AbortablePromise$1<WeakAnnotationEditSession>;
+  private readCurrentPage;
+}
+//#endregion
+//#region src/document/CloudDocumentPagesService.d.ts
+/**
+ * Cloud-side document pages service. Mirrors `LocalDocumentPagesService`
+ * over HTTP: GET /pages for `list`, POST /pages/move for the reorder.
+ *
+ * Page identity rule (locked with the user, do not change):
+ *   - Pages are addressed exclusively by their indirect
+ *     `pageObjectNumber`. The wire never sends a page index for a
+ *     mutation. This keeps multi-call client logic from having to
+ *     account for index drift between requests.
+ *   - Successful `move()` returns the new `layout` (order + geometry) plus
+ *     cloud coherence pins. The server does NOT bump per-page revisions on a
+ *     page move (page reorder is intentionally outside the weak-ref staleness
+ *     model), only `docVersion` + `layoutVersion`.
+ */
+declare class CloudDocumentPagesService implements DocumentPagesService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly isClosed;
+  private readonly manifest;
+  private readonly publisher;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
+  /**
+   * Page-geometry list. The geometry bytes live at the content-addressed
+   * `/layout@layoutVersion=N` leaf (not in the manifest); the manifest only
+   * publishes the `layoutVersion` pointer. So `list()` reads `layoutVersion`
+   * from the cached manifest, fetches the layout leaf, and on a 404 (stale
+   * pointer) transparently refreshes the manifest and retries once — the
+   * same ladder the per-page text/geometry reads use. `layoutVersion` bumps
+   * only on structural page ops, so this leaf stays cached across content
+   * and annotation edits.
+   */
+  list(): AbortablePromise$1<PageListSnapshot>;
+  move(pageObjectNumbers: PageObjectNumber[], destIndex: number): AbortablePromise$1<PageMoveResult>;
+  rotate(pageObjectNumbers: PageObjectNumber[], rotation: PageRotation): AbortablePromise$1<PageRotateResult>;
+  delete(pageObjectNumbers: PageObjectNumber[]): AbortablePromise$1<PageDeleteResult>;
+  flatten(pageObjectNumbers: PageObjectNumber[], usage?: PageFlattenUsage): AbortablePromise$1<PageFlattenResult>;
+}
+//#endregion
+//#region src/document/CloudPageAnnotationsService.d.ts
+/**
+ * Cloud-side page annotation service. Mirrors the local wiring: each
+ * call produces an `AbortablePromise` that propagates `signal.abort()`
+ * down to `fetch` and validates the JSON response with the wire-stable
+ * Zod schema.
+ *
+ * Reads use immutable versioned layer URLs discovered from the
+ * manifest. Mutations use unversioned layer URLs and are never cached.
+ */
+declare class CloudPageAnnotationsService implements PageAnnotationsService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly pageObjectNumber;
+  private readonly isClosed;
+  private readonly manifest;
+  private readonly publisher;
+  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
+  list(): AbortablePromise$1<AnnotationListPageSnapshot>;
+  renderAppearances(_options?: AnnotationAppearanceRenderOptions): AbortablePromise$1<AnnotationAppearancesResult>;
+  renderAppearanceImages(options?: AnnotationAppearanceImageOptions): AbortablePromise$1<AnnotationAppearanceImagesResult>;
+  /**
+   * Decode and return the file embedded in a FileAttachment annotation.
+   * A read over the immutable `attachment-files` leaf, pinned by the
+   * manifest's `attachmentsVersion` (annotation-level files re-key on the
+   * same pin as document-level ones), with the same stale-404 refresh
+   * retry as {@link list}. Weak `index` refs cannot be spliced into a GET
+   * URL (no body to carry the revision), so bytes reads require a stable
+   * id — the same `:annotKey` routing update()/delete() use.
+   */
+  downloadFile(ref: AnnotationRef): AbortablePromise$1<AttachmentContent>;
+  create(draft: AnnotationDraft): AbortablePromise$1<AnnotationCreateResult>;
+  update(ref: AnnotationRef, patch: AnnotationPatch): AbortablePromise$1<AnnotationUpdateResult>;
+  /** PATCH as plain JSON, or as multipart when the patch carried binaries. */
+  private patchMutation;
+  delete(ref: AnnotationRef): AbortablePromise$1<AnnotationDeleteResult>;
+  move(refs: AnnotationRef[], toIndex: number): AbortablePromise$1<AnnotationMoveResult>;
+  /**
+   * Patch the cached manifest, then publish the mutation to the document's
+   * event stream (in that order — listeners reading the manifest in their
+   * callback must see post-mutation state). Each call site pairs the event
+   * `type` with the matching result by construction; the cast localizes that
+   * pairing here instead of widening every site.
+   */
+  private absorbMutation;
+}
+//#endregion
+//#region src/document/CloudPageGeometryService.d.ts
+declare class CloudPageGeometryService implements PageGeometryService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly pageObjectNumber;
+  private readonly isClosed;
+  private readonly manifest;
+  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor);
+  read(): AbortablePromise$1<PageGeometrySnapshot>;
+}
+//#endregion
+//#region src/document/CloudPageRenderService.d.ts
+declare class CloudPageRenderService implements PageRenderService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly pageObjectNumber;
+  private readonly isClosed;
+  private readonly manifest;
+  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor);
+  image(options?: PageImageOptions): AbortablePromise$1<PageImageHandle>;
+  raw(_options?: PageRenderOptions): AbortablePromise$1<PageRaster>;
+}
+//#endregion
+//#region src/document/CloudPageTextService.d.ts
+/**
+ * Cloud-side per-page text service. `read()` fetches the
+ * content-addressed URL `/v1/docs/:id/text/pages/:pon/data@contentVersion=N`, where
+ * `:P` is the page's current `contentVersion` from the cached
+ * manifest. On a 404 (stale version) the SDK transparently refreshes
+ * `/head` + `/manifest@docVersion=N`, rebuilds the URL with the fresh `cN`,
+ * and retries exactly once.
+ */
+declare class CloudPageTextService implements PageTextService$1 {
+  private readonly http;
+  private readonly docId;
+  private readonly layerName;
+  private readonly pageObjectNumber;
+  private readonly isClosed;
+  private readonly manifest;
+  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor);
+  read(): AbortablePromise$1<PageTextSnapshot>;
+}
+//#endregion
+//#region src/document/CloudPageHandle.d.ts
+declare class CloudPageHandle implements PageHandle$1 {
+  readonly pageObjectNumber: PageObjectNumber;
+  readonly pageIndex: number;
+  readonly annotations: CloudPageAnnotationsService;
+  readonly text: CloudPageTextService;
+  readonly geometry: CloudPageGeometryService;
+  readonly render: CloudPageRenderService;
+  constructor(pageObjectNumber: PageObjectNumber, pageIndex: number, http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
+}
+//#endregion
+//#region src/transport/decodeUnverifiedClaims.d.ts
+/**
+ * Lightweight, **unverified** JWT payload decoder.
+ *
+ * We use this on the SDK side purely to extract routing information
+ * (the `doc_id` claim) so we know which `/v1/docs/:id/head` URL to
+ * hit. Signature verification is the server's job — Layer 2 of the
+ * token-class-confusion defense in `JwtVerifier.coerceClaims`
+ * rejects anything malformed before the bytes are accepted.
+ *
+ * This module is intentionally cryptography-free: it never imports
+ * `crypto` or `jose`. That keeps the SDK lean for browser bundles
+ * (jose adds ~50KB minified) and means a misconfigured customer
+ * can't accidentally rely on client-side verification.
+ */
+interface UnverifiedClaims {
+  doc_id?: string;
+  tenant_id?: string;
+  sub?: string;
+  exp?: number;
+  iat?: number;
+  /** Pass-through; we don't validate anything else SDK-side. */
+  [key: string]: unknown;
+}
+declare function decodeUnverifiedClaims(token: string): UnverifiedClaims;
+//#endregion
+//#region src/index.d.ts
+declare function createCloudEngine(opts: CloudEngineOptions): CloudEngine;
+/**
+ * Create a cloud {@link CloudEngine} — the drop-in counterpart of
+ * `localEngine()`, so swapping local for cloud is a one-import change.
+ *
+ * Synchronous and cheap: no WASM to compile, no worker to spawn — the engine
+ * holds an HTTP client and nothing else. Like `localEngine()`, the returned
+ * instance is yours (call `destroy()` when done, usually never for a
+ * module-scope singleton); pass a thunk (`engine={() => cloudEngine(...)}`)
+ * to let a `<Viewer>` own the lifetime instead.
+ *
+ * Note the deliberate asymmetry with `localEngine()`: there is no `fonts`
+ * option. Fallback fonts are a SERVER policy on the cloud (`Engine.fonts` is
+ * `undefined` cloud-side), so they cannot be configured from the client. This
+ * is the local-vs-cloud split, surfaced in the API.
+ *
+ * ```ts
+ * const engine = cloudEngine({ baseUrl: 'https://pdf.example.com', token });
+ * <Viewer engine={engine} plugins={[stagePlugin(), renderPlugin()]} />
+ * ```
+ */
+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 };
+//# sourceMappingURL=index.d.ts.map