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

package/package.json

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

package/src/Timeline.ts

@@ -0,0 +1,58 @@
+/**
+ * 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/AudioNavigator.ts

@@ -11,6 +11,7 @@ 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";
@@ -59,6 +60,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
     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;
 
@@ -69,6 +71,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 readonly _keyboardPeripheralsManager: KeyboardPeripherals | null = null;
     private readonly _suspiciousActivityListener: ((event: Event) => void) | null = null;
     private readonly _keyboardPeripheralListener: ((event: Event) => void) | null = null;
@@ -79,6 +82,7 @@ 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);
@@ -163,6 +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.listeners.positionChanged(this.currentLocator);
             })
             .catch(() => {
@@ -209,6 +214,10 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
         return this.pub;
     }
 
+    get timeline(): AudioTimeline {
+        return this._timeline;
+    }
+
     private ensureLocatorLocations(locator: Locator): Locator {
         return new Locator({
             ...locator,
@@ -356,6 +365,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                     progression,
                     fragments: [`t=${currentTime}`]
                 }));
+                this._timeline.update(this.currentLocation);
                 this.listeners.positionChanged(this.currentLocation);
             }
         });
@@ -407,6 +417,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
                 progression,
                 fragments: [`t=${currentTime}`]
             }));
+            this._timeline.update(this.currentLocation);
             this.listeners.positionChanged(this.currentLocation);
         }, this._settings.pollInterval);
     }
@@ -432,7 +443,11 @@ 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(trackIndex, direction);
@@ -443,6 +458,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             if (id !== this.navigationId) return;
 
             this.listeners.trackLoaded(this.pool.audioEngine.getMediaElement());
+            this._timeline.update(this.currentLocator);
             this.listeners.positionChanged(this.currentLocator);
 
             if (this._settings.enableMediaSession) {
@@ -450,6 +466,7 @@ export class AudioNavigator extends MediaNavigator implements Configurable<Audio
             }
 
             if (wasPlaying) this.play();
+            this._playIntent = false;
 
             cb(true);
         } catch (error) {

package/src/audio/AudioPoolManager.ts

@@ -59,6 +59,11 @@ export class AudioPoolManager {
         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);
@@ -105,16 +110,7 @@ export class AudioPoolManager {
         const href = this.pickPlayableHref(this._publication.readingOrder.items[currentIndex]);
         const element = this.ensure(href);
 
-        // Hand the element to the engine. When Web Audio is active, the pooled
-        // element doesn't have crossOrigin set (it would break non-CORS servers
-        // during preload), so we swap in the fresh element and let loadAudio
-        // handle CORS setup + fallback on the engine's own mediaElement.
-        if (this.audioEngine.isWebAudioActive) {
-            this.audioEngine.setMediaElement(element);
-            this.audioEngine.loadAudio(href);
-        } else {
-            this.audioEngine.setMediaElement(element);
-        }
+        this.audioEngine.setMediaElement(element);
 
         // Remove from pool so the engine fully owns it and we don't dispose it
         this.pool.delete(href);

package/src/audio/AudioTimeline.ts

@@ -0,0 +1,156 @@
+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/src/audio/engine/AudioEngine.ts

@@ -40,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.

package/src/audio/engine/WebAudioEngine.ts

@@ -95,52 +95,6 @@ export class WebAudioEngine implements AudioEngine {
     );
   }
 
-  /**
-   * Load the audio resource at the given URL.
-   * @param url The URL of the audio resource.
-   * */
-  public loadAudio(url: string): void {
-    // Abort any in-progress load before starting a new one.
-    this.mediaElement.pause();
-    this.mediaElement.removeAttribute("src");
-    this.mediaElement.load();
-
-    this.isLoadingValue = true;
-    this.isLoadedValue = false;
-    this.isPlayingValue = false;
-    this.isPausedValue = false;
-
-    if (this.webAudioActive) {
-      this.mediaElement.crossOrigin = "anonymous";
-      this.mediaElement.src = url;
-      this.mediaElement.load();
-      this.mediaElement.playbackRate = this.currentPlaybackRate;
-
-      // If the server doesn't honour the CORS preflight, fall back to a
-      // non-CORS load and tear down the Web Audio graph so the element
-      // is never passed to MediaElementAudioSourceNode in a tainted state.
-      const cleanup = () => {
-        this.mediaElement.removeEventListener("error", onCORSError);
-        this.mediaElement.removeEventListener("canplaythrough", onCORSSuccess);
-      };
-      const onCORSError = () => {
-        cleanup();
-        this.deactivateWebAudio();
-        this.mediaElement.removeAttribute("crossOrigin");
-        this.mediaElement.src = url;
-        this.mediaElement.load();
-        this.mediaElement.playbackRate = this.currentPlaybackRate;
-      };
-      const onCORSSuccess = () => cleanup();
-      this.mediaElement.addEventListener("error", onCORSError);
-      this.mediaElement.addEventListener("canplaythrough", onCORSSuccess);
-    } else {
-      this.mediaElement.src = url;
-      this.mediaElement.load();
-      this.mediaElement.playbackRate = this.currentPlaybackRate;
-    }
-  }
-
   private deactivateWebAudio(): void {
     if (this.worklet) {
       this.worklet.destroy();
@@ -162,18 +116,7 @@ export class WebAudioEngine implements AudioEngine {
    * @param element The HTML audio element to use.
    */
   public setMediaElement(element: HTMLAudioElement): void {
-    // Pause the outgoing element before replacing it
-    this.mediaElement.pause();
-    this.isPlayingValue = false;
-    this.isPausedValue = false;
-
-    // Disconnect old source node if it exists
-    if (this.sourceNode) {
-      this.sourceNode.disconnect();
-      this.sourceNode = null;
-    }
-
-    // Remove old event listeners from current mediaElement
+    // Remove listeners BEFORE pausing so the pause doesn't leak through
     this.mediaElement.removeEventListener("canplaythrough", this.boundOnCanPlayThrough);
     this.mediaElement.removeEventListener("timeupdate", this.boundOnTimeUpdate);
     this.mediaElement.removeEventListener("error", this.boundOnError);
@@ -190,6 +133,17 @@ export class WebAudioEngine implements AudioEngine {
     this.mediaElement.removeEventListener("pause", this.boundOnPause);
     this.mediaElement.removeEventListener("progress", this.boundOnProgress);
 
+    // Now safe to pause the outgoing element
+    this.mediaElement.pause();
+    this.isPlayingValue = false;
+    this.isPausedValue = false;
+
+    // Disconnect old source node if it exists
+    if (this.sourceNode) {
+      this.sourceNode.disconnect();
+      this.sourceNode = null;
+    }
+
     // Set new media element
     this.mediaElement = element;
 
@@ -214,6 +168,26 @@ export class WebAudioEngine implements AudioEngine {
     this.mediaElement.volume = this.isMutedValue ? 0 : this.currentVolume;
     this.mediaElement.playbackRate = this.currentPlaybackRate;
 
+    // Reconnect the Web Audio graph to the new element
+    if (this.webAudioActive) {
+      try {
+        const ctx = this.getOrCreateAudioContext();
+        this.sourceNode = new MediaElementAudioSourceNode(ctx, { mediaElement: this.mediaElement });
+        if (!this.gainNode) {
+          this.gainNode = ctx.createGain();
+          this.gainNode.connect(ctx.destination);
+        }
+        if (this.worklet?.workletNode) {
+          this.sourceNode.connect(this.worklet.workletNode);
+        } else {
+          this.sourceNode.connect(this.gainNode);
+        }
+      } catch {
+        // CORS failed on this element — deactivate Web Audio gracefully
+        this.deactivateWebAudio();
+      }
+    }
+
     // Check if metadata is already loaded (common with preloaded elements)
     if (this.mediaElement.readyState >= 1) {
       this.onLoadedMetadata(new Event('loadedmetadata'));

package/src/audio/index.ts

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

package/src/epub/frame/FrameManager.ts

@@ -85,7 +85,7 @@ export class FrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/epub/fxl/FXLFrameManager.ts

@@ -219,7 +219,7 @@ export class FXLFrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/index.ts

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

package/src/preferences/Types.ts

@@ -81,7 +81,7 @@ export const volumeRangeConfig: RangeConfig = {
 }
 
 export const playbackRateRangeConfig: RangeConfig = {
-  range: [0.5, 2],
+  range: [0.5, 4],
   step: 0.1
 }
 

package/src/protection/DevToolsDetector.ts

@@ -282,6 +282,7 @@ export class DevToolsDetector {
         // Cleanup Web Worker
         if (this.workerConsole) {
             this.workerConsole.destroy();
+            this.workerConsole = undefined;
         }
         
         this.isOpen = false;

package/src/webpub/WebPubFrameManager.ts

@@ -83,7 +83,7 @@ export class WebPubFrameManager {
         }
 
         // Apply print protection if configured
-        if (this.contentProtectionConfig.protectPrinting) {
+        if (this.contentProtectionConfig.protectPrinting?.disable) {
             this.comms!.send("print_protection", this.contentProtectionConfig.protectPrinting);
         }
     }

package/src/webpub/WebPubNavigator.ts

@@ -128,8 +128,12 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
             
             // Listen for custom events from NavigatorProtector
             this._suspiciousActivityListener = (event: Event) => {
-                const customEvent = event as CustomEvent;
-                this.listeners.contentProtection(customEvent.detail.type, customEvent.detail);
+                const { type, ...activity } = (event as CustomEvent).detail;
+                if (type === "context_menu") {
+                    this.listeners.contextMenu(activity as ContextMenuEvent);
+                } else {
+                    this.listeners.contentProtection(type, activity);
+                }
             };
             window.addEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);
         }

package/types/src/Timeline.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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/AudioNavigator.d.ts

@@ -2,6 +2,7 @@ import { Link, Locator, Publication } 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;
@@ -28,6 +29,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private readonly pub;
     private positionPollInterval;
     private navigationId;
+    private _playIntent;
     private listeners;
     private currentLocation;
     private _preferences;
@@ -37,6 +39,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private _mediaSessionEnabled;
     private pool;
     private readonly _navigatorProtector;
+    private readonly _timeline;
     private readonly _keyboardPeripheralsManager;
     private readonly _suspiciousActivityListener;
     private readonly _keyboardPeripheralListener;
@@ -46,6 +49,7 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     submitPreferences(preferences: AudioPreferences): Promise<void>;
     private applyPreferences;
     get publication(): Publication;
+    get timeline(): AudioTimeline;
     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/AudioTimeline.d.ts

@@ -0,0 +1,34 @@
+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;
+}