@readium/shared 2.3.1 → 2.4.0-alpha.1

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

@@ -1,31 +1,11 @@
 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";
 
-export interface PublicationLike {
+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[];
 }
 
 /**
@@ -37,61 +17,32 @@ export interface ContextualizedTocEntry {
  *   2. Populate flat children — all TOC fragment entries that reference the
  *      resource, collected depth-first in TOC declaration order.
  *
- * `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.
+ * 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.
  *
- * 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.
+ * 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.
  */
 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>,
-        conformsTo: readonly Profile[] = [],
-        tocLinks: Link[] = [],
-        tocDepth: number | undefined = undefined,
-    ) {
+    constructor(items: TimelineItem[], linkMap: Map<TimelineItem, Link>) {
         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[] = [];
 
@@ -101,7 +52,8 @@ export class Timeline {
 
             const title =
                 ro.title ??
-                Timeline.findTitleInToc(tocLinks, bare, depth);
+                Timeline.findTitleInToc(tocLinks, bare, depth) ??
+                `Resource ${i + 1}`;
 
             const tocChildren = Timeline.collectChildrenFromToc(tocLinks, bare, depth, 1, linkMap);
 
@@ -115,25 +67,7 @@ export class Timeline {
             items.push(item);
         }
 
-        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;
-        }
+        return new Timeline(items, linkMap);
     }
 
     /**
@@ -148,10 +82,8 @@ 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. */
@@ -169,63 +101,26 @@ export class Timeline {
 
     locate(locator: Locator): TimelineItem | undefined {
         const href = locator.href.split("#")[0];
-        const time = getTime(locator.locations);
-        const htmlId = getHtmlId(locator.locations);
-        const progression = locator.locations.progression;
+        const time = locator.locations?.time();
+
+        let match: TimelineItem | undefined;
 
-        // 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;
         }
 
-        // 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];
-            }
+        if (!match) {
+            match = this.flat.find(item => this.bareHrefFromItem(item) === href);
         }
 
-        // Fallback: bare href match.
-        return this.flat.find(item => this.itemMatchesHref(item, href));
+        return match;
     }
 
     adjacentTo(item: TimelineItem): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
@@ -238,11 +133,35 @@ export class Timeline {
 
     segmentsForHref(href: string): TimelineItem[] {
         const bare = href.split("#")[0];
-        const item = this.items.find(i => this.itemMatchesHref(i, bare));
+        const item = this.items.find(i => this.bareHrefFromItem(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) ?? [];
     }
@@ -251,52 +170,11 @@ 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
     // -------------------------------------------------------------------------
@@ -337,17 +215,8 @@ export class Timeline {
         const result: TimelineItem[] = [];
 
         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 === '';
-            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],
-                };
+            if (Timeline.bareHref(link.href) === bare && link.title && !Timeline.isStartOfResource(link.href)) {
+                const child: TimelineItem = { title: link.title, references: [link.href] };
                 linkMap.set(child, link);
                 result.push(child);
             }
@@ -381,8 +250,7 @@ export class Timeline {
         const fragments: Link[] = [];
 
         for (const link of tocLinks) {
-            const linkBare = Timeline.bareHref(link.href);
-            if ((linkBare === bare || linkBare === '') && link.title) {
+            if (Timeline.bareHref(link.href) === bare && link.title) {
                 if (Timeline.isStartOfResource(link.href)) {
                     atStart.push(link);
                 } else {
@@ -414,120 +282,6 @@ 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
     // -------------------------------------------------------------------------
@@ -565,8 +319,7 @@ 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;
-            // Fragment-only reference (e.g. "#t=60") has no resource of its own — use the queried href.
-            const effectiveHref = refHref || href;
+            const effectiveHref = refHref || this.bareHrefFromItem(item);
             if (effectiveHref !== href) continue;
             if (!refFragment) return undefined;
             const match = refFragment.match(/(?:^|&)t=([^&]+)/);
@@ -575,12 +328,17 @@ export class Timeline {
         return 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 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 ancestorPath(items: TimelineItem[], target: TimelineItem): TimelineItem[] | null {
@@ -594,10 +352,6 @@ 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, when one could be derived. */
-    title?: string;
+    /** Display title of this entry. */
+    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[];
-    /** Raw position: book-global seconds for audio, a Positions List position for EPUB, a page number for PDF. */
+    /** Position number in the reading order context. */
     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/index.ts

@@ -1,14 +1,2 @@
-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,22 +49,3 @@ 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/fetcher/HttpFetcher.d.ts

@@ -1,6 +1,6 @@
 import { Link } from '../publication/Link.ts';
 import { Fetcher } from './Fetcher.ts';
-import { NumberRange, Resource } from './Resource.ts';
+import { NumberRange, Resource, ResourceReadOptions } from './Resource.ts';
 export type FetchImplementation = (input: RequestInfo | URL, init?: RequestInit | undefined) => Promise<Response>;
 export declare class HttpFetcher implements Fetcher {
     private readonly baseUrl?;
@@ -20,9 +20,9 @@ export declare class HttpResource implements Resource {
     private headResponse;
     close(): void;
     link(): Promise<Link>;
-    read(range?: NumberRange): Promise<Uint8Array | undefined>;
+    read(range?: NumberRange, options?: ResourceReadOptions): Promise<Uint8Array | undefined>;
     length(): Promise<number>;
     readAsJSON(): Promise<unknown>;
     readAsString(): Promise<string>;
-    readAsXML(): Promise<XMLDocument>;
+    readAsXML(): Promise<Document>;
 }

package/types/src/fetcher/Resource.d.ts

@@ -4,12 +4,16 @@ export declare class NumberRange {
     readonly endInclusive: number;
     constructor(start: number, endInclusive: number);
 }
+export interface ResourceReadOptions {
+    /** Aborts the underlying request, e.g. when a prefetched resource is no longer needed */
+    signal?: AbortSignal;
+}
 export declare abstract class Resource {
     abstract link(): Promise<Link>;
     abstract length(): Promise<number | undefined>;
-    abstract read(range?: NumberRange): Promise<Uint8Array | undefined>;
+    abstract read(range?: NumberRange, options?: ResourceReadOptions): Promise<Uint8Array | undefined>;
     readAsString(): Promise<string | undefined>;
     readAsJSON(): Promise<unknown | undefined>;
-    readAsXML(): Promise<XMLDocument | undefined>;
+    readAsXML(): Promise<Document | undefined>;
     abstract close(): void;
 }

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

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

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

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

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

@@ -1,2 +1,10 @@
-import { Properties } from '../Properties.ts';
-export declare function getContains(properties: Properties): Set<string>;
+declare module '../Properties' {
+    interface Properties {
+        /**
+         * Identifies content contained in the linked resource, that cannot be strictly identified using a
+         * media type.
+         */
+        getContains(): Set<string> | undefined;
+    }
+}
+export {};

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

@@ -1,8 +1,19 @@
 import { Links } from '../Link.ts';
-import { Publication } from '../Publication.ts';
-export declare function getPageList(pub: Publication): Links | undefined;
-export declare function getLandmarks(pub: Publication): Links | undefined;
-export declare function getListOfAudioClips(pub: Publication): Links | undefined;
-export declare function getListOfIllustrations(pub: Publication): Links | undefined;
-export declare function getListOfTables(pub: Publication): Links | undefined;
-export declare function getListOfVideoClips(pub: Publication): Links | undefined;
+declare module '../Publication' {
+    interface Publication {
+        /**
+         * Provides navigation to positions in the Publication content that correspond to the locations of
+         * page boundaries present in a print source being represented by this EPUB Publication.
+         */
+        getPageList(): Links | undefined;
+        /**
+         * Identifies fundamental structural components of the publication in order to enable Reading
+         * Systems to provide the User efficient access to them.
+         */
+        getLandmarks(): Links | undefined;
+        getListOfAudioClips(): Links | undefined;
+        getListOfIllustrations(): Links | undefined;
+        getListOfTables(): Links | undefined;
+        getListOfVideoClips(): Links | undefined;
+    }
+}