@readium/shared 2.3.0 → 2.3.2

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Readium Foundation
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/publication/services/timeline/Timeline.js

@@ -1 +1 @@
-import{getTime as g,getHtmlId as k}from"../../html/Locations.js";import{Profile as u}from"../../Profiles.js";import{isNptStartOfResource as v,formatNptTime as I,parseNptTime as T}from"../../../util/npt.js";class l{constructor(e,t,i=[],s=[],n=void 0){this._trimmedLinkMap=new Map,this._allItems=e,this.linkMap=t,this._conformsTo=i,this.tocLinks=s,this._tocDepth=n}static build(e,t={}){const i=e.toc?.items??[],s=e.readingOrder.items,{depth:n}=t,o=e.metadata?.conformsTo??[],r=new Map,c=[];for(let h=0;h<s.length;h++){const f=s[h],a=l.bareHref(f.href),p=f.title??l.findTitleInToc(i,a,n),d=l.collectChildrenFromToc(i,a,n,1,r),m={title:p,references:[f.href],children:d.length>0?d:void 0};r.set(m,f),c.push(m)}return new l(c,r,o,i,n)}augment(e){for(const t of this.flatAll){const i=this.linkFor(t);if(!i)continue;const s=e(t,i);s.position!==void 0&&(t.position=s.position),s.scroll!==void 0&&(t.scroll=s.scroll),s.role!==void 0&&(t.role=s.role)}}get depth(){return this._depth}set depth(e){this._depth!==e&&(this._depth=e,this._tocDepth=e,this._items=void 0,this._flat=void 0,this._toc=void 0)}get items(){return this._items||(this._depth!==void 0?(this._trimmedLinkMap=new Map,this._items=l.trimToDepth(this._allItems,this._depth,this.linkMap,this._trimmedLinkMap)):this._items=this._allItems),this._items}locate(e){const t=e.href.split("#")[0],i=g(e.locations),s=k(e.locations),n=e.locations.progression;if(i!==void 0){let o=-1/0,r;for(const c of this.flat){if(!this.itemMatchesHref(c,t))continue;const h=this.itemStartTime(c,t);h!==void 0&&h<=i&&h>o&&(o=h,r=c)}if(r)return r}if(s){const o=this.flat.find(r=>this.itemMatchesHref(r,t)?r.references.some(c=>c.split("#")[1]===s):!1);if(o)return o}if(n!==void 0){let o=-1/0,r;for(const h of this.flat){if(!this.itemMatchesHref(h,t))continue;const f=this.itemScrollPosition(h);f!==void 0&&f<=n&&f>o&&(o=f,r=h)}if(r)return r;const c=this.items.find(h=>this.itemMatchesHref(h,t));if(c?.children?.length&&!c.children.some(h=>h.scroll!==void 0)){const h=Math.min(Math.floor(n*c.children.length),c.children.length-1);return c.children[h]}}return this.flat.find(o=>this.itemMatchesHref(o,t))}adjacentTo(e){const t=this.flat.indexOf(e);return{previous:t>0?this.flat[t-1]:void 0,next:t>=0&&t<this.flat.length-1?this.flat[t+1]:void 0}}segmentsForHref(e){const t=e.split("#")[0],i=this.items.find(s=>this.itemMatchesHref(s,t));return i?i.children?.length?i.children:[i]:[]}ancestors(e){return this.ancestorPath(this.items,e)??[]}linkFor(e){return this.linkMap.get(e)??this._trimmedLinkMap.get(e)}get contextualizedToc(){return this._toc||(this._toc=this.tocLinks.length>0?this.buildTocEntries(this.tocLinks,this._tocDepth,1):this._allItems.map(e=>this.entryFor(this.linkFor(e),e))),this._toc}tocEntryFor(e){const t=this.linkFor(e);if(!t)return;const i=this.findTocEntryByLink(this.contextualizedToc,t);return i||this.nearestTocEntryForResource(t.href,e)}get flat(){return this._flat||(this._flat=this.flattenItems(this.items)),this._flat}get flatAll(){return this.flattenItems(this._allItems)}static findTitleInToc(e,t,i){const{atStart:s,fragments:n}=l.collectTocCandidates(e,t,i,1);if(s.length>0)return s[0].title;if(n.length===1)return n[0].title}static collectChildrenFromToc(e,t,i,s,n){if(i!==void 0&&s>i)return[];const o=[];for(const r of e){const c=l.bareHref(r.href);if((c===t||c==="")&&r.title&&!l.isStartOfResource(r.href)){const f=c===""?t+r.href:r.href,a={title:r.title,references:[f]};n.set(a,r),o.push(a)}r.children?.items?.length&&o.push(...l.collectChildrenFromToc(r.children.items,t,i,s+1,n))}return o}static collectTocCandidates(e,t,i,s){if(i!==void 0&&s>i)return{atStart:[],fragments:[]};const n=[],o=[];for(const r of e){const c=l.bareHref(r.href);if((c===t||c==="")&&r.title&&(l.isStartOfResource(r.href)?n.push(r):o.push(r)),r.children?.items?.length){const h=l.collectTocCandidates(r.children.items,t,i,s+1);n.push(...h.atStart),o.push(...h.fragments)}}return{atStart:n,fragments:o}}static isStartOfResource(e){const t=e.split("#")[1];if(!t)return!0;const i=t.match(/(?:^|&)t=([^&]+)/);return i!==null&&v(i[1])}get linkToItem(){if(!this._linkToItem){this._linkToItem=new Map;for(const[e,t]of this.linkMap)this._linkToItem.set(t,e)}return this._linkToItem}buildTocEntries(e,t,i){return t!==void 0&&i>t?[]:e.map(s=>{const n=this.linkToItem.get(s)??this.resourceStartItem(s.href),o=s.children?.items?.length?this.buildTocEntries(s.children.items,t,i+1):[];return{...this.entryFor(s,n),children:o.length>0?o:void 0}})}tocLinksFlat(e,t,i){if(t!==void 0&&i>t)return[];const s=[];for(const n of e)s.push(n),n.children?.items?.length&&s.push(...this.tocLinksFlat(n.children.items,t,i+1));return s}entryFor(e,t){const i=this._conformsTo.includes(u.AUDIOBOOK);return{link:e,position:!i&&t?.position!==void 0?String(t.position):void 0,timestamp:i&&t?.position!==void 0?I(t.position):void 0}}resourceStartItem(e){const t=l.bareHref(e);return this._allItems.find(i=>this.itemMatchesHref(i,t))}findTocEntryByLink(e,t){for(const i of e){if(i.link===t)return i;if(i.children){const s=this.findTocEntryByLink(i.children,t);if(s)return s}}}nearestTocEntryForResource(e,t){const i=l.bareHref(e),s=this.tocLinksFlat(this.tocLinks,this._tocDepth,1).filter(f=>l.bareHref(f.href)===i).map(f=>({link:f,item:this.linkToItem.get(f)??this.resourceStartItem(f.href)}));if(s.length===0)return;const n=this._conformsTo.includes(u.AUDIOBOOK),o=n?t.position??0:t.scroll??0;let r,c=-1/0;for(const f of s){const a=n?f.item?.position??0:f.item?.scroll??0;a<=o&&a>c&&(c=a,r=f)}const h=r??s[0];return this.findTocEntryByLink(this.contextualizedToc,h.link)}static trimToDepth(e,t,i,s){return e.map(n=>{const o={...n,children:t>1&&n.children?.length?l.trimToDepth(n.children,t-1,i,s):void 0},r=i.get(n);return r&&s.set(o,r),o})}flattenItems(e){const t=[];for(const i of e)t.push(i),i.children&&t.push(...this.flattenItems(i.children));return t}itemStartTime(e,t){for(const i of e.references){const s=i.indexOf("#"),n=s>=0?i.slice(0,s):i,o=s>=0?i.slice(s+1):void 0;if((n||t)!==t)continue;if(!o)return;const c=o.match(/(?:^|&)t=([^&]+)/);return c?T(c[1]):void 0}}itemMatchesHref(e,t){return e.references.some(i=>{const s=i.split("#")[0];return s===t||s===""})}ancestorPath(e,t){for(const i of e){if(i===t)return[];if(i.children){const s=this.ancestorPath(i.children,t);if(s!==null)return[i,...s]}}return null}itemScrollPosition(e){return e.scroll}static bareHref(e){return e.split("#")[0]}}export{l as Timeline};
+import{getTime as g,getHtmlId as v}from"../../html/Locations.js";import{Profile as p}from"../../Profiles.js";import{isNptStartOfResource as k,formatNptTime as I,parseNptTime as T}from"../../../util/npt.js";class l{constructor(i,t,e=[],s=[],n=void 0){this._trimmedLinkMap=new Map,this._allItems=i,this.linkMap=t,this._conformsTo=e,this.tocLinks=s,this._tocDepth=n}static build(i,t={}){const e=i.toc?.items??[],s=i.readingOrder.items,{depth:n}=t,o=i.metadata?.conformsTo??[],r=new Map,c=[];for(let h=0;h<s.length;h++){const f=s[h],a=l.bareHref(f.href),d=f.title??l.findTitleInToc(e,a,n),u=l.collectChildrenFromToc(e,a,n,1,r),m={title:d,references:[f.href],children:u.length>0?u:void 0};r.set(m,f),c.push(m)}return new l(c,r,o,e,n)}augment(i){for(const t of this.flatAll){const e=this.linkFor(t);if(!e)continue;const s=i(t,e);s.position!==void 0&&(t.position=s.position),s.scroll!==void 0&&(t.scroll=s.scroll),s.role!==void 0&&(t.role=s.role)}}get depth(){return this._depth}set depth(i){this._depth!==i&&(this._depth=i,this._tocDepth=i,this._items=void 0,this._flat=void 0,this._toc=void 0)}get items(){return this._items||(this._depth!==void 0?(this._trimmedLinkMap=new Map,this._items=l.trimToDepth(this._allItems,this._depth,this.linkMap,this._trimmedLinkMap)):this._items=this._allItems),this._items}locate(i){const t=i.href.split("#")[0],e=g(i.locations),s=v(i.locations),n=i.locations.progression;if(e!==void 0){let o=-1/0,r;for(const c of this.flat){if(!this.itemMatchesHref(c,t))continue;const h=this.itemStartTime(c,t);h!==void 0&&h<=e&&h>o&&(o=h,r=c)}if(r)return r}if(s){const o=this.flat.find(r=>this.itemMatchesHref(r,t)?r.references.some(c=>c.split("#")[1]===s):!1);if(o)return o}if(n!==void 0){let o=-1/0,r;for(const h of this.flat){if(!this.itemMatchesHref(h,t))continue;const f=this.itemScrollPosition(h);f!==void 0&&f<=n&&f>o&&(o=f,r=h)}if(r)return r;const c=this.items.find(h=>this.itemMatchesHref(h,t));if(c?.children?.length&&!c.children.some(h=>h.scroll!==void 0)){const h=Math.min(Math.floor(n*c.children.length),c.children.length-1);return c.children[h]}}return this.flat.find(o=>this.itemMatchesHref(o,t))}adjacentTo(i){const t=this.flat.indexOf(i);return{previous:t>0?this.flat[t-1]:void 0,next:t>=0&&t<this.flat.length-1?this.flat[t+1]:void 0}}segmentsForHref(i){const t=i.split("#")[0],e=this.items.find(s=>this.itemMatchesHref(s,t));return e?e.children?.length?e.children:[e]:[]}ancestors(i){return this.ancestorPath(this.items,i)??[]}linkFor(i){return this.linkMap.get(i)??this._trimmedLinkMap.get(i)}get contextualizedToc(){return this._toc||(this._toc=this.tocLinks.length>0?this.buildTocEntries(this.tocLinks,this._tocDepth,1):this._allItems.map(i=>this.entryFor(this.linkFor(i),i))),this._toc}tocEntryFor(i){const t=this.linkFor(i);if(!t)return;const e=this.findTocEntryByLink(this.contextualizedToc,t);if(e)return e;const s=this.nearestTocEntryForResource(t.href,i);return s||this.previousResolvedTocEntry(t)}get flat(){return this._flat||(this._flat=this.flattenItems(this.items)),this._flat}get flatAll(){return this.flattenItems(this._allItems)}static findTitleInToc(i,t,e){const{atStart:s,fragments:n}=l.collectTocCandidates(i,t,e,1);if(s.length>0)return s[0].title;if(n.length===1)return n[0].title}static collectChildrenFromToc(i,t,e,s,n){if(e!==void 0&&s>e)return[];const o=[];for(const r of i){const c=l.bareHref(r.href),h=r.href.startsWith("#");if((c===t||h&&c==="")&&r.title&&!l.isStartOfResource(r.href)){const a=c===""?t+r.href:r.href,d={title:r.title,references:[a]};n.set(d,r),o.push(d)}r.children?.items?.length&&o.push(...l.collectChildrenFromToc(r.children.items,t,e,s+1,n))}return o}static collectTocCandidates(i,t,e,s){if(e!==void 0&&s>e)return{atStart:[],fragments:[]};const n=[],o=[];for(const r of i){const c=l.bareHref(r.href),h=r.href.startsWith("#");if((c===t||h&&c==="")&&r.title&&(l.isStartOfResource(r.href)?n.push(r):o.push(r)),r.children?.items?.length){const f=l.collectTocCandidates(r.children.items,t,e,s+1);n.push(...f.atStart),o.push(...f.fragments)}}return{atStart:n,fragments:o}}static isStartOfResource(i){const t=i.split("#")[1];if(!t)return!0;const e=t.match(/(?:^|&)t=([^&]+)/);return e!==null&&k(e[1])}get linkToItem(){if(!this._linkToItem){this._linkToItem=new Map;for(const[i,t]of this.linkMap)this._linkToItem.set(t,i)}return this._linkToItem}buildTocEntries(i,t,e){return t!==void 0&&e>t?[]:i.map(s=>{const n=this.linkToItem.get(s)??this.resourceStartItem(s.href),o=s.children?.items?.length?this.buildTocEntries(s.children.items,t,e+1):[];return{...this.entryFor(s,n),children:o.length>0?o:void 0}})}tocLinksFlat(i,t,e){if(t!==void 0&&e>t)return[];const s=[];for(const n of i)s.push(n),n.children?.items?.length&&s.push(...this.tocLinksFlat(n.children.items,t,e+1));return s}entryFor(i,t){const e=this._conformsTo.includes(p.AUDIOBOOK);return{link:i,position:!e&&t?.position!==void 0?String(t.position):void 0,timestamp:e&&t?.position!==void 0?I(t.position):void 0}}resourceStartItem(i){const t=l.bareHref(i);return this._allItems.find(e=>this.itemMatchesHref(e,t))}findTocEntryByLink(i,t){for(const e of i){if(e.link===t)return e;if(e.children){const s=this.findTocEntryByLink(e.children,t);if(s)return s}}}nearestTocEntryForResource(i,t){const e=l.bareHref(i),s=this.tocLinksFlat(this.tocLinks,this._tocDepth,1).filter(f=>l.bareHref(f.href)===e).map(f=>({link:f,item:this.linkToItem.get(f)??this.resourceStartItem(f.href)}));if(s.length===0)return;const n=this._conformsTo.includes(p.AUDIOBOOK),o=n?t.position??0:t.scroll??0;let r,c=-1/0;for(const f of s){const a=n?f.item?.position??0:f.item?.scroll??0;a<=o&&a>c&&(c=a,r=f)}const h=r??s[0];return this.findTocEntryByLink(this.contextualizedToc,h.link)}previousResolvedTocEntry(i){const t=this._allItems.findIndex(e=>this.linkFor(e)===i);if(t!==-1)for(let e=t-1;e>=0;e--){const s=this.linkFor(this._allItems[e]);if(!s)continue;const n=l.bareHref(s.href),{atStart:o,fragments:r}=l.collectTocCandidates(this.tocLinks,n,this._tocDepth,1),c=o.filter(d=>l.bareHref(d.href)===n),h=r.filter(d=>l.bareHref(d.href)===n),f=c[0]??(h.length>0?h[h.length-1]:void 0);if(!f)continue;const a=this.findTocEntryByLink(this.contextualizedToc,f);if(a)return a}}static trimToDepth(i,t,e,s){return i.map(n=>{const o={...n,children:t>1&&n.children?.length?l.trimToDepth(n.children,t-1,e,s):void 0},r=e.get(n);return r&&s.set(o,r),o})}flattenItems(i){const t=[];for(const e of i)t.push(e),e.children&&t.push(...this.flattenItems(e.children));return t}itemStartTime(i,t){for(const e of i.references){const s=e.indexOf("#"),n=s>=0?e.slice(0,s):e,o=s>=0?e.slice(s+1):void 0;if((n||t)!==t)continue;if(!o)return;const c=o.match(/(?:^|&)t=([^&]+)/);return c?T(c[1]):void 0}}itemMatchesHref(i,t){return i.references.some(e=>{const s=e.split("#")[0];return s===t||s===""})}ancestorPath(i,t){for(const e of i){if(e===t)return[];if(e.children){const s=this.ancestorPath(e.children,t);if(s!==null)return[e,...s]}}return null}itemScrollPosition(i){return i.scroll}static bareHref(i){return i.split("#")[0]}}export{l as Timeline};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/shared",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "type": "module",
   "description": "Shared models to be used across other Readium projects and implementations in Typescript",
   "author": "readium",
@@ -63,14 +63,6 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "dev": "vite",
-    "clean": "rimraf types dist",
-    "build": "pnpm clean && tsc && vite build",
-    "test": "jest",
-    "check-locales": "node scripts/check-locales.mjs",
-    "update-locales": "node scripts/update-locales.mjs && node scripts/check-locales.mjs"
-  },
   "devDependencies": {
     "@babel/core": "^7.28.6",
     "@babel/preset-env": "^7.28.6",
@@ -84,5 +76,13 @@
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.1"
+  },
+  "scripts": {
+    "dev": "vite",
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build",
+    "test": "jest",
+    "check-locales": "node scripts/check-locales.mjs",
+    "update-locales": "node scripts/update-locales.mjs && node scripts/check-locales.mjs"
   }
-}
+}

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

@@ -267,10 +267,12 @@ export class Timeline {
     }
 
     /**
-     * Maps a `TimelineItem` (typically from `locate()`) to its `ContextualizedTocEntry`:
-     * a direct match first, falling back to the nearest preceding toc entry
-     * for that resource when there's no exact match (e.g. a mid-resource
-     * audio position between chapter markers).
+     * 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);
@@ -279,7 +281,10 @@ export class Timeline {
         const direct = this.findTocEntryByLink(this.contextualizedToc, link);
         if (direct) return direct;
 
-        return this.nearestTocEntryForResource(link.href, current);
+        const nearest = this.nearestTocEntryForResource(link.href, current);
+        if (nearest) return nearest;
+
+        return this.previousResolvedTocEntry(link);
     }
 
     private get flat(): TimelineItem[] {
@@ -334,8 +339,11 @@ export class Timeline {
         for (const link of tocLinks) {
             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.
-            const matchesBare = linkBare === bare || linkBare === '';
+            // 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;
@@ -377,7 +385,8 @@ export class Timeline {
 
         for (const link of tocLinks) {
             const linkBare = Timeline.bareHref(link.href);
-            if ((linkBare === bare || linkBare === '') && link.title) {
+            const isFragmentOnly = link.href.startsWith('#');
+            if ((linkBare === bare || (isFragmentOnly && linkBare === '')) && link.title) {
                 if (Timeline.isStartOfResource(link.href)) {
                     atStart.push(link);
                 } else {
@@ -470,6 +479,11 @@ export class Timeline {
         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
@@ -491,6 +505,33 @@ export class Timeline {
         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
     // -------------------------------------------------------------------------

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

@@ -103,10 +103,12 @@ export declare class Timeline {
      */
     get contextualizedToc(): ContextualizedTocEntry[];
     /**
-     * Maps a `TimelineItem` (typically from `locate()`) to its `ContextualizedTocEntry`:
-     * a direct match first, falling back to the nearest preceding toc entry
-     * for that resource when there's no exact match (e.g. a mid-resource
-     * audio position between chapter markers).
+     * 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;
     private get flat();
@@ -146,7 +148,18 @@ export declare class Timeline {
     private entryFor;
     private resourceStartItem;
     private findTocEntryByLink;
+    /**
+     * 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;
+    /**
+     * 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;
     private static trimToDepth;
     private flattenItems;
     private itemStartTime;