@readium/navigator-html-injectables 2.5.0 → 2.6.1

package/src/modules/snapper/CJKVerticalSnapper.ts

@@ -68,7 +68,14 @@ export class CJKVerticalSnapper extends Snapper {
         return Math.max(0, this.doc().scrollWidth - this.wnd.innerWidth);
     }
 
-    private reportProgress() {
+    protected hasScrolledPast(el: Element): boolean {
+        const rect = el.getBoundingClientRect();
+        // vertical-rl: content flows right→left; leading edge is right, scrolled past when off-screen right.
+        // vertical-lr: content flows left→right; leading edge is left, scrolled past when off-screen left.
+        return this.verticalLR ? rect.right <= 0 : rect.left >= this.wnd.innerWidth;
+    }
+
+    private reportProgress(forcedFragmentId?: string) {
         if (!this.comms.ready) return;
         const scrollWidth = this.doc().scrollWidth;
         const viewportWidth = this.wnd.innerWidth;
@@ -82,7 +89,8 @@ export class CJKVerticalSnapper extends Snapper {
 
         this.comms.send("progress", {
             start: progress,
-            end: viewportEnd
+            end: viewportEnd,
+            fragmentId: forcedFragmentId !== undefined ? forcedFragmentId : this.currentTimelineFragment()
         });
     }
 
@@ -150,6 +158,7 @@ export class CJKVerticalSnapper extends Snapper {
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
+        this.setupTimelineObserver();
 
         this.initialScrollHandled = false;
         this.lastScrollLeft = 0;
@@ -223,7 +232,9 @@ export class CJKVerticalSnapper extends Snapper {
                 // vertical-lr: scrollLeft is positive; vertical-rl: negative.
                 const target = this.scrollable() * position;
                 this.doc().scrollLeft = this.verticalLR ? target : -target;
-                this.reportProgress();
+                // No known target fragment for an arbitrary position — force a fresh
+                // geometry scan instead of trusting a possibly-stale visibility cache.
+                this.reportProgress(this.fragmentFromGeometry());
                 deselect(this.wnd);
                 ack(true);
             });
@@ -235,7 +246,10 @@ export class CJKVerticalSnapper extends Snapper {
             this.wnd.requestAnimationFrame(() => {
                 // getBoundingClientRect().left is in viewport coords; translate to scroll coords
                 this.doc().scrollLeft += element.getBoundingClientRect().left - wnd.innerWidth / 2;
-                this.reportProgress();
+                const targetId = data as string;
+                this.reportProgress(
+                    this.timelineEntries.has(targetId) ? targetId : this.nearestPrecedingTimelineEntry(element)
+                );
                 deselect(this.wnd);
                 ack(true);
             });
@@ -259,7 +273,7 @@ export class CJKVerticalSnapper extends Snapper {
             if (!r) { ack(false); return; }
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollLeft += r.getBoundingClientRect().left - wnd.innerWidth / 2;
-                this.reportProgress();
+                this.reportProgress(this.nearestPrecedingTimelineEntry(r.startContainer));
                 deselect(this.wnd);
                 ack(true);
             });
@@ -269,7 +283,10 @@ export class CJKVerticalSnapper extends Snapper {
         comms.register("go_start", CJKVerticalSnapper.moduleName, (_, ack) => {
             if (this.doc().scrollLeft === 0) return ack(false);
             this.doc().scrollLeft = 0;
-            this.reportProgress();
+            // The first fragment isn't necessarily reached at document start
+            // (there may be content before it) — check only that one element
+            // instead of assuming sortedFragmentIds[0] is already visible.
+            this.reportProgress(this.firstFragmentIfReached());
             ack(true);
         });
 
@@ -279,7 +296,7 @@ export class CJKVerticalSnapper extends Snapper {
         comms.register("go_end", CJKVerticalSnapper.moduleName, (_, ack) => {
             if (Math.abs(this.doc().scrollLeft) === this.scrollable()) return ack(false);
             this.doc().scrollLeft = this.verticalLR ? this.scrollable() : -this.scrollable();
-            this.reportProgress();
+            this.reportProgress(this.sortedFragmentIds[this.sortedFragmentIds.length - 1]);
             ack(true);
         });
 
@@ -311,6 +328,11 @@ export class CJKVerticalSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("timeline_entries", CJKVerticalSnapper.moduleName, (data, ack) => {
+            this.updateTimelineEntries(Array.isArray(data) ? data as string[] : [], wnd);
+            ack(true);
+        });
+
         comms.log("CJKVerticalSnapper Mounted");
         return true;
     }
@@ -327,6 +349,11 @@ export class CJKVerticalSnapper extends Snapper {
             this.isScrollProtectionEnabled = false;
         }
 
+        this.timelineObserver?.disconnect();
+        this.timelineObserver = null;
+        this.visibleFragmentIds.clear();
+        this.timelineEntries.clear();
+
         comms.log("CJKVerticalSnapper Unmounted");
         return true;
     }

package/src/modules/snapper/ColumnSnapper.ts

@@ -72,7 +72,40 @@ export class ColumnSnapper extends Snapper {
         return this.rtl ? Math.abs(raw) : Math.max(0, this.wnd.scrollX > 0 ? this.wnd.scrollX : raw);
     }
 
-    reportProgress() {
+    protected hasScrolledPast(el: Element): boolean {
+        const rect = el.getBoundingClientRect();
+        return this.rtl ? rect.left >= this.wnd.innerWidth : rect.right <= 0;
+    }
+
+    /**
+     * IntersectionObserver cannot be used here. In Chrome and Safari, body's computed
+     * dimensions in a CSS multi-column layout are wrong unless body height is constrained
+     * to 100% *and* overflow is visible — but we can't set overflow: visible, since content
+     * overflowing a column must stay clipped to it rather than bleeding into adjacent
+     * columns. Even with that fix applied, Safari's IntersectionObserver still never fires
+     * a single callback — confirmed dead end there, and WebKit is mandatory on iOS. Firefox
+     * needs no fix at all: it reports accurate body dimensions in this layout regardless.
+     * Use rect-based detection instead: walk elements in DOM order and return the last one
+     * whose leading edge has entered or passed the viewport — that is the current section.
+     */
+    protected currentTimelineFragment(): string | undefined {
+        if (this.timelineEntries.size === 0) return undefined;
+
+        const vw = this.wnd.innerWidth;
+        let result: string | undefined;
+        for (const id of this.sortedFragmentIds) {
+            const el = this.timelineEntries.get(id)!;
+            const rect = el.getBoundingClientRect();
+            // LTR: element has started when its left edge is before the viewport's right.
+            // RTL: element has started when its right edge is past the viewport's left.
+            const started = this.rtl ? rect.right > 0 : rect.left < vw;
+            if (started) result = id;
+            else break;
+        }
+        return result;
+    }
+
+    reportProgress(forcedFragmentId?: string) {
         const scrollWidth = this.cachedScrollWidth;
         const viewportWidth = this.wnd.innerWidth;
         const norm = this.normScroll();
@@ -83,7 +116,8 @@ export class ColumnSnapper extends Snapper {
         const viewportEnd = Math.max(0, Math.min(1, (norm + viewportWidth) / scrollWidth));
         this.comms.send("progress", {
             start: progress,
-            end: viewportEnd
+            end: viewportEnd,
+            fragmentId: forcedFragmentId !== undefined ? forcedFragmentId : this.currentTimelineFragment()
         });
     }
 
@@ -474,7 +508,10 @@ export class ColumnSnapper extends Snapper {
                 } else {
                     this.doc().scrollLeft = this.snapOffset(element.getBoundingClientRect().left + wnd.scrollX);
                 }
-                this.reportProgress();
+                const targetId = data as string;
+                this.reportProgress(
+                    this.timelineEntries.has(targetId) ? targetId : this.nearestPrecedingTimelineEntry(element)
+                );
                 deselect(this.wnd);
                 ack(true);
             });
@@ -509,7 +546,7 @@ export class ColumnSnapper extends Snapper {
                 } else {
                     this.doc().scrollLeft = this.snapOffset(r.getBoundingClientRect().left + wnd.scrollX);
                 }
-                this.reportProgress();
+                this.reportProgress(this.nearestPrecedingTimelineEntry(r.startContainer));
                 deselect(this.wnd);
                 ack(true);
             });
@@ -528,7 +565,7 @@ export class ColumnSnapper extends Snapper {
                 }
                 if(this.doc().scrollLeft === snappedFinal) return ack(false);
                 this.doc().scrollLeft = snappedFinal;
-                this.reportProgress();
+                this.reportProgress(this.sortedFragmentIds[this.sortedFragmentIds.length - 1]);
                 deselect(this.wnd);
                 ack(true);
             });
@@ -538,7 +575,10 @@ export class ColumnSnapper extends Snapper {
             this.wnd.requestAnimationFrame(() => {
                 if(this.doc().scrollLeft === 0) return ack(false);
                 this.doc().scrollLeft = 0;
-                this.reportProgress();
+                // The first fragment isn't necessarily reached at document start
+                // (there may be content before it) — check only that one element
+                // instead of assuming sortedFragmentIds[0] is already visible.
+                this.reportProgress(this.firstFragmentIfReached());
                 deselect(this.wnd);
                 ack(true);
             });
@@ -608,6 +648,12 @@ export class ColumnSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("timeline_entries", ColumnSnapper.moduleName, (data, ack) => {
+            this.updateTimelineEntries(Array.isArray(data) ? data as string[] : [], wnd);
+            wnd.requestAnimationFrame(() => this.reportProgress());
+            ack(true);
+        });
+
         // Add interaction listeners
         wnd.addEventListener("touchstart", this.onTouchStarter, { passive: true });
         wnd.addEventListener("touchend", this.onTouchEnder, { passive: true });
@@ -641,6 +687,8 @@ export class ColumnSnapper extends Snapper {
 
         wnd.document.getElementById(COLUMN_SNAPPER_STYLE_ID)?.remove();
 
+        this.timelineEntries.clear();
+
         comms.log("ColumnSnapper Unmounted");
         return super.unmount(wnd, comms);
     }

package/src/modules/snapper/ScrollSnapper.ts

@@ -37,7 +37,11 @@ export class ScrollSnapper extends Snapper {
         return this.wnd.document.scrollingElement as HTMLElement;
     }
 
-    private reportProgress() {
+    protected hasScrolledPast(el: Element): boolean {
+        return el.getBoundingClientRect().bottom <= 0;
+    }
+
+    private reportProgress(forcedFragmentId?: string) {
         if (!this.comms.ready) return;
         // We have to round up the scroll position because
         // Android may never reach 100% of the scroll height
@@ -50,7 +54,8 @@ export class ScrollSnapper extends Snapper {
 
         this.comms.send("progress", {
             start: progress,
-            end: viewportEnd
+            end: viewportEnd,
+            fragmentId: forcedFragmentId !== undefined ? forcedFragmentId : this.currentTimelineFragment()
         });
     }
 
@@ -124,6 +129,7 @@ export class ScrollSnapper extends Snapper {
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
+        this.setupTimelineObserver();
 
         this.initialScrollHandled = false;
         this.lastScrollTop = 0;
@@ -198,7 +204,9 @@ export class ScrollSnapper extends Snapper {
 
             this.wnd.requestAnimationFrame(() => {
               this.doc().scrollTop = this.doc().offsetHeight * position;
-              this.reportProgress();
+              // No known target fragment for an arbitrary position — force a fresh
+              // geometry scan instead of trusting a possibly-stale visibility cache.
+              this.reportProgress(this.fragmentFromGeometry());
               deselect(this.wnd);
               ack(true);
           });
@@ -212,7 +220,10 @@ export class ScrollSnapper extends Snapper {
             }
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollTop = element.getBoundingClientRect().top + wnd.scrollY - wnd.innerHeight / 2;
-                this.reportProgress();
+                const targetId = data as string;
+                this.reportProgress(
+                    this.timelineEntries.has(targetId) ? targetId : this.nearestPrecedingTimelineEntry(element)
+                );
                 deselect(this.wnd);
                 ack(true);
             });
@@ -243,7 +254,7 @@ export class ScrollSnapper extends Snapper {
             }
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollTop = r.getBoundingClientRect().top + wnd.scrollY - wnd.innerHeight / 2;
-                this.reportProgress();
+                this.reportProgress(this.nearestPrecedingTimelineEntry(r.startContainer));
                 deselect(this.wnd);
                 ack(true);
             });
@@ -252,14 +263,17 @@ export class ScrollSnapper extends Snapper {
         comms.register("go_start", ScrollSnapper.moduleName, (_, ack) => {
             if (this.doc().scrollTop === 0) return ack(false);
             this.doc().scrollTop = 0;
-            this.reportProgress();
+            // The first fragment isn't necessarily reached at document start
+            // (there may be content before it) — check only that one element
+            // instead of assuming sortedFragmentIds[0] is already visible.
+            this.reportProgress(this.firstFragmentIfReached());
             ack(true);
         });
 
         comms.register("go_end", ScrollSnapper.moduleName, (_, ack) => {
             if (this.doc().scrollTop === this.doc().scrollHeight - this.doc().offsetHeight) return ack(false);
             this.doc().scrollTop = this.doc().scrollHeight - this.doc().offsetHeight;
-            this.reportProgress();
+            this.reportProgress(this.sortedFragmentIds[this.sortedFragmentIds.length - 1]);
             ack(true);
         })
 
@@ -289,6 +303,11 @@ export class ScrollSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("timeline_entries", ScrollSnapper.moduleName, (data, ack) => {
+            this.updateTimelineEntries(Array.isArray(data) ? data as string[] : [], wnd);
+            ack(true);
+        });
+
         comms.log("ScrollSnapper Mounted");
         return true;
     }
@@ -298,6 +317,10 @@ export class ScrollSnapper extends Snapper {
         this.resizeObserver.disconnect();
         if (this.handleScroll) wnd.removeEventListener("scroll", this.handleScroll);
         wnd.document.getElementById(SCROLL_SNAPPER_STYLE_ID)?.remove();
+        this.timelineObserver?.disconnect();
+        this.timelineObserver = null;
+        this.visibleFragmentIds.clear();
+        this.timelineEntries.clear();
 
         if (this.patternAnalyzer) {
             this.patternAnalyzer.clear();

package/src/modules/snapper/Snapper.ts

@@ -10,6 +10,150 @@ export abstract class Snapper extends Module {
 
     private protected = false;
 
+    // Timeline fragment tracking
+    protected timelineObserver: IntersectionObserver | null = null;
+    protected timelineEntries: Map<string, Element> = new Map();
+    protected visibleFragmentIds: Set<string> = new Set();
+    protected cachedFragmentIds: string[] = [];
+    // DOM-order-sorted fragment ids, recomputed only when entries are (re)populated —
+    // sorting on every progress report (i.e. every scroll frame) is wasted work.
+    protected sortedFragmentIds: string[] = [];
+
+    private static inDomOrder(entries: Map<string, Element>, a: string, b: string): number {
+        const ea = entries.get(a);
+        const eb = entries.get(b);
+        if (!ea || !eb) return 0;
+        const cmp = ea.compareDocumentPosition(eb);
+        return cmp & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+    }
+
+    /**
+     * A zero-area target (e.g. an empty `<a id="…">` landmark) always has
+     * intersectionRatio 0 by spec, so `isIntersecting` can never become true for it —
+     * no threshold value changes that. For those entries, fall back to a geometric
+     * containment check against `rootBounds` instead of trusting `isIntersecting`.
+     */
+    private static isVisibleEntry(entry: IntersectionObserverEntry): boolean {
+        const rect = entry.boundingClientRect;
+        // Element has real width and height: isIntersecting is spec-correct, trust it as-is.
+        if (rect.width > 0 && rect.height > 0) return entry.isIntersecting;
+        // Zero-width or zero-height element: isIntersecting is stuck at false (ratio is
+        // area / 0, defined as 0), so it can't be trusted. Do our own overlap check instead.
+        const root = entry.rootBounds;
+        if (!root) return entry.isIntersecting;
+        return rect.left <= root.right && rect.right >= root.left &&
+            rect.top <= root.bottom && rect.bottom >= root.top;
+    }
+
+    protected setupTimelineObserver(): void {
+        if (this.timelineObserver) this.timelineObserver.disconnect();
+        this.timelineObserver = new IntersectionObserver(
+            (entries) => {
+                for (const entry of entries) {
+                    if (Snapper.isVisibleEntry(entry))
+                        this.visibleFragmentIds.add((entry.target as HTMLElement).id);
+                    else
+                        this.visibleFragmentIds.delete((entry.target as HTMLElement).id);
+                }
+            },
+            { threshold: [0.01] }
+        );
+    }
+
+    /**
+     * Populates `timelineEntries`/`sortedFragmentIds` from a fresh id list, and
+     * (re)starts IntersectionObserver-based visibility tracking for subclasses that use it.
+     * Shared by all snappers' `timeline_entries` comms handler so DOM-order sorting and
+     * observer bookkeeping only happen once per (re)population, not per report.
+     */
+    protected updateTimelineEntries(ids: string[], wnd: ReadiumWindow): void {
+        this.cachedFragmentIds = ids;
+        this.timelineObserver?.disconnect();
+        this.visibleFragmentIds.clear();
+        this.timelineEntries.clear();
+        for (const id of ids) {
+            const el = wnd.document.getElementById(id);
+            if (el) {
+                this.timelineEntries.set(id, el);
+                this.timelineObserver?.observe(el);
+            }
+        }
+        this.sortedFragmentIds = Array.from(this.timelineEntries.keys())
+            .sort((a, b) => Snapper.inDomOrder(this.timelineEntries, a, b));
+    }
+
+    /**
+     * Returns the nearest fragment at or before `node` in DOM (reading) order, with no
+     * dependency on rendered geometry — safe to call for programmatic navigation where the
+     * target is already known, regardless of whether layout/IntersectionObserver has settled.
+     */
+    protected nearestPrecedingTimelineEntry(node: Node): string | undefined {
+        let nearestId: string | undefined;
+        for (const id of this.sortedFragmentIds) {
+            const el = this.timelineEntries.get(id)!;
+            const cmp = el.compareDocumentPosition(node);
+            const nodeFollowsEl = el === node || el.contains(node) ||
+                (cmp & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+            if (nodeFollowsEl) nearestId = id;
+            else break;
+        }
+        return nearestId;
+    }
+
+    /**
+     * Rect-based scan: last element in DOM order whose leading edge has already been
+     * scrolled past. Subclasses implement `hasScrolledPast` for their layout/axis.
+     * Exposed so callers can force an accurate one-off geometry check (e.g. right after
+     * a `go_progression` jump) instead of trusting a possibly-stale visibility cache.
+     */
+    protected fragmentFromGeometry(): string | undefined {
+        let nearestId: string | undefined;
+        for (const id of this.sortedFragmentIds) {
+            const el = this.timelineEntries.get(id)!;
+            if (this.hasScrolledPast(el)) nearestId = id;
+            else break;
+        }
+        return nearestId;
+    }
+
+    /**
+     * go_start-specific check: whether the first known fragment's leading edge has
+     * already been scrolled past, checking only that one element rather than scanning
+     * the whole timeline. At document start there is nothing before the first fragment
+     * to confuse the result, so a single rect check is sufficient (and cheaper than
+     * `fragmentFromGeometry`).
+     */
+    protected firstFragmentIfReached(): string | undefined {
+        const id = this.sortedFragmentIds[0];
+        if (id === undefined) return undefined;
+        const el = this.timelineEntries.get(id)!;
+        return this.hasScrolledPast(el) ? id : undefined;
+    }
+
+    /**
+     * Returns the ID of the currently active timeline fragment:
+     * 1. Primary — IntersectionObserver: returns the first visible element in DOM (reading) order.
+     *    This is direction-agnostic; works for LTR, RTL, and vertical writing modes. Reliable for
+     *    continuous, gradual scrolling.
+     * 2. Fallback — rect scan (`fragmentFromGeometry`): used when IntersectionObserver hasn't
+     *    fired yet. Not reliable right after an instantaneous programmatic jump — callers that
+     *    know the target (goTo-style navigation) should bypass this method entirely.
+     */
+    protected currentTimelineFragment(): string | undefined {
+        if (this.visibleFragmentIds.size > 0) {
+            return Array.from(this.visibleFragmentIds)
+                .sort((a, b) => Snapper.inDomOrder(this.timelineEntries, a, b))[0];
+        }
+        return this.fragmentFromGeometry();
+    }
+
+    /**
+     * Returns true if the element's leading edge (in reading direction) has been scrolled past
+     * — i.e. the element is before the current viewport position.
+     * Subclasses implement this for their specific scroll axis and reading direction.
+     */
+    protected abstract hasScrolledPast(el: Element): boolean;
+
     buildStyles() {
         return `
         html, body {

package/src/modules/snapper/WebPubSnapper.ts

@@ -31,7 +31,11 @@ export class WebPubSnapper extends Snapper {
         return this.wnd.document.scrollingElement as HTMLElement;
     }
 
-    private reportProgress() {
+    protected hasScrolledPast(el: Element): boolean {
+        return el.getBoundingClientRect().bottom <= 0;
+    }
+
+    private reportProgress(forcedFragmentId?: string) {
         if (!this.comms.ready) return;
 
         const scrollTop = Math.ceil(this.doc().scrollTop);
@@ -42,7 +46,8 @@ export class WebPubSnapper extends Snapper {
 
         this.comms.send("progress", {
             start: progress,
-            end: viewportEnd
+            end: viewportEnd,
+            fragmentId: forcedFragmentId !== undefined ? forcedFragmentId : this.currentTimelineFragment()
         });
     }
 
@@ -115,6 +120,7 @@ export class WebPubSnapper extends Snapper {
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
+        this.setupTimelineObserver();
 
         this.initialScrollHandled = false;
         this.lastScrollTop = 0;
@@ -170,7 +176,9 @@ export class WebPubSnapper extends Snapper {
 
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollTop = this.doc().offsetHeight * position;
-                this.reportProgress();
+                // No known target fragment for an arbitrary position — force a fresh
+                // geometry scan instead of trusting a possibly-stale visibility cache.
+                this.reportProgress(this.fragmentFromGeometry());
                 deselect(this.wnd);
                 ack(true);
             });
@@ -184,7 +192,10 @@ export class WebPubSnapper extends Snapper {
             }
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollTop = element.getBoundingClientRect().top + wnd.scrollY - wnd.innerHeight / 2;
-                this.reportProgress();
+                const targetId = data as string;
+                this.reportProgress(
+                    this.timelineEntries.has(targetId) ? targetId : this.nearestPrecedingTimelineEntry(element)
+                );
                 deselect(this.wnd);
                 ack(true);
             });
@@ -214,7 +225,7 @@ export class WebPubSnapper extends Snapper {
             }
             this.wnd.requestAnimationFrame(() => {
                 this.doc().scrollTop = r.getBoundingClientRect().top + wnd.scrollY - wnd.innerHeight / 2;
-                this.reportProgress();
+                this.reportProgress(this.nearestPrecedingTimelineEntry(r.startContainer));
                 deselect(this.wnd);
                 ack(true);
             });
@@ -223,14 +234,17 @@ export class WebPubSnapper extends Snapper {
         comms.register("go_start", WebPubSnapper.moduleName, (_, ack) => {
             if (this.doc().scrollTop === 0) return ack(false);
             this.doc().scrollTop = 0;
-            this.reportProgress();
+            // The first fragment isn't necessarily reached at document start
+            // (there may be content before it) — check only that one element
+            // instead of assuming sortedFragmentIds[0] is already visible.
+            this.reportProgress(this.firstFragmentIfReached());
             ack(true);
         });
 
         comms.register("go_end", WebPubSnapper.moduleName, (_, ack) => {
             if (this.doc().scrollTop === this.doc().scrollHeight - this.doc().offsetHeight) return ack(false);
             this.doc().scrollTop = this.doc().scrollHeight - this.doc().offsetHeight;
-            this.reportProgress();
+            this.reportProgress(this.sortedFragmentIds[this.sortedFragmentIds.length - 1]);
             ack(true);
         });
 
@@ -259,6 +273,11 @@ export class WebPubSnapper extends Snapper {
             ack(true);
         });
 
+        comms.register("timeline_entries", WebPubSnapper.moduleName, (data, ack) => {
+            this.updateTimelineEntries(Array.isArray(data) ? data as string[] : [], wnd);
+            ack(true);
+        });
+
         comms.log("WebPubSnapper Mounted");
         return true;
     }
@@ -274,6 +293,11 @@ export class WebPubSnapper extends Snapper {
             this.isScrollProtectionEnabled = false;
         }
 
+        this.timelineObserver?.disconnect();
+        this.timelineObserver = null;
+        this.visibleFragmentIds.clear();
+        this.timelineEntries.clear();
+
         comms.log("WebPubSnapper Unmounted");
         return true;
     }

package/types/src/comms/comms.d.ts

@@ -15,11 +15,20 @@ export interface Registrant {
 }
 export type CommsAck = (ok: boolean) => void;
 export type CommsCallback = (data: unknown, ack: CommsAck) => void;
+export interface IComms {
+    register(key: CommsCommandKey | CommsCommandKey[], module: string, callback: CommsCallback): void;
+    unregister(key: CommsCommandKey | CommsCommandKey[], module: string): void;
+    unregisterAll(module: string): void;
+    send(key: CommsEventKey, data: unknown, id?: unknown, transfer?: Transferable[]): void;
+    log(...data: any[]): void;
+    readonly ready: boolean;
+    destroy(): void;
+}
 /**
  * Comms is basically a wrapper around window.postMessage that
  * adds structure to the messages and lets modules register callbacks.
  */
-export declare class Comms {
+export declare class Comms implements IComms {
     private readonly wnd;
     private destination;
     private registrar;

package/types/src/comms/keys.d.ts

@@ -1,3 +1,3 @@
-export type CommsEventKey = "_pong" | "_unhandled" | "_ack" | "log" | "error" | "click" | "tap" | "tap_more" | "no_more" | "no_less" | "swipe" | "scroll" | "progress" | "first_visible_locator" | "text_selected" | "context_menu" | "media_play" | "media_pause" | "content_protection" | "keyboard_peripherals" | "decoration_activated";
-export type CommsCommandKey = "_ping" | "go_prev" | "go_next" | "go_id" | "go_text" | "go_end" | "go_start" | "go_progression" | "get_properties" | "update_properties" | "set_property" | "remove_property" | "first_visible_locator" | "decorate" | "decoration_activatable" | "protect" | "unprotect" | "unfocus" | "focus" | "activate" | "shake" | "force_webkit_recalc" | "peripherals_protection" | "keyboard_peripherals" | "scroll_protection" | "print_protection";
+export type CommsEventKey = "_pong" | "_unhandled" | "_ack" | "log" | "error" | "click" | "tap" | "tap_more" | "no_more" | "no_less" | "swipe" | "scroll" | "progress" | "first_visible_locator" | "text_selected" | "context_menu" | "media_play" | "media_pause" | "content_protection" | "keyboard_peripherals" | "decoration_activated" | "decoration_pointer_enter" | "decoration_pointer_leave";
+export type CommsCommandKey = "_ping" | "go_prev" | "go_next" | "go_id" | "go_text" | "go_end" | "go_start" | "go_progression" | "get_properties" | "update_properties" | "set_property" | "remove_property" | "first_visible_locator" | "decorate" | "decoration_activatable" | "decoration_hoverable" | "protect" | "unprotect" | "unfocus" | "focus" | "activate" | "shake" | "force_webkit_recalc" | "peripherals_protection" | "keyboard_peripherals" | "scroll_protection" | "print_protection" | "timeline_entries";
 export type SuspiciousActivityType = "developer_tools" | "select_all" | "save" | "suspicious_selection" | "bulk_copy" | "suspicious_scrolling" | "suspicious_snapping" | "drag_detected" | "drop_detected" | "print";

package/types/src/helpers/css.d.ts

@@ -11,6 +11,6 @@ export declare function getProperties(wnd: ReadiumWindow): {
 export declare function updateProperties(wnd: ReadiumWindow, properties: {
     [key: string]: string;
 }): void;
-export declare function getProperty(wnd: ReadiumWindow, key: string): string;
+export declare function getProperty(wnd: Window, key: string): string;
 export declare function setProperty(wnd: ReadiumWindow, key: string, value: string): void;
 export declare function removeProperty(wnd: ReadiumWindow, key: string): void;

package/types/src/helpers/document.d.ts

@@ -1,7 +1,7 @@
 import { ReadiumWindow } from "./dom.ts";
-export declare function isRTL(wnd: ReadiumWindow): boolean;
-export declare function isVerticalLR(wnd: ReadiumWindow): boolean;
-export declare function isVerticalWriting(wnd: ReadiumWindow): boolean;
+export declare function isRTL(wnd: Window): boolean;
+export declare function isVerticalLR(wnd: Window): boolean;
+export declare function isVerticalWriting(wnd: Window): boolean;
 /**
  * Axis-normalizing context for decoration layout.
  *
@@ -66,8 +66,8 @@ export interface WritingContext {
     /** Convert logical coordinates back to a physical DOMRect. */
     toRect(inlineStart: number, blockStart: number, inlineSize: number, blockSize: number): DOMRect;
 }
-export declare function makeWritingContext(wnd: ReadiumWindow): WritingContext;
-export declare function getColumnCountPerScreen(wnd: ReadiumWindow): number;
+export declare function makeWritingContext(wnd: Window): WritingContext;
+export declare function getColumnCountPerScreen(wnd: Window): number;
 /**
 * Returns the "content height" of an element, which is its clientHeight
 * minus any vertical padding.

package/types/src/helpers/rect.d.ts

@@ -6,5 +6,6 @@ export interface Rect {
     top: number;
     width: number;
 }
-export declare function getClientRectsNoOverlap(range: Range, doNotMergeHorizontallyAlignedRects: boolean, doNotMergeVerticallyAlignedRects?: boolean): Rect[];
+export declare function getTextClientRects(range: Range, skipTags: string[]): Rect[];
+export declare function getClientRectsNoOverlap(source: Range | Rect[], doNotMergeHorizontallyAlignedRects: boolean, doNotMergeVerticallyAlignedRects?: boolean, expand?: number): Rect[];
 export declare function rectContainsPoint(rect: Rect, x: number, y: number, tolerance: number): boolean;

package/types/src/index.d.ts

@@ -2,5 +2,5 @@ export * from './comms/index.ts';
 export * from './modules/index.ts';
 export * from './Loader.ts';
 export * from './protection/index.ts';
-export * from './helpers/sML.ts';
+export type { ReadiumWindow } from './helpers/dom.ts';
 export * from './keyboard/index.ts';