Package and startup

WebPub and EPUB have different containers, but both expose an ADT data root. Resolve that root once, then load only the sidecars that are actually present. The root is shared; the available feature files can differ by format and export.

The two package shapes

webpub/
  manifest.json
  assets/config.json
  content/pages.json
  content/i18n/<lang>/
  pg002_sec001.html …

META-INF/container.xml
OEBPS/
  content.opf
  assets/config.json
  content/pages.json
  content/i18n/<lang>/
  pg002_sec001.xhtml …

Reader prerequisites

Your reader must be able to inspect and update the rendered content document. Use a same-origin iframe, a webview injection bridge, or preprocessing before display. A cross-origin iframe without an injection bridge cannot apply the ADT text map, glossary markers, or page-level feature behavior.

Treat an opened package as untrusted. Keep its filesystem path or ZIP handle on the trusted side of your application; the UI should receive a book handle, never an arbitrary path supplied by page content.

Inspect export references

These syntax-highlighted excerpts come from verified ADT exports. They are reference artifacts, not file names that a reader must reproduce. Select a file to see why it matters; the highlighting is produced at build time from the committed sample, so no highlighter is sent to the reader’s browser. The collection can grow with additional exports as the formats evolve.

{
  "@context": "https://readium.org/webpub-manifest/context.jsonld",
  "metadata": {
    "@type": "http://schema.org/Book",
    "conformsTo": [
      "https://readium.org/webpub-manifest/profiles/epub"
    ],
    "title": "Hyena and Raven",
    "language": [
      "en-US",
      "pt-BR"
    ],
    "modified": "2026-08-27T21:29:26.733Z",
    "presentation": {
      "overflow": "scrolled",
      "spread": "none"
    },
    "author": "Tony Lelliott, Wiehan de Jager",
    "publisher": "African Storybook",
    "accessibility": {
      "accessMode": [
        "textual",
        "visual",
        "auditory"
      ],
      "accessModeSufficient": [
        [
          "textual",
          "visual"
        ]
      ],
      "feature": [
        "readingOrder",
        "tableOfContents",
        "alternativeText",
        // … 2 more entries
      ],
      "hazard": [
        "none"
      ],
      "summary": "Includes read-aloud audio synchronized with the text, alternative text for images, sign-language video."
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "manifest.json",
      "type": "application/webpub+json"
    },
    {
      "rel": "cover",
      "href": "cover.png",
      "type": "image/png"
    }
  ],
  "readingOrder": [
    {
      "href": "index.html",
      "type": "text/html",
      "title": "pg001_sec001"
    },
    {
      "href": "pg002_sec001.html",
      "type": "text/html",
      "title": "1"
    },
    {
      "href": "pg003_sec001.html",
      "type": "text/html",
      "title": "2"
    },
    // … 12 more entries
  ],
  "resources": [
    {
      "href": "assets/activities.bundle.local.js",
      "type": "application/javascript"
    },
    {
      "href": "assets/auto-fit.js",
      "type": "application/javascript"
    },
    {
      "href": "assets/config.json",
      "type": "application/json"
    },
    // … 333 more entries
  ],
  "toc": [
    {
      "href": "index.html",
      "title": "Hyena and"
    }
  ],
  "pageList": [
    {
      "href": "pg002_sec001.html",
      "title": "1"
    },
    {
      "href": "pg003_sec001.html",
      "title": "2"
    },
    {
      "href": "pg004_sec001.html",
      "title": "3"
    },
    // … 7 more entries
  ],
  "landmarks": [
    {
      "rel": "cover",
      "href": "cover.png"
    },
    {
      "rel": "bodymatter",
      "href": "index.html"
    }
  ]
}

Detect an ADT

A publication is an ADT when it has a readable configuration file with a features object and a recognisable WebPub or EPUB entry point:

const dataBase = await exists(join(packageRoot, "OEBPS/content.opf"))
  ? join(packageRoot, "OEBPS")
  : packageRoot;

const config = await readJson(join(dataBase, "assets/config.json"));
const isAdt = Boolean(
  config?.features &&
    (await exists(join(dataBase, "manifest.json")) ||
      await exists(join(dataBase, "content.opf"))),
);

dataBase is the package root for WebPub and OEBPS/ for EPUB. Keep detection cheap: read one config file and stat only the expected entry points. Feature flags describe data that was produced; when a flag is false, hide the control rather than showing an affordance that cannot work. Invalid JSON or a missing config means “not an ADT,” not a reader error.

V1 sidecar contract

assets/config.json carries bundleVersion. The reference exports on this page use version 1. A reader should treat an unknown future version as a new contract, retain baseline WebPub or EPUB reading, and avoid activating ADT enhancements until it supports that version.

All sidecars are optional, even when a feature flag is true. A flag means the export can provide a capability; the current language and page must still have usable data.

The current EPUB reference includes the text map and native glossref markup. It does not demonstrate every WebPub sidecar. Do not infer sidecar parity between formats. Word timing is not guaranteed by V1: when a book carries it, it ships as a timecode/ sidecar, and an EPUB may instead expose native Media Overlays. Treat either as progressive enhancement and keep narration working at node level without them — see Read-aloud.

What the public references cover

The code excerpts on this page prove the shapes below, but they are not complete downloadable test packages. Use them to understand the contract; use your own package-level tests before shipping.

When a new public format or capability is added, include a publishable fixture package and expected-results matrix with it. PNLD packages are out of scope for this public contract.

Structural markers

The rendered HTML has the joining information your reader needs:

Use these markers rather than file names when deciding how to render a page.