@readium/navigator 2.6.1 → 2.7.0-alpha.1

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

@@ -0,0 +1,113 @@
+import { Layout, Link, Locator, Publication, ReadingProgression } 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;
+    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 _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 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(): 1 | 2;
+    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>;
+}

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

@@ -0,0 +1,65 @@
+import { Link, Page, Publication } from "@readium/shared";
+/**
+ * A single page of a Divina publication, with its resolved layout properties.
+ * Unlike FXLSpreader, this model never mutates the publication's links.
+ */
+export declare class DivinaPage {
+    readonly link: Link;
+    readonly index: number;
+    page: Page;
+    isLandscape: boolean;
+    addBlank: boolean;
+    constructor(link: Link, index: number);
+    /** 1-based page number */
+    get number(): number;
+    get authoredPage(): Page | undefined;
+    /** Whether this page occupies both slots of a spread in double-page mode */
+    get double(): boolean;
+}
+/**
+ * Computes synthetic spreads for a Divina publication from the `page`
+ * (left/right/center) link properties, falling back to computed alternation.
+ *
+ * Slot model (used by the paged presenter): in double-page mode every spread
+ * occupies exactly two slots — a pair is 1+1, and a lone page (center,
+ * landscape or orphaned/addBlank) takes a double-width slot. This keeps
+ * slide indices (always even) aligned with spread boundaries.
+ */
+export declare class DivinaSpreader {
+    readonly rtl: boolean;
+    shift: boolean;
+    pages: DivinaPage[];
+    spreads: DivinaPage[][];
+    private itemToSlotArr;
+    private slotToItemArr;
+    private spreadOfItemArr;
+    constructor(publication: Publication);
+    private index;
+    private testShift;
+    private buildSpreads;
+    /**
+     * Builds the item <-> slot mappings for double-page mode.
+     * Slots are consumed in spread order; every spread takes exactly two slots.
+     */
+    private buildSlots;
+    /** Total number of slots (spread mode). Always even. */
+    get slotCount(): number;
+    /** Count of pages that take a double-width slot in spread mode */
+    get nDouble(): number;
+    slotOfItem(itemIndex: number): number;
+    itemOfSlot(slot: number): number;
+    spreadIndexOfItem(itemIndex: number): number;
+    spreadOfItem(itemIndex: number): DivinaPage[];
+    /**
+     * Whether the page occupies a full spread on its own in double-page mode
+     * (and therefore takes a double-width slot). This mirrors buildSlots()
+     * exactly: any page alone in its spread is double.
+     */
+    isDouble(itemIndex: number): boolean;
+    findByHref(href: string): DivinaPage | undefined;
+    /**
+     * The position of a page within a spread, viewport-wise:
+     * left/right of the gutter, or centered when displayed alone.
+     */
+    spreadPosition(spread: DivinaPage[], target: DivinaPage, perPage: number): Page;
+}

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

@@ -0,0 +1,30 @@
+import { Link } from "@readium/shared";
+/**
+ * User-selectable image quality for publications that provide alternate
+ * resolutions of their pages (RWPM `alternate` links).
+ */
+export declare enum DivinaQuality {
+    auto = "auto",// Match the display resolution
+    low = "low",// Smallest available variant
+    high = "high",// One step above the display resolution
+    max = "max"
+}
+export declare const MOBILE_MAX_HEIGHT = 2560;
+export declare const MOBILE_MAX_WIDTH = 1800;
+/** The link itself and its (bitmap) alternates, if any */
+export declare function gatherVariants(item: Link): Link[];
+export interface VariantSelectionOptions {
+    /** Display size of the page in device pixels (CSS box × devicePixelRatio) */
+    targetWidth: number;
+    targetHeight: number;
+    /** The axis that constrains the display: height in paged mode, width in scrolled mode */
+    axis: "width" | "height";
+    quality: DivinaQuality;
+}
+/**
+ * Selects the most appropriate variant of a page image for the current
+ * display, based purely on the choices the manifest offers: the smallest
+ * variant that covers the display resolution (in device pixels), biased by
+ * the quality preference, and capped on mobile devices.
+ */
+export declare function selectVariant(item: Link, opts: VariantSelectionOptions): Link;

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

@@ -0,0 +1,8 @@
+export * from "./DivinaNavigator.ts";
+export * from "./DivinaSpreader.ts";
+export * from "./DivinaPageManager.ts";
+export * from "./DivinaPagedPresenter.ts";
+export * from "./DivinaScrolledPresenter.ts";
+export * from "./DivinaPeripherals.ts";
+export * from "./DivinaVariantSelector.ts";
+export * from "./preferences/index.ts";

package/types/src/divina/preferences/DivinaDefaults.d.ts

@@ -0,0 +1,18 @@
+import { DivinaQuality } from "../DivinaVariantSelector.ts";
+export interface IDivinaDefaults {
+    backgroundColor?: string | null;
+    constraint?: number | null;
+    quality?: DivinaQuality | null;
+    scrolled?: boolean | null;
+    spreads?: boolean | null;
+    stripWidth?: number | null;
+}
+export declare class DivinaDefaults {
+    backgroundColor: string | null;
+    constraint: number;
+    quality: DivinaQuality;
+    scrolled: boolean | null;
+    spreads: boolean;
+    stripWidth: number;
+    constructor(defaults: IDivinaDefaults);
+}