@readium/navigator 2.10.2 → 2.11.0

package/src/epub/fxl/FXLFramePoolManager.ts

@@ -1,9 +1,9 @@
 import { ModuleName } from "@readium/navigator-html-injectables";
-import { Locator, Publication, ReadingProgression, Page, Link } from "@readium/shared";
+import { Locator, Publication, ReadingProgression, Page, Link, Layout } from "@readium/shared";
 import { FrameCommsListener } from "../frame/index.ts";
-import FrameBlobBuider from "../frame/FrameBlobBuilder.ts";
+import FrameBlobBuilder, { UpgradeInsecureRequests } from "../frame/FrameBlobBuilder.ts";
 import { FXLFrameManager } from "./FXLFrameManager.ts";
-import { FXLPeripherals } from "./FXLPeripherals.ts";
+import { FXLPeripherals, isTypedOMSupported } from "./FXLPeripherals.ts";
 import { FXLSpreader, Orientation, Spread } from "./FXLSpreader.ts";
 import { VisualNavigatorViewport, IContentProtectionConfig, IKeyboardPeripheralsConfig } from "../../Navigator.ts";
 import { Injector } from "../../injection/Injector.ts";
@@ -21,7 +21,7 @@ export class FXLFramePoolManager {
     private readonly container: HTMLElement;
     private readonly positions: Locator[];
     private readonly pool: Map<string, FXLFrameManager> = new Map();
-    private readonly blobs: Map<string, string> = new Map();
+    private readonly blobs: Map<string, FrameBlobBuilder> = new Map();
     private readonly inprogress: Map<string, Promise<void>> = new Map();
     private readonly delayedShow: Map<string, Promise<void>> = new Map();
     private readonly delayedTimeout: Map<string, number> = new Map();
@@ -31,6 +31,7 @@ export class FXLFramePoolManager {
     private readonly contentProtectionConfig: IContentProtectionConfig;
     private readonly keyboardPeripheralsConfig: IKeyboardPeripheralsConfig;
     private resizeWatchSelectors: string[];
+    private readonly upgradeInsecureRequests: UpgradeInsecureRequests;
 
     // NEW
     private readonly bookElement: HTMLDivElement;
@@ -38,7 +39,7 @@ export class FXLFramePoolManager {
     private readonly pub: Publication;
     public width: number = 0;
     public height: number = 0;
-    private transform: string = "";
+    private transform: number | undefined;
     public currentSlide: number = 0;
     private spreader: FXLSpreader;
     private spread = true; // TODO
@@ -53,10 +54,12 @@ export class FXLFramePoolManager {
         container: HTMLElement,
         positions: Locator[],
         pub: Publication,
+        _layout: Layout, // TODO: used by upcoming scrolled-layout support
         injector?: Injector | null,
         contentProtectionConfig?: IContentProtectionConfig,
         keyboardPeripheralsConfig?: IKeyboardPeripheralsConfig,
         resizeWatchSelectors: string[] = [],
+        upgradeInsecureRequests?: UpgradeInsecureRequests,
     ) {
         this.container = container;
         this.positions = positions;
@@ -65,11 +68,12 @@ export class FXLFramePoolManager {
         this.contentProtectionConfig = contentProtectionConfig || {};
         this.keyboardPeripheralsConfig = keyboardPeripheralsConfig || [];
         this.resizeWatchSelectors = [...resizeWatchSelectors];
+        this.upgradeInsecureRequests = upgradeInsecureRequests ?? 'always';
         this.spreadPresentation = pub.metadata.otherMetadata?.spread || Spread.auto;
 
         if(this.pub.metadata.effectiveReadingProgression !== ReadingProgression.rtl && this.pub.metadata.effectiveReadingProgression !== ReadingProgression.ltr)
             // TODO support TTB and BTT
-            throw Error("Unsupported reading progression for EPUB");
+            throw Error("Unsupported reading progression for fixed-layout EPUB");
 
         // NEW
         this.spreader = new FXLSpreader(this.pub);
@@ -89,16 +93,18 @@ export class FXLFramePoolManager {
 
         this.peripherals = new FXLPeripherals(this);
 
+        const fragment = document.createDocumentFragment();
         this.pub.readingOrder.items.forEach((link) => {
             // Create <iframe>
             const fm = new FXLFrameManager(this.peripherals, this.pub.metadata.effectiveReadingProgression, link.href, this.contentProtectionConfig, this.keyboardPeripheralsConfig, this.resizeWatchSelectors);
-            this.spineElement.appendChild(fm.element);
 
-            // this.pages.push(fm);
             this.pool.set(link.href, fm);
             fm.width = 100 / this.length * (link.properties?.otherProperties["orientation"] === Orientation.landscape || link.properties?.otherProperties["addBlank"] ? this.perPage : 1);
             fm.height = this.height;
+            fragment.appendChild(fm.wrapper);
         });
+        this.spineElement.appendChild(fragment);
+
     }
 
     private _listener!: FrameCommsListener;
@@ -137,15 +143,18 @@ export class FXLFramePoolManager {
 
         clearTimeout(this.resizeTimeout);
         this.resizeTimeout = window.setTimeout(() => {
-            // TODO optimize this expensive set of loops and operations
+            const baseWidthFactor = 100 / this.length;
+            const itemLookup = new Map(this.pub.readingOrder.items.map(item => [item.href, item]));
             this.pool.forEach((frm, linkHref) => {
-                let i = this.pub.readingOrder.items.findIndex(l => l.href === linkHref);
-                const link = this.pub.readingOrder.items[i];
-                frm.width = 100 / this.length * (link.properties?.otherProperties["orientation"] === Orientation.landscape || link.properties?.otherProperties["addBlank"] ? this.perPage : 1);
-                frm.height = this.height;
-                if(!frm.loaded) return;
-                const spread = this.spreader.findByLink(link)!;
-                frm.update(this.spreadPosition(spread, link));
+                const link = itemLookup.get(linkHref);
+                if(!link) return;
+                requestAnimationFrame(() => {
+                    frm.width = baseWidthFactor * (link.properties?.otherProperties["orientation"] === Orientation.landscape || link.properties?.otherProperties["addBlank"] ? this.perPage : 1);
+                    frm.height = this.height;
+                    if(!frm.loaded) return;
+                    const spread = this.spreader.findByLink(link)!;
+                    frm.update(this.spreadPosition(spread, link));
+                });
             });
         }, RESIZE_UPDATE_TIMEOUT);
     }
@@ -184,25 +193,42 @@ export class FXLFramePoolManager {
     }
 
     public updateSpineStyle(animate: boolean, fast = true) {
-        let margin = "0";
+        let margin = 0;
         this.updateDimensions();
         if(this.perPage > 1 && true) // this.shift
-            margin = `${this.width / 2}px`;
-
-        const spineStyle = {
-            transition: animate ? `all ${fast ? SLIDE_FAST : SLIDE_SLOW}ms ease-out` : "all 0ms ease-out",
-            marginRight: this.rtl ? margin : "0",
-            marginLeft: this.rtl ? "0" : margin,
-            width: `${(this.width / this.perPage) * this.length}px`,
-            transform: this.transform,
-
-            // Static (should be moved to CSS)
-            contain: "content"
-        } as CSSStyleDeclaration;
-
-        Object.assign(this.spineElement.style, spineStyle);
+            margin = this.width / 2;
+
+        if(isTypedOMSupported()) {
+            // TODO: don't use UnparsedValue, but rather the longhand of every transition property
+            this.spineElement.attributeStyleMap.set("transition", new CSSUnparsedValue([animate ? `all ${fast ? SLIDE_FAST : SLIDE_SLOW}ms ease-out` : "all 0ms ease-out"]));
+            this.spineElement.attributeStyleMap.set("margin-right", CSS.px(this.rtl ? margin : 0));
+            this.spineElement.attributeStyleMap.set("margin-left", CSS.px(this.rtl ? 0 : margin));
+            this.spineElement.attributeStyleMap.set("width", CSS.px((this.width / this.perPage) * this.length));
+            this.transform ? this.spineElement.attributeStyleMap.set("transform", new CSSTransformValue([
+                new CSSTranslate(CSS.px(this.transform || 0), CSS.px(0), CSS.px(0))
+            ])) : this.spineElement.attributeStyleMap.delete("transform");
+            this.spineElement.attributeStyleMap.set("contain", new CSSUnparsedValue(["content"]));
+        } else {
+            const spineStyle = {
+                transition: animate ? `all ${fast ? SLIDE_FAST : SLIDE_SLOW}ms ease-out` : "all 0ms ease-out",
+                marginRight: this.rtl ? `${margin}px` : "0",
+                marginLeft: this.rtl ? "0" : `${margin}px`,
+                width: `${(this.width / this.perPage) * this.length}px`,
+                transform: this.transform ? `translate3d(${this.transform}px, 0px, 0px)` : "",
+                // Static (should be moved to CSS)
+                contain: "content"
+            } as CSSStyleDeclaration;
+            Object.assign(this.spineElement.style, spineStyle);
+        }
     }
 
+    // Reused typed transform for the per-event zoom/pan write: allocating
+    // fresh CSSTransformValue objects per write is slower than string
+    // parsing; mutating a persistent one is faster than both
+    private bookScale: CSSScale | null = null;
+    private bookTranslate: CSSTranslate | null = null;
+    private bookTransform: CSSTransformValue | null = null;
+
     public updateBookStyle(initial=false) {
         if(initial) {
             const bookStyle = {
@@ -221,7 +247,23 @@ export class FXLFramePoolManager {
             } as CSSStyleDeclaration;
             Object.assign(this.bookElement.style, bookStyle);
         }
-        this.bookElement.style.transform = `scale(${this.peripherals?.scale || 1})` + (this.peripherals ? ` translate3d(${this.peripherals.pan.translateX}px, ${this.peripherals.pan.translateY}px, 0px)` : "");
+        const scale = this.peripherals?.scale || 1;
+        const translateX = this.peripherals?.pan.translateX || 0;
+        const translateY = this.peripherals?.pan.translateY || 0;
+        if(isTypedOMSupported()) {
+            if(!this.bookTransform) {
+                this.bookScale = new CSSScale(1, 1);
+                this.bookTranslate = new CSSTranslate(CSS.px(0), CSS.px(0), CSS.px(0));
+                this.bookTransform = new CSSTransformValue([this.bookScale, this.bookTranslate]);
+            }
+            (this.bookScale!.x as CSSUnitValue).value = scale;
+            (this.bookScale!.y as CSSUnitValue).value = scale;
+            (this.bookTranslate!.x as CSSUnitValue).value = translateX;
+            (this.bookTranslate!.y as CSSUnitValue).value = translateY;
+            this.bookElement.attributeStyleMap.set("transform", this.bookTransform);
+        } else {
+            this.bookElement.style.transform = `scale(${scale}) translate3d(${translateX}px, ${translateY}px, 0px)`;
+        }
     }
 
     /**
@@ -285,22 +327,22 @@ export class FXLFramePoolManager {
      */
     slideToCurrent(enableTransition?: boolean, fast = true) {
         this.updateDimensions();
+        // Always commit: the spine transform may have been written directly
+        // by the peripherals during a drag (snap-back relies on this), and
+        // reading style.transform back as a string for comparison doesn't
+        // match under CSS Typed OM (its serialization differs).
         if (enableTransition) {
             // This one is tricky, I know but this is a perfect explanation:
             // https://youtu.be/cCOL7MC4Pl0
             requestAnimationFrame(() => {
                 requestAnimationFrame(() => {
-                    const newTransform = `translate3d(${this.offset}px, 0, 0)`;
-                    if(this.spineElement.style.transform === newTransform) return;
-                    this.transform = newTransform;
+                    this.transform = this.offset;
                     this.updateSpineStyle(true, fast);
                     this.deselect();
                 });
             });
         } else {
-            const newTransform = `translate3d(${this.offset}px, 0, 0)`;
-            if(this.spineElement.style.transform === newTransform) return;
-            this.transform = newTransform;
+            this.transform = this.offset;
             this.updateSpineStyle(false);
             this.deselect();
         }
@@ -308,10 +350,10 @@ export class FXLFramePoolManager {
 
     bounce(rtl = false) {
         requestAnimationFrame(() => {
-            this.transform = `translate3d(${this.offset+(50 * (rtl ? 1 : -1))}px, 0, 0)`;
+            this.transform = this.offset + (50 * (rtl ? 1 : -1));
             this.updateSpineStyle(true, true);
             setTimeout(() => {
-                this.transform = `translate3d(${this.offset}px, 0, 0)`;
+                this.transform = this.offset;
                 this.updateSpineStyle(true, true);
             }, 100);
         });
@@ -408,7 +450,8 @@ export class FXLFramePoolManager {
         this.pool.clear();
 
         // Revoke all blobs
-        this.blobs.forEach(v => URL.revokeObjectURL(v));
+        this.blobs.forEach(v => v.reset());
+        this.blobs.clear();
 
         // Clean up injector if it exists
         this.injector?.dispose();
@@ -499,13 +542,13 @@ export class FXLFramePoolManager {
                 if(!this.pool.has(href)) return;
                 this.cancelShowing(href);
                 await this.pool.get(href)?.unload();
-                // this.pool.delete(href);
+                this.blobs.get(href)?.reset();
             });
 
             // Check if base URL of publication has changed
             if(this.currentBaseURL !== undefined && pub.baseURL !== this.currentBaseURL) {
                 // Revoke all blobs
-                this.blobs.forEach(v => URL.revokeObjectURL(v));
+                this.blobs.forEach(v => v.reset());
                 this.blobs.clear();
             }
             this.currentBaseURL = pub.baseURL;
@@ -515,16 +558,15 @@ export class FXLFramePoolManager {
                 const itm = pub.readingOrder.items[index];
                 if(!itm) return; // TODO throw?
                 if(!this.blobs.has(href)) {
-                    const blobBuilder = new FrameBlobBuider(
+                    this.blobs.set(href, new FrameBlobBuilder(
                         pub,
                         this.currentBaseURL || "",
                         itm,
                         {
-                            injector: this.injector
+                            injector: this.injector,
+                            upgradeInsecureRequests: this.upgradeInsecureRequests
                         }
-                    );
-                    const blobURL = await blobBuilder.build(true);
-                    this.blobs.set(href, blobURL);
+                    ));
                 }
 
                 // Show future offscreen frame in advance after a delay
@@ -538,7 +580,7 @@ export class FXLFramePoolManager {
                             const spread = this.makeSpread(this.reAlign(index));
                             const page = this.spreadPosition(spread, itm);
                             const fm = this.pool.get(href)!;
-                            await fm.load(modules, this.blobs.get(href)!);
+                            await fm.load(modules, await this.blobs.get(href)!.build(true));
                             if(!this.peripherals.isScaled) // When scaled, positioning is screwed up, so wait to show
                                 await fm.show(page); // Show/activate new frame
                             this.delayedShow.delete(href);
@@ -565,7 +607,7 @@ export class FXLFramePoolManager {
                 if(!source) continue; // This can get destroyed
 
                 this.cancelShowing(s.href);
-                await newFrame.load(modules, source); // In order to ensure modules match the latest configuration
+                await newFrame.load(modules, await source.build(true)); // In order to ensure modules match the latest configuration
                 await newFrame.show(this.spreadPosition(spread, s)); // Show/activate new frame
                 this.previousFrames.push(newFrame);
                 await newFrame.activate();
@@ -592,9 +634,12 @@ export class FXLFramePoolManager {
         for (const s of spread) {
             this.inprogress.set(s.href, progressPromise); // Add the job to the in progress map
         }
-        await progressPromise; // Wait on the job to finish...
-        for (const s of spread) {
-            this.inprogress.delete(s.href); // Delete it from the in progress map!
+        try {
+            await progressPromise; // Wait on the job to finish...
+        } finally {
+            for (const s of spread) {
+                this.inprogress.delete(s.href); // Delete it from the in progress map!
+            }
         }
     }
 

package/src/epub/fxl/FXLPeripherals.ts

@@ -35,6 +35,8 @@ export interface Zoomer {
     };
 }
 
+export const isTypedOMSupported = () => typeof window.CSSTransformValue !== 'undefined';
+
 export class FXLPeripherals {
 
     private readonly manager: FXLFramePoolManager;
@@ -339,6 +341,12 @@ export class FXLPeripherals {
 
     private moveFrame = 0;
 
+    // Reused typed transform for the per-frame drag write: allocating fresh
+    // CSSTransformValue/CSSTranslate objects per write is slower than string
+    // parsing; mutating a persistent one is faster than both
+    private dragTranslate: CSSTranslate | null = null;
+    private dragTransform: CSSTransformValue | null = null;
+
     /**
      * touchmove event handler
      */
@@ -494,11 +502,24 @@ export class FXLPeripherals {
             const currentOffset = currentSlide * (this.manager.width / this.manager.perPage);
             const dragOffset = (this.pan.endX - this.pan.startX);
             const offset = this.manager.rtl ? currentOffset + dragOffset : currentOffset - dragOffset;
+            // Snap the translation to device pixels: at fractional offsets the
+            // spread gutter is rasterized with a hairline gap between the pages
+            const dpr = window.devicePixelRatio || 1;
+            const snapped = Math.round((this.manager.rtl ? 1 : -1) * offset * dpr) / dpr;
 
             cancelAnimationFrame(this.moveFrame);
             this.moveFrame = requestAnimationFrame(() => {
                 requestAnimationFrame(() => {
-                    this.manager.spineElement.style.transform = `translate3d(${(this.manager.rtl ? 1 : -1) * offset}px, 0, 0)`;
+                    if(isTypedOMSupported()) {
+                        if(!this.dragTransform) {
+                            this.dragTranslate = new CSSTranslate(CSS.px(0), CSS.px(0), CSS.px(0));
+                            this.dragTransform = new CSSTransformValue([this.dragTranslate]);
+                        }
+                        (this.dragTranslate!.x as CSSUnitValue).value = snapped;
+                        this.manager.spineElement.attributeStyleMap.set("transform", this.dragTransform);
+                    } else {
+                        this.manager.spineElement.style.transform = `translate3d(${snapped}px, 0, 0)`;
+                    }
                 })
             });
         }

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './Navigator.ts';
 export * from './decorations/index.ts';
 export * from './webpub/index.ts';
 export * from './epub/index.ts';
+export * from './divina/index.ts';
 export * from './audio/index.ts';
 export * from './helpers/index.ts';
 export * from './preferences/index.ts';

package/src/peripherals/KeyboardConditionBridge.ts

@@ -12,18 +12,28 @@ export class KeyboardConditionBridge {
     setup() {
         let initializing = true;
 
+        // Subscribe once per distinct condition object: combos commonly share
+        // one condition, and a per-combo subscription would trigger one full
+        // onUpdate rebuild per combo for a single condition change.
+        const combosByCondition = new Map<NonNullable<KeyCombo["condition"]>, KeyCombo[]>();
         this.config.forEach(peripheral =>
             peripheral.keyCombos.forEach(combo => {
                 if (combo.condition) {
-                    const unsub = combo.condition.subscribe((value) => {
-                        this.conditionValues.set(combo, value);
-                        if (!initializing) this.onUpdate(this.buildSerializable());
-                    });
-                    this.unsubs.push(unsub);
+                    const combos = combosByCondition.get(combo.condition) ?? [];
+                    combos.push(combo);
+                    combosByCondition.set(combo.condition, combos);
                 }
             })
         );
 
+        combosByCondition.forEach((combos, condition) => {
+            const unsub = condition.subscribe((value) => {
+                combos.forEach(combo => this.conditionValues.set(combo, value));
+                if (!initializing) this.onUpdate(this.buildSerializable());
+            });
+            this.unsubs.push(unsub);
+        });
+
         initializing = false;
         this.onUpdate(this.buildSerializable());
     }

package/src/peripherals/KeyboardPeripherals.ts

@@ -14,11 +14,16 @@ export interface KeyboardPeripheralOptions {
 export class KeyboardPeripherals {
     private keydownHandler?: (event: KeyboardEvent) => void;
     private keyManager = new KeyCombinationManager();
+    // pagehide instead of unload: an unload listener disqualifies the page
+    // from the back/forward cache; only tear down on real unloads.
+    private readonly pagehideHandler = (e: PageTransitionEvent) => {
+        if (!e.persisted) this.destroy();
+    };
 
     constructor(options: KeyboardPeripheralOptions = {}) {
         this.setupKeyboardPeripherals(options.keyboardPeripherals || []);
     }
-    
+
     private setupKeyboardPeripherals(keyboardPeripherals: KeyboardPeripheral[]) {
         if (keyboardPeripherals.length > 0) {
             // Create activity event dispatcher
@@ -28,26 +33,27 @@ export class KeyboardPeripherals {
                 });
                 window.dispatchEvent(customEvent);
             };
-            
+
             // Create unified handler using the provided keyboard peripherals
             this.keydownHandler = this.keyManager.createUnifiedHandler(
                 "", // Empty string as target frame source for main window
-                keyboardPeripherals, 
+                keyboardPeripherals,
                 dispatcher
             );
-            
+
             if (this.keydownHandler) {
                 document.addEventListener("keydown", this.keydownHandler, true);
             }
         }
-        
-        window.addEventListener("unload", () => this.destroy());
+
+        window.addEventListener("pagehide", this.pagehideHandler);
     }
-    
+
     public destroy() {
         if (this.keydownHandler) {
             document.removeEventListener("keydown", this.keydownHandler, true);
             this.keydownHandler = undefined;
         }
+        window.removeEventListener("pagehide", this.pagehideHandler);
     }
 }

package/src/webpub/WebPubFrameManager.ts

@@ -29,7 +29,7 @@ export class WebPubFrameManager {
         this.frame = document.createElement("iframe");
         this.frame.classList.add("readium-navigator-iframe");
         this.frame.style.visibility = "hidden";
-        this.frame.style.setProperty("aria-hidden", "true");
+        this.frame.ariaHidden = "true";
         this.frame.style.opacity = "0";
         this.frame.style.position = "absolute";
         this.frame.style.pointerEvents = "none";
@@ -140,7 +140,7 @@ export class WebPubFrameManager {
     async hide(): Promise<void> {
         if(this.destroyed) return;
         this.frame.style.visibility = "hidden";
-        this.frame.style.setProperty("aria-hidden", "true");
+        this.frame.ariaHidden = "true";
         this.frame.style.opacity = "0";
         this.frame.style.pointerEvents = "none";
         this.hidden = true;
@@ -176,7 +176,7 @@ export class WebPubFrameManager {
 
                     const remove = () => {
                         this.frame.style.removeProperty("visibility");
-                        this.frame.style.removeProperty("aria-hidden");
+                        this.frame.ariaHidden = null;
                         this.frame.style.removeProperty("opacity");
                         this.frame.style.removeProperty("pointer-events");
                         this.hidden = false;
@@ -201,14 +201,12 @@ export class WebPubFrameManager {
     setCSSProperties(properties: { [key: string]: string }) {
         if(this.destroyed || !this.frame.contentWindow) return;
 
-        // We need to resume and halt postMessage to update the properties
-        // if the frame is hidden since it's been halted in hide()
-        if (this.hidden) {
-            if (this.comms) this.comms?.resume();
-            else this.comms = new FrameComms(this.frame.contentWindow!, this.source);
+        // A halted comms can still send, so only a never-shown hidden frame needs one created
+        if (this.hidden && !this.comms) {
+            this.comms = new FrameComms(this.frame.contentWindow, this.source);
+            this.comms.halt();
         }
         this.comms?.send("update_properties", properties);
-        if (this.hidden) this.comms?.halt();
     }
 
     get iframe() {

package/src/webpub/WebPubFramePoolManager.ts

@@ -208,8 +208,11 @@ export class WebPubFramePoolManager {
         });
 
         this.inprogress.set(newHref, progressPromise);
-        await progressPromise;
-        this.inprogress.delete(newHref);
+        try {
+            await progressPromise;
+        } finally {
+            this.inprogress.delete(newHref);
+        }
     }
 
     setCSSProperties(properties: { [key: string]: string }) {

package/src/webpub/WebPubNavigator.ts

@@ -73,6 +73,7 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
     private framePool!: WebPubFramePoolManager;
     private currentIndex: number = 0;
     private currentLocation: Locator;
+    private _destroyed = false;
     private _currentTimelineItem: TimelineItem | undefined;
     private _visibleFragmentIds: string[] = [];
     private _notifiedVisibleFragmentIds: string[] = [];
@@ -192,6 +193,7 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
 
     public async load() {
         await this.updateCSS(false);
+        if (this._destroyed) return;
         const cssProperties = this.compileCSSProperties(this._css);
         this.framePool = new WebPubFramePoolManager(
             this.container,
@@ -206,6 +208,9 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
             [...this._decorationResizeSelectors]
         );
 
+        if (this._destroyed) return;
+        this.currentLocation = this.completeLocator(this.currentLocation);
+
         await this.apply();
     }
 
@@ -456,6 +461,8 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
     }
 
     public async destroy() {
+        // Flag synchronously so an in-flight load() bails before attaching frames.
+        this._destroyed = true;
         if (this._suspiciousActivityListener) {
             window.removeEventListener(NAVIGATOR_SUSPICIOUS_ACTIVITY_EVENT, this._suspiciousActivityListener);
         }
@@ -859,7 +866,44 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
         cb(done);
     }
 
+    private completeLocator(locator: Locator): Locator {
+        if (!locator.href) {
+            const items = this.pub.readingOrder.items;
+            let fellback = false;
+            if (typeof locator.locations.position === "number") {
+                const link = items[locator.locations.position - 1];
+                if (link) {
+                    locator = (this.pub.manifest.locatorFromLink(link) || new Locator({
+                        href: link.href,
+                        type: link.type || "text/html"
+                    })).copyWithLocations(locator.locations);
+                    fellback = true;
+                }
+            }
+            if (!fellback && typeof locator.locations?.totalProgression === "number") {
+                // WebPub has no per-resource totalProgression like EPUB's position list,
+                // so approximate by spreading the reading order evenly. This is here to
+                // help with conversion from OPDS locators which only require the total
+                // progression in the publication.
+                const targetProgression = locator.locations.totalProgression;
+                const closestIdx = Math.min(
+                    items.length - 1,
+                    Math.max(0, Math.round(targetProgression * (items.length - 1)))
+                );
+                const link = items[closestIdx];
+                if (link) {
+                    locator = (this.pub.manifest.locatorFromLink(link) || new Locator({
+                        href: link.href,
+                        type: link.type || "text/html"
+                    })).copyWithLocations(locator.locations);
+                }
+            }
+        }
+        return locator;
+    }
+
     public go(locator: Locator, _: boolean, cb: (ok: boolean) => void): void {
+        locator = this.completeLocator(locator);
         const href = locator.href.split("#")[0];
         let link = this.pub.readingOrder.findWithHref(href);
         if(!link) {

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

@@ -1,6 +1,7 @@
 import { Link, Locator, Publication, Timeline, TimelineItem } from "@readium/shared";
 import { MediaNavigator, IContentProtectionConfig, IKeyboardPeripheralsConfig, KeyboardPeripheralEventData } from "../Navigator.ts";
 import { Configurable } from "../preferences/Configurable.ts";
+import { AudioMseLoaderFactory } from "./engine/index.ts";
 import { AudioPreferences, AudioSettings, AudioPreferencesEditor, IAudioPreferences, IAudioDefaults } from "./preferences/index.ts";
 import { ContextMenuEvent, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
 export interface AudioMetadata {
@@ -35,6 +36,24 @@ export interface AudioNavigatorConfiguration {
     defaults: IAudioDefaults;
     contentProtection?: IAudioContentProtectionConfig;
     keyboardPeripherals?: IKeyboardPeripheralsConfig;
+    /**
+     * Called with the persistent playback element before
+     * the first src is assigned, so the host can prepare it. Use for MSE/EME
+     * setups. When it returns a promise, loading of
+     * the initial track (and prefetching of adjacent ones) is deferred until
+     * the promise settles; a rejection is forwarded to the error listener and
+     * loading proceeds anyway.
+     */
+    mediaElementSetup?: (element: HTMLMediaElement) => void | Promise<void>;
+    /**
+     * When provided, media bytes reach the playback element through Media
+     * Source Extensions instead of direct `src` assignment: the engine
+     * creates one loader per track via this factory and the loader owns all
+     * fetching. Supply one for e.g. EME encrypted audio, since browsers have
+     * poor support for encrypted audio directly through `src`. The container
+     * handling (WebM, fMP4, …) is the loader implementation's concern.
+     */
+    mseLoaderFactory?: AudioMseLoaderFactory;
 }
 export declare class AudioNavigator extends MediaNavigator implements Configurable<AudioSettings, AudioPreferences> {
     private readonly pub;
@@ -58,9 +77,13 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     /** True while a track transition is in progress; suppresses spurious mid-navigation events. */
     private _isNavigating;
     private _isStalled;
+    /** Set by destroy(); stops the deferred initial load from touching a dead instance. */
+    private _destroyed;
     private _stalledWatchdog;
     private _stalledCheckTime;
     constructor(publication: Publication, listeners: AudioNavigatorListeners, initialPosition?: Locator, configuration?: AudioNavigatorConfiguration);
+    /** Sets the initial track on the primary element and seeks to the starting position. */
+    private startInitialLoad;
     get settings(): AudioSettings;
     get preferencesEditor(): AudioPreferencesEditor;
     submitPreferences(preferences: AudioPreferences): Promise<void>;
@@ -73,6 +96,12 @@ export declare class AudioNavigator extends MediaNavigator implements Configurab
     private hrefToTrackIndex;
     /** Current track index derived from the current location's href. */
     private currentTrackIndex;
+    /**
+     * Builds a locator for an overall publication progression (0–1) by walking
+     * the cumulative track durations. Falls back to the start of the first
+     * track when the reading order carries no duration metadata.
+     */
+    private locatorFromTotalProgression;
     get currentLocator(): Locator;
     get isPlaying(): boolean;
     get isPaused(): boolean;