@readium/shared 2.2.3 → 2.3.1

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,26 +169,63 @@ 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 } {
@@ -133,35 +238,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 +251,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 +337,17 @@ 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.
+            const matchesBare = linkBare === bare || 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 +381,8 @@ 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);
+            if ((linkBare === bare || linkBare === '') && link.title) {
                 if (Timeline.isStartOfResource(link.href)) {
                     atStart.push(link);
                 } else {
@@ -282,6 +414,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 +565,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 +575,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 +594,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];
     }

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

@@ -6,8 +6,8 @@
  * show previous/next as chapter titles, group search results by chapter, etc.
  */
 export interface TimelineItem {
-    /** Display title of this entry. */
-    title: string;
+    /** Display title of this entry, when one could be derived. */
+    title?: string;
     /**
      * References as hrefs with optional fragments.
      * e.g. ["track1.mp3#t=60"] for audio, ["chapter1.html"] for EPUB, ["#page=6"] for PDF.
@@ -15,7 +15,7 @@ export interface TimelineItem {
     references: string[];
     /** Structural roles of this entry, e.g. ["chapter"], ["part"]. */
     role?: string[];
-    /** Position number in the reading order context. */
+    /** Raw position: book-global seconds for audio, a Positions List position for EPUB, a page number for PDF. */
     position?: number;
     /** Scroll progression within the resource (0 to 1), for entries that start mid-way in a resource. */
     scroll?: number;

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

@@ -0,0 +1,31 @@
+import { parseNptTime } from "../../../util/npt.ts";
+import { Timeline, PublicationLike } from "./Timeline.ts";
+
+export function buildAudioTimeline(pub: PublicationLike, opts?: { depth?: number }): Timeline {
+    const t = Timeline.build(pub, opts);
+    const ro = pub.readingOrder.items;
+    const canLabel = ro.length <= 1 || ro.every(l => l.duration !== undefined);
+    if (!canLabel) return t;
+
+    let offset = 0;
+    const offsets = new Map(ro.map(l => {
+        const o = offset;
+        offset += l.duration ?? 0;
+        return [l.href, o];
+    }));
+
+    t.augment((_item, link) => {
+        const href = link.href;
+        const hashIndex = href.indexOf('#');
+        const bare = hashIndex >= 0 ? href.slice(0, hashIndex) : href;
+        const fragment = hashIndex >= 0 ? href.slice(hashIndex + 1) : undefined;
+        const trackOffset = offsets.get(bare) ?? 0;
+        const tMatch = fragment?.match(/(?:^|&)t=([^&]+)/);
+        const seconds = tMatch ? parseNptTime(tMatch[1]) : undefined;
+        return {
+            position: trackOffset + (seconds ?? 0),
+        };
+    });
+
+    return t;
+}

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

@@ -0,0 +1,5 @@
+import { Timeline, PublicationLike } from "./Timeline.ts";
+
+export function buildHtmlTimeline(pub: PublicationLike, opts?: { depth?: number }): Timeline {
+    return Timeline.build(pub, opts);
+}

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

@@ -1,2 +1,14 @@
+import { Profile } from "../../Profiles.ts";
+import { PublicationLike, Timeline } from "./Timeline.ts";
+import { buildAudioTimeline } from "./audio.ts";
+import { buildHtmlTimeline } from "./html.ts";
+
 export * from './Timeline.ts';
 export * from './TimelineItem.ts';
+export { buildHtmlTimeline } from './html.ts';
+export { buildAudioTimeline } from './audio.ts';
+
+export function buildTimeline(pub: PublicationLike, options?: { depth?: number }): Timeline {
+    const isAudio = pub.metadata?.conformsTo?.includes(Profile.AUDIOBOOK) ?? false;
+    return isAudio ? buildAudioTimeline(pub, options) : buildHtmlTimeline(pub, options);
+}

package/src/util/npt.ts

@@ -49,3 +49,22 @@ export function isNptStartOfResource(raw: string): boolean {
     const t = parseNptTime(raw);
     return t !== undefined && t === 0;
 }
+
+/**
+ * Formats a duration in seconds as a human-readable string suitable for
+ * display in a Table of Contents or progress indicator.
+ *
+ * Outputs "H:MM:SS" when hours > 0, otherwise "M:SS".
+ * Minutes and seconds are always zero-padded to two digits.
+ *
+ * Examples: 0 → "0:00", 90 → "1:30", 3661 → "1:01:01"
+ */
+export function formatNptTime(seconds: number): string {
+    const totalSeconds = Math.floor(seconds);
+    const h = Math.floor(totalSeconds / 3600);
+    const m = Math.floor((totalSeconds % 3600) / 60);
+    const s = totalSeconds % 60;
+    const mm = String(m).padStart(2, "0");
+    const ss = String(s).padStart(2, "0");
+    return h > 0 ? `${h}:${mm}:${ss}` : `${m}:${ss}`;
+}

package/types/src/publication/encryption/Properties.d.ts

@@ -1,10 +1,3 @@
+import { Properties } from '../Properties.ts';
 import { Encryption } from './Encryption.ts';
-declare module '../Properties' {
-    interface Properties {
-        /**
-         * Indicates that a resource is encrypted/obfuscated and provides relevant information for
-         * decryption.
-         */
-        encryption: Encryption | undefined;
-    }
-}
+export declare function getEncryption(properties: Properties): Encryption | undefined;

package/types/src/publication/epub/Metadata.d.ts

@@ -1,6 +1,3 @@
-import { MediaOverlay } from "./MediaOverlay.ts";
-declare module '../Metadata' {
-    interface Metadata {
-        getMediaOverlay(): MediaOverlay | undefined;
-    }
-}
+import { Metadata } from '../Metadata.ts';
+import { MediaOverlay } from './MediaOverlay.ts';
+export declare function getMediaOverlay(metadata: Metadata): MediaOverlay | undefined;