Sign in Subscribe
Web

Release Note · July 2026: New features in the TS Toolkit

We are pleased to announce the implementation of the Decorator API in TS-Toolkit, along with Timeline support for HTML publications, tree-shakeable ESM-only builds, and a new Helpers package.

Release Note · July 2026: New features in the TS Toolkit


Browse the full releases on GitHub

The Decorator API


The Decorator API lets you render visual annotations over text, addressed by Locator rather than raw DOM ranges. EpubNavigator and WebPubNavigator now implement it directly, so you can apply decorations, group them, and react to activation and hover without touching the DOM yourself.

Decorations are applied in groups — "tts", "search-results", "annotations", whatever makes sense for your app. Calling applyDecorations() again for a group simply replaces its previous decorations.

The original API only had highlight and underline. This release adds outline, text color, mask, custom HTML templates, a combined highlightUnderline, and strikethrough. Hover is new too: register onDecorationPointerEnter/onDecorationPointerLeave on a DecorationObserver, alongside the existing onDecorationActivated for taps and clicks.

The Decorator API is shared across the Readium toolkits, and these additions land in TS-Toolkit first — we expect Kotlin and Swift to follow.

@readium/decorator also ships a new DecorationController, so you can render decorations directly on a webpage with no navigator involved at all. We will use it ourselves in @readium/speech.

Demo from Readium Speech with an article on Speech Synthesis. We can see controls and read along feature being activated. In the text, the current utterance has a yellow background, the spoken word has a red underline.
This new Decorator package will be used and provided in Readium Speech. It should simplify decorating utterances and boundaries for a read-along feature.

Tree-shakeable, ESM-only builds (breaking change)


@readium/shared, @readium/navigator, and @readium/navigator-html-injectables have all moved to tree-shakeable builds, dropping their CommonJS/UMD build. All three are now ESM-only.

@readium/shared no longer patches methods directly onto its models (e.g. loc.time()). Those are now standalone functions you import instead (getTime(loc)). See our migration guide for the full before/after mapping.

If your project consumes these packages via require() or a bundler that doesn't understand ESM, you will need to update your setup before pulling in these versions.

Timeline, now for HTML-based publications


The Timeline API used to only make sense for audiobooks, where it tracks playback position across resources. It now works for HTML publications too, letting any navigator report its position on a shared timeline and notify you when the reader crosses into a new timeline item — useful for chapter indicators or table-of-contents highlighting.

You can now also get a contextualized table of contents: each entry annotated with a formatted timestamp for audiobooks, or a position for EPUB, so you can render a TOC that shows where each chapter falls without computing that yourself.

Thorium Web audio player with its table of contents open. For each entry you can see a timestamp, which represents the start of the part or section.
As part of this update, the API now returns a contextualised table of contents. For audiobooks, it populates timestamp for each entry, so that you know where it starts in the publication.

This is still a work in progress: positions are currently resolved at runtime for EPUB, so TOC entries that point to a specific anchor within a chapter, rather than the chapter itself, don't always get one. Resolving those ahead of time is one of our next challenge across toolkits.

New: Helpers for browser utilities


@readium/helpers is a new package for general-purpose browser utilities: color parsing and contrast helpers, plus OS/browser detection. The contrast helpers are handy on their own — they're how you'd check that a highlight color stays readable against arbitrary publication styling.

These are the same utilities @readium/navigator and @readium/navigator-html-injectables use internally, now published as their own package so you can use them directly, even outside of a Readium navigator.

Technical updates and breaking changes


A few smaller changes are worth knowing about:

  • Spatial media fragments: As part of the standalone-functions migration, getSpace() now also supports percentages, not just pixels.
  • Timeline accuracy: Decimal timestamps in audio locators are now handled correctly, fixing retrieval of timeline items at fractional-second positions.
  • Decorations: Now render into the Shadow DOM, and BasicTextSelection returns a ready-to-use Locator.
  • Keyboard input: Now ignores synthetic (non-trusted) key events.
  • Accessibility metadata: Spanish, Estonian, Finnish, Polish, and Greek are now supported languages for the accessibility metadata display guide.

All packages are available on NPM:

Read next