@readium/navigator 2.10.3 → 2.11.1

package/src/divina/DivinaSpreader.ts

@@ -0,0 +1,202 @@
+import { Link, Page, Publication, ReadingProgression } from "@readium/shared";
+import { Orientation, Spread } from "../epub/fxl/FXLSpreader.ts";
+
+/**
+ * A single page of a Divina publication, with its resolved layout properties.
+ * Unlike FXLSpreader, this model never mutates the publication's links.
+ */
+export class DivinaPage {
+    readonly link: Link;
+    readonly index: number; // Index in the reading order
+    page: Page = Page.center; // Resolved position within a spread
+    isLandscape: boolean;
+    addBlank = false; // Orphaned single page that must occupy a full spread on its own
+
+    constructor(link: Link, index: number) {
+        this.link = link;
+        this.index = index;
+        const orientation = link.properties?.otherProperties["orientation"];
+        this.isLandscape = orientation === Orientation.landscape ||
+            (orientation !== Orientation.portrait && (link.width || 0) > (link.height || 0));
+    }
+
+    /** 1-based page number */
+    get number(): number {
+        return this.index + 1;
+    }
+
+    get authoredPage(): Page | undefined {
+        return this.link.properties?.page;
+    }
+
+    /** Whether this page occupies both slots of a spread in double-page mode */
+    get double(): boolean {
+        return this.page === Page.center || this.isLandscape || this.addBlank;
+    }
+}
+
+/**
+ * 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 class DivinaSpreader {
+    readonly rtl: boolean;
+    shift = true; // Whether the first page stands alone (cover)
+    pages: DivinaPage[] = [];
+    spreads: DivinaPage[][] = [];
+    private itemToSlotArr: number[] = [];
+    private slotToItemArr: number[] = [];
+    private spreadOfItemArr: number[] = [];
+
+    constructor(publication: Publication) {
+        this.rtl = publication.metadata.effectiveReadingProgression === ReadingProgression.rtl;
+        this.pages = publication.readingOrder.items.map((link, index) => new DivinaPage(link, index));
+        this.index();
+        this.testShift();
+        this.buildSlots();
+    }
+
+    private index(redo = false) {
+        let nDouble = 0;
+        this.pages.forEach((page, index) => {
+            if(!page.authoredPage || redo) {
+                page.page = page.isLandscape ?
+                    Page.center :
+                    ((((this.shift ? 0 : 1) + index - nDouble) % 2) ?
+                        (this.rtl ? Page.right : Page.left) :
+                        (this.rtl ? Page.left : Page.right));
+            } else {
+                page.page = page.authoredPage;
+            }
+            if(page.double)
+                nDouble++;
+        });
+        this.buildSpreads();
+    }
+
+    private testShift() {
+        let wasLastSingle = false;
+        this.spreads.forEach((spread, index) => {
+            if(spread.length > 1) {
+                wasLastSingle = false;
+                return; // Only interested in single-page "spreads"
+            }
+            const single = spread[0];
+
+            // First page is landscape/spread-both means no shift
+            if(index === 0 && (single.isLandscape || single.link.properties?.otherProperties["spread"] === Spread.both))
+                this.shift = false;
+
+            // If the last spread was a true single, and this spread is a center page,
+            // the single was an orphaned half of a double page spread: pad it.
+            if(wasLastSingle && single.page === Page.center)
+                this.spreads[index - 1][0].addBlank = true;
+
+            // An orphaned component of a double page spread (that's not the first page)
+            if(!single.isLandscape && single.page !== Page.center && single.index > 0)
+                wasLastSingle = true;
+            else
+                wasLastSingle = false;
+        });
+        if(!this.shift) {
+            this.spreads = [];
+            this.index(true); // Re-index spreads
+        }
+    }
+
+    private buildSpreads() {
+        this.spreads = [];
+        let currentSet: DivinaPage[] = [];
+        this.pages.forEach((page, index) => {
+            if(!index && this.shift) {
+                this.spreads.push([page]);
+            } else if(page.page === Page.center) {
+                // A center (single) page spread: push immediately and reset current set
+                if(currentSet.length > 0) this.spreads.push(currentSet);
+                this.spreads.push([page]);
+                currentSet = [];
+            } else if(currentSet.length >= 2) { // Spread has max 2 pages
+                this.spreads.push(currentSet);
+                currentSet = [page];
+            } else
+                currentSet.push(page);
+        });
+        if(currentSet.length > 0) this.spreads.push(currentSet);
+    }
+
+    /**
+     * Builds the item <-> slot mappings for double-page mode.
+     * Slots are consumed in spread order; every spread takes exactly two slots.
+     */
+    private buildSlots() {
+        this.itemToSlotArr = new Array(this.pages.length);
+        this.slotToItemArr = [];
+        this.spreadOfItemArr = new Array(this.pages.length);
+        let slot = 0;
+        this.spreads.forEach((spread, spreadIndex) => {
+            spread.forEach((page) => {
+                this.itemToSlotArr[page.index] = slot;
+                this.spreadOfItemArr[page.index] = spreadIndex;
+                const width = spread.length === 1 ? 2 : 1;
+                for (let i = 0; i < width; i++)
+                    this.slotToItemArr[slot + i] = page.index;
+                slot += width;
+            });
+        });
+    }
+
+    /** Total number of slots (spread mode). Always even. */
+    get slotCount(): number {
+        return this.slotToItemArr.length;
+    }
+
+    /** Count of pages that take a double-width slot in spread mode */
+    get nDouble(): number {
+        return this.pages.reduce((n, p) => n + (p.double ? 1 : 0), 0);
+    }
+
+    slotOfItem(itemIndex: number): number {
+        return this.itemToSlotArr[Math.max(0, Math.min(itemIndex, this.pages.length - 1))] ?? 0;
+    }
+
+    itemOfSlot(slot: number): number {
+        return this.slotToItemArr[Math.max(0, Math.min(slot, this.slotToItemArr.length - 1))] ?? 0;
+    }
+
+    spreadIndexOfItem(itemIndex: number): number {
+        return this.spreadOfItemArr[Math.max(0, Math.min(itemIndex, this.pages.length - 1))] ?? 0;
+    }
+
+    spreadOfItem(itemIndex: number): DivinaPage[] {
+        return this.spreads[this.spreadIndexOfItem(itemIndex)];
+    }
+
+    /**
+     * 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 {
+        return this.spreadOfItem(itemIndex)?.length === 1;
+    }
+
+    findByHref(href: string): DivinaPage | undefined {
+        return this.pages.find(p => p.link.href === href);
+    }
+
+    /**
+     * 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 {
+        if(perPage < 2 || spread.length < 2) return Page.center;
+        return target === spread[0] ?
+            (this.rtl ? Page.right : Page.left) :
+            (this.rtl ? Page.left : Page.right);
+    }
+}

package/src/divina/DivinaVariantSelector.ts

@@ -0,0 +1,77 @@
+import { Link } from "@readium/shared";
+import { sML } from "@readium/helpers";
+
+/**
+ * User-selectable image quality for publications that provide alternate
+ * resolutions of their pages (RWPM `alternate` links).
+ */
+export enum DivinaQuality {
+    auto = "auto", // Match the display resolution
+    low = "low", // Smallest available variant
+    high = "high", // One step above the display resolution
+    max = "max", // Largest available variant
+}
+
+// Display caps for mobile devices: beyond this, decode lag, memory pressure
+// and canvas limits outweigh the quality gain (from xbreader)
+export const MOBILE_MAX_HEIGHT = 2560;
+export const MOBILE_MAX_WIDTH = 1800;
+
+// Accounts for rounding and slight aspect-ratio variance between variants
+const DIMENSION_TOLERANCE = 16;
+
+/** The link itself and its (bitmap) alternates, if any */
+export function gatherVariants(item: Link): Link[] {
+    const variants = item.alternates?.items ? [...item.alternates.items] : [];
+    variants.unshift(item);
+    return variants.filter(l => !l.type || l.type.startsWith("image/"));
+}
+
+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 function selectVariant(item: Link, opts: VariantSelectionOptions): Link {
+    const dim = (l: Link) => (opts.axis === "width" ? l.width : l.height) || 0;
+    // Variants without dimensions can't be compared, leave them out
+    const candidates = gatherVariants(item).filter(l => dim(l) > 0);
+    if (candidates.length <= 1) return candidates[0] || item;
+
+    const sorted = candidates.sort((a, b) => dim(a) - dim(b));
+    const mobile = sML.OS.iOS || sML.OS.Android;
+    const cap = mobile ? (opts.axis === "width" ? MOBILE_MAX_WIDTH : MOBILE_MAX_HEIGHT) : Infinity;
+    /** The largest variant that doesn't exceed the mobile cap (or the smallest overall) */
+    const capped = (pick: Link): Link => {
+        if (dim(pick) <= cap) return pick;
+        const fitting = sorted.filter(l => l === pick || dim(l) <= cap);
+        return fitting.length > 1 ? fitting[fitting.length - 2] : sorted[0];
+    };
+
+    switch (opts.quality) {
+        case DivinaQuality.low:
+            return sorted[0];
+        case DivinaQuality.max:
+            return capped(sorted[sorted.length - 1]);
+        default: {
+            const target = Math.min(opts.axis === "width" ? opts.targetWidth : opts.targetHeight, cap);
+            // Smallest variant that covers the display resolution
+            let pick = sorted.find(l => dim(l) >= target - DIMENSION_TOLERANCE) || sorted[sorted.length - 1];
+            if (opts.quality === DivinaQuality.high) {
+                const next = sorted[sorted.indexOf(pick) + 1];
+                if (next) pick = next;
+            }
+            return capped(pick);
+        }
+    }
+}

package/src/divina/index.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/src/divina/preferences/DivinaDefaults.ts

@@ -0,0 +1,37 @@
+import {
+  ensureBoolean,
+  ensureEnumValue,
+  ensureNonNegative,
+  ensureString,
+  ensureValueInRange
+} from "../../preferences/guards.ts";
+
+import { DivinaQuality } from "../DivinaVariantSelector.ts";
+import { stripWidthRangeConfig } from "./DivinaPreferences.ts";
+
+export interface IDivinaDefaults {
+  backgroundColor?: string | null,
+  constraint?: number | null,
+  quality?: DivinaQuality | null,
+  scrolled?: boolean | null,
+  spreads?: boolean | null,
+  stripWidth?: number | null
+}
+
+export class DivinaDefaults {
+  backgroundColor: string | null;
+  constraint: number;
+  quality: DivinaQuality;
+  scrolled: boolean | null;
+  spreads: boolean;
+  stripWidth: number;
+
+  constructor(defaults: IDivinaDefaults) {
+    this.backgroundColor = ensureString(defaults.backgroundColor) || null;
+    this.constraint = ensureNonNegative(defaults.constraint) || 0;
+    this.quality = ensureEnumValue<DivinaQuality>(defaults.quality, DivinaQuality) || DivinaQuality.auto;
+    this.scrolled = ensureBoolean(defaults.scrolled) ?? null;
+    this.spreads = ensureBoolean(defaults.spreads) ?? true;
+    this.stripWidth = ensureValueInRange(defaults.stripWidth, stripWidthRangeConfig.range) || 720;
+  }
+}

package/src/divina/preferences/DivinaPreferences.ts

@@ -0,0 +1,77 @@
+import { ConfigurablePreferences } from "../../preferences/Configurable.ts";
+import { RangeConfig } from "../../preferences/Types.ts";
+import { DivinaQuality } from "../DivinaVariantSelector.ts";
+
+import {
+  ensureBoolean,
+  ensureEnumValue,
+  ensureNonNegative,
+  ensureString,
+  ensureValueInRange
+} from "../../preferences/guards.ts";
+
+/**
+ * Maximum width in pixels of the vertical strip in scrolled mode.
+ */
+export const stripWidthRangeConfig: RangeConfig = {
+  range: [480, 2400],
+  step: 20
+}
+
+export interface IDivinaPreferences {
+  /** Background color behind the pages (equivalent of the EPUB page background theme) */
+  backgroundColor?: string | null,
+  /** Number of pixels to constrain the container width by (e.g. for docked panels) */
+  constraint?: number | null,
+  /** Image quality when the publication offers alternate resolutions */
+  quality?: DivinaQuality | null,
+  /** Display the publication as a vertical scroll instead of horizontal pages */
+  scrolled?: boolean | null,
+  /** Display two pages side-by-side on landscape viewports (paged mode only) */
+  spreads?: boolean | null,
+  /** Maximum width in pixels of the vertical strip in scrolled mode */
+  stripWidth?: number | null
+}
+
+export class DivinaPreferences implements ConfigurablePreferences<DivinaPreferences> {
+  backgroundColor?: string | null;
+  constraint?: number | null;
+  quality?: DivinaQuality | null;
+  scrolled?: boolean | null;
+  spreads?: boolean | null;
+  stripWidth?: number | null;
+
+  constructor(preferences: IDivinaPreferences = {}) {
+    this.backgroundColor = ensureString(preferences.backgroundColor);
+    this.constraint = ensureNonNegative(preferences.constraint);
+    this.quality = ensureEnumValue<DivinaQuality>(preferences.quality, DivinaQuality);
+    this.scrolled = ensureBoolean(preferences.scrolled);
+    this.spreads = ensureBoolean(preferences.spreads);
+    this.stripWidth = ensureValueInRange(preferences.stripWidth, stripWidthRangeConfig.range);
+  }
+
+  static serialize(preferences: DivinaPreferences): string {
+    const { ...properties } = preferences;
+    return JSON.stringify(properties);
+  }
+
+  static deserialize(preferences: string): DivinaPreferences | null {
+    try {
+      const parsedPreferences = JSON.parse(preferences);
+      return new DivinaPreferences(parsedPreferences);
+    } catch (error) {
+      console.error("Failed to deserialize preferences:", error);
+      return null;
+    }
+  }
+
+  merging(other: DivinaPreferences): DivinaPreferences {
+    const merged: IDivinaPreferences = { ...this };
+    for (const key of Object.keys(other) as (keyof IDivinaPreferences)[]) {
+      if (other[key] !== undefined) {
+        (merged as Record<string, unknown>)[key] = other[key];
+      }
+    }
+    return new DivinaPreferences(merged);
+  }
+}

package/src/divina/preferences/DivinaPreferencesEditor.ts

@@ -0,0 +1,96 @@
+import { Layout, Metadata } from "@readium/shared";
+
+import { IPreferencesEditor } from "../../preferences/PreferencesEditor.ts";
+import { BooleanPreference, EnumPreference, Preference, RangePreference } from "../../preferences/Preference.ts";
+import { DivinaQuality } from "../DivinaVariantSelector.ts";
+import { DivinaPreferences, stripWidthRangeConfig } from "./DivinaPreferences.ts";
+import { DivinaSettings } from "./DivinaSettings.ts";
+
+export class DivinaPreferencesEditor implements IPreferencesEditor {
+  preferences: DivinaPreferences;
+  private settings: DivinaSettings;
+  private metadata: Metadata;
+
+  constructor(initialPreferences: DivinaPreferences, settings: DivinaSettings, metadata: Metadata) {
+    this.preferences = new DivinaPreferences({ ...initialPreferences });
+    this.settings = settings;
+    this.metadata = metadata;
+  }
+
+  clear(): void {
+    this.preferences = new DivinaPreferences({
+      backgroundColor: null,
+      constraint: null,
+      quality: null,
+      scrolled: null,
+      spreads: null,
+      stripWidth: null
+    });
+  }
+
+  private updatePreference<K extends keyof DivinaPreferences>(key: K, value: DivinaPreferences[K]) {
+    this.preferences[key] = value;
+  }
+
+  private get manifestScrolled(): boolean {
+    return this.metadata.effectiveLayout === Layout.scrolled;
+  }
+
+  get backgroundColor(): Preference<string> {
+    return new Preference<string>({
+      initialValue: this.preferences.backgroundColor,
+      effectiveValue: this.settings.backgroundColor,
+      isEffective: true,
+      onChange: (newValue) => {
+        this.updatePreference("backgroundColor", newValue ?? null);
+      }
+    });
+  }
+
+  get quality(): EnumPreference<DivinaQuality> {
+    return new EnumPreference<DivinaQuality>({
+      initialValue: this.preferences.quality,
+      effectiveValue: this.settings.quality,
+      isEffective: true,
+      onChange: (newValue) => {
+        this.updatePreference("quality", newValue ?? null);
+      },
+      supportedValues: [DivinaQuality.auto, DivinaQuality.low, DivinaQuality.high, DivinaQuality.max]
+    });
+  }
+
+  get scrolled(): BooleanPreference {
+    return new BooleanPreference({
+      initialValue: this.preferences.scrolled,
+      effectiveValue: this.settings.scrolled,
+      isEffective: !this.manifestScrolled,
+      onChange: (newValue) => {
+        this.updatePreference("scrolled", newValue ?? null);
+      }
+    });
+  }
+
+  get spreads(): BooleanPreference {
+    return new BooleanPreference({
+      initialValue: this.preferences.spreads,
+      effectiveValue: this.settings.spreads,
+      isEffective: !this.settings.scrolled,
+      onChange: (newValue) => {
+        this.updatePreference("spreads", newValue ?? null);
+      }
+    });
+  }
+
+  get stripWidth(): RangePreference<number> {
+    return new RangePreference<number>({
+      initialValue: this.preferences.stripWidth,
+      effectiveValue: this.settings.stripWidth,
+      isEffective: this.settings.scrolled,
+      onChange: (newValue) => {
+        this.updatePreference("stripWidth", newValue ?? null);
+      },
+      supportedRange: stripWidthRangeConfig.range,
+      step: stripWidthRangeConfig.step
+    });
+  }
+}

package/src/divina/preferences/DivinaSettings.ts

@@ -0,0 +1,38 @@
+import { ConfigurableSettings } from "../../preferences/Configurable.ts";
+import { DivinaQuality } from "../DivinaVariantSelector.ts";
+import { DivinaDefaults } from "./DivinaDefaults.ts";
+import { DivinaPreferences } from "./DivinaPreferences.ts";
+
+export interface IDivinaSettings {
+  backgroundColor?: string | null,
+  constraint?: number | null,
+  quality?: DivinaQuality | null,
+  scrolled?: boolean | null,
+  spreads?: boolean | null,
+  stripWidth?: number | null
+}
+
+export class DivinaSettings implements ConfigurableSettings {
+  backgroundColor: string | null;
+  constraint: number;
+  quality: DivinaQuality;
+  scrolled: boolean;
+  spreads: boolean;
+  stripWidth: number;
+
+  /**
+   * @param manifestScrolled Whether the publication itself declares `layout: scrolled`.
+   * A natively scrolled publication (e.g. webtoon) cannot be switched to paged mode,
+   * while a fixed publication can be switched to scrolled by the user.
+   */
+  constructor(preferences: DivinaPreferences, defaults: DivinaDefaults, manifestScrolled: boolean) {
+    this.backgroundColor = preferences.backgroundColor ?? defaults.backgroundColor;
+    this.constraint = preferences.constraint ?? defaults.constraint;
+    this.quality = preferences.quality ?? defaults.quality;
+    this.scrolled = manifestScrolled
+      ? true
+      : (preferences.scrolled ?? defaults.scrolled ?? false);
+    this.spreads = preferences.spreads ?? defaults.spreads;
+    this.stripWidth = preferences.stripWidth ?? defaults.stripWidth;
+  }
+}

package/src/divina/preferences/index.ts

@@ -0,0 +1,4 @@
+export * from "./DivinaDefaults.ts";
+export * from "./DivinaPreferences.ts";
+export * from "./DivinaPreferencesEditor.ts";
+export * from "./DivinaSettings.ts";

package/src/divina/protection/DivinaNavigatorProtector.ts

@@ -0,0 +1,44 @@
+import { NavigatorProtector } from "../../protection/NavigatorProtector.ts";
+import { DragAndDropProtector } from "../../protection/DragAndDropProtector.ts";
+import { CopyProtector } from "../../protection/CopyProtector.ts";
+import { IContentProtectionConfig } from "../../Navigator.ts";
+
+/**
+ * Content protection for the Divina navigator. Because Divina renders images
+ * directly in the host DOM (no iframes), the in-frame halves of the EPUB
+ * protection (copy and drag-and-drop blocking) must run host-side instead,
+ * like the audio navigator does.
+ */
+export class DivinaNavigatorProtector extends NavigatorProtector {
+    private dragAndDropProtector?: DragAndDropProtector;
+    private copyProtector?: CopyProtector;
+
+    constructor(config: IContentProtectionConfig = {}) {
+        super(config);
+
+        if (config.disableDragAndDrop) {
+            this.dragAndDropProtector = new DragAndDropProtector({
+                onDragDetected: (dataTransferTypes) => {
+                    this.dispatchSuspiciousActivity("drag_detected", { dataTransferTypes, targetFrameSrc: "" });
+                },
+                onDropDetected: (dataTransferTypes, fileCount) => {
+                    this.dispatchSuspiciousActivity("drop_detected", { dataTransferTypes, fileCount, targetFrameSrc: "" });
+                }
+            });
+        }
+
+        if (config.protectCopy) {
+            this.copyProtector = new CopyProtector({
+                onCopyBlocked: () => {
+                    this.dispatchSuspiciousActivity("bulk_copy", { targetFrameSrc: "" });
+                }
+            });
+        }
+    }
+
+    public override destroy() {
+        super.destroy();
+        this.dragAndDropProtector?.destroy();
+        this.copyProtector?.destroy();
+    }
+}