@cloudpdf/engine 3.0.0-next.14 → 3.0.0-next.16

package/dist/index.d.ts

@@ -1,9 +1,13 @@
-import { AbortError, AbortablePromise, AbortablePromise as AbortablePromise$1, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationAppearanceRenderOptions, AnnotationAppearancesResult, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationFlattenResult, 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, DocumentSignaturesService, 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, PageMeasureService, PageMeasurementViewport, PageMoveResult, PageNameInput, PageNameResult, PageObjectNumber, PageRaster, PageRemoveNameInput, PageRenderOptions, PageRenderService, PageRenderService as PageRenderService$1, PageRotateResult, PageRotation, PageStructureCache, PageTextService, PageTextService as PageTextService$1, PageTextSnapshot, PdfMeasure, PdfSaveMode, PdfSaveMode as PdfSaveMode$1, SearchRequest, SearchSlice, TokenSource, WeakAnnotationEditSession } from "@embedpdf/engine-core/runtime";
+import { AbortablePromise, AnnotationAppearanceImageOptions, AnnotationAppearanceImagesResult, AnnotationBundle, AnnotationCreateOptions, AnnotationCreateResult, AnnotationDeleteResult, AnnotationDraft, AnnotationExportSelection, AnnotationFlattenResult, AnnotationImportOptions, AnnotationImportResult, AnnotationList, AnnotationListOptions, AnnotationPatch, AnnotationPosition, AnnotationRef, AnnotationReorderResult, AnnotationResourceRole, AnnotationUpdateOptions, AnnotationUpdateResult, BundleLimits, CallFacts, Change, ChangeAnswer, ChangeResult, CustomMetadataService, DocumentActionsService, DocumentAnnotationsService, DocumentAttachmentsService, DocumentEventStream, DocumentFormsService, DocumentHandle, DocumentMetadata, DocumentOutlineService, DocumentPagesService, DocumentRedactionService, DocumentRenderService, DocumentSearchService, DocumentSecurityService, DocumentSignaturesService, DownloadOptions, EditSessionAccess, EditSessionStatus, Engine, EngineError, FlattenWriteOptions, MetadataPatch, MetadataService, MetadataUpdateResult, MutationMeta, ObjectNumberPool, ObjectNumberRange, ObjectNumbersLost, OpenInput, OpenOptions, PageAnnotationsService, PageCoordinates, PageExtractOptions, PageFlattenResult, PageFormsService, PageHandle, PageImageOptions, PageLayerRights, PageLayout, PageListSnapshot, PageMeasureService, PageMeasurementViewportList, PageNameInput, PageNameResult, PagePrintRights, PageRef, PageRemoveNameInput, PageRenderImage, PageRenderService, PageScaleResult, PageStructureVerb, PageTextService, PageTextSnapshot, PdfMeasure, SearchRequest, SearchSlice, SessionEventPublisher, TextLayout, TextRange, TokenSource, WireAnnotationResources, WorkingSetPage, WriteOptions } from "@embedpdf/engine-core/runtime";
 import { CdnAccessInfoForApply, DocumentHead, DocumentManifest, LayerScopePlane } from "@embedpdf/engine-core/wire";
-import { SessionEventPublisher } from "@embedpdf/engine-services";
+export * from "@embedpdf/engine-core/public";
 //#region src/transport/HttpClient.d.ts
+/** CloudPDF SaaS: where an engine connects when it names no server of its own. */
+declare const CLOUDPDF_SAAS_URL = "https://engine.cloudpdf.com";
 interface HttpClientOptions {
-  baseUrl: string;
+  /** Where your CloudPDF runs: your own `@cloudpdf/server`, or CloudPDF SaaS
+   *  ({@link CLOUDPDF_SAAS_URL}) when left out. */
+  baseUrl?: string;
   /**
    * Optional bearer token. Either a string or a function that
    * returns a fresh token on every call (so callers can rotate
@@ -12,26 +16,30 @@ interface HttpClientOptions {
    * scenario where the doc-scoped token is provided per-`open` and
    * the engine itself has no engine-level credentials.
    */
-  token?: string | (() => string | Promise<string>);
+  token?: TokenSource;
   /**
-   * 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).
+   * The open document's session id, sent as `X-Engine-Session-Id` where the
+   * server reads it: on writes, `/access`, the event stream and the bulk
+   * reservation (see {@link RequestOptions}). The server keeps the editing
+   * session's object numbers under it, and stores it on a write's audit
+   * row, so the document's own stream can drop its echoes. Each open
+   * document has its own (see {@link HttpClient.forDocument}); the engine's
+   * client has none.
    */
   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
+   * 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
+   * 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
+   * `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.
@@ -63,15 +71,35 @@ interface CdnBinding {
   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.
+ * What a write sends beside its request: its `opId` as `Idempotency-Key`,
+ * so a retry is answered with what the first try committed, and how many
+ * object numbers to top the editing session up by.
  */
+interface WriteRequest {
+  /** Absent for a request of changes: its body names each change by its own `opId`. */
+  readonly opId?: string;
+  /** `EmbedPDF-Reserve-Object-Numbers`, when more than 0. */
+  readonly reserveObjectNumbers?: number;
+  /** Called with the numbers the response hands out (`EmbedPDF-Object-Numbers`). */
+  readonly onObjectNumbers?: (ranges: ObjectNumberRange[]) => void;
+}
+/** How one request is sent, beyond its path and body. */
+interface RequestOptions {
+  /**
+   * A write: sent as the editing session with its `Idempotency-Key`, and
+   * sent again with the same key after a network failure.
+   */
+  readonly write?: WriteRequest;
+  /** Sent as the editing session though not a write: `/access`, the bulk reservation. */
+  readonly session?: boolean;
+}
+/** A raw-bytes response plus its headers. */
 interface HttpFileResponse {
   bytes: Uint8Array;
   headers: Headers;
 }
 declare class HttpClient {
+  private readonly options;
   private readonly base;
   private readonly tokenFn;
   private readonly fetchFn;
@@ -80,9 +108,12 @@ declare class HttpClient {
   private static readonly MAX_RETRIES;
   private static readonly RETRY_AFTER_CAP_MS;
   private static readonly RETRY_AFTER_DEFAULT_MS;
-  private readonly sessionId;
+  /** A write whose request failed on the network is sent again after these waits. */
+  private static readonly NETWORK_RETRY_MS;
+  /** The open document's session id; `null` on the engine's own client. */
+  readonly sessionId: string | null;
   private cdnBinding;
-  constructor(opts: HttpClientOptions);
+  constructor(options: HttpClientOptions);
   /** Normalized server base URL (no trailing slash). */
   get baseUrl(): string;
   /**
@@ -93,13 +124,16 @@ declare class HttpClient {
    */
   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
-   * per-open token, so each opened document's RPCs go out under
-   * the right authorization without disturbing the engine-level
-   * token.
+   * A client for one open document: this client's settings, the document's
+   * own editing session, its own CDN binding, and `token` as its bearer
+   * when the open names one (else this client's). Two open documents never
+   * share object numbers, event echoes or a CDN binding, even two opens of
+   * the same document on one engine.
    */
-  withToken(token: string | (() => string | Promise<string>)): HttpClient;
+  forDocument({ sessionId, token }: {
+    sessionId: string;
+    token?: TokenSource;
+  }): HttpClient;
   /**
    * Raw streaming GET (the SSE channel). Same auth/session headers and
    * error mapping as every other request; the caller owns the body stream.
@@ -110,13 +144,13 @@ declare class HttpClient {
    * 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
+   * 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).
+   * receives them on subsequent fetches. Outside the browser signed
+   * cookies are ignored: this client keeps no cookie jar.
    */
   setCdnAccess(binding: CdnBinding | null): void;
   /** Current CDN binding (or null). Exposed for diagnostics/tests. */
@@ -175,26 +209,28 @@ declare class HttpClient {
    * `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>;
+  postMultipartJson<T>(path: string, body: FormData, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): 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>;
-  putJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal): Promise<T>;
+  patchMultipartJson<T>(path: string, body: FormData, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
+  postJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
+  putJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
+  /** POST a JSON body and parse a `multipart/form-data` response (a large annotation export). */
+  postJsonFormData(path: string, body: unknown, signal: AbortSignal): Promise<FormData>;
   /** 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>;
-  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>;
+  postBytesJson<T>(path: string, bytes: Uint8Array, contentType: string, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
+  patchJson<T>(path: string, body: unknown, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
+  deleteJson<T>(path: string, parser: (raw: unknown) => T, signal: AbortSignal, options?: RequestOptions): Promise<T>;
   private requestJson;
   private request;
   private execute;
   private parseJsonResponse;
   /**
    * Decide where this request actually goes. With no CDN binding (or
-   * binding's `cdn` is null) every request stays on origin. Otherwise
+   * binding's `cdn` is null) every request stays on origin, and so does
+   * every request that isn't a read (`GET`, `HEAD`): a write must reach the
+   * server itself, whatever read its path looks like. Otherwise
    * `applyCdnAccess` decides per-request based on the resource the
    * path resolves to (and whether the caller's scope granted CDN
    * access to it).
@@ -204,21 +240,31 @@ declare class HttpClient {
 }
 //#endregion
 //#region src/CloudEngine.d.ts
-interface CloudEngineOptions extends HttpClientOptions {}
+/**
+ * `cloudEngine()`'s options: the HTTP client's, minus the session id, which
+ * the engine mints for each document it opens.
+ */
+interface CloudEngineOptions extends Omit<HttpClientOptions, 'sessionId'> {}
 /**
  * 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 {
+declare class CloudEngine implements Engine {
   private readonly http;
-  /** This engine instance's identity on every event's `origin.sessionId`. */
-  private readonly sessionId;
   static fromOptions(opts: CloudEngineOptions): CloudEngine;
+  /** It opens the documents your server holds, never a file's bytes. */
+  readonly canOpenFiles = false;
   private destroyed;
+  /** The documents this engine opened and nobody closed yet. */
+  private readonly handles;
   private constructor();
-  open(input: OpenInput$1, options?: OpenOptions$1): AbortablePromise$1<DocumentHandle$1>;
-  destroy(): AbortablePromise$1<void>;
+  open(input: OpenInput, options?: OpenOptions): AbortablePromise<DocumentHandle>;
+  /**
+   * Close every document this engine opened (their event streams stop), then
+   * refuse new opens. As on the local engine, a handle is unusable after.
+   */
+  destroy(): AbortablePromise<void>;
 }
 //#endregion
 //#region src/document/CloudDocumentSearchService.d.ts
@@ -227,14 +273,14 @@ declare class CloudEngine implements Engine$1 {
  *
  * 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
+ * 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
+ * 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.
  */
@@ -245,29 +291,192 @@ declare class CloudDocumentSearchService implements DocumentSearchService {
   private readonly isClosed;
   private readonly manifest;
   constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor);
-  query(request: SearchRequest): AbortablePromise$1<SearchSlice>;
+  query(request: SearchRequest): AbortablePromise<SearchSlice>;
+}
+//#endregion
+//#region src/document/CloudObjectNumberPool.d.ts
+interface CloudObjectNumberPoolOptions {
+  /** `POST …/object-numbers`: `count` more numbers for this editing session. */
+  reserve(count: number, signal: AbortSignal): Promise<{
+    objectNumbers: ObjectNumberRange[];
+    expiresIn: number;
+  }>;
+  now?: () => number;
+}
+/** What became of the numbers a write named. */
+type WriteOutcome =
+/** It committed: they are spent. */
+'committed' |
+/** The server refused them (`ObjectNumberUnavailable`): the caller knows. */
+'refused' |
+/** It failed otherwise: the caller still holds them, for a retry. */
+'failed';
+/**
+ * The cloud engine's object numbers: what the server handed this editing
+ * session (the engine's `X-Engine-Session-Id` with the token's subject).
+ *
+ * Numbers arrive with `/access`, with a write's response (the top-up a
+ * write asks for when fewer than 8 are held), with the event stream's
+ * `session` events, and from `reserve`'s bulk reservation. A number
+ * `take` hands out is the caller's until a write naming it commits.
+ *
+ * The session lives while the event stream is connected or something
+ * keeps it alive; without that it expires, and its numbers may go to
+ * another session. So once its expiry has passed while the stream is down,
+ * the pool hands out nothing until the server says again what it holds.
+ * The stream's `session` event lists everything the session holds: any
+ * number this pool held or handed out that isn't on it, and that no write
+ * in flight names, is lost (`onLost`, `'reclaimed'`). A new version of the
+ * document numbers objects anew: everything is lost (`'versioned'`).
+ */
+declare class CloudObjectNumberPool implements ObjectNumberPool {
+  private readonly opts;
+  private readonly now;
+  /** Held and not handed out, lowest first. */
+  private available;
+  /** Handed out by `take`, not yet spent by a write. */
+  private readonly taken;
+  /** Named by a write in flight, and how many writes name each. */
+  private readonly writing;
+  /** When the session expires unless kept alive (ms since the epoch). */
+  private expiresAt;
+  /** Half the longest lifetime the server has told: what a write's touch guarantees. */
+  private halfLifetimeMs;
+  private streamConnected;
+  private readonly listeners;
+  /** The bulk reservation in flight, which later `reserve` calls wait behind. */
+  private reserving;
+  /** The newest version a `versioned` call named. */
+  private version;
+  constructor(opts: CloudObjectNumberPoolOptions);
+  get held(): number;
+  take(): number | null;
+  reserve(count: number): AbortablePromise<void>;
+  onLost(listener: (lost: ObjectNumbersLost) => void): () => void;
+  /** How many numbers a write should ask the server for: 0 while enough are held. */
+  topUp(): number;
+  /** How many numbers `/access` should ask for: enough to make up the first block. */
+  wantedAtAccess(): number;
+  /**
+   * `/access` answered for the editing session. A session the server made
+   * anew holds nothing of what this pool had.
+   */
+  opened(edit: EditSessionAccess): void;
+  /**
+   * Numbers handed to the session: by `/access`, a write's top-up or the
+   * bulk reservation; `expiresIn` (seconds) when the answer told it. Numbers
+   * held from before an expiry the server can't vouch for any more are
+   * dropped: only a `session` event says which survived.
+   */
+  receive(ranges: readonly ObjectNumberRange[], expiresIn?: number): void;
+  /**
+   * The event stream's `session` event: everything the session holds now.
+   * What this pool held or handed out and the list doesn't name, unless a
+   * write in flight names it, is lost.
+   */
+  sync(status: EditSessionStatus): void;
+  /**
+   * Version `sha256` was published: it numbers objects anew, so every number
+   * held or handed out is gone. Told once per version (the stream and this
+   * engine's own completion both tell it, in either order).
+   */
+  versioned(sha256: string): void;
+  /** The event stream connected or dropped: while it's up, the server keeps the session alive. */
+  connected(connected: boolean): void;
+  /** A write that names `numbers` was called. */
+  beginWrite(numbers: readonly number[]): void;
+  /**
+   * The write that named `numbers` settled. A committed write also kept the
+   * session alive: at least half its lifetime is left.
+   */
+  endWrite(numbers: readonly number[], outcome: WriteOutcome): void;
+  private usable;
+  private expiresIn;
+  private add;
+  /** Held or handed out, and named by no write in flight. */
+  private unspent;
+  private lose;
+  private emit;
+}
+//#endregion
+//#region src/document/CloudWrites.d.ts
+/**
+ * One write's place in its document's line (see {@link CloudWrites}): its
+ * request goes out once every write called before it has settled.
+ */
+interface CloudWrite {
+  /**
+   * Wait for this write's turn, then send its request with `options`: the
+   * write's `opId` as `Idempotency-Key`, a top-up when the pool runs low,
+   * and the numbers the response hands out back into the pool.
+   */
+  send<T>(request: (options: RequestOptions) => Promise<T>): Promise<T>;
+}
+/** A change as its request sends it: its `opId`, and its ops with the bytes they carry. */
+interface SentChange {
+  readonly opId: string;
+  readonly change: Change<PageCoordinates, WireAnnotationResources>;
+}
+/**
+ * Sends one request of changes (`POST …/changes`) with `options`, the
+ * changes in line order, and answers each, in the same order.
+ */
+type ChangeSender = (changes: readonly SentChange[], options: RequestOptions) => Promise<readonly ChangeAnswer[]>;
+/** How a change takes its place in the line (see {@link CloudWrites.change}). */
+interface LinedChangeOptions {
+  /** The object numbers the change creates objects at. */
+  readonly named?: readonly number[];
+  /**
+   * The change carries bytes: it goes in a request of its own, so bytes the
+   * server refuses refuse only this change.
+   */
+  readonly alone?: boolean;
+}
+/**
+ * A document's writes, sent one at a time in the order they were called,
+ * so the server applies them in that order: a create, then an update of
+ * what it made, never the other way round. Reads don't wait.
+ *
+ * A write takes its place when it is called: `run` must be the first thing
+ * a write does, before anything it awaits. What it does before `send`
+ * (reading a file to upload, say) happens meanwhile; its turn ends when it
+ * settles, after the event it publishes.
+ *
+ * Changes (`doc.apply`) called one after another share a place: while the
+ * write before them is in flight they wait together, and go out as one
+ * request when their turn comes, each answered on its own.
+ */
+declare class CloudWrites {
+  private readonly pool;
+  private readonly sendChanges;
+  /** Settles when every write so far has settled. */
+  private last;
+  /** The changes still waiting for their turn, which the next change joins. */
+  private open;
+  constructor(pool: CloudObjectNumberPool, sendChanges?: ChangeSender);
+  run<T>(opId: string, signal: AbortSignal, body: (write: CloudWrite) => Promise<T>,
+  /** The object numbers the write creates objects at. */
+  named?: readonly (number | undefined)[]): Promise<T>;
+  /**
+   * Take a change's place in the line: it joins the changes waiting for
+   * their turn, and goes out with them. `ready` is what the request sends
+   * for it, which it may still be preparing (reading bytes). A change aborted
+   * before its request goes out is left out of it; once out, it is answered.
+   */
+  change(signal: AbortSignal, ready: Promise<SentChange>, { named, alone }?: LinedChangeOptions): Promise<ChangeAnswer>;
+  /** A new batch at the end of the line, open for the changes that follow. */
+  private queue;
+  /** A batch's turn: nothing joins it any more, and what's ready goes out. */
+  private send;
 }
 //#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>;
+declare class CloudMetadataService implements MetadataService {
+  readonly custom: CustomMetadataService;
+  private readonly deps;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites);
+  get(): AbortablePromise<DocumentMetadata>;
+  update(patch: MetadataPatch, options?: WriteOptions): AbortablePromise<MetadataUpdateResult>;
 }
 //#endregion
 //#region src/document/CloudDocumentHandle.d.ts
@@ -291,42 +500,39 @@ interface ManifestAccessor {
    * 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;
-  /** Page insert: the cached manifest has no rows for the fresh PONs (the
+  /** A page delete: the advance, plus dropping the deleted pages' manifest
+   *  rows so per-page leaf URLs stop resolving locally. */
+  applyPageDelete(meta: MutationMeta, deletedPages: readonly PageRef[]): void;
+  /** Page insert: the cached manifest has no rows for the fresh page object numbers (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
-   *  attachment create/delete. */
-  applyAttachments(cache: AttachmentsCache): void;
+  applyPageInsert(meta: MutationMeta): void;
 }
-declare class CloudDocumentHandle implements DocumentHandle$1 {
+declare class CloudDocumentHandle implements DocumentHandle {
   private readonly http;
   private readonly layerName;
+  /** Called once, when the handle closes (the engine forgets it). */
+  private readonly onClose;
   readonly id: string;
-  readonly capabilities: {
-    readonly weakAnnotationEditSessions: "required";
-    readonly pageEditSessions: "unsupported";
-  };
   readonly metadata: CloudMetadataService;
-  readonly annotations: DocumentAnnotationsService$1;
+  readonly annotations: DocumentAnnotationsService;
   readonly actions: DocumentActionsService;
+  readonly outline: DocumentOutlineService;
   readonly attachments: DocumentAttachmentsService;
   readonly signatures: DocumentSignaturesService;
   readonly forms: DocumentFormsService;
   readonly search: CloudDocumentSearchService;
-  readonly pages: DocumentPagesService$1;
+  readonly pages: DocumentPagesService;
+  /** The page reads behind `pages`, the layout per page among them. */
+  private readonly pageReads;
   readonly redaction: DocumentRedactionService;
-  readonly security: DocumentSecurityService$1;
+  readonly security: DocumentSecurityService;
   readonly render: DocumentRenderService;
   readonly events: DocumentEventStream;
+  readonly objectNumbers: ObjectNumberPool;
+  private readonly pool;
+  private readonly writes;
+  private readonly changes;
   private readonly publisher;
   private readonly hub;
   private readonly sessionId;
@@ -349,6 +555,7 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
   private manifestFloorVersion;
   private pendingInitialHead;
   private readonly manifestAccessor;
+  private readonly cloudSecurity;
   constructor(http: HttpClient, id: string, layerName?: string, initialHead?: DocumentHead,
   /**
    * The doc-scoped JWT the engine was opened with, decoded
@@ -357,11 +564,28 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
    * 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>;
+  initialToken?: string | null,
+  /** Called once, when the handle closes (the engine forgets it). */
+  onClose?: () => void);
+  page(ref: PageRef): PageHandle;
+  /**
+   * This handle: the cloud engine sends every call as it's made, in
+   * parallel, and the server runs them in arrival order, so a call's facts
+   * change nothing here.
+   */
+  with(_facts: CallFacts): DocumentHandle;
+  /** One change as one transaction, or the undo of one (see `DocumentHandle.apply`). */
+  apply(change: Change, options?: WriteOptions): AbortablePromise<ChangeResult>;
+  /** Ignored: the server learns what's needed from what is asked of it. */
+  setWorkingSet(_view: string, _pages: readonly WorkingSetPage[]): void;
+  download(options?: DownloadOptions): AbortablePromise<Uint8Array>;
+  /**
+   * Learn what the document's signatures forbid before the caller's first
+   * question: the manifest carries it, so `open()` fetches it up front and
+   * `security.allows()` answers as the server would from the start. A locked
+   * document, which the server won't describe yet, learns it from `unlock()`.
+   */
+  learnProtection(signal: AbortSignal): Promise<void>;
   /**
    * Return the cached manifest, fetching cold-cache once if needed.
    * Concurrent callers share a single inflight request (singleflight)
@@ -376,9 +600,9 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
    */
   refreshManifest(signal: AbortSignal): Promise<DocumentManifest>;
   /**
-   * Monotone plane-scope flip: mark the planes a mutation OWNS as layer-scoped in
+   * 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
+   * 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
@@ -387,122 +611,132 @@ declare class CloudDocumentHandle implements DocumentHandle$1 {
   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).
+   * Patch the cached manifest after a page delete: the shared advance plus
+   * dropping the deleted pages' manifest rows, so no leaf URL for a retired
+   * page object number can be built from the cache (a stale request would
+   * 404 anyway — this keeps the failure local and instant). Delete changes
+   * the page set: a view that removed content must never resolve base
+   * artifacts again, so content, annotations and forms flip with layout.
    */
   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
+   * cached manifest losslessly (it only removes rows), but an insert needs
+   * manifest rows for the fresh page object numbers 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 and forms 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
-   * 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>;
+  close(): AbortablePromise<void>;
   private retainRemoteStream;
   private releaseRemoteStream;
-  /** Patch the cached manifest from a REMOTE event's coherence pins — the
+  /** 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. */
+   *  whose hand caused the change. Every event kind is named below, so a new
+   *  one can't be forgotten: a missed one leaves this client reading the
+   *  old version from an immutable, cached URL. */
   private absorbRemoteEvent;
 }
 //#endregion
 //#region src/document/CloudDocumentAnnotationsService.d.ts
-declare class CloudDocumentAnnotationsService implements DocumentAnnotationsService$1 {
+declare class CloudDocumentAnnotationsService implements DocumentAnnotationsService {
   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);
+  private readonly publisher;
+  private readonly writes;
+  /** The server's import limits, as its `/v1/access` advertises them. */
+  private readonly importLimits;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites,
+  /** The server's import limits, as its `/v1/access` advertises them. */
+  importLimits: () => Promise<BundleLimits>);
   /**
-   * 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).
+   * Every page: 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).
+   *
+   * Some pages: each page's versioned leaf, the same read as
+   * `page.annotations.list()`, in the order asked.
    */
-  listRawAll(): AbortablePromise$1<AnnotationListSnapshotAllPages>;
+  list(options?: AnnotationListOptions): AbortablePromise<AnnotationList>;
   /** 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>;
+  /** One page's versioned leaf, with the standard stale-pin retry
+   *  (404 → refresh the manifest → once). */
+  private readPage;
+  /**
+   * One versioned, CDN-cacheable read at the manifest's annotation and
+   * layout pins, with the stale-pin retry (404 → refresh the manifest →
+   * once). The response is the bundle without its bytes and one part per
+   * resource; every part is checked against its id before it is returned.
+   */
+  export(selection?: AnnotationExportSelection): AbortablePromise<AnnotationBundle>;
+  /**
+   * One request: the bundle's manifest and each resource once, as parts of
+   * one multipart POST under the import's `opId` as `Idempotency-Key`, so a
+   * retry applies once. The server holds the limits; the same numbers are checked
+   * here first, so a bundle past one fails before its bytes move.
+   */
+  import(bundle: AnnotationBundle, options?: AnnotationImportOptions): AbortablePromise<AnnotationImportResult>;
+  /**
+   * The cacheable export URL for `selection` at the manifest's pins — the
+   * base leaf while the layer inherits both planes the bundle depends on —
+   * or `null` when a URL can't carry it: a URL has room for a few hundred
+   * refs.
+   */
+  private exportPathAt;
   /** 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>;
 }
 //#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.
+ * Cloud-side document pages service: the reads, extract, flatten and the page
+ * names, over HTTP, as `LocalDocumentPagesService` has them. The structure
+ * verbs are changes (`pageVerbs`), so they can be undone.
  *
  * 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`.
+ *   - Pages are addressed exclusively by `PageRef` (their indirect
+ *     `pageObjectNumber`); mutation bodies ship `{ pages: PageRef[] }`.
+ *     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.
+ *   - A page reorder (a change) returns the new `layout` (order + geometry)
+ *     plus cloud coherence pins. It bumps only `docVersion` +
+ *     `layoutVersion`; every per-page pin stays warm.
  */
-declare class CloudDocumentPagesService implements DocumentPagesService$1 {
+declare class CloudDocumentPagesService implements Omit<DocumentPagesService, PageStructureVerb> {
   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);
+  private readonly writes;
+  /** The last layout leaf read by {@link pageLayout}, keyed by its URL path. */
+  private layoutMemo;
+  constructor(http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites);
   /**
    * Page-geometry list. The geometry bytes live at the content-addressed
    * `/layout@layoutVersion=N` leaf (not in the manifest); the manifest only
@@ -513,22 +747,31 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
    * 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>;
-  setName(input: PageNameInput): AbortablePromise$1<PageNameResult>;
-  removeName(input: PageRemoveNameInput): AbortablePromise$1<PageNameResult>;
+  list(): AbortablePromise<PageListSnapshot>;
   /**
-   * Named pages are LAYOUT: both verbs share the page-move patch exactly —
+   * One page's layout, for renders to size their image without a round
+   * trip per tile. The layout leaf never changes at a given URL, so the
+   * last one read is kept and shared until the manifest points elsewhere.
+   */
+  pageLayout(ref: PageRef, signal: AbortSignal): Promise<PageLayout>;
+  /**
+   * Plane-scope rule: the layout leaf depends on the `layout` plane —
+   * while inherited (no reorder/rotate/insert/delete ever ran), every
+   * visitor's page list is one doc-level URL served from the base
+   * session; the SDK open sequence creates no layer session.
+   */
+  private layoutPath;
+  private fetchLayout;
+  setName(input: PageNameInput, options?: WriteOptions): AbortablePromise<PageNameResult>;
+  removeName(input: PageRemoveNameInput, options?: WriteOptions): AbortablePromise<PageNameResult>;
+  /**
+   * Named pages are layout: both verbs share the page-reorder patch exactly —
    * docVersion + layoutVersion advance, no per-page pin changes, so the
    * cached manifest is patched in place and the fresh layout is published.
    */
   private runNameMutation;
-  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>;
+  extract(pages: PageRef[], options?: PageExtractOptions): AbortablePromise<Uint8Array>;
+  flatten(pages: PageRef[], options?: FlattenWriteOptions): AbortablePromise<PageFlattenResult>;
 }
 //#endregion
 //#region src/document/CloudPageAnnotationsService.d.ts
@@ -541,36 +784,35 @@ declare class CloudDocumentPagesService implements DocumentPagesService$1 {
  * 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 {
+declare class CloudPageAnnotationsService implements PageAnnotationsService {
   private readonly http;
   private readonly docId;
   private readonly layerName;
-  private readonly pageObjectNumber;
+  private readonly pageRef;
   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 readonly writes;
+  constructor(http: HttpClient, docId: string, layerName: string, pageRef: PageRef, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites);
+  list(): AbortablePromise<AnnotationList>;
+  renderAppearances(options?: AnnotationAppearanceImageOptions): AbortablePromise<AnnotationAppearanceImagesResult>;
+  /**
+   * One of the annotation's resources. `file` is 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}. `appearance` is a
+   * derived read (no-store), like {@link exportAppearance}. Both address the
+   * annotation by the same `:annotKey` update()/delete() use.
+   */
+  downloadResource(ref: AnnotationRef, role: AnnotationResourceRole): AbortablePromise<Uint8Array>;
+  create(draft: AnnotationDraft, options?: AnnotationCreateOptions): AbortablePromise<AnnotationCreateResult>;
+  update(ref: AnnotationRef, patch: AnnotationPatch, options?: AnnotationUpdateOptions): AbortablePromise<AnnotationUpdateResult>;
+  /** PATCH as plain JSON, or as multipart when resources came with the patch. */
   private patchMutation;
-  delete(ref: AnnotationRef): AbortablePromise$1<AnnotationDeleteResult>;
-  move(refs: AnnotationRef[], toIndex: number): AbortablePromise$1<AnnotationMoveResult>;
-  flatten(refs: AnnotationRef[], usage?: PageFlattenUsage): AbortablePromise$1<AnnotationFlattenResult>;
-  exportAppearance(refs: AnnotationRef[]): AbortablePromise$1<Uint8Array>;
+  delete(ref: AnnotationRef, options?: WriteOptions): AbortablePromise<AnnotationDeleteResult>;
+  reorder(refs: AnnotationRef[], position: AnnotationPosition, options?: WriteOptions): AbortablePromise<AnnotationReorderResult>;
+  flatten(refs: AnnotationRef[], options?: FlattenWriteOptions): AbortablePromise<AnnotationFlattenResult>;
+  exportAppearance(refs: AnnotationRef[]): AbortablePromise<Uint8Array>;
   /**
    * Patch the cached manifest, then publish the mutation to the document's
    * event stream (in that order — listeners reading the manifest in their
@@ -578,52 +820,78 @@ declare class CloudPageAnnotationsService implements PageAnnotationsService$1 {
    * `type` with the matching result by construction; the cast localizes that
    * pairing here instead of widening every site.
    */
+  /** A delete's event names what went, for listeners that didn't delete it. */
+  private absorbDelete;
   private absorbMutation;
 }
 //#endregion
-//#region src/document/CloudPageGeometryService.d.ts
-declare class CloudPageGeometryService implements PageGeometryService$1 {
+//#region src/document/CloudPageFormsService.d.ts
+/**
+ * Cloud page form service: the page's widget images, one read of the
+ * immutable `form/pages/{p}/appearances@` leaf at the page's `widgetVersion`,
+ * at the base's URL while the layer inherits the `forms` plane.
+ */
+declare class CloudPageFormsService implements PageFormsService {
   private readonly http;
   private readonly docId;
   private readonly layerName;
-  private readonly pageObjectNumber;
+  private readonly pageRef;
   private readonly isClosed;
   private readonly manifest;
-  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor);
-  read(): AbortablePromise$1<PageGeometrySnapshot>;
+  constructor(http: HttpClient, docId: string, layerName: string, pageRef: PageRef, isClosed: () => boolean, manifest: ManifestAccessor);
+  renderAppearances(options?: AnnotationAppearanceImageOptions): AbortablePromise<AnnotationAppearanceImagesResult>;
 }
 //#endregion
 //#region src/document/CloudPageRenderService.d.ts
-declare class CloudPageRenderService implements PageRenderService$1 {
+declare class CloudPageRenderService implements PageRenderService {
   private readonly http;
   private readonly docId;
   private readonly layerName;
-  private readonly pageObjectNumber;
+  private readonly pageRef;
   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>;
+  private readonly layout;
+  /** What the caller may read, when the client can know it; null leaves it to the server. */
+  private readonly layerRights;
+  /** What the caller may print, when the client can know it; null leaves it to the server. */
+  private readonly printRights;
+  constructor(http: HttpClient, docId: string, layerName: string, pageRef: PageRef, isClosed: () => boolean, manifest: ManifestAccessor, layout: (signal: AbortSignal) => Promise<PageLayout>,
+  /** What the caller may read, when the client can know it; null leaves it to the server. */
+  layerRights: () => PageLayerRights | null,
+  /** What the caller may print, when the client can know it; null leaves it to the server. */
+  printRights: () => PagePrintRights | null);
+  image(options?: PageImageOptions): AbortablePromise<PageRenderImage>;
+  /**
+   * The image's transform, computed like the server's render (the same
+   * `renderSize` and matrix), so the handle knows its size and its pixels
+   * before any are fetched. Only a full page needs the page's layout.
+   */
+  private transformOf;
 }
 //#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.
+ * Cloud-side per-page text service. `get()` fetches the content-addressed
+ * URL `/v1/docs/:id/text/pages/:pon/data@contentVersion=N` and `layout()`
+ * its geometry twin, where `N` 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 version, and retries exactly once.
  */
-declare class CloudPageTextService implements PageTextService$1 {
+declare class CloudPageTextService implements PageTextService {
   private readonly http;
   private readonly docId;
   private readonly layerName;
-  private readonly pageObjectNumber;
+  private readonly pageRef;
   private readonly isClosed;
   private readonly manifest;
-  constructor(http: HttpClient, docId: string, layerName: string, pageObjectNumber: PageObjectNumber, isClosed: () => boolean, manifest: ManifestAccessor);
-  read(): AbortablePromise$1<PageTextSnapshot>;
+  constructor(http: HttpClient, docId: string, layerName: string, pageRef: PageRef, isClosed: () => boolean, manifest: ManifestAccessor);
+  get(): AbortablePromise<PageTextSnapshot>;
+  slice(range: TextRange): AbortablePromise<string>;
+  layout(): AbortablePromise<TextLayout>;
+  /** One of the page's content leaves at the manifest's pin, with the stale-pin retry. */
+  private readLeaf;
+  private leafPath;
 }
 //#endregion
 //#region src/document/CloudPageMeasureService.d.ts
@@ -631,26 +899,32 @@ declare class CloudPageMeasureService implements PageMeasureService {
   private readonly http;
   private readonly docId;
   private readonly layerName;
-  private readonly pon;
+  private readonly pageRef;
   private readonly isClosed;
   private readonly manifest;
   private readonly publisher;
-  constructor(http: HttpClient, docId: string, layerName: string, pon: number, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
-  viewports(): AbortablePromise$1<PageMeasurementViewport[]>;
-  setScale(measure: PdfMeasure | null): AbortablePromise$1<void>;
+  private readonly writes;
+  constructor(http: HttpClient, docId: string, layerName: string, pageRef: PageRef, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites);
+  listViewports(): AbortablePromise<PageMeasurementViewportList>;
+  setScale(measure: PdfMeasure | null, options?: WriteOptions): AbortablePromise<PageScaleResult>;
   private check;
 }
 //#endregion
 //#region src/document/CloudPageHandle.d.ts
-declare class CloudPageHandle implements PageHandle$1 {
-  readonly pageObjectNumber: PageObjectNumber;
-  readonly pageIndex: number;
+/**
+ * Cloud page handle, keyed on `ref` — the page's durable address (its
+ * object number). Every service below addresses the wire by it
+ * (`/pages/obj:N/…`), keys the manifest by its number, and publishes
+ * that number in events.
+ */
+declare class CloudPageHandle implements PageHandle {
+  readonly ref: PageRef;
   readonly annotations: CloudPageAnnotationsService;
+  readonly forms: CloudPageFormsService;
   readonly text: CloudPageTextService;
-  readonly geometry: CloudPageGeometryService;
   readonly render: CloudPageRenderService;
   readonly measure: CloudPageMeasureService;
-  constructor(pageObjectNumber: PageObjectNumber, pageIndex: number, http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher);
+  constructor(ref: PageRef, http: HttpClient, docId: string, layerName: string, isClosed: () => boolean, manifest: ManifestAccessor, publisher: SessionEventPublisher, writes: CloudWrites, layout: (signal: AbortSignal) => Promise<PageLayout>, layerRights: () => PageLayerRights | null, printRights: () => PagePrintRights | null);
 }
 //#endregion
 //#region src/transport/decodeUnverifiedClaims.d.ts
@@ -683,7 +957,7 @@ declare function decodeUnverifiedClaims(token: string): UnverifiedClaims;
 /**
  * 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
+ * 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
@@ -732,7 +1006,7 @@ declare function exchangeShareToken(baseUrl: string, shareToken: string, opts?:
  * retry). Everything else maps by meaning, with the HTTP status as the
  * fallback discriminator.
  */
-declare function engineErrorFromShareExchange(error: ShareExchangeError): EngineError$1;
+declare function engineErrorFromShareExchange(error: ShareExchangeError): EngineError;
 /**
  * A caching, self-renewing token source over the exchange — the callable
  * member of the engine's `TokenSource` union, assignable wherever one is
@@ -743,7 +1017,6 @@ declare function engineErrorFromShareExchange(error: ShareExchangeError): Engine
 declare function shareSessionSource(baseUrl: string, shareToken: string, opts?: ShareExchangeOptions): () => Promise<string>;
 //#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.
@@ -755,16 +1028,19 @@ declare function createCloudEngine(opts: CloudEngineOptions): 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
+ * 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.
  *
+ * Without a `baseUrl` it connects to CloudPDF SaaS; your own server names itself:
+ *
  * ```ts
- * const engine = cloudEngine({ baseUrl: 'https://pdf.example.com', token });
+ * const engine = cloudEngine();                                    // CloudPDF SaaS
+ * const own = cloudEngine({ baseUrl: 'https://pdf.example.com' }); // your @cloudpdf/server
  * <Viewer engine={engine} plugins={[stagePlugin(), renderPlugin()]} />
  * ```
  */
-declare function cloudEngine(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 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 };
+export { CLOUDPDF_SAAS_URL, CloudDocumentAnnotationsService, CloudDocumentHandle, CloudDocumentPagesService, CloudEngine, type CloudEngineOptions, CloudMetadataService, CloudPageAnnotationsService, CloudPageHandle, CloudPageRenderService, HttpClient, type HttpClientOptions, ShareExchangeError, type ShareExchangeOptions, type ShareSession, type UnverifiedClaims, cloudEngine, decodeUnverifiedClaims, engineErrorFromShareExchange, exchangeShareToken, shareSessionSource };
 //# sourceMappingURL=index.d.ts.map