@readium/shared 2.4.0-alpha.1 → 2.5.0

package/src/publication/opds/Properties.ts

@@ -3,82 +3,37 @@ import { positiveNumberfromJSON } from '../../util/JSONParse.ts';
 import { Link } from '../Link.ts';
 import { Properties } from '../Properties.ts';
 
-// OPDS extensions for link [Properties].
+// OPDS extensions for link Properties.
 // https://specs.opds.io/schema/properties.schema.json
 
-declare module '../Properties' {
-  export interface Properties {
-    /**
-     * Provides a hint about the expected number of items returned.
-     */
-    getNumberOfItems(): number | undefined;
-
-    /**
-     * The price of a publication is tied to its acquisition link.
-     */
-    getPrice(): Price | undefined;
-
-    /**
-     * Indirect acquisition provides a hint for the expected media type that will be acquired after
-     * additional steps.
-     */
-    getIndirectAcquisitions(): Array<Acquisition> | undefined;
-
-    /**
-     * Library-specific features when a specific book is unavailable but provides a hold list.
-     */
-    getHolds(): Holds | undefined;
-
-    /**
-     * Library-specific feature that contains information about the copies that a library has acquired.
-     */
-    getCopies(): Copies | undefined;
-
-    /**
-     * Indicated the availability of a given resource.
-     */
-    getAvailability(): Availability | undefined;
-
-    /**
-     * Indicates that the linked resource supports authentication with the associated Authentication
-     * Document.
-     *
-     * See https://specs.opds.io/authentication-for-opds-1.0.html
-     */
-    getAuthenticate(): Link | undefined;
-  }
+export function getNumberOfItems(properties: Properties): number | undefined {
+  return positiveNumberfromJSON(properties.otherProperties['numberOfItems']);
 }
 
-Properties.prototype.getNumberOfItems = function(): number | undefined {
-  return positiveNumberfromJSON(this.otherProperties['numberOfItems']);
-};
-
-Properties.prototype.getPrice = function(): Price | undefined {
-  return Price.deserialize(this.otherProperties['price']);
-};
+export function getPrice(properties: Properties): Price | undefined {
+  return Price.deserialize(properties.otherProperties['price']);
+}
 
-Properties.prototype.getIndirectAcquisitions = function():
-  | Array<Acquisition>
-  | undefined {
-  const json = this.otherProperties['indirectAcquisition'];
+export function getIndirectAcquisitions(properties: Properties): Array<Acquisition> | undefined {
+  const json = properties.otherProperties['indirectAcquisition'];
   if (!(json && Array.isArray(json))) return;
   return json
     .map<Acquisition>(item => Acquisition.deserialize(item) as Acquisition)
     .filter(x => x !== undefined);
-};
+}
 
-Properties.prototype.getHolds = function(): Holds | undefined {
-  return Holds.deserialize(this.otherProperties['holds']);
-};
+export function getHolds(properties: Properties): Holds | undefined {
+  return Holds.deserialize(properties.otherProperties['holds']);
+}
 
-Properties.prototype.getCopies = function(): Copies | undefined {
-  return Copies.deserialize(this.otherProperties['copies']);
-};
+export function getCopies(properties: Properties): Copies | undefined {
+  return Copies.deserialize(properties.otherProperties['copies']);
+}
 
-Properties.prototype.getAvailability = function(): Availability | undefined {
-  return Availability.deserialize(this.otherProperties['availability']);
-};
+export function getAvailability(properties: Properties): Availability | undefined {
+  return Availability.deserialize(properties.otherProperties['availability']);
+}
 
-Properties.prototype.getAuthenticate = function(): Link | undefined {
-  return Link.deserialize(this.otherProperties['authenticate']);
-};
+export function getAuthenticate(properties: Properties): Link | undefined {
+  return Link.deserialize(properties.otherProperties['authenticate']);
+}

package/src/publication/opds/Publication.ts

@@ -1,14 +1,8 @@
 import { Links } from '../Link.ts';
 import { Publication } from '../Publication.ts';
 
-// OPDS extensions for [Publication]
+// OPDS extensions for Publication.
 
-declare module '../Publication' {
-  export interface Publication {
-    getImages(): Links | undefined;
-  }
+export function getImages(pub: Publication): Links | undefined {
+  return pub.linksWithRole('images');
 }
-
-Publication.prototype.getImages = function(): Links | undefined {
-  return this.linksWithRole('images');
-};

package/src/publication/services/content/iterators/HTMLResourceContentIterator.ts

@@ -5,6 +5,7 @@ import { IllegalStateError, Iterator } from "../Iterator.ts";
 import { Attribute, AttributeKeys, AudioElement, Body, ContentElement, Footnote, Heading, ImageElement, TextElement, TextQuote, TextRole, TextSegment, VideoElement } from "../element/index.ts";
 import { appendNormalizedWhitespace, elementLanguage, isBlank, isInlineTag, srcRelativeToHref, trimUnicodeSpace, trimUnicodeSpaceEnd, trimUnicodeSpaceStart, trimmingTextLocator } from "./helpers.ts";
 import { getCssSelector } from "css-selector-generator";
+import { getCssSelector as locatorCssSelector } from "../../../html/Locations.ts";
 
 interface ElementWithDelta {
     element: ContentElement;
@@ -93,10 +94,11 @@ export class HTMLResourceContentIterator extends Iterator {
     private async parseElements(): Promise<ParsedElementRecipes> {
         const raw = await this.resource.readAsString();
         const doc = (new DOMParser()).parseFromString(raw!, this.locator.type as DOMParserSupportedType);
+        const startSel = locatorCssSelector(this.locator.locations);
         this.parser = new ContentParser(
             doc,
             this.locator,
-            this.locator.locations.getCssSelector() ? doc.querySelector(this.locator.locations.getCssSelector()!) as Element : null,
+            startSel ? doc.querySelector(startSel) as Element : null,
             this.beforeMaxLength
         );
 

package/src/publication/services/timeline/Timeline.ts

@@ -1,11 +1,31 @@
 import { Link, Links } from "../../Link.ts";
 import { Locator } from "../../Locator.ts";
+import { getHtmlId, getTime } from "../../html/Locations.ts";
+import { Profile } from "../../Profiles.ts";
+import { formatNptTime, isNptStartOfResource, parseNptTime } from "../../../util/npt.ts";
 import { TimelineItem } from "./TimelineItem.ts";
-import { isNptStartOfResource, parseNptTime } from "../../../util/npt.ts";
 
-interface PublicationLike {
+export interface PublicationLike {
     toc?: Links;
     readingOrder: Links;
+    metadata?: { conformsTo?: Profile[] };
+}
+
+/**
+ * A TOC entry, mirroring `publication.toc`'s authored hierarchy and
+ * contextualized with display-ready progression.  When a publication has no
+ * `toc` at all, falls back to one flat entry per reading-order item.
+ *
+ * Exactly one of `position`/`timestamp` is populated, depending on the
+ * publication's profile.
+ */
+export interface ContextualizedTocEntry {
+    link: Link;
+    /** Display-ready label for non-audio profiles: a Positions List position for EPUB, a page number for PDF (e.g. "42"). */
+    position?: string;
+    /** Display-ready formatted time for audiobooks (e.g. "27:27"). */
+    timestamp?: string;
+    children?: ContextualizedTocEntry[];
 }
 
 /**
@@ -17,32 +37,61 @@ interface PublicationLike {
  *   2. Populate flat children — all TOC fragment entries that reference the
  *      resource, collected depth-first in TOC declaration order.
  *
- * No TOC hierarchy is reconstructed; that requires role context and is not yet
- * implemented.  TOC entries whose href does not match any reading order item
- * are ignored.
+ * `contextualizedToc` returns the authored TOC hierarchy (see
+ * `ContextualizedTocEntry`), each entry contextualized with progression.
+ * `tocEntryFor(item)` maps a `TimelineItem` (e.g. from
+ * `locate()`) back to its entry in that hierarchy.  TOC entries whose href
+ * does not match any reading order item are ignored.
  *
- * The `depth` build option limits how many levels deep into the TOC tree both
- * title resolution and child collection may look.  Level 1 = top-level TOC
- * entries; level 2 = their children; etc.  `undefined` means no limit.
+ * The `depth` build option limits how many levels deep into the TOC tree
+ * title resolution, child collection, and `contextualizedToc` traversal may
+ * look.  Level 1 = top-level TOC entries; level 2 = their children; etc.
+ * `undefined` means no limit.
  */
 export class Timeline {
     private readonly _allItems: TimelineItem[];
     private readonly linkMap: Map<TimelineItem, Link>;
+    private readonly _conformsTo: readonly Profile[];
+    private readonly tocLinks: Link[];
     private _depth: number | undefined;
+    /**
+     * Depth used for `contextualizedToc` traversal.  Tracks `_depth`, but is
+     * seeded independently from `Timeline.build()`'s `depth` option: unlike
+     * `_depth`, which only ever triggers `items`/`flat` re-trimming via the
+     * runtime `depth` setter, the TOC tree is walked fresh from `tocLinks`
+     * every time, so there's no equivalent "already baked in, don't reapply"
+     * hazard to avoid.
+     */
+    private _tocDepth: number | undefined;
     private _items: TimelineItem[] | undefined;
     private _flat: TimelineItem[] | undefined;
+    private _toc: ContextualizedTocEntry[] | undefined;
+    private _linkToItem: Map<Link, TimelineItem> | undefined;
     /** Populated when depth is set; maps cloned items from trimToDepth back to their Links. */
     private _trimmedLinkMap: Map<TimelineItem, Link> = new Map();
 
-    constructor(items: TimelineItem[], linkMap: Map<TimelineItem, Link>) {
+    constructor(
+        items: TimelineItem[],
+        linkMap: Map<TimelineItem, Link>,
+        conformsTo: readonly Profile[] = [],
+        tocLinks: Link[] = [],
+        tocDepth: number | undefined = undefined,
+    ) {
         this._allItems = items;
         this.linkMap = linkMap;
+        this._conformsTo = conformsTo;
+        this.tocLinks = tocLinks;
+        this._tocDepth = tocDepth;
     }
 
-    static build(publication: PublicationLike, options: { depth?: number } = {}): Timeline {
+    static build(
+        publication: PublicationLike,
+        options: { depth?: number } = {},
+    ): Timeline {
         const tocLinks = publication.toc?.items ?? [];
         const roLinks = publication.readingOrder.items;
         const { depth } = options;
+        const conformsTo = publication.metadata?.conformsTo ?? [];
         const linkMap = new Map<TimelineItem, Link>();
         const items: TimelineItem[] = [];
 
@@ -52,8 +101,7 @@ export class Timeline {
 
             const title =
                 ro.title ??
-                Timeline.findTitleInToc(tocLinks, bare, depth) ??
-                `Resource ${i + 1}`;
+                Timeline.findTitleInToc(tocLinks, bare, depth);
 
             const tocChildren = Timeline.collectChildrenFromToc(tocLinks, bare, depth, 1, linkMap);
 
@@ -67,7 +115,25 @@ export class Timeline {
             items.push(item);
         }
 
-        return new Timeline(items, linkMap);
+        return new Timeline(items, linkMap, conformsTo, tocLinks, depth);
+    }
+
+    /**
+     * Augments all items in the timeline by applying the mapper's returned patch.
+     * The mapper receives the item and its original manifest Link, and returns
+     * a partial TimelineItem — any fields it sets will overwrite the item's
+     * current value.  Use this to populate `position`, `scroll`, `role`, or any
+     * future TimelineItem fields from format-specific data.
+     */
+    augment(mapper: (item: TimelineItem, link: Link) => Partial<TimelineItem>): void {
+        for (const item of this.flatAll) {
+            const link = this.linkFor(item);
+            if (!link) continue;
+            const patch = mapper(item, link);
+            if (patch.position !== undefined) item.position = patch.position;
+            if (patch.scroll   !== undefined) item.scroll   = patch.scroll;
+            if (patch.role     !== undefined) item.role     = patch.role;
+        }
     }
 
     /**
@@ -82,8 +148,10 @@ export class Timeline {
     set depth(value: number | undefined) {
         if (this._depth === value) return;
         this._depth = value;
+        this._tocDepth = value;
         this._items = undefined;
         this._flat = undefined;
+        this._toc = undefined;
     }
 
     /** Top-level timeline items.  Cached; invalidated when `depth` changes. */
@@ -101,29 +169,67 @@ export class Timeline {
 
     locate(locator: Locator): TimelineItem | undefined {
         const href = locator.href.split("#")[0];
-        const time = locator.locations?.time();
-
-        let match: TimelineItem | undefined;
+        const time = getTime(locator.locations);
+        const htmlId = getHtmlId(locator.locations);
+        const progression = locator.locations.progression;
 
+        // Audio: best-match on t= start time.
         if (time !== undefined) {
             let bestTime = -Infinity;
+            let match: TimelineItem | undefined;
             for (const item of this.flat) {
+                if (!this.itemMatchesHref(item, href)) continue;
                 const t = this.itemStartTime(item, href);
                 if (t !== undefined && t <= time && t > bestTime) {
                     bestTime = t;
                     match = item;
                 }
             }
+            if (match) return match;
         }
 
-        if (!match) {
-            match = this.flat.find(item => this.bareHrefFromItem(item) === href);
+        // EPUB: match on HTML ID fragment.
+        if (htmlId) {
+            const match = this.flat.find(item => {
+                if (!this.itemMatchesHref(item, href)) return false;
+                return item.references.some(ref => ref.split("#")[1] === htmlId);
+            });
+            if (match) return match;
+        }
+
+        // EPUB: best-match on scroll progression.
+        if (progression !== undefined) {
+            let bestScroll = -Infinity;
+            let match: TimelineItem | undefined;
+            for (const item of this.flat) {
+                if (!this.itemMatchesHref(item, href)) continue;
+                const s = this.itemScrollPosition(item);
+                if (s !== undefined && s <= progression && s > bestScroll) {
+                    bestScroll = s;
+                    match = item;
+                }
+            }
+            if (match) return match;
+
+            // No scroll data resolved anywhere in this resource yet: guess a
+            // child by evenly dividing the fraction across its children,
+            // rather than naming the whole resource.
+            const container = this.items.find(i => this.itemMatchesHref(i, href));
+            if (container?.children?.length && !container.children.some(c => c.scroll !== undefined)) {
+                const index = Math.min(
+                    Math.floor(progression * container.children.length),
+                    container.children.length - 1,
+                );
+                return container.children[index];
+            }
         }
 
-        return match;
+        // Fallback: bare href match.
+        return this.flat.find(item => this.itemMatchesHref(item, href));
     }
 
-    adjacentTo(item: TimelineItem): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
+    /** The items navigable to/from `item`: its previous/next neighbors in the flattened timeline. */
+    navigableFrom(item: TimelineItem): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
         const index = this.flat.indexOf(item);
         return {
             previous: index > 0 ? this.flat[index - 1] : undefined,
@@ -133,35 +239,11 @@ export class Timeline {
 
     segmentsForHref(href: string): TimelineItem[] {
         const bare = href.split("#")[0];
-        const item = this.items.find(i => this.bareHrefFromItem(i) === bare);
+        const item = this.items.find(i => this.itemMatchesHref(i, bare));
         if (!item) return [];
         return item.children?.length ? item.children : [item];
     }
 
-    itemAtProgression(href: string, progression: number, duration?: number): TimelineItem | undefined {
-        const bare = href.split("#")[0];
-        const item = this.items.find(i => this.bareHrefFromItem(i) === bare);
-        if (!item) return undefined;
-        if (!item.children?.length) return item;
-
-        if (duration !== undefined) {
-            const time = progression * duration;
-            let match: TimelineItem = item;
-            let bestTime = -Infinity;
-            for (const child of item.children) {
-                const t = this.timeFromItem(child);
-                if (t !== undefined && t <= time && t > bestTime) {
-                    bestTime = t;
-                    match = child;
-                }
-            }
-            return match;
-        }
-
-        const index = Math.min(Math.floor(progression * item.children.length), item.children.length - 1);
-        return item.children[index];
-    }
-
     ancestors(item: TimelineItem): TimelineItem[] {
         return this.ancestorPath(this.items, item) ?? [];
     }
@@ -170,11 +252,52 @@ export class Timeline {
         return this.linkMap.get(item) ?? this._trimmedLinkMap.get(item);
     }
 
+    /**
+     * The authored TOC, contextualized with display-ready progression.  Mirrors
+     * `publication.toc`'s authored hierarchy (respecting `depth`), falling
+     * back to one flat entry per reading-order item when there's no toc at
+     * all.  Cached; invalidated when `depth` changes.
+     */
+    get contextualizedToc(): ContextualizedTocEntry[] {
+        if (!this._toc) {
+            this._toc = this.tocLinks.length > 0
+                ? this.buildTocEntries(this.tocLinks, this._tocDepth, 1)
+                : this._allItems.map(item => this.entryFor(this.linkFor(item)!, item));
+        }
+        return this._toc;
+    }
+
+    /**
+     * Maps a `TimelineItem` (typically from `locate()`) to its `ContextualizedTocEntry`,
+     * trying three fallbacks in order:
+     *   1. A direct match on `current`'s own link.
+     *   2. The nearest preceding toc entry within the same resource.
+     *   3. When no toc entry references the resource at all, the nearest
+     *      preceding resource's toc entry.
+     */
+    tocEntryFor(current: TimelineItem): ContextualizedTocEntry | undefined {
+        const link = this.linkFor(current);
+        if (!link) return undefined;
+
+        const direct = this.findTocEntryByLink(this.contextualizedToc, link);
+        if (direct) return direct;
+
+        const nearest = this.nearestTocEntryForResource(link.href, current);
+        if (nearest) return nearest;
+
+        return this.previousResolvedTocEntry(link);
+    }
+
     private get flat(): TimelineItem[] {
         if (!this._flat) this._flat = this.flattenItems(this.items);
         return this._flat;
     }
 
+    /** All items flattened from _allItems, depth-independent — used by augment(). */
+    private get flatAll(): TimelineItem[] {
+        return this.flattenItems(this._allItems);
+    }
+
     // -------------------------------------------------------------------------
     // TOC title resolution
     // -------------------------------------------------------------------------
@@ -215,8 +338,20 @@ export class Timeline {
         const result: TimelineItem[] = [];
 
         for (const link of tocLinks) {
-            if (Timeline.bareHref(link.href) === bare && link.title && !Timeline.isStartOfResource(link.href)) {
-                const child: TimelineItem = { title: link.title, references: [link.href] };
+            const linkBare = Timeline.bareHref(link.href);
+            // Fragment-only hrefs (e.g. "#t=60" in single-track audio) have no bare href,
+            // so they are associated with the current resource. A hrefless link (e.g. a
+            // <span> grouping heading) also bareHrefs to '', but names no resource at all
+            // and must not match every resource.
+            const isFragmentOnly = link.href.startsWith('#');
+            const matchesBare = linkBare === bare || (isFragmentOnly && linkBare === '');
+            if (matchesBare && link.title && !Timeline.isStartOfResource(link.href)) {
+                // Prepend the resource href when the link uses a fragment-only reference.
+                const ref = linkBare === '' ? bare + link.href : link.href;
+                const child: TimelineItem = {
+                    title: link.title,
+                    references: [ref],
+                };
                 linkMap.set(child, link);
                 result.push(child);
             }
@@ -250,7 +385,9 @@ export class Timeline {
         const fragments: Link[] = [];
 
         for (const link of tocLinks) {
-            if (Timeline.bareHref(link.href) === bare && link.title) {
+            const linkBare = Timeline.bareHref(link.href);
+            const isFragmentOnly = link.href.startsWith('#');
+            if ((linkBare === bare || (isFragmentOnly && linkBare === '')) && link.title) {
                 if (Timeline.isStartOfResource(link.href)) {
                     atStart.push(link);
                 } else {
@@ -282,6 +419,120 @@ export class Timeline {
         return match !== null && isNptStartOfResource(match[1]);
     }
 
+    // -------------------------------------------------------------------------
+    // Contextualized TOC
+    // -------------------------------------------------------------------------
+
+    private get linkToItem(): Map<Link, TimelineItem> {
+        if (!this._linkToItem) {
+            this._linkToItem = new Map();
+            for (const [item, link] of this.linkMap) this._linkToItem.set(link, item);
+        }
+        return this._linkToItem;
+    }
+
+    private buildTocEntries(links: Link[], maxDepth: number | undefined, currentDepth: number): ContextualizedTocEntry[] {
+        if (maxDepth !== undefined && currentDepth > maxDepth) return [];
+        return links.map(link => {
+            const item = this.linkToItem.get(link) ?? this.resourceStartItem(link.href);
+            const kids = link.children?.items?.length
+                ? this.buildTocEntries(link.children.items, maxDepth, currentDepth + 1)
+                : [];
+            return { ...this.entryFor(link, item), children: kids.length > 0 ? kids : undefined };
+        });
+    }
+
+    /** All toc Links flattened, respecting the same depth limit as `buildTocEntries`. */
+    private tocLinksFlat(links: Link[], maxDepth: number | undefined, currentDepth: number): Link[] {
+        if (maxDepth !== undefined && currentDepth > maxDepth) return [];
+        const result: Link[] = [];
+        for (const link of links) {
+            result.push(link);
+            if (link.children?.items?.length) {
+                result.push(...this.tocLinksFlat(link.children.items, maxDepth, currentDepth + 1));
+            }
+        }
+        return result;
+    }
+
+    private entryFor(link: Link, item: TimelineItem | undefined): ContextualizedTocEntry {
+        const isAudio = this._conformsTo.includes(Profile.AUDIOBOOK);
+        return {
+            link,
+            position: !isAudio && item?.position !== undefined ? String(item.position) : undefined,
+            timestamp: isAudio && item?.position !== undefined ? formatNptTime(item.position) : undefined,
+        };
+    }
+
+    private resourceStartItem(href: string): TimelineItem | undefined {
+        const bare = Timeline.bareHref(href);
+        return this._allItems.find(i => this.itemMatchesHref(i, bare));
+    }
+
+    private findTocEntryByLink(entries: ContextualizedTocEntry[], link: Link): ContextualizedTocEntry | undefined {
+        for (const entry of entries) {
+            if (entry.link === link) return entry;
+            if (entry.children) {
+                const found = this.findTocEntryByLink(entry.children, link);
+                if (found) return found;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Tier-2 fallback for `tocEntryFor`: among the toc entries that reference
+     * `href`'s own resource (e.g. chapter markers within one audio file),
+     * return the nearest one at or before `current`'s position/scroll.
+     */
+    private nearestTocEntryForResource(href: string, current: TimelineItem): ContextualizedTocEntry | undefined {
+        const bare = Timeline.bareHref(href);
+        // Re-walk with raw items (not the display-formatted TocEntry tree) so we can compare
+        // current.position/current.scroll directly against each candidate's source TimelineItem.
+        const candidates = this.tocLinksFlat(this.tocLinks, this._tocDepth, 1)
+            .filter(link => Timeline.bareHref(link.href) === bare)
+            .map(link => ({ link, item: this.linkToItem.get(link) ?? this.resourceStartItem(link.href) }));
+        if (candidates.length === 0) return undefined;
+
+        const isAudio = this._conformsTo.includes(Profile.AUDIOBOOK);
+        const currentValue = isAudio ? (current.position ?? 0) : (current.scroll ?? 0);
+        let best: { link: Link; item: TimelineItem | undefined } | undefined;
+        let bestValue = -Infinity;
+        for (const c of candidates) {
+            const v = isAudio ? (c.item?.position ?? 0) : (c.item?.scroll ?? 0);
+            if (v <= currentValue && v > bestValue) { bestValue = v; best = c; }
+        }
+        const chosen = best ?? candidates[0];
+        return this.findTocEntryByLink(this.contextualizedToc, chosen.link);
+    }
+
+    /**
+     * Tier-3 fallback for `tocEntryFor`: when no toc entry references
+     * `href`'s resource at all, walk backward through the reading order and
+     * return the nearest preceding resource's toc entry.
+     */
+    private previousResolvedTocEntry(link: Link): ContextualizedTocEntry | undefined {
+        const index = this._allItems.findIndex(item => this.linkFor(item) === link);
+        if (index === -1) return undefined;
+
+        for (let i = index - 1; i >= 0; i--) {
+            const precedingLink = this.linkFor(this._allItems[i]);
+            if (!precedingLink) continue;
+            const precedingBare = Timeline.bareHref(precedingLink.href);
+            const { atStart, fragments } = Timeline.collectTocCandidates(this.tocLinks, precedingBare, this._tocDepth, 1);
+            // Exclude fragment-only entries (bareHref "") — collectTocCandidates
+            // treats them as matching any bare href for single-track audio, but
+            // here they must belong to this specific preceding resource.
+            const ownAtStart = atStart.filter(l => Timeline.bareHref(l.href) === precedingBare);
+            const ownFragments = fragments.filter(l => Timeline.bareHref(l.href) === precedingBare);
+            const chosen = ownAtStart[0] ?? (ownFragments.length > 0 ? ownFragments[ownFragments.length - 1] : undefined);
+            if (!chosen) continue;
+            const entry = this.findTocEntryByLink(this.contextualizedToc, chosen);
+            if (entry) return entry;
+        }
+        return undefined;
+    }
+
     // -------------------------------------------------------------------------
     // Shared utilities
     // -------------------------------------------------------------------------
@@ -319,7 +570,8 @@ export class Timeline {
             const hashIndex = ref.indexOf("#");
             const refHref = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
             const refFragment = hashIndex >= 0 ? ref.slice(hashIndex + 1) : undefined;
-            const effectiveHref = refHref || this.bareHrefFromItem(item);
+            // Fragment-only reference (e.g. "#t=60") has no resource of its own — use the queried href.
+            const effectiveHref = refHref || href;
             if (effectiveHref !== href) continue;
             if (!refFragment) return undefined;
             const match = refFragment.match(/(?:^|&)t=([^&]+)/);
@@ -328,17 +580,12 @@ export class Timeline {
         return undefined;
     }
 
-    private bareHrefFromItem(item: TimelineItem): string {
-        return (item.references[0] ?? "").split("#")[0];
-    }
-
-    private timeFromItem(item: TimelineItem): number | undefined {
-        const ref = item.references[0];
-        if (!ref) return undefined;
-        const fragment = ref.split("#")[1];
-        if (!fragment) return undefined;
-        const match = fragment.match(/(?:^|&)t=([^&]+)/);
-        return match ? parseNptTime(match[1]) : undefined;
+    private itemMatchesHref(item: TimelineItem, href: string): boolean {
+        return item.references.some(ref => {
+            const bare = ref.split("#")[0];
+            // Fragment-only reference (single-track audio) matches the current resource.
+            return bare === href || bare === '';
+        });
     }
 
     private ancestorPath(items: TimelineItem[], target: TimelineItem): TimelineItem[] | null {
@@ -352,6 +599,10 @@ export class Timeline {
         return null;
     }
 
+    private itemScrollPosition(item: TimelineItem): number | undefined {
+        return item.scroll;
+    }
+
     private static bareHref(href: string): string {
         return href.split("#")[0];
     }