@embedpdf/web 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.d.cts

@@ -7,7 +7,7 @@ interface PickFileOptions {
 }
 /** Open the file dialog; resolve the picked file, or null if cancelled. */
 declare function pickImageFile(options?: PickFileOptions): Promise<File | null>;
-/** The same dialog with NO type filter — any file (attachments). */
+/** The same dialog with no type filter — any file (attachments). */
 declare const pickFile: (options?: PickFileOptions) => Promise<File | null>;
 /**
  * Hand bytes to the user as a browser download (a one-shot `<a download>`).
@@ -15,50 +15,112 @@ declare const pickFile: (options?: PickFileOptions) => Promise<File | null>;
  * capability's `downloadAttachment` or the document `attachments.download`.
  */
 declare function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void;
+/**
+ * The browser's default for a plugin's file prompt (the annotation plugin's
+ * `FilePickerProvider`): the file dialog, honouring the request's `accept`
+ * filter. A picked `File` carries its own name and type, so it goes straight
+ * through as the engine's file source; a dismissed dialog answers `null`.
+ */
+declare function pickRequestedFile(request: {
+  accept?: string | null;
+}): Promise<{
+  data: File;
+} | null>;
+/** Where a provider goes: the annotation plugin's port (its capability satisfies it). */
+interface FilePickerPort<Provider> {
+  /** Install the provider, `null` to make click-then-pick tools do nothing. Returns its removal. */
+  setFilePickerProvider(provider: Provider | null): () => void;
+}
+/**
+ * Install `provider` as a document's file picker, until the call it returns
+ * removes it. A document has one port, so a second install while the first
+ * is there silently replaces it: `onRepeat` hears of it (an adapter warns in
+ * development, saying where to install it once).
+ */
+declare function installFilePickerProvider<Provider>(annotation: FilePickerPort<Provider>, provider: Provider | null, onRepeat: () => void): () => void;
 //#endregion
-//#region src/clipboard.d.ts
+//#region src/clock.d.ts
 /**
- * Clipboard wiring for text selection — the environmental half of copy.
- *
- * The selection plugin is deliberately DOM-free: its public capability ends
- * at `readText()` (data). Everything that touches `navigator.clipboard` or
- * the native `copy` event lives HERE, structurally typed so this module
- * stays a pure DOM utility with no EmbedPDF dependencies (the selection
- * capability satisfies {@link ClipboardSelectionSource} as-is).
+ * The browser's time, for the kernel: `createKernel({ clock: browserClock() })`.
+ * Timers, and frames from `requestAnimationFrame`, so plugins can animate and
+ * merge their wake-ups into one per painted frame. Structurally `HostClock`
+ * from `@embedpdf/core`, declared here so this package stays dependency-free.
+ */
+/** Structural twin of `HostClock` (`@embedpdf/core`). */
+interface WebClock {
+  now(): number;
+  after(ms: number, run: () => void): () => void;
+  nextFrame?(run: (timeMs: number) => void): () => void;
+}
+/**
+ * The browser's clock. A page without `requestAnimationFrame` (some test
+ * environments) gets a clock without frames, and plugins then skip animation.
+ */
+declare function browserClock(): WebClock;
+//#endregion
+//#region src/css-text.d.ts
+/**
+ * Style records as CSS text. This package hands styles out as records with
+ * camelCase names (`strokeWidth`, `fontFamily`) and lengths with their units,
+ * the shape a style object takes in React, Vue and Angular. A framework whose
+ * `style` is a string (Svelte) turns a record into CSS text with
+ * {@link cssText}: `stroke-width: …; font-family: …`. Paint values are
+ * `var(--epdf-…, …)`, which only work in `style`, never in an SVG
+ * presentation attribute.
  */
+/** A style record: CSS property names in camelCase, each a value or left out. */
+type StyleRecord<Style> = { readonly [Name in keyof Style]?: string | number | null; };
+/** A style record as CSS text, leaving out what is `undefined` or `null`. */
+declare function cssText<Style extends StyleRecord<Style>>(style: Style): string;
+//#endregion
+//#region src/clipboard.d.ts
 /** The slice of the selection capability clipboard wiring needs. */
 interface ClipboardSelectionSource {
   hasSelection(): boolean;
   canCopy(): boolean;
   readText(): Promise<string>;
-  onChange(cb: () => void): () => void;
-  onCommit(cb: () => void): () => void;
+  onChanged(listener: () => void): () => void;
+  onCommitted(listener: () => void): () => void;
 }
 interface SelectionClipboardOptions {
   /**
    * Prefetch the selected text when the selection settles (default true).
-   * This is what makes the NATIVE copy path work: a `copy` event handler
+   * This is what makes the native copy path work: a `copy` event handler
    * must call `clipboardData.setData` synchronously — awaiting a page-text
    * read inside it is too late — and it also keeps the async path instant.
    * The fetch is one versioned, cached, permission-gated read per page;
    * pass false to make copying strictly on-demand.
    */
   prefetch?: boolean;
-  /** Event target to listen on. Defaults to `document`. */
-  target?: Document;
+  /**
+   * Whose keys and copies these are (default `document`, the whole page). An element takes
+   * them only while focus is inside it, for a page with more than one viewer; a copy from the
+   * browser's Edit menu included, which reaches the page's body when nothing is selected there.
+   */
+  target?: Document | HTMLElement;
+  /**
+   * Called when Ctrl/Cmd+C or a copy (Edit → Copy) meets a selection the user may not copy.
+   * The browser's own copy is prevented either way; this is where to say so.
+   */
+  onRefused?: () => void;
 }
 /**
  * Wire clipboard copy for a selection. Two delivery paths, both fed by the
  * prefetched text:
  *
  *   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page
- *     has a DOM selection or focused editable — e.g. the viewer shell's
- *     focus sink): answered SYNCHRONOUSLY from the cache;
+ *     has a DOM selection): answered synchronously from the cache;
  *   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually
  *     have none, and browsers don't dispatch `copy` then): a keydown
  *     fallback writes via the async Clipboard API inside the keystroke's
  *     user-activation window.
  *
+ * A selection the user may not copy is never copied by either path, nor by
+ * the browser: the key and the copy are prevented, and `onRefused` says so.
+ * Keys and copies in a text field are the field's, and left alone. With an
+ * element as `target`, only the keys and copies made while focus is inside it
+ * are its own.
+ *
  * Returns the unwire function. Mount once per document view (not per page).
  */
 declare function wireSelectionClipboard(selection: ClipboardSelectionSource, options?: SelectionClipboardOptions): () => void;
@@ -69,29 +131,67 @@ declare function wireSelectionClipboard(selection: ClipboardSelectionSource, opt
  * with what was copied ('' when nothing was — nothing is written then, so an
  * empty selection never clobbers the user's clipboard).
  */
-declare function copySelection(selection: ClipboardSelectionSource): Promise<string>;
+declare function copySelection(selection: Pick<ClipboardSelectionSource, 'readText'>): Promise<string>;
 //#endregion
-//#region src/anchored-position.d.ts
+//#region src/command-shortcuts.d.ts
+/** Why a matched command won't run whatever the moment, as the commands plugin says it. */
+interface ShortcutRefusal {
+  /** Turned off in this viewer, or not allowed by the scope. */
+  readonly reason: 'turned-off' | 'not-allowed';
+  /** A sentence for the user. */
+  readonly message: string;
+}
+/** The part of the commands capability shortcuts need. */
+interface ShortcutCommands {
+  /**
+   * The command a keystroke's shortcut names, with its refusal when it's refused, or `null`.
+   * With `inTextField`, only a command that runs from text fields.
+   */
+  matchStroke(stroke: KeyboardEvent, options: {
+    isMac: boolean;
+    inTextField: boolean;
+  }): {
+    readonly commandId: string;
+    readonly refusal: ShortcutRefusal | null;
+  } | null;
+  canExecute(id: string): boolean;
+  execute(id: string): Promise<unknown>;
+}
+interface CommandShortcutOptions {
+  /** Whether `Mod` is Cmd (a Mac) or Ctrl. Default: what the browser says. */
+  isMac?: boolean;
+  /** Where to listen. Default: `window`. */
+  target?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+  /** Called when a key's command is turned off or not allowed, with why: say so to the user. */
+  onRefused?: (commandId: string, refusal: ShortcutRefusal) => void;
+}
+/** Whether this is an Apple platform, where `Mod` is Cmd and shortcuts show as `⌘K`. */
+declare const isMacPlatform: () => boolean;
+/**
+ * Run a command when its shortcut is pressed, and return the function that stops listening.
+ * Keys typed into a text field are left alone, except a command's that says it runs from text
+ * fields (`shortcutInTextFields`, as Find does). A command that's turned off or not allowed
+ * still takes its key, so the browser doesn't do something else with it (Cmd+P printing the
+ * page), and `onRefused` says why. A key whose command only can't run right now keeps its
+ * browser default.
+ */
+declare function bindCommandShortcuts(commands: ShortcutCommands, options?: CommandShortcutOptions): () => void;
+//#endregion
+//#region src/page-ref.d.ts
 /**
- * Anchored-overlay geometry for UI floating over page content (selection
- * menus, draft menus, popovers): the projector SNAPSHOT contract, the
- * anchor shape, and the placement math. Pure values and pure functions over
- * structural rect/point shapes — no EmbedPDF types, no framework, no
- * reactive lifecycle — so every framework adapter (React, Vue, Svelte,
- * Angular) shares ONE implementation and binds it with its NATIVE
- * reactivity (context revision, signals, computed, $derived).
- *
- * The boundary laws:
- *   - Placement policy lives HERE, above the projector seam: a projector
- *     only knows geometry — never what is being positioned nor where it
- *     prefers to sit.
- *   - A projector describes the CURRENT projection; it never implements a
- *     framework-style reactive lifecycle. State-driven changes (the Stage
- *     camera) must reach consumers through the framework's own render
- *     cycle so surface and overlay commit TOGETHER; only genuinely
- *     browser-driven changes (a PageView moving because the document
- *     scrolled) use an external listener ({@link observeClientGeometry}).
+ * A page address — structurally the kernel's `PageRef` from `@embedpdf/core`
+ * (`{ kind: 'objectNumber', objectNumber }`), mirrored here like the
+ * rect/point shapes so this package stays free of EmbedPDF imports. Every
+ * `PageRef` the kernel or a plugin hands out satisfies it; the surfaces pass
+ * it through untouched (a stage's `pageAt` result, an anchor's page) — the
+ * number is never read here.
  */
+interface PageRef {
+  readonly kind: 'objectNumber';
+  readonly objectNumber: number;
+}
+//#endregion
+//#region src/anchored-position.d.ts
 interface AnchoredRect {
   x: number;
   y: number;
@@ -102,36 +202,68 @@ interface AnchoredPoint {
   x: number;
   y: number;
 }
-type AnchoredPlacement = 'top' | 'right' | 'bottom' | 'left';
+/** A side of the box. */
+type AnchoredSide = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Where anchored UI sits: a side of the box, centred on it, or lined up with
+ * the side's start or end (`'top-end'`: above the box, right edges lined up).
+ */
+type AnchoredPlacement = AnchoredSide | `${AnchoredSide}-${'start' | 'end'}`;
+/** How anchored UI is placed: where, how far from the box, and whether it may move to fit. */
+interface AnchoredOptions {
+  placement: AnchoredPlacement;
+  /** Screen px between the box and the UI; negative overlaps the box. */
+  gap: number;
+  /** Stays where `placement` puts it: never flips, never moves to stay in view. */
+  pinned?: boolean;
+}
 /** CSS-ready output: absolute/fixed `left`/`top` plus a centering transform. */
 interface AnchoredPosition {
   left: number;
   top: number;
   transform: string;
+  /** Where it sits: the placement asked for, or its opposite side when that had no room. */
+  placement: AnchoredPlacement;
+}
+interface AnchoredSize {
+  width: number;
+  height: number;
 }
 /**
- * Place an upright element around `box` (screen px). `avoid` is a screen
- * point the element must clear (e.g. the rotate knob): the element extends
- * ONLY the edge it sits on, and ONLY when the point protrudes past that
- * edge — so it clears the obstacle without ever shifting off-centre on the
- * other axis. When the point is on another side (e.g. a 90° shape, knob at
- * mid-height for a `top` placement) the edge is untouched and the element
- * stays centred on `box`.
- */
-/** What anchored UI attaches to: a content-space rect on a page, plus
- *  optional content-space points the UI must clear (e.g. a rotate knob).
+ * What placement needs to keep anchored UI on screen: the element's size, and
+ * the area it must stay inside, in the projector's space (the Stage's own box,
+ * or the browser window).
+ */
+interface AnchoredFit {
+  size: AnchoredSize;
+  view: AnchoredRect;
+}
+/** How a page is shown right now: its view scale, its rotation on screen, and its zoom (1 = 100%). */
+interface PageViewEnv {
+  scale: number;
+  rotation: 0 | 90 | 180 | 270;
+  zoom: number;
+}
+/** What anchored UI attaches to: a page-space rect on a page, plus
+ *  optional page-space points the UI must clear (e.g. a rotate knob).
  *  Structural — plugin anchor reads satisfy it without importing this
  *  package. */
 interface AnchorTarget {
-  pon: number;
+  page: PageRef;
   bounds: AnchoredRect;
+  /**
+   * Where the box is in a given view, for a box whose size or orientation
+   * depends on it (a note that keeps its size on screen). The projection
+   * calls it, so the anchor itself never has to follow the view.
+   */
+  boundsIn?: (view: PageViewEnv) => AnchoredRect | null;
   avoid?: AnchoredPoint[];
 }
 /**
- * A page surface's PROJECTION SNAPSHOT: how a content-space rect on a page
+ * A page surface's projection snapshot: how a page-space rect on a page
  * becomes screen coordinates, right now. Provided by `<Stage>`
  * (camera-driven, pure state, no DOM reads) and `<PageView>` (DOM-measured).
- * Deliberately NO subscribe here — when projection changes is a framework
+ * Deliberately no subscribe here — when projection changes is a framework
  * binding concern (see the module doc), not part of the snapshot.
  */
 interface ViewProjector {
@@ -144,38 +276,163 @@ interface ViewProjector {
    *     position:fixed, so no ancestor overflow can clip. (PageView)
    */
   space: 'overlay' | 'client';
-  /** Content-space rect on a page → coords in `space`. Null: not projectable
+  /** Page-space rect on a page → coords in `space`. Null: not projectable
    *  right now (page not shown / not measurable yet). */
-  toScreen(pon: number, rect: AnchoredRect): AnchoredRect | null;
-  toScreenPoint(pon: number, at: AnchoredPoint): AnchoredPoint | null;
+  toScreen(page: PageRef, rect: AnchoredRect): AnchoredRect | null;
+  toScreenPoint(page: PageRef, at: AnchoredPoint): AnchoredPoint | null;
   /** The page's live view facts (for anchor reads that need them — e.g. the
    *  screen-constant rotate-knob stalk), or null when the page isn't shown. */
-  viewEnv(pon: number): {
-    scale: number;
-    rotation: 0 | 90 | 180 | 270;
-    zoom: number;
-  } | null;
+  viewEnv(page: PageRef): PageViewEnv | null;
+  /** The area anchored UI can be seen in, in `space`: the surface's box, or
+   *  the window. Null while it isn't measurable yet. */
+  view(): AnchoredRect | null;
 }
 /**
- * THE anchored projection: anchor → screen position, in one pure call —
+ * The anchored projection: anchor → screen position, in one pure call —
  * projection, avoid-point transform, and the shared placement policy.
  * Frameworks recompute this inside their native reactive primitive
  * (a React render, a Vue `computed`, an Angular signal, a Svelte
  * `$derived`); nothing here schedules anything.
+ *
+ * Null when there is nothing to show: the page isn't shown, or the box is so
+ * far out of view that the UI around it can't reach into it.
  */
-declare function projectAnchoredTarget(projector: ViewProjector, anchor: AnchorTarget, placement: AnchoredPlacement, gap: number): AnchoredPosition | null;
+declare function projectAnchoredTarget(projector: ViewProjector, anchor: AnchorTarget, { placement, gap, pinned }: AnchoredOptions, fit?: AnchoredFit | null): AnchoredPosition | null;
 /**
- * The one genuinely BROWSER-driven invalidation: an element in normal
+ * The one genuinely browser-driven invalidation: an element in normal
  * document flow moves when the document scrolls or the window resizes —
  * no state change announces it. `<PageView>`'s binding registers this;
  * the Stage never does (its camera is state, delivered through render).
  */
 declare function observeClientGeometry(callback: () => void): () => void;
+/**
+ * The area anchored UI stays inside: the surface's own box (`'overlay'` space, the element's
+ * positioned parent) or the window (`'client'` space). Null while the element has no
+ * positioned parent to measure.
+ */
+declare function anchoredViewOf(element: HTMLElement, space: ViewProjector['space']): AnchoredRect | null;
+/** Whether two measurements give the same sizes, so a placement made from the first still holds. */
+declare function sameAnchoredFit(left: AnchoredFit | null, right: AnchoredFit): boolean;
+/**
+ * Measure anchored UI's `element` and the area it stays inside ({@link anchoredViewOf}) now, and
+ * again whenever either resizes: `report` hears every measurement (keep it when
+ * {@link sameAnchoredFit} says it changed). A camera move changes neither, so it measures nothing.
+ * Returns the function that stops measuring.
+ */
+declare function observeAnchoredFit(element: HTMLElement, space: ViewProjector['space'], report: (fit: AnchoredFit) => void): () => void;
+/**
+ * Place an upright element around `box` (screen px). `avoid` is a screen
+ * point the element must clear (e.g. the rotate knob): the element extends
+ * only the edge it sits on, and only when the point protrudes past that
+ * edge — so it clears the obstacle without ever shifting along the side.
+ * When the point is on another side (e.g. a 90° shape, knob at mid-height
+ * for a `top` placement) the edge is untouched.
+ */
 declare function positionAnchoredRect(box: AnchoredRect, placement: AnchoredPlacement, gap: number, avoid?: AnchoredPoint | null): AnchoredPosition;
+/**
+ * Place an element of a known size around `box`, inside `fit.view`. It sits
+ * where `placement` says when it fits there; otherwise on the opposite side,
+ * lined up the same way, when that fits or has more room. Then, while `box`
+ * is in view, it moves along both axes to stay inside the view, `gap` from
+ * its edges; UI whose box scrolled out of view goes with it. The result is
+ * the element's top-left corner, with no transform.
+ */
+declare function fitAnchoredRect(box: AnchoredRect, placement: AnchoredPlacement, gap: number, fit: AnchoredFit, avoid?: AnchoredPoint | null): AnchoredPosition;
+//#endregion
+//#region src/annotation-frame.d.ts
+/**
+ * An annotation's frame in pixels. The annotation plugin hands out each
+ * render item's frame (a box, its turn, and how large the page draws it) and
+ * the raster inside it, in page points; these put them in the page layer's
+ * pixels, with the CSS turn about the middle. Plain geometry over structural
+ * shapes, the same for every framework adapter, so none of them converts,
+ * turns or scales anything itself.
+ */
+/** A box in page points and its turn, degrees clockwise about its middle. */
+interface TurnedBox {
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  rotation: number;
+}
+/** A frame: its box and turn, and how large the page draws it relative to its own size. */
+interface FrameBox extends TurnedBox {
+  scale: number;
+}
+/** What a page layer converts with: its transform's `toPixels`, its turn, and its zoom (1 = 100%). */
+interface PageLayerTransform {
+  toPixels(point: {
+    x: number;
+    y: number;
+  }): {
+    x: number;
+    y: number;
+  };
+  rotation: number;
+  zoom: number;
+}
+/** A box in pixels and the CSS that turns it about its middle (`undefined` for no turn). */
+interface PixelBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  transform: string | undefined;
+}
+/** A frame in the page layer's pixels, and what a look drawn inside it needs. */
+interface FramePixels extends PixelBox {
+  /** Its turn on screen: its own and the page's, degrees clockwise. */
+  rotationOnScreen: number;
+  /**
+   * How large the frame is on screen relative to the annotation at its 100%
+   * size: the zoom, or for a body that keeps its size on screen, the zoom
+   * capped at 1. A look drawn at `design` size is scaled by this.
+   */
+  scale: number;
+  /** The frame's size at the annotation's 100% size, in pixels: the size a look is drawn at. */
+  design: {
+    width: number;
+    height: number;
+  };
+}
+/** A box inside its frame as CSS percentages of the frame, so it lands in place at any size. */
+interface FrameFraction {
+  left: string;
+  top: string;
+  width: string;
+  height: string;
+  transform: string | undefined;
+}
+/** A frame in the page layer's pixels: where it is, its turn, and the size and scale a look is drawn at. */
+declare function frameInPixels(frame: FrameBox, page: PageLayerTransform): FramePixels;
+/**
+ * A raster inside its frame, as CSS percentages of the frame. `raster`'s box
+ * is relative to the frame's box, as the annotation plugin hands it out.
+ */
+declare function rasterInFrame(raster: TurnedBox, frame: TurnedBox): FrameFraction;
+/** The frame a renderer's look draws into: the size to draw at, its turn on screen, and its scale. */
+interface AnnotationLookFrame {
+  width: number;
+  height: number;
+  /** Its turn on screen, the page's and its own, degrees clockwise. */
+  rotation: number;
+  /** How much the layer scales what the look draws. */
+  scale: number;
+}
+/**
+ * The frame a look draws into. A `scaled` look (the default) draws at the
+ * annotation's 100% size (`design`) inside an element of that size, which
+ * the layer scales by `scale` from its top-left corner; an unscaled look
+ * draws at the frame's size on screen.
+ */
+declare function lookFrameOf(frame: FramePixels, scaled: boolean): AnnotationLookFrame;
 //#endregion
 //#region src/cursor.d.ts
 /**
- * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the
+ * SVG → CSS cursor string. The armed-tool indicator is the cursor itself (the
  * only zero-latency pointer-locked pixel the web has — the OS composites it),
  * so an app hands its toolbar icon here and assigns the result via the
  * interaction hub's `setToolCursor`.
@@ -207,14 +464,43 @@ interface SvgCursorOptions {
 }
 /** Build the CSS cursor value: `url("data:image/svg+xml,…") x y, fallback`. */
 declare function svgCursor({ svg, hotspot, fallback }: SvgCursorOptions): string;
+/** One cursor slot: an SVG image ({@link SvgCursorOptions}) or a plain CSS cursor ('crosshair', 'url(…) 4 4, copy'). */
+type ToolCursorImage = SvgCursorOptions | string;
+/**
+ * A tool's cursors: the tool, and its cursors by keyword. Build `svg` from the same icon your
+ * toolbar shows, so the cursor and the button never drift apart.
+ */
+interface ToolCursorSpec {
+  toolId: string;
+  /**
+   * keyword → cursor: replace the keywords this tool can show (its own cursor, 'crosshair' or
+   * 'copy', and hover claims, 'text' over text) with the tool's look. Keywords left out show as
+   * they are: a markup tool's 'default' stays the bare arrow, a 'move' claim drops the icon. An
+   * SVG value's `fallback` defaults to the keyword it replaces.
+   */
+  cursors: Record<string, ToolCursorImage>;
+}
+/**
+ * A tool's cursors as CSS cursor values, for the interaction hub's `setToolCursor(toolId,
+ * cursors)`: a string stays as it is, an SVG becomes its `url(…)` cursor, falling back to the
+ * keyword it replaces unless it names its own fallback.
+ */
+declare function toolCursorsOf(cursors: Record<string, ToolCursorImage>): Record<string, string>;
 //#endregion
 //#region src/external-uri.d.ts
 /**
- * Validate a link URI for opening in the browser. Returns the URI when its
- * scheme is allowed (scheme-relative and bare URIs resolve as https), else
- * `null`. Never throws — a malformed URI is just an unopenable one.
+ * Validate a link URI for opening in the browser. Returns the absolute URI to open when its
+ * scheme is allowed (scheme-relative and bare `www.` URIs become https), else `null`. Never
+ * throws — a malformed URI is just an unopenable one.
  */
 declare function sanitizeExternalUri(uri: string, allowedSchemes?: Iterable<string>): string | null;
+/**
+ * Open a link target in a new tab when its address is allowed (`http`,
+ * `https`, `mailto`, `tel`); anything else is refused. True when it opened.
+ * Call it inside the user's click (the link plugin's `activate()` does), so
+ * the click is still the gesture that opens the tab.
+ */
+declare function openExternalUri(uri: string): boolean;
 //#endregion
 //#region src/actions-ui.d.ts
 /** Structural twin of plugin-actions' `ActionOrigin`. */
@@ -226,20 +512,20 @@ interface ActionsUiEffectContext {
 }
 /** Structural twin of plugin-actions' `ActionUiAdapter`. */
 interface ActionsUiAdapterShape {
-  openUri(uri: string, opts: {
+  openUri(uri: string, options: {
     isMap: boolean;
     origin: ActionsUiOrigin;
   }): void;
-  print(opts?: ActionsUiEffectContext): void;
-  alert?(message: string, opts: ActionsUiEffectContext & {
+  print(options?: ActionsUiEffectContext): void;
+  alert?(message: string, options: ActionsUiEffectContext & {
     icon: number;
     title?: string;
   }): void;
-  gotoPage?(page: number, opts: ActionsUiEffectContext): void;
+  gotoPage?(page: number, options: ActionsUiEffectContext): void;
 }
 interface DefaultActionsUiAdapterOptions {
   /**
-   * Per-handler overrides. Pass a FUNCTION for late binding (a binding's
+   * Per-handler overrides. Pass a function for late binding (a binding's
    * mutable handlers ref) — it is consulted on every effect, so a fresh
    * closure never needs a reinstall.
    */
@@ -250,12 +536,18 @@ interface DefaultActionsUiAdapterOptions {
 declare const createDefaultActionsUiAdapter: (options?: DefaultActionsUiAdapterOptions) => ActionsUiAdapterShape;
 //#endregion
 //#region src/painted-image.d.ts
-/** A browser image source whose object URL has an explicit lifetime. */
+/**
+ * A browser image source whose object URL has an explicit lifetime: an
+ * engine `PageImageHandle`, whose `objectUrl()` is cancellable and follows an
+ * `AbortSignal` through `abortWith()`.
+ */
 interface ObjectUrlImageSource {
-  objectUrl(signal?: AbortSignal): Promise<{
-    url: string;
-    revoke(): void;
-  }>;
+  objectUrl(): {
+    abortWith(signal: AbortSignal): PromiseLike<{
+      url: string;
+      revoke(): void;
+    }>;
+  };
 }
 interface PaintedImageCallbacks {
   onPainted(): void;
@@ -280,9 +572,9 @@ declare function bindPaintedImage(image: HTMLImageElement, source: ObjectUrlImag
  * stays plugin-free, per the layering law).
  *
  * Honesty about reach: `navigator.vibrate` works on Android browsers and is
- * NOT implemented in iOS Safari — there the default provider is a silent
+ * not implemented in iOS Safari — there the default provider is a silent
  * no-op until Apple ships a haptics API. (The community switch-control hacks
- * were evaluated and deliberately NOT shipped: Apple patched programmatic
+ * were evaluated and deliberately not shipped: Apple patched programmatic
  * triggering in iOS 26.5, leaving only tap-on-control tricks that don't fit a
  * viewer's gesture moments.) The real iPhone haptic today comes through a
  * native shell: a WKWebView embedder installs a script message handler and
@@ -303,7 +595,7 @@ interface WebPlatformFeedback {
 declare const vibrationFeedback: WebPlatformFeedback;
 /**
  * A provider for native iOS shells: forwards each call to a WKWebView script
- * message handler the HOST APP installed under `handlerName` — an explicit
+ * message handler the host app installed under `handlerName` — an explicit
  * contract between the embedder and their own app, never a global this library
  * sniffs on its own. The message shape is
  * `{ family: 'selection' } | { family: 'impact', weight } | { family: 'notify', kind }`;
@@ -315,40 +607,40 @@ declare const wkFeedback: (handlerName: string, fallback?: WebPlatformFeedback)
 //#endregion
 //#region src/stage-gestures.d.ts
 /**
- * Stage gesture controller — the ONE DOM input binding for a Stage surface,
+ * Stage gesture controller — the one DOM input binding for a Stage surface,
  * shared by every framework adapter (React, Angular, …) so the feel can never
  * drift between them.
  *
  * The premise (see the stage plugin's camera doctrine): desktop inputs arrive
  * with physics already applied by the OS — momentum lives in the wheel stream,
- * a trackpad pinch is one pre-arbitrated gesture stream. Touch arrives RAW:
+ * a trackpad pinch is one pre-arbitrated gesture stream. Touch arrives raw:
  * with `touch-action: none` the platform scroller is out of the loop, so the
  * ballistics (velocity → fling) and the arbitration (is this contact a scroll,
  * a pinch, a tap, or a tool gesture?) must be synthesized here.
  *
- * Arbitration is MODALITY-AWARE:
+ * Arbitration is modality-aware:
  *   - touch  — navigation-first: one finger pans (whatever tool is armed), two
  *     fingers pinch-zoom around their centroid, release velocity flings, a tap
  *     forwards as a click, a double-tap zoom-toggles, a long-press hands the
  *     gesture to the interaction hub (text selection), and a second finger
- *     landing mid-tool-gesture CANCELS it into a pinch (the Notes/Procreate
+ *     landing mid-tool-gesture cancels it into a pinch (the Notes/Procreate
  *     convention).
  *   - mouse/pen — tool-first, exactly the pre-existing behavior: with a hub,
  *     every down/move/up forwards (pan is the pan tool's job); without one,
  *     dragging pans. Wheel and Safari-trackpad gesture events are unchanged.
  *
- * Camera writes are rAF-COALESCED: pointer events only update gesture state;
+ * Camera writes are rAF-coalesced: pointer events only update gesture state;
  * one animation-frame tick applies at most one pan and one zoom per frame,
  * inside the host's begin/endGesture transaction. Events may arrive at 120 Hz;
  * the camera moves at display rate.
  *
- * Dependency note: this module speaks to the stage through the STRUCTURAL
- * {@link StageGestureHost} interface (satisfied by `StageCapability`) and to
+ * Dependency note: this module speaks to the stage through the structural
+ * {@link StageGestureHost} interface (satisfied by `StageHostCapability`) and to
  * the interaction hub through {@link StageGestureSink} (a closure the adapter
  * builds) — @embedpdf/web stays free of plugin imports, per the layering law.
  */
 type StagePointerKind = 'mouse' | 'pen' | 'touch';
-/** What the controller needs from the camera — `StageCapability` satisfies it. */
+/** What the controller needs from the camera — `StageHostCapability` satisfies it. */
 interface StageGestureHost {
   panBy(dxScreen: number, dyScreen: number): void;
   zoomAround(screenPt: {
@@ -362,7 +654,7 @@ interface StageGestureHost {
   /** Momentum pan from a release velocity in screen px/s. */
   fling(velocityX: number, velocityY: number): void;
   /** True while a tween/fling runs — a touch-down then is a "catch", not a tap. */
-  cameraInMotion(): boolean;
+  isMoving(): boolean;
   doubleTapZoom(screenPt: {
     x: number;
     y: number;
@@ -370,25 +662,25 @@ interface StageGestureHost {
 }
 /**
  * Where non-navigation gestures go — the adapter's bridge to the interaction
- * hub. Every callback receives the ORIGINAL PointerEvent so the adapter can
+ * hub. Every callback receives the original PointerEvent so the adapter can
  * resolve pages/points exactly as it always has. Omit the sink entirely for a
  * hub-less (built-in pan) stage.
  */
 interface StageGestureSink {
-  down(e: PointerEvent, clickCount: number): void;
-  move(e: PointerEvent): void;
-  up(e: PointerEvent): void;
+  down(event: PointerEvent, clickCount: number): void;
+  move(event: PointerEvent): void;
+  up(event: PointerEvent): void;
   /** The gesture was taken over by navigation (second finger → pinch) or
    *  cancelled by the system — abort, don't commit. */
-  cancel(e: PointerEvent): void;
+  cancel(event: PointerEvent): void;
   /** Pointer travel with no gesture in flight — cursor feedback. */
-  hover(e: PointerEvent): void;
+  hover(event: PointerEvent): void;
   /** A touch press held still: hand the gesture to the hub (the adapter
    *  typically forwards it as a word-select down). Subsequent move/up arrive
    *  via {@link move}/{@link up}. */
-  longPress(e: PointerEvent): void;
+  longPress(event: PointerEvent): void;
   /**
-   * Touch-consent pre-flight, asked at touch-down BEFORE the contact is
+   * Touch-consent pre-flight, asked at touch-down before the contact is
    * classified: does a tool have standing to own this contact? True when the
    * armed tool takes fingers wholesale (a drawing tool) or something under
    * the point claims its drags (a selected annotation's body or handles).
@@ -396,7 +688,7 @@ interface StageGestureSink {
    * where a second finger still cancels it into a pinch. Must be a pure
    * read. Absent = never; the contact navigates.
    */
-  claimsPoint?(e: PointerEvent): boolean;
+  claimsPoint?(event: PointerEvent): boolean;
 }
 /** The wheel fields the zoom classifier reads (see `./wheel`'s `WheelSample`). */
 interface StageWheelSample {
@@ -411,7 +703,7 @@ interface StageGestureOptions {
    *  swallowed, never page-zooming the browser. Default true. */
   zoomGestures?: boolean;
   /** The wheel → zoom-factor classifier. Defaults to this package's
-   *  `wheelZoomFactor` (browser wheel classification lives HERE, with the rest
+   *  `wheelZoomFactor` (browser wheel classification lives here, with the rest
    *  of the browser input handling); inject to override or to fake in tests. */
   wheelZoomFactor?: (sample: StageWheelSample) => number;
   /** Tool routing for non-navigation gestures; omit for built-in-pan stages. */
@@ -429,7 +721,7 @@ interface StageGestureOptions {
  * Release velocity from a trail of pointer samples: the mean velocity over the
  * trailing `windowMs` (first-to-last inside the window). Null when the trail is
  * too thin or too stale to trust — the standard "held still, then let go"
- * case, which must NOT fling. Pure; exported for tests.
+ * case, which must not fling. Pure; exported for tests.
  */
 declare function computeReleaseVelocity(samples: ReadonlyArray<{
   t: number;
@@ -440,7 +732,7 @@ declare function computeReleaseVelocity(samples: ReadonlyArray<{
   vy: number;
 } | null;
 /** Attach the gesture controller to a Stage container. Returns the detach fn. */
-declare function createStageGestureController(el: HTMLElement, host: StageGestureHost, options: StageGestureOptions): () => void;
+declare function createStageGestureController(element: HTMLElement, host: StageGestureHost, options: StageGestureOptions): () => void;
 //#endregion
 //#region src/selection-handles.d.ts
 /**
@@ -450,12 +742,12 @@ declare function createStageGestureController(el: HTMLElement, host: StageGestur
  * `handles` module; this file never imports it, per the layering law:
  * structural interfaces only).
  *
- * The load-bearing subtlety this module owns: the pointer-DOWN shield must be
- * a NATIVE listener. The stage's gesture controller listens natively on the
+ * The load-bearing subtlety this module owns: the pointer-down shield must be
+ * a native listener. The stage's gesture controller listens natively on the
  * container, so a framework-synthetic stopPropagation (React runs its
- * handlers at the root, AFTER the container's native ones) would be too late
+ * handlers at the root, after the container's native ones) would be too late
  * — the stage would already be panning underneath the handle drag. Once the
- * down is captured here, movement tracks by CLIENT DELTAS from the handle's
+ * down is captured here, movement tracks by client deltas from the handle's
  * own base point: no DOM geometry reads, and the client↔overlay conversion
  * cancels out.
  */
@@ -472,7 +764,7 @@ interface SelectionHandleSession {
 interface AttachSelectionHandleOptions {
   /**
    * Called at pointer-down to arm a drag: return the drag session plus the
-   * handle's current BASE point in overlay space (the bar's midpoint — the
+   * handle's current base point in overlay space (the bar's midpoint — the
    * point the user grabbed). Return null to decline (endpoint vanished, page
    * not laid out) — the press then does nothing and nothing is captured.
    */
@@ -482,30 +774,30 @@ interface AttachSelectionHandleOptions {
   } | null;
 }
 /** Bind one handle element. Returns the detach fn. */
-declare function attachSelectionHandle(el: HTMLElement, options: AttachSelectionHandleOptions): () => void;
+declare function attachSelectionHandle(element: HTMLElement, options: AttachSelectionHandleOptions): () => void;
 //#endregion
 //#region src/stage-surface.d.ts
 interface SurfacePoint {
   x: number;
   y: number;
 }
-/** What the binding needs from the stage — `StageCapability` satisfies it. */
+/** What the binding needs from the stage — `StageHostCapability` satisfies it. */
 interface StageSurfaceHost extends StageGestureHost {
-  setViewport(size: {
+  setViewportSize(size: {
     width: number;
     height: number;
   }): void;
   setDevicePixelRatio(ratio: number): void;
   /** Viewport point → the page under it (with per-page display context), or null over a gap. */
-  pageAt(screen: SurfacePoint): {
-    pon: number;
+  getPageAt(screen: SurfacePoint): {
+    ref: PageRef;
     point: SurfacePoint;
     scale?: number;
     rotation?: 0 | 90 | 180 | 270;
     zoom?: number;
   } | null;
-  /** Viewport point → a SPECIFIC page's content space, unclamped (frame-stable projection). */
-  pointOnPage(pon: number, screen: SurfacePoint): SurfacePoint | null;
+  /** Viewport point → a specific page's page space, unclamped (frame-stable projection). */
+  viewportToPage(page: PageRef, screen: SurfacePoint): SurfacePoint | null;
 }
 /**
  * The page-resolved sample the binding hands the hub — structurally a
@@ -517,13 +809,13 @@ interface StageSurfaceSample {
   phase: 'down' | 'move' | 'up' | 'cancel';
   viewport: SurfacePoint;
   page?: {
-    pon: number;
+    ref: PageRef;
     point: SurfacePoint;
     scale?: number;
     rotation?: 0 | 90 | 180 | 270;
     zoom?: number;
   };
-  project: (pon: number) => SurfacePoint | null;
+  project: (page: PageRef) => SurfacePoint | null;
   modifiers: {
     shift: boolean;
     alt: boolean;
@@ -535,11 +827,11 @@ interface StageSurfaceSample {
   gesture?: 'long-press';
   source?: string;
 }
-/** What the binding needs from the interaction hub — `InteractionCapability` satisfies it. */
+/** What the binding needs from the interaction hub — `InteractionHostCapability` satisfies it. */
 interface StageSurfaceHub {
-  dispatch(sample: StageSurfaceSample): void;
-  activeTool(): {
-    touchDirect?: boolean;
+  dispatchPointer(sample: StageSurfaceSample): void;
+  getActiveTool(): {
+    touch?: 'draw' | 'tap';
   };
   wouldClaimTouch(sample: StageSurfaceSample): boolean;
 }
@@ -547,7 +839,7 @@ interface StageSurfaceOptions {
   /** Route pointer input to the interaction hub (page-resolved samples) instead
    *  of built-in drag-to-pan. Omit/null for a hub-less stage. */
   hub?: StageSurfaceHub | null;
-  /** The lens identity stamped on every sample (`StageCapability.lensId()`),
+  /** The lens identity stamped on every sample (`StageHostCapability.getLensId()`),
    *  so lens-scoped handlers only see their own stage's input. */
   source?: string;
   /** Ambient zoom gestures (see {@link StageGestureOptions}). Default true. */
@@ -556,7 +848,7 @@ interface StageSurfaceOptions {
   wheelZoomFactor?: (sample: StageWheelSample) => number;
 }
 /** Attach the full surface binding. Returns the detach fn. */
-declare function createStageSurface(el: HTMLElement, stage: StageSurfaceHost, options?: StageSurfaceOptions): () => void;
+declare function createStageSurface(element: HTMLElement, stage: StageSurfaceHost, options?: StageSurfaceOptions): () => void;
 //#endregion
 //#region src/wheel.d.ts
 /**
@@ -566,14 +858,14 @@ declare function createStageSurface(el: HTMLElement, stage: StageSurfaceHost, op
  * A ctrl/cmd wheel event is one of three physically different inputs that
  * happen to share an event type, each with its own unit system:
  *
- *   • trackpad PINCH — browsers (Chrome/Edge/Firefox) synthesize ctrl+wheel
+ *   • trackpad pinch — browsers (Chrome/Edge/Firefox) synthesize ctrl+wheel
  *     px-deltas scaled to the de-facto convention that `exp(-Δ/100)` tracks
  *     the physical finger scale 1:1. Anything weaker feels dead (the content
  *     must track the fingers — the Figma/maps feel).
- *   • mouse NOTCHES — coarse steps: ±100/±120 px in Chrome, lines/pages mode
+ *   • mouse notches — coarse steps: ±100/±120 px in Chrome, lines/pages mode
  *     in Firefox. The pinch mapping would triple per click; a notch instead
  *     steps by 1.2, the same ratio as the zoom buttons.
- *   • cmd + continuous SCROLL — real scroll px, big and streaming (with
+ *   • cmd + continuous scroll — real scroll px, big and streaming (with
  *     momentum): a gentle scrub coefficient. A cmd+mouse notch (±120 px)
  *     lands within 0.3% of the 1.2 button step, so it needs no special case.
  *
@@ -588,7 +880,7 @@ interface WheelSample {
   metaKey: boolean;
 }
 /** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
-declare function wheelZoomFactor(e: WheelSample): number;
+declare function wheelZoomFactor(sample: WheelSample): number;
 //#endregion
 //#region src/byte-store.d.ts
 /**
@@ -614,11 +906,11 @@ interface IndexedDbByteStoreOptions {
   storeName?: string;
 }
 /** Open (creating on first use) one IndexedDB object store keyed by id. */
-declare function indexedDbByteStore(dbName: string, opts?: IndexedDbByteStoreOptions): ByteStore;
+declare function indexedDbByteStore(dbName: string, options?: IndexedDbByteStoreOptions): ByteStore;
 //#endregion
 //#region src/rich-text-editor.d.ts
 /**
- * Rich text editor binding — the ONE contentEditable mechanics module for a
+ * Rich text editor binding — the one contentEditable mechanics module for a
  * FreeText annotation, shared by every framework adapter (React, Angular,
  * Vue, Svelte…) so editing can never drift between them:
  *
@@ -631,7 +923,7 @@ declare function indexedDbByteStore(dbName: string, opts?: IndexedDbByteStoreOpt
  *   • hold re-renders during IME composition, paste as plain text, forward
  *     Cmd/Ctrl+B/I/U as commands
  *
- * The browser owns typing; this module only translates. The POLICY — what a
+ * The browser owns typing; this module only translates. The policy — what a
  * command does to the document, when to commit, what a family maps to —
  * belongs to the host (the annotation plugin), reached through the
  * structural {@link RichTextEditorHost}: @embedpdf/web imports no plugin,
@@ -642,9 +934,9 @@ declare function indexedDbByteStore(dbName: string, opts?: IndexedDbByteStoreOpt
  * runs concatenated, a hard break inside a run is a `\r` too. The same
  * arithmetic the core's run algebra uses.
  *
- * Known limits (by design, recorded in the plan): the browser's native undo
- * stack does not span a host-driven restyle; DOM line wrapping approximates
- * the engine's layout, the appearance stream is the truth.
+ * Known limits, by design: the browser's native undo stack does not span a
+ * host-driven restyle; DOM line wrapping approximates the engine's layout,
+ * the appearance stream is the truth.
  */
 type RichTextEditorDecoration = 'underline' | 'line-through' | 'word';
 type RichTextEditorScript = 'normal' | 'sub' | 'super';
@@ -689,12 +981,12 @@ interface RichTextEditorHost {
   /** A keyboard command the host applies to the current selection. */
   onCommand(command: RichTextEditorCommand): void;
   /** The CSS family list for a PDF family ("Helvetica" → a web stack, a
-   *  registered family → itself, mounted as a @font-face). */
+   *  registered family → the family its face is mounted under, see `mountWebFont`). */
   cssFontFamily(family: string): string;
 }
 interface RichTextEditorProps {
   document: RichTextEditorDocument;
-  /** Screen px per content unit (the page scale): sizes are content points. */
+  /** Screen px per page unit (the page scale): sizes are page points. */
   scale: number;
 }
 interface RichTextEditorBinding {
@@ -768,26 +1060,166 @@ declare function offsetOfPosition(root: EditorNode, position: EditorPosition): n
  *  else the empty block / the slot after a hard break the offset names. */
 declare function positionOfOffset(root: EditorNode, offset: number): EditorPosition | null;
 /** Bind one contentEditable element. Returns the Svelte-action-shaped handle. */
-declare function attachRichTextEditor(el: HTMLElement, host: RichTextEditorHost, initial: RichTextEditorProps): RichTextEditorBinding;
+declare function attachRichTextEditor(element: HTMLElement, host: RichTextEditorHost, initial: RichTextEditorProps): RichTextEditorBinding;
 //#endregion
 //#region src/web-font.d.ts
 /**
  * Mount a registered font for the DOM: the engine lays text out with the
  * font's bytes, the browser needs the same face as a `@font-face` so the
  * live editor and the vector renderer show the glyphs the appearance stream
- * will bake. The family name is the font's KEY — the CSS family the
- * annotation plugin emits for a registered font (`cssFontFamily`) — so
- * mounting under the key is what makes the two agree.
+ * will bake. The face's family is {@link webFontFamily} of the key.
  *
  * Returns the unmount. Idempotent per (document, key): a second mount of a
  * key already in the document's font set is a no-op that still returns an
- * unmount of its own (the face leaves when the LAST holder unmounts).
+ * unmount of its own (the face leaves when the last holder unmounts).
  */
 declare function mountWebFont(key: string, data: ArrayBuffer | Uint8Array, options?: {
   document?: Document;
   weight?: number | string;
   style?: 'normal' | 'italic';
 }): Promise<() => void>;
+/**
+ * A font program to mount: its CSS family, its style, and its bytes. The
+ * structural twin of `@embedpdf/core-fonts`' `FontProgram`, whose family is
+ * named by the program's hash, so it never shadows another font.
+ */
+interface MountableFontProgram {
+  readonly family: string;
+  readonly weight: number;
+  readonly style: 'normal' | 'italic';
+  load(): Promise<Uint8Array>;
+}
+/**
+ * Mount a program under its own family, as it is (already in the viewer's
+ * namespace), in its own weight and style, so CSS asking for that style takes
+ * it as it is and never fakes a bold or an italic. Refcounted per document
+ * like {@link mountWebFont}; resolves with the unmount.
+ */
+declare function mountFontProgram(program: MountableFontProgram, options?: {
+  document?: Document;
+}): Promise<() => void>;
+/**
+ * The programs one layer has mounted: each mounted once, however often it's
+ * asked for, and all let go together when the layer goes (a program another
+ * layer holds stays, refcounted per document). A mount after the release
+ * holds again, for a layer that comes back (React's strict mode runs effects
+ * twice).
+ */
+declare function createFontMounts(options?: {
+  document?: Document;
+}): {
+  mount(programs: readonly MountableFontProgram[]): void;
+  release(): void;
+};
+//#endregion
+//#region src/object-urls.d.ts
+/** Bytes and their type, as the stamp and annotation plugins hand out previews. */
+interface PictureBytes {
+  readonly bytes: Uint8Array;
+  readonly mimeType?: string | null;
+}
+/** An object URL, and how to release it. */
+interface ObjectUrl {
+  readonly url: string;
+  revoke(): void;
+}
+/** An object URL for bytes. Revoke it when nothing shows it any more. */
+declare function objectUrlOf(picture: PictureBytes): ObjectUrl;
+/**
+ * Load a picture and hand its object URL to `onUrl` once it's there (nothing
+ * for `null`). What it returns cancels: a load still running is dropped, and
+ * the URL is revoked. Keep showing the previous URL until `onUrl` brings the
+ * next one, so a swap never flickers.
+ */
+declare function loadObjectUrl(load: () => Promise<PictureBytes | null>, onUrl: (url: string) => void): () => void;
+/**
+ * One picture as its owner hands it out (the annotation plugin's or the form
+ * plugin's `renderAppearances`): an item in one of its states, at its version.
+ */
+interface AppearancePicture<Ref> {
+  readonly ref: Ref;
+  /** The state it draws (`/AS`), or `null` for an item without states. */
+  readonly state: string | null;
+  /** The box it was rendered into, in page points. */
+  readonly rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** The version of its item it shows: an item at another version looks different now. */
+  readonly version: number;
+  readonly image: ObjectUrlImageSource;
+}
+/** A picture's URL, the box it was rendered into, and the version of its item it shows. */
+interface AppearanceUrl {
+  url: string;
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  version: number;
+}
+/**
+ * The picture an item shows, from {@link loadAppearanceUrls}: the one of the
+ * state it's in (`'Off'` when it names none), or its only picture when it has
+ * no states; `null` until it's loaded.
+ */
+declare function shownAppearance(urls: Readonly<Record<string, AppearanceUrl>>, itemKey: string, appearanceState: string | null): AppearanceUrl | null;
+/**
+ * The engine's picture of an annotation as a renderer gets it (its
+ * `appearance`): `{ url }` once {@link loadAppearanceUrls} has loaded the one
+ * of the state it shows, else `null`.
+ */
+declare function bakedAppearanceOf(urls: Readonly<Record<string, AppearanceUrl>>, itemKey: string, appearanceState: string | null): {
+  url: string;
+} | null;
+/**
+ * The URLs a layer shows, kept from one load to the next: a set stays valid
+ * until the set after it is shown, so a picture that shows again before the
+ * next set arrives (an annotation an undo brings back) still has a live URL.
+ * One per layer, passed to every load; `release()` when the layer goes.
+ */
+interface ShownUrls {
+  /** Revoke the URLs shown now: the layer is going. A later load starts afresh. */
+  release(): void;
+}
+/** What a layer shows, for {@link loadAppearanceUrls}. */
+declare function createShownUrls(): ShownUrls;
+/**
+ * Load a page's pictures, every state of every item, and hand their URLs to
+ * `onLoaded` once all of them are there; the set `shown` held before is
+ * revoked then. {@link shownAppearance} picks an item's: a check box that
+ * changes shows its other picture at once. What it returns cancels: the load
+ * is aborted and the URLs it made are revoked, unless it already handed them
+ * over. Start it again when the page's appearance epoch or the appearance
+ * scale changes, never mid-gesture.
+ */
+declare function loadAppearanceUrls<Ref>(shown: ShownUrls, load: (signal: AbortSignal) => Promise<readonly AppearancePicture<Ref>[]>, keyOf: (ref: Ref) => string, onLoaded: (urls: Record<string, AppearanceUrl>) => void): () => void;
+//#endregion
+//#region src/picture-or-painting.d.ts
+type PictureOrPainting<Painting> = {
+  readonly kind: 'picture';
+  readonly picture: AppearanceUrl;
+} | {
+  readonly kind: 'painting';
+  readonly painting: Painting;
+} | null;
+interface LookState<Painting> {
+  /** The owner draws the item live now: a pending change, a widget's look not confirmed yet. */
+  readonly pending: boolean;
+  /** Its picture, for the state it shows; `null` when there is none. */
+  readonly picture: AppearanceUrl | null;
+  /** The item's picture version now. */
+  readonly version: number;
+  /** The page's pictures have loaded at least once. */
+  readonly loaded: boolean;
+  /** Its live drawing; `null` for an item that has none. */
+  readonly paint: () => Painting | null;
+}
+declare function pictureOrPainting<Painting>(look: LookState<Painting>): PictureOrPainting<Painting>;
 //#endregion
 //#region src/web-font-metrics.d.ts
 /**
@@ -848,5 +1280,2248 @@ declare function lineModelFor(cssFamily: string, measure?: (cssFamily: string) =
  */
 declare function firstLineShiftFor(cssFamily: string, fontSize: number, measure?: (cssFamily: string) => WebFontMetrics | null): number;
 //#endregion
-export { type ActionsUiAdapterShape, type ActionsUiEffectContext, type ActionsUiOrigin, type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ByteStore, type ClipboardSelectionSource, type DefaultActionsUiAdapterOptions, type EditorDocumentFactory, type EditorElement, type EditorNode, type EditorPosition, type EditorRoot, type EditorStyle, type IndexedDbByteStoreOptions, type LineModel, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type RichTextEditorAlign, type RichTextEditorBinding, type RichTextEditorCommand, type RichTextEditorDecoration, type RichTextEditorDocument, type RichTextEditorHost, type RichTextEditorParagraph, type RichTextEditorProps, type RichTextEditorRange, type RichTextEditorRun, type RichTextEditorScript, type RichTextEditorStyle, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebFontMetrics, type WebPlatformFeedback, type WheelSample, applyFirstLineShift, attachRichTextEditor, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createDefaultActionsUiAdapter, createStageGestureController, createStageSurface, firstLineShiftFor, indexedDbByteStore, lineModelFor, mountWebFont, observeClientGeometry, offsetOfPosition, pickFile, pickImageFile, positionAnchoredRect, positionOfOffset, projectAnchoredTarget, renderRichText, sanitizeExternalUri, saveFile, serializeRichText, styleDeltaOf, svgCursor, vibrationFeedback, webFontMetrics, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
+//#region src/theme.d.ts
+/**
+ * The `--epdf-*` CSS variables that theme EmbedPDF, and the CSS value each
+ * painted part uses. Every paint setting (a color, a line width, a dash, a
+ * shadow, an opacity) can also come from a variable, and any variable wins over
+ * any setting: a part looks for its own variable, then the variables of the
+ * parts its default follows (another part, its plugin's accent, the viewer's
+ * accent), and only then uses its setting's value. Parts you style yourself
+ * have no setting, only a variable and a built-in look.
+ *
+ * {@link EPDF_VARIABLES} is plain data with no imports, so a script can read the
+ * list without a browser. {@link epdfThemeVariables} turns a theme written with
+ * setting names into the variables.
+ */
+/**
+ * A part other parts' defaults follow: an accent, or a part whose setting is
+ * another part's default, such as the handles the rotation handle looks like.
+ */
+type EpdfFollowedVariable = 'accent' | 'annotation-accent' | 'annotation-handle-fill' | 'annotation-handle-stroke';
+/** One themable part, named by its variable without the `--epdf-` prefix. */
+interface EpdfVariableDefinition {
+  /**
+   * The setting the variable overrides, as `<plugin>.<path>`: `viewer.` for the
+   * viewer's own settings, `[]` for every entry of a list. Absent for a part you
+   * style yourself, which only has CSS.
+   */
+  readonly setting?: string;
+  /**
+   * The part whose setting is this part's default, looked up right after the
+   * part's own variable, and followed in turn: the rotation handle's stroke
+   * follows the handles' stroke, which follows the annotation accent, which
+   * follows the viewer's. So `--epdf-annotation-handle-stroke` reaches the
+   * rotation handle before any accent does.
+   */
+  readonly follows?: EpdfFollowedVariable;
+  /** A translucent default, the accent it follows at this percent: see {@link mixAccent}. */
+  readonly accentPercent?: number;
+  /**
+   * The CSS value of each keyword, for a setting that takes keywords instead of
+   * a CSS value.
+   */
+  readonly keywords?: Readonly<Record<string, string>>;
+  /** What the part paints when neither its setting nor a variable is set. */
+  readonly default: string;
+}
+/** Every theming variable, in the order the theming page lists them. */
+declare const EPDF_VARIABLES: {
+  readonly accent: {
+    readonly setting: "viewer.accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'page-background': {
+    readonly setting: "viewer.page.background";
+    readonly default: "#ffffff";
+  };
+  readonly 'page-shadow': {
+    readonly setting: "viewer.page.shadow";
+    readonly default: "0 6px 18px rgb(0 0 0 / 0.18)";
+  };
+  readonly 'annotation-accent': {
+    readonly setting: "annotation.chrome.accent";
+    readonly follows: "accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-outline': {
+    readonly setting: "annotation.chrome.outline.color";
+    readonly follows: "annotation-accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-outline-width': {
+    readonly setting: "annotation.chrome.outline.width";
+    readonly default: "1";
+  };
+  readonly 'annotation-outline-dash': {
+    readonly setting: "annotation.chrome.outline.style";
+    readonly keywords: {
+      readonly solid: "none";
+      readonly dashed: "4 3";
+    };
+    readonly default: "none";
+  };
+  readonly 'annotation-handle-fill': {
+    readonly setting: "annotation.chrome.handles.fill";
+    readonly default: "#ffffff";
+  };
+  readonly 'annotation-handle-stroke': {
+    readonly setting: "annotation.chrome.handles.stroke";
+    readonly follows: "annotation-accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-rotation-handle-fill': {
+    readonly setting: "annotation.chrome.rotationHandle.fill";
+    readonly follows: "annotation-handle-fill";
+    readonly default: "#ffffff";
+  };
+  readonly 'annotation-rotation-handle-stroke': {
+    readonly setting: "annotation.chrome.rotationHandle.stroke";
+    readonly follows: "annotation-handle-stroke";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-guide': {
+    readonly setting: "annotation.chrome.guides.color";
+    readonly default: "#e91e63";
+  };
+  readonly 'annotation-rotation-guide': {
+    readonly setting: "annotation.chrome.guides.rotationColor";
+    readonly follows: "annotation-accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-guide-width': {
+    readonly setting: "annotation.chrome.guides.width";
+    readonly default: "1.5";
+  };
+  readonly 'annotation-guide-dash': {
+    readonly setting: "annotation.chrome.guides.style";
+    readonly keywords: {
+      readonly solid: "none";
+      readonly dashed: "4 3";
+    };
+    readonly default: "none";
+  };
+  readonly 'annotation-marquee-fill': {
+    readonly setting: "annotation.chrome.marquee.fill";
+    readonly follows: "annotation-accent";
+    readonly accentPercent: 8;
+    readonly default: "color-mix(in srgb, #3858e9 8%, transparent)";
+  };
+  readonly 'annotation-marquee-stroke': {
+    readonly setting: "annotation.chrome.marquee.stroke";
+    readonly follows: "annotation-accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'annotation-text-outline': {
+    readonly setting: "annotation.chrome.textOutline";
+    readonly follows: "annotation-accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'readout-background': {
+    readonly setting: "annotation.chrome.readout.background";
+    readonly default: "rgb(0 0 0 / 0.8)";
+  };
+  readonly 'readout-color': {
+    readonly setting: "annotation.chrome.readout.color";
+    readonly default: "#ffffff";
+  };
+  readonly 'ghost-opacity': {
+    readonly setting: "annotation.tools[].ghost.opacity";
+    readonly default: "0.5";
+  };
+  readonly 'text-selection': {
+    readonly setting: "selection.color";
+    readonly follows: "accent";
+    readonly accentPercent: 35;
+    readonly default: "color-mix(in srgb, #3858e9 35%, transparent)";
+  };
+  readonly 'text-selection-handle': {
+    readonly setting: "selection.handles.color";
+    readonly follows: "accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'text-selection-handle-shadow': {
+    readonly setting: "selection.handles.shadow";
+    readonly default: "0 1px 4px rgb(0 0 0 / 0.35)";
+  };
+  readonly 'search-highlight': {
+    readonly setting: "search.highlight.color";
+    readonly default: "#ffd500";
+  };
+  readonly 'search-highlight-active': {
+    readonly setting: "search.highlight.activeColor";
+    readonly default: "#ff9632";
+  };
+  readonly 'search-blend-mode': {
+    readonly setting: "search.highlight.blendMode";
+    readonly default: "multiply";
+  };
+  readonly 'form-focus': {
+    readonly setting: "form.focus.color";
+    readonly follows: "accent";
+    readonly default: "#3858e9";
+  };
+  readonly 'form-field-border': {
+    readonly setting: "form.fields.border";
+    readonly follows: "accent";
+    readonly accentPercent: 55;
+    readonly default: "color-mix(in srgb, #3858e9 55%, transparent)";
+  };
+  readonly 'form-field-background': {
+    readonly setting: "form.fields.background";
+    readonly default: "rgb(255 255 255 / 0.92)";
+  };
+  readonly 'form-field-color': {
+    readonly setting: "form.fields.color";
+    readonly default: "#1f2a44";
+  };
+  readonly 'scrollbar-thumb': {
+    readonly default: "rgb(0 0 0 / 0.4)";
+  };
+  readonly 'toolbar-surface': {
+    readonly default: "#ffffff";
+  };
+  readonly 'toolbar-border': {
+    readonly default: "rgb(0 0 0 / 0.15)";
+  };
+  readonly 'toolbar-active': {
+    readonly default: "rgb(0 0 0 / 0.12)";
+  };
+  readonly 'font-mono': {
+    readonly default: "ui-monospace, monospace";
+  };
+};
+type Definitions = typeof EPDF_VARIABLES;
+/** A theming variable's name, without its `--epdf-` prefix. */
+type EpdfVariable = keyof Definitions;
+/** A variable that overrides a setting: its part paints with {@link paint}. */
+type EpdfSettingVariable = { [Name in EpdfVariable]: Definitions[Name] extends {
+  readonly setting: string;
+} ? Name : never; }[EpdfVariable];
+/** A part you style yourself, which has no setting: it paints with {@link paintDefault}. */
+type EpdfCssOnlyVariable = Exclude<EpdfVariable, EpdfSettingVariable>;
+/** A part whose default is the accent at a percent: that default comes from {@link mixAccent}. */
+type EpdfTranslucentVariable = { [Name in EpdfVariable]: Definitions[Name] extends {
+  readonly accentPercent: number;
+} ? Name : never; }[EpdfVariable];
+/**
+ * The CSS value for a painted part: its own variable, then the variables of the
+ * parts its default follows (the part it follows, its plugin's accent,
+ * `--epdf-accent`), then the setting's value. Put it in a style (`style.stroke`),
+ * not an SVG attribute, because attributes don't read `var()`.
+ *
+ * `paint('annotation-outline', '#3858e9')` is
+ * `var(--epdf-annotation-outline, var(--epdf-annotation-accent, var(--epdf-accent, #3858e9)))`,
+ * `paint('annotation-rotation-handle-fill', '#ffffff')` is
+ * `var(--epdf-annotation-rotation-handle-fill, var(--epdf-annotation-handle-fill, #ffffff))`,
+ * and `paint('search-highlight', '#ffd500')` is `var(--epdf-search-highlight, #ffd500)`.
+ */
+declare function paint(name: EpdfSettingVariable, settingValue: string | number): string;
+/**
+ * The default of a translucent part, such as "the accent at 35%": the accent it
+ * follows, variables included, mixed with transparent. Use it as the setting's
+ * value while the part's own setting is unset.
+ *
+ * The accent variables sit inside the mix, not in {@link paint}'s lookup: there
+ * a set `--epdf-accent` would paint at full strength, and CSS can't mix a
+ * variable only when it's set. So a part's own setting, when you give one, wins
+ * over the accent variables, though not over the part's own variable.
+ *
+ * `mixAccent('text-selection', '#3858e9')` is
+ * `color-mix(in srgb, var(--epdf-accent, #3858e9) 35%, transparent)`.
+ */
+declare function mixAccent(name: EpdfTranslucentVariable, accentValue: string): string;
+/**
+ * The CSS value for a part you style yourself, which has no setting: its
+ * variable, then its built-in look.
+ *
+ * `paintDefault('scrollbar-thumb')` is `var(--epdf-scrollbar-thumb, rgb(0 0 0 / 0.4))`.
+ */
+declare function paintDefault(name: EpdfCssOnlyVariable): string;
+/** A setting's path as a theme writes it: the viewer's own at the top, a list's entries as one. */
+type ThemePath<Setting extends string> = Setting extends `viewer.${infer Rest}` ? Rest : Setting extends `${infer Head}[]${infer Tail}` ? `${Head}${Tail}` : Setting;
+/** What a part takes: one of its keywords, or a CSS value. */
+type ThemeValue<Name extends EpdfSettingVariable> = Definitions[Name] extends {
+  readonly keywords: infer Keywords;
+} ? keyof Keywords & string : string | number;
+/** One setting as a nested object: `'page.shadow'` is `{ page?: { shadow?: … } }`. */
+type ThemeBranch<Path extends string, Value> = Path extends `${infer Head}.${infer Rest}` ? { readonly [Key in Head]?: ThemeBranch<Rest, Value>; } : { readonly [Key in Path]?: Value; };
+type Intersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends ((value: infer Both) => void) ? Both : never;
+/**
+ * A theme by setting names, every part optional: `{ accent: '#e91e63', search: { highlight:
+ * { color: '#7dd3fc' } } }`. The viewer's own settings sit at the top; each plugin's under its
+ * name, as the theming page lists them.
+ */
+type EpdfTheme = Intersection<{ [Name in EpdfSettingVariable]: ThemeBranch<ThemePath<Definitions[Name]['setting']>, ThemeValue<Name>>; }[EpdfSettingVariable]>;
+/** The CSS variables of a theme, by their full name: `{ '--epdf-accent': '#e91e63' }`. */
+type EpdfThemeVariables = Readonly<Record<`--epdf-${EpdfVariable}`, string>>;
+/**
+ * The CSS variables that set a theme, for a style on an element around the viewer: CSS variables
+ * win over settings, and reach everything inside the element. A part left out keeps its own
+ * look, so the parts that follow the accent follow a new `accent`.
+ *
+ * `epdfThemeVariables({ accent: '#e91e63', page: { shadow: 'none' } })` is
+ * `{ '--epdf-accent': '#e91e63', '--epdf-page-shadow': 'none' }`.
+ */
+declare function epdfThemeVariables(theme: EpdfTheme): Partial<EpdfThemeVariables>;
+//#endregion
+//#region src/page-pixels.d.ts
+/**
+ * Page-space shapes in a page layer's pixels. Every layer over a page (the
+ * annotation, form, link, selection and search layers) gets boxes and quads
+ * in page points and places its elements in the page layer's own pixels,
+ * always through the page's `toPixels`: never by multiplying with a scale of
+ * its own. Plain geometry over structural shapes, the same for every
+ * framework adapter.
+ */
+/** A point in page points or in pixels. */
+interface PagePoint {
+  x: number;
+  y: number;
+}
+/** What a page layer converts with: its transform's `toPixels`. */
+interface PageToPixels {
+  toPixels(point: PagePoint): PagePoint;
+}
+/** A box in a page layer's pixels, the shape a positioned element takes. */
+interface PixelRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+/** A quad's four corners, as the engine names them. */
+interface PageQuad {
+  upperLeft: PagePoint;
+  upperRight: PagePoint;
+  lowerRight: PagePoint;
+  lowerLeft: PagePoint;
+}
+/** A box in page points as a box in the page layer's pixels. */
+declare function rectInPixels(rect: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}, page: PageToPixels): PixelRect;
+/**
+ * A quad's corners in the page layer's pixels, in drawing order (upper left,
+ * upper right, lower right, lower left). The map is affine, so mapping the
+ * corners is exact, for turned text too.
+ */
+declare function quadInPixels(quad: PageQuad, page: PageToPixels): PagePoint[];
+/** Points as an SVG `points` attribute: `"x,y x,y …"`. */
+declare function svgPoints(points: readonly PagePoint[]): string;
+/** Whether a quad is an upright box: drawn as a positioned box instead of a polygon. */
+declare function isUprightQuad(quad: PageQuad): boolean;
+//#endregion
+//#region src/event-isolation.d.ts
+/**
+ * Keeping a page's own listeners out of controls drawn over it. The Stage
+ * listens natively on an ancestor of every page: a press that bubbles to it
+ * starts a tool gesture or reads as a click outside (ending an edit), and a
+ * wheel pans or zooms the page. A control that owns its gestures stops them
+ * with a native listener on itself, which runs during real DOM bubbling,
+ * before the Stage's. A framework's own event system may run too late: React
+ * dispatches from its root, above the Stage.
+ */
+/**
+ * Stop presses that begin inside `element` from reaching the page, and tell `onPress` about each
+ * one. A control that needs the press itself (a link or a form field sending its PDF "mouse down"
+ * action) must take it here: once the press stops at the element, a framework that dispatches
+ * from its root (React) never sees it. Returns the detach.
+ */
+declare function isolatePointerDown(element: HTMLElement, onPress?: (event: PointerEvent) => void): () => void;
+/**
+ * Stop wheel events inside `element` from reaching the page, so the browser
+ * scrolls the element itself (a list box) instead of the Stage panning or
+ * zooming. Returns the detach.
+ */
+declare function isolateWheel(element: HTMLElement): () => void;
+//#endregion
+//#region src/outside-press.d.ts
+/**
+ * Call `onPress` when a pointer press starts anywhere in `element`'s document
+ * outside `element`: how a menu closes when the user presses somewhere else,
+ * in the viewer or on the page around it. Where the press landed is read from
+ * its composed path: at the document, an event from inside a shadow root is
+ * retargeted to the shadow host, so `element.contains(event.target)` would
+ * call every press inside a shadow-rooted menu an outside one. Listens in the
+ * capture phase, so a handler that stops the press can't keep a menu open.
+ * Returns the stop.
+ */
+declare function observeOutsidePress(element: Element, onPress: (event: PointerEvent) => void): () => void;
+//#endregion
+//#region src/anchor-equality.d.ts
+/**
+ * Equality for the anchors plugins hand out. An anchor read (where a menu, a
+ * badge or a selection handle attaches) returns a new object every time; a
+ * framework adapter compares reads with these, so the UI attached to an
+ * anchor renders again only when the anchor moved. The anchors are mirrored
+ * structurally, so this package stays free of EmbedPDF imports.
+ */
+interface AnchorPoint {
+  readonly x: number;
+  readonly y: number;
+}
+interface AnchorBox {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+interface AnchorPage {
+  readonly objectNumber: number;
+}
+/** A box on a page: a text selection's anchor, and the core of every other one. */
+interface PageBoundsAnchor {
+  readonly page: AnchorPage;
+  readonly bounds: AnchorBox;
+}
+/** The same page and box (a text selection's menu anchor). */
+declare function samePageBounds(left: PageBoundsAnchor | null, right: PageBoundsAnchor | null): boolean;
+/** The annotation selection's anchor: its page, its box, and its rotation handle when it has one. */
+interface SelectionAnchorShape extends PageBoundsAnchor {
+  readonly rotationHandle?: AnchorPoint | null;
+}
+/** The same annotation selection anchor: page, box and rotation handle. */
+declare function sameSelectionAnchor(left: SelectionAnchorShape | null, right: SelectionAnchorShape | null): boolean;
+/** One annotation's anchor: page, box, and the view-dependent box of one that keeps its size on screen. */
+interface AnnotationAnchorShape extends PageBoundsAnchor {
+  readonly boundsIn?: unknown;
+}
+/** The same annotation anchor: page, box, and how it follows the view. */
+declare function sameAnnotationAnchor(left: AnnotationAnchorShape | null, right: AnnotationAnchorShape | null): boolean;
+/** A shape being drawn click by click (a polygon): where it is and how far it got. */
+interface CreationDraftAnchorShape extends PageBoundsAnchor {
+  readonly kind: string;
+  readonly subtype: string;
+  readonly pointCount: number;
+  readonly minPoints: number;
+  readonly canFinish: boolean;
+}
+/** The same creation draft: what it draws, its points so far, whether it can finish, and its box. */
+declare function sameCreationDraftAnchor(left: CreationDraftAnchorShape | null, right: CreationDraftAnchorShape | null): boolean;
+/** A turn in progress: the pointer's page point and the angle. */
+interface RotationAnchorShape {
+  readonly page: AnchorPage;
+  readonly at: AnchorPoint;
+  readonly angle: number;
+}
+/** The same turn in progress: page, pointer and angle. */
+declare function sameRotationAnchor(left: RotationAnchorShape | null, right: RotationAnchorShape | null): boolean;
+interface AnchorQuad {
+  readonly upperLeft: AnchorPoint;
+  readonly upperRight: AnchorPoint;
+  readonly lowerLeft: AnchorPoint;
+  readonly lowerRight: AnchorPoint;
+}
+/** One end of a text selection: its page, the boundary glyph's quad, and the side of the glyph. */
+interface SelectionEndpointShape {
+  readonly page: AnchorPage;
+  readonly glyphQuad: AnchorQuad;
+  readonly advance: unknown;
+}
+/** Both ends of a text selection, where its handles sit. */
+interface SelectionEndpointsShape {
+  readonly start: SelectionEndpointShape;
+  readonly end: SelectionEndpointShape;
+}
+/**
+ * The same selection ends. The glyph quads compare corner by corner, so an
+ * end that turns without moving its bounding box still counts as moved.
+ */
+declare function sameSelectionEndpoints(left: SelectionEndpointsShape | null, right: SelectionEndpointsShape | null): boolean;
+//#endregion
+//#region src/annotation-scene.d.ts
+/** How a scene node paints: the structural twin of core-annotation's `Paint`. */
+interface ScenePaint {
+  fill?: string;
+  stroke?: string;
+  /** Stroke width, in page points. */
+  width?: number;
+  opacity?: number;
+  /** Stroke dash, in page points. */
+  dash?: number[];
+  blend?: string;
+  lineCap?: 'round';
+  join?: 'round';
+  fillRule?: 'evenodd';
+}
+interface SceneBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface ScenePoint {
+  x: number;
+  y: number;
+}
+/** One painted node: the structural twin of core-annotation's `SceneNode`. */
+type SceneShapeNode = ({
+  kind: 'rect';
+  rect: SceneBox;
+  paint: ScenePaint;
+} | {
+  kind: 'ellipse';
+  rect: SceneBox;
+  paint: ScenePaint;
+} | {
+  kind: 'line';
+  a: ScenePoint;
+  b: ScenePoint;
+  paint: ScenePaint;
+} | {
+  kind: 'poly';
+  points: ScenePoint[];
+  closed: boolean;
+  paint: ScenePaint;
+} | {
+  kind: 'path';
+  d: string;
+  paint: ScenePaint;
+} | {
+  kind: 'text';
+  at: ScenePoint;
+  text: string;
+  fontSize: number;
+  fontFamily?: string;
+  rotation?: number;
+  paint: ScenePaint;
+} | {
+  kind: 'glyphs';
+  at: ScenePoint;
+  text: string;
+  offsets: number[];
+  fontSize: number;
+  fontFamily: string;
+  fontWeight?: number;
+  fontStyle?: 'normal' | 'italic';
+  rotation?: number;
+  /** The face it draws in: whatever draws it mounts it. */
+  program?: MountableFontProgram;
+  paint: ScenePaint;
+}) & {
+  /** Drawn only inside this upright box. */
+  clip?: SceneBox;
+};
+/** The SVG elements a scene draws with; a nested `svg` clips what's inside it to its box. */
+type SvgShapeTag = 'rect' | 'ellipse' | 'line' | 'path' | 'text' | 'polygon' | 'polyline' | 'svg';
+/**
+ * One SVG element: its tag, its attributes under their SVG names
+ * (`stroke-width`, `fill-rule`; an attribute left out is not set), the text
+ * inside it, and its blend mode, which is CSS (`mix-blend-mode` in its
+ * `style`), never an attribute.
+ */
+interface SvgShape {
+  tag: SvgShapeTag;
+  attributes: Readonly<Record<string, string | number>>;
+  text?: string;
+  blend?: string;
+  /** What a clipping `svg` holds, in drawing order. */
+  children?: SvgShape[];
+  /** The face a `text` draws in: the renderer mounts it (`fontProgramsOf`). */
+  program?: MountableFontProgram;
+}
+/** The faces shapes draw their text in, each once: a renderer mounts them while it shows the shapes. */
+declare function fontProgramsOf(shapes: readonly SvgShape[]): MountableFontProgram[];
+interface SvgShapesOptions {
+  /**
+   * The stroke miter limit, core-annotation's `MITER_LIMIT`: it must be the
+   * one the core's bounds math uses, so a sharp corner spikes or bevels the
+   * same way in both.
+   */
+  miterLimit: number;
+}
+/**
+ * Each scene node as one SVG element, in drawing order, in the scene's own
+ * page-point units. A clipped node comes inside an `svg` of its clip box,
+ * which shows only what's inside it (no ids, so every framework draws it the
+ * same).
+ */
+declare function svgShapesOf(nodes: readonly SceneShapeNode[], options: SvgShapesOptions): SvgShape[];
+/**
+ * The `viewBox` an item's scene draws in: its box, in page points. `null`
+ * while the box has no area (a drawing at its first press): draw nothing then.
+ *
+ * The `<svg>` fills the item's frame, so the viewBox and the element's size
+ * stay proportional (their ratio is the zoom). Never clamp either one: a
+ * clamped element with a shrinking viewBox scales its content up, and a
+ * cloudy border's scallops flood the page.
+ */
+declare function sceneViewBox(box: SceneBox): string | null;
+/** How opaque a tool's ghost paints: `--epdf-ghost-opacity` wins over the tool's own. */
+declare function ghostOpacity(opacity: number): string;
+//#endregion
+//#region src/annotation-chrome.d.ts
+/** The chrome settings the paint reads: the structural twin of the annotation plugin's `ChromeSettings`. */
+interface ChromePaintSettings {
+  readonly accent: string | null;
+  readonly outline: {
+    readonly color: string | null;
+    readonly style: string;
+    readonly width: number;
+  };
+  readonly handles: {
+    readonly fill: string;
+    readonly stroke: string | null;
+  };
+  readonly rotationHandle: {
+    readonly fill: string | null;
+    readonly stroke: string | null;
+  };
+  readonly guides: {
+    readonly color: string;
+    readonly rotationColor: string | null;
+    readonly style: string;
+    readonly width: number;
+  };
+  readonly marquee: {
+    readonly fill: string | null;
+    readonly stroke: string | null;
+  };
+  readonly textOutline: string | null;
+}
+/** A line's paint as CSS: its color, width and dash. */
+interface ChromeLinePaint {
+  readonly stroke: string;
+  readonly strokeWidth: string;
+  readonly strokeDasharray: string;
+}
+/** A shape's paint as CSS: its fill and its stroke color. */
+interface ChromeShapePaint {
+  readonly fill: string;
+  readonly stroke: string;
+}
+/**
+ * Every chrome color, width and dash as CSS, each its `--epdf-annotation-*`
+ * variable first, then the setting. Put them in `style`: an SVG attribute
+ * doesn't read `var()`.
+ */
+interface AnnotationChromePaint {
+  /** The selection box. */
+  readonly outline: ChromeLinePaint;
+  /** The resize and point handles. */
+  readonly handle: ChromeShapePaint;
+  /** The rotation handle; its stalk takes the `stroke`. */
+  readonly rotationHandle: ChromeShapePaint;
+  /** A snapped move's alignment guide. */
+  readonly guide: ChromeLinePaint;
+  /** The reference cross and the angle line while turning. */
+  readonly rotationGuide: ChromeLinePaint;
+  /** The box dragged to select. */
+  readonly marquee: ChromeShapePaint;
+  /** The outline color of a text box while someone types in it. */
+  readonly textOutline: string;
+}
+/**
+ * The chrome settings as paint. A color left `null` follows the part it
+ * names, and in the end the accent: the chrome's own, else the viewer's.
+ */
+declare function annotationChromePaint(chrome: ChromePaintSettings, viewerAccent: string): AnnotationChromePaint;
+/**
+ * One chrome node as the annotation plugin lists it: the structural twin of
+ * core-annotation's `ChromeNode`. `Role` is what a handle reshapes.
+ */
+type ChromeNodeShape<Role extends string = string> = {
+  kind: 'outline';
+  rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+} | {
+  kind: 'obb';
+  corners: readonly PagePoint[];
+} | {
+  kind: 'handle';
+  at: PagePoint;
+  rot?: number;
+  role: Role;
+  active: boolean;
+} | {
+  kind: 'rotate-knob';
+  at: PagePoint;
+  from: PagePoint;
+} | {
+  kind: 'guide';
+  axis: 'x' | 'y';
+  at: number;
+  lo: number;
+  hi: number;
+} | {
+  kind: 'rotate-guides';
+  lines: ReadonlyArray<{
+    a: PagePoint;
+    b: PagePoint;
+    role: 'axis' | 'indicator';
+  }>;
+} | {
+  kind: 'marquee';
+  rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+};
+/** A line in pixels. */
+interface ChromeLine {
+  from: PagePoint;
+  to: PagePoint;
+}
+/**
+ * A chrome node in the page layer's pixels. What each one draws:
+ * - `outline`, `marquee`: a rectangle, `box` (the marquee is always dashed `4 3`);
+ * - `turned-outline`: a closed polygon through `points`, the outline of a turned selection;
+ * - `handle`: a handle centred on `at`, turned by `rotation` (degrees clockwise) when square;
+ * - `rotation-handle`: a round handle at `at`, its stalk from `from` on the box;
+ * - `guide`: a crisp line, a snapped move's alignment;
+ * - `rotation-guides`: the lines of a turn in progress, each at its `opacity`.
+ */
+type ChromeInPixels<Role extends string = string> = {
+  kind: 'outline';
+  box: PixelRect;
+} | {
+  kind: 'marquee';
+  box: PixelRect;
+} | {
+  kind: 'turned-outline';
+  points: string;
+} | {
+  kind: 'handle';
+  at: PagePoint;
+  rotation: number;
+  role: Role;
+  active: boolean;
+} | {
+  kind: 'rotation-handle';
+  at: PagePoint;
+  from: PagePoint;
+} | ({
+  kind: 'guide';
+} & ChromeLine) | {
+  kind: 'rotation-guides';
+  lines: Array<ChromeLine & {
+    opacity: number;
+  }>;
+};
+/**
+ * Each chrome node in the page layer's pixels, in drawing order. The plugin
+ * already sized the screen-constant parts (handle grab zones, the rotation
+ * handle's offset) for the page's zoom; this only places them.
+ */
+declare function chromeInPixels<Role extends string>(nodes: readonly ChromeNodeShape<Role>[], page: PageToPixels): ChromeInPixels<Role>[];
+//#endregion
+//#region src/text-box-editor.d.ts
+/** A text box as the annotation plugin lists it (`listTextItems`): the fields the editor reads. */
+interface TextBoxEditorItem<Ref> {
+  readonly id: string;
+  /** `null` for a box that isn't written yet: nothing to route typing to. */
+  readonly ref: Ref | null;
+  readonly richText: RichTextEditorDocument;
+  /** True while someone types in this box. */
+  readonly editing: boolean;
+}
+/** The annotation plugin's text-editing calls (its host capability satisfies it). */
+interface TextBoxEditorAnnotation<Ref> {
+  draftRichText(ref: Ref, document: RichTextEditorDocument): void;
+  setTextSelection(ref: Ref, range: RichTextEditorRange | null): void;
+  readonly text: {
+    toggleFormat(format: RichTextEditorCommand): unknown;
+  };
+  getCssFontFamily(family: string): string;
+  getEditingId(): string | null;
+}
+/** An element made a text box's editor. */
+interface TextBoxEditor<Ref> {
+  /**
+   * The box as the plugin has it now, at `scale` pixels per point (or `null`
+   * while there is none). Call it whenever either changes: the binding
+   * redraws only when the text differs (so the caret never jumps while
+   * typing), and focus follows `editing`.
+   */
+  update(item: TextBoxEditorItem<Ref> | null, scale: number): void;
+  /** Remove the listeners and the rich-text binding. */
+  detach(): void;
+}
+/**
+ * Make `element` the editor of a text box. Typing shows at once and reaches
+ * the engine in one write after a pause (or when the edit ends), not one
+ * write per keystroke.
+ */
+declare function attachTextBoxEditor<Ref>(element: HTMLElement, annotation: TextBoxEditorAnnotation<Ref>): TextBoxEditor<Ref>;
+/** Keeps an element the editor of a text box while what it edits with changes. */
+interface TextBoxEditorFollower<Ref> {
+  /**
+   * The element, the plugin, the box and the scale as they are now. Call it
+   * whenever any of them changes: the editor attaches when there are an
+   * element and a plugin, attaches again when either is another one (a
+   * document that opens anew), and gets the box and the scale every time.
+   */
+  follow(element: HTMLElement | null, annotation: TextBoxEditorAnnotation<Ref> | null, item: TextBoxEditorItem<Ref> | null, scale: number): void;
+  /** Let go of the element, when the component that drew it goes away. */
+  detach(): void;
+}
+/**
+ * A text box editor that follows its inputs: what each framework's binding
+ * holds between renders. The update runs right after an attach, in the same
+ * call, so the element never shows an editor without its text.
+ */
+declare function createTextBoxEditorFollower<Ref>(): TextBoxEditorFollower<Ref>;
+/**
+ * Pixels per point for an editor element you draw yourself (a renderer's own
+ * text box): the box's width on the page over its width in points, or the
+ * page's view scale while there is no box. Inside a look the layer scales
+ * (`lookScale`, 1 outside one), the element draws at the annotation's 100%
+ * size and the look's scale does the rest.
+ */
+declare function textBoxEditorScaleOf(item: {
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+} | null, page: PageToPixels & {
+  viewScale: number;
+}, lookScale: number): number;
+/** A free text body's look, as the plugin hands it (`TextItem.css`). */
+interface TextBoxCss {
+  fontFamily: string;
+  /** In page points. */
+  fontSize: number;
+  color: string;
+  fontWeight: number;
+  fontStyle: string;
+  textDecoration: string;
+  align: 'left' | 'center' | 'right';
+  /** The plate's inset from the box, in page points. */
+  padding: number;
+}
+/** A text box's body style as CSS: put it on the editor element. */
+interface TextBoxStyle {
+  fontFamily: string;
+  /** In pixels, with its unit. */
+  fontSize: string;
+  color: string;
+  fontWeight: number;
+  fontStyle: string;
+  textDecoration: string;
+  textAlign: 'left' | 'center' | 'right';
+}
+/**
+ * A text box's body style at `scale` pixels per point: font, size, color and
+ * alignment. No line height: the editor binding states the engine's line
+ * model per face on the element itself.
+ */
+declare function textBoxStyleOf(css: TextBoxCss, scale: number): TextBoxStyle;
+/** Where a free text's editor element goes, and the scale it draws at. */
+interface TextPlatePixels {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  /** Pixels per page point. */
+  scale: number;
+}
+/**
+ * The editor element of a free text box in the page layer's pixels: the
+ * engine's text plate (`SetPlateRect` and its `re W n` clip), the box inset
+ * by its padding. Place it there with no CSS padding, so its edge is the
+ * plate's: CSS padding doesn't clip overflow, and scrolled lines would paint
+ * over the border band. The box never grows with its text.
+ */
+declare function textPlateInPixels(item: {
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  css: {
+    padding: number;
+  };
+}, page: PageToPixels): TextPlatePixels;
+//#endregion
+//#region src/annotation-renderers.d.ts
+/**
+ * The annotation layer's renderers: which drawing each annotation gets, and
+ * the behaviors that `interactive` renderers register. A renderer is a rule
+ * ("draw these annotations with this component"); a framework adapter keeps
+ * the component, and these decide everything around it, the same for every
+ * framework:
+ *
+ * - {@link registerRendererBehaviors}: an `interactive` renderer takes the
+ *   pointer through a behavior the annotation plugin knows, registered once
+ *   per capability and renderer entry however many pages mount the layer.
+ * - {@link annotationDrawingOf}: per annotation, the layer's own drawing, a
+ *   look of yours, or a sibling plugin's control (ownership beats looks).
+ * - {@link editingTextKeyOf} and {@link layerTextBoxesOf}: which text box is
+ *   typed in, and which text boxes the layer draws rather than a look.
+ *
+ * The plugin's types are mirrored structurally, so this package stays free of
+ * EmbedPDF imports.
+ */
+/** A sibling plugin's renderer: it draws what the behavior `behavior` owns (the form plugin's controls). */
+interface BehaviorRendererEntry {
+  behavior: string;
+}
+/** What an `interactive` function is asked: the annotation, and the active tool. */
+interface RendererInteractiveContext<Annotation> {
+  annotation: Annotation;
+  toolId: string;
+}
+/** A look of yours: draws the annotations `for` matches. */
+interface LookRendererEntry<Annotation> {
+  /** A stable id for the registration (optional; generated). */
+  id?: string;
+  for(annotation: Annotation): boolean;
+  /** Takes the pointer: always, or when the function says so (asked whenever it matters). */
+  interactive?: boolean | ((context: RendererInteractiveContext<Annotation>) => boolean);
+}
+type RendererEntry<Annotation> = BehaviorRendererEntry | LookRendererEntry<Annotation>;
+/** The annotation plugin's behavior registry (its host capability satisfies it). */
+interface RendererBehaviorRegistry<Annotation> {
+  registerBehavior(behavior: {
+    id: string;
+    matches(annotation: Annotation): boolean;
+    engaged(annotation: Annotation): boolean;
+  }): () => void;
+  getBehaviorFor(annotation: Annotation): {
+    id: string;
+  } | null;
+}
+/**
+ * Register a behavior for each `interactive` look in `renderers`, so the
+ * plugin lets that renderer take the pointer. Call it when a layer mounts (and
+ * again when its renderer list changes); call what it returns when it
+ * unmounts. `activeToolId` is read whenever an `interactive` function is asked.
+ */
+declare function registerRendererBehaviors<Annotation>(annotation: RendererBehaviorRegistry<Annotation>, renderers: readonly RendererEntry<Annotation>[], activeToolId: () => string): () => void;
+/** The behavior id a renderer entry answers for: a sibling plugin's own, or the one registered for it. */
+declare function rendererBehaviorId<Annotation>(annotation: object, renderer: RendererEntry<Annotation>): string | null;
+/** The first of your looks that draws this annotation, or `null`. */
+declare function lookRendererFor<Annotation, Entry extends RendererEntry<Annotation>>(record: Annotation, renderers: readonly Entry[] | undefined): Extract<Entry, {
+  for: unknown;
+}> | null;
+/**
+ * How the layer draws one annotation:
+ * - `native`: its own drawing (the scene or the engine's raster). `inert`
+ *   when an engaged behavior's plugin owns the input with no renderer of
+ *   yours (a link's anchor takes the click).
+ * - `owned`: a sibling plugin's renderer draws it and takes the input (the
+ *   form plugin's fill controls); it places its own controls.
+ * - `look`: your renderer draws it, in the annotation's frame. `interactive`
+ *   when an engaged behavior gave it the pointer; otherwise it only draws,
+ *   and the frame is `inert` (no pointer, no focus) unless its text box is
+ *   being typed in, where the renderer's editor takes the keys.
+ */
+type AnnotationDrawing<Entry> = {
+  kind: 'native';
+  inert: boolean;
+} | {
+  kind: 'owned';
+  entry: Extract<Entry, {
+    behavior: string;
+  }>;
+} | {
+  kind: 'look';
+  entry: Extract<Entry, {
+    for: unknown;
+  }>;
+  interactive: boolean;
+  inert: boolean;
+};
+/**
+ * The drawing an annotation gets. Ownership beats looks: an engaged
+ * behavior's renderer is authoritative; `for` rules apply only to what the
+ * layer owns, and draw without the pointer. `typing` is whether this
+ * annotation's text box is being typed in.
+ */
+declare function annotationDrawingOf<Annotation, Entry extends RendererEntry<Annotation>>(record: Annotation, annotation: RendererBehaviorRegistry<Annotation>, renderers: readonly Entry[] | undefined, typing: boolean): AnnotationDrawing<Entry>;
+/**
+ * The key of the text box being typed in (the one that is `editing` and has a
+ * ref), or `null`. An annotation with this key is `typing` for
+ * {@link annotationDrawingOf}: while it is, a look's own editor takes the keys.
+ */
+declare function editingTextKeyOf<Ref>(texts: readonly {
+  readonly editing: boolean;
+  readonly ref: Ref | null;
+}[], keyOf: (ref: Ref) => string): string | null;
+/**
+ * The text boxes the layer draws itself: all of them but the ones whose
+ * annotation a look of yours draws, which that look edits with its own editor
+ * (a renderer's rich text editor). `items` are the page's render items, which
+ * carry each annotation; the same array comes back when there is no look.
+ */
+declare function layerTextBoxesOf<Annotation, Ref, Text extends {
+  readonly ref: Ref | null;
+}>(texts: readonly Text[], items: readonly {
+  readonly ref: Ref | null;
+  readonly annotation?: Annotation | null;
+}[], renderers: readonly RendererEntry<Annotation>[] | undefined, keyOf: (ref: Ref) => string): readonly Text[];
+//#endregion
+//#region src/comment-threads.d.ts
+/**
+ * Comment threads with where their page is shown: the join of the annotation
+ * plugin's threads and the document's page list that a comments panel
+ * prints. A thread's identity stays its page's address; the index and the
+ * label are presentation, following page moves and deletes.
+ */
+/** Where a thread's page is shown now. */
+interface CommentThreadPage {
+  /** Current 0-based display index of the thread's page; `-1` when the page is no longer in the document. */
+  pageIndex: number;
+  /**
+   * The page's `/PageLabels` label when the PDF declares one ("iv", "A-2"),
+   * else the 1-based position as a string; `'?'` for a page that's gone.
+   * Print it as it is.
+   */
+  pageLabel: string;
+}
+/** A page as the document's page list has it: its address, display index and label. */
+interface CommentPageLayout {
+  readonly ref: {
+    readonly objectNumber: number;
+  };
+  readonly index: number;
+  readonly label?: string | null;
+}
+/**
+ * Each thread with its page's display index and label. A thread whose page
+ * was just deleted reads `-1` and `'?'` for the one render before it goes.
+ */
+declare function enrichCommentThreads<Thread extends {
+  readonly page: {
+    readonly objectNumber: number;
+  };
+}>(threads: readonly Thread[], pages: readonly CommentPageLayout[]): Array<Thread & CommentThreadPage>;
+//#endregion
+//#region src/form-field.d.ts
+/** The form settings the colors read: the structural twin of the form plugin's `focus` and `fields`. */
+interface FormColorSettings {
+  readonly focus: {
+    readonly color: string | null;
+  };
+  readonly fields: {
+    readonly border: string | null;
+    readonly background: string;
+    readonly color: string;
+  };
+}
+/** The colors the viewer draws fields with, each its `--epdf-form-*` variable first, then the setting. */
+interface FormColors {
+  /** The focus ring around the field being filled in. */
+  readonly focus: string;
+  /** The edge of a field without a border of its own. */
+  readonly border: string;
+  /** Inside a field without a background of its own, while it's filled in. */
+  readonly background: string;
+  /** The text of a field without a color of its own. */
+  readonly text: string;
+}
+/** The form settings as colors: an unset focus color is the accent, an unset edge the accent at 55%. */
+declare function formColorsOf(settings: FormColorSettings, accent: string): FormColors;
+/** How a widget looks in the PDF: the structural twin of the form plugin's `FormWidgetLook`. */
+interface FieldLook {
+  readonly border: string | null;
+  /** In page points. */
+  readonly borderWidth: number;
+  readonly borderStyle: string;
+  readonly background: string | null;
+  readonly color: string | null;
+  /** One of the 14 standard PDF fonts (`'helvetica-bold'`), or `null`. */
+  readonly fontFamily: string | null;
+  /** In page points; `0` or `null` fits the text to the box. */
+  readonly fontSize: number | null;
+  readonly textAlign: 'left' | 'center' | 'right';
+}
+/** A standard PDF font as CSS. */
+type CssFont = {
+  fontFamily: string;
+  fontWeight: number;
+  fontStyle: 'normal' | 'italic';
+};
+/** One of the 14 standard PDF fonts as CSS: a family that looks like it, its weight and style. */
+declare function cssFontOf(pdfFont: string | null): CssFont;
+/** A field's text as CSS: its font, size, alignment and colors, the settings where it has none. */
+type FieldTextStyle = CssFont & {
+  /** In pixels, with its unit. */
+  fontSize: string;
+  textAlign: 'left' | 'center' | 'right';
+  color: string;
+  background: string;
+};
+/** A text field as the layer's editor shows it while focused, in the field's own font. */
+type TextFieldStyle = FieldTextStyle & {
+  /** A comb field's spacing (its box split into `maxLength` cells), in pixels with its unit. */
+  letterSpacing?: string;
+};
+/**
+ * A text field's editor style. A font size of 0 means "fit the box" in PDF:
+ * the box height for one line, Acrobat's 12 pt for several.
+ */
+declare function textFieldStyleOf(field: {
+  box: {
+    width: number;
+  };
+  look: FieldLook;
+  multiline: boolean;
+  comb: boolean;
+  maxLength: number | null;
+}, frame: PixelRect, colors: FormColors): TextFieldStyle;
+/** A list box as the layer draws it: the field's text look, and its border. */
+type ListBoxStyle = FieldTextStyle & {
+  /** In pixels, with its unit; never thinner than one pixel. */
+  borderWidth: string;
+  borderStyle: 'solid' | 'dashed';
+  borderColor: string;
+};
+/** A list box's style: the field's own look, the settings where it has none (12 pt for a fitted size). */
+declare function listBoxStyleOf(field: {
+  box: {
+    width: number;
+  };
+  look: FieldLook;
+}, frame: PixelRect, colors: FormColors): ListBoxStyle;
+/** The PDF events a widget's `/AA` actions answer, as the actions plugin names them. */
+type WidgetEventKind = 'cursorEnter' | 'cursorExit' | 'mouseDown' | 'mouseUp' | 'focus' | 'blur';
+/**
+ * Send a widget's pointer and focus events (`/AA`: enter, exit, down, up,
+ * focus, blur) to `notify`, from native listeners on the widget's box. Put
+ * them on the always-active box, never on the control inside: "may edit this
+ * field" and "may receive PDF action events" are different rights, and a
+ * session that may not fill still sees hover tooltips. Focus is `focusin` and
+ * `focusout`, so the control's focus reaches the box, and a blur arrives
+ * after the control's own blur handler started its commit. Returns the
+ * detach.
+ */
+declare function bindWidgetEvents(box: HTMLElement, notify: (event: WidgetEventKind) => void): () => void;
+/** What a toggle press writes with: the form plugin's `setValue`. */
+interface ToggleForm<Field> {
+  setValue(field: Field, value: {
+    value: string | null;
+  }): Promise<unknown>;
+}
+/**
+ * A checkbox or radio button pressed: a checked checkbox clears, a radio
+ * button always selects its own value. The value is written first, then the
+ * widget's action runs (Acrobat's order), so an action script reads the new
+ * state; a read-only toggle writes nothing and still runs its action.
+ */
+declare function pressToggle<Field>(form: ToggleForm<Field>, toggle: {
+  fieldRef: Field;
+  kind: 'checkbox' | 'radio';
+  checked: boolean;
+  exportValue: string;
+  disabled: boolean;
+}, activate: () => void): void;
+/** The form plugin's draft calls for a text field (its host capability satisfies it). */
+interface TextFieldDrafts<Field> {
+  draftText(field: Field, text: string): void;
+  /** Resolves with how the write ended (`'rejected'`: the form's validation refused it), or `null`. */
+  commitDraftText(field: Field): Promise<{
+    readonly status: string;
+  } | null>;
+  discardDraftText(field: Field): void;
+}
+/** What a text field's editor shows: whether it has focus, and the text in it. */
+interface TextFieldEditorState {
+  readonly focused: boolean;
+  readonly draft: string;
+}
+/**
+ * A text field being typed in, framework-free: the editor's `value` is
+ * `draft`, and its events call the methods. Read the state with `getState`
+ * and re-render on `subscribe`; the state object stays the same until it
+ * changes.
+ */
+interface TextFieldEditor {
+  getState(): TextFieldEditorState;
+  subscribe(listener: () => void): () => void;
+  /** The field's value as the form has it now. The draft follows it, except while focused. */
+  setValue(value: string): void;
+  /** The editor took focus. */
+  focus(): void;
+  /** Someone typed: the draft shows it, and the plugin keeps it so a download writes it. */
+  input(text: string): void;
+  /**
+   * A key went down. True when the editor should blur now: Escape (which
+   * puts the value back) and, in a one-line field, Enter (which commits).
+   */
+  keyDown(key: string, multiline: boolean): boolean;
+  /** The editor lost focus: commit what changed, discard what didn't or was cancelled. */
+  blur(): void;
+}
+/**
+ * The editing policy of one text field: typing drafts, blur or Enter
+ * commits, Escape discards. A commit keeps the typed text until the field
+ * shows it (at once, as the form shows a fill before the engine answers), so
+ * a blur never shows the old value for a moment. A value the form's
+ * validation refuses stays typed, as in Acrobat; a write the engine refuses
+ * puts the field's value back.
+ */
+declare function createTextFieldEditor<Field>(form: TextFieldDrafts<Field>, field: Field, value: string): TextFieldEditor;
+/**
+ * A list box's selection, shown at once while its write is on its way. The
+ * native control must stay the same element (never remounted), so its own
+ * scroll position stays where the user left it.
+ */
+interface OptimisticSelection {
+  /** The selection the control shows. */
+  get(): readonly string[];
+  subscribe(listener: () => void): () => void;
+  /** The selection the engine has now: the control shows it once it differs from the last one. */
+  setConfirmed(values: readonly string[]): void;
+  /** Show `values` now and write them; a write that fails puts the engine's selection back. */
+  choose(values: string[], write: (values: string[]) => void | Promise<unknown>): void;
+}
+/** A list box's optimistic selection, starting at the engine's. */
+declare function createOptimisticSelection(confirmed: readonly string[]): OptimisticSelection;
+/** A native `<select>`, as {@link showSelectedOptions} reads it: its options. */
+interface SelectOptions {
+  readonly options: ArrayLike<{
+    readonly value: string;
+    selected: boolean;
+  }>;
+}
+/**
+ * Show `values` as a native `<select>`'s selection, set on each option. A
+ * `value` binding can't hold several values, and setting the options also
+ * puts a choice back when its write fails before the framework renders
+ * again. Setting the same selection again changes nothing the user sees,
+ * scroll position included.
+ */
+declare function showSelectedOptions(select: SelectOptions, values: readonly string[]): void;
+//#endregion
+//#region src/form-styles.d.ts
+/** A control that fills the widget's box it sits in: every native control the layer draws. */
+declare const FORM_CONTROL_FILL: Readonly<{
+  readonly position: "absolute";
+  readonly inset: "0";
+  readonly width: "100%";
+  readonly height: "100%";
+  readonly boxSizing: "border-box";
+  readonly margin: "0";
+}>;
+/** {@link FORM_CONTROL_FILL}'s shape. */
+type FormControlFill = typeof FORM_CONTROL_FILL;
+/** The box a widget's control sits in, placed over the widget on the page. */
+type WidgetBoxStyle = {
+  position: 'absolute';
+  left: string;
+  top: string;
+  width: string;
+  height: string;
+  /** Always the widget's event surface: the control inside gates the edits. */
+  pointerEvents: 'auto';
+  /** The edge of a field without a border of its own, so people see where to fill in. */
+  boxShadow?: string;
+};
+/**
+ * The style of a widget's box at `frame` (the widget's box in the page
+ * layer's pixels). `edge: false` leaves the edge out, for a control that draws
+ * its own (a list box) or never has one (a button).
+ */
+declare function widgetBoxStyleOf(widget: {
+  look: Pick<FieldLook, 'border'>;
+}, frame: PixelRect, colors: FormColors, { edge }?: {
+  edge?: boolean;
+}): WidgetBoxStyle;
+/**
+ * Where a text field's editor shows the text typed in it, so it sits where the engine will draw
+ * it (the form plugin's `getTextEditorLayout`), in page points.
+ */
+interface TextEditorLayout {
+  readonly fontFamily: string;
+  readonly fontWeight: number;
+  readonly fontStyle: 'normal' | 'italic';
+  readonly fontSize: number;
+  readonly lineHeight: number;
+  readonly padding: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+  };
+  /** A comb's room between characters; it starts at the left padding, whatever the alignment. */
+  readonly letterSpacing: number;
+  readonly comb: boolean;
+}
+/** A text field's editor: see-through at rest, the field's own look while focused. */
+type TextFieldEditorStyle = FormControlFill & TextFieldStyle & {
+  border: 'none';
+  outline: string;
+  outlineOffset: string;
+  padding: string;
+  /** In pixels, with its unit: one line of the engine's layout. */
+  lineHeight?: string;
+  resize: 'none';
+  cursor: 'text';
+  /** 1 while focused, 0 at rest, where the field's picture shows through. */
+  opacity: number;
+  /** `none` for a disabled field: the box below runs the widget's action. */
+  pointerEvents?: 'none';
+};
+/**
+ * The style of a text field's editor, the `<input>` or `<textarea>` that is
+ * always there: focused, it shows the field's text in its own font with a
+ * focus ring; at rest it is see-through over the field's picture. A disabled
+ * control would swallow clicks, and the box below runs the widget's action
+ * (the read-only "button" pattern), so a disabled one lets them through.
+ *
+ * With the engine's `layout` of the text being typed, the editor writes it
+ * where the engine will draw it: in the engine's face (mounted), at the size
+ * it draws (a fitted size resolved), in the box inside the border, a line of
+ * the face's height (one line centred, as the engine centres it).
+ */
+declare function textFieldEditorStyleOf(field: Parameters<typeof textFieldStyleOf>[0] & {
+  disabled: boolean;
+}, frame: PixelRect, colors: FormColors, focused: boolean, layout?: TextEditorLayout | null): TextFieldEditorStyle;
+/** A list box: the visible native `<select>` in the field's own look. */
+type ListBoxControlStyle = FormControlFill & ListBoxStyle & {
+  padding: string;
+  borderRadius: string;
+  outline: 'none';
+  cursor: 'default' | 'pointer';
+  /** `none` for a disabled field: the box below runs the widget's action. */
+  pointerEvents?: 'none';
+};
+/**
+ * The style of a list box's `<select>`, filling the widget's box: the field's
+ * own look ({@link listBoxStyleOf}) with its own border, so the box adds no
+ * edge. The focus ring is drawn above it ({@link formFocusRingStyleOf}).
+ */
+declare function listBoxControlStyleOf(field: Parameters<typeof listBoxStyleOf>[0] & {
+  disabled: boolean;
+}, frame: PixelRect, colors: FormColors): ListBoxControlStyle;
+/** The focus ring of a field whose control is see-through, or is the box itself. */
+type FormFocusRingStyle = {
+  position: 'absolute';
+  inset: string;
+  zIndex: number;
+  boxSizing: 'border-box';
+  outline: string;
+  outlineOffset: string;
+  pointerEvents: 'none';
+};
+/**
+ * The style of a field's focus ring in `color` (the form's focus color): an
+ * element of its own above the field's picture and its control. An outline on
+ * the box would sit under an opaque child, so a rectangular checkbox or a
+ * dropdown would look unfocused while it has the focus.
+ */
+declare function formFocusRingStyleOf(color: string): FormFocusRingStyle;
+//#endregion
+//#region src/link-anchor.d.ts
+/** A link as the link plugin lists it: the fields the anchor reads. */
+interface LinkAnchorShape {
+  readonly target: {
+    readonly kind: string;
+    readonly uri?: string;
+  };
+  /** The full `/A` tree; a `/Next` after its root chains more actions. */
+  readonly activate?: {
+    readonly root: {
+      readonly next: readonly unknown[];
+    } | null;
+  } | null;
+  /** A link riding an editable annotation (its parent owns its pixels while annotations are edited). */
+  readonly attached: boolean;
+}
+/**
+ * The links a page layer shows anchors for. One owner per pixel: while the
+ * active tool edits annotations, a link attached to an annotation stands
+ * down so its parent can be selected and moved; a document's own links
+ * navigate under every tool that enables link navigation.
+ */
+declare function navigableLinksOf<Link extends LinkAnchorShape>(links: readonly Link[], annotationEditEnabled: boolean): readonly Link[];
+/**
+ * The anchor's native `href`: only for a website the browser may open and
+ * nothing chained after it. Blocked schemes, targets inside the document and
+ * action chains activate through the plugin instead: a native navigation
+ * would run the first action and silently drop the rest.
+ */
+declare function linkHrefOf(link: LinkAnchorShape): string | null;
+/** A link's anchor, ready to draw. */
+interface LinkAnchor<Link> {
+  readonly link: Link;
+  /** Where the anchor sits, in the page layer's pixels. */
+  readonly box: PixelRect;
+  /** Its native `href` ({@link linkHrefOf}), or null. */
+  readonly href: string | null;
+  /** Its `title` and `aria-label`. */
+  readonly label: string;
+}
+/**
+ * The anchor for `link` on a page layer: its box from the link's `bounds`,
+ * its `href`, and the label `labelOf` (the link plugin's `getLabel`) gives it.
+ */
+declare function linkAnchorOf<Link extends LinkAnchorShape & {
+  readonly bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}>(link: Link, page: PageToPixels, labelOf: (link: Link) => string): LinkAnchor<Link>;
+/**
+ * Whether a click on an anchor with an `href` stays the browser's: a click
+ * with a modifier key opens a background tab or a new window. Every other
+ * click is prevented and follows the link through the plugin.
+ */
+declare function isModifiedClick(event: {
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+}): boolean;
+//#endregion
+//#region src/link-events.d.ts
+/**
+ * What a page link's anchor tells the plugins: the context a click or a key
+ * follows the link with (the link plugin's `activate()`), and the link's own
+ * PDF events (`/AA`): entering and leaving through the layer's hover pump,
+ * the press, the release, focus and blur through the actions plugin's
+ * `dispatch()`. Only a link that is an annotation has events of its own. The
+ * plugins' types are mirrored structurally and their refs stay opaque, so
+ * this package stays free of EmbedPDF imports.
+ */
+/** The events an anchor sends the actions plugin itself; entering and leaving go through the hover pump. */
+type LinkAnchorEvent = 'mouseDown' | 'mouseUp' | 'focus' | 'blur';
+/** A link's fields these read: its `/A` tree, the annotation it is, and which hover trees it has. */
+interface LinkEventShape<Ref, Action = unknown, HoverEvents = unknown> {
+  readonly activate?: Action;
+  readonly ref?: Ref;
+  readonly hoverEvents?: HoverEvents;
+}
+/** The link as the source of an actions-plugin event. */
+interface LinkActionSource<Ref, Page> {
+  readonly kind: 'link';
+  readonly annotation: Ref;
+  readonly page: Page;
+}
+/** The actions plugin, as an anchor uses it. */
+interface LinkActionDispatcher<Ref, Page> {
+  dispatch(trigger: {
+    readonly scope: 'annotation';
+    readonly event: LinkAnchorEvent;
+    readonly ref: Ref;
+    readonly page: Page;
+    readonly source: LinkActionSource<Ref, Page>;
+  }): unknown;
+}
+/** One link layer's hover pump (`createHoverPump` in the actions plugin's contract). */
+interface LinkHoverPump<Ref, Page, HoverEvents> {
+  hover(target: {
+    readonly ref: Ref;
+    readonly page: Page;
+    readonly source: LinkActionSource<Ref, Page>;
+    readonly events: HoverEvents;
+  } | null): void;
+}
+/**
+ * The context a click or a key follows `link` with: its `/A` tree (the
+ * actions plugin runs it instead of the target), the annotation it is, its
+ * page, and the view it was followed in (a page destination moves that one).
+ */
+declare function linkActivateContextOf<Ref, Action, Page, Stage>(link: LinkEventShape<Ref, Action>, page: Page, stage: Stage | null): {
+  activate?: Action;
+  ref?: Ref;
+  page: Page;
+  stage?: Stage;
+};
+/**
+ * Send `link`'s own event for a press, a release or a focus change: only for
+ * a link that is an annotation, and only with the actions plugin.
+ */
+declare function sendLinkEvent<Ref, Page>(actions: NoInfer<LinkActionDispatcher<Ref, Page>> | null, link: LinkEventShape<Ref>, page: Page, event: LinkAnchorEvent): void;
+/**
+ * Tell the layer's hover pump the pointer entered `link`: only a link that is
+ * an annotation with hover trees has enter and exit events. Leaving is
+ * `pump.hover(null)`.
+ */
+declare function hoverLink<Ref, Page, HoverEvents>(pump: NoInfer<LinkHoverPump<Ref, Page, HoverEvents>> | null, link: LinkEventShape<Ref, unknown, HoverEvents>, page: Page): void;
+//#endregion
+//#region src/search-highlights.d.ts
+/** A match as the search plugin lists it: the fields the paint reads. */
+interface SearchHitShape {
+  /** Where the match starts in the document's text: with the line's index, its key. */
+  readonly start: number;
+  /** One per line the match spans, in page points. */
+  readonly segments: readonly {
+    readonly quad: PageQuad;
+  }[];
+}
+/** One line of a match, ready to draw. */
+interface SearchHighlightPiece<Hit extends SearchHitShape> {
+  readonly key: string;
+  readonly hit: Hit;
+  /** Whether it's a line of the active match. */
+  readonly active: boolean;
+  readonly fill: string;
+  /** The line's box in the page layer's pixels when it's upright; null when it's turned. */
+  readonly box: PixelRect | null;
+  /** The four corners as SVG `points`, for a turned line; null when it's upright. */
+  readonly points: string | null;
+}
+/** What {@link searchHighlightsOf} paints with. */
+interface SearchHighlightOptions<Hit extends SearchHitShape> {
+  /** The search's active match (compared by identity), or null. */
+  readonly active: Hit | null;
+  /** The page layer's transform. */
+  readonly page: PageToPixels;
+  /** The fill of a match, and of the active one (`paint('search-highlight', …)`). */
+  readonly color: string;
+  readonly activeColor: string;
+}
+/** Every line of `hits` as a piece to draw, in hit order. */
+declare function searchHighlightsOf<Hit extends SearchHitShape>(hits: readonly Hit[], options: SearchHighlightOptions<Hit>): SearchHighlightPiece<Hit>[];
+//#endregion
+//#region src/press-click.d.ts
+/**
+ * Telling a click from a drag on something drawn over a page (a search
+ * match). The press still reaches the page, so a drag that starts there
+ * selects text; only a press that stays put counts as a click.
+ */
+/** A click detector for one layer: feed it the `pointerdown`, ask it at the `click`. */
+interface ClickDetector {
+  /** A press began (`pointerdown`). */
+  press(event: {
+    clientX: number;
+    clientY: number;
+    pointerType: string;
+  }): void;
+  /** Whether this `click` is a click, not the end of a drag. Forgets the press. */
+  isClick(event: {
+    clientX: number;
+    clientY: number;
+  }): boolean;
+}
+declare function createClickDetector(): ClickDetector;
+//#endregion
+//#region src/page-projector.d.ts
+/** The page transform members a projection reads; `PageTransform` satisfies it. */
+interface ProjectedTransform {
+  readonly viewScale: number;
+  readonly rotation: 0 | 90 | 180 | 270;
+  readonly zoom: number;
+}
+/**
+ * The page surface a client projector measures: the page context's members. `transform` may be
+ * the transform or a function that returns the current one (a signal).
+ */
+interface ClientProjectedPage {
+  readonly ref: PageRef;
+  readonly transform: ProjectedTransform | (() => ProjectedTransform);
+  toClientRect(rect: AnchoredRect): AnchoredRect;
+  toClientPoint(point: {
+    x: number;
+    y: number;
+  }): {
+    x: number;
+    y: number;
+  };
+}
+/**
+ * A client-space projector for one page. `mounted` says whether the page
+ * element is in the document yet: until it is, every projection is `null`,
+ * and the anchored UI waits for the first measurable pass. The view is the
+ * window. Pair it with {@link observeClientGeometry}, which reports the
+ * browser-driven moves (document scroll, window resize) no state announces.
+ * Every member reads `page` when it runs, so a page context whose members
+ * change keeps one projector.
+ */
+declare function clientPageProjector(page: ClientProjectedPage, mounted: () => boolean): ViewProjector;
+/** What a Stage projection reads from the Stage lens; `StageHostCapability` satisfies it. */
+interface StageProjection {
+  pageRectToViewport(page: PageRef, rect: AnchoredRect): AnchoredRect | null;
+  getPageFrame(page: PageRef): {
+    readonly transform: ProjectedTransform;
+  } | null;
+  getViewportSize(): {
+    width: number;
+    height: number;
+  };
+}
+/**
+ * The Stage's projector: anchored UI positions through the camera, in the Stage's own box
+ * (`'overlay'` space). `stage()` gives the lens when a projection runs, or null without one
+ * (nothing projects then). It reads only the Stage's state, so the binding's revision (the
+ * visible pages) is what tells anchored UI to place itself again, in the same render as the
+ * pages.
+ */
+declare function stageViewProjector(stage: () => StageProjection | null): ViewProjector;
+//#endregion
+//#region src/page-context.d.ts
+interface ContextPoint {
+  x: number;
+  y: number;
+}
+interface ContextRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/** The bands reserved around a page for its chrome, in screen pixels per side. */
+interface PageFrameShape {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+/** What the conversions need from the page transform; `PageTransform` satisfies it. */
+interface PageContextTransform {
+  viewToPage(point: ContextPoint): ContextPoint;
+  pageToView(point: ContextPoint): ContextPoint;
+  pageToViewRect(rect: ContextRect): ContextRect;
+}
+/** Where the page's content box is on screen, in client pixels: `getBoundingClientRect()`. */
+interface ClientBox {
+  readonly left: number;
+  readonly top: number;
+}
+/** Between client (screen) pixels and points on one page. */
+interface PageClientSpace {
+  /** A client (screen) point to a point on the page: the one platform-bound hit test. */
+  toPagePoint(clientX: number, clientY: number): ContextPoint;
+  /**
+   * A point on the page to client pixels, the exact inverse of `toPagePoint` (rotation applied),
+   * so UI in the view can anchor to a page point without a Stage camera.
+   */
+  toClientPoint(point: ContextPoint): ContextPoint;
+  /** A box on the page to the client-pixel box around it: the box twin of `toClientPoint`. */
+  toClientRect(rect: ContextRect): ContextRect;
+}
+/**
+ * The page context. `Transform` is the page transform (`PageTransform`), `Demand` what the view
+ * wants rendered (`PageViewDemand`).
+ */
+interface PageContext<Transform extends PageContextTransform, Demand> extends PageClientSpace {
+  documentId: string;
+  /**
+   * The page's durable address: use it for keys, rendering and annotations (read
+   * `ref.objectNumber` where a map key is needed). The same object for the surface's lifetime,
+   * so layers may key their work on it.
+   */
+  ref: PageRef;
+  /** The display index (page N), from 0: for ordering and page numbers people read. */
+  pageIndex: number;
+  /**
+   * The bands reserved around the page, in screen pixels per side. The page chrome draws into
+   * the outer box (content and frame): a label in the bottom band is
+   * `bottom: 0; height: frame.bottom`.
+   */
+  frame: PageFrameShape;
+  /**
+   * The one bridge between PDF points, view pixels and device pixels for this page: `toPixels`
+   * to place content, `renderScale` and `deviceWidth` to render, `contentWidth` for sizes
+   * relative to the page. Never multiply by the scale or the device pixel ratio yourself.
+   */
+  transform: Transform;
+  /**
+   * What the page's view wants rendered, as a pull the host fills: a Stage reads the page's
+   * visible part live at call time (a zero box while it is off screen, see
+   * {@link stagePageDemand}); a surface without a camera leaves it out, which means the whole
+   * page.
+   */
+  getViewDemand?: () => Demand;
+  /**
+   * The hosting view's identity: the stage lens id (`stage.getLensId()`) or a per-instance
+   * `PageView` id. Per-view raster planning (tiles) keys its state by it, so two views showing
+   * the same page never fight over one plan.
+   */
+  view: string;
+}
+/**
+ * The client-space conversions of a page whose content box `box()` measures on screen when a
+ * conversion runs: client pixels to box-local view pixels, then the transform undoes the turn
+ * and the scale. `toPagePoint` and `toClientPoint` read the same live box, so they never drift.
+ */
+declare function pageClientSpace(transform: () => PageContextTransform, box: () => ClientBox): PageClientSpace;
+/**
+ * Build a page context. `getRect` is the page's content box on screen (the turned content
+ * element's bounding box), read when a conversion runs.
+ */
+declare function makePageContext<Transform extends PageContextTransform, Demand = never>(documentId: string, view: string, ref: PageRef, pageIndex: number, frame: PageFrameShape, transform: Transform, getRect: () => ClientBox, getViewDemand?: () => Demand): PageContext<Transform, Demand>;
+/**
+ * A page context that reads every member through `current()`: the same object for a surface's
+ * lifetime, current in what it answers. For an adapter whose layers keep the object they were
+ * given once (a Svelte component reads `page.transform` in a template and follows the zoom).
+ */
+declare function livePageContext<Context extends PageContext<PageContextTransform, unknown>>(current: () => Context): Context;
+//#endregion
+//#region src/page-layers.d.ts
+/**
+ * Which parts of a page the layers on it paint themselves. The annotation
+ * layer paints the annotations, the form layer the form fields; while one is
+ * on the page it says so here, and the page's picture (the render layer)
+ * leaves that part out, so nothing is drawn twice and nobody passes a flag.
+ *
+ * Kept per page surface, by the page ref it hands its layers (`page.ref`):
+ * each surface makes its own, and keeps it while it shows the page, through
+ * zooms. Changes reach subscribers a microtask later, so a layer may say what
+ * it paints from any point in its framework's lifecycle (React's insertion
+ * effects included, which must not start updates); `painted()` is current at
+ * once.
+ */
+/** A part of a page a layer can paint instead of the page's picture. */
+type PagePart = 'annotations' | 'formFields';
+/** Which parts the layers on one page paint. */
+interface PaintedParts {
+  readonly annotations: boolean;
+  readonly formFields: boolean;
+}
+/** One page's layers: which parts they paint. */
+interface PageLayers {
+  /** Say this layer paints `part`, until the function it returns is called. */
+  paint(part: PagePart): () => void;
+  /** Which parts are painted now: the same object for the same answer. */
+  painted(): PaintedParts;
+  /** Hear when `painted()` changes. Returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+}
+/** The layers of one page surface, by the page ref it hands its layers. */
+declare function pageLayersOf(pageRef: object): PageLayers;
+/** The parts a render layer was told to draw (`true`) or leave out (`false`). */
+interface PicturePartProps {
+  readonly annotations?: boolean;
+  readonly formFields?: boolean;
+}
+/** What the user may read of each part (the render plugin's `getLayerRights()`). */
+interface PartRights {
+  readonly annotations: boolean;
+  readonly formFields: boolean;
+}
+/** The picture's layer options, as the render plugin takes them. */
+interface PictureLayerOptions {
+  includeAnnotations: boolean;
+  includeFormFields: boolean;
+}
+/**
+ * What the page's picture draws, as the render plugin's layer options: a part
+ * the props name is drawn or left out as they say; any other part is drawn
+ * when no layer on the page paints it and the user may read it. Both are
+ * always given, so a picture that leaves the annotations to a layer still
+ * draws the form fields.
+ */
+declare function pictureLayerOptionsOf(painted: PaintedParts, props: PicturePartProps, may: PartRights): PictureLayerOptions;
+/**
+ * The parts a picture draws that a layer on the page paints too, because the
+ * props asked for them: drawn twice.
+ */
+declare function partsDrawnTwice(painted: PaintedParts, props: PicturePartProps): PagePart[];
+//#endregion
+//#region src/page-surface.d.ts
+/** A box in its parent's pixels. */
+interface SurfaceBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+/** The transform members a surface is laid out from; `PageTransform` satisfies it. */
+interface SurfaceTransform {
+  readonly rotation: 0 | 90 | 180 | 270;
+  readonly viewWidth: number;
+  readonly viewHeight: number;
+  readonly contentWidth: number;
+  readonly contentHeight: number;
+}
+/** The three boxes of a page surface. */
+interface PageSurfaceLayout {
+  /** The footprint and the reserved bands, in the surface's parent; the page chrome fills it. */
+  outer: SurfaceBox;
+  /** The drop shadow at the footprint, in the outer box. */
+  shadow: SurfaceBox;
+  /** The page's content box in the outer box, before it turns; its layers draw in it. */
+  content: SurfaceBox;
+  /** The CSS transform that turns the content box about its centre, or null when it's upright. */
+  turn: string | null;
+}
+/**
+ * Lay out a page surface. `footprint` is where the page's footprint sits in the surface's
+ * parent (a Stage page's device-snapped `screenX`/`screenY`); the outer box sits one band further
+ * out, so the content keeps its place. Without it the outer box is at 0, 0 (a `PageView`, placed
+ * by the page around it).
+ */
+declare function pageSurfaceLayout(transform: SurfaceTransform, frame: PageFrameShape, footprint?: {
+  x: number;
+  y: number;
+}): PageSurfaceLayout;
+/** What {@link stagePageDemand} reads from the Stage; `StageCapability` satisfies it. */
+interface StageDemandSource {
+  listVisiblePages(): readonly {
+    readonly ref: {
+      readonly objectNumber: number;
+    };
+    readonly transform: {
+      readonly deviceWidth: number;
+    };
+    readonly visibleRect: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    };
+  }[];
+}
+/** What a page's view wants rendered; the render plugin's `PageViewDemand` takes it. */
+interface StagePageDemand {
+  desiredDeviceWidth: number;
+  visibleRect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}
+/**
+ * What a Stage page's view wants rendered, read live from the Stage when the render layer asks:
+ * the page's visible part at its device width, or a zero box (want nothing) while the page is
+ * off screen, at `offScreenDeviceWidth`. Visibility is the Stage's data, so no adapter derives
+ * camera math or keeps a copy of it.
+ */
+declare function stagePageDemand(stage: StageDemandSource, pageObjectNumber: number, offScreenDeviceWidth: number): StagePageDemand;
+/** The page a `PageView` shows, as its document's page list has it. */
+interface PageViewPage {
+  readonly size: {
+    readonly width: number;
+    readonly height: number;
+  };
+  readonly rotation: 0 | 90 | 180 | 270;
+  readonly userUnit: number;
+}
+/** The input of `pageTransform()` (`@embedpdf/core-geometry`) for a `PageView`. */
+interface PageViewTransformInput {
+  pageSize: {
+    width: number;
+    height: number;
+  };
+  rotation: 0 | 90 | 180 | 270;
+  scale: number;
+  baseScale: number;
+  dpr: number;
+}
+/**
+ * What a `PageView` builds its page transform from: no camera, so the scale (view pixels per
+ * point) is `width` over the page's width. The base scale is physical 100% on the web, a point
+ * at 96/72 CSS pixels times the page's /UserUnit, so `transform.zoom` still means something: a
+ * thumbnail-sized page reads as zoomed out. Without a page yet, a 1 × 1 placeholder.
+ */
+declare function pageViewTransformInput(page: PageViewPage | null, width: number, dpr: number): PageViewTransformInput;
+//#endregion
+//#region src/page-pointer.d.ts
+interface PointerPoint {
+  x: number;
+  y: number;
+}
+/**
+ * A multi-click counter. `pointerdown.detail` is 0 or 1 in several browsers, so clicks are
+ * counted here from timing and distance: the standard double and triple click. Input is
+ * normalized in the adapter; the hub and its handlers stay pure.
+ */
+declare function createClickCounter(maxGapMs?: number, maxDistancePx?: number): (now: number, x: number, y: number) => number;
+/** What the listener reads from the page context when an event arrives. */
+interface PagePointerPage {
+  readonly ref: PageRef;
+  readonly transform: {
+    readonly viewScale: number;
+    readonly rotation: 0 | 90 | 180 | 270;
+    readonly zoom: number;
+  };
+  toPagePoint(clientX: number, clientY: number): PointerPoint;
+}
+/** The sample the listener hands the hub: structurally the interaction plugin's `PointerSample`. */
+interface PagePointerSample {
+  phase: 'down' | 'move' | 'up';
+  viewport: PointerPoint;
+  page: {
+    ref: PageRef;
+    point: PointerPoint;
+    scale: number;
+    rotation: 0 | 90 | 180 | 270;
+    zoom: number;
+  };
+  project: (page: PageRef) => PointerPoint | null;
+  modifiers: {
+    shift: boolean;
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+  };
+  clickCount: number;
+  pointerType: 'mouse' | 'pen' | 'touch';
+}
+/** What the listener needs from the interaction hub; `InteractionHostCapability` satisfies it. */
+interface PagePointerHub {
+  dispatchPointer(sample: PagePointerSample): void;
+}
+/**
+ * Listen to the pointer on `element` for the page `page()` gives when an event arrives (a zoom
+ * changes it, and a drag carries on through it), and dispatch every event to `hub`. A press
+ * starts on the element; while it lasts the window listens, so a drag goes on outside the page.
+ * Returns the function that stops listening.
+ */
+declare function attachPagePointer(element: HTMLElement, hub: PagePointerHub, page: () => PagePointerPage): () => void;
+//#endregion
+//#region src/scrollbar.d.ts
+/**
+ * A Stage scrollbar's geometry and its press handling, shared by every framework's `Scrollbar`.
+ *
+ * The Stage gives its scroll position as a scrolling element has it (`scrollTop`,
+ * `scrollHeight`, `clientHeight` and their horizontal twins, in screen pixels). From that and the
+ * measured track this module draws the thumb, and turns presses into Stage calls the way a native
+ * bar does: a thumb drag keeps the point it grabbed under the pointer, and a press on the track
+ * pages toward the pointer, repeating while held and stopping when the thumb reaches it. A drag
+ * is frozen at the press (grab point, travel, range) and applied as relative pans: absolute in
+ * feel on a bounded Stage, and steady on an unbounded one, whose range moves under the pointer.
+ *
+ * The adapters keep their reactive glue: the track's size, auto-hide, hover and the markup.
+ */
+/** The scroll position a Stage reports (`ScrollMetrics` from the stage plugin satisfies it). */
+interface ScrollbarMetrics {
+  readonly scrollLeft: number;
+  readonly scrollTop: number;
+  readonly scrollWidth: number;
+  readonly scrollHeight: number;
+  readonly clientWidth: number;
+  readonly clientHeight: number;
+}
+/** The bar along one axis, in track pixels. */
+interface ScrollbarLayout {
+  /** The view's length along the axis. */
+  client: number;
+  /** How far the view is scrolled. */
+  offset: number;
+  /** The farthest it can scroll. */
+  maxOffset: number;
+  thumbLength: number;
+  /** How far the thumb can move along the track. */
+  travel: number;
+  thumbPosition: number;
+}
+/**
+ * The thumb from the metrics and the track's length: one formula for drawing, dragging and
+ * paging, so they never disagree. The thumb never gets shorter than `minThumbSize`, and its
+ * position stays proportional over the travel that leaves.
+ */
+declare function scrollbarLayout(metrics: ScrollbarMetrics, vertical: boolean, trackPx: number, minThumbSize: number): ScrollbarLayout;
+/** The Stage calls a scrollbar makes; `StageCapability` satisfies it. */
+interface ScrollbarStage {
+  scrollTo(position: {
+    top?: number;
+    left?: number;
+  }): void;
+  scrollBy(delta: {
+    top?: number;
+    left?: number;
+  }): void;
+  panBy(dx: number, dy: number): void;
+}
+/** The bar as it is at a press: what the press handlers read. */
+interface ScrollbarTrack {
+  readonly stage: ScrollbarStage;
+  readonly vertical: boolean;
+  /** The track element: pointer positions are measured from its start. */
+  readonly element: Element;
+  /** The layout drawn now. */
+  readonly layout: ScrollbarLayout;
+  /** The layout from the Stage's metrics as they are now, for each paging step. */
+  liveLayout(): ScrollbarLayout;
+}
+/**
+ * The pointer event a press handler reads: a DOM `PointerEvent`, or a framework's own event
+ * with the same members (React's), so `stopPropagation` and `currentTarget` mean what the
+ * framework's handlers mean.
+ */
+interface ScrollbarPointerEvent {
+  readonly button: number;
+  readonly pointerId: number;
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly target: EventTarget | null;
+  readonly currentTarget: EventTarget | null;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+/** A scrollbar's presses: wire the thumb's and the track's pointer events to these. */
+interface ScrollbarPresses {
+  /** A press on the thumb starts a drag. */
+  pressThumb(event: ScrollbarPointerEvent, track: ScrollbarTrack): void;
+  /**
+   * A press on the track itself: `'page'` steps 90% of a view toward the pointer, repeats while
+   * held and stops at the pointer; `'jump'` puts the thumb under the pointer and goes on as a
+   * drag. A press that reached the track from the thumb is the thumb's.
+   */
+  pressTrack(event: ScrollbarPointerEvent, track: ScrollbarTrack, mode: 'page' | 'jump'): void;
+  /** A pointer move on the track (pointer capture sends them there): drags, and paging's target. */
+  move(event: ScrollbarPointerEvent, track: ScrollbarTrack): void;
+  /** The press ended: no drag, no repeat. Also call it when the bar goes away. */
+  release(): void;
+}
+/**
+ * One scrollbar's press handling. `onDragging` hears when a drag starts and ends, for the bar's
+ * `data-dragging` and to keep it shown.
+ */
+declare function createScrollbarPresses(onDragging: (dragging: boolean) => void): ScrollbarPresses;
+//#endregion
+//#region src/orientation.d.ts
+/**
+ * Which way a row of controls runs, and which way its text reads: what a
+ * toolbar measures along, and what its arrow keys move along.
+ */
+/** A row of controls side by side, or one under another (`aria-orientation`'s values). */
+type Orientation = 'horizontal' | 'vertical';
+/** The writing direction an element lays out in: its computed CSS `direction`. */
+declare function directionOf(element: Element): 'ltr' | 'rtl';
+//#endregion
+//#region src/toolbar-measure.d.ts
+/** The keys the measurement layer reports lengths under, the ones the metrics look up. */
+declare const toolbarMeasureKey: {
+  /** A unit (`NormalizedUnit.key`) at one variant. */
+  readonly unit: (unitKey: string, variant: string) => string;
+  /** A group in its collapsed form. */
+  readonly group: (groupId: string) => string;
+  /** A shed group's disclosure trigger, measured with the whole group behind it. */
+  readonly groupTrigger: (groupId: string) => string;
+  /** The "More" button. */
+  readonly overflowTrigger: "t:";
+};
+/** The lengths a fit needs: the structural twin of core-ui's `FitMetrics`. */
+interface ToolbarFitMetrics {
+  unit(key: string, variant: string): number | undefined;
+  groupCollapsed(groupId: string): number | undefined;
+  groupTrigger(groupId: string): number | undefined;
+  readonly overflowTrigger: number;
+  readonly gap: number;
+  readonly separator: number;
+}
+/**
+ * The measured lengths of one toolbar, kept apart per orientation: a toolbar
+ * turned on its side never fits with the other axis's numbers.
+ */
+interface ToolbarLengths {
+  /**
+   * A measured element's length along `orientation`, under its
+   * {@link toolbarMeasureKey}. True when it changed by more than half a pixel:
+   * render (and solve) again.
+   */
+  report(orientation: Orientation, key: string, length: number): boolean;
+  /**
+   * The lengths along `orientation` as fit metrics, for items `gap` px apart
+   * and separators `separatorWidth` px thick (a separator's width is its
+   * thickness, across a horizontal bar or down a vertical one). A separator is
+   * one more flex child: its thickness plus one gap. Until the "More" button
+   * is measured it counts as 32 px.
+   */
+  metrics(orientation: Orientation, gap: number, separatorWidth: number): ToolbarFitMetrics;
+}
+declare function createToolbarLengths(): ToolbarLengths;
+/**
+ * Report an element's width (its border box) now and whenever it resizes. Put
+ * it on every element of a horizontal toolbar's measurement layer, and on a
+ * custom slot's `<slot>` socket, which is measured live where it renders.
+ * Returns the detach.
+ */
+declare function observeWidth(element: Element, onWidth: (width: number) => void): () => void;
+/** {@link observeWidth} for a vertical toolbar: an element's border-box height. */
+declare function observeHeight(element: Element, onHeight: (height: number) => void): () => void;
+/** An element's length along a toolbar: {@link observeWidth} or {@link observeHeight}. */
+declare function observeLength(element: Element, orientation: Orientation, onLength: (length: number) => void): () => void;
+/**
+ * Report the width a toolbar has to fill (its content box) now and whenever
+ * it changes by more than half a pixel. Returns the detach.
+ */
+declare function observeContentWidth(element: HTMLElement, onWidth: (width: number) => void): () => void;
+/**
+ * The height a vertical toolbar has to fill, like {@link observeContentWidth}.
+ * The toolbar fits the height it's given, so its container needs one.
+ */
+declare function observeContentHeight(element: HTMLElement, onHeight: (height: number) => void): () => void;
+/** The room along a toolbar: {@link observeContentWidth} or {@link observeContentHeight}. */
+declare function observeContentLength(element: HTMLElement, orientation: Orientation, onLength: (length: number) => void): () => void;
+//#endregion
+//#region src/focusable.d.ts
+/**
+ * Which elements take keyboard focus, for the keyboard models (a toolbar's
+ * stops, a menu's items, a dialog's tab order). Decided from the markup only,
+ * never from layout, so it answers the same before the first paint: `hidden`,
+ * `inert` and `disabled` count; a `display: none` from a stylesheet doesn't.
+ */
+/** Whether an element can take focus now: focusable markup, not disabled, not hidden or inert. */
+declare function canTakeFocus(element: Element): boolean;
+/** Whether Tab stops at an element: it takes focus and its `tabIndex` isn't negative. */
+declare function isTabbable(element: Element): element is HTMLElement;
+/**
+ * The elements inside `root` that can take focus, in the order they show: through a `<slot>`,
+ * the page's elements the browser shows there (a web component's slotted children).
+ */
+declare function focusablesIn(root: ParentNode): HTMLElement[];
+/** The elements inside `root` that Tab stops at, in document order. */
+declare function tabbablesIn(root: ParentNode): HTMLElement[];
+/**
+ * The element that has focus, looking into shadow roots: the document's
+ * `activeElement` is only the outermost shadow host. Null when nothing has
+ * focus (the body).
+ */
+declare function deepActiveElementOf(doc: Document): Element | null;
+/**
+ * Whether the element with focus is `container` or inside it, as the page shows it: through
+ * shadow roots, and from an element slotted into a shadow root to its slot, so a control
+ * slotted into a viewer counts as inside the viewer, as its keys do.
+ */
+declare function containsFocus(container: Element): boolean;
+/**
+ * Whether a control says it can't be used now, through `disabled` or
+ * `aria-disabled="true"`: the keyboard models pass over it.
+ */
+declare function isUnavailable(element: Element): boolean;
+/**
+ * Whether a focused control uses `key` itself, so a keyboard model around it
+ * must leave the key alone: a text field moves its caret with Left, Right,
+ * Home and End; a select changes with Up and Down; a slider takes them all.
+ */
+declare function usesKey(element: Element, key: string): boolean;
+//#endregion
+//#region src/roving-focus.d.ts
+/** Where a key moves focus in a row. */
+type RovingMove = 'next' | 'previous' | 'first' | 'last';
+/** The move `key` asks for in a row running `orientation`, or null for a key the row leaves alone. */
+declare function rovingMoveOf(key: string, orientation: Orientation, direction: 'ltr' | 'rtl'): RovingMove | null;
+/**
+ * The index `move` lands on among `count` stops, from `current` (-1 for
+ * none), passing over the stops `available` rejects. With `loop`, next and
+ * previous wrap around the ends; without it they stop there. -1 when there is
+ * nowhere to go.
+ */
+declare function rovingTargetOf(move: RovingMove, current: number, count: number, available: (index: number) => boolean, loop: boolean): number;
+interface RovingFocusOptions {
+  /** Which arrows move: Left and Right for `'horizontal'`, Up and Down for `'vertical'`. */
+  readonly orientation: Orientation;
+  /** The stops, in order; read again on every key and every {@link RovingFocus.refresh}. */
+  readonly stops: () => readonly HTMLElement[];
+  /** The writing direction. Default: the container's computed `direction`, read on each key. */
+  readonly direction?: () => 'ltr' | 'rtl';
+  /** Whether next and previous wrap around at the ends. Default true. */
+  readonly loop?: boolean;
+}
+/** A row's roving focus, from {@link attachRovingFocus}. */
+interface RovingFocus {
+  /**
+   * Put the one tab stop back after the stops changed: on the stop that had
+   * focus last while it's still there and usable, else on the first usable
+   * one. Call it after every render that can add, remove or disable a stop.
+   */
+  refresh(): void;
+  /** Stop handling keys and focus. The stops keep their `tabIndex`. */
+  detach(): void;
+}
+/**
+ * Make the stops of `container` one tab stop with arrow keys between them.
+ * Keys count only while a stop itself has focus, so keys inside a menu or
+ * another control the row holds are theirs; a key with Alt, Control, Meta or
+ * Shift, or one a handler already took (`defaultPrevented`), is left alone.
+ */
+declare function attachRovingFocus(container: HTMLElement, options: RovingFocusOptions): RovingFocus;
+//#endregion
+//#region src/toolbar-focus.d.ts
+/** The attribute on the element around each item of a toolbar's live row. */
+declare const TOOLBAR_ITEM_ATTRIBUTE = "data-epdf-toolbar-item";
+/**
+ * A toolbar's stops: the first element of each item that takes focus, in
+ * order. A menu an item holds open is not part of its stop.
+ */
+declare function toolbarStopsOf(toolbar: ParentNode): HTMLElement[];
+/** Arrow keys between a toolbar's items, along its orientation; `refresh()` after each render. */
+declare function attachToolbarFocus(toolbar: HTMLElement, orientation: Orientation): RovingFocus;
+//#endregion
+//#region src/menu-keys.d.ts
+/**
+ * The item typeahead lands on: the first one from `current` on, wrapping, that
+ * is available and whose label starts with `query` (any case). A one-letter
+ * query starts after `current`, so typing the same letter again moves on, and
+ * a query of one letter repeated ("ppp") cycles like that letter. -1 when no
+ * item matches.
+ */
+declare function typeaheadMatchOf(labels: readonly string[], current: number, query: string, available: (index: number) => boolean): number;
+/**
+ * The words typeahead matches an item by: its `aria-label`, else its text,
+ * without the marks a row may start with (a bullet, a check, an icon glyph).
+ */
+declare function menuItemLabelOf(item: Element): string;
+interface MenuKeysOptions {
+  /** The button that opened the menu: it says it's expanded, and gets focus back. */
+  readonly trigger: HTMLElement | null;
+  /** Close the menu; removing it is the caller's. */
+  readonly close: () => void;
+  /** The items, in order. Default: the menu's `menuitem`, `menuitemradio` and `menuitemcheckbox` elements. */
+  readonly items?: () => readonly HTMLElement[];
+  /** Which item takes focus when the menu opens. Default `'first'`. */
+  readonly initialFocus?: 'first' | 'last' | 'none';
+}
+/**
+ * Drive an open `menu` from the keyboard until the returned detach runs.
+ * Detaching (the menu closed) gives focus back to the trigger when focus was
+ * in the menu or went nowhere, and never when the user moved it elsewhere.
+ */
+declare function attachMenuKeys(menu: HTMLElement, options: MenuKeysOptions): () => void;
+//#endregion
+//#region src/focus-trap.d.ts
+/**
+ * Move focus into `container` unless it's there already: to `initialFocus`, else its first
+ * control Tab stops at, else the container itself. Focus already inside stays where it is, so a
+ * control that took focus as it appeared (a search field asking for the cursor) keeps it.
+ */
+declare function moveFocusInto(container: HTMLElement, initialFocus?: HTMLElement | null): void;
+interface FocusTrapOptions {
+  /**
+   * What takes focus when the trap starts, unless focus is inside already. Default: the first
+   * control Tab stops at.
+   */
+  readonly initialFocus?: HTMLElement | null;
+  /** Whether focus goes back to where it was when the trap is released. Default true. */
+  readonly returnFocus?: boolean;
+}
+/** Trap focus in `container` until the returned release runs. */
+declare function attachFocusTrap(container: HTMLElement, options?: FocusTrapOptions): () => void;
+//#endregion
+//#region src/surface-focus.d.ts
+/**
+ * Putting the cursor in a panel when it asks. The shell raises a surface's `focusRequest` on
+ * every `open(id, { focus: true })` and clears it when the surface closes; the element that
+ * follows it takes focus whenever the request changes to a new value above 0, and when it starts
+ * following while the request is up (the panel opened, or its code loaded, because of it). The
+ * adapters' surface-focus hooks bind a follower to their reactivity; the rule lives here.
+ */
+/** How an element takes focus when its surface asks. */
+interface SurfaceFocusOptions {
+  /** Select the text of an input or a text area as it takes focus, so typing replaces it. */
+  readonly select?: boolean;
+}
+/** One element following one surface's focus requests. */
+interface SurfaceFocusFollower {
+  /**
+   * Take the surface's request as it is now. `shell` is the capability it was read from (null
+   * without a document): another document's shell starts over, as a new mount does. Without an
+   * element yet, a request waits for it.
+   */
+  follow(element: HTMLElement | null, shell: object | null, request: number, options?: SurfaceFocusOptions): void;
+}
+declare function createSurfaceFocusFollower(): SurfaceFocusFollower;
+//#endregion
+//#region src/standard-commands-platform.d.ts
+/** What the standard commands need from the browser: the structural twin of `StandardCommandsPlatform`. */
+interface StandardCommandsBrowser {
+  copySelection: typeof copySelection;
+  saveFile(bytes: Uint8Array, fileName: string): void;
+  print(): void;
+}
+declare const standardCommandsBrowser: StandardCommandsBrowser;
+//#endregion
+export { type ActionsUiAdapterShape, type ActionsUiEffectContext, type ActionsUiOrigin, type AnchorTarget, type AnchoredFit, type AnchoredOptions, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AnchoredSide, type AnchoredSize, type AnnotationAnchorShape, type AnnotationChromePaint, type AnnotationDrawing, type AnnotationLookFrame, type AppearancePicture, type AppearanceUrl, type AttachSelectionHandleOptions, type BehaviorRendererEntry, type ByteStore, type ChromeInPixels, type ChromeLine, type ChromeLinePaint, type ChromeNodeShape, type ChromePaintSettings, type ChromeShapePaint, type ClickDetector, type ClientBox, type ClientProjectedPage, type ClipboardSelectionSource, type CommandShortcutOptions, type CommentPageLayout, type CommentThreadPage, type CreationDraftAnchorShape, type CssFont, type DefaultActionsUiAdapterOptions, EPDF_VARIABLES, type EditorDocumentFactory, type EditorElement, type EditorNode, type EditorPosition, type EditorRoot, type EditorStyle, type EpdfCssOnlyVariable, type EpdfFollowedVariable, type EpdfSettingVariable, type EpdfTheme, type EpdfThemeVariables, type EpdfTranslucentVariable, type EpdfVariable, type EpdfVariableDefinition, FORM_CONTROL_FILL, type FieldLook, type FieldTextStyle, type FilePickerPort, type FocusTrapOptions, type FormColorSettings, type FormColors, type FormControlFill, type FormFocusRingStyle, type FrameBox, type FrameFraction, type FramePixels, type IndexedDbByteStoreOptions, type LineModel, type LinkActionDispatcher, type LinkActionSource, type LinkAnchor, type LinkAnchorEvent, type LinkAnchorShape, type LinkEventShape, type LinkHoverPump, type ListBoxControlStyle, type ListBoxStyle, type LookRendererEntry, type LookState, type MenuKeysOptions, type MountableFontProgram, type ObjectUrl, type ObjectUrlImageSource, type OptimisticSelection, type Orientation, type PageBoundsAnchor, type PageClientSpace, type PageContext, type PageContextTransform, type PageFrameShape, type PageLayerTransform, type PageLayers, type PagePart, type PagePoint, type PagePointerHub, type PagePointerPage, type PagePointerSample, type PageQuad, type PageRef, type PageSurfaceLayout, type PageToPixels, type PageViewEnv, type PageViewPage, type PageViewTransformInput, type PaintedImageCallbacks, type PaintedParts, type PartRights, type PickFileOptions, type PictureBytes, type PictureLayerOptions, type PictureOrPainting, type PicturePartProps, type PixelBox, type PixelRect, type ProjectedTransform, type RendererBehaviorRegistry, type RendererEntry, type RendererInteractiveContext, type RichTextEditorAlign, type RichTextEditorBinding, type RichTextEditorCommand, type RichTextEditorDecoration, type RichTextEditorDocument, type RichTextEditorHost, type RichTextEditorParagraph, type RichTextEditorProps, type RichTextEditorRange, type RichTextEditorRun, type RichTextEditorScript, type RichTextEditorStyle, type RotationAnchorShape, type RovingFocus, type RovingFocusOptions, type RovingMove, type ScenePaint, type SceneShapeNode, type ScrollbarLayout, type ScrollbarMetrics, type ScrollbarPointerEvent, type ScrollbarPresses, type ScrollbarStage, type ScrollbarTrack, type SearchHighlightOptions, type SearchHighlightPiece, type SearchHitShape, type SelectOptions, type SelectionAnchorShape, type SelectionClipboardOptions, type SelectionEndpointShape, type SelectionEndpointsShape, type SelectionHandleSession, type ShortcutCommands, type ShortcutRefusal, type ShownUrls, type StageDemandSource, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePageDemand, type StagePointerKind, type StageProjection, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type StandardCommandsBrowser, type StyleRecord, type SurfaceBox, type SurfaceFocusFollower, type SurfaceFocusOptions, type SurfaceTransform, type SvgCursorOptions, type SvgShape, type SvgShapeTag, type SvgShapesOptions, TOOLBAR_ITEM_ATTRIBUTE, type TextBoxCss, type TextBoxEditor, type TextBoxEditorAnnotation, type TextBoxEditorFollower, type TextBoxEditorItem, type TextBoxStyle, type TextEditorLayout, type TextFieldDrafts, type TextFieldEditor, type TextFieldEditorState, type TextFieldEditorStyle, type TextFieldStyle, type TextPlatePixels, type ToggleForm, type ToolCursorImage, type ToolCursorSpec, type ToolbarFitMetrics, type ToolbarLengths, type TurnedBox, type ViewProjector, type WebClock, type WebFontMetrics, type WebPlatformFeedback, type WheelSample, type WidgetBoxStyle, type WidgetEventKind, anchoredViewOf, annotationChromePaint, annotationDrawingOf, applyFirstLineShift, attachFocusTrap, attachMenuKeys, attachPagePointer, attachRichTextEditor, attachRovingFocus, attachSelectionHandle, attachTextBoxEditor, attachToolbarFocus, bakedAppearanceOf, bindCommandShortcuts, bindPaintedImage, bindWidgetEvents, browserClock, canTakeFocus, chromeInPixels, clientPageProjector, computeReleaseVelocity, containsFocus, copySelection, createClickCounter, createClickDetector, createDefaultActionsUiAdapter, createFontMounts, createOptimisticSelection, createScrollbarPresses, createShownUrls, createStageGestureController, createStageSurface, createSurfaceFocusFollower, createTextBoxEditorFollower, createTextFieldEditor, createToolbarLengths, cssFontOf, cssText, deepActiveElementOf, directionOf, editingTextKeyOf, enrichCommentThreads, epdfThemeVariables, firstLineShiftFor, fitAnchoredRect, focusablesIn, fontProgramsOf, formColorsOf, formFocusRingStyleOf, frameInPixels, ghostOpacity, hoverLink, indexedDbByteStore, installFilePickerProvider, isMacPlatform, isModifiedClick, isTabbable, isUnavailable, isUprightQuad, isolatePointerDown, isolateWheel, layerTextBoxesOf, lineModelFor, linkActivateContextOf, linkAnchorOf, linkHrefOf, listBoxControlStyleOf, listBoxStyleOf, livePageContext, loadAppearanceUrls, loadObjectUrl, lookFrameOf, lookRendererFor, makePageContext, menuItemLabelOf, mixAccent, mountFontProgram, mountWebFont, moveFocusInto, navigableLinksOf, objectUrlOf, observeAnchoredFit, observeClientGeometry, observeContentHeight, observeContentLength, observeContentWidth, observeHeight, observeLength, observeOutsidePress, observeWidth, offsetOfPosition, openExternalUri, pageClientSpace, pageLayersOf, pageSurfaceLayout, pageViewTransformInput, paint, paintDefault, partsDrawnTwice, pickFile, pickImageFile, pickRequestedFile, pictureLayerOptionsOf, pictureOrPainting, positionAnchoredRect, positionOfOffset, pressToggle, projectAnchoredTarget, quadInPixels, rasterInFrame, rectInPixels, registerRendererBehaviors, renderRichText, rendererBehaviorId, rovingMoveOf, rovingTargetOf, sameAnchoredFit, sameAnnotationAnchor, sameCreationDraftAnchor, samePageBounds, sameRotationAnchor, sameSelectionAnchor, sameSelectionEndpoints, sanitizeExternalUri, saveFile, sceneViewBox, scrollbarLayout, searchHighlightsOf, sendLinkEvent, serializeRichText, showSelectedOptions, shownAppearance, stagePageDemand, stageViewProjector, standardCommandsBrowser, styleDeltaOf, svgCursor, svgPoints, svgShapesOf, tabbablesIn, textBoxEditorScaleOf, textBoxStyleOf, textFieldEditorStyleOf, textFieldStyleOf, textPlateInPixels, toolCursorsOf, toolbarMeasureKey, toolbarStopsOf, typeaheadMatchOf, usesKey, vibrationFeedback, webFontMetrics, wheelZoomFactor, widgetBoxStyleOf, wireSelectionClipboard, wkFeedback };
 //# sourceMappingURL=index.d.cts.map