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

package/README.md

@@ -15,7 +15,7 @@ move, and each one keeps exactly one thing still:
 | drag, pinch, ctrl+wheel                            | the content under your pointer | nothing — that's physics      |
 | click zoom in/out, `zoomTo`, switch to fit-width   | a focal point in the viewport  | **`zoomAlign`**               |
 | resize the container, rotate a page, change spread | the spot you were looking at   | **`anchorAlign`**             |
-| `goToPage`, next/prev, reset                       | nothing — a fresh landing      | **`arrivalAlign`**            |
+| `goToPage`, `nextPage`/`previousPage`, `resetView` | nothing — a fresh landing      | **`arrivalAlign`**            |
 | click an outline entry, a search hit, a PDF link   | whatever the call specifies    | the call itself, per-`reveal` |
 
 One more setting stands outside the table. When an axis of content **fits** the
@@ -23,7 +23,8 @@ viewport, the camera has no freedom on that axis — there is nowhere to scroll.
 **`fitAlign`** says where content rests in that case (default: centered). It is a
 standing constraint applied to _every_ move above, not a move of its own.
 
-All four settings speak the same per-axis vocabulary, and `x`/`y` are independent:
+All four settings speak the same per-axis vocabulary — `'start' | 'center' | 'end'`,
+plus a viewport fraction for the three move policies — and `x`/`y` are independent:
 
 ```ts
 stagePlugin({
@@ -39,9 +40,9 @@ want, configure nothing.)
 
 ## `arrivalAlign` — where navigation lands
 
-When you _navigate_ (`goToPage`, `next`, `prev`, reset), the target page lands at
-the same place **at every zoom level** — landing is a policy, never a side effect
-of how zoomed in you happen to be. Per axis:
+When you _navigate_ (`goToPage`, `nextPage`, `previousPage`, `resetView`), the
+target page lands at the same place **at every zoom level** — landing is a
+policy, never a side effect of how zoomed in you happen to be. Per axis:
 
 | Value      | Landing                                                                   |
 | ---------- | ------------------------------------------------------------------------- |
@@ -56,13 +57,13 @@ and last pages — exactly like a browser.
 
 One value deserves a second look: **`x: 'keep'`** — page forward without losing
 your horizontal position. Zoomed into the left column of a two-column paper,
-`next()` takes you to the left column of the next page. (It's the PDF
+`nextPage()` takes you to the left column of the next page. (It's the PDF
 `/XYZ null` semantic, as a default.)
 
 Any single navigation can override the setting:
 
 ```ts
-stage.goToPage(12, { arrivalAlign: { y: 'center' } });
+stage.goToPage(page, { arrivalAlign: { y: 'center' } });
 ```
 
 ## `zoomAlign` — what focal-less zoom zooms around
@@ -99,9 +100,9 @@ Adobe's "Rotate View": a quarter-turn applied to how **every page displays in
 this lens**, on top of each page's own `/Rotate`.
 
 ```ts
-stage.rotateView(90); // toolbar verb: one quarter-turn clockwise from here
+stage.rotateViewBy(90); // toolbar verb: one quarter-turn clockwise from here
 stage.setViewRotation(180); // absolute
-stage.viewRotation(); // 0 | 90 | 180 | 270
+stage.getViewRotation(); // 0 | 90 | 180 | 270
 stagePlugin({ viewRotation: 90 }); // or start rotated
 ```
 
@@ -146,26 +147,35 @@ stagePlugin({ arrivalAlign: { x: 'keep', y: 0.35 } });
 ```
 
 A "preset" is just an object you keep and pass — to `stagePlugin()` at setup or
-`stage.update()` at runtime. The plugin ships no named presets; that taxonomy
-belongs to your product.
+`stage.updateSettings()` at runtime. The plugin ships no named presets; that
+taxonomy belongs to your product.
 
 ## The scroller contract — scrollbars, minimaps, "% read"
 
-The Stage doubles as a **virtual scroll element**. `scrollMetrics()` projects
+The Stage doubles as a **virtual scroll element**. `getScrollMetrics()` projects
 the camera into the native DOM vocabulary — every field means exactly what it
-means on a `<div>`, in screen px:
+means on a `<div>`, in screen px. It lives on the host lens
+(`@embedpdf/plugin-stage/contract/host`), the same runtime capability typed
+wider, because a scrollbar is chrome that drives the camera:
 
 ```ts
-const m = stage.scrollMetrics();
-// m.scrollTop / m.scrollLeft       — where you are
-// m.scrollHeight / m.scrollWidth   — how much there is
-// m.clientHeight / m.clientWidth   — how much you see
-// m.scrollableY / m.scrollableX    — false = nothing to scroll (hide the bar)
+import { StageToken } from '@embedpdf/plugin-stage/contract/host';
+
+const stage = kernel.capability(StageToken);
+const metrics = stage.getScrollMetrics();
+// metrics.scrollTop / metrics.scrollLeft       — where you are
+// metrics.scrollHeight / metrics.scrollWidth   — how much there is
+// metrics.clientHeight / metrics.clientWidth   — how much you see
+// metrics.scrollableY / metrics.scrollableX    — false = nothing to scroll (hide the bar)
 
 stage.scrollTo({ top: 0 }); // Element.scrollTo semantics
-stage.scrollBy({ top: m.clientHeight * 0.9 }); // page down
+stage.scrollBy({ top: metrics.clientHeight * 0.9 }); // page down
 ```
 
+In React, `useScrollMetrics()` reads the same numbers reactively and
+`<Scrollbar axis="y" />` draws a native-feeling bar from them (both from
+`@embedpdf/react/stage`).
+
 That is the whole contract. A scrollbar thumb is
 `clientHeight / scrollHeight` of the track, positioned at
 `scrollTop / scrollHeight`; a reading-progress indicator is
@@ -179,8 +189,8 @@ a scrollbar can never disagree with where panning actually stops:
   like a longer document.
 - **Paged flow** scrolls the current item: the bar reflects one page (or
   spread), and hides when it fits.
-- **A fitting axis** reports `scrollable: false` with `scrollWidth ===
-clientWidth` — the native "no bar" condition, for free.
+- **A fitting axis** reports `scrollableX: false` (or `scrollableY`) with
+  `scrollWidth === clientWidth` — the native "no bar" condition, for free.
 - **RTL** stays physical: `scrollLeft` is the offset from the range's left
   edge, deliberately sidestepping the DOM's negative-`scrollLeft` behavior.
 
@@ -192,7 +202,7 @@ is in view, both axes report unscrollable and the bars disappear.
 
 `scrollTo`/`scrollBy` default to `behavior: 'instant'` (the DOM's `'auto'`);
 pass `'smooth'` for the camera tween. The `scrollBehavior` _setting_ is not
-consulted — it governs navigation verbs (`goToPage`, `next`), not scrolling.
+consulted — it governs navigation verbs (`goToPage`, `nextPage`), not scrolling.
 
 ## What these settings never touch
 
@@ -201,5 +211,5 @@ consulted — it governs navigation verbs (`goToPage`, `next`), not scrolling.
   outline clicks, PDF destinations — carries its own anchor and always beats the
   settings. Bare `reveal(page)` stays minimal-movement: it scrolls only as far as
   needed to make the page visible, and not a pixel further.
-- **Saved viewpoints.** `goToPage(i, { viewpoint })` restores exactly what was
+- **Saved viewpoints.** `goToPage(page, { viewpoint })` restores exactly what was
   captured.

package/dist/contract/host.cjs

@@ -0,0 +1,16 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("../contract-iSNhoXLC.cjs");
+let _embedpdf_core = require("@embedpdf/core");
+let _embedpdf_core_stage = require("@embedpdf/core-stage");
+//#region src/host-contract.ts
+const StageToken = (0, _embedpdf_core.createHostToken)(require_contract.StageToken);
+//#endregion
+exports.StageToken = StageToken;
+Object.defineProperty(exports, "ZoomMode", {
+	enumerable: true,
+	get: function() {
+		return _embedpdf_core_stage.ZoomMode;
+	}
+});
+
+//# sourceMappingURL=host.cjs.map

package/dist/contract/host.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.cjs","names":["PublicStageToken"],"sources":["../../src/host-contract.ts"],"sourcesContent":["import { createHostToken, type PageRef, type Unsubscribe } from '@embedpdf/core';\nimport type { Point, Rect } from '@embedpdf/core-geometry';\nimport type { Camera, ScrollMetrics, Size } from '@embedpdf/core-stage';\n\nimport type { StageCapability, StageViewState, ViewportPoint } from './contract';\nimport { StageToken as PublicStageToken } from './token';\n\nexport * from './contract';\nexport type { StageState } from './model';\n\n/**\n * The host lens: what the surface binding, the gesture controller and sibling\n * plugins need. The same runtime token as the public contract, typed wider.\n */\nexport interface StageHostCapability extends StageCapability {\n  /**\n   * Report the container box (ResizeObserver); the first real size triggers placement. After\n   * that, a box with no area (hidden, or taken out of the page) keeps the last real viewport.\n   */\n  setViewportSize(size: Size): void;\n  /** Report the device pixel ratio so page transforms render crisp. */\n  setDevicePixelRatio(ratio: number): void;\n  /** Bracket a direct-manipulation gesture (touch pan / pinch); `elastic` enables rubber-band. */\n  beginGesture(options?: { elastic?: boolean }): void;\n  endGesture(): void;\n  /** Momentum pan from a release velocity in viewport px/s. */\n  fling(velocityX: number, velocityY: number): void;\n  /** The touch double-tap zoom ladder around a viewport point. */\n  doubleTapZoom(point: ViewportPoint): void;\n  /** Zoom by a factor holding a viewport point fixed — the pinch primitive. */\n  zoomAround(point: ViewportPoint, factor: number): void;\n  /** The camera as a native scroller, in viewport px. Reference-stable. */\n  getScrollMetrics(): ScrollMetrics;\n  worldToViewport(world: Point): ViewportPoint;\n  viewportToWorld(point: ViewportPoint): Point;\n  pageToWorld(page: PageRef, point: Point): Point | null;\n  /** Offer a candidate initial view; the highest-priority non-null wins at placement. */\n  provideInitialView(priority: number, provider: () => StageViewState | null): Unsubscribe;\n  /** Resolve the registered providers once (else reset). Called when the viewport is ready. */\n  placeInitial(): void;\n  /** Re-resolve the zoom intent against the current scene (wired to the page registry). */\n  refit(): void;\n  /** This lens's identity — the stage plugin id; pointer samples are stamped with it. */\n  getLensId(): string;\n}\n\nexport const StageToken = createHostToken<StageHostCapability>(PublicStageToken);\nexport type { Camera, Point, Rect, ScrollMetrics, Size };\n"],"mappings":";;;;;AA8CA,MAAa,cAAA,GAAA,eAAA,gBAAA,CAAkDA,iBAAAA,UAAgB"}

package/dist/contract/host.d.cts

@@ -0,0 +1,3 @@
+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, U as ViewportPoint, V as StageZoomChangedEvent, W as ViewportRect, Y as ZoomToOptions, a as ArrivalAlignValue, b as RevealAnchorValue, 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, x as RevealOptions, y as RevealAnchor, z as StageViewState } from "../contract-DZR_jRer.cjs";
+import { a as Size, c as StageState, i as ScrollMetrics, n as Point, o as StageHostCapability, r as Rect, s as StageToken, t as Camera } from "../host-contract-CPtbnJ4j.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, type Rect, ResponsiveRule, RevealAnchor, RevealAnchorValue, RevealOptions, RevealZoom, ScrollBehaviorKind, type ScrollMetrics, type Size, type SizingMode, type SpreadMode, StageBox, StageCameraChangedEvent, StageCapability, StageConfig, StageHostCapability, StageMotionEndedEvent, StagePageChangedEvent, StagePluginOptions, StageScrollToOptions, StageSettings, StageSettingsChangedEvent, StageSettingsPatch, type StageState, StageToken, StageViewState, StageViewportChangedEvent, StageZoomChangedEvent, Viewpoint, ViewportPoint, ViewportRect, VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec, ZoomToOptions };

package/dist/contract/host.d.ts

@@ -0,0 +1,3 @@
+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, U as ViewportPoint, V as StageZoomChangedEvent, W as ViewportRect, Y as ZoomToOptions, a as ArrivalAlignValue, b as RevealAnchorValue, 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, x as RevealOptions, y as RevealAnchor, z as StageViewState } from "../contract-CjHtrfJj.js";
+import { a as Size, c as StageState, i as ScrollMetrics, n as Point, o as StageHostCapability, r as Rect, s as StageToken, t as Camera } from "../host-contract-Du5tEZ4h.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, type Rect, ResponsiveRule, RevealAnchor, RevealAnchorValue, RevealOptions, RevealZoom, ScrollBehaviorKind, type ScrollMetrics, type Size, type SizingMode, type SpreadMode, StageBox, StageCameraChangedEvent, StageCapability, StageConfig, StageHostCapability, StageMotionEndedEvent, StagePageChangedEvent, StagePluginOptions, StageScrollToOptions, StageSettings, StageSettingsChangedEvent, StageSettingsPatch, type StageState, StageToken, StageViewState, StageViewportChangedEvent, StageZoomChangedEvent, Viewpoint, ViewportPoint, ViewportRect, VisiblePage, ZoomMode, type ZoomModeValue, type ZoomSpec, ZoomToOptions };

package/dist/contract/host.js

@@ -0,0 +1,8 @@
+import { n as StageToken$1, t as ZoomMode } from "../contract-BoOt8rJM.js";
+import { createHostToken } from "@embedpdf/core";
+//#region src/host-contract.ts
+const StageToken = createHostToken(StageToken$1);
+//#endregion
+export { StageToken, ZoomMode };
+
+//# sourceMappingURL=host.js.map

package/dist/contract/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","names":["PublicStageToken"],"sources":["../../src/host-contract.ts"],"sourcesContent":["import { createHostToken, type PageRef, type Unsubscribe } from '@embedpdf/core';\nimport type { Point, Rect } from '@embedpdf/core-geometry';\nimport type { Camera, ScrollMetrics, Size } from '@embedpdf/core-stage';\n\nimport type { StageCapability, StageViewState, ViewportPoint } from './contract';\nimport { StageToken as PublicStageToken } from './token';\n\nexport * from './contract';\nexport type { StageState } from './model';\n\n/**\n * The host lens: what the surface binding, the gesture controller and sibling\n * plugins need. The same runtime token as the public contract, typed wider.\n */\nexport interface StageHostCapability extends StageCapability {\n  /**\n   * Report the container box (ResizeObserver); the first real size triggers placement. After\n   * that, a box with no area (hidden, or taken out of the page) keeps the last real viewport.\n   */\n  setViewportSize(size: Size): void;\n  /** Report the device pixel ratio so page transforms render crisp. */\n  setDevicePixelRatio(ratio: number): void;\n  /** Bracket a direct-manipulation gesture (touch pan / pinch); `elastic` enables rubber-band. */\n  beginGesture(options?: { elastic?: boolean }): void;\n  endGesture(): void;\n  /** Momentum pan from a release velocity in viewport px/s. */\n  fling(velocityX: number, velocityY: number): void;\n  /** The touch double-tap zoom ladder around a viewport point. */\n  doubleTapZoom(point: ViewportPoint): void;\n  /** Zoom by a factor holding a viewport point fixed — the pinch primitive. */\n  zoomAround(point: ViewportPoint, factor: number): void;\n  /** The camera as a native scroller, in viewport px. Reference-stable. */\n  getScrollMetrics(): ScrollMetrics;\n  worldToViewport(world: Point): ViewportPoint;\n  viewportToWorld(point: ViewportPoint): Point;\n  pageToWorld(page: PageRef, point: Point): Point | null;\n  /** Offer a candidate initial view; the highest-priority non-null wins at placement. */\n  provideInitialView(priority: number, provider: () => StageViewState | null): Unsubscribe;\n  /** Resolve the registered providers once (else reset). Called when the viewport is ready. */\n  placeInitial(): void;\n  /** Re-resolve the zoom intent against the current scene (wired to the page registry). */\n  refit(): void;\n  /** This lens's identity — the stage plugin id; pointer samples are stamped with it. */\n  getLensId(): string;\n}\n\nexport const StageToken = createHostToken<StageHostCapability>(PublicStageToken);\nexport type { Camera, Point, Rect, ScrollMetrics, Size };\n"],"mappings":";;;AA8CA,MAAa,aAAa,gBAAqCA,YAAgB"}

package/dist/contract-BoOt8rJM.js

@@ -0,0 +1,11 @@
+import { createCapabilityToken } from "@embedpdf/core";
+import { ZoomMode as ZoomMode$1 } from "@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 = createCapabilityToken("stage", { hint: `add stagePlugin() from '@embedpdf/plugin-stage' to your plugins list` });
+//#endregion
+export { StageToken as n, ZoomMode$1 as t };
+
+//# sourceMappingURL=contract-BoOt8rJM.js.map

package/dist/contract-BoOt8rJM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-BoOt8rJM.js","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,aAAa,sBAAuC,SAAS,EACxE,MAAM,uEACR,CAAC"}