@readium/shared 2.2.0-alpha.2 → 2.2.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/shared",
-  "version": "2.2.0-alpha.2",
+  "version": "2.2.0-beta.2",
   "type": "module",
   "description": "Shared models to be used across other Readium projects and implementations in Typescript",
   "author": "readium",
@@ -44,6 +44,15 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "dev": "vite",
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build",
+    "test": "jest",
+    "size": "size-limit",
+    "check-locales": "node scripts/check-locales.mjs",
+    "update-locales": "pnpm remove @edrlab/thorium-locales && pnpm add @edrlab/thorium-locales@github:edrlab/thorium-locales && pnpm check-locales"
+  },
   "size-limit": [
     {
       "path": "dist/index.js",
@@ -68,14 +77,5 @@
     "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",
-    "size": "size-limit",
-    "check-locales": "node scripts/check-locales.mjs",
-    "update-locales": "pnpm remove @edrlab/thorium-locales && pnpm add @edrlab/thorium-locales@github:edrlab/thorium-locales && pnpm check-locales"
   }
-}
+}

package/src/fetcher/HttpFetcher.ts

@@ -108,7 +108,7 @@ export class HttpResource implements Resource {
     return await resp.text();
   }
 
-  async readAsXML(): Promise<Document> {
+  async readAsXML(): Promise<XMLDocument> {
     const resp = await this.client(this.url);
     if (!resp.ok)
       throw new Error(
@@ -116,7 +116,7 @@ export class HttpResource implements Resource {
       ); // TODO
     return new DOMParser().parseFromString(
       await resp.text(),
-      this._link.mediaType.isHTML ? (this._link.mediaType.string as 'application/xhtml+xml' | 'text/html') : 'text/xml'
+      'application/xml'
     );
   }
 }

package/src/fetcher/Resource.ts

@@ -27,11 +27,11 @@ export abstract class Resource {
       return JSON.parse(str);
     });
   }
-  readAsXML(): Promise<Document | undefined> {
-    return this.link().then(l => this.readAsString().then(str => {
+  readAsXML(): Promise<XMLDocument | undefined> {
+    return this.readAsString().then(str => {
       if (str === undefined) return str;
-      return new DOMParser().parseFromString(str, l.mediaType.isHTML ? (l.mediaType.string as 'application/xhtml+xml' | 'text/html') : 'text/xml');
-    }));
+      return new DOMParser().parseFromString(str, 'text/xml');
+    });
   }
   abstract close(): void;
 }

package/src/publication/Manifest.ts

@@ -35,7 +35,7 @@ export class Manifest {
   constructor(values: {
     context?: Array<string>;
     metadata: Metadata;
-    links?: Links;
+    links: Links;
     readingOrder: Links;
     resources?: Links;
     toc?: Links;
@@ -43,7 +43,7 @@ export class Manifest {
   }) {
     this.context = values.context;
     this.metadata = values.metadata;
-    this.links = values.links || new Links([]);
+    this.links = values.links;
     this.readingOrder = values.readingOrder;
     this.resources = values.resources;
     this.toc = values.toc;
@@ -63,6 +63,10 @@ export class Manifest {
 
     if (!metadata) return;
 
+    const links = Links.deserialize(json.links);
+
+    if (!links) return;
+
     const readingOrder = Links.deserialize(
       json.readingOrder ? json.readingOrder : json.spine
     );
@@ -72,7 +76,7 @@ export class Manifest {
     return new Manifest({
       context: arrayfromJSONorString(json['@context']),
       metadata,
-      links: Links.deserialize(json.links),
+      links,
       readingOrder,
       resources: Links.deserialize(json.resources),
       toc: Links.deserialize(json.toc),
@@ -89,7 +93,7 @@ export class Manifest {
     const json: any = {};
     if (this.context !== undefined) json['@context'] = this.context;
     json.metadata = this.metadata.serialize();
-    if (this.links?.items.length > 0) json.links = this.links.serialize();
+    json.links = this.links.serialize();
     json.readingOrder = this.readingOrder.serialize();
     if (this.resources) json.resources = this.resources.serialize();
     if (this.toc) json.toc = this.toc.serialize();
@@ -104,9 +108,7 @@ export class Manifest {
     if (this.resources) {
       links.push(this.resources);
     }
-    if(this.links) {
-      links.push(this.links);
-    }
+    links.push(this.links);
 
     let result: Link | undefined;
 
@@ -127,9 +129,7 @@ export class Manifest {
     if (this.resources) {
       result.push(this.resources.filterByRel(rel));
     }
-    if(this.links) {
-      result.push(this.links.filterByRel(rel));
-    }
+    result.push(this.links.filterByRel(rel));
 
     return result.reduce((acc, val) => acc.concat(val), []);
   }
@@ -197,9 +197,7 @@ export class Manifest {
     if (this.resources) {
       links.push(this.resources);
     }
-    if(this.links) {
-      links.push(this.links);
-    }
+    links.push(this.links);
 
     const link = find(links);
 

package/src/publication/Publication.ts

@@ -12,6 +12,8 @@ import { PublicationCollection } from './PublicationCollection';
 import { Resource } from '../fetcher/Resource';
 import { GuidedNavigationDocument } from "./GuidedNavigation";
 import { URITemplate } from "../util";
+import { MediaType } from "../util/mediatype/MediaType";
+import { Timeline } from './services/timeline/Timeline';
 
 export type ServiceFactory = () => null;
 
@@ -20,6 +22,7 @@ export class Publication {
   /** The manifest holding the publication metadata extracted from the publication file */
   public manifest: Manifest;
   private readonly fetcher: Fetcher = new EmptyFetcher();
+  private _timeline: Timeline | undefined;
 
   // Shortcuts to manifest properties
   public readonly context?: Array<string>;
@@ -46,6 +49,16 @@ export class Publication {
     this.subcollections = values.manifest.subcollections;
   }
 
+  /**
+   * Returns the publication's timeline, built from its reading order and table of contents.
+   * Called with no arguments, the result is cached. Pass options to build a fresh timeline
+   * with a specific configuration (e.g. a depth limit).
+   */
+  public get timeline(): Timeline {
+    if (!this._timeline) this._timeline = Timeline.build(this);
+    return this._timeline;
+  }
+
   /** The URL where this publication is served, computed from the `Link` with `self` relation.
    *  e.g. https://provider.com/pub1293/manifest.json gives https://provider.com/pub1293/
    */
@@ -79,6 +92,36 @@ export class Publication {
     return this.manifest.linkWithRel(rel);
   }
 
+  /**
+   * Gets the cover image for the publication.
+   * First looks for rel='cover' in links/resources/readingOrder,
+   * then falls back to any image (JPEG, PNG, GIF, AVIF, SVG) as bitmap fallback.
+   */
+  public getCover(): Link | undefined {
+    const locations = [
+      this.links,
+      this.resources,
+      this.readingOrder
+    ].filter(Boolean) as Links[];
+
+    // First, look for explicit cover relationship
+    for (const location of locations) {
+      const cover = location.items.find(link => link.rels?.has('cover'));
+      if (cover) return cover;
+    }
+
+    // Fallback to any image (including SVG which is not bitmap)
+    for (const location of locations) {
+      const image = location.items.find(link => 
+        link.mediaType.isBitmap || 
+        link.mediaType.matches(MediaType.SVG)
+      );
+      if (image) return image;
+    }
+
+    return undefined;
+  }
+
   public async positionsFromManifest(): Promise<Locator[]> {
     const positionListLink = this.manifest.links.findWithMediaType(
       'application/vnd.readium.position-list+json'

package/src/publication/html/Locations.ts

@@ -53,13 +53,6 @@ declare module '../Locator' {
      * https://www.w3.org/TR/media-frags/
      */
     space(): [number, number, number, number] | undefined;
-
-    /**
-     * Text fragments, used by browsers to jump to/highlight text.
-     *
-     * https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments
-     */
-    text(): string | undefined;
   }
 }
 
@@ -133,11 +126,4 @@ LocatorLocations.prototype.space = function(): [number, number, number, number]
   if(xywh.length !== 4) return; // Must have four parts
   if(xywh.some(isNaN)) return; // All parts must be numbers
   return xywh as [number, number, number, number];
-}
-
-LocatorLocations.prototype.text = function(): string | undefined {
-  const fp = this.fragmentParameters();
-  console.log(fp);
-  // :~:
-  return undefined;
 }

package/src/publication/services/index.ts

@@ -1 +1,2 @@
-export * from './content';
+export * from './content';
+export * from './timeline';

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

@@ -0,0 +1,349 @@
+import { Link, Links } from "../../Link";
+import { Locator } from "../../Locator";
+import { TimelineItem } from "./TimelineItem";
+
+interface PublicationLike {
+    toc?: Links;
+    readingOrder: Links;
+}
+
+/**
+ * A publication's timeline, built once from its reading order and table of contents.
+ *
+ * **Source of truth**: the reading order.  Every reading order item becomes
+ * exactly one top-level `TimelineItem`.  The TOC is consulted to:
+ *   1. Derive a display title when the reading order item has none.
+ *   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.
+ *
+ * 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 _depth: number | undefined;
+    private _items: TimelineItem[] | undefined;
+    private _flat: TimelineItem[] | undefined;
+
+    constructor(items: TimelineItem[], linkMap: Map<TimelineItem, Link>) {
+        this._allItems = items;
+        this.linkMap = linkMap;
+    }
+
+    static build(publication: PublicationLike, options: { depth?: number } = {}): Timeline {
+        const tocLinks = publication.toc?.items ?? [];
+        const roLinks = publication.readingOrder.items;
+        const { depth } = options;
+        const linkMap = new Map<TimelineItem, Link>();
+        const items: TimelineItem[] = [];
+
+        for (let i = 0; i < roLinks.length; i++) {
+            const ro = roLinks[i];
+            const bare = Timeline.bareHref(ro.href);
+
+            const title =
+                ro.title ??
+                Timeline.findTitleInToc(tocLinks, bare, depth) ??
+                `Resource ${i + 1}`;
+
+            const tocChildren = Timeline.collectChildrenFromToc(tocLinks, bare, depth, 1, linkMap);
+
+            const item: TimelineItem = {
+                title,
+                references: [ro.href],
+                children: tocChildren.length > 0 ? tocChildren : undefined,
+            };
+
+            const tocLink = Timeline.findTocLink(tocLinks, bare, depth);
+            linkMap.set(item, tocLink ?? ro);
+            items.push(item);
+        }
+
+        return new Timeline(items, linkMap);
+    }
+
+    /**
+     * The active depth limit for TOC traversal (title resolution and child
+     * collection).  `undefined` means unlimited.  Setting the same value again
+     * is a no-op; a new value invalidates the cached items and flat list.
+     */
+    get depth(): number | undefined {
+        return this._depth;
+    }
+
+    set depth(value: number | undefined) {
+        if (this._depth === value) return;
+        this._depth = value;
+        this._items = undefined;
+        this._flat = undefined;
+    }
+
+    /** Top-level timeline items.  Cached; invalidated when `depth` changes. */
+    get items(): TimelineItem[] {
+        if (!this._items) {
+            this._items = this._depth !== undefined
+                ? Timeline.trimToDepth(this._allItems, this._depth)
+                : this._allItems;
+        }
+        return this._items;
+    }
+
+    locate(locator: Locator): TimelineItem | undefined {
+        const href = locator.href.split("#")[0];
+        const time = locator.locations?.time();
+
+        let match: TimelineItem | undefined;
+
+        if (time !== undefined) {
+            for (const item of this.flat) {
+                if (this.itemMatchesTime(item, href, time)) match = item;
+            }
+        }
+
+        if (!match) {
+            match = this.flat.find(item => this.bareHrefFromItem(item) === href);
+        }
+
+        return match;
+    }
+
+    adjacentTo(item: TimelineItem): { previous: TimelineItem | undefined; next: TimelineItem | undefined } {
+        const index = this.flat.indexOf(item);
+        return {
+            previous: index > 0 ? this.flat[index - 1] : undefined,
+            next: index >= 0 && index < this.flat.length - 1 ? this.flat[index + 1] : undefined,
+        };
+    }
+
+    segmentsForHref(href: string): TimelineItem[] {
+        const bare = href.split("#")[0];
+        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;
+            for (const child of item.children) {
+                const t = this.timeFromItem(child);
+                if (t === undefined || t > time) break;
+                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) ?? [];
+    }
+
+    linkFor(item: TimelineItem): Link | undefined {
+        return this.linkMap.get(item);
+    }
+
+    private get flat(): TimelineItem[] {
+        if (!this._flat) this._flat = this.flattenItems(this.items);
+        return this._flat;
+    }
+
+    // -------------------------------------------------------------------------
+    // TOC title resolution
+    // -------------------------------------------------------------------------
+
+    /**
+     * Resolve a display title for `bare` from the TOC, looking no deeper than
+     * `maxDepth` levels (1 = top-level entries only).  Priority:
+     *   1. A start-of-resource entry: bare href or `#t=0` (audio).
+     *   2. Exactly one fragment entry referencing this resource — unambiguous.
+     *   3. Multiple fragment entries — ambiguous, returns `undefined`.
+     */
+    private static findTitleInToc(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+    ): string | undefined {
+        const { atStart, fragments } = Timeline.collectTocCandidates(tocLinks, bare, maxDepth, 1);
+        if (atStart.length > 0) return atStart[0].title!;
+        if (fragments.length === 1) return fragments[0].title!;
+        return undefined;
+    }
+
+    /**
+     * Return the most relevant TOC Link for `bare` (used for `linkFor`).
+     * Prefers a start-of-resource entry; falls back to the first fragment entry.
+     */
+    private static findTocLink(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+    ): Link | undefined {
+        const { atStart, fragments } = Timeline.collectTocCandidates(tocLinks, bare, maxDepth, 1);
+        return atStart[0] ?? fragments[0];
+    }
+
+    /**
+     * Collect all TOC entries that reference `bare` as flat children, walking
+     * up to `maxDepth` levels deep.  Start-of-resource entries (#t=0 or no
+     * fragment) are excluded — they contribute to title resolution, not children.
+     * Order follows TOC declaration (depth-first).
+     */
+    private static collectChildrenFromToc(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+        currentDepth: number,
+        linkMap: Map<TimelineItem, Link>,
+    ): TimelineItem[] {
+        if (maxDepth !== undefined && currentDepth > maxDepth) return [];
+
+        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] };
+                linkMap.set(child, link);
+                result.push(child);
+            }
+
+            if (link.children?.items?.length) {
+                result.push(...Timeline.collectChildrenFromToc(
+                    link.children.items, bare, maxDepth, currentDepth + 1, linkMap,
+                ));
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Walk the TOC tree up to `maxDepth` levels and collect all entries whose
+     * bare href matches `bare`, split into start-of-resource entries and
+     * fragment entries.
+     */
+    private static collectTocCandidates(
+        tocLinks: Link[],
+        bare: string,
+        maxDepth: number | undefined,
+        currentDepth: number,
+    ): { atStart: Link[]; fragments: Link[] } {
+        if (maxDepth !== undefined && currentDepth > maxDepth) {
+            return { atStart: [], fragments: [] };
+        }
+
+        const atStart: Link[] = [];
+        const fragments: Link[] = [];
+
+        for (const link of tocLinks) {
+            if (Timeline.bareHref(link.href) === bare && link.title) {
+                if (Timeline.isStartOfResource(link.href)) {
+                    atStart.push(link);
+                } else {
+                    fragments.push(link);
+                }
+            }
+
+            if (link.children?.items?.length) {
+                const child = Timeline.collectTocCandidates(
+                    link.children.items, bare, maxDepth, currentDepth + 1,
+                );
+                atStart.push(...child.atStart);
+                fragments.push(...child.fragments);
+            }
+        }
+
+        return { atStart, fragments };
+    }
+
+    /**
+     * A TOC href points to the start of its resource when it has no fragment,
+     * or when the fragment is `t=0` (audio: explicit beginning of the file).
+     */
+    private static isStartOfResource(href: string): boolean {
+        const fragment = href.split("#")[1];
+        if (!fragment) return true;
+        return fragment === "t=0";
+    }
+
+    // -------------------------------------------------------------------------
+    // Shared utilities
+    // -------------------------------------------------------------------------
+
+    private static trimToDepth(items: TimelineItem[], remaining: number): TimelineItem[] {
+        return items.map(item => ({
+            ...item,
+            children: remaining > 1 && item.children?.length
+                ? Timeline.trimToDepth(item.children, remaining - 1)
+                : undefined,
+        }));
+    }
+
+    private flattenItems(items: TimelineItem[]): TimelineItem[] {
+        const result: TimelineItem[] = [];
+        for (const item of items) {
+            result.push(item);
+            if (item.children) result.push(...this.flattenItems(item.children));
+        }
+        return result;
+    }
+
+    private itemMatchesTime(item: TimelineItem, href: string, time: number): boolean {
+        for (const ref of item.references) {
+            const hashIndex = ref.indexOf("#");
+            const refHref = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+            const refFragment = hashIndex >= 0 ? ref.slice(hashIndex + 1) : undefined;
+            if ((refHref || href) !== href) continue;
+            if (time >= Timeline.parseTimeFragment(refFragment)) return true;
+        }
+        return false;
+    }
+
+    private static parseTimeFragment(fragment: string | undefined): number {
+        if (!fragment) return 0;
+        const match = fragment.match(/(?:^|&)t=(\d+(?:\.\d+)?)/);
+        return match ? parseFloat(match[1]) : 0;
+    }
+
+    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=(\d+(?:\.\d+)?)/);
+        return match ? parseFloat(match[1]) : undefined;
+    }
+
+    private ancestorPath(items: TimelineItem[], target: TimelineItem): TimelineItem[] | null {
+        for (const item of items) {
+            if (item === target) return [];
+            if (item.children) {
+                const path = this.ancestorPath(item.children, target);
+                if (path !== null) return [item, ...path];
+            }
+        }
+        return null;
+    }
+
+    private static bareHref(href: string): string {
+        return href.split("#")[0];
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Represents a single entry in a publication's timeline.
+ *
+ * The timeline contextualizes the reading order and table of contents so that
+ * consuming apps can display the current chapter title, build a progress bar,
+ * show previous/next as chapter titles, group search results by chapter, etc.
+ */
+export interface TimelineItem {
+    /** 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.
+     */
+    references: string[];
+    /** Structural roles of this entry, e.g. ["chapter"], ["part"]. */
+    role?: string[];
+    /** 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;
+    /** Nested entries. */
+    children?: TimelineItem[];
+}

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

@@ -0,0 +1,2 @@
+export * from './Timeline';
+export * from './TimelineItem';

package/src/util/mediatype/MediaType.ts

@@ -224,6 +224,7 @@ export class MediaType {
   /** Returns whether this media type is of a bitmap image, so excluding vectorial formats. */
   public get isBitmap(): boolean {
     return this.matchesAny(
+      MediaType.AVIF,
       MediaType.BMP,
       MediaType.GIF,
       MediaType.JPEG,
@@ -292,6 +293,9 @@ export class MediaType {
       fileExtension: 'avi',
     });
   }
+  public static get AVIF(): MediaType {
+    return MediaType.parse({ mediaType: 'image/avif', fileExtension: 'avif' });
+  }
   public static get BINARY(): MediaType {
     return MediaType.parse({ mediaType: 'application/octet-stream' });
   }

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

@@ -24,5 +24,5 @@ export declare class HttpResource implements Resource {
     length(): Promise<number>;
     readAsJSON(): Promise<unknown>;
     readAsString(): Promise<string>;
-    readAsXML(): Promise<Document>;
+    readAsXML(): Promise<XMLDocument>;
 }

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

@@ -10,6 +10,6 @@ export declare abstract class Resource {
     abstract read(range?: NumberRange): Promise<Uint8Array | undefined>;
     readAsString(): Promise<string | undefined>;
     readAsJSON(): Promise<unknown | undefined>;
-    readAsXML(): Promise<Document | undefined>;
+    readAsXML(): Promise<XMLDocument | undefined>;
     abstract close(): void;
 }

package/types/src/publication/Manifest.d.ts

@@ -20,7 +20,7 @@ export declare class Manifest {
     constructor(values: {
         context?: Array<string>;
         metadata: Metadata;
-        links?: Links;
+        links: Links;
         readingOrder: Links;
         resources?: Links;
         toc?: Links;