Proposal: Timeline API

[JayPanoz]

Summary

The Timeline is a media-type-agnostic model of a publication's structure, built from its reading order and table of contents and augmented by a navigator with the format-specific data it depends on — a Positions List for EPUB, native page numbers for PDF, track durations for audio — exposing a single API to locate, traverse, and inspect that structure regardless of format.

Motivation

Reading apps constantly need to tell the user where they are: the chapter title in a running header, the previous and next section names in a navigation bar, the chapter a search result or bookmark falls in. This is structural context, and users expect it everywhere.

Today every app rebuilds it by reconciling information scattered across several differently-shaped pieces — the reading order, the table of contents, and whatever format-specific data is needed to pin down an actual location, such as a Positions List for EPUB or track durations for audio — none of which was designed on its own to answer "which entry covers a given location?". And how a location is expressed depends on the format: a time offset for audio, an anchor or progression for reflowable text, a page for PDF. So the same reconciliation logic gets written again and again, per format and per platform.

The Timeline does that reconciliation in the toolkit instead of in every app: built from the reading order and table of contents, then augmented by a navigator with whatever format-specific data it needs, it gives an app a single structural view of the publication against which to ask a few simple questions and get the same kind of answer regardless of format.

Use cases

• A running header showing the current chapter title.
• Previous/next navigation labelled with the adjacent section names.
• A progress bar divided into chapter segments, naming the chapter under the cursor.
• Search results, bookmarks, and highlights grouped under the chapter they fall in.
• Breadcrumbs from the publication down to the current section.
• A dedicated table-of-contents panel that highlights the entry matching the current reading position, with a position, page number, or timestamp next to each entry.