@readium/navigator 2.4.0-beta.1 → 2.4.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator",
-  "version": "2.4.0-beta.1",
+  "version": "2.4.0-beta.10",
   "type": "module",
   "description": "Next generation SDK for publications in Web Apps",
   "author": "readium",

package/src/audio/AudioNavigator.ts

@@ -1,5 +1,5 @@
-import { Link, Locator, LocatorLocations, Publication } from "@readium/shared";
-import { MediaNavigator } from "../Navigator";
+import { Link, Locator, LocatorLocations, Publication, Timeline, TimelineItem } from "@readium/shared";
+import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../Navigator";
 import { Configurable } from "../preferences";
 import { WebAudioEngine, PlaybackState } from "./engine";
 import {
@@ -11,10 +11,15 @@ import {
     IAudioDefaults
 } from "./preferences";
 import { AudioPoolManager } from "./AudioPoolManager";
+import { ContextMenuEvent, KeyboardEventData, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
+import { AudioNavigatorProtector } from "./protection/AudioNavigatorProtector";
+import { NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT } from "../protection/NavigatorProtector";
+import { KeyboardPeripherals, NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT } from "../peripherals/KeyboardPeripherals";
 
 export interface AudioNavigatorListeners {
     trackLoaded: (media: HTMLMediaElement) => void;
     positionChanged: (locator: Locator) => void;
+    timelineItemChanged: (item: TimelineItem | undefined) => void;
     error: (error: any, locator: Locator) => void;
     trackEnded: (locator: Locator) => void;
     play: (locator: Locator) => void;
@@ -23,17 +28,40 @@ export interface AudioNavigatorListeners {
     stalled: (isStalled: boolean) => void;
     seeking: (isSeeking: boolean) => void;
     seekable: (seekable: TimeRanges) => void;
+    contentProtection: (type: string, data: SuspiciousActivityEvent) => void;
+    peripheral: (data: KeyboardEventData) => void;
+    contextMenu: (data: ContextMenuEvent) => void;
 }
 
+const defaultListeners = (listeners: Partial<AudioNavigatorListeners>): AudioNavigatorListeners => ({
+    trackLoaded: listeners.trackLoaded ?? (() => {}),
+    positionChanged: listeners.positionChanged ?? (() => {}),
+    timelineItemChanged: listeners.timelineItemChanged ?? (() => {}),
+    error: listeners.error ?? (() => {}),
+    trackEnded: listeners.trackEnded ?? (() => {}),
+    play: listeners.play ?? (() => {}),
+    pause: listeners.pause ?? (() => {}),
+    metadataLoaded: listeners.metadataLoaded ?? (() => {}),
+    stalled: listeners.stalled ?? (() => {}),
+    seeking: listeners.seeking ?? (() => {}),
+    seekable: listeners.seekable ?? (() => {}),
+    contentProtection: listeners.contentProtection ?? (() => {}),
+    peripheral: listeners.peripheral ?? (() => {}),
+    contextMenu: listeners.contextMenu ?? (() => {}),
+});
+
 export interface AudioNavigatorConfiguration {
     preferences: IAudioPreferences;
     defaults: IAudioDefaults;
+    contentProtection?: IContentProtectionConfig;
+    keyboardPeripherals?: IKeyboardPeripheralsConfig;
 }
 
 export class AudioNavigator extends MediaNavigator implements Configurable<AudioSettings, AudioPreferences> {
     private readonly pub: Publication;
     private positionPollInterval: ReturnType<typeof setInterval> | null = null;
     private navigationId: number = 0;
+    private _playIntent: boolean = false;
     private listeners: AudioNavigatorListeners;
     private currentLocation!: Locator;
 
@@ -41,7 +69,13 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     private _defaults: AudioDefaults;
     private _settings: AudioSettings;
     private _preferencesEditor: AudioPreferencesEditor | null = null;
+    private _mediaSessionEnabled: boolean = false;
     private pool: AudioPoolManager;
+    private readonly _navigatorProtector: AudioNavigatorProtector | null = null;
+    private _currentTimelineItem: TimelineItem | undefined;
+    private readonly _keyboardPeripheralsManager: KeyboardPeripherals | null = null;
+    private readonly _suspiciousActivityListener: ((event: Event) => void) | null = null;
+    private readonly _keyboardPeripheralListener: ((event: Event) => void) | null = null;
 
     constructor(publication: Publication, listeners: AudioNavigatorListeners, initialPosition?: Locator, configuration: AudioNavigatorConfiguration = {
         preferences: {},
@@ -49,11 +83,11 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     }) {
         super();
         this.pub = publication;
+        this.listeners = defaultListeners(listeners);
 
         this._preferences = new AudioPreferences(configuration.preferences);
         this._defaults = new AudioDefaults(configuration.defaults);
         this._settings = new AudioSettings(this._preferences, this._defaults);
-        this.listeners = listeners;
 
         if (initialPosition) {
             this.currentLocation = this.ensureLocatorLocations(initialPosition);
@@ -81,27 +115,59 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 state: {
                     currentTime: initialTime,
                     duration: 0,
-                    volume: this._settings.volume
                 } as PlaybackState,
                 playWhenReady: false,
                 index: trackIndex
             }
         });
 
-        this.pool = new AudioPoolManager(audioEngine);
-        this.setupEventListeners();
+        this.pool = new AudioPoolManager(audioEngine, publication);
+
+        // Initialize content protection
+        const contentProtection = configuration.contentProtection || {};
+        const keyboardPeripherals = this.mergeKeyboardPeripherals(
+            contentProtection,
+            configuration.keyboardPeripherals || []
+        );
+
+        if (contentProtection.disableContextMenu ||
+            contentProtection.checkAutomation ||
+            contentProtection.checkIFrameEmbedding ||
+            contentProtection.monitorDevTools ||
+            contentProtection.protectPrinting?.disable ||
+            contentProtection.disableDragAndDrop ||
+            contentProtection.protectCopy) {
+            this._navigatorProtector = new AudioNavigatorProtector(contentProtection);
+            this._suspiciousActivityListener = (event: Event) => {
+                const { type, ...detail } = (event as CustomEvent).detail;
+                if (type === "context_menu") {
+                    this.listeners.contextMenu(detail as ContextMenuEvent);
+                } else {
+                    this.listeners.contentProtection(type, detail as SuspiciousActivityEvent);
+                }
+            };
+            window.addEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);
+        }
 
-        if (this._settings.enableMediaSession) {
-            this.setupMediaSession();
+        if (keyboardPeripherals.length > 0) {
+            this._keyboardPeripheralsManager = new KeyboardPeripherals({ keyboardPeripherals });
+            this._keyboardPeripheralListener = (event: Event) => {
+                this.listeners.peripheral((event as CustomEvent).detail);
+            };
+            window.addEventListener(NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT, this._keyboardPeripheralListener);
         }
 
-        this.pool.setCurrentAudio(initialHref, this.pub, trackIndex, "forward");
+        this.setupEventListeners();
+        this.applyPreferences();
+
+        this.pool.setCurrentAudio(trackIndex, "forward");
 
         // Load and seek to initial position, then notify consumer.
         // No cancellation needed here — the constructor runs once.
         this.waitForLoadedAndSeeked(initialTime)
             .then(() => {
                 this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
+                this._notifyTimelineChange(this.currentLocator);
                 this.listeners.positionChanged(this.currentLocator);
             })
             .catch(() => {
@@ -126,7 +192,6 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     }
 
     private applyPreferences(): void {
-        const oldSettings = this._settings;
         this._settings = new AudioSettings(this._preferences, this._defaults);
 
         if (this._preferencesEditor !== null) {
@@ -136,9 +201,11 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.pool.audioEngine.setVolume(this._settings.volume);
         this.pool.audioEngine.setPlaybackRate(this._settings.playbackRate, this._settings.preservePitch);
 
-        if (this._settings.enableMediaSession && !oldSettings.enableMediaSession) {
+        if (this._settings.enableMediaSession && !this._mediaSessionEnabled) {
+            this._mediaSessionEnabled = true;
             this.setupMediaSession();
-        } else if (!this._settings.enableMediaSession && oldSettings.enableMediaSession) {
+        } else if (!this._settings.enableMediaSession && this._mediaSessionEnabled) {
+            this._mediaSessionEnabled = false;
             this.destroyMediaSession();
         }
     }
@@ -147,6 +214,18 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         return this.pub;
     }
 
+    get timeline(): Timeline {
+        return this.pub.timeline;
+    }
+
+    private _notifyTimelineChange(locator: Locator): void {
+        const item = this.pub.timeline.locate(locator);
+        if (item !== this._currentTimelineItem) {
+            this._currentTimelineItem = item;
+            this.listeners.timelineItemChanged(item);
+        }
+    }
+
     private ensureLocatorLocations(locator: Locator): Locator {
         return new Locator({
             ...locator,
@@ -264,6 +343,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 fragments: [`t=${this.duration}`]
             }));
             this.listeners.trackEnded(this.currentLocator);
+            if (!this.canGoForward) return;
             await this.nextTrack();
             if (this._settings.autoPlay) this.play();
         });
@@ -293,6 +373,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                     progression,
                     fragments: [`t=${currentTime}`]
                 }));
+                this._notifyTimelineChange(this.currentLocation);
                 this.listeners.positionChanged(this.currentLocation);
             }
         });
@@ -300,6 +381,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.pool.audioEngine.on("seeking", () => this.listeners.seeking(true));
         this.pool.audioEngine.on("waiting", () => this.listeners.seeking(true));
         this.pool.audioEngine.on("stalled", () => this.listeners.stalled(true));
+        this.pool.audioEngine.on("canplaythrough", () => this.listeners.stalled(false));
         this.pool.audioEngine.on("progress", (seekable: TimeRanges) => this.listeners.seekable(seekable));
         
         this.pool.audioEngine.on("loadedmetadata", () => {
@@ -322,12 +404,14 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         if (!("mediaSession" in navigator)) return;
         const trackIndex = this.currentTrackIndex();
         const track = this.pub.readingOrder.items[trackIndex];
+        const cover = this.pub.getCover();
         navigator.mediaSession.metadata = new MediaMetadata({
             title: track?.title || `Track ${trackIndex + 1}`,
             artist: this.pub.metadata.authors
                 ? this.pub.metadata.authors.items.map((a) => a.name.getTranslation()).join(", ")
                 : undefined,
             album: this.pub.metadata.title.getTranslation(),
+            artwork: cover ? [{ src: cover.href, type: cover.type }] : undefined,
         });
     }
 
@@ -342,6 +426,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 progression,
                 fragments: [`t=${currentTime}`]
             }));
+            this._notifyTimelineChange(this.currentLocation);
             this.listeners.positionChanged(this.currentLocation);
         }, this._settings.pollInterval);
     }
@@ -367,17 +452,25 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
             const id = ++this.navigationId;
             const direction: "forward" | "backward" = trackIndex >= this.currentTrackIndex() ? "forward" : "backward";
-            const wasPlaying = this.isPlaying;
+            // Use _playIntent rather than isPlaying — setMediaElement resets the
+            // engine's playing flag, so a rapid second go() would see false and
+            // never resume playback.
+            const wasPlaying = this.isPlaying || this._playIntent;
+            this._playIntent = wasPlaying;
 
             this.stopPositionPolling();
-            this.pool.setCurrentAudio(href, this.pub, trackIndex, direction);
+            this.pool.setCurrentAudio(trackIndex, direction);
             this.currentLocation = locator.copyWithLocations(locator.locations);
 
             await this.waitForLoadedAndSeeked(time, id);
 
-            if (id !== this.navigationId) return;
+            if (id !== this.navigationId) {
+                cb(false);
+                return;
+            }
 
             this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
+            this._notifyTimelineChange(this.currentLocator);
             this.listeners.positionChanged(this.currentLocator);
 
             if (this._settings.enableMediaSession) {
@@ -390,6 +483,8 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         } catch (error) {
             console.error("Failed to go to locator:", error);
             cb(false);
+        } finally {
+            this._playIntent = false;
         }
     }
 
@@ -399,7 +494,8 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             cb(false);
             return;
         }
-        const locator = this.createLocator(trackIndex, 0);
+        const time = link.locator.locations?.time() ?? 0;
+        const locator = this.createLocator(trackIndex, time);
         await this.go(locator, _animated, cb);
     }
 
@@ -492,6 +588,14 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     destroy(): void {
         this.stopPositionPolling();
         this.destroyMediaSession();
+        if (this._suspiciousActivityListener) {
+            window.removeEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);
+        }
+        if (this._keyboardPeripheralListener) {
+            window.removeEventListener(NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT, this._keyboardPeripheralListener);
+        }
+        this._navigatorProtector?.destroy();
+        this._keyboardPeripheralsManager?.destroy();
         this.pool.destroy();
     }
 }

package/src/audio/AudioPoolManager.ts

@@ -1,120 +1,130 @@
-import { Publication } from "@readium/shared";
+import { Link, Publication } from "@readium/shared";
 import { WebAudioEngine } from "./engine/WebAudioEngine";
 
+const UPPER_BOUNDARY = 1;
+const LOWER_BOUNDARY = 1;
+
 export class AudioPoolManager {
-    private preloadedElements: Map<string, HTMLAudioElement> = new Map();
+    private readonly pool: Map<string, HTMLAudioElement> = new Map();
     private _audioEngine: WebAudioEngine;
+    private readonly _publication: Publication;
+    private readonly _supportedAudioTypes: Map<string, "probably" | "maybe">;
 
-    constructor(audioEngine: WebAudioEngine) {
+    constructor(audioEngine: WebAudioEngine, publication: Publication) {
         this._audioEngine = audioEngine;
+        this._publication = publication;
+        this._supportedAudioTypes = this.detectSupportedAudioTypes();
     }
 
-    get audioEngine(): WebAudioEngine {
-        return this._audioEngine;
+    private detectSupportedAudioTypes(): Map<string, "probably" | "maybe"> {
+        const audio = document.createElement("audio");
+        const unique = new Set<string>();
+        for (const link of this._publication.readingOrder.items) {
+            if (link.type) unique.add(link.type);
+            for (const alt of link.alternates?.items ?? []) {
+                if (alt.type) unique.add(alt.type);
+            }
+        }
+        const supported = new Map<string, "probably" | "maybe">();
+        for (const type of unique) {
+            const result = audio.canPlayType(type);
+            if (result !== "") supported.set(type, result as "probably" | "maybe");
+        }
+        return supported;
     }
 
-    /**
-     * Sets the current audio by href, using preloaded element if available or loading otherwise,
-     * and preloads adjacent tracks.
-     * @param href The URL of the audio resource.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
-     */
-    setCurrentAudio(href: string, publication: Publication, currentIndex: number, direction: 'forward' | 'backward'): void {
-        // When Web Audio is active, preloaded elements lack crossOrigin="anonymous"
-        // and cannot be connected to MediaElementAudioSourceNode, so bypass the pool.
-        const preloadedElement = !this.audioEngine.isWebAudioActive ? this.get(href) : undefined;
-        if (preloadedElement) {
-            this.audioEngine.setMediaElement(preloadedElement);
-            this.clear(href);
-        } else {
-            this.clear(href);
-            this.audioEngine.loadAudio(href);
+    private pickPlayableHref(link: Link): string {
+        const candidates = [link, ...(link.alternates?.items ?? [])];
+        let best: { href: string; confidence: "probably" | "maybe" } | undefined;
+        for (const candidate of candidates) {
+            if (!candidate.type) continue;
+            const confidence = this._supportedAudioTypes.get(candidate.type);
+            if (!confidence) continue;
+            if (confidence === "probably") return candidate.href;
+            if (!best) best = { href: candidate.href, confidence };
         }
-        this.preloadAdjacent(publication, currentIndex, direction);
+        return best?.href ?? link.href;
     }
-    preload(href: string): void {
-        if (this.preloadedElements.has(href)) {
-            return; // Already preloaded
-        }
 
-        const audioElement = document.createElement("audio");
-        audioElement.preload = "auto";
-        audioElement.src = href;
-        audioElement.load(); // Start buffering
-
-        this.preloadedElements.set(href, audioElement);
+    get audioEngine(): WebAudioEngine {
+        return this._audioEngine;
     }
 
     /**
-     * Retrieves a preloaded audio element by URL.
-     * @param href The URL of the audio resource.
-     * @returns The preloaded HTMLAudioElement, or undefined if not preloaded.
+     * Ensures an audio element exists in the pool for the given href.
+     * If one already exists, it is left untouched (preserving its buffered data).
      */
-    get(href: string): HTMLAudioElement | undefined {
-        return this.preloadedElements.get(href);
+    private ensure(href: string): HTMLAudioElement {
+        let element = this.pool.get(href);
+        if (!element) {
+            element = document.createElement("audio");
+            element.preload = "auto";
+            // When Web Audio is active CORS already succeeded, so preload
+            // with crossOrigin to avoid a destructive reload at swap time.
+            if (this._audioEngine.isWebAudioActive) {
+                element.crossOrigin = "anonymous";
+            }
+            element.src = href;
+            element.load();
+            this.pool.set(href, element);
+        }
+        return element;
     }
 
     /**
-     * Removes a preloaded element from the pool.
-     * @param href The URL of the audio resource.
+     * Updates the pool around the given index: ensures elements exist within
+     * the LOWER_BOUNDARY and disposes those beyond the UPPER_BOUNDARY.
      */
-    clear(href: string): void {
-        this.preloadedElements.delete(href);
-    }
+    private update(currentIndex: number): void {
+        const items = this._publication.readingOrder.items;
+        const keep = new Set<string>();
 
-    /**
-     * Preloads the next track in the reading order.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadNext(publication: Publication, currentIndex: number): void {
-        const nextIndex = currentIndex + 1;
-        if (nextIndex < publication.readingOrder.items.length) {
-            const nextLink = publication.readingOrder.items[nextIndex];
-            if (nextLink.href) {
-                this.preload(nextLink.href);
+        for (let j = 0; j < items.length; j++) {
+            const href = this.pickPlayableHref(items[j]);
+            if (j >= currentIndex - LOWER_BOUNDARY && j <= currentIndex + LOWER_BOUNDARY) {
+                this.ensure(href);
+                keep.add(href);
+            } else if (j >= currentIndex - UPPER_BOUNDARY && j <= currentIndex + UPPER_BOUNDARY) {
+                // Between lower and upper: keep if already loaded, don't create
+                if (this.pool.has(href)) {
+                    keep.add(href);
+                }
             }
         }
-    }
 
-    /**
-     * Preloads the previous track in the reading order.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     */
-    preloadPrevious(publication: Publication, currentIndex: number): void {
-        const prevIndex = currentIndex - 1;
-        if (prevIndex >= 0) {
-            const prevLink = publication.readingOrder.items[prevIndex];
-            if (prevLink.href) {
-                this.preload(prevLink.href);
+        // Dispose elements beyond the upper boundary
+        for (const [href, element] of this.pool) {
+            if (!keep.has(href)) {
+                element.removeAttribute("src");
+                element.load(); // release network resources
+                this.pool.delete(href);
             }
         }
     }
 
     /**
-     * Preloads adjacent tracks (previous and next) for smoother navigation.
-     * @param publication The publication containing the reading order.
-     * @param currentIndex The current track index.
-     * @param direction The navigation direction ('forward' or 'backward').
+     * Sets the current audio for playback at the given track index.
+     * The element is always sourced from the pool — never loaded ad-hoc on the engine.
      */
-    preloadAdjacent(publication: Publication, currentIndex: number, direction: 'forward' | 'backward' = 'forward'): void {
-        if (direction === 'forward') {
-            this.preloadNext(publication, currentIndex);
-            this.preloadPrevious(publication, currentIndex);
-        } else {
-            this.preloadPrevious(publication, currentIndex);
-            this.preloadNext(publication, currentIndex);
-        }
+    setCurrentAudio(currentIndex: number, _direction: 'forward' | 'backward'): void {
+        const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
+        const element = this.ensure(href);
+
+        this.audioEngine.setMediaElement(element);
+
+        // Remove from pool so the engine fully owns it and we don't dispose it
+        this.pool.delete(href);
+
+        // Manage the pool around the new position
+        this.update(currentIndex);
     }
 
-    /**
-     * Destroys the pool by stopping the engine and clearing all preloaded elements.
-     */
     destroy(): void {
         this.audioEngine.stop();
-        this.preloadedElements.clear();
+        for (const [, element] of this.pool) {
+            element.removeAttribute("src");
+            element.load();
+        }
+        this.pool.clear();
     }
 }

package/src/audio/engine/AudioEngine.ts

@@ -11,11 +11,6 @@ export interface PlaybackState {
      * The duration of the audio resource.
      */
     duration: number;
-
-    /**
-     * The volume of the audio resource.
-     */
-    volume: number;
 }
 
 /**
@@ -45,12 +40,6 @@ export interface AudioEngine {
      */
     playback: Playback;
 
-    /**
-     * Loads the audio resource at the given URL.
-     * @param url The URL of the audio resource.
-     */
-    loadAudio(url: string): void;
-    
     /**
      * Adds an event listener to the audio engine.
      * @param event The event name to listen.