@embedpdf/plugin-stage 3.0.0-next.1 → 3.0.0-next.10

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { CapabilityToken, PageLayout, PageObjectNumber, PdfDestination } from "@embedpdf/core";
 import { PageRotation, PageTransform, Rect } from "@embedpdf/core-geometry";
 import { Align, AlignValue, Alignment, Alignment as Alignment$1, AlignmentValue, Anchor, Camera, Direction, Direction as Direction$1, PageBox, PageFrame, PageFrame as PageFrame$1, Point, ScrollMetrics, ScrollMetrics as ScrollMetrics$1, Size, 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";
+import { InteractionCapability, InteractionHandler } from "@embedpdf/plugin-interaction";
 //#region src/types.d.ts
 type LayoutKind = 'vertical' | 'horizontal' | 'grid';
 /** Navigation (goToPage) either tweens the camera or jumps instantly. */
@@ -30,6 +31,53 @@ type GridColumns = 'square' | 'auto' | number;
 type Gap = number | {
   px: number;
 };
+/**
+ * The one environmental fact a headless stage has: the box it was told about
+ * (`setViewport`). 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 (AND-ed). */
+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 + runtime setters) ⊕ matching patches.
+ *
+ * Semantics, stated honestly:
+ *   • Runtime setters write the BASE; a matching rule wins over it. Apps
+ *     needing situational absolute control edit the rules (`setResponsive`).
+ *   • 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 (`matches(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?: Partial<StageSettings>;
+}
 /**
  * One axis of the ARRIVAL policy — stage-core's AlignValue ('start' |
  * 'center' | 'end' | viewport fraction 0–1) plus one navigation-only word:
@@ -159,7 +207,7 @@ interface StageSettings {
  *    `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`),
+ *    through it (`contentToView` / `viewToContent` / `deviceWidth` / `cssMatrix`),
  *    never by re-deriving `x * scale` / `* dpr`. Page-local, so it's
  *    camera/pan-invariant.
  */
@@ -186,6 +234,29 @@ interface VisiblePage extends PageBox {
 }
 interface StageState extends StageSettings {
   camera: Camera;
+  /**
+   * One-way render-commit latch. False while the initial viewport-driven
+   * placement is unresolved; true only after its camera/settings writes have
+   * completed. Page/scroll screen-space selectors refuse to answer while
+   * false, so an adapter can never paint the placeholder camera at the origin.
+   */
+  placed: boolean;
+  /**
+   * Names of the responsive rules currently matching the box, in source order.
+   * State (not derived) so `matches()` is reactive through the ordinary
+   * selector machinery in every framework.
+   */
+  activeRules: readonly string[];
+  /**
+   * False while the ZOOM is in motion, true once it has rested (~150ms of
+   * frames without a zoom write). Device-snapping of page origins is gated
+   * on this: a continuous zoom and a snapped origin cannot coexist without
+   * the anchor point jittering ±0.5 device px per step (the rounding lands
+   * differently every frame), so pages place fractionally while zooming and
+   * snap once at rest — when crispness actually matters. Pans always snap
+   * (a pure translation snap has no anchor error). Transient like `camera`.
+   */
+  cameraResting: boolean;
   vp: Size;
   /**
    * Device pixels per view pixel (web: `window.devicePixelRatio`). Reported by
@@ -204,6 +275,11 @@ interface StageState extends StageSettings {
 type StageAction = {
   type: 'CAMERA';
   camera: Camera;
+} | {
+  type: 'CAMERA_REST';
+  resting: boolean;
+} | {
+  type: 'PLACED';
 } | {
   type: 'VP';
   vp: Size;
@@ -216,6 +292,9 @@ type StageAction = {
 } | {
   type: 'PATCH';
   patch: Partial<StageSettings>;
+} | {
+  type: 'RESPONSIVE';
+  active: readonly string[];
 };
 /**
  * A page-relative view memento: "what I'm looking at and how zoomed". The durable
@@ -309,11 +388,13 @@ type RevealZoom = 'keep' | 'fit' | 'fit-width' | 'fit-height' | {
 interface RevealOptions {
   behavior?: ScrollBehaviorKind;
   /**
-   * CONTENT-space target rect on the page (y-down, crop-relative, unscaled
-   * points — the same space selection/search rects live in). Absent → the
-   * whole page. A zero-size rect is a point (/XYZ).
+   * Target rect on the page in the VIEWER's coordinates (y-down,
+   * crop-relative, unscaled points — the same `Rect` selection/search rects
+   * and `CommentThreadView.contentRect` live in). Absent or `null` → the
+   * whole page (null accepted so nullable sources flow in directly). A
+   * zero-size rect is a point (/XYZ).
    */
-  rect?: Rect;
+  rect?: Rect | null;
   zoom?: RevealZoom;
   anchor?: RevealAnchor;
 }
@@ -424,6 +505,45 @@ interface StageCapability {
   /** `Element.scrollBy`: relative offsets — sugar over `scrollTo`. */
   scrollBy(opts: StageScrollToOptions): void;
   zoomAround(screenPt: Point, factor: number): void;
+  /**
+   * Bracket a continuous direct-manipulation gesture (touch pan / pinch).
+   * While a gesture is open the camera writes stay cheap and visually calm:
+   * `zoomAround` defers its zoom-intent PATCH (one per gesture instead of one
+   * per event), and the camera-rest detector holds un-rested — device
+   * snapping and settle-gated rendering wait for the END of the gesture, not
+   * for a 150 ms hesitation inside it. Re-entrant (nesting counts). Opening a
+   * gesture cancels any running tween or fling — that is how a finger
+   * "catches" a moving page.
+   *
+   * `elastic` opts the gesture into RUBBER-BAND overscroll: pans past the
+   * clamp stretch on the iOS resistance curve instead of stopping dead, and
+   * ending the gesture (or a fling reaching an edge) springs the camera home
+   * on a critically-damped curve. The clamp itself stays the untouched law of
+   * REST — elasticity is a transient the gesture is allowed to hold, never a
+   * state the camera can settle in. Touch contacts pass it; mouse drags and
+   * wheel pans stay rigid (the desktop convention). Default false.
+   */
+  beginGesture(options?: {
+    elastic?: boolean;
+  }): void;
+  endGesture(): void;
+  /**
+   * Momentum scroll: keep panning from a release velocity (screen px/s, the
+   * same sign convention as `panBy` deltas), decelerating on UIScrollView's
+   * curve. Every other camera verb — including `beginGesture` from the next
+   * touch — cancels it. No-op without host frames (SSR/tests without a
+   * scheduler jump nowhere: momentum is presentation, not state).
+   */
+  fling(velocityX: number, velocityY: number): void;
+  /** True while the camera is animating (navigation tween or fling) — the
+   *  input layer reads it to tell a "catch" from a tap. */
+  cameraInMotion(): boolean;
+  /**
+   * The touch double-tap toggle: zoomed out → animate to ~2.5× the automatic
+   * fit around `screenPt`; already zoomed past that → animate back to the fit
+   * level, same focal point. Lands as a fixed zoom level either way.
+   */
+  doubleTapZoom(screenPt: Point): void;
   zoomIn(): void;
   zoomOut(): void;
   zoomTo(spec: ZoomSpec$1): void;
@@ -459,9 +579,26 @@ interface StageCapability {
   next(opts?: GoToOptions): void;
   /** Step backward by the navigation unit. */
   prev(opts?: GoToOptions): void;
+  /**
+   * This lens's identity — the stage plugin id it was registered under
+   * ('stage' for the main lens; a custom id per additional lens). The surface
+   * binding stamps it on every pointer sample (`PointerSample.source`) and
+   * lens-scoped interaction handlers register under it, so two stages on one
+   * document can never capture each other's input.
+   */
+  lensId(): string;
   /** Set any subset of settings at once — ONE anchor-preserving update. The way to
-   *  apply a customer preset: `update(myPreset)`. */
+   *  apply a customer preset: `update(myPreset)`. Writes the responsive BASE:
+   *  a matching rule's key wins until its rule stops matching. */
   update(patch: Partial<StageSettings>): void;
+  /** Replace the responsive rules (see {@link ResponsiveRule}); re-resolves
+   *  immediately with the usual anchor-preserving reactions. */
+  setResponsive(rules: readonly ResponsiveRule[]): void;
+  /** Is the named responsive rule currently matching? Reactive: recomputed
+   *  whenever the box crosses a rule boundary. */
+  matches(name: string): boolean;
+  /** Names of all currently-matching rules, in source order. */
+  activeRules(): readonly string[];
   setFlow(flow: FlowMode): void;
   setLayout(layout: LayoutKind): void;
   setSpread(spread: SpreadMode$1): void;
@@ -495,6 +632,12 @@ interface StageCapability {
 interface StageConfig extends Partial<StageSettings> {
   /** Override the host timing seam (tests/SSR). Defaults to browser rAF. */
   scheduler?: Scheduler;
+  /**
+   * 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[];
 }
 declare const StageToken: import("@embedpdf/core").CapabilityToken<StageCapability>;
 //#endregion
@@ -518,20 +661,6 @@ declare const StageToken: import("@embedpdf/core").CapabilityToken<StageCapabili
 interface StagePluginOptions extends StageConfig {
   id?: string;
   token?: CapabilityToken<StageCapability>;
-  /**
-   * Opt this lens into the interaction hub: register a tool-gated `scroll`
-   * handler (so dragging pans only in `pan` mode). Pair with `<Stage interaction>`
-   * on the React side, which forwards pointer events to the hub. Default false —
-   * secondary lenses (thumbnails) stay click-to-navigate.
-   */
-  interaction?: boolean;
-  /**
-   * When {@link interaction} is on, let drags over page GAPS pan regardless of the
-   * active tool (and show a grab cursor there) — the gutter always pans, matching
-   * v2 and the intuition that there's nothing to draw/select outside a page.
-   * On-page behaviour is untouched. Default true; ignored without `interaction`.
-   */
-  panFallback?: boolean;
 }
 /**
  * Wires the parts into a kernel plugin. This file is the "manifest": it says what
@@ -554,37 +683,28 @@ interface DestinationReveal {
  */
 declare function destinationToReveal(dest: PdfDestination, layout: PageLayout, bbox?: Rect): DestinationReveal;
 //#endregion
-//#region src/wheel.d.ts
+//#region src/scroll-handler.d.ts
+interface ScrollHandlerOptions {
+  /**
+   * Let a drag over a page GAP pan regardless of the active tool — and show a grab
+   * cursor there — so the gutter always pans (v2 parity, and the natural feel:
+   * outside a page there's nothing to draw/select on). On-page behaviour is
+   * untouched; the tool's own gesture still owns page space. Default true.
+   */
+  panFallback?: boolean;
+}
 /**
- * Wheel-input classification for ambient zoom — pure, so every framework
- * adapter shares one feel and the mapping is unit-testable.
- *
- * 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:
+ * Pan-the-camera as an interaction handler. Live under the built-in `pan` tool
+ * (the `scroll` tag) and — with `panFallback` — under every tool, where it then
+ * captures ONLY page-gap drags (on-page downs belong to the active tool, which
+ * claims them first at higher priority). It uses the sample's viewport delta, so
+ * it pans over the whole viewport (pages and gaps).
  *
- *   • 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
- *     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
- *     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.
- *
- * (Safari never synthesizes ctrl+wheel for pinch — it fires proprietary
- * gesture events with an absolute scale; that wiring lives in the adapters.)
+ * Cursor feel: a closed hand (`grabbing`) while dragging; an open hand (`grab`)
+ * hovering a gap under a non-pan tool. The pan tool's own resting `grab` comes
+ * from its `Tool.cursor`, so hovering it needs no claim here.
  */
-interface WheelSample {
-  deltaY: number;
-  /** WheelEvent.deltaMode: 0 = pixels, 1 = lines, 2 = pages. */
-  deltaMode: number;
-  ctrlKey: boolean;
-  metaKey: boolean;
-}
-/** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
-declare function wheelZoomFactor(e: WheelSample): number;
+declare function createScrollHandler(stage: StageCapability, interaction: InteractionCapability, options?: ScrollHandlerOptions): InteractionHandler;
 //#endregion
 //#region src/settings.d.ts
 /**
@@ -595,9 +715,41 @@ declare function wheelZoomFactor(e: WheelSample): number;
  * `update()`, so that taxonomy stays a customer concern.
  */
 declare const DEFAULT_SETTINGS: StageSettings;
+/**
+ * Out-of-the-box responsive rules — the platform feel with zero configuration:
+ * a compact container gets the thin gutter phones use (space, not device — an
+ * embedded 500px pane on a desktop is compact too). Override the whole list
+ * with `stagePlugin({ responsive: [...] })`; `responsive: []` opts out. The
+ * 'compact' name is queryable app-side via `stage.matches('compact')`.
+ */
+declare const DEFAULT_RESPONSIVE: readonly ResponsiveRule[];
 /** Field-by-field settings equality, derived from the registry — a new setting is
  *  covered automatically. (The React `useStageSettings` selector equality.) */
 declare const settingsEqual: (a: StageSettings, b: StageSettings) => boolean;
 //#endregion
-export { type Align, type Alignment, DEFAULT_SETTINGS, type DestinationReveal, type Direction, type FlowMode, type Gap, type GoToOptions, type GridColumns, type LayoutKind, type PageFrame, type RevealAnchor, type RevealAnchorValue, type RevealOptions, type RevealZoom, type Scheduler, type ScrollBehaviorKind, type ScrollMetrics, type SizingMode, type SpreadMode, type StageAction, type StageCapability, type StageConfig, type StagePluginOptions, type StageScrollToOptions, type StageSettings, type StageState, StageToken, type StageViewState, type Viewpoint, type VisiblePage, type WheelSample, ZoomMode, type ZoomModeValue, type ZoomSpec, destinationToReveal, settingsEqual, stagePlugin, wheelZoomFactor };
+//#region src/responsive.d.ts
+/**
+ * Container queries for the settings bag — the pure half. The capability owns
+ * the driver (when to re-resolve, how to react); the LAWS live here: what a
+ * box is, when a query matches, and what the effective settings are. No state,
+ * no dispatch — property-testable in isolation (the `wheel.ts` convention).
+ *
+ * The query vocabulary is deliberately just the box: a headless, DOM-free
+ * stage knows exactly one environmental fact — the viewport it was told.
+ * Anything else (pointer coarseness, platform, app state) is either per-event
+ * (`PointerSample.pointerType`) or the app's own business via `update()`.
+ */
+/** The reported viewport as a queryable box. A square box is 'portrait' (CSS). */
+declare const boxOf: (vp: Size) => StageBox;
+/** All bounds inclusive, all fields optional, conditions AND-ed (CSS ranges). */
+declare const matchesQuery: (q: BoxQuery, box: StageBox) => boolean;
+interface ResolvedResponsive {
+  /** base ⊕ every matching rule's patch, in source order (later wins per key). */
+  effective: StageSettings;
+  /** Names of the matching rules, in source order. */
+  active: string[];
+}
+declare const resolveResponsive: (base: StageSettings, rules: readonly ResponsiveRule[], box: StageBox) => ResolvedResponsive;
+//#endregion
+export { type Align, type Alignment, type BoxQuery, DEFAULT_RESPONSIVE, DEFAULT_SETTINGS, type DestinationReveal, 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 ScrollHandlerOptions, type ScrollMetrics, type SizingMode, type SpreadMode, type StageAction, type StageBox, type StageCapability, type StageConfig, type StagePluginOptions, type StageScrollToOptions, type StageSettings, type StageState, StageToken, type StageViewState, type Viewpoint, type VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec, boxOf, createScrollHandler, destinationToReveal, matchesQuery, resolveResponsive, settingsEqual, stagePlugin };
 //# sourceMappingURL=index.d.cts.map