@embedpdf/angular 3.0.0-next.14 → 3.0.0-next.16

package/dist/fesm2022/embedpdf-angular-stage.mjs

@@ -1,31 +1,170 @@
-import { StageToken, createScrollHandler, settingsEqual } from '@embedpdf/plugin-stage';
+import { StageToken, stageState, DEFAULT_SETTINGS, stagePlugin, createScrollHandler } from '@embedpdf/plugin-stage';
 export * from '@embedpdf/plugin-stage';
 import * as i0 from '@angular/core';
-import { inject, TemplateRef, Directive, input, computed, viewChild, Injector, ChangeDetectionStrategy, Component, contentChild, PLATFORM_ID, ElementRef, NgZone, effect } from '@angular/core';
+import { computed, Injectable, inject, TemplateRef, Directive, input, viewChild, Injector, ChangeDetectionStrategy, Component, signal, output, contentChild, PLATFORM_ID, effect, untracked, ElementRef, forwardRef, DestroyRef } from '@angular/core';
+import { injectKernelHost, CapabilityBinding, injectDocumentScope, createPageContext, EPDF_PAGE, EPDF_DOCUMENT_SCOPE, EPDF_SCOPED_SERVICES, outsideStageError } from '@embedpdf/angular/runtime';
 import { NgTemplateOutlet, isPlatformBrowser } from '@angular/common';
-import { createPageContext, EPDF_PAGE, injectKernelHost, injectOptionalCapabilityFor, injectOptionalCapability, injectDocumentId, injectOptionalSelectorFor, injectCapability, injectSelector, shallowArray } from '@embedpdf/angular/runtime';
-import { InteractionToken } from '@embedpdf/plugin-interaction/contract';
-import { createStageSurface } from '@embedpdf/web';
+import { toPageRef, shallowEqual } from '@embedpdf/core';
+import { InteractionToken } from '@embedpdf/plugin-interaction/contract/host';
+import { pageSurfaceLayout, paint, stagePageDemand, stageViewProjector, createStageSurface, scrollbarLayout, paintDefault, createScrollbarPresses } from '@embedpdf/web';
+import { EPDF_PROJECTOR } from '@embedpdf/angular/anchored';
 
 /**
- * The render-prop translation: React's `children: (page) => ReactNode` becomes
- * marker directives on `<ng-template>`, typed so `let-page` infers
- * `EpdfPageContext` in the template.
+ * `EpdfStageRef`: a Stage's API, for code that injects it. It has every method of the Stage
+ * page's Methods table, every value of its State table as a signal (`zoomLevel()`,
+ * `currentPageIndex()`, `pageCount()`), its settings as `settings()`, and its events as streams
+ * (`pageChanged$`).
+ *
+ * Inside `<epdf-stage>`, `inject(EpdfStageRef)` is that Stage: the component extends this class
+ * and provides itself under it, so its `[token]` view and its `[document]` are what you drive.
+ * Anywhere else under a viewer it drives the main view (`StageToken`) of the document in scope
+ * (`[epdfDocumentScope]`), else of the active document, as `inject(EpdfSearch)` does. Around a
+ * Stage, its template reference (`#stage="epdfStage"`) or `viewChild(EpdfStage)` reaches it.
+ *
+ * Without a document its signals read their empty values, and a method called then refuses
+ * with `not-ready`. Each method looks the view up when it's called, so it acts on the document
+ * shown at that moment.
+ */
+const NO_SCROLL = Object.freeze({
+    scrollLeft: 0,
+    scrollTop: 0,
+    scrollWidth: 0,
+    scrollHeight: 0,
+    clientWidth: 0,
+    clientHeight: 0,
+    scrollableX: false,
+    scrollableY: false,
+});
+/** The same runtime token, typed with the wider capability the Stage itself drives. */
+const asHost = (token) => token;
+class EpdfStageRef {
+    /** The viewer the view is in. */
+    host = injectKernelHost(this.usedAs());
+    /** The view, for the document in scope: inside `<epdf-stage>`, the Stage's own. */
+    binding = new CapabilityBinding(this.host, () => asHost(this.view()), injectDocumentScope());
+    /** The view it drives: the main one. `<epdf-stage>` drives the one its `[token]` names. */
+    view() {
+        return StageToken;
+    }
+    /** What an error says was used without a viewer. */
+    usedAs() {
+        return 'inject(EpdfStageRef)';
+    }
+    // ── state: the Stage page's State table, one signal per value ─────────────────
+    state = this.binding.select((stage) => stageState.read(stage), stageState.empty);
+    /** The zoom as a number: `1` is 100%. */
+    zoomLevel = computed(() => this.state().zoomLevel, ...(ngDevMode ? [{ debugName: "zoomLevel" }] : []));
+    /** The fit mode, such as `'fit-width'`, or `'custom'` after a pinch or an exact level. */
+    zoomMode = computed(() => this.state().zoomMode, ...(ngDevMode ? [{ debugName: "zoomMode" }] : []));
+    /** The current page's place in the document, from 0. */
+    currentPageIndex = computed(() => this.state().currentPageIndex, ...(ngDevMode ? [{ debugName: "currentPageIndex" }] : []));
+    /** The current page's ref, or null before the document has pages. */
+    currentPage = computed(() => this.state().currentPage, ...(ngDevMode ? [{ debugName: "currentPage" }] : []));
+    /** How many pages the document has. */
+    pageCount = computed(() => this.state().pageCount, ...(ngDevMode ? [{ debugName: "pageCount" }] : []));
+    /** How the view is turned: `0`, `90`, `180` or `270`. */
+    viewRotation = computed(() => this.state().viewRotation, ...(ngDevMode ? [{ debugName: "viewRotation" }] : []));
+    /** The names of the responsive rules that apply now, in order. */
+    activeRules = computed(() => this.state().activeRules, ...(ngDevMode ? [{ debugName: "activeRules" }] : []));
+    /** The view's settings; the defaults without a document. Change them with `updateSettings()`. */
+    settings = this.binding.select((stage) => stage.getSettings(), DEFAULT_SETTINGS);
+    /** The scroll position as a scrolling element has it, in screen pixels; all zero without a document. */
+    scrollMetrics = this.binding.select((stage) => stage.getScrollMetrics(), NO_SCROLL, Object.is);
+    // ── events, as streams ───────────────────────────────────────────────────────
+    /** Another page became the current one: `page`, `pageIndex`, `previousPageIndex`. */
+    pageChanged$ = this.binding.stream((stage) => stage.onPageChanged);
+    /** The zoom level changed: `level`, `previousLevel`, `mode`. */
+    zoomChanged$ = this.binding.stream((stage) => stage.onZoomChanged);
+    /** The view moved, on every frame of a scroll or zoom: `camera`. */
+    cameraChanged$ = this.binding.stream((stage) => stage.onCameraChanged);
+    /** Scrolling, a fling or an animated move came to rest: `camera`. */
+    motionEnded$ = this.binding.stream((stage) => stage.onMotionEnded);
+    /** The Stage itself changed size: `size`. */
+    viewportChanged$ = this.binding.stream((stage) => stage.onViewportChanged);
+    /** A setting changed, by a call or a responsive rule: `settings`, `changed`. */
+    settingsChanged$ = this.binding.stream((stage) => stage.onSettingsChanged);
+    // ── methods: the Stage page's Methods table ──────────────────────────────────
+    getCamera = this.binding.method('getCamera');
+    setCamera = this.binding.method('setCamera');
+    getViewportSize = this.binding.method('getViewportSize');
+    getZoomLevel = this.binding.method('getZoomLevel');
+    getZoomMode = this.binding.method('getZoomMode');
+    getViewRotation = this.binding.method('getViewRotation');
+    getCurrentPage = this.binding.method('getCurrentPage');
+    getCurrentPageIndex = this.binding.method('getCurrentPageIndex');
+    getPageCount = this.binding.method('getPageCount');
+    listCurrentItemPages = this.binding.method('listCurrentItemPages');
+    listVisiblePages = this.binding.method('listVisiblePages');
+    isPageVisible = this.binding.method('isPageVisible');
+    getViewpoint = this.binding.method('getViewpoint');
+    getViewState = this.binding.method('getViewState');
+    applyViewState = this.binding.method('applyViewState');
+    isMoving = this.binding.method('isMoving');
+    stopMotion = this.binding.method('stopMotion');
+    zoomTo = this.binding.method('zoomTo');
+    zoomBy = this.binding.method('zoomBy');
+    zoomIn = this.binding.method('zoomIn');
+    zoomOut = this.binding.method('zoomOut');
+    fitWidth = this.binding.method('fitWidth');
+    fitPage = this.binding.method('fitPage');
+    fitAll = this.binding.method('fitAll');
+    fitAutomatic = this.binding.method('fitAutomatic');
+    goToPage = this.binding.method('goToPage');
+    goToDestination = this.binding.method('goToDestination');
+    goToFirstPage = this.binding.method('goToFirstPage');
+    goToLastPage = this.binding.method('goToLastPage');
+    nextPage = this.binding.method('nextPage');
+    previousPage = this.binding.method('previousPage');
+    canGoNext = this.binding.method('canGoNext');
+    canGoPrevious = this.binding.method('canGoPrevious');
+    reveal = this.binding.method('reveal');
+    scrollTo = this.binding.method('scrollTo');
+    scrollBy = this.binding.method('scrollBy');
+    panBy = this.binding.method('panBy');
+    resetView = this.binding.method('resetView');
+    setViewRotation = this.binding.method('setViewRotation');
+    rotateViewBy = this.binding.method('rotateViewBy');
+    getSettings = this.binding.method('getSettings');
+    updateSettings = this.binding.method('updateSettings');
+    resetSettings = this.binding.method('resetSettings');
+    setResponsiveRules = this.binding.method('setResponsiveRules');
+    listActiveRules = this.binding.method('listActiveRules');
+    matchesRule = this.binding.method('matchesRule');
+    getPageAt = this.binding.method('getPageAt');
+    viewportToPage = this.binding.method('viewportToPage');
+    pageToViewport = this.binding.method('pageToViewport');
+    pageRectToViewport = this.binding.method('pageRectToViewport');
+    getPageFrame = this.binding.method('getPageFrame');
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfStageRef, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfStageRef, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfStageRef, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+function withStage(options) {
+    return { plugins: [stagePlugin(options)], services: [EpdfStageRef] };
+}
+
+/**
+ * The templates a Stage draws each page with. React's page function becomes a marker directive
+ * on an `<ng-template>`, typed so `let-page` is the page context:
  *
  *   <epdf-stage>
- *     <ng-template epdfPage>            page-space content (rotates)
- *     <ng-template epdfPageChrome>      box-space chrome (never rotates)
+ *     <ng-template epdfPage>              on the page: turns with it (layers)
+ *     <ng-template epdfPageChrome>        around the page: never turns (labels, buttons)
  *
- * The `$implicit` context is the SAME stable object the per-page injector
- * provides as `EPDF_PAGE` — `let-page` is sugar for inline chrome; components
- * inside the template just call `injectPage()`.
+ * `let-page` is the same context a component inside the template gets from `injectPage()`.
+ */
+/**
+ * What each visible page draws: the render layer, text selection, annotations, your markers.
+ * It sits in the page's content box and turns with the page, so positions in it are page
+ * coordinates.
  */
-/** PAGE-SPACE content for each visible page (RenderLayer, annotations,
- *  markers). Rendered inside the page's content frame, so it ROTATES with the
- *  page's display rotation — coordinates are plain PDF points. */
 class EpdfPageTemplate {
     template = inject(TemplateRef);
-    static ngTemplateContextGuard(_dir, ctx) {
+    static ngTemplateContextGuard(_directive, context) {
         return true;
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfPageTemplate, deps: [], target: i0.ɵɵFactoryTarget.Directive });
@@ -33,15 +172,16 @@ class EpdfPageTemplate {
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfPageTemplate, decorators: [{
             type: Directive,
-            args: [{ selector: 'ng-template[epdfPage]', standalone: true }]
+            args: [{ selector: 'ng-template[epdfPage]' }]
         }] });
-/** BOX-SPACE chrome for each visible page (page-number label, selection
- *  border, per-page buttons). Rendered into the OUTER box (content + reserved
- *  `pageFrame`), so it does NOT rotate and the reserved bands are plain
- *  regions (`bottom: 0; height: page.frame().bottom`). */
+/**
+ * What goes around each visible page: a page number, a border, a row of buttons. It fills the
+ * page's box with the bands `pageFrame` reserves, and never turns, so a label in the bottom
+ * band is `bottom: 0` with `[style.height.px]="page.frame().bottom"`.
+ */
 class EpdfPageChrome {
     template = inject(TemplateRef);
-    static ngTemplateContextGuard(_dir, ctx) {
+    static ngTemplateContextGuard(_directive, context) {
         return true;
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfPageChrome, deps: [], target: i0.ɵɵFactoryTarget.Directive });
@@ -49,96 +189,103 @@ class EpdfPageChrome {
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfPageChrome, decorators: [{
             type: Directive,
-            args: [{ selector: 'ng-template[epdfPageChrome]', standalone: true }]
+            args: [{ selector: 'ng-template[epdfPageChrome]' }]
         }] });
 
 /**
- * INTERNAL page shell — one per visible page, tracked by `pon` so the instance
- * (and everything below) survives camera motion and page reorders.
+ * One page on a Stage: its box, its shadow, its turned content, and the page and chrome
+ * templates drawn into them. The Stage tracks surfaces by the page's object number, so a
+ * surface (and every layer in it) lives while its page is on screen, through camera moves and
+ * page reorders.
  *
- * THE STABILITY INVARIANT (see page-context.ts): `page` (the context) and
- * `pageInjector` are created ONCE per surface. Camera frames arrive as new
- * `vp` input values; only the signals inside the context change. Changing the
- * injector or context object identity would make `NgTemplateOutlet` recreate
- * the embedded views — destroying layers at 120Hz. Don't.
+ * The page context and the injector that provides it are made once per surface; camera frames
+ * arrive as new `visiblePage` input values and change only the signals inside the context. A
+ * new context or injector would make the template outlet recreate every layer on every frame.
  *
- * Geometry mirrors React's PageSurface: the outer box = content footprint +
- * reserved chrome bands; the shadow is axis-aligned and stays put under
- * rotation; the content wrapper is the ONLY thing rotation turns, and carries
- * no transform at rotation 0 so it pixel-snaps like the shadow behind it.
- * All numbers come from the transform — never re-derive `* zoom` / `* dpr`.
+ * The geometry is every framework's (`pageSurfaceLayout` from `@embedpdf/web`): the outer box
+ * is the page's footprint plus the reserved chrome bands; the shadow is axis-aligned and stays
+ * put when the page turns; only the content box turns, and at rotation 0 it carries no
+ * transform, so it snaps to pixels like the shadow behind it. Every number comes from the page
+ * transform.
  */
 class EpdfPageSurface {
-    vp = input.required(...(ngDevMode ? [{ debugName: "vp" }] : []));
+    visiblePage = input.required(...(ngDevMode ? [{ debugName: "visiblePage" }] : []));
+    /** The bands reserved around the page, in screen pixels. */
     frame = input.required(...(ngDevMode ? [{ debugName: "frame" }] : []));
     documentId = input.required(...(ngDevMode ? [{ debugName: "documentId" }] : []));
-    pageTpl = input.required(...(ngDevMode ? [{ debugName: "pageTpl" }] : []));
-    chromeTpl = input(null, ...(ngDevMode ? [{ debugName: "chromeTpl" }] : []));
-    t = computed(() => this.vp().transform, ...(ngDevMode ? [{ debugName: "t" }] : []));
-    // Outer box = display footprint + reserved chrome bands; screenX/screenY are
-    // the device-snapped footprint top-left, so the box sits one frame further out.
-    left = computed(() => this.vp().screenX - this.frame().left, ...(ngDevMode ? [{ debugName: "left" }] : []));
-    top = computed(() => this.vp().screenY - this.frame().top, ...(ngDevMode ? [{ debugName: "top" }] : []));
-    outerWidth = computed(() => this.t().viewWidth + this.frame().left + this.frame().right, ...(ngDevMode ? [{ debugName: "outerWidth" }] : []));
-    outerHeight = computed(() => this.t().viewHeight + this.frame().top + this.frame().bottom, ...(ngDevMode ? [{ debugName: "outerHeight" }] : []));
-    // Center the (possibly rotated) content box on the display box and rotate
-    // about its center — NO translate(), so rotation 0 carries no transform.
-    contentLeft = computed(() => this.frame().left + (this.t().viewWidth - this.t().contentWidth) / 2, ...(ngDevMode ? [{ debugName: "contentLeft" }] : []));
-    contentTop = computed(() => this.frame().top + (this.t().viewHeight - this.t().contentHeight) / 2, ...(ngDevMode ? [{ debugName: "contentTop" }] : []));
-    rotate = computed(() => {
-        const rotation = this.vp().rotation;
-        return rotation ? `rotate(${rotation}deg)` : null;
-    }, ...(ngDevMode ? [{ debugName: "rotate" }] : []));
-    contentEl = viewChild.required('content');
-    /** ONE stable context per surface — volatile parts are signals inside it. */
+    /** The Stage's view; the tile demand reads what's on screen from it when asked. */
+    stage = input.required(...(ngDevMode ? [{ debugName: "stage" }] : []));
+    /** The viewer's `page` settings: the background and the shadow. */
+    look = input.required(...(ngDevMode ? [{ debugName: "look" }] : []));
+    pageTemplate = input.required(...(ngDevMode ? [{ debugName: "pageTemplate" }] : []));
+    chromeTemplate = input(null, ...(ngDevMode ? [{ debugName: "chromeTemplate" }] : []));
+    transform = computed(() => this.visiblePage().transform, ...(ngDevMode ? [{ debugName: "transform" }] : []));
+    // The outer box, the shadow and the turned content box, from `@embedpdf/web`'s layout, shared
+    // by every framework; screenX/screenY are the footprint's device-snapped corner.
+    layout = computed(() => {
+        const visiblePage = this.visiblePage();
+        return pageSurfaceLayout(this.transform(), this.frame(), {
+            x: visiblePage.screenX,
+            y: visiblePage.screenY,
+        });
+    }, ...(ngDevMode ? [{ debugName: "layout" }] : []));
+    // The settings, unless CSS sets `--epdf-page-shadow` or `--epdf-page-background`.
+    shadow = computed(() => paint('page-shadow', this.look().shadow), ...(ngDevMode ? [{ debugName: "shadow" }] : []));
+    background = computed(() => paint('page-background', this.look().background), ...(ngDevMode ? [{ debugName: "background" }] : []));
+    content = viewChild.required('content');
+    pageRef = null;
+    /** The page context, one for the surface's lifetime. */
     page = createPageContext({
         documentId: () => this.documentId(),
-        pon: () => this.vp().pon,
-        pageIndex: computed(() => this.vp().pageIndex),
+        // The Stage builds a new ref each frame; the surface keeps the first, so layers can key
+        // their work on it.
+        ref: () => (this.pageRef ??= toPageRef(this.visiblePage().ref.objectNumber)),
+        view: () => this.stage().getLensId(),
+        pageIndex: computed(() => this.visiblePage().pageIndex),
         frame: this.frame,
-        transform: this.t,
-        getRect: () => this.contentEl().nativeElement.getBoundingClientRect(),
+        transform: this.transform,
+        getRect: () => this.content().nativeElement.getBoundingClientRect(),
+        // Read live from the Stage: off screen, the page wants nothing (an empty rect).
+        getViewDemand: () => stagePageDemand(this.stage(), this.visiblePage().ref.objectNumber, this.transform().deviceWidth),
     });
-    /** ONE stable injector per surface (see the invariant above), parented to
-     *  this surface's node injector so layers also reach the kernel host. */
+    /** One injector for the surface's lifetime, under this surface, so layers reach the viewer too. */
     pageInjector = Injector.create({
         providers: [{ provide: EPDF_PAGE, useValue: this.page }],
         parent: inject(Injector),
     });
     templateContext = { $implicit: this.page };
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfPageSurface, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.2.4", type: EpdfPageSurface, isStandalone: true, selector: "epdf-page-surface", inputs: { vp: { classPropertyName: "vp", publicName: "vp", isSignal: true, isRequired: true, transformFunction: null }, frame: { classPropertyName: "frame", publicName: "frame", isSignal: true, isRequired: true, transformFunction: null }, documentId: { classPropertyName: "documentId", publicName: "documentId", isSignal: true, isRequired: true, transformFunction: null }, pageTpl: { classPropertyName: "pageTpl", publicName: "pageTpl", isSignal: true, isRequired: true, transformFunction: null }, chromeTpl: { classPropertyName: "chromeTpl", publicName: "chromeTpl", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "style.left.px": "left()", "style.top.px": "top()", "style.width.px": "outerWidth()", "style.height.px": "outerHeight()" }, styleAttribute: "position: absolute; display: block;" }, viewQueries: [{ propertyName: "contentEl", first: true, predicate: ["content"], descendants: true, isSignal: true }], ngImport: i0, template: `
-    <!-- drop shadow ONLY — axis-aligned at the content box (inset by the frame),
-         transparent fill so it can never peek out behind the bitmap, and it
-         stays put under rotation. -->
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.2.4", type: EpdfPageSurface, isStandalone: true, selector: "epdf-page-surface", inputs: { visiblePage: { classPropertyName: "visiblePage", publicName: "visiblePage", isSignal: true, isRequired: true, transformFunction: null }, frame: { classPropertyName: "frame", publicName: "frame", isSignal: true, isRequired: true, transformFunction: null }, documentId: { classPropertyName: "documentId", publicName: "documentId", isSignal: true, isRequired: true, transformFunction: null }, stage: { classPropertyName: "stage", publicName: "stage", isSignal: true, isRequired: true, transformFunction: null }, look: { classPropertyName: "look", publicName: "look", isSignal: true, isRequired: true, transformFunction: null }, pageTemplate: { classPropertyName: "pageTemplate", publicName: "pageTemplate", isSignal: true, isRequired: true, transformFunction: null }, chromeTemplate: { classPropertyName: "chromeTemplate", publicName: "chromeTemplate", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "style.left.px": "layout().outer.left", "style.top.px": "layout().outer.top", "style.width.px": "layout().outer.width", "style.height.px": "layout().outer.height" }, styleAttribute: "position: absolute; display: block;" }, viewQueries: [{ propertyName: "content", first: true, predicate: ["content"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    <!-- The shadow only: axis-aligned at the content box, with no fill that could show behind
+         the picture, and it stays put when the page turns. -->
     <div
-      style="position: absolute; box-shadow: var(--epdf-page-shadow, 0 6px 18px rgba(0, 0, 0, 0.18));"
-      [style.left.px]="frame().left"
-      [style.top.px]="frame().top"
-      [style.width.px]="t().viewWidth"
-      [style.height.px]="t().viewHeight"
+      style="position: absolute"
+      [style.left.px]="layout().shadow.left"
+      [style.top.px]="layout().shadow.top"
+      [style.width.px]="layout().shadow.width"
+      [style.height.px]="layout().shadow.height"
+      [style.box-shadow]="shadow()"
     ></div>
-    <!-- the page: white backing + content as ONE box — the only thing rotation
-         turns. We render our own selection highlights, so native selection is
-         suppressed on the whole page subtree. -->
+    <!-- The page: its background and content as one box, the only thing that turns. The layers
+         draw their own selection, so the browser's is off for the whole page. -->
     <div
       #content
-      style="position: absolute; background: #fff; user-select: none; -webkit-user-select: none;"
-      [style.left.px]="contentLeft()"
-      [style.top.px]="contentTop()"
-      [style.width.px]="t().contentWidth"
-      [style.height.px]="t().contentHeight"
-      [style.transform]="rotate()"
+      style="position: absolute; user-select: none; -webkit-user-select: none"
+      [style.left.px]="layout().content.left"
+      [style.top.px]="layout().content.top"
+      [style.width.px]="layout().content.width"
+      [style.height.px]="layout().content.height"
+      [style.background]="background()"
+      [style.transform]="layout().turn"
     >
       <ng-container
-        [ngTemplateOutlet]="pageTpl()"
+        [ngTemplateOutlet]="pageTemplate()"
         [ngTemplateOutletContext]="templateContext"
         [ngTemplateOutletInjector]="pageInjector"
       />
     </div>
-    <!-- box-space chrome — fills the outer box, NEVER rotates. Bands are plain
-         regions: a label is bottom: 0; height: frame().bottom. -->
-    @if (chromeTpl(); as chrome) {
+    <!-- Around the page: fills the outer box, never turns. -->
+    @if (chromeTemplate(); as chrome) {
       <ng-container
         [ngTemplateOutlet]="chrome"
         [ngTemplateOutletContext]="templateContext"
@@ -151,48 +298,46 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImpor
             type: Component,
             args: [{
                     selector: 'epdf-page-surface',
-                    standalone: true,
                     imports: [NgTemplateOutlet],
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     host: {
                         style: 'position: absolute; display: block;',
-                        '[style.left.px]': 'left()',
-                        '[style.top.px]': 'top()',
-                        '[style.width.px]': 'outerWidth()',
-                        '[style.height.px]': 'outerHeight()',
+                        '[style.left.px]': 'layout().outer.left',
+                        '[style.top.px]': 'layout().outer.top',
+                        '[style.width.px]': 'layout().outer.width',
+                        '[style.height.px]': 'layout().outer.height',
                     },
                     template: `
-    <!-- drop shadow ONLY — axis-aligned at the content box (inset by the frame),
-         transparent fill so it can never peek out behind the bitmap, and it
-         stays put under rotation. -->
+    <!-- The shadow only: axis-aligned at the content box, with no fill that could show behind
+         the picture, and it stays put when the page turns. -->
     <div
-      style="position: absolute; box-shadow: var(--epdf-page-shadow, 0 6px 18px rgba(0, 0, 0, 0.18));"
-      [style.left.px]="frame().left"
-      [style.top.px]="frame().top"
-      [style.width.px]="t().viewWidth"
-      [style.height.px]="t().viewHeight"
+      style="position: absolute"
+      [style.left.px]="layout().shadow.left"
+      [style.top.px]="layout().shadow.top"
+      [style.width.px]="layout().shadow.width"
+      [style.height.px]="layout().shadow.height"
+      [style.box-shadow]="shadow()"
     ></div>
-    <!-- the page: white backing + content as ONE box — the only thing rotation
-         turns. We render our own selection highlights, so native selection is
-         suppressed on the whole page subtree. -->
+    <!-- The page: its background and content as one box, the only thing that turns. The layers
+         draw their own selection, so the browser's is off for the whole page. -->
     <div
       #content
-      style="position: absolute; background: #fff; user-select: none; -webkit-user-select: none;"
-      [style.left.px]="contentLeft()"
-      [style.top.px]="contentTop()"
-      [style.width.px]="t().contentWidth"
-      [style.height.px]="t().contentHeight"
-      [style.transform]="rotate()"
+      style="position: absolute; user-select: none; -webkit-user-select: none"
+      [style.left.px]="layout().content.left"
+      [style.top.px]="layout().content.top"
+      [style.width.px]="layout().content.width"
+      [style.height.px]="layout().content.height"
+      [style.background]="background()"
+      [style.transform]="layout().turn"
     >
       <ng-container
-        [ngTemplateOutlet]="pageTpl()"
+        [ngTemplateOutlet]="pageTemplate()"
         [ngTemplateOutletContext]="templateContext"
         [ngTemplateOutletInjector]="pageInjector"
       />
     </div>
-    <!-- box-space chrome — fills the outer box, NEVER rotates. Bands are plain
-         regions: a label is bottom: 0; height: frame().bottom. -->
-    @if (chromeTpl(); as chrome) {
+    <!-- Around the page: fills the outer box, never turns. -->
+    @if (chromeTemplate(); as chrome) {
       <ng-container
         [ngTemplateOutlet]="chrome"
         [ngTemplateOutletContext]="templateContext"
@@ -204,239 +349,494 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImpor
         }] });
 
 /**
- * `<epdf-stage>` — virtualizes and positions page surfaces by the camera, and
- * stamps each one with YOUR `<ng-template epdfPage>` — you bring the layers.
+ * `<epdf-stage>`: shows the document's pages. It lays them out, keeps only the visible ones
+ * mounted, handles scrolling, zoom and page navigation by mouse, keyboard and touch, and draws
+ * each page with your `<ng-template epdfPage>`.
  *
- * NULL-SAFE BY DESIGN (a deliberate deviation from React's strict Stage):
- * Angular instantiates projected content eagerly, so a stage constructed
- * before any document exists must not crash — it renders zero pages and its
- * listeners no-op until the document arrives. Teach the document gate anyway:
- * document CHROME (toolbars, panels) still belongs behind `*epdfDocumentGate`.
+ * The component is the Stage's API, `EpdfStageRef`'s (`stage-ref.ts`): every method of the
+ * Stage page's Methods table, every value of its State table as a signal, its settings as
+ * `settings()`, and its events as streams (`pageChanged$`). From around it, a template reference
+ * (`<epdf-stage #stage="epdfStage">`, then `stage.zoomIn()` and `stage.zoomLevel()`) or
+ * `viewChild(EpdfStage)` reaches it; from inside it, `inject(EpdfStageRef)`. `[(page)]` and
+ * `[(zoom)]` bind the current page index and the zoom level.
  *
- * ZONE RULE: every DOM listener here attaches OUTSIDE Angular's zone — a
- * 120Hz pointermove stream must never trigger app-wide change detection.
- * State flows kernel → tick signal → computeds → bindings, so the adapter is
- * zone-agnostic (zoneless recommended, zone.js tolerated).
+ * `[document]` opens a document for this Stage and follows the value: a new source opens, the
+ * old document closes. `[token]` makes it a second view, registered with `withStage({ token })`.
+ *
+ * Without a document it shows no pages and its signals read their empty values; a method
+ * called then refuses with `not-ready`.
+ */
+const NO_PAGES = Object.freeze([]);
+const NO_FRAME = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
+const frameEqual = (left, right) => left.top === right.top &&
+    left.right === right.right &&
+    left.bottom === right.bottom &&
+    left.left === right.left;
+/**
+ * The document a Stage shows: the one its `[document]` opened, else its scope's. The Stage and
+ * what's inside it read it, so it's made before the Stage itself.
  */
-const EMPTY_PAGES = [];
-const NO_FRAME = { top: 0, right: 0, bottom: 0, left: 0 };
-const frameEqual = (a, b) => a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
-class EpdfStage {
+class StageDocument {
+    parent = inject(EPDF_DOCUMENT_SCOPE, { optional: true, skipSelf: true });
+    /** The document `[document]` opened, once it has its id. */
+    opened = signal(null, ...(ngDevMode ? [{ debugName: "opened" }] : []));
+    id = computed(() => this.opened() ?? this.parent?.id() ?? null, ...(ngDevMode ? [{ debugName: "id" }] : []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: StageDocument, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: StageDocument });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: StageDocument, decorators: [{
+            type: Injectable
+        }] });
+class EpdfStage extends EpdfStageRef {
+    /** The view to drive: a token registered with `withStage({ token })`; the main view without one. */
+    token = input(undefined, ...(ngDevMode ? [{ debugName: "token" }] : []));
+    /** A document to open for this Stage. A new value opens it and closes the one before. */
+    document = input(undefined, ...(ngDevMode ? [{ debugName: "document" }] : []));
+    /** The current page's index, from 0: `[(page)]`. Setting it goes to that page. */
+    page = input(undefined, ...(ngDevMode ? [{ debugName: "page" }] : []));
+    /** Another page became the current one: its index. The output half of `[(page)]`. */
+    pageChange = output();
+    /** The zoom level, `1` for 100%: `[(zoom)]`. Setting it zooms there. */
+    zoom = input(undefined, ...(ngDevMode ? [{ debugName: "zoom" }] : []));
+    /** The zoom level changed. The output half of `[(zoom)]`. */
+    zoomChange = output();
+    ownDocument = inject(StageDocument);
+    /** The document this Stage shows, for what's inside it: its own `[document]`, else its scope's. */
+    documentScope = this.ownDocument;
+    /** The view's capability, or null without a document. */
+    hostCapability = this.binding.capability;
+    view() {
+        return this.token() ?? StageToken;
+    }
+    usedAs() {
+        return '<epdf-stage>';
+    }
+    // ── what the template draws ──────────────────────────────────────────────────
+    /** The pages on screen, each with its place and transform: a new list every camera frame. */
+    pages = this.binding.select((stage) => stage.listVisiblePages(), NO_PAGES, Object.is);
+    frame = this.binding.select((stage) => stage.getSettings().pageFrame, NO_FRAME, frameEqual);
+    documentId = this.host.read((kernel) => this.documentScope.id() ?? kernel.documents.getActiveId(), () => null);
+    /** The viewer's `page` settings: each page's background and shadow. */
+    look = computed(() => this.host.viewerSettings().page, ...(ngDevMode ? [{ debugName: "look", equal: shallowEqual }] : [{
+            equal: shallowEqual,
+        }]));
+    pageTemplateDirective = contentChild(EpdfPageTemplate, ...(ngDevMode ? [{ debugName: "pageTemplateDirective" }] : []));
+    chromeTemplateDirective = contentChild(EpdfPageChrome, ...(ngDevMode ? [{ debugName: "chromeTemplateDirective" }] : []));
+    // Typed, so the built declarations name `EpdfPageTemplateContext` from this file instead of
+    // importing this entry point by its own package name.
+    pageTemplate = computed(() => this.pageTemplateDirective()?.template ?? null, ...(ngDevMode ? [{ debugName: "pageTemplate" }] : []));
+    chromeTemplate = computed(() => this.chromeTemplateDirective()?.template ?? null, ...(ngDevMode ? [{ debugName: "chromeTemplate" }] : []));
+    // ── input ────────────────────────────────────────────────────────────────────
+    // How this view takes pointer input is its own settings: a change binds the surface again.
+    interaction = this.binding.select((stage) => stage.getSettings().interaction, true);
+    panFallback = this.binding.select((stage) => stage.getSettings().panFallback, true);
+    zoomGestures = this.binding.select((stage) => stage.getSettings().zoomGestures, true);
+    /** The interaction hub of this Stage's document: the active tool takes the pointer. */
+    hub = new CapabilityBinding(this.host, () => InteractionToken, this.documentScope.id).capability;
+    usesHub = computed(() => this.interaction() && this.hub() !== null, ...(ngDevMode ? [{ debugName: "usesHub" }] : []));
+    hubCursor = this.host.read(() => this.hub()?.getCursor() ?? 'default', () => 'default');
+    /** The hub's cursor (text, grab, a tool's own), while the hub takes this Stage's pointer. */
+    cursor = computed(() => (this.usesHub() ? this.hubCursor() : null), ...(ngDevMode ? [{ debugName: "cursor" }] : []));
+    // ── anchored UI ──────────────────────────────────────────────────────────────
     /**
-     * Route this Stage's pointer events to the interaction hub (page-resolved via
-     * `pageAt`) — AND register this lens's tool-gated pan-scroll handler with it
-     * (lens-scoped, so multiple stages on one document never pan each other).
-     * Pan is then the `pan` tool's job and dragging in `pointer` mode selects
-     * text (incl. across pages).
-     *
-     * Default TRUE: registering `interactionPlugin()` is the one opt-in — tools
-     * just work; without the hub this is inert and the stage falls back to
-     * built-in drag-to-pan, so a hub-less setup costs nothing. Set `false` on
-     * SECONDARY lenses (a thumbnail rail) that should stay click-to-navigate
-     * instead of feeding the document's tools.
+     * How anchored UI (`<epdf-anchored>`) inside the Stage follows the camera: a projection
+     * through the view, and the visible pages as its revision, so the pages and the UI on them
+     * update in the same change detection pass and never a frame apart.
      */
-    interaction = input(true, ...(ngDevMode ? [{ debugName: "interaction" }] : []));
+    projection = {
+        // `@embedpdf/web`'s Stage projection, shared by every framework: page boxes to the Stage's
+        // own coordinates.
+        projector: computed(() => {
+            const stage = this.hostCapability();
+            return stage ? stageViewProjector(() => stage) : null;
+        }),
+        revision: this.pages,
+        shownPages: computed(() => {
+            const shown = this.pages().map((visible) => visible.ref.objectNumber);
+            return new Set(shown);
+        }, 
+        // The same set until a page comes on screen or leaves it.
+        {
+            equal: (left, right) => left.size === right.size && [...left].every((objectNumber) => right.has(objectNumber)),
+        }),
+    };
+    constructor() {
+        super();
+        this.followDocumentInput();
+        this.followPageAndZoom();
+        if (isPlatformBrowser(inject(PLATFORM_ID)))
+            this.bindSurface();
+    }
+    /** `[document]`: open it for this Stage once the viewer runs; close it when the value changes. */
+    followDocumentInput() {
+        effect((onCleanup) => {
+            const source = this.document();
+            const kernel = this.host.kernel();
+            if (!source || !kernel || this.host.status() !== 'ready')
+                return;
+            untracked(() => {
+                const cancel = new AbortController();
+                const opening = kernel.documents.open(source, { signal: cancel.signal });
+                // The new tab is the active one at once; its id is final when the open resolves.
+                let id = kernel.documents.getActiveId();
+                opening.then(({ document }) => {
+                    id = document.id;
+                    if (!cancel.signal.aborted)
+                        this.ownDocument.opened.set(document.id);
+                }, () => {
+                    // Its tab shows why it couldn't be opened.
+                });
+                onCleanup(() => {
+                    cancel.abort();
+                    this.ownDocument.opened.set(null);
+                    if (id && kernel.documents.has(id))
+                        void kernel.documents.close(id).catch(() => { });
+                });
+            });
+        });
+    }
     /**
-     * With `interaction`: let drags over page GAPS pan regardless of the active
-     * tool (and show a grab cursor there) — the gutter always pans; there is
-     * nothing to draw/select outside a page. Default true.
+     * `[(page)]` and `[(zoom)]`. A value from the parent moves the view there; a move of the view
+     * (scroll, pinch, a button) goes out as `pageChange` and `zoomChange`. When the Stage changes
+     * documents (another tab), the new document keeps its own place and reports it.
      */
-    panFallback = input(true, ...(ngDevMode ? [{ debugName: "panFallback" }] : []));
+    followPageAndZoom() {
+        let previous = null;
+        effect(() => {
+            const stage = this.hostCapability();
+            const page = this.page();
+            const zoom = this.zoom();
+            untracked(() => {
+                const switched = previous !== null && stage !== null && stage !== previous;
+                previous = stage;
+                if (!stage)
+                    return;
+                if (switched) {
+                    if (page !== undefined && page !== stage.getCurrentPageIndex()) {
+                        this.pageChange.emit(stage.getCurrentPageIndex());
+                    }
+                    if (zoom !== undefined && zoom !== stage.getZoomLevel()) {
+                        this.zoomChange.emit(stage.getZoomLevel());
+                    }
+                    return;
+                }
+                if (page !== undefined && page !== stage.getCurrentPageIndex())
+                    stage.goToPage(page);
+                if (zoom !== undefined && zoom !== stage.getZoomLevel())
+                    stage.zoomTo(zoom);
+            });
+        });
+        effect((onCleanup) => {
+            const stage = this.hostCapability();
+            if (!stage)
+                return;
+            const offPage = stage.onPageChanged(({ pageIndex }) => this.pageChange.emit(pageIndex));
+            const offZoom = stage.onZoomChanged(({ level }) => this.zoomChange.emit(level));
+            onCleanup(() => {
+                offPage();
+                offZoom();
+            });
+        });
+    }
     /**
-     * Ambient ZOOM gestures on this stage: ctrl/cmd+wheel and trackpad pinch
-     * (Safari gesture events included). Default true. Turn OFF for follower
-     * lenses with a fixed magnification (a thumbnail rail should scroll under
-     * cmd+wheel, not zoom); pinches are still swallowed either way.
+     * The browser side: the viewport size and pixel ratio, wheel and touch gestures, and the
+     * pointer going to the interaction hub. All of it is `@embedpdf/web`'s, shared by every
+     * framework, so the Stage feels the same everywhere; this binds it again when the view, the
+     * hub or the input settings change.
      */
-    zoomGestures = input(true, ...(ngDevMode ? [{ debugName: "zoomGestures" }] : []));
-    /** The stage lens to drive (default: the main StageToken). */
-    token = input(StageToken, ...(ngDevMode ? [{ debugName: "token" }] : []));
-    host = injectKernelHost();
-    stage = injectOptionalCapabilityFor(() => this.token());
-    ix = injectOptionalCapability(InteractionToken);
-    useHub = computed(() => this.interaction() && this.ix() !== null, ...(ngDevMode ? [{ debugName: "useHub" }] : []));
-    // The hub's resolved cursor (text/grab/…), applied to the viewport when driving.
-    hubCursor = this.host.value(() => this.ix()?.cursor() ?? 'default');
-    cursor = computed(() => (this.useHub() ? this.hubCursor() : null), ...(ngDevMode ? [{ debugName: "cursor" }] : []));
-    documentId = injectDocumentId();
-    // visiblePages already folds in the camera (each page carries its
-    // device-snapped screenX/screenY + transform), so panning re-emits the list —
-    // no separate camera subscription needed for positioning. The capability
-    // memoizes, so Object.is equality suffices.
-    pages = injectOptionalSelectorFor(() => this.token(), (c) => c.visiblePages(), EMPTY_PAGES);
-    // Reserved chrome bands (screen px), uniform across pages — the frame the
-    // outer box reserves and the chrome template paints into.
-    frame = injectOptionalSelectorFor(() => this.token(), (c) => c.pageFrame(), NO_FRAME, frameEqual);
-    pageTemplateDir = contentChild(EpdfPageTemplate, ...(ngDevMode ? [{ debugName: "pageTemplateDir" }] : []));
-    chromeTemplateDir = contentChild(EpdfPageChrome, ...(ngDevMode ? [{ debugName: "chromeTemplateDir" }] : []));
-    pageTemplate = computed(() => this.pageTemplateDir()?.template ?? null, ...(ngDevMode ? [{ debugName: "pageTemplate" }] : []));
-    chromeTemplate = computed(() => this.chromeTemplateDir()?.template ?? null, ...(ngDevMode ? [{ debugName: "chromeTemplate" }] : []));
-    constructor() {
-        if (!isPlatformBrowser(inject(PLATFORM_ID)))
-            return;
-        const el = inject(ElementRef).nativeElement;
-        const zone = inject(NgZone);
-        // Rebinds when the stage capability (document open/close/switch, token
-        // change), hub, or gesture flags change — the Angular spelling of the React
-        // Stage effect and its dependency array.
+    bindSurface() {
+        const element = inject(ElementRef).nativeElement;
         effect((onCleanup) => {
-            const stage = this.stage();
-            const ix = this.ix();
-            const useHub = this.interaction() && !!ix;
+            const stage = this.hostCapability();
+            const hub = this.hub();
+            const usesHub = this.usesHub();
             const panFallback = this.panFallback();
             const zoomGestures = this.zoomGestures();
             if (!stage)
-                return; // no document yet — nothing to drive
-            const cleanups = [];
-            zone.runOutsideAngular(() => {
-                // The WHOLE browser binding — viewport/DPR reporting, sample
-                // normalization, gesture controller — is the shared @embedpdf/web
-                // surface, so every framework adapter has one feel. This component
-                // keeps only Angular glue.
-                cleanups.push(createStageSurface(el, stage, {
-                    hub: useHub ? ix : null,
-                    source: stage.lensId(),
-                    zoomGestures,
-                }));
-                // Interaction opt-in lives WITH the sample source: the same knob that
-                // forwards this lens's samples also registers its pan-scroll handler,
-                // lens-scoped — two stages on one document can never pan each other.
-                if (useHub && ix) {
-                    cleanups.push(ix.registerHandler(createScrollHandler(stage, ix, { panFallback }), {
-                        source: stage.lensId(),
-                    }));
-                }
+                return;
+            const detachSurface = createStageSurface(element, stage, {
+                hub: usesHub ? hub : null,
+                source: stage.getLensId(),
+                zoomGestures,
+            });
+            // The pointer and this view's drag-to-scroll go to the hub together, for this view only,
+            // so two Stages on one document never scroll each other.
+            const offScroll = usesHub && hub
+                ? hub.registerHandler(createScrollHandler(stage, hub, { panFallback }), {
+                    source: stage.getLensId(),
+                })
+                : null;
+            onCleanup(() => {
+                offScroll?.();
+                detachSurface();
             });
-            onCleanup(() => cleanups.forEach((fn) => fn()));
         });
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfStage, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.2.4", type: EpdfStage, isStandalone: true, selector: "epdf-stage", inputs: { interaction: { classPropertyName: "interaction", publicName: "interaction", isSignal: true, isRequired: false, transformFunction: null }, panFallback: { classPropertyName: "panFallback", publicName: "panFallback", isSignal: true, isRequired: false, transformFunction: null }, zoomGestures: { classPropertyName: "zoomGestures", publicName: "zoomGestures", isSignal: true, isRequired: false, transformFunction: null }, token: { classPropertyName: "token", publicName: "token", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "style.cursor": "cursor()" }, styleAttribute: "position: relative; overflow: hidden; touch-action: none; display: block;" }, queries: [{ propertyName: "pageTemplateDir", first: true, predicate: EpdfPageTemplate, descendants: true, isSignal: true }, { propertyName: "chromeTemplateDir", first: true, predicate: EpdfPageChrome, descendants: true, isSignal: true }], ngImport: i0, template: `
-    @if (pageTemplate(); as tpl) {
-      @for (p of pages(); track p.pon) {
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.2.4", type: EpdfStage, isStandalone: true, selector: "epdf-stage", inputs: { token: { classPropertyName: "token", publicName: "token", isSignal: true, isRequired: false, transformFunction: null }, document: { classPropertyName: "document", publicName: "document", isSignal: true, isRequired: false, transformFunction: null }, page: { classPropertyName: "page", publicName: "page", isSignal: true, isRequired: false, transformFunction: null }, zoom: { classPropertyName: "zoom", publicName: "zoom", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { pageChange: "pageChange", zoomChange: "zoomChange" }, host: { properties: { "style.cursor": "cursor()" }, styleAttribute: "position: relative; display: block; overflow: hidden; touch-action: none;" }, providers: [
+            // The services inside act on this Stage's document. After them, so it wins over the
+            // `EpdfStageRef` among them: what's inside injects this Stage as `EpdfStageRef`, talks to
+            // its document, and projects anchored UI through its camera.
+            EPDF_SCOPED_SERVICES,
+            StageDocument,
+            { provide: EPDF_DOCUMENT_SCOPE, useExisting: StageDocument },
+            { provide: EpdfStageRef, useExisting: forwardRef(() => EpdfStage) },
+            { provide: EPDF_PROJECTOR, useFactory: () => inject(EpdfStage).projection },
+        ], queries: [{ propertyName: "pageTemplateDirective", first: true, predicate: EpdfPageTemplate, descendants: true, isSignal: true }, { propertyName: "chromeTemplateDirective", first: true, predicate: EpdfPageChrome, descendants: true, isSignal: true }], exportAs: ["epdfStage"], usesInheritance: true, ngImport: i0, template: `
+    @if (pageTemplate(); as template) {
+      @for (visiblePage of pages(); track visiblePage.ref.objectNumber) {
         <epdf-page-surface
-          [vp]="p"
+          [visiblePage]="visiblePage"
           [frame]="frame()"
           [documentId]="documentId() ?? ''"
-          [pageTpl]="tpl"
-          [chromeTpl]="chromeTemplate()"
+          [stage]="hostCapability()!"
+          [look]="look()"
+          [pageTemplate]="template"
+          [chromeTemplate]="chromeTemplate()"
         />
       }
     }
-    <!-- viewport-space overlay UI: anything projected into <epdf-stage>
-         renders above the pages (menus, controls, scrollbars). -->
+    <!-- What you put inside <epdf-stage> sits over the pages, in the Stage's own box. -->
     <ng-content />
-  `, isInline: true, dependencies: [{ kind: "component", type: EpdfPageSurface, selector: "epdf-page-surface", inputs: ["vp", "frame", "documentId", "pageTpl", "chromeTpl"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, dependencies: [{ kind: "component", type: EpdfPageSurface, selector: "epdf-page-surface", inputs: ["visiblePage", "frame", "documentId", "stage", "look", "pageTemplate", "chromeTemplate"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfStage, decorators: [{
             type: Component,
             args: [{
                     selector: 'epdf-stage',
-                    standalone: true,
+                    exportAs: 'epdfStage',
                     imports: [EpdfPageSurface],
                     changeDetection: ChangeDetectionStrategy.OnPush,
+                    providers: [
+                        // The services inside act on this Stage's document. After them, so it wins over the
+                        // `EpdfStageRef` among them: what's inside injects this Stage as `EpdfStageRef`, talks to
+                        // its document, and projects anchored UI through its camera.
+                        EPDF_SCOPED_SERVICES,
+                        StageDocument,
+                        { provide: EPDF_DOCUMENT_SCOPE, useExisting: StageDocument },
+                        { provide: EpdfStageRef, useExisting: forwardRef(() => EpdfStage) },
+                        { provide: EPDF_PROJECTOR, useFactory: () => inject(EpdfStage).projection },
+                    ],
                     host: {
-                        style: 'position: relative; overflow: hidden; touch-action: none; display: block;',
+                        style: 'position: relative; display: block; overflow: hidden; touch-action: none;',
                         '[style.cursor]': 'cursor()',
                     },
                     template: `
-    @if (pageTemplate(); as tpl) {
-      @for (p of pages(); track p.pon) {
+    @if (pageTemplate(); as template) {
+      @for (visiblePage of pages(); track visiblePage.ref.objectNumber) {
         <epdf-page-surface
-          [vp]="p"
+          [visiblePage]="visiblePage"
           [frame]="frame()"
           [documentId]="documentId() ?? ''"
-          [pageTpl]="tpl"
-          [chromeTpl]="chromeTemplate()"
+          [stage]="hostCapability()!"
+          [look]="look()"
+          [pageTemplate]="template"
+          [chromeTemplate]="chromeTemplate()"
         />
       }
     }
-    <!-- viewport-space overlay UI: anything projected into <epdf-stage>
-         renders above the pages (menus, controls, scrollbars). -->
+    <!-- What you put inside <epdf-stage> sits over the pages, in the Stage's own box. -->
     <ng-content />
   `,
                 }]
         }], ctorParameters: () => [] });
 
-/** Late-binding method passthrough: exact capability signature, current doc. */
-const lazy = (cap, key) => ((...args) => cap()[key](...args));
-function injectStage(token = StageToken) {
-    return injectCapability(token);
-}
-function injectZoom(token = StageToken) {
-    const s = injectCapability(token);
-    return {
-        zoom: injectSelector(token, (c) => c.zoomLevel()),
-        /** Active zoom intent: 'automatic' | 'fit-page' | 'fit-width' | 'fit-all' | 'custom'. */
-        mode: injectSelector(token, (c) => c.zoomMode()),
-        zoomIn: lazy(s, 'zoomIn'),
-        zoomOut: lazy(s, 'zoomOut'),
-        fitWidth: lazy(s, 'fitWidth'),
-        fitPage: lazy(s, 'fitPage'),
-        fitAll: lazy(s, 'fitAll'),
-        automatic: lazy(s, 'automatic'),
-        zoomTo: lazy(s, 'zoomTo'),
-    };
-}
-function injectPages(token = StageToken) {
-    const s = injectCapability(token);
-    return {
-        currentPage: injectSelector(token, (c) => c.currentPage()),
-        pageCount: injectSelector(token, (c) => c.pageCount()),
-        goToPage: lazy(s, 'goToPage'),
-        next: lazy(s, 'next'),
-        prev: lazy(s, 'prev'),
-        reveal: lazy(s, 'reveal'),
-    };
-}
-function injectLayout(token = StageToken) {
-    const s = injectCapability(token);
-    return {
-        flow: injectSelector(token, (c) => c.flow()),
-        layout: injectSelector(token, (c) => c.layout()),
-        spread: injectSelector(token, (c) => c.spread()),
-        sizing: injectSelector(token, (c) => c.sizing()),
-        bounded: injectSelector(token, (c) => c.bounded()),
-        setFlow: lazy(s, 'setFlow'),
-        setLayout: lazy(s, 'setLayout'),
-        setSpread: lazy(s, 'setSpread'),
-        setSizing: lazy(s, 'setSizing'),
-        setBounded: lazy(s, 'setBounded'),
-    };
-}
-/** The document's page list (with PDF labels) + the current item's pages — the
- *  data for page thumbnails / worksheet-style page tabs. */
-function injectPageList(token = StageToken) {
-    return {
-        pages: injectSelector(token, (c) => c.pages(), (a, b) => a.length === b.length && a.every((p, i) => p.pon === b[i].pon && p.label === b[i].label)),
-        currentItemPages: injectSelector(token, (c) => c.currentItemPages(), shallowArray),
-    };
-}
 /**
- * All Stage settings + the batch `update`. The seam for "presets are a customer
- * concern": keep your own `Partial<StageSettings>` objects and apply them with
- * `update(preset)` (one anchor-preserving change).
+ * `<epdf-scrollbar>`: a scrollbar for the Stage it's in, that you style yourself. Put it inside
+ * `<epdf-stage>`; it reads the Stage's `scrollMetrics()` (the numbers a scrolling element has)
+ * and scrolls through its calls.
+ *
+ * It behaves like a native bar: drag the thumb (the point you grabbed stays under the pointer),
+ * press the track to page toward the pointer (repeating while held, stopping at the pointer),
+ * a minimum thumb length on long documents, and macOS-style hiding when nothing moves. On an
+ * unbounded Stage the metrics already cover the content and the view together, so the bar
+ * shrinks as you pan away; the mapping is frozen while the thumb is dragged, so the thumb never
+ * chases itself.
+ *
+ * The element is the track; style it with your own class and these attributes:
+ *   [data-embedpdf-scrollbar][data-axis="y"][data-state="visible|hidden"]
+ *   [data-embedpdf-scrollbar][data-dragging]
+ *   [data-embedpdf-scrollbar-thumb]          (or `thumbClass`)
+ * Until you style the thumb, its color is `--epdf-scrollbar-thumb`.
  */
-function injectStageSettings(token = StageToken) {
-    const s = injectCapability(token);
-    return {
-        // settingsEqual derives from the plugin's settings registry — a new setting
-        // is covered automatically, without this package spelling out the shape.
-        settings: injectSelector(token, (c) => c.settings(), settingsEqual),
-        update: lazy(s, 'update'),
-        reset: lazy(s, 'resetView'),
-    };
+class EpdfScrollbar {
+    /** `'y'` for a vertical bar, `'x'` for a horizontal one. */
+    axis = input.required(...(ngDevMode ? [{ debugName: "axis" }] : []));
+    /**
+     * Hide this many milliseconds after the view stops moving (hover and dragging keep it shown;
+     * a hidden bar ignores the pointer, like macOS), or `false` to always show it.
+     */
+    autoHide = input(1200, ...(ngDevMode ? [{ debugName: "autoHide", transform: (value) => (value === false || value === 'false' ? false : Number(value)) }] : [{
+            transform: (value) => (value === false || value === 'false' ? false : Number(value)),
+        }]));
+    /** The shortest thumb, in pixels, so it never vanishes on a long document. */
+    minThumbSize = input(24, ...(ngDevMode ? [{ debugName: "minThumbSize" }] : []));
+    /**
+     * Pressing the track: `'page'` steps 90% of a view toward the pointer and repeats while held;
+     * `'jump'` puts the thumb under the pointer and goes on as a drag.
+     */
+    trackPress = input('page', ...(ngDevMode ? [{ debugName: "trackPress" }] : []));
+    /** The thumb's class. */
+    thumbClass = input(null, ...(ngDevMode ? [{ debugName: "thumbClass" }] : []));
+    stage;
+    element = inject(ElementRef).nativeElement;
+    trackPx = signal(0, ...(ngDevMode ? [{ debugName: "trackPx" }] : []));
+    dragging = signal(false, ...(ngDevMode ? [{ debugName: "dragging" }] : []));
+    hovered = signal(false, ...(ngDevMode ? [{ debugName: "hovered" }] : []));
+    /** The view moved a moment ago. */
+    active = signal(true, ...(ngDevMode ? [{ debugName: "active" }] : []));
+    vertical = computed(() => this.axis() === 'y', ...(ngDevMode ? [{ debugName: "vertical" }] : []));
+    scrollable = computed(() => {
+        const metrics = this.stage.scrollMetrics();
+        return this.vertical() ? metrics.scrollableY : metrics.scrollableX;
+    }, ...(ngDevMode ? [{ debugName: "scrollable" }] : []));
+    /** The thumb along the track: one formula for drawing, dragging and paging, in every framework. */
+    layout = computed(() => scrollbarLayout(this.stage.scrollMetrics(), this.vertical(), this.trackPx(), this.minThumbSize()), ...(ngDevMode ? [{ debugName: "layout" }] : []));
+    shown = computed(() => this.autoHide() === false ||
+        this.autoHide() === 0 ||
+        this.active() ||
+        this.hovered() ||
+        this.dragging(), ...(ngDevMode ? [{ debugName: "shown" }] : []));
+    thumbColor = paintDefault('scrollbar-thumb');
+    round = Math.round;
+    /** Thumb drags, track paging and jumps: `@embedpdf/web`'s, shared by every framework. */
+    presses = createScrollbarPresses((dragging) => this.dragging.set(dragging));
+    constructor() {
+        const stage = inject(EpdfStage, { optional: true });
+        if (!stage)
+            throw outsideStageError('<epdf-scrollbar>');
+        this.stage = stage;
+        // Any move of the view shows the bar again and starts the countdown to hiding it.
+        effect((onCleanup) => {
+            this.stage.scrollMetrics();
+            const hideAfter = this.autoHide();
+            if (hideAfter === false || hideAfter === 0)
+                return;
+            this.active.set(true);
+            const timer = setTimeout(() => this.active.set(false), hideAfter);
+            onCleanup(() => clearTimeout(timer));
+        });
+        // The track's length, which the thumb maps onto; again whenever the bar appears or resizes.
+        effect((onCleanup) => {
+            const vertical = this.vertical();
+            if (!this.scrollable() || typeof ResizeObserver === 'undefined')
+                return;
+            const measure = () => this.trackPx.set(vertical ? this.element.clientHeight : this.element.clientWidth);
+            const observer = new ResizeObserver(measure);
+            observer.observe(this.element);
+            measure();
+            onCleanup(() => observer.disconnect());
+        });
+        inject(DestroyRef).onDestroy(() => this.endDrag());
+    }
+    /** The bar as it is now, for `@embedpdf/web`'s press handling. */
+    track() {
+        const vertical = this.vertical();
+        return {
+            stage: this.stage,
+            vertical,
+            element: this.element,
+            layout: this.layout(),
+            // Fresh geometry for paging steps, from the metrics as they are now.
+            liveLayout: () => scrollbarLayout(this.stage.scrollMetrics(), vertical, this.trackPx(), this.minThumbSize()),
+        };
+    }
+    onThumbDown(event) {
+        this.presses.pressThumb(event, this.track());
+    }
+    onTrackDown(event) {
+        this.presses.pressTrack(event, this.track(), this.trackPress());
+    }
+    /** Pointer capture sends the moves here, for thumb drags, jump drags and paging alike. */
+    onMove(event) {
+        this.presses.move(event, this.track());
+    }
+    endDrag() {
+        this.presses.release();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfScrollbar, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "20.2.4", type: EpdfScrollbar, isStandalone: true, selector: "epdf-scrollbar", inputs: { axis: { classPropertyName: "axis", publicName: "axis", isSignal: true, isRequired: true, transformFunction: null }, autoHide: { classPropertyName: "autoHide", publicName: "autoHide", isSignal: true, isRequired: false, transformFunction: null }, minThumbSize: { classPropertyName: "minThumbSize", publicName: "minThumbSize", isSignal: true, isRequired: false, transformFunction: null }, trackPress: { classPropertyName: "trackPress", publicName: "trackPress", isSignal: true, isRequired: false, transformFunction: null }, thumbClass: { classPropertyName: "thumbClass", publicName: "thumbClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "scrollbar", "data-embedpdf-scrollbar": "" }, listeners: { "pointerdown": "onTrackDown($event)", "pointermove": "onMove($event)", "pointerup": "endDrag()", "pointercancel": "endDrag()", "pointerenter": "hovered.set(true)", "pointerleave": "hovered.set(false)" }, properties: { "attr.aria-orientation": "vertical() ? 'vertical' : 'horizontal'", "attr.aria-valuemin": "0", "attr.aria-valuemax": "round(layout().maxOffset)", "attr.aria-valuenow": "round(layout().offset)", "attr.data-axis": "axis()", "attr.data-state": "shown() ? 'visible' : 'hidden'", "attr.data-dragging": "dragging() ? '' : null", "style.display": "scrollable() ? 'block' : 'none'", "style.top.px": "vertical() ? 0 : null", "style.left.px": "vertical() ? null : 0", "style.right.px": "0", "style.bottom.px": "0", "style.width.px": "vertical() ? 12 : null", "style.height.px": "vertical() ? null : 12", "style.opacity": "shown() ? 1 : 0", "style.pointer-events": "shown() ? 'auto' : 'none'" }, styleAttribute: "position: absolute; touch-action: none; user-select: none; transition: opacity 200ms" }, ngImport: i0, template: `
+    <div
+      data-embedpdf-scrollbar-thumb=""
+      [class]="thumbClass()"
+      style="position: absolute; border-radius: 6px"
+      [style.background]="thumbColor"
+      [style.left.px]="vertical() ? 2 : layout().thumbPosition"
+      [style.right.px]="vertical() ? 2 : null"
+      [style.top.px]="vertical() ? layout().thumbPosition : 2"
+      [style.bottom.px]="vertical() ? null : 2"
+      [style.width.px]="vertical() ? null : layout().thumbLength"
+      [style.height.px]="vertical() ? layout().thumbLength : null"
+      (pointerdown)="onThumbDown($event)"
+    ></div>
+  `, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: EpdfScrollbar, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'epdf-scrollbar',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    host: {
+                        role: 'scrollbar',
+                        'data-embedpdf-scrollbar': '',
+                        style: 'position: absolute; touch-action: none; user-select: none; transition: opacity 200ms',
+                        '[attr.aria-orientation]': "vertical() ? 'vertical' : 'horizontal'",
+                        '[attr.aria-valuemin]': '0',
+                        '[attr.aria-valuemax]': 'round(layout().maxOffset)',
+                        '[attr.aria-valuenow]': 'round(layout().offset)',
+                        '[attr.data-axis]': 'axis()',
+                        '[attr.data-state]': "shown() ? 'visible' : 'hidden'",
+                        '[attr.data-dragging]': "dragging() ? '' : null",
+                        // Pinned to the right (y) or bottom (x) edge of the Stage; nothing to scroll, no bar.
+                        '[style.display]': "scrollable() ? 'block' : 'none'",
+                        '[style.top.px]': 'vertical() ? 0 : null',
+                        '[style.left.px]': 'vertical() ? null : 0',
+                        '[style.right.px]': '0',
+                        '[style.bottom.px]': '0',
+                        '[style.width.px]': 'vertical() ? 12 : null',
+                        '[style.height.px]': 'vertical() ? null : 12',
+                        '[style.opacity]': 'shown() ? 1 : 0',
+                        // A hidden bar must not take the clicks meant for the pages under it.
+                        '[style.pointer-events]': "shown() ? 'auto' : 'none'",
+                        '(pointerdown)': 'onTrackDown($event)',
+                        '(pointermove)': 'onMove($event)',
+                        '(pointerup)': 'endDrag()',
+                        '(pointercancel)': 'endDrag()',
+                        '(pointerenter)': 'hovered.set(true)',
+                        '(pointerleave)': 'hovered.set(false)',
+                    },
+                    template: `
+    <div
+      data-embedpdf-scrollbar-thumb=""
+      [class]="thumbClass()"
+      style="position: absolute; border-radius: 6px"
+      [style.background]="thumbColor"
+      [style.left.px]="vertical() ? 2 : layout().thumbPosition"
+      [style.right.px]="vertical() ? 2 : null"
+      [style.top.px]="vertical() ? layout().thumbPosition : 2"
+      [style.bottom.px]="vertical() ? null : 2"
+      [style.width.px]="vertical() ? null : layout().thumbLength"
+      [style.height.px]="vertical() ? layout().thumbLength : null"
+      (pointerdown)="onThumbDown($event)"
+    ></div>
+  `,
+                }]
+        }], ctorParameters: () => [] });
 
 /**
- * @embedpdf/angular/stage — the viewport trunk: `<epdf-stage>` + page
- * templates + the stage facade inject functions.
+ * @embedpdf/angular/stage: `<epdf-stage>` and what goes with it.
+ *
+ *   withStage(options)                       the plugin, for provideEmbedPdf()
+ *   <epdf-stage #stage="epdfStage">          the pages, and the Stage's API
+ *   inject(EpdfStageRef)                     the Stage's API, from inside a Stage or anywhere
+ *   <ng-template epdfPage>, epdfPageChrome   what each page draws, and around it
+ *   <epdf-scrollbar>                         a scrollbar you style yourself
  */
-// One-line-per-feature: registration travels with the UI.
+// The plugin's types and helpers, so app code has one import for the feature.
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { EpdfPageChrome, EpdfPageSurface, EpdfPageTemplate, EpdfStage, injectLayout, injectPageList, injectPages, injectStage, injectStageSettings, injectZoom };
+export { EpdfPageChrome, EpdfPageTemplate, EpdfScrollbar, EpdfStage, EpdfStageRef, withStage };
 //# sourceMappingURL=embedpdf-angular-stage.mjs.map