@readium/navigator 2.10.2 → 2.11.0

package/types/src/audio/engine/AudioEngine.d.ts

@@ -27,6 +27,30 @@ export interface Playback {
     offset?: number;
     buffered?: number;
 }
+/**
+ * A consumer-supplied loader that feeds one resource to the playback element
+ * through Media Source Extensions. The engine constructs one per track via
+ * the [AudioMseLoaderFactory] and calls [start] immediately; the loader owns
+ * the element's `src` (a MediaSource object URL), all fetching, buffering and
+ * seek servicing until [destroy] is called. Container specifics (WebM, fMP4,
+ * byte ranges vs. segments…) are entirely up to the implementation.
+ */
+export interface AudioMseLoader {
+    /** Attaches to the element and begins streaming. Called exactly once. */
+    start(): void;
+    /**
+     * Cancels in-flight fetches, detaches element listeners and releases the
+     * MediaSource object URL. The element itself must be left intact — the
+     * engine reuses it for the next track.
+     */
+    destroy(): void;
+}
+/**
+ * Creates the [AudioMseLoader] for a resource. [mimeType] is the resource's
+ * media type from the manifest, when known — needed to configure the
+ * SourceBuffer.
+ */
+export type AudioMseLoaderFactory = (element: HTMLMediaElement, href: string, mimeType?: string) => AudioMseLoader;
 /**
  * An audio engine that plays audio resources from a publication.
  * @playback - The current [Playback] state.
@@ -52,8 +76,10 @@ export interface AudioEngine {
      * Changes the src of the primary media element without swapping it,
      * preserving the RemotePlayback session and all attached event listeners.
      * @param href The URL of the new audio resource.
+     * @param mimeType The media type of the resource, when known. Required for
+     * MSE-based loading to configure the SourceBuffer.
      */
-    changeSrc(href: string): void;
+    changeSrc(href: string, mimeType?: string): void;
     /**
      * Plays the current audio resource.
      */

package/types/src/audio/engine/WebAudioEngine.d.ts

@@ -1,4 +1,4 @@
-import { AudioEngine, Playback } from "./AudioEngine.ts";
+import { AudioEngine, AudioMseLoaderFactory, Playback } from "./AudioEngine.ts";
 type EventCallback = (data: any) => void;
 export declare class WebAudioEngine implements AudioEngine {
     readonly playback: Playback;
@@ -16,6 +16,10 @@ export declare class WebAudioEngine implements AudioEngine {
     private isStoppedValue;
     private worklet;
     private webAudioActive;
+    private readonly mseLoaderFactory;
+    private mseLoader;
+    /** The resource href currently loaded (element src is a blob: URL in MSE mode). */
+    private currentHref;
     private readonly boundOnCanPlayThrough;
     private readonly boundOnTimeUpdate;
     private readonly boundOnError;
@@ -33,6 +37,7 @@ export declare class WebAudioEngine implements AudioEngine {
     private readonly boundOnProgress;
     constructor(values: {
         playback: Playback;
+        mseLoaderFactory?: AudioMseLoaderFactory;
     });
     /**
      * Adds an event listener to the audio engine.
@@ -132,6 +137,8 @@ export declare class WebAudioEngine implements AudioEngine {
      */
     private activateWebAudio;
     get isWebAudioActive(): boolean;
+    /** True when this engine streams media through Media Source Extensions. */
+    get usesMse(): boolean;
     /**
      * Tears down the Web Audio graph and restores the media element to standalone
      * playback. Safe to call even if Web Audio was never activated.
@@ -145,10 +152,15 @@ export declare class WebAudioEngine implements AudioEngine {
      * the required headers), the graph is torn down and the src is reloaded
      * without CORS so playback continues — just without pitch correction.
      */
-    changeSrc(href: string): void;
+    changeSrc(href: string, mimeType?: string): void;
     /**
      * Returns the HTML media element used for playback.
      */
     getMediaElement(): HTMLMediaElement;
+    /**
+     * Releases loader resources (in-flight fetches, MediaSource object URL).
+     * The media element itself is left intact.
+     */
+    destroy(): void;
 }
 export {};

package/types/src/divina/DivinaNavigator.d.ts

@@ -0,0 +1,119 @@
+import { Layout, Link, Locator, Publication, ReadingProgression, Timeline, TimelineItem } from "@readium/shared";
+import { ContextMenuEvent, FrameClickEvent, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
+import { IContentProtectionConfig, IKeyboardPeripheralsConfig, KeyboardPeripheralEventData, VisualNavigator, VisualNavigatorViewport } from "../Navigator.ts";
+import { Configurable, ConfigurableSettings } from "../preferences/Configurable.ts";
+import { IDivinaDefaults } from "./preferences/DivinaDefaults.ts";
+import { DivinaPreferences, IDivinaPreferences } from "./preferences/DivinaPreferences.ts";
+import { DivinaSettings } from "./preferences/DivinaSettings.ts";
+import { DivinaPreferencesEditor } from "./preferences/DivinaPreferencesEditor.ts";
+export interface DivinaNavigatorConfiguration {
+    preferences: IDivinaPreferences;
+    defaults: IDivinaDefaults;
+    contentProtection?: IContentProtectionConfig;
+    keyboardPeripherals?: IKeyboardPeripheralsConfig;
+}
+export interface DivinaNavigatorListeners {
+    positionChanged: (locator: Locator) => void;
+    timelineItemChanged: (item: TimelineItem | undefined) => void;
+    tap: (e: FrameClickEvent) => boolean;
+    click: (e: FrameClickEvent) => boolean;
+    zoom: (scale: number) => void;
+    miscPointer: (amount: number) => void;
+    scroll: (delta: number) => void;
+    customEvent: (key: string, data: unknown) => void;
+    handleLocator: (locator: Locator) => boolean;
+    contentProtection: (type: string, data: SuspiciousActivityEvent) => void;
+    contextMenu: (data: ContextMenuEvent) => void;
+    peripheral: (data: KeyboardPeripheralEventData) => void;
+}
+/**
+ * Navigator for Divina (visual narrative) publications: bitmap pages rendered
+ * as <img> elements with blob sources, in either a horizontal paged view with
+ * synthetic spreads (comics/manga) or a continuous vertical scroll (webtoons).
+ */
+export declare class DivinaNavigator extends VisualNavigator implements Configurable<ConfigurableSettings, DivinaPreferences> {
+    private readonly pub;
+    private readonly container;
+    private readonly listeners;
+    private positions;
+    private currentLocation;
+    private _destroyed;
+    private _isNavigating;
+    private _timelineAugmented;
+    private _wrappedTimeline;
+    private _currentTimelineItem;
+    private _preferences;
+    private _defaults;
+    private _settings;
+    private _preferencesEditor;
+    private readonly spreader;
+    private readonly pool;
+    private pagedPresenter;
+    private scrolledPresenter;
+    private readonly _contentProtection;
+    private readonly _keyboardPeripherals;
+    private readonly _navigatorProtector;
+    private _keyboardPeripheralsManager;
+    private readonly _keyboardConditionBridge;
+    private readonly _suspiciousActivityListener;
+    private readonly _keyboardPeripheralListener;
+    private resizeObserver;
+    constructor(container: HTMLElement, pub: Publication, listeners: Partial<DivinaNavigatorListeners>, positions?: Locator[], initialPosition?: Locator | undefined, configuration?: DivinaNavigatorConfiguration);
+    private get manifestScrolled();
+    get ownerWindow(): Window;
+    get publication(): Publication;
+    get timeline(): Timeline;
+    private _notifyTimelineChange;
+    get layout(): Layout;
+    get readingProgression(): ReadingProgression;
+    private get presenter();
+    load(): Promise<boolean | undefined>;
+    private synthesizePositions;
+    private createPresenter;
+    private destroyPresenter;
+    private handlePointer;
+    /** Paged mode: move by one spread and report the new position */
+    private changeSpread;
+    private setLocationToIndex;
+    /** Scrolled mode: debounced position reports from the scroll handler */
+    private updateLocationFromScroll;
+    private applyBackground;
+    /** Whether a CSS color is dark, via computed-style normalization; null if unparseable */
+    private isDarkColor;
+    resizeHandler(): void;
+    private completeLocator;
+    /**
+     * The reading order index for a href, tolerating representation
+     * mismatches: a TOC can use absolute URLs while the reading order is
+     * relative (or vice versa), and it can reference a page through one of
+     * its alternate variants rather than the main href. Both sides are
+     * resolved against the publication base, and each page matches on its
+     * own href or any of its alternates.
+     */
+    private findReadingOrderIndex;
+    go(locator: Locator, animated: boolean, cb: (ok: boolean) => void): void;
+    goLink(link: Link, animated: boolean, cb: (ok: boolean) => void): void;
+    goForward(animated: boolean, cb: (ok: boolean) => void): void;
+    goBackward(animated: boolean, cb: (ok: boolean) => void): void;
+    /**
+     * Scrolled mode: scroll by a fixed pixel amount (e.g. a line step for
+     * arrow keys) instead of the viewport-sized go* step. Falls back to a
+     * spread turn in paged mode.
+     */
+    scrollBy(px: number, animated: boolean, cb: (ok: boolean) => void): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    zoomReset(): void;
+    get currentLocator(): Locator;
+    get viewport(): VisualNavigatorViewport;
+    get isScrollStart(): boolean;
+    get isScrollEnd(): boolean;
+    get canGoBackward(): boolean;
+    get canGoForward(): boolean;
+    get settings(): Readonly<DivinaSettings>;
+    get preferencesEditor(): DivinaPreferencesEditor;
+    private _applying;
+    submitPreferences(preferences: DivinaPreferences): Promise<void>;
+    private applyPreferences;
+    destroy(): Promise<void>;
+}

package/types/src/divina/DivinaPageManager.d.ts

@@ -0,0 +1,66 @@
+import { Link, Page } from "@readium/shared";
+import { DivinaPage } from "./DivinaSpreader.ts";
+import { DivinaQuality } from "./DivinaVariantSelector.ts";
+export declare function placeholderSVG(width: number, height: number, message: string, detail?: string): string;
+export type DivinaPageMode = "paged" | "scrolled";
+/**
+ * Manages the lifecycle of a single Divina page: an <img> element inside a
+ * wrapper <div>, with blob-based loading, an intrinsic-size SVG placeholder,
+ * and per-mode layout. The image-based equivalent of FXLFrameManager.
+ */
+export declare class DivinaPageManager {
+    readonly page: DivinaPage;
+    readonly wrapper: HTMLDivElement;
+    readonly img: HTMLImageElement;
+    private readonly fetchBlob;
+    private readonly getQuality;
+    private readonly placeholder;
+    private objectURL;
+    private loadPromise;
+    private abortController;
+    private _loaded;
+    private destroyed;
+    private generation;
+    private mode;
+    constructor(page: DivinaPage, fetchBlob: (link: Link, signal?: AbortSignal) => Promise<Blob>, getQuality?: () => DivinaQuality);
+    get intrinsicWidth(): number;
+    get intrinsicHeight(): number;
+    get loaded(): boolean;
+    get element(): HTMLDivElement;
+    /**
+     * Configure the wrapper/image styles for the given presentation mode.
+     * Paged: the image is fitted (letterboxed) inside the slot-sized wrapper.
+     * Scrolled: the image dictates the height via its aspect ratio.
+     */
+    setMode(mode: DivinaPageMode): void;
+    /**
+     * Position the fitted image within its wrapper (paged mode only).
+     *
+     * @param position In a two-page spread, the side of the gutter this page
+     * sits on (pages butt against the gutter). With `half`, the half of a
+     * full-spread wrapper the page occupies.
+     * @param half The page is alone in a double-width (full-spread) slot but
+     * carries a left/right position hint — e.g. a shifted cover or the
+     * orphaned component of a spread — so it is fitted to and centered
+     * within its half of the spread.
+     */
+    fit(position: Page, half?: boolean): void;
+    /** Scrolled mode: constrain the display width of this page in the strip */
+    applyStripWidth(displayWidth: number): void;
+    /**
+     * Fetch the image as a blob and swap it in for the placeholder.
+     * Idempotent; concurrent calls await the same promise.
+     */
+    /**
+     * The most appropriate variant (main link or alternate) for the page's
+     * current display box and the user's quality preference.
+     */
+    private pickVariant;
+    load(): Promise<void>;
+    /**
+     * Release the blob and go back to the placeholder (memory reclamation),
+     * aborting any in-flight fetch.
+     */
+    unload(): void;
+    destroy(): void;
+}

package/types/src/divina/DivinaPagedPresenter.d.ts

@@ -0,0 +1,122 @@
+import { Publication } from "@readium/shared";
+import { VisualNavigatorViewport } from "../Navigator.ts";
+import { DivinaPageManager } from "./DivinaPageManager.ts";
+import { DivinaManagerEventKey, DivinaPagedManager, DivinaPeripherals } from "./DivinaPeripherals.ts";
+import { DivinaPage, DivinaSpreader } from "./DivinaSpreader.ts";
+export type DivinaPresenterListener = (key: DivinaManagerEventKey, data: unknown) => void;
+/**
+ * Horizontal paged presenter for Divina publications: a sliding spine of
+ * page slots with synthetic spreads, ported from the FXLFramePoolManager
+ * slider core but rendering <img> pages instead of iframes.
+ *
+ * Slot model: in double-page mode every spread occupies exactly two slots
+ * (single pages get a double-width slot), so slide indices are always even
+ * and always aligned with spread boundaries.
+ */
+export declare class DivinaPagedPresenter implements DivinaPagedManager {
+    private readonly container;
+    private readonly pub;
+    private readonly spreader;
+    private readonly pool;
+    readonly bookElement: HTMLDivElement;
+    readonly spineElement: HTMLDivElement;
+    readonly peripherals: DivinaPeripherals;
+    width: number;
+    height: number;
+    currentSlide: number;
+    private transform;
+    private spread;
+    private orientationInternal;
+    private containerHeightCached;
+    private destroyed;
+    private loadTimers;
+    listener: DivinaPresenterListener;
+    constructor(container: HTMLElement, pub: Publication, spreader: DivinaSpreader, pool: Map<number, DivinaPageManager>, spreads: boolean);
+    get rtl(): boolean;
+    private get single();
+    get perPage(): 2 | 1;
+    get threshold(): number;
+    get portrait(): boolean;
+    get slength(): number;
+    /** Total slot count in the current mode */
+    get length(): number;
+    /**
+     * The x position of a slot boundary within the spine, snapped to device
+     * pixels. Fractional boundaries leave hairline gaps at the spread gutter
+     * (the background shows through between the two page images), varying
+     * with the window size.
+     */
+    private slotEdge;
+    private get offset();
+    get doNotDisturb(): boolean;
+    /** The reading-order index of the first page of the current spread */
+    get currentIndex(): number;
+    /** The pages currently (meant to be) visible */
+    get currentSpread(): DivinaPage[];
+    private updateDimensions;
+    private bookScale;
+    private bookTranslate;
+    private bookTransform;
+    updateBookStyle(initial?: boolean): void;
+    updateSpineStyle(animate: boolean, fast?: boolean): void;
+    /**
+     * Recompute every slot's width and height. Widths are derived from
+     * device-pixel-snapped slot boundaries so adjacent pages of a spread
+     * meet exactly at the gutter without subpixel seams.
+     */
+    private updateSlotSizes;
+    reAlign(index?: number): number;
+    /**
+     * Moves the spine to the position of the currently active slide.
+     * Always commits: the spine transform may have been written directly by
+     * the peripherals during a drag (snap-back relies on this), and reading
+     * style.transform back for comparison is unreliable under CSS Typed OM.
+     */
+    slideToCurrent(enableTransition?: boolean, fast?: boolean): void;
+    bounce(rtl?: boolean): void;
+    private onChange;
+    /**
+     * Go to the next spread/page.
+     * @returns whether moving forward was possible
+     */
+    next(): boolean;
+    /**
+     * Go to the previous spread/page.
+     * @returns whether moving backward was possible
+     */
+    prev(): boolean;
+    /**
+     * Go to the slide showing the given reading order item.
+     * @returns whether the slide changed
+     */
+    /**
+     * The slide showing the given item in the current mode: the item index
+     * itself in single mode, or the start slot of the item's spread in
+     * double-page mode (the item may occupy the spread's second slot).
+     */
+    private slideForItem;
+    goToItem(itemIndex: number, animated?: boolean): boolean;
+    /**
+     * Loads pages within the load window around the current position,
+     * unloads distant ones, and positions the current spread.
+     */
+    update(): Promise<void>;
+    /**
+     * Fit a page of the current spread within its slot. A lone portrait page
+     * with a left/right hint (shifted cover, orphaned spread half) is fitted
+     * into its half of the full-spread slot; everything else is fitted to the
+     * whole slot and anchored against the gutter (or centered).
+     */
+    private placePage;
+    /** Union of the current spread's image bounds, used for zoom/pan clamping */
+    get currentBounds(): DOMRect;
+    get viewport(): VisualNavigatorViewport;
+    /**
+     * When the container resizes, resize slider components as well
+     */
+    resizeHandler(slide?: boolean, fast?: boolean): void;
+    /** Toggle double-page spreads (from preferences) */
+    setSpreads(spreads: boolean): void;
+    deselect(): void;
+    destroy(): Promise<void>;
+}

package/types/src/divina/DivinaPeripherals.d.ts

@@ -0,0 +1,121 @@
+import { PanTracker } from "../epub/fxl/FXLPeripherals.ts";
+export type DivinaManagerEventKey = "no_more" | "no_less" | "zoom" | "tap" | "click";
+export interface DivinaPointerEvent {
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+    doNotDisturb: boolean;
+}
+/**
+ * The narrow surface of DivinaPagedPresenter that the peripherals interact with.
+ * Mirrors what FXLPeripherals uses from FXLFramePoolManager.
+ */
+export interface DivinaPagedManager {
+    readonly spineElement: HTMLDivElement;
+    readonly bookElement: HTMLDivElement;
+    readonly width: number;
+    readonly height: number;
+    readonly perPage: number;
+    readonly rtl: boolean;
+    readonly threshold: number;
+    readonly length: number;
+    readonly currentSlide: number;
+    readonly currentBounds: DOMRect;
+    listener(key: DivinaManagerEventKey, data: unknown): void;
+    updateBookStyle(initial?: boolean): void;
+    updateSpineStyle(animate: boolean, fast?: boolean): void;
+    slideToCurrent(enableTransition?: boolean, fast?: boolean): void;
+    deselect(): void;
+}
+/**
+ * Input handling for the paged Divina presenter. Ported from FXLPeripherals
+ * (touch pan/pinch-zoom/swipe state machines) with additions for content that
+ * lives in the host DOM instead of iframes: click/tap synthesis, mouse wheel
+ * page turning (one page per wheel burst, xbreader/bibi-like), ctrl+wheel and
+ * double-click zoom.
+ */
+export declare class DivinaPeripherals {
+    private readonly manager;
+    private readonly coordinator;
+    dragState: number;
+    private minimumMoved;
+    pan: PanTracker;
+    private pinch;
+    private _scale;
+    get scale(): number;
+    private scaleDebouncer;
+    set scale(value: number);
+    private frameBounds;
+    private destroyed;
+    private mouseDown;
+    private clickTimer;
+    private lastTouchEnd;
+    private tapTimer;
+    private lastTapTime;
+    private lastTapX;
+    private lastTapY;
+    private wheelHot;
+    private wheelLastDir;
+    private wheelLastMag;
+    private wheelDecelCount;
+    private wheelLastEvent;
+    private wheelCooldownTimer;
+    constructor(manager: DivinaPagedManager);
+    private readonly btouchstartHandler;
+    private readonly btouchendHandler;
+    private readonly btouchmoveHandler;
+    private readonly bdblclickHandler;
+    private readonly bmousedownHandler;
+    private readonly bmouseupHandler;
+    private readonly bmousemoveHandler;
+    private readonly bwheelHandler;
+    observe(item: EventTarget): void;
+    unobserve(item: EventTarget): void;
+    destroy(): void;
+    private clearPan;
+    clearPinch(): void;
+    get isScaled(): boolean;
+    resetZoom(): void;
+    private emitPointer;
+    /**
+     * touchstart event handler (ported from FXLPeripherals)
+     */
+    touchstartHandler(e: TouchEvent): void;
+    private startTouch;
+    /**
+     * touchend event handler (ported from FXLPeripherals, adds tap synthesis)
+     */
+    touchendHandler(e: TouchEvent): void;
+    private moveFrame;
+    private dragTranslate;
+    private dragTransform;
+    /**
+     * touchmove event handler (ported from FXLPeripherals)
+     */
+    touchmoveHandler(e: TouchEvent): void;
+    /**
+     * Double click/tap: toggle zoom between 1x and 2x, centered on the point.
+     */
+    toggleZoom(clientX: number, clientY: number): void;
+    /** Zoom in/out by a keyboard step, clamped to [1, MAX_SCALE] */
+    zoomBy(delta: number): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    dblclickHandler(e: MouseEvent): void;
+    private addTouch;
+    mousedownHandler(e: MouseEvent): void;
+    mouseupHandler(e: MouseEvent): void;
+    mousemoveHandler(e: MouseEvent): void;
+    /**
+     * Wheel handler: ctrl+wheel zooms (trackpad pinch on Chrome), otherwise a
+     * wheel burst turns exactly one page. A new page turn requires either
+     * 200ms of quiet (fresh gesture), a direction reversal, or a re-acceleration
+     * after a decelerating tail (deliberate consecutive flicks).
+     */
+    wheelHandler(e: WheelEvent): void;
+    /**
+     * Recalculate drag/swipe event and reposition the frame of the slider
+     */
+    private updateAfterDrag;
+}

package/types/src/divina/DivinaScrolledPresenter.d.ts

@@ -0,0 +1,125 @@
+import { VisualNavigatorViewport } from "../Navigator.ts";
+import { DivinaPageManager } from "./DivinaPageManager.ts";
+import { DivinaSpreader } from "./DivinaSpreader.ts";
+export type DivinaScrolledEventKey = "scroll" | "position" | "tap" | "click";
+export type DivinaScrolledListener = (key: DivinaScrolledEventKey, data: unknown) => void;
+/**
+ * Vertical scrolled ("webtoon") presenter for Divina publications: all pages
+ * stacked in a native scroll container with no gaps, constrained to a
+ * configurable strip width, based on xbreader but improved
+ *
+ * Page offsets are cached and looked up with binary search so per-frame
+ * scroll work stays constant regardless of publication size.
+ */
+export declare class DivinaScrolledPresenter {
+    private readonly container;
+    private readonly spreader;
+    private readonly pool;
+    readonly scrollerElement: HTMLDivElement;
+    private stripWidth;
+    private destroyed;
+    private scrollRAF;
+    private restoreRAF;
+    private positionTimer;
+    private lastScrollTop;
+    /** Position within the strip as a fraction of total strip height (resize retention) */
+    private fraction;
+    private pageTops;
+    private pageHeights;
+    private stripHeightCached;
+    private viewportHeightCached;
+    private loadedIndices;
+    private lastWindowIndex;
+    private programmaticScroll;
+    private programmaticTimer;
+    private scrollTarget;
+    private animating;
+    private animRAF;
+    private animLastTime;
+    listener: DivinaScrolledListener;
+    constructor(container: HTMLElement, spreader: DivinaSpreader, pool: Map<number, DivinaPageManager>, stripWidth: number);
+    private readonly bscrollHandler;
+    private readonly bscrollendHandler;
+    private readonly banimStep;
+    private readonly buserTakeoverHandler;
+    private readonly bmousedownHandler;
+    private readonly bclickHandler;
+    private readonly btouchendHandler;
+    private readonly btouchstartHandler;
+    /** Display width of each page in the strip */
+    private get displayWidth();
+    /**
+     * Recomputes the cached page offsets and viewport metrics.
+     * Cheap relative to the per-frame layout reads it replaces, but still a
+     * forced layout: only call after actual layout changes.
+     */
+    private refreshLayoutCache;
+    /** The index of the last page whose top is at or above the given strip offset */
+    private indexAtOffset;
+    applyStripWidth(stripWidth: number): void;
+    private restoreFraction;
+    private updateFraction;
+    /** Top offset in pixels of the given page within the strip */
+    private pageTop;
+    private pageHeight;
+    /**
+     * The reading-order index of the current page: the last page whose top
+     * is above the middle of the viewport.
+     */
+    get currentIndex(): number;
+    /** Progression within the current page (0..1) */
+    get currentPageProgression(): number;
+    /**
+     * Marks the start of a programmatic scroll: "scroll" events are not
+     * reported to the host until the scroll settles (scrollend or timeout),
+     * so navigation doesn't masquerade as user scrolling.
+     */
+    private beginProgrammaticScroll;
+    private scrollendHandler;
+    /** Load the window around wherever the scroll settled */
+    private settleWindow;
+    /** Direct user input takes over any in-flight programmatic scroll */
+    private userTakeoverHandler;
+    private scrollHandler;
+    /** Load nearby pages, unload distant ones */
+    private updateWindow;
+    private touchStartY;
+    private lastTouchEnd;
+    private touchstartHandler;
+    private touchendHandler;
+    private mouseDownPos;
+    private mousedownHandler;
+    private clickHandler;
+    private emitPointer;
+    /**
+     * Scroll forward/backward by a fraction of the viewport.
+     * Repeated calls chain from the pending target, so rapid key presses
+     * (including autorepeat from a held key) extend one animation that keeps
+     * cruising instead of restarting; the target is clamped to stay within
+     * reach of the position so releasing the key stops promptly rather than
+     * replaying the queued distance.
+     * @returns whether scrolling was possible
+     */
+    next(animated?: boolean, stepPx?: number): boolean;
+    prev(animated?: boolean, stepPx?: number): boolean;
+    private scrollToTarget;
+    /**
+     * One frame of the owned scroll animation: exponential approach toward
+     * the (re)targetable scrollTarget, capped at a cruise speed. Under a held
+     * key the cap dominates and the scroll advances at constant speed; once
+     * input stops the exponential term eases it out into the target.
+     */
+    private animStep;
+    private stopAnimation;
+    /**
+     * Go to the top of a page, optionally at a progression within it.
+     * @returns whether the position changed
+     */
+    goToItem(itemIndex: number, animated?: boolean, progression?: number): boolean;
+    update(): Promise<void>;
+    get atStart(): boolean;
+    get atEnd(): boolean;
+    get viewport(): VisualNavigatorViewport;
+    resizeHandler(): void;
+    destroy(): Promise<void>;
+}