@readium/navigator 2.4.0-beta.8 → 2.4.0-beta.9

package/package.json

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

package/src/audio/AudioNavigator.ts

@@ -1,4 +1,4 @@
-import { Link, Locator, LocatorLocations, Publication } from "@readium/shared";
+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";
@@ -11,7 +11,6 @@ import {
     IAudioDefaults
 } from "./preferences";
 import { AudioPoolManager } from "./AudioPoolManager";
-import { AudioTimeline } from "./AudioTimeline";
 import { ContextMenuEvent, KeyboardEventData, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
 import { AudioNavigatorProtector } from "./protection/AudioNavigatorProtector";
 import { NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT } from "../protection/NavigatorProtector";
@@ -20,6 +19,7 @@ import { KeyboardPeripherals, NAVIGATOR_KEYBOARD_PERIPHERAL_EVENT } from "../per
 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;
@@ -36,6 +36,7 @@ export interface AudioNavigatorListeners {
 const defaultListeners = (listeners: Partial<AudioNavigatorListeners>): AudioNavigatorListeners => ({
     trackLoaded: listeners.trackLoaded ?? (() => {}),
     positionChanged: listeners.positionChanged ?? (() => {}),
+    timelineItemChanged: listeners.timelineItemChanged ?? (() => {}),
     error: listeners.error ?? (() => {}),
     trackEnded: listeners.trackEnded ?? (() => {}),
     play: listeners.play ?? (() => {}),
@@ -71,7 +72,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     private _mediaSessionEnabled: boolean = false;
     private pool: AudioPoolManager;
     private readonly _navigatorProtector: AudioNavigatorProtector | null = null;
-    private readonly _timeline: AudioTimeline;
+    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;
@@ -82,7 +83,6 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     }) {
         super();
         this.pub = publication;
-        this._timeline = new AudioTimeline(publication);
         this.listeners = defaultListeners(listeners);
 
         this._preferences = new AudioPreferences(configuration.preferences);
@@ -167,7 +167,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         this.waitForLoadedAndSeeked(initialTime)
             .then(() => {
                 this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
-                this._timeline.update(this.currentLocator);
+                this._notifyTimelineChange(this.currentLocator);
                 this.listeners.positionChanged(this.currentLocator);
             })
             .catch(() => {
@@ -214,8 +214,16 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         return this.pub;
     }
 
-    get timeline(): AudioTimeline {
-        return this._timeline;
+    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 {
@@ -365,7 +373,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                     progression,
                     fragments: [`t=${currentTime}`]
                 }));
-                this._timeline.update(this.currentLocation);
+                this._notifyTimelineChange(this.currentLocation);
                 this.listeners.positionChanged(this.currentLocation);
             }
         });
@@ -373,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", () => {
@@ -417,7 +426,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 progression,
                 fragments: [`t=${currentTime}`]
             }));
-            this._timeline.update(this.currentLocation);
+            this._notifyTimelineChange(this.currentLocation);
             this.listeners.positionChanged(this.currentLocation);
         }, this._settings.pollInterval);
     }
@@ -455,10 +464,13 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
 
             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._timeline.update(this.currentLocator);
+            this._notifyTimelineChange(this.currentLocator);
             this.listeners.positionChanged(this.currentLocator);
 
             if (this._settings.enableMediaSession) {
@@ -466,12 +478,13 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
 
             if (wasPlaying) this.play();
-            this._playIntent = false;
 
             cb(true);
         } catch (error) {
             console.error("Failed to go to locator:", error);
             cb(false);
+        } finally {
+            this._playIntent = false;
         }
     }
 

package/src/audio/index.ts

@@ -1,4 +1,3 @@
 export * from './engine';
 export * from './preferences';
-export * from './AudioNavigator';
-export * from './AudioTimeline';
+export * from './AudioNavigator';

package/src/index.ts

@@ -1,5 +1,4 @@
 export * from './Navigator';
-export * from './Timeline';
 export * from './webpub';
 export * from './epub';
 export * from './audio';

package/types/src/audio/AudioNavigator.d.ts

@@ -1,12 +1,12 @@
-import { Link, Locator, Publication } from "@readium/shared";
+import { Link, Locator, Publication, Timeline, TimelineItem } from "@readium/shared";
 import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../Navigator";
 import { Configurable } from "../preferences";
 import { AudioPreferences, AudioSettings, AudioPreferencesEditor, IAudioPreferences, IAudioDefaults } from "./preferences";
-import { AudioTimeline } from "./AudioTimeline";
 import { ContextMenuEvent, KeyboardEventData, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
 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;
@@ -39,7 +39,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private _mediaSessionEnabled;
     private pool;
     private readonly _navigatorProtector;
-    private readonly _timeline;
+    private _currentTimelineItem;
     private readonly _keyboardPeripheralsManager;
     private readonly _suspiciousActivityListener;
     private readonly _keyboardPeripheralListener;
@@ -49,7 +49,8 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     submitPreferences(preferences: AudioPreferences): Promise<void>;
     private applyPreferences;
     get publication(): Publication;
-    get timeline(): AudioTimeline;
+    get timeline(): Timeline;
+    private _notifyTimelineChange;
     private ensureLocatorLocations;
     /** Resolves a bare href (no fragment) to its index in the reading order. Returns -1 if not found. */
     private hrefToTrackIndex;

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

@@ -1,4 +1,3 @@
 export * from './engine';
 export * from './preferences';
 export * from './AudioNavigator';
-export * from './AudioTimeline';

package/types/src/index.d.ts

@@ -1,5 +1,4 @@
 export * from './Navigator';
-export * from './Timeline';
 export * from './webpub';
 export * from './epub';
 export * from './audio';

package/src/Timeline.ts

@@ -1,58 +0,0 @@
-/**
- * Represents a single entry in the publication's timeline.
- * The timeline contextualizes the reading order, table of contents,
- * positions list, and guided navigation document (GND) so that
- * consuming apps can, for instance, display position numbers
- * for TOC items, select the current TOC entry when
- * it has a fragment, or display previous/next as chapter titles while
- * pointing to the actual resources.
- *
- * Properties vary by format — not all will be populated for every format.
- */
-export interface TimelineItem {
-    /** Title of this timeline entry (e.g. chapter or section name). */
-    title: string;
-    /** References as hrefs with optional fragments, e.g. ["chapter1.html"], ["track1.mp3#t=60"], ["#page=6"]. */
-    references: string[];
-    /** Roles of this entry, e.g. ["chapter"], ["section"], ["part"]. */
-    role?: string[];
-    /** Position number in the reading order context. */
-    position?: number;
-    /** Scroll progression within the resource (0 to 1), for entries that start mid-way in a resource. */
-    scroll?: number;
-    /** Nested timeline entries. */
-    children?: TimelineItem[];
-}
-
-export type TimelineChangeCallback = (current: TimelineItem | undefined, previous: TimelineItem | undefined, next: TimelineItem | undefined) => void;
-
-/**
- * A timeline built from a publication's structure.
- * Format-specific subclasses are responsible for building the items
- * from the publication's reading order, table of contents, positions list and GND.
- */
-export abstract class Timeline {
-    abstract readonly items: TimelineItem[];
-
-    /** The current timeline item matching the navigator's position. */
-    abstract get current(): TimelineItem | undefined;
-
-    /** The previous entry relative to current, based on resource boundaries in the TOC tree. */
-    abstract get previous(): TimelineItem | undefined;
-
-    /** The next entry relative to current, based on resource boundaries in the TOC tree. */
-    abstract get next(): TimelineItem | undefined;
-
-    /** Returns the previous and next entries relative to current. */
-    get adjacent(): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
-        return { previous: this.previous, next: this.next };
-    }
-
-    protected changeCallback: TimelineChangeCallback | null = null;
-
-    /** Register a callback invoked when the current timeline item changes. */
-    onChange(callback: TimelineChangeCallback): void {
-        this.changeCallback = callback;
-    }
-
-}

package/src/audio/AudioTimeline.ts

@@ -1,156 +0,0 @@
-import { Link, Locator, Publication } from "@readium/shared";
-import { Timeline, TimelineItem } from "../Timeline";
-
-/**
- * Audio-specific timeline built from the publication's table of contents,
- * falling back to the reading order when no TOC is available.
- */
-export class AudioTimeline extends Timeline {
-    readonly items: TimelineItem[];
-
-    private _current: TimelineItem | undefined;
-    private _previous: TimelineItem | undefined;
-    private _next: TimelineItem | undefined;
-    private readonly flat: TimelineItem[];
-
-    constructor(publication: Publication) {
-        super();
-        const toc = publication.toc;
-        this.items = toc && toc.items.length > 0
-            ? AudioTimeline.itemsFromToc(toc.items)
-            : AudioTimeline.itemsFromReadingOrder(publication.readingOrder.items);
-        this.flat = this.flatten(this.items);
-    }
-
-    get current(): TimelineItem | undefined {
-        return this._current;
-    }
-
-    get previous(): TimelineItem | undefined {
-        return this._previous;
-    }
-
-    get next(): TimelineItem | undefined {
-        return this._next;
-    }
-
-    update(locator: Locator): void {
-        const href = locator.href.split("#")[0];
-        const time = locator.locations?.time() ?? 0;
-
-        const matched = this.findCurrent(this.items, href, time);
-        
-        // Only fire callback when timeline values actually change
-        if (matched !== this._current) {
-            this._current = matched;
-            this._previous = matched ? this.findPrevious(matched) : undefined;
-            this._next = matched ? this.findNext(matched) : undefined;
-            this.changeCallback?.(this._current, this._previous, this._next);
-        }
-    }
-
-    /**
-     * Finds the deepest timeline item whose reference matches the given
-     * href and whose time offset is at or before the current time.
-     */
-    private findCurrent(_items: TimelineItem[], href: string, time: number): TimelineItem | undefined {
-        // Search for time-based match first
-        let match: TimelineItem | undefined;
-        
-        for (const item of this.flat) {
-            if (this.itemMatchesPosition(item, href, time)) {
-                match = item;
-            }
-        }
-        
-        // If no time-based match, fallback to base href match
-        if (!match) {
-            for (const item of this.flat) {
-                if (this.bareHref(item) === href) {
-                    match = item;
-                    break;
-                }
-            }
-        }
-        
-        return match;
-    }
-
-    /** First preceding entry in the flat list */
-    private findPrevious(target: TimelineItem): TimelineItem | undefined {
-        const index = this.flat.indexOf(target);
-        if (index > 0) {
-            return this.flat[index - 1];
-        }
-        return undefined;
-    }
-
-    /** First following entry in the flat list */
-    private findNext(target: TimelineItem): TimelineItem | undefined {
-        const index = this.flat.indexOf(target);
-        if (index < this.flat.length - 1) {
-            return this.flat[index + 1];
-        }
-        return undefined;
-    }
-
-    private bareHref(item: TimelineItem): string {
-        const ref = item.references[0];
-        if (!ref) return "";
-        return ref.split("#")[0];
-    }
-
-    private flatten(items: TimelineItem[]): TimelineItem[] {
-        const result: TimelineItem[] = [];
-        for (const item of items) {
-            result.push(item);
-            if (item.children) {
-                result.push(...this.flatten(item.children));
-            }
-        }
-        return result;
-    }
-
-    private itemMatchesPosition(item: TimelineItem, href: string, time: number): boolean {
-        for (const ref of item.references) {
-            const [refHref, refFragment] = ref.split("#");
-            const refBare = refHref || href; // empty refHref means same resource (e.g. "#t=60")
-            if (refBare !== href) continue;
-            const refTime = this.parseTimeFragment(refFragment);
-            if (time >= refTime) return true;
-        }
-        return false;
-    }
-
-    private parseTimeFragment(fragment: string | undefined): number {
-        if (!fragment) return 0;
-        const match = fragment.match(/(?:^|&)t=(\d+(?:\.\d+)?)/);
-        return match ? parseFloat(match[1]) : 0;
-    }
-
-    private static itemsFromToc(links: Link[]): TimelineItem[] {
-        return links
-            .map(link => AudioTimeline.linkToItem(link))
-            .filter(Boolean) as TimelineItem[];
-    }
-
-    private static itemsFromReadingOrder(links: Link[]): TimelineItem[] {
-        return links
-            .map(link => AudioTimeline.linkToItem(link))
-            .filter(Boolean) as TimelineItem[];
-    }
-
-    private static linkToItem(link: Link): TimelineItem | undefined {
-        if (!link.title) return undefined;
-
-        const children = link.children?.items
-            .map(child => AudioTimeline.linkToItem(child))
-            .filter(Boolean) as TimelineItem[] | undefined;
-
-        return {
-            title: link.title,
-            references: [link.href],
-            children: children && children.length > 0 ? children : undefined,
-        };
-    }
-}

package/types/src/Timeline.d.ts

@@ -1,48 +0,0 @@
-/**
- * Represents a single entry in the publication's timeline.
- * The timeline contextualizes the reading order, table of contents,
- * positions list, and guided navigation document (GND) so that
- * consuming apps can, for instance, display position numbers
- * for TOC items, select the current TOC entry when
- * it has a fragment, or display previous/next as chapter titles while
- * pointing to the actual resources.
- *
- * Properties vary by format — not all will be populated for every format.
- */
-export interface TimelineItem {
-    /** Title of this timeline entry (e.g. chapter or section name). */
-    title: string;
-    /** References as hrefs with optional fragments, e.g. ["chapter1.html"], ["track1.mp3#t=60"], ["#page=6"]. */
-    references: string[];
-    /** Roles of this entry, e.g. ["chapter"], ["section"], ["part"]. */
-    role?: string[];
-    /** Position number in the reading order context. */
-    position?: number;
-    /** Scroll progression within the resource (0 to 1), for entries that start mid-way in a resource. */
-    scroll?: number;
-    /** Nested timeline entries. */
-    children?: TimelineItem[];
-}
-export type TimelineChangeCallback = (current: TimelineItem | undefined, previous: TimelineItem | undefined, next: TimelineItem | undefined) => void;
-/**
- * A timeline built from a publication's structure.
- * Format-specific subclasses are responsible for building the items
- * from the publication's reading order, table of contents, positions list and GND.
- */
-export declare abstract class Timeline {
-    abstract readonly items: TimelineItem[];
-    /** The current timeline item matching the navigator's position. */
-    abstract get current(): TimelineItem | undefined;
-    /** The previous entry relative to current, based on resource boundaries in the TOC tree. */
-    abstract get previous(): TimelineItem | undefined;
-    /** The next entry relative to current, based on resource boundaries in the TOC tree. */
-    abstract get next(): TimelineItem | undefined;
-    /** Returns the previous and next entries relative to current. */
-    get adjacent(): {
-        previous: TimelineItem | undefined;
-        next: TimelineItem | undefined;
-    };
-    protected changeCallback: TimelineChangeCallback | null;
-    /** Register a callback invoked when the current timeline item changes. */
-    onChange(callback: TimelineChangeCallback): void;
-}

package/types/src/audio/AudioTimeline.d.ts

@@ -1,34 +0,0 @@
-import { Locator, Publication } from "@readium/shared";
-import { Timeline, TimelineItem } from "../Timeline";
-/**
- * Audio-specific timeline built from the publication's table of contents,
- * falling back to the reading order when no TOC is available.
- */
-export declare class AudioTimeline extends Timeline {
-    readonly items: TimelineItem[];
-    private _current;
-    private _previous;
-    private _next;
-    private readonly flat;
-    constructor(publication: Publication);
-    get current(): TimelineItem | undefined;
-    get previous(): TimelineItem | undefined;
-    get next(): TimelineItem | undefined;
-    update(locator: Locator): void;
-    /**
-     * Finds the deepest timeline item whose reference matches the given
-     * href and whose time offset is at or before the current time.
-     */
-    private findCurrent;
-    /** First preceding entry in the flat list */
-    private findPrevious;
-    /** First following entry in the flat list */
-    private findNext;
-    private bareHref;
-    private flatten;
-    private itemMatchesPosition;
-    private parseTimeFragment;
-    private static itemsFromToc;
-    private static itemsFromReadingOrder;
-    private static linkToItem;
-}