@embedpdf/plugin-stage 3.0.0-next.13 → 3.0.0-next.15

package/dist/contract-DZR_jRer.d.cts

@@ -0,0 +1,568 @@
+import { CapabilityToken, EventHook, PageDestination, PageInfo, PageRef } from "@embedpdf/core";
+import { PageRotation, PageTransform, Rect } from "@embedpdf/core-geometry";
+import { Align, AlignValue, AlignValue as AlignValue$1, Alignment, Alignment as Alignment$1, AlignmentValue, AlignmentValue as AlignmentValue$1, Anchor, Camera, Camera as Camera$1, Direction, Direction as Direction$1, PageBox, PageFrame, PageFrame as PageFrame$1, Point, Point as Point$1, ScrollMetrics, Size, Size as Size$1, SizingMode, SizingMode as SizingMode$1, SpreadMode, SpreadMode as SpreadMode$1, ZoomMode, ZoomModeValue, ZoomModeValue as ZoomModeValue$1, ZoomSpec, ZoomSpec as ZoomSpec$1 } from "@embedpdf/core-stage";
+//#region src/token.d.ts
+declare const StageToken: import("@embedpdf/core").CapabilityToken<StageCapability>;
+//#endregion
+//#region src/contract.d.ts
+type LayoutKind = 'vertical' | 'horizontal' | 'grid';
+/** Navigation (goToPage) either tweens the camera or jumps instantly. */
+type ScrollBehaviorKind = 'smooth' | 'instant';
+/**
+ * Presentation flow:
+ *   'continuous' — the whole document is scrollable; the camera roams the full scene.
+ *   'paged'      — one item (page or spread) at a time: the scene is a one-item
+ *                  slice at the cursor, and nextPage/previousPage step between items.
+ */
+type FlowMode = 'continuous' | 'paged';
+/**
+ * Grid column policy:
+ *   'square' — ≈√n columns (the classic canvas arrangement)
+ *   'auto'   — wrapped: as many columns as fit the viewport line at the current
+ *              zoom (the responsive thumbnail-sidebar behavior; re-wraps on resize)
+ *   number   — a fixed column count
+ */
+type GridColumns = 'square' | 'auto' | number;
+/**
+ * Space between items — the value's shape carries the unit (like ZoomSpec):
+ *   number     — world units: the gap is part of the canvas and scales with zoom,
+ *                so the whole scene zooms as one rigid object (the document feel).
+ *   { px: n }  — screen px: UI-stable spacing, the same in every document at every
+ *                zoom (the browser-of-items feel: thumbnails, organizers).
+ */
+type Gap = number | {
+  px: number;
+};
+/**
+ * The one environmental fact a headless stage has: the box it was told about
+ * (`setViewportSize`). Responsive rules can query nothing else — no user agent, no
+ * pointer type (modality is per-event, on `PointerSample`), no window. Space,
+ * not device: a narrow pane on a desktop is compact too, and each stage
+ * instance resolves against its own box.
+ */
+interface StageBox {
+  width: number;
+  height: number;
+  /** Of the container, not the device. A square box is 'portrait' (the CSS rule). */
+  orientation: 'portrait' | 'landscape';
+}
+/** Declarative box query: all bounds inclusive, all fields optional, every condition must hold. */
+interface BoxQuery {
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+  orientation?: 'portrait' | 'landscape';
+}
+/**
+ * One `@container` block for the settings bag: when the box matches, assert
+ * this settings patch. Rules evaluate in source order and all matching rules
+ * apply, later winning per key (each key replaced whole — no deep merges).
+ * Effective settings = base (config + `updateSettings()`) ⊕ matching patches.
+ *
+ * Semantics:
+ *   • `updateSettings()` writes the base; a matching rule wins over it. Apps
+ *     needing situational absolute control edit the rules (`setResponsiveRules`).
+ *   • Rules assert at transitions (box/base/rules changes), not continuously —
+ *     between crossings, interaction owns the state. A rule containing `zoom`
+ *     re-fits when the box crosses it (the rotate-an-iPad behavior) and then
+ *     leaves the pinch alone.
+ *
+ * A rule with a `name` is a queryable fact (`matchesRule(name)`), reactive in
+ * every framework; a named rule with no settings is a pure shared breakpoint
+ * the app chrome can key its own presentation off — one definition serving
+ * both the layout math and the UI.
+ */
+interface ResponsiveRule {
+  name?: string;
+  /** Declarative box query, or a predicate for anything the box can answer. */
+  when: BoxQuery | ((box: StageBox) => boolean);
+  /** The settings this situation asserts. Omit for a pure named query. */
+  settings?: StageSettingsPatch;
+}
+/**
+ * One axis of the arrival policy — stage-core's AlignValue ('start' |
+ * 'center' | 'end' | viewport fraction 0–1) plus one navigation-only word:
+ *   'keep' — this axis does not move on arrival: page forward, hold your
+ *            pan (the two-column-paper feel; the PDF /XYZ null semantic).
+ */
+type ArrivalAlignValue = AlignValue | 'keep';
+interface ArrivalAlignment {
+  x: ArrivalAlignValue;
+  y: ArrivalAlignValue;
+}
+/**
+ * The stage's orthogonal settings, one view's own. Any subset changes in one
+ * `updateSettings()` call, and each value given replaces the current one
+ * whole. A preset is a {@link StageSettingsPatch} the app keeps and applies;
+ * no preset machinery lives here.
+ */
+interface StageSettings {
+  /** Continuous scroll, or one item at a time. */
+  flow: FlowMode;
+  layout: LayoutKind;
+  spread: SpreadMode;
+  /** Page sizing: true PDF sizes, or equalize the cross axis so pages sit flush. */
+  sizing: SizingMode;
+  /** Grid column policy (grid layout only): 'square', 'auto' (wrapped), or a count. */
+  columns: GridColumns;
+  /** Clamp the camera to the content? Off = free infinite pan (construction drawings). */
+  bounded: boolean;
+  /**
+   * Breathing room (screen px) around the content — the one spacing concept.
+   * Fit-modes inset by it, arrivals leave it as a gutter, and the clamp lets the
+   * camera reveal exactly this much beyond each content edge.
+   */
+  padding: number;
+  /**
+   * Space between items — and between the halves of a spread. A number is world
+   * units (scales with zoom — the canvas feel); `{ px }` is screen px (UI-stable
+   * — the thumbnail feel). See {@link Gap}.
+   */
+  gap: Gap;
+  /**
+   * Reserved chrome real estate around each page, in screen px — one thickness
+   * per side. The page content is inset by these; the bands hold box-space
+   * chrome (a label below, a button row above, side rails) painted by the app
+   * via the adapter's `pageChrome` slot. Per page, not per item: in a spread
+   * every page keeps its own flanks. Constant screen px (unaffected by zoom).
+   *
+   * Naming rule for this settings bag: every setting describes the stage itself
+   * (the container) — `padding`, `gap`, `layout`, … The rare setting owned by the
+   * page carries the `page` prefix (`pageFrame`; `pageWidth` in zoom).
+   */
+  pageFrame: PageFrame;
+  /**
+   * Reading direction. RTL: horizontal items advance leftward, spreads bind on the
+   * right, grid rows fill right→left, and alignment 'start' on x means the right
+   * edge (logical, CSS-style). Navigation is index-based and never changes.
+   */
+  direction: Direction;
+  /**
+   * The alignment family — every camera move is defined by what it holds
+   * fixed. Gestures (pan/pinch/wheel) hold the pointer: physics, no setting.
+   * Explicit arrivals (positioned reveal, destinations, viewpoints) hold
+   * whatever the call specifies. These four settings govern the rest:
+   *
+   *   fitAlign     — the standing constraint: where content rests on an axis
+   *                  the camera cannot travel (it fits the true bounds — the
+   *                  scene in continuous flow, the item slice in paged). The
+   *                  clamp enforces it on every camera write — which is why a
+   *                  fitting axis settles identically whatever arrivalAlign
+   *                  says. center/center = document feel; y:'start' = sidebar
+   *                  thumbnails hugging the top.
+   *   arrivalAlign — the landing policy: where navigation (goToPage,
+   *                  nextPage, previousPage, resetView) puts the target — the
+   *                  same at every zoom.
+   *                  start/start = reading (top-left, direction-aware);
+   *                  center/center = presentation/drawings (Drawboard feel);
+   *                  y: 0.35 = the find-bar line; 'keep' = don't move an axis.
+   *   zoomAlign    — the focal point of a pointer-less zoom (zoomIn/zoomOut,
+   *                  zoomTo, fit-mode switches). Pinch/ctrl+wheel always hold
+   *                  the pointer instead — that is physics, not policy.
+   *                  center/center = the view inflates around its middle;
+   *                  y:'start' = the first visible line holds still.
+   *   anchorAlign  — the viewport point that survives a reframe (viewport
+   *                  resize, page rotation, spread/gap change): the view
+   *                  anchor is captured there and restored there. start/start
+   *                  = the browser scroll model (growth reveals below — a
+   *                  container that mounts small and expands never shoves the
+   *                  document down); center/center = canvas-style symmetric
+   *                  resizes (the Figma feel).
+   *
+   * Named x values are logical (CSS-style: 'start' = reading start — the
+   * right edge in RTL); fractions are physical, like screen coordinates.
+   */
+  fitAlign: Alignment;
+  /** See {@link StageSettings.fitAlign} — where navigation lands, per axis. */
+  arrivalAlign: ArrivalAlignment;
+  /** See {@link StageSettings.fitAlign} — the pointer-less zoom focal point. */
+  zoomAlign: AlignmentValue;
+  /** See {@link StageSettings.fitAlign} — the viewport point reframes hold. */
+  anchorAlign: AlignmentValue;
+  /**
+   * A non-persistent view rotation: a quarter-turn (clockwise) applied to how
+   * every page is displayed in this lens, on top of each page's own /Rotate —
+   * Adobe's "Rotate View". A display setting like `zoom` or `layout`: per lens
+   * (the main viewer can rotate while a thumbnail lens stays upright), never
+   * written to the document, gone when the lens resets. The permanent
+   * counterpart — writing /Rotate into the PDF — is plugin-page-edit's
+   * `rotateBy`/`setRotation`.
+   */
+  viewRotation: PageRotation;
+  /** Zoom intent: a fit-mode (automatic/fit-page/fit-width/fit-all) or a fixed level. */
+  zoom: ZoomSpec;
+  /** Default behavior for goToPage, nextPage and previousPage. */
+  scrollBehavior: ScrollBehaviorKind;
+  /**
+   * Whether this view's pointer input reaches the interaction hub: a drag
+   * selects text or draws with the active tool, and the `pan` tool pans.
+   * Off, the view only scrolls (its own drag-to-pan), which suits a
+   * thumbnail strip. Without the interaction plugin the view only scrolls
+   * either way.
+   */
+  interaction: boolean;
+  /**
+   * With `interaction`: a drag in the space between pages pans whatever the
+   * tool, with a grab cursor there; there is nothing to select or draw off a
+   * page.
+   */
+  panFallback: boolean;
+  /**
+   * Whether a pinch, Ctrl+wheel (Cmd on a Mac) or a trackpad pinch zooms this
+   * view. Off, a zoom wheel scrolls instead, for a view with a fixed
+   * magnification; a pinch never zooms the browser page either way.
+   */
+  zoomGestures: boolean;
+  /**
+   * View pixels per PDF point — the platform's physical unit factor, folded into
+   * the layout so 100% (zoom 1) is physically accurate. Web = 96/72 (1 pt = 1/72",
+   * 1 CSS px = 1/96"); a native platform injects its own (iOS pt, Android dp). It
+   * scales every page's world size (and thus `contentScale`), so the camera math,
+   * `gap`/`padding`/`pageFrame` (world units), and absolute-px zoom modes
+   * (`pageWidth`) are all unaffected — only the pages themselves resize.
+   */
+  viewUnitsPerPoint: number;
+}
+/**
+ * A change to the settings: any of them, each replacing the current value
+ * whole. A `pageFrame` names only the sides it reserves (`{ bottom: 20 }`);
+ * the sides it leaves out are 0.
+ */
+interface StageSettingsPatch extends Partial<Omit<StageSettings, 'pageFrame'>> {
+  pageFrame?: Partial<PageFrame>;
+}
+/**
+ * A laid-out page handed to the shell.
+ *  - PageBox + `ref`: layout truth (world coords + identity) — the shell uses
+ *    `x/y/width/height` only to position the page container.
+ *  - `transform`: presentation truth — the single bridge between PDF points,
+ *    view px, and device px for this page. Plugins do all coordinate work
+ *    through it (`pageToView` / `viewToPage` / `deviceWidth` / `cssMatrix`),
+ *    never by re-deriving `x * scale` / `* dpr`. Page-local, so it's
+ *    camera/pan-invariant.
+ */
+interface VisiblePage extends PageBox {
+  ref: PageRef;
+  /**
+   * The page's display-box (footprint) top-left in screen px, camera-resolved and
+   * snapped to the device grid. The shell positions the page container at this —
+   * snapping here (not in the adapter) keeps a CSS-rotated page on the pixel grid
+   * for every framework, with no hand-rounding.
+   */
+  screenX: number;
+  screenY: number;
+  transform: PageTransform;
+  /**
+   * The page region actually on screen, in un-rotated page points (y-down) —
+   * viewport ∩ footprint inverted through the transform (exact for
+   * quarter-turns). Zero-sized when the page sits outside the viewport.
+   * Visibility is the stage's data (it already intersects viewport × pages to
+   * virtualize); adapters and demand consumers (tiling's `PageViewDemand`)
+   * read it instead of re-deriving camera math per framework.
+   */
+  visibleRect: Rect;
+}
+/**
+ * A page-relative view memento: "what I'm looking at and how zoomed". The durable
+ * currency for per-page view memory (construction worksheets): capture with
+ * `getViewpoint()`, restore with `goToPage(page, { viewpoint })`. Survives resizes
+ * because the anchor is page-relative and fit-modes re-resolve.
+ */
+interface Viewpoint {
+  anchor: Anchor;
+  zoom: ZoomSpec;
+}
+/** Durable, serializable view state — the unit of session persistence. */
+interface StageViewState extends StageSettings {
+  cursor: number;
+  anchor: Anchor;
+}
+/**
+ * Options for the scroller writes — `Element.scrollTo` semantics: absolute
+ * offsets (screen px) into the current scroll range (see
+ * {@link StageHostCapability.getScrollMetrics}); an omitted axis does not move.
+ * `behavior` defaults to 'instant' (the DOM's 'auto'), not the stage's
+ * `scrollBehavior` setting — that setting governs navigation verbs, and a
+ * scrollbar thumb must track the pointer exactly.
+ */
+interface StageScrollToOptions {
+  left?: number;
+  top?: number;
+  behavior?: ScrollBehaviorKind;
+}
+/** Options for `goToDestination`: the destination itself says where and how close. */
+interface GoToDestinationOptions {
+  behavior?: ScrollBehaviorKind;
+}
+/** Options for navigation intents. */
+interface GoToOptions {
+  behavior?: ScrollBehaviorKind;
+  /** Restore this exact viewpoint instead of fresh placement (per-page memory). */
+  viewpoint?: Viewpoint;
+  /** Override the landing for this navigation only (explicit beats default). */
+  arrivalAlign?: Partial<ArrivalAlignment>;
+}
+/**
+ * One axis of a reveal arrival — `scrollIntoView` vocabulary plus two
+ * PDF-protocol necessities:
+ *   absent     → minimal movement: scroll only if the target is off-screen
+ *                (CSS 'nearest', as a bare reveal does)
+ *   'keep'     → this axis does not move at all (PDF /XYZ null coordinate)
+ *   'start'    → target edge at the viewport start (plus padding)
+ *   'center'   → target centered
+ *   'end'      → target edge at the viewport end (minus padding)
+ *   number 0–1 → target center at this viewport fraction (0.35 = "top middle",
+ *                the browser find-bar feel)
+ */
+type RevealAnchorValue = 'keep' | 'start' | 'center' | 'end' | number;
+interface RevealAnchor {
+  x?: RevealAnchorValue;
+  y?: RevealAnchorValue;
+}
+/**
+ * What happens to zoom on a reveal — always relative to the reveal's target
+ * rect (the whole page when no `rect` is given):
+ *   'keep'       → pure pan, zoom untouched (search hits, /XYZ null zoom)
+ *   { level }    → explicit factor (/XYZ zoom)
+ *   'fit'        → the rect fully visible (/FitR; /Fit, /FitB via rect=page/bbox)
+ *   'fit-width'  → the rect's width fills the viewport (/FitH, /FitBH)
+ *   'fit-height' → the rect's height fills the viewport (/FitV, /FitBV)
+ */
+type RevealZoom = 'keep' | 'fit' | 'fit-width' | 'fit-height' | {
+  level: number;
+};
+/**
+ * Options for `reveal`: bring a page or a spot on it into view (a search hit,
+ * "jump to comment"). A destination goes through `goToDestination`.
+ *
+ * With none of `rect`/`zoom`/`anchor` set, a reveal is minimal movement to
+ * make the page visible, with the cursor untouched.
+ * A positioned reveal (any of the three set) is "you are now looking at
+ * this spot": the camera places the target per the anchor, a zoom
+ * directive resolves to a concrete level (recorded as the zoom intent),
+ * and the cursor follows the camera — while still clamping against the
+ * normal camera bounds, so anchors are best-effort near document edges.
+ */
+interface RevealOptions {
+  behavior?: ScrollBehaviorKind;
+  /**
+   * Target rect in page space (points from the page's top-left, y down; the
+   * space annotation, selection and search rects use).
+   * Absent or `null` → the whole page (null accepted so nullable sources flow
+   * in directly). A zero-size rect is a point.
+   */
+  rect?: Rect | null;
+  zoom?: RevealZoom;
+  anchor?: RevealAnchor;
+}
+interface StagePageChangedEvent {
+  /** The new current page, or null when the document has no pages. */
+  readonly page: PageRef | null;
+  readonly pageIndex: number;
+  readonly previousPageIndex: number;
+}
+interface StageZoomChangedEvent {
+  readonly level: number;
+  readonly previousLevel: number;
+  readonly mode: ZoomModeValue | 'custom';
+}
+interface StageCameraChangedEvent {
+  readonly camera: Camera;
+}
+interface StageMotionEndedEvent {
+  readonly camera: Camera;
+}
+interface StageSettingsChangedEvent {
+  readonly settings: StageSettings;
+  readonly changed: readonly (keyof StageSettings)[];
+}
+interface StageViewportChangedEvent {
+  readonly size: Size;
+}
+/** A viewport-space point or rect: this stage's container px, top-left origin. */
+type ViewportPoint = Point;
+type ViewportRect = Rect;
+interface ZoomToOptions {
+  /** Hold this viewport point fixed while the level changes (default: the `zoomAlign` point). */
+  readonly around?: ViewportPoint;
+}
+/**
+ * The stage's public contract: the camera, layout, zoom and navigation of one
+ * presentation of a document. Pointer and surface plumbing (viewport size,
+ * gesture brackets, fling, world space, initial placement) live on the host
+ * contract (`@embedpdf/plugin-stage/contract/host`).
+ */
+interface StageCapability {
+  /** Camera origin (world units) and zoom. */
+  getCamera(): Camera;
+  /** Write the camera directly; marks the cause as user motion. */
+  setCamera(camera: Camera): void;
+  /** The container size the stage was told about. */
+  getViewportSize(): Size;
+  /** Resolved zoom factor. */
+  getZoomLevel(): number;
+  /** The active zoom intent: a fit mode, or 'custom' for a fixed level. */
+  getZoomMode(): ZoomModeValue | 'custom';
+  /** The lens's view rotation — see {@link StageSettings.viewRotation}. */
+  getViewRotation(): PageRotation;
+  /** The current page's ref, or null before the document has pages. */
+  getCurrentPage(): PageRef | null;
+  /** The current page's display index, from 0. */
+  getCurrentPageIndex(): number;
+  /** How many pages the document has. */
+  getPageCount(): number;
+  /** Pages of the current item (one page, or a spread / grid row). */
+  listCurrentItemPages(): readonly PageInfo[];
+  /** Pages on screen, with their viewport rects and visible page-space rect. Reference-stable. */
+  listVisiblePages(): readonly VisiblePage[];
+  /** Is any part of the page (its ref or its index) on screen. False for a page that isn't in the document. */
+  isPageVisible(page: PageRef | number): boolean;
+  /** What the viewer is looking at plus the zoom intent, for per-page view memory. */
+  getViewpoint(): Viewpoint;
+  /** Serialisable view state — the unit of session persistence. */
+  getViewState(): StageViewState;
+  /** Restore a saved view state; the responsive rules re-assert on top of its settings. */
+  applyViewState(view: StageViewState): void;
+  /** A tween or fling is running. */
+  isMoving(): boolean;
+  /** Halt any running tween or fling where it is. */
+  stopMotion(): void;
+  /** Set a fixed level (a bare number) or a fit mode. */
+  zoomTo(zoom: number | ZoomSpec, options?: ZoomToOptions): void;
+  /** Multiply the zoom, holding a viewport point fixed (default: the `zoomAlign` point). */
+  zoomBy(factor: number, options?: ZoomToOptions): void;
+  /** Zoom in one step around the `zoomAlign` point. */
+  zoomIn(): void;
+  /** Zoom out one step around the `zoomAlign` point. */
+  zoomOut(): void;
+  /** Zoom so the page width fills the viewport. */
+  fitWidth(): void;
+  /** Zoom so the whole page fits the viewport. */
+  fitPage(): void;
+  /** Fit the whole scene (every page) in view. */
+  fitAll(): void;
+  /** Fit width but never upscale past 100% (Adobe's "Automatic"). */
+  fitAutomatic(): void;
+  /**
+   * Go to a page: its `PageRef`, or its display index (0 is the first page; an
+   * index past either end goes to that end). The page lands by the arrival
+   * rule; pass `viewpoint` to restore a saved spot instead.
+   */
+  goToPage(page: PageRef | number, options?: GoToOptions): void;
+  /**
+   * Go where a destination says: a link's, an outline entry's, an action's,
+   * the document's open destination, or one you build. It may change the
+   * zoom, as the destination asks. A destination another PDF tool read, in
+   * the file's numbers, converts first:
+   * `goToDestination(pageDestinationOf(destination, layout.pdfCropBox))`.
+   */
+  goToDestination(destination: PageDestination, options?: GoToDestinationOptions): void;
+  goToFirstPage(options?: GoToOptions): void;
+  goToLastPage(options?: GoToOptions): void;
+  /** Step forward / backward by the navigation unit (the item if it fits the viewport, else the page). */
+  nextPage(options?: GoToOptions): void;
+  previousPage(options?: GoToOptions): void;
+  /** The cursor is before the last page. */
+  canGoNext(): boolean;
+  /** The cursor is after the first page. */
+  canGoPrevious(): boolean;
+  /**
+   * Bring a page, or a spot on it, into view: its `PageRef` or its display
+   * index. Bare, it scrolls only when the page is off screen and leaves the
+   * current page alone. With `rect`, `zoom` or `anchor` it lands on that spot,
+   * and the current page follows.
+   */
+  reveal(page: PageRef | number, options?: RevealOptions): void;
+  /** `Element.scrollTo` / `scrollBy` for the camera, in viewport px. */
+  scrollTo(options: StageScrollToOptions): void;
+  scrollBy(options: StageScrollToOptions): void;
+  /** Pan by a viewport delta. */
+  panBy(dxViewport: number, dyViewport: number): void;
+  /** Back to the first page at the current zoom intent. */
+  resetView(): void;
+  /** Set the lens's view rotation (see {@link StageSettings.viewRotation}). */
+  setViewRotation(rotation: PageRotation): void;
+  /** Turn the view rotation a quarter clockwise (90) or counter-clockwise (-90). */
+  rotateViewBy(delta: 90 | -90): void;
+  /** Every live setting (build or save a preset). */
+  getSettings(): StageSettings;
+  /**
+   * Change any subset in one update that keeps the view on the same page.
+   * Each value replaces the current one whole; a matching responsive rule
+   * still wins on the settings it names. Fires `onSettingsChanged`.
+   */
+  updateSettings(changes: StageSettingsPatch): void;
+  /** Back to the settings the plugin was registered with. Fires `onSettingsChanged`. */
+  resetSettings(): void;
+  /** Replace the container-query rules (see {@link ResponsiveRule}). */
+  setResponsiveRules(rules: readonly ResponsiveRule[]): void;
+  /** Names of the responsive rules matching the current box, in source order. */
+  listActiveRules(): readonly string[];
+  /** Whether the named responsive rule matches the current box. */
+  matchesRule(name: string): boolean;
+  /** The page under a viewport point and the page-space point on it; null over a gap. */
+  getPageAt(point: ViewportPoint): {
+    ref: PageRef;
+    point: Point;
+    scale: number;
+    /** The hit page's total display rotation (document /Rotate + view rotation). */
+    rotation: PageRotation;
+    /** The hit page's zoom relative to its 100% baseline. */
+    zoom: number;
+  } | null;
+  /**
+   * Project a viewport point onto one page (its ref or its index), unclamped;
+   * null when the page is not on screen or not in the document.
+   */
+  viewportToPage(page: PageRef | number, point: ViewportPoint): Point | null;
+  /** A page-space point → this stage's viewport; null when the page is not laid out. */
+  pageToViewport(page: PageRef | number, point: Point): ViewportPoint | null;
+  /** A page-space rect → its viewport-space bounding box; null when the page is not laid out. */
+  pageRectToViewport(page: PageRef | number, rect: Rect): ViewportRect | null;
+  /** The laid-out box for a page (its ref or its index), on screen or not; null before placement. */
+  getPageFrame(page: PageRef | number): VisiblePage | null;
+  /** The cursor page changed. */
+  readonly onPageChanged: EventHook<StagePageChangedEvent>;
+  /** The camera's zoom level changed. */
+  readonly onZoomChanged: EventHook<StageZoomChangedEvent>;
+  /** Coalesced per camera write, not per frame. */
+  readonly onCameraChanged: EventHook<StageCameraChangedEvent>;
+  /** A tween or fling settled, or was stopped. */
+  readonly onMotionEnded: EventHook<StageMotionEndedEvent>;
+  /** One or more settings changed value; `changed` names them. */
+  readonly onSettingsChanged: EventHook<StageSettingsChangedEvent>;
+  /** The host reported a new viewport size. */
+  readonly onViewportChanged: EventHook<StageViewportChangedEvent>;
+}
+interface StageConfig extends StageSettingsPatch {
+  /**
+   * Container queries for the settings bag (see {@link ResponsiveRule}).
+   * Defaults to `DEFAULT_RESPONSIVE` (compact containers get the thin phone
+   * gutter); pass `[]` to opt out entirely.
+   */
+  responsive?: readonly ResponsiveRule[];
+}
+/**
+ * Options for registering a stage instance. The stage is a lens, not a
+ * singleton: a document may be viewed through several stages at once (the
+ * main view, a wrapped thumbnail sidebar, …), each with its own camera and
+ * settings. Register an additional lens with its own `id` and `token`:
+ *
+ *   const ThumbsToken = createCapabilityToken<StageCapability>('stage-thumbs');
+ *   plugins = [
+ *     stagePlugin(),                                                   // main lens
+ *     stagePlugin({ id: 'stage-thumbs', token: ThumbsToken,
+ *                   layout: 'grid', columns: 'auto', zoom: { level: 0.2 } }),
+ *   ];
+ *
+ * State, capabilities and teardown are keyed by plugin id × document in the
+ * kernel, so lenses never share anything.
+ */
+interface StagePluginOptions extends StageConfig {
+  id?: string;
+  token?: CapabilityToken<StageCapability>;
+}
+//#endregion
+export { StageCapability as A, StageViewportChangedEvent as B, ScrollBehaviorKind as C, SpreadMode$1 as D, SizingMode$1 as E, StageScrollToOptions as F, VisiblePage as G, Viewpoint as H, StageSettings as I, ZoomSpec$1 as J, ZoomMode as K, StageSettingsChangedEvent as L, StageMotionEndedEvent as M, StagePageChangedEvent as N, StageBox as O, StagePluginOptions as P, StageSettingsPatch as R, RevealZoom as S, Size$1 as T, ViewportPoint as U, StageZoomChangedEvent as V, ViewportRect as W, StageToken as X, ZoomToOptions as Y, Point$1 as _, ArrivalAlignValue as a, RevealAnchorValue as b, Camera$1 as c, Gap as d, GoToDestinationOptions as f, PageFrame$1 as g, LayoutKind as h, AlignmentValue$1 as i, StageConfig as j, StageCameraChangedEvent as k, Direction$1 as l, GridColumns as m, AlignValue$1 as n, ArrivalAlignment as o, GoToOptions as p, ZoomModeValue$1 as q, Alignment$1 as r, BoxQuery as s, Align as t, FlowMode as u, ResponsiveRule as v, ScrollMetrics as w, RevealOptions as x, RevealAnchor as y, StageViewState as z };
+//# sourceMappingURL=contract-DZR_jRer.d.cts.map

package/dist/contract-iSNhoXLC.cjs

@@ -0,0 +1,16 @@
+let _embedpdf_core = require("@embedpdf/core");
+require("@embedpdf/core-stage");
+//#region src/token.ts
+/** The package token, created once here; `contract.ts` re-exports it and
+*  `host-contract.ts` widens it to the host capability. Additional lenses
+*  create their own token (see `StagePluginOptions`). */
+const StageToken = (0, _embedpdf_core.createCapabilityToken)("stage", { hint: `add stagePlugin() from '@embedpdf/plugin-stage' to your plugins list` });
+//#endregion
+Object.defineProperty(exports, "StageToken", {
+	enumerable: true,
+	get: function() {
+		return StageToken;
+	}
+});
+
+//# sourceMappingURL=contract-iSNhoXLC.cjs.map

package/dist/contract-iSNhoXLC.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-iSNhoXLC.cjs","names":[],"sources":["../src/token.ts"],"sourcesContent":["/** The package token, created once here; `contract.ts` re-exports it and\n *  `host-contract.ts` widens it to the host capability. Additional lenses\n *  create their own token (see `StagePluginOptions`). */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { StageCapability } from './contract';\n\nexport const StageToken = createCapabilityToken<StageCapability>('stage', {\n  hint: `add stagePlugin() from '@embedpdf/plugin-stage' to your plugins list`,\n});\n"],"mappings":";;;;;;AAOA,MAAa,cAAA,GAAA,eAAA,sBAAA,CAAoD,SAAS,EACxE,MAAM,uEACR,CAAC"}

package/dist/contract.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-BU33R4oL.cjs");
+const require_contract = require("./contract-iSNhoXLC.cjs");
 let _embedpdf_core_stage = require("@embedpdf/core-stage");
 exports.StageToken = require_contract.StageToken;
 Object.defineProperty(exports, "ZoomMode", {

package/dist/contract.d.cts

@@ -1,3 +1,2 @@
-import { C as Viewpoint, S as StageViewState, _ as StageConfig, a as GridColumns, b as StageState, c as RevealAnchor, d as RevealZoom, f as Scheduler, g as StageCapability, h as StageBox, i as GoToOptions, l as RevealAnchorValue, m as StageAction, n as FlowMode, o as LayoutKind, p as ScrollBehaviorKind, r as Gap, s as ResponsiveRule, t as BoxQuery, u as RevealOptions, v as StageScrollToOptions, w as VisiblePage, x as StageToken, y as StageSettings } from "./types-qdO_v-V-.cjs";
-import { Align, Alignment, Direction, PageFrame, ScrollMetrics, SizingMode, SpreadMode, ZoomMode, ZoomModeValue, ZoomSpec } from "@embedpdf/core-stage";
-export { type Align, type Alignment, type BoxQuery, type Direction, type FlowMode, type Gap, type GoToOptions, type GridColumns, type LayoutKind, type PageFrame, type ResponsiveRule, type RevealAnchor, type RevealAnchorValue, type RevealOptions, type RevealZoom, type Scheduler, type ScrollBehaviorKind, type ScrollMetrics, type SizingMode, type SpreadMode, type StageAction, type StageBox, type StageCapability, type StageConfig, type StageScrollToOptions, type StageSettings, type StageState, StageToken, type StageViewState, type Viewpoint, type VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec };
+import { A as StageCapability, B as StageViewportChangedEvent, C as ScrollBehaviorKind, D as SpreadMode, E as SizingMode, F as StageScrollToOptions, G as VisiblePage, H as Viewpoint, I as StageSettings, J as ZoomSpec, K as ZoomMode, L as StageSettingsChangedEvent, M as StageMotionEndedEvent, N as StagePageChangedEvent, O as StageBox, P as StagePluginOptions, R as StageSettingsPatch, S as RevealZoom, T as Size, U as ViewportPoint, V as StageZoomChangedEvent, W as ViewportRect, X as StageToken, Y as ZoomToOptions, _ as Point, a as ArrivalAlignValue, b as RevealAnchorValue, c as Camera, d as Gap, f as GoToDestinationOptions, g as PageFrame, h as LayoutKind, i as AlignmentValue, j as StageConfig, k as StageCameraChangedEvent, l as Direction, m as GridColumns, n as AlignValue, o as ArrivalAlignment, p as GoToOptions, q as ZoomModeValue, r as Alignment, s as BoxQuery, t as Align, u as FlowMode, v as ResponsiveRule, w as ScrollMetrics, x as RevealOptions, y as RevealAnchor, z as StageViewState } from "./contract-DZR_jRer.cjs";
+export { type Align, type AlignValue, type Alignment, type AlignmentValue, ArrivalAlignValue, ArrivalAlignment, BoxQuery, type Camera, type Direction, FlowMode, Gap, GoToDestinationOptions, GoToOptions, GridColumns, LayoutKind, type PageFrame, type Point, ResponsiveRule, RevealAnchor, RevealAnchorValue, RevealOptions, RevealZoom, ScrollBehaviorKind, type ScrollMetrics, type Size, type SizingMode, type SpreadMode, StageBox, StageCameraChangedEvent, StageCapability, StageConfig, StageMotionEndedEvent, StagePageChangedEvent, StagePluginOptions, StageScrollToOptions, StageSettings, StageSettingsChangedEvent, StageSettingsPatch, StageToken, StageViewState, StageViewportChangedEvent, StageZoomChangedEvent, Viewpoint, ViewportPoint, ViewportRect, VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec, ZoomToOptions };

package/dist/contract.d.ts

@@ -1,3 +1,2 @@
-import { C as Viewpoint, S as StageViewState, _ as StageConfig, a as GridColumns, b as StageState, c as RevealAnchor, d as RevealZoom, f as Scheduler, g as StageCapability, h as StageBox, i as GoToOptions, l as RevealAnchorValue, m as StageAction, n as FlowMode, o as LayoutKind, p as ScrollBehaviorKind, r as Gap, s as ResponsiveRule, t as BoxQuery, u as RevealOptions, v as StageScrollToOptions, w as VisiblePage, x as StageToken, y as StageSettings } from "./types-CdIFKQnj.js";
-import { Align, Alignment, Direction, PageFrame, ScrollMetrics, SizingMode, SpreadMode, ZoomMode, ZoomModeValue, ZoomSpec } from "@embedpdf/core-stage";
-export { type Align, type Alignment, type BoxQuery, type Direction, type FlowMode, type Gap, type GoToOptions, type GridColumns, type LayoutKind, type PageFrame, type ResponsiveRule, type RevealAnchor, type RevealAnchorValue, type RevealOptions, type RevealZoom, type Scheduler, type ScrollBehaviorKind, type ScrollMetrics, type SizingMode, type SpreadMode, type StageAction, type StageBox, type StageCapability, type StageConfig, type StageScrollToOptions, type StageSettings, type StageState, StageToken, type StageViewState, type Viewpoint, type VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec };
+import { A as StageCapability, B as StageViewportChangedEvent, C as ScrollBehaviorKind, D as SpreadMode, E as SizingMode, F as StageScrollToOptions, G as VisiblePage, H as Viewpoint, I as StageSettings, J as ZoomSpec, K as ZoomMode, L as StageSettingsChangedEvent, M as StageMotionEndedEvent, N as StagePageChangedEvent, O as StageBox, P as StagePluginOptions, R as StageSettingsPatch, S as RevealZoom, T as Size, U as ViewportPoint, V as StageZoomChangedEvent, W as ViewportRect, X as StageToken, Y as ZoomToOptions, _ as Point, a as ArrivalAlignValue, b as RevealAnchorValue, c as Camera, d as Gap, f as GoToDestinationOptions, g as PageFrame, h as LayoutKind, i as AlignmentValue, j as StageConfig, k as StageCameraChangedEvent, l as Direction, m as GridColumns, n as AlignValue, o as ArrivalAlignment, p as GoToOptions, q as ZoomModeValue, r as Alignment, s as BoxQuery, t as Align, u as FlowMode, v as ResponsiveRule, w as ScrollMetrics, x as RevealOptions, y as RevealAnchor, z as StageViewState } from "./contract-CjHtrfJj.js";
+export { type Align, type AlignValue, type Alignment, type AlignmentValue, ArrivalAlignValue, ArrivalAlignment, BoxQuery, type Camera, type Direction, FlowMode, Gap, GoToDestinationOptions, GoToOptions, GridColumns, LayoutKind, type PageFrame, type Point, ResponsiveRule, RevealAnchor, RevealAnchorValue, RevealOptions, RevealZoom, ScrollBehaviorKind, type ScrollMetrics, type Size, type SizingMode, type SpreadMode, StageBox, StageCameraChangedEvent, StageCapability, StageConfig, StageMotionEndedEvent, StagePageChangedEvent, StagePluginOptions, StageScrollToOptions, StageSettings, StageSettingsChangedEvent, StageSettingsPatch, StageToken, StageViewState, StageViewportChangedEvent, StageZoomChangedEvent, Viewpoint, ViewportPoint, ViewportRect, VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec, ZoomToOptions };

package/dist/contract.js

@@ -1,2 +1,2 @@
-import { n as StageToken, t as ZoomMode } from "./contract-CPSX8ANN.js";
+import { n as StageToken, t as ZoomMode } from "./contract-BoOt8rJM.js";
 export { StageToken, ZoomMode };