Release notes Web Framework 5 release candidate

For more information about release candidates, see Release Candidates.

5.0.0-rc.7 2026-09-11

API Docs

Bugfixes

• Fixed an issue where an EPUB content document containing an XML processing instruction, for example <?target data?>, sometimes failed to render on Chrome 150 and later, leaving the page blank.

5.0.0-rc.6 2026-09-08

API Docs

Breaking changes

• Added a warning log whenever the Reading System emits a license event with zero listeners. This includes all events listed in the IEngineEventTypeMap that start with the word license. Add listeners for these events using ReadingSystemEngine.addEngineEventListener().
• Setting ISyncMediaManagedReaderViewSynchronizationOptions.enabled to false now disables all synchronization: the player no longer updates the Reading Position, IReaderView.scrollBy() no longer seeks the player, and IReaderView.setSyncMediaPlayer() no longer performs any initial synchronization, whichever initialSyncMethod is given. Call ISyncMediaPlayer.attemptReaderViewSynchronization() from your application instead.
• The options parameter of ISyncMediaPlayer.setManagedReaderViewSynchronizationOptions() is now required.

New features

• Added the new option ISyncMediaTtsTimelineContentTransformationOptions.contentBlockAttributeExclusions. It lists the attribute names, and optionally attribute values, that exclude a content block and its descendants from a TTS Sync Media timeline. By default, content blocks with role="presentation", role="none" or aria-hidden="true" are excluded, which matches the previous hard-coded behavior. Setting the option replaces the default list rather than adding to it, and an empty list excludes nothing. Attribute names are matched on the qualified name, so a namespace-prefixed attribute must be listed with its prefix.

Improvements

• <audio>, <video>, <canvas> and <iframe> elements are now always kept indivisible during reflow, whatever IEpubReflowOptions.plugins.fragmentableElements.blacklistSelectors is set to, so a page break can no longer be placed inside one. <audio> and <video> have therefore been removed from that option's default value, which is now ['tr', 'picture', 'math'].
• In ContinuousScrollRenderer and SingleDocumentScrollRenderer, a settled user scroll now moves the Reading Position reported by IReaderView.getReadingPosition() to the start of the Reading Area, instead of leaving it where it was until it fell outside the visible range. It can still differ from the Reading Area start, for example while a Sync Media player with managed synchronization drives it. See the API documentation for details.

Bugfixes

• Fixed an issue where <audio>, <video>, <canvas> and <iframe> elements in reflowable publications were left-aligned in paginated renderers instead of being centered by their container's text-align (e.g. figure { text-align: center }).
• Fixed an issue where an <audio controls> element in a reflowable publication collapsed to zero size, hiding its controls, when the page was narrower than the control's default width.
• Fixed an issue where an image that a publication sized by height or max-height alone was sometimes rendered at the image file's full width, leaving it stretched or several times larger than intended.
• Fixed an issue where an SVG image with only a viewBox and no intrinsic width/height no longer filled the available width, and instead collapsed to the browser's default image size, which differs between browsers.
• Fixed an issue where an image in a reflowable publication was resized when the publication's CSS combined box-sizing: border-box with a border or padding on the image.
• Fixed an issue where an element that set overflow-x through an inline style attribute was measured with a scrollable vertical overflow, which could change layout and pagination. Affected content also logged a warning naming an invalid CSS selector.
• Fixed an issue where embedded fonts in EPUB publications whose @font-face rules declare only WOFF2 sources were never loaded, so the content was rendered with a fallback font instead. This affected WKWebView, Samsung Internet and Electron.
• Fixed an issue where IReaderView.scrollBy() did not move the Reading Position to the start of the new Reading Area unless IReaderViewScrollByOptions.setReadingPositionToReadingAreaStart was passed explicitly, even though the option is documented to default to true.
• Fixed an issue where ISyncMediaPlayer.setManagedReaderViewSynchronizationOptions() silently reset every option the caller did not mention to its default value. A partial update now keeps the options it does not mention, the same way other setOptions() methods behave.
• Fixed an issue where attaching a Sync Media player with IReaderView.setSyncMediaPlayer() left it attached to the Reader View it was already attached to. Both Reader Views kept returning the player from IReaderView.getSyncMediaPlayer() while only one of them was actually driven by it. A player drives one Reader View at a time, and attaching it now detaches it from the other Reader View and logs a warning.
• Fixed an issue where IReaderView.getSyncMediaPlayer() kept returning a Sync Media player after ISyncMediaPlayer.destroy() had been called. Destroying a player now detaches it from the Reader View.
• Fixed an issue where IVerticalScrollRendererOptions.readingAreaOffsetTop and readingAreaOffsetBottom were not capped to the documented 0-30% of the display area in the scroll renderers.

5.0.0-rc.5 2026-07-21

API Docs

Breaking changes

• The insets option has been moved from IRendererOptions to IReaderViewOptions.contentDisplayAreaOptions.

New features

• Added the new option IPublicationStyleOptions.hyphens. This option determines how words should be hyphenated when text wraps across multiple lines.
• Added the new option IEpubRemoteResourceOptions.iframeDomainsToRenderAsOverlay that allows embedded iframes to render as an overlay on top of the publication content. This prevents some third-party websites, such as youtube.com, from blocking their content due to missing Referer header.
• The insets option is now fully supported by all renderers. You set it using IReaderViewOptions.contentDisplayAreaOptions.insets.
• Added the new method IVisiblePage.fetchBoundingClientRectForContentLocation(). It returns a single DOMRect, in application viewport coordinates, that encompasses a given content location, or null when the location targets non-rendered content. Unlike fetchRectsForVisibleContent, which returns one rectangle per rendered leaf, this returns a single combined rectangle.

Bugfixes

• Fixed an issue where Reader View annotations using mix-blend-mode: multiply sometimes appeared opaque instead of blending with the background in PDFs on the desktop version of Safari 26.
• Fixed an issue where you couldn't pinch zoom if you tried to do it in the margins around the publication.
• Fixed some corner-case issues where publication content could be cut off at the end in scroll renderers.
• Fixed an issue where page navigation swipe gestures failed to trigger when initiated over a scrollable container that had reached its scroll limits.
• Fixed an issue where scripted documents consuming touch events by calling event.preventDefault() did not prevent the swipe navigation gesture in paginated renderers.
• Fixed a rendering bug where inline MathML was forced onto its own line in paginated renderers instead of remaining inline as in scroll renderers.
• Fixed an issue where attaching a SyncMediaPlayer to a ReaderView with the SYNC_MEDIA_SEEK method could navigate the view to the player's position instead of seeking the player to the current reading position.
• Fixed an issue where a <video> element that set only a width or only a height attribute could be rendered with the other dimension as 0. Missing video dimensions are now derived from the video's intrinsic aspect ratio, and videos with no available metadata no longer render at an excessive size in scroll renderers.
• Fixed an issue where enabling removePublicationDefinedHorizontalPageMargins could leave content left-aligned and narrower than the available width when a publication used a constrained width with auto margins (e.g. max-width with margin: 0 auto) to center its content.
• Fixed an issue where scripts in sandboxed EPUB content could not resolve relative URLs because Node.baseURI did not reflect the content document's URL.
• Fixed an issue where audio created with the new Audio() constructor in sandboxed EPUB content failed to load and play.
• Fixed an issue where reflowable images without explicit width/height attributes could stay locked to the narrower pre-margin width and fail to expand to the full content width after removePublicationDefinedHorizontalPageMargins removed the page margins.
• Fixed an issue where custom color palettes were not applied to publications that define colors using CSS custom properties (e.g. background-color: var(--x)), which could leave backgrounds transparent and text rendered in an incorrect color.
• Fixed an issue where an embedded <iframe> (such as a YouTube embed) in a reflowable document could overflow horizontally when the viewport was narrower than the iframe's authored width; the iframe is now scaled down to fit the available width while preserving its aspect ratio.

5.0.0-rc.4 2026-04-21

API Docs

Bugfixes

• Fixed an issue where EPUB locators were occasionally inaccurate near focused content when calling IReaderView.focusOnReadingPosition with focusTarget set to NEAREST_SENTENCE, NEAREST_WORD, or NEAREST_CHARACTER.

5.0.0-rc.3 2026-04-02

API Docs

New features

• Added support for publications utilizing CSS nesting.

• Introduced explicit focus targeting for IReaderView.focusOnReadingPosition. You can now select the nearest element, character, word, or sentence, significantly improving precision for accessibility and reading-position workflows.

• Added a new insets option to IRendererOptions that allows you to add extra padding inside the renderer's scrolling container. This is useful for ensuring content can be scrolled comfortably below system UI elements, such as the device notch or status bars on iOS and Android.

  Note: This option is experimental and its behavior might change before the final 5.0.0 release.

• Upgraded PDF.js to version 5.4.530, delivering enhanced performance and broader document compatibility.

• Added the onCMapModuleRequest option to IPdfPublicationOptions, enabling the framework to load PDF Character Map (CMap) modules on demand. This enables full text support for complex scripts and various languages while reducing the initial application bundle size.

Deprecations

• Deprecated focusNearContentLocation in IFocusOnReadingPositionOptions. Please use focusTargetOptions instead.

Improvements

• Changed the default value of IEpubSelectorDocumentSectioningAlgorithm.minimumCharactersPerSection from 10000 to 20000.
• Selectors defined in IEpubReflowOptions.plugins.fragmentableElements.blacklistSelectors are now also used when performing document sectioning breaks.
• Elements that trigger document sectioning breaks are now marked with the attribute data-colibrio-document-sectioning-break. The attribute value is set to either BEFORE or AFTER depending on the rule that triggered the document sectioning break.
• Improved the extensibility of the WebSpeechTtsSynthesizer class by changing the access modifiers for key playback callback methods from private to protected. This allows subclasses to override and orchestrate custom playback behavior more effectively.
• Impacted methods: onUtteranceBoundary, onUtteranceEnd, and onUtteranceError.

Bugfixes

• Fixed an issue that could cause publication content with position: absolute to overflow in paginated renderers without being able to scroll the content.
• Resolved an issue where :nth- pseudo-class selectors using An+B syntax like :nth-child(2n+1) sometimes were not preserved correctly.
• Fixed an EPUB rendering issue where overflow mitigations could override publication-defined CSS transforms in reflowable content documents.
• Fixed several issues where selecting text in PDF documents would fail or behave unexpectedly.

5.0.0-rc.2 2026-01-23

API Docs

Bugfixes

• Fixed an issue in the ContinuousScrollRenderer where starting your swipe action horizontally before swiping vertically would not let you scroll.
• Fixed an issue where calling IReaderView.goTo twice in quick succession (causing the first call to be aborted) could leave pages stuck in a "Loading" state or cause rendering glitches.
• Fixed an issue where nested CSS @import declarations used the wrong base URL. Relative URLs inside imported CSS files located in a different directory than the parent CSS file now resolve correctly.
• Fixed an issue with relative URLs in IPublicationStyleFontFace.srcUrl when setting publicationStyleOptions. They now resolve against the main window's base URL.
• Fixed an issue causing EPUBs with MathML to sometimes fail rendering on Chrome 108 and earlier.

5.0.0-rc.1 2025-11-14

API Docs

NOTE

These release notes describe the changes since version 4.6.0

Known issues

• When rendering PDFs using a ReaderView Element that is inside a Shadow DOM, offscreen <canvas> elements may be added to document.body instead of the Shadow root. This will be fixed in 5.0.0-rc.2.

New features

• Added the new renderer ContinuousScrollRenderer that shows all documents in a single vertical scrolling view.
• Added ReaderView.getReadingAreaRange(). The Reading Area is a subset of the visible content that the renderer uses as the reference point for reading position calculations. Note that for paginated renderers the Reading Area range is the same as the visible range. Use the readingAreaRangeChanged engine event to detect when this value changes.
  • Note: We have marked ReaderView.getReadingAreaRange() and its corresponding listener readingAreaRangeChanged as experimental APIs as we may change the definition of the Reading Area based on your feedback.
• Added support for rendering the ReaderView in a Shadow DOM. Previously, our styles were not reaching the viewElement if it was inside a Shadow DOM but that has now been fixed.
• Added a new ReaderView.goTo() option scrollRendererScrollBehavior to control how scroll renderers behave when the target position is already visible in the ReaderView.
• Scroll renderers can now smoothly scroll to nearby positions. The duration of the smooth scrolling can be controlled with the renderer options scrollAnimationDurationMs and scrollAnimationMaxDistance. Please refer to the API documentation for more information.
• Added a new event, rendererScrollChanged, which is fired continuously while scroll renderers are scrolling.
• It is now possible to determine whether scrolling was initiated by the user using the rendererScrollStarted event by inspecting the userGenerated property.
• Added a new renderer option swipeNavigationGestureThreshold. This option can be used to configure the swipe distance required to perform a swipe navigation. Additionally, swipe animations have been refined to start more smoothly.
• Added a new option to ReaderView.scrollBy() called setReadingPositionToReadingAreaStart. When set to true, the reading position moves to the start of the new Reading Area after scrolling, instead of staying until it leaves the visible range. This is now the default behavior of scrollBy().
• Added support for EPUB switch/case elements.

Breaking changes

• The minimum supported browser versions have changed to:
  • Safari 15
  • Firefox 128
  • Chrome 64
  • Edge 79
• The distributed framework module files .mjs are now real ES modules instead of importing the common JS version of the module.
• Typescript definition files are now built from Typescript 5.9.3
• The distributed framework module files are now using ECMASCRIPT 2018 syntax.
• Changed the rendererScrollStarted event type to IRendererScrollEngineEvent
• ReaderView.scrollBy() now returns a Promise that resolves when the scrolling animation has finished.
• The ContainerContentBlockType enum entry MATHML_SUB_SUPERSCRIPT was renamed to MATHML_SUBSUP_SCRIPT to be consistent with its value.

Changes to default options

• IEpubReaderPublicationOptions.documentSectioningOptions.enabled has changed from false to true.
• IReaderViewOptions.pageProgressionTimelineOptions.enabled has changed from true to false.
• IReaderPublicationOptions.reflowOptions.unforcedTextBreak.widows.minLines has changed from 3 to 2.
• If you are using PageProgressionTimeline, in addition to enabling it, you must also:
  • Set IEpubReaderPublicationOptions.documentSectioningOptions.enabled to false, or
  • Set IReaderViewOptions.pageProgressionTimelineOptions.forceCompleteRendition to true

Removed old deprecated types and members

• Removed IReaderPublicationStorage.setStorageState() and IReaderPublicationStorage.getStorageState(). Please get the storage area instead using getStorageArea(), then use IReaderPublicationStorageArea.setItems() and IReaderPublicationStorageArea.getItems() instead.
• Removed ISyncMediaPlayer.isPlaying(). Please use !isPaused() && isReady() instead.
• Removed IReaderView.fetchRectsForVisibleContent(). Please use IVisiblePage.fetchRectsForVisibleContent() instead.
• Removed ReadingSystemEngine.setOptions(). Pass options when calling new ReadingSystemEngine() instead.
• Removed IReaderDocument.fetchContentBlocks(). Please use IReaderDocument.fetchContentBlockTree() instead.
• Removed IReaderDocument.fetchLocatorForContentBlockData(). Please use fetchContentBlockTree(), and use IContentBlock.getLocator() instead.
• Removed the whole module colibrio-readingsystem-indexengine. Please use the API available at ReadingSystemEngine.getReaderDocumentSearch() instead.

Bugfixes

• Fixed an issue with pinch-zooming in PDFs containing many links. Previously, if one finger was on a link, pinch-zooming failed.
• Fixed an issue with publication CSS stylesheets not working on iOS 26.2 Beta 2.