Web framework 3

This version is covered by warranty support until 2026-01-31.
It will however not be updated with new features.

3.12.2 (2025-05-16)

API Docs

Bug fixes

Fixed an issue where tables containing <colgroup> could sometimes cause blank pages during reflow.

3.12.1 (2025-03-06)

API Docs

Bug fixes

Fixed an issue where TTS playback could not be resumed after being paused due to interruption from a screen reader.
Fixed a memory leak issue.
Fixed an issue with the page shadow animation in the Stack Renderer in iOS 18.3.
Fixed an issue where IVisiblePageData.boundingClientRect sometimes was assigned undefined.
Fixed a bug where the selectionChanged engine event would not fire if ReaderView.setScriptedContentDocumentEventHandlersEnabled(false) had been called.
Fixed a bug where CSS background images did not load if the selector for the style rule contained :before of :after pseudo selectors.

Improvements

Improved building TTS SyncMediaTimeline performance.

3.12.0 (2024-09-12)

Bug fixes

Fixed an issue where VoiceOver was able to move focus into offscreen/hidden content on iOS 18.
Fixed a bug where URLSearchParams did not work when passing an URLSearchParams to the constructor.
Setting the option ISyncMediaTtsTimelineContentTransformationOptions.normalizeQuotationMarks to true now converts all Unicode single quotation mark characters to the U+0027 Apostrophe (') character, while all Unicode double quotation marks are still converted to the U+0022 Quotation mark (") character.
Fixed a bug where the “keydown” engine event’s modifiers.shift always was false, even if shift was pressed.

3.11.0 (2024-05-22)

Important Security Fix

CVE-2024-4367
This release includes a crucial security fix for PDF.js. This vulnerability allowed arbitrary JavaScript execution through malicious PDF files. We strongly advise updating your reader applications as soon as possible to mitigate this issue. For more details, please refer to this article.

If you do not load PDF files with Colibrio, you are not affected by this vulnerability.

Bug fixes

Fixed an issue where CSS @import declarations could cause the framework to get stuck in an infinite recursion if an imported stylesheet contained an @import declaration pointing to itself.
Fixed an issue where IReaderPublicationOptions.preventDragAndDropActions had the wrong default value.
Fixed a bug where the reading position might not be accurate when navigating to a locator range that partially intersected with the visible content.
Fixed an issue where EPUBs with an NCX navigation document would fail to load in some cases.

3.10.1 (2024-03-15)

Bug fixes

Fixed an issue where EPUB MediaOverlays and W3C Audiobooks could not be played on iOS 17.4.

3.10.0 (2024-03-07)

Bug fixes

When streaming EPUBs over slow connections, initial aspect ratio calculations might take a long time, and led to navigation to wrongfully time out. In this version the engine instead waits for the aspect ratio calculations to finish.
Importing colibrio-polyfill-webanimation into your app will now force the polyfill implementation to be used in Desktop Safari. This solves animation issues and glitches introduced in Safari 17.3.

New features

Added a new option, ISingleDocumentScrollRendererOptions.scrollBarPosition that allows you to choose if the scroll bar of a SingleDocumentScrollRenderer should appear right next to the document content or at the edge of the ReaderView.
Added a new option, IEpubContentProcessingOptions.skipUnusedImagesInScriptedPublicationCss in IEpubReaderPublicationOptions. If set to true, background-images defined in a scripted publication CSS that aren't used by any element in the initial DOM will be skipped. This can significantly reduce load time and memory usage for some publications. This option should be set to false if the publication contains scripted content documents that inserts elements into the document dynamically.
Added a new option, IPublicationStyleOptions.disableCssAnimations. If set to true, CSS animations and transitions are disabled in the publication.

3.9.0 (2023-12-08)

Bug fixes

Fixed an issue where floating elements with negative margins could overlap other publication content in reflowable EPUBs.
Fixed an issue where the aspect ratio of a PDF publication could be wrong.
Fixed an issue where, in the onConfigureUtterance callback in the WebSpeechTtsSynthesizer, the TtsUtteranceData.nodeData pointed to the parent of an <img> node instead of the <img> itself.
Fixed an issue where content documents with media type application/html was parsed as XHTML instead of HTML.
Fixed issue where TTS utterances were not preloaded correctly during playback.
Fixed a bug where PDFs could not be loaded with a RandomAccessDataSource if the fetchChunk() method returned a ReadableStream and the option IPdfPublicationOptions.enableDeterministicChunkRequests was set to true.

New features

New includePreContentBlocks and includeMathMlContentBlocks options added to IEpubContentBlockOptions.
Please note that adding these extra ContentBlock types will invalidate existing ids that you may have cached.
math element's alttext is now read aloud by the TTS.

3.8.0 (2023-10-02)

Bug fixes

Fixed a bug that prevented Youtube iframes to enter fullscreen
Fixed a bug that could cause the initial ReaderView.goTo() or ReaderView.goToStart() to fail with the error message No renderer has been set using ReaderView.addRenderer() even though a renderer had been added.
Fixed an issue causing ContentLocaiton.fetchNavigationItemReferences to return an error on very old versions of Chrome.
Fixed an issue where iOS Safari failed to play large audio files.
Added the option ISyncMediaTtsTimelineContentTransformationOptions.normalizeQuotationMarks. If enabled, all special unicode quotation mark characters are replaced with the standard U+0022 Quotation mark ("). This may increase compatibility with some TTS Voices which may not work correctly otherwise. Specifically, non-english TTS voices on iOS 17.0 may skip segments completely when special quotation mark characters are encountered. This new option defaults to true.

New features

Added the engine event syncMediaSegmentFinished. This event fires when a SyncMediaPlayer finishes playback of a segment.

Improvements

Improved performance when loading reflowable EPUBs with large cover images.
All Colibrio modules can now be imported in NodeJS without throwing any errors. Note however that the Colibrio modules are targeted for the Web platform and requires Web APIs to be available. Calling any Colibrio framework method from NodeJS is unsupported at this time and the behaviour is undefined.

3.7.0 (2023-07-07)

Bug fixes

When setting the ISyncMediaTtsContentBlockRendererOptions.wordHighlightEnabled to false, while the TTS are playing, the highlight is removed from active word.
Fixed an issue where scripted documents would not be able to load in very old versions of Chrome/Android webviews.
Fixed an issues where IReaderViewTransformManager methods zoomToClientPosition and zoomToClientRect did not work in very old versions of Chrome/Android Webview.
Fixed an issue in Safari where pausing and resuming a SyncMediaPlayer with a TTS SyncMediaTimeline caused it to continue speaking from the wrong position and highlighting to stop working.
Fixed compatibility issues when using third-party polyfills for the URL API.

New features

Added a new event, ISwipeNavigationGestureProgressEngineEvent. This will fire during swipe navigation and contains the pending navigation action, i.e. if the outcome of the swipe navigation is next page, previous page or stay on current page. It also contains data representing page swipe animation progress and related pointer movement.
Added support for loading a font from a URL. This is done by specifying srcUrl in IPublicationStyleFontFace.
Added the option IEpubReaderPublicationCustomCssOptions.enableNormalizeCss controlling if the CSS reset/normalizer "normalize.css" should be injected into all reflowable EPUB content documents.

3.6.0 (2023-06-02)

Bug fixes

Scripted EPUBs adding <video> or <audio> elements with <source> child elements should now work correctly.
Fixed an issue where SyncMediaPlayer.getApproximateElapsedTimeMs() in some cases returned NaN when at the end of the timeline.
Fixed an issue where calling ReaderView.setReaderDocuments([]) with an empty list, caused wrong aspect ratio to be used when later calling the method with a non-empty list.

New features

Added includeContentLocationInPointerMoveEvents in IEpubReaderPublicationOptions and IPdfReaderPublicationOptions controlling if "pointermove" engine events should include the contentLocation property.
Added a new function, EpubReaderPublication.fetchContentLocationFromHref. This allows you to retreive a content location for an href like “../chapter2.xhtml#title-2".
Added nodeData to ITtsUtteranceData. This lets you investigate the Node data from where the TTS utterance was generated.
Added support for font variants, i.e. font-weight, font-stretch and font-style, in the IPublicationStyleFontFace option.
Added button to IMouseEngineEvent. On pointerdown, pointerup, and click , this property indicates the device button whose state change caused the event to fire.
Added support for tree-structural pseudo-classes in publication css.
Added a new method SyncMediaPlayer.setPlaybackRange(). Use this new method to restrict playback to a specific timeline range. Added the engine events syncMediaRangeEndReached and syncMediaRangeRemoved related to playback ranges.
Added the option highlightFirstWordOnSegmentActive in SyncMediaTtsContentBlockRendererOptions. Set it to true to highlight the first word immediately when a segment becomes active.

Improvements

Improved ISyncMediaTimeline.fetchTimelinePosition() for pre-paginated EPUBs when there is a media segment matching a parent node of the passed locator.

3.5.0 (2023-04-04)

Bug fixes

Fixed an issue where syncMediaSeeked event would not fire.
Fixed an issue where calling ContentPositionTimeline.fetchContentLocationAsRange(pos, pos + 1) with a position at the start of a ContentDocument would return a collapsed ContentLocation instead of a range.

New features

Added the new option contentBlockOptions.disableDefaultAttributeFiltering to EpubReaderPublicationOptions. If set to true, the default attribute filtering is disabled and all attributes will be available in the ContentBlocks.
Added the new option ReaderViewOptions.rendererTransitionAnimationDurationMs. A renderer transition happens when the activeRenderer changes, or a refresh() call requires the activeRenderer to re-layout its content. Normally the renderer transition will start when visible content has finished rendering by fading it in over the old content. This new option controls the duration of the fade-in animation. The default value is null which will use a platform specific duration. Setting this value to 0 disables the animation.
Added the new option ReaderViewOptions.emitPointerMoveEventsOnHover. When set to true, “pointermove” engine events will be emitted when moving the mouse without pressing any button.

Improvements

Improved ZIP uncompress performance for Chrome and Edge.
PageProgressionTimeline now only recalculates on ReaderView and publication layout changes. Calling readerView.refresh(true) will also cause the PageProgressionTimeline to recalculate.

3.4.0 (2023-02-23)

New features

IEpubContentPositionTimelineOptions has a new option fetchWithLowPriority. If set to true, all async operations in the IContentPositionTimeline will be executed when no other more prioritized tasks, like animation or document rendering, are running..
ISyncMediaTimeline has a new method called fetchTimelineRange() that can be used to fetch the corresponding ISyncMediaTimelineRange for a Locator or ContentLocation.
IVisiblePage has a new method, getBoundingClientRect(), returning the bounding DOMRect of a rendered page.
A new methodReaderViewTransformModel.zoomToPublicationViewportRect translates and scales the publication so that the rectangle is centered in the ReaderView. The method uses the publication viewport as coordinate system.
Safari requires Audio playback to be initiated on a user generated event, such as a click. Because of this, the Colibrio Reader's SyncMediaPlayer needs to create a pool of audio elements within such a user generated event. By setting prepareSyncMediaAudioElementsOnFirstUserInteraction in the ReadingSystemEngineOptions.plaftformWorkaroundOptions object to true, Colibrio Reader Framework will prepare audio elements on first user interaction.
Added support for remote http sources for audio and video elements in non-scripted content documents. Use IEpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions to allow these sources in the CSP.
When an element is fragmented across pages, a new option IEpubReflowPluginOptions.removeTopMarginsOnFragmentedElements determines if the top margin of the fragmented element should be carried over to subsequent pages.
Added Engine Events that can be used for tracking the state of <audio> and <video> elements inside publications. See the documentation in IEngineEventTypeMap for more information. The new event names are:
- mediaElementCurrentTimeChanged
- mediaElementInsideVisiblePages
- mediaElementOutsideVisiblePages
- mediaElementPaused
- mediaElementPlay
- mediaElementReady
- mediaElementSeeked
- mediaElementWaiting
IReaderPublicationOptions has a new option preventDragAndDropActions. If set to true, all drag-and-drop actions originating from the publication content is prevented.

Bugfixes

Fixed an issue where the reading position would sometimes be slow to update from sync media playback.
Fixed that ReaderView.fetchRectsForVisibleContent sometimes merged too many lines.
A bug in chrome removed whitespace from clipboard data. To work around this, we changed how we get the copied text.
When any of the createSyncMediaTimeline results in a ISyncMediaTimeline instance that have no segments, the returned Promise is rejected with an error where errorType is set to INVALID_SYNC_MEDIA_TIMELINE. Previously, empty SyncMediaTimelines were allowed but caused various errors later when used with a SyncMediaPlayer.

Improvements

Added a new engine event, licenseReadingSessionPending that will be fired if there is a problem connecting to the license server. This event allows you to more quickly diagnose issues related to for example CSP policies that block access to the server.

3.3.0 (2022-11-22)

New features

Added a new password option to IPdfPublicationOptions. This can be used to load password protected PDF publications.
Added a new method ReaderView.fetchRectsForVisibleContent. This method returns a result set containing the positions and dimensions for all text line boxes and replaced elements, such as image and video elements. You can pass a Locator to the method to only return rects that are inside that location.
This data can be used to implement reading rulers, popovers for a text selection or an element, and more.

Bugfixes

Fixed an issue where ReaderView.canPerformGoTo incorrectly returned false.
Due to issues with media streaming in iPadOS, the IEpubReaderPublicationOptions.enableMediaStreaming option is now ignored for that platform.
Fixed a timing issue where visiblePages were not updated when the visibleRangeChanged event was fired. The visiblePages and visibleRange are now in sync.

3.2.0 (2022-10-04)

New features

Added EpubReaderPublicationOptions.splitTextOptions. This option object allows you to enable and configure splitting of very large text nodes in EPUB publications. When a single text node contains several thousand characters, enabling this option will reduce the time it takes to reflow such a publication.

Bugfixes

Fixed issues causing text and images to look blurry when zooming into publication content on iOS.
Fixed an issue where SpreadSwipeRenderer and SinglePageSwipeRenderer caused horizontal scrollbars unless overflow: hidden was used on the ReaderView element.

Improvements

Improved performance when pinch-zooming the ReaderView and when animating the ReaderView using the ReaderViewTransformManager.

3.1.1 (2022-09-15)

New features

When a scripted EPUB content document tries to open a URL using window.open, the reading system will now emit a navigationIntent engine event with that URL.

Bugfixes

Fixed an issue where panning with the mouse in PDFs did not work as expected.
window.devicePixelRatio is now modified in fixed-layout EPUB content documents so that the scaling applied to the content document within the ReaderView is taken into account. This fixes issues when scripted content documents calculate the width and height to use for <canvas> elements.
Fixed an issue where calling readerView.setOptions() in some cases did not work when modifying various gestureOptions.panZoom or gestureOptions.swipeNavigation options.
Fixed an issue where readerDocumentSearch.createTextQuery("") returned a search result containing all positions in the ReaderDocuments. Now, createTextQuery("") returns an empty search result.
Fixed an issue where activeTransformChanged sometimes fired even if the active transform did not change.
Fixed an issue where setting maxPanOffsetHorizontal and maxPanOffsetVertical in readerViewOptions.gestureOptions.panZoom had no effect.

3.1.0 (2022-09-09)

Major new features

ReaderDocumentSearch

This release includes new APIs for text search and highlighting search results in the ReaderView. You can access the new search API through readingSystemEngine.getReaderDocumentSearch().

This example shows how to search for the string “Paris” in all ReaderDocuments in a publication:

TYPESCRIPT

const readerDocumentSearch = readingSystemEngine.getReaderDocumentSearch();
const searchQuery = readerDocumentSearch.createTextQuery("Paris");
const resultIterator = query.execute(readerPublication.getSpine());

// Take the next 10 search result items from the iterator.
const firstTenResults = await resultIterator.take(10);

// Take all the remaining search result items from the iterator.
const remainingResults = await resultIterator.takeRemaining();

You can now more easily highlight search result items in the ReaderView by using a IReaderViewSearchAgent. A IReaderViewSearchAgent uses a IReaderDocumentSearchQuery to search the visible ReaderDocuments in the ReaderView. For each found search match, the agent creates a ReaderViewAnnotation.

The agent will continue to search, add and remove ReaderViewAnnotations as necessary when the ReaderView is navigated.

TYPESCRIPT

// Create the annotation layer used for highlighting search results.
const annotationLayer = readerView.createAnnotationLayer('searchHighlights');
annotationLayer.setLayerOptions({
    layerStyle: {
        'mix-blend-mode': 'multiply',
    },
});
annotationLayer.setDefaultAnnotationOptions({
    rangeStyle: {
        'background-color': 'lightblue',
    },
});

const readerDocumentSearch = readingSystemEngine.getReaderDocumentSearch();

// Create the query
const textQuery = readerDocumentSearch.createTextQuery('Paris');

// Create a search agent that will highlight all matches using the annotation layer.
const searchAgent = readerDocumentSearch.createReaderViewSearchAgent(annotationLayer);
searchAgent.setSearchQuery(textQuery);

See the API Docs for IReaderDocumentSearch for more information.

Breaking changes

The engine events click and dblclick now correctly maps to the type IMouseEngineEvent instead of IPointerEngineEvent. This was an error in the Typescript definitions file. The actual data emitted on those events has always conformed to IMouseEngineEvent.

New features

IEncryptionMethod.decrypt now takes a third parameter IXmlEncryptionEntry containing all information from the EPUB’s encryption.xml file related to the resource being decrypted. This makes it easier to implement support for additional DRM solutions.
IReaderViewTransformManager: New methods added:
- zoomToClientRect : Allows you to zoom to a rectangle.
- zoomToPublicationViewportPosition: Allows to you to zoom to a position within the publication viewport. The publication viewport is the rectangle that contains the visible pages.
- zoomToClientPosition: Allows you to zoom to a position in client space, meaning you no longer need a pointer event to zoom. Replaces zoomToPointerEvent which is deprecated.
IReaderViewTransformManager: All transform changes can now be animated by passing a ITransformAnimationOptions object to any of the different zoom methods. You can specify your desired easing function and the duration of the animation.
It is now optional to specify publicationToken in the IReadingSessionOptions when loading a publication with ReadingSystemEngine.loadPublication. If not specified, the framework will calculate an obfuscated publicationToken.
INavigationIntentEngineEvent now contains a readerDocument property indicating from where the navigation intent originated.
IMouseEngineEvent (and its sub-types) now contains a buttons property that can be used to detect which mouse buttons that are pressed.

Deprecated APIs

The following APIs still work, but will be removed in an upcoming major version of the framework:

IReaderViewOptions.gestureOptions.panZoom: The following options have been deprecated:
- maxPanOffsetVertical
- maxPanOffsetHorizontal
- maxScaleFactor

Please set these options using IReaderViewOptions.transformManagerOptions instead.

IReaderViewTransformManager: zoomToPointerEvent has been deprecated. Please use zoomToClientPosition instead.
colibrio-readingsystem-indexengine: This module has been deprecated including all its types. Please use ReadingSystemEngine.getReaderDocumentSearch() instead.

Bugfixes

IReaderViewAnnotationLayer: Fixed issues causing some ContentLocation to not render correctly.
IReaderViewAnnotationLayer: The engine event annotationContextMenu option now works as expected on iOS and iPadOS.
IReadingSystemEngine: Loading the same publication twice now throws an Error.
ISyncMediaPlayer: The optional parameter snapToVisiblePagesBoundary now works as expected when calling seekToNextSegment and seekToPreviousSegment .
ISyncMediaPlayer: getPlaybackRate() now returns the correct value.
<a> tags without href attribute no longer generates navigationIntent events.
IReaderViewOptions: Performing swipe gestures with the mouse now works correctly when gestureOptions.swipeNavigation.pointerTypes.mouse is true. However, you must also call IReaderView.setContentSelectionEnabled(false) as the gesture otherwise interferes with content selection and image drag-and-drop.
IReaderViewOptions: gestureOptions.panZoom.maxPanOffsetHorizontal and gestureOptions.panZoom.maxPanOffsetVertical now works as expected for all paginated renderers.
IReaderViewGestureManager: Programmatically panning and zooming now works without an initial click or tap on the ReaderView.

3.0.0 (2022-06-13)

Breaking changes

IResourceRequestOptions.range changed type from IByteRange to IByteRangeRequest, where end property is optional. When omitting the end property, the byte range ends at the end of the resource.

New features

You can now pass a callback when creating a new WebSpeechTtsSynthesizer . It allows you to modify SpeechSynthesisUtterance objects before they are sent to the speechSynthesis engine, such as setting the voice or any other attribute you'd like to change.
When appending additional IReaderDocuments to the ReaderView using IReaderView.setReaderDocuments(), the ReaderView will now more gracefully append those documents and internally trigger a “refresh” instead of clearing the ReaderView and forcing you to call goTo(). This new behavior allows you to avoid the “flash of white” that would occur otherwise.

Bugfixes

Fixed an issue where TTS stopped working on sentences taking longer than 10 seconds to speak on Chrome for Android.
Fixed an issue where the TTS voice used could suddenly change after a couple of sentences had been spoken.
Fixed an issue where customizing the palette of an EUB publication using PublicStyleOptions.palette could cause text to become transparent if the publication’s CSS contained invalid CSS color values.
ReaderView.getReadingPosition() now returns “resolved” locators for EPUB in cases where ReaderView.goTo() was called with an incomplete EPUB CFI that was resolved using for example XML ID assertions.
Fixed a rare issue with EPUB Media Overlays where a <text> element in a .smil document could contribute to the SyncMediaTimeline for a specific content document, even if that content document’s manifest item in the .opf file did not reference the .smil file with the media-overlay attribute. This was never allowed by the Media Overlay specification and when this is encountered, the <text> element is ignored and an error is logged to the console instead.

3.0.0-rc.4 (2022-05-16)

New features

The TTS SyncMediaTimeline no longer adds the text “Media element” or “Image alt text” when a media element is encountered. Instead, when you call ReaderPublication.createTtsSyncMediaTimeline(), you can set what text to prepend by setting the option contentTransformationOptions.imageAltTextPrefix.
Added IReaderPublicationOptions.preventDefaultContextMenu. If set to true, the reading system will prevent the default "right-click" and "long-press" context menus to be shown for publication content. Please note that this option does not work on iOS and iPadOS. There are no Web APIs available to prevent the context menu from being shown on those platforms. A workaround is to disable user content selection with ReaderView.setContentSelectionEnabled(false).
Added IReadingSystemEngineOptions.platformWorkaroundOptions.useTouchEventsOnIos. Set this option to true to force "touch" events to be used on iPhones and iPads instead of "pointer" events. This option should be enabled when integrating the Colibrio Reader Framework with a Flutter app.
Added initial support for ContentBlocks.getMarks(). This method returns ContentBlockMarkData items that further describes parts of the text content, such as bold or italic text.

Bugfixes

Fixed an bug causing ReaderView.getVisibleRange() to return an incorrect ContentLocation when using FlipbookRenderer or SpreadSwipeRenderer while one of the visible pages was an “intentional empty page”.
The EPUB package meta element attribute rendition:spread now maps the deprecated value portrait to both as specified in the EPUB specification.
Fixed an issue with ContentPositionTimeline.fetchTimelineRange for EPUB. When passing a ContentLocation range that ended just before a media element, the returned result incorrectly included the media element.

3.0.0-rc.2

New features

Create ContentPositionTimeline instances quickly

Creating ContentPositionTimeline instances can take a significant amount of time on large publications. You can now work around this by calling ContentPositionTimeline.toSerializedData() and saving the returned data. The next time you create a ContentPositionTimeline, you can pass that data with IEpubContentPositionTimelineOptions.serializedData to create the ContentPositionTimeline almost instantly.

The data returned by ContentPositionTimeline.toSerializedData() is a base64 encoded string and is usually just a few hundred bytes large. It is unique to one publication and can safely be shared among clients.

When you pass serializedData to readerPublication.createContentPositionTimeline(), it will be validated to ensure it has the correct format and that it was created for the same publication. If validation fails, the serializedData is discarded and recalculated again.

Other new features

Added the static method WpPublication.createFromResourceProvider().
Added WpPublication.getManifest().getValidationErrors(). Use it to get a list of errors that were found when the WP Publication Manifest was processed.
Added ISyncMediaAudioRendererOptions.alignedSegmentSeekThresholdMs. This option controls how the SyncMediaAudioRenderer should treat gaps between two consecutive segments. If you hear many clicks, and cutoff words when playing back the audio in the publication, try increasing the value of this option.
Added ISyncMediaTimeline.getApproximateOffsetMs(). Use it to get the approximate offset into the timeline in milliseconds from an ISyncMediaTimelinePosition.
Added ISyncMediaTimeline.getTimelinePositionFromApproximateOffsetMs(). Use it to get the timeline position that most closely matches an offset into the timeline.
Added the EngineEvent rendererScrollHeightChanged. It fires when a scrolling renderer's scrollHeight has changed, either due to navigation or due to scripts inside a document changing the height of the document.

Breaking changes

Removed IXmlEncryptionEntry.cipherValueBase64.
Deprecated IZipArchiveInformation.sha1signature. Please use IZipArchiveInformation.signature.sha1Hash instead.
Deprecated IPublication.getMediaType(). Please use IPublication.getType() instead.
Deprecated ISyncMediaPlayer.getApproximateElapsedTimeMsForTimelinePosition(). Please use ISyncMediaTimeline.getApproximateOffsetMs() instead.
Renamed ISyncMediaTimelinePositionData.offsetMs to offsetWithinSegmentMs.
Renamed ISyncMediaTimelinePosition.getOffsetMs() to getOffsetWithinSegmentMs().

Bugfixes

Fixed an issue that in some cases caused EPUB Media Overlay playback to stop working on iOS 15.
Fixed an issue where PDF pages sometimes rendered as blank pages if the rendering was interrupted by a ReaderView.refresh() or ReaderView.setOptions().
Fixed-layout EPUBs and PDFs are now centered in the ReaderView when ReaderViewOptions.ignoreAspectRatio is true.
Fixed an issue where <video> elements could shrink too much if it was wrapped inside a container element with a fixed height.
The playsinline attribute is now preserved for <video> elements. Previously it was always removed.
Fixed an issue in WpAudiobookReaderPublication where ContentLocation.fetchNavigationItemReferences() returned to many “intersecting” items.
Fixed an issue where links in certain PDFs did not work.
Fixed an issue that caused some PDFs to never finish rendering and show a loader indefinitely.
Improved playback of EPUB Media Overlays when there are small seeks between segments.
Fixed an issue where EPUBs rendered with the wrong aspect ratio if document tag <meta name="viewport" ... contained extra spaces inside the content attribute.
Fixed an issue where IEngineEventMediaResource.getResourceUrl() could return incorrect URLs if loading the EPUB publication with a ResourceProvider that fetched resources over http .
Calling ReaderView.setSyncMediaPlayer() will no longer cause a synchronization event to fire if the ReaderView and the SyncMediaPlayer are already in sync.
Fixed an issue where EPUB Media Overlay playback could stall if there was a segment that did not reference an audio file.
Fixed an issue where IEngineEventMediaResource.createUrl() could return non-working URLs when clicking images in EPUBs that had nested iframes.
Calling ReaderView.renderTo() with an element where its position style is static will now cause it to set position to relative as specified in the API docs.
Corrected the parameter type for BrowserDetector.isOS() so the method correctly recognized MacOS.

3.0.0-rc.1

New major features

The Colibrio Reader Framework 3.0.0 adds support for W3C Audiobooks format: https://www.w3.org/TR/audiobooks/

You can load an Audiobook from an Audiobook Manifest file or by loading a packaged Audiobook file (LPF: https://www.w3.org/TR/audiobooks/#audio-packaging ) from the user’s device or from the Web.

The following example code shows how to load an Audiobook that has been packaged into an LPF file and prepare it for playback:

TYPESCRIPT

const wpPublication = await WpPublication.createFromBlob(lpfFile);
const engine = new ReadingSystemEngine({licenseApiKey: 'my-api-key'});
engine.addFormatAdapter(new WpAudiobookFormatAdapter());
const readerPublication = await engine.loadPublication(wpPublication) as IWpAudiobookReaderPublication;
const syncMediaTimeline = await readerPublication.createSyncMediaTimeline(readerPublication.getSpine());
const syncMediaPlayer = engine.createSyncMediaPlayer(syncMediaTimeline);

You can extract Metadata about the Audiobook by using WpPublication.getMetadata() and the Table of Contents using IWpAudiobookReaderPublication.fetchPublicationNavigation().

Locators in Audiobooks uses the t= selector as defined in the the Media Fragments URIs standard: https://www.w3.org/TR/media-frags/ , measuring the number of seconds into the Audiobook where t=0 is at the start of the Audiobook.

NOTE:

This feature is currently in BETA. Expect breaking changes to the APIs related with WpPublication/Audiobooks until the final 3.0.0 release.

Known issues

There is a known bug related to IContentLocation.fetchNavigationItemReferences() affecting ContentLocations for WpAudiobookReaderPublication. Calling this method may result in unexpected navigation items showing up in the result set. Note that this does not affect EPUB or PDF.

New features

You can now disable the pan/zoom reset when navigating a ReaderView by setting IReaderViewOptions.transformManagerOptions.removeTransformOnNavigation to false.
You can now allow non-scripted EPUBs to fetch remote resources such as fonts, videos or images from the Web. To enable this feature, see the option IEpubReaderPublicationOptions.remoteResourcesNonScriptedDocumentsOptions

Breaking Changes

IReaderView.addRenderer() - Responsive view rule behavior has changed. When multiple renderers have been added and the ReaderView automatically picks which renderer to use it will now prioritize renderers that were added with a rule passed to addRenderer(). To keep the old behavior, you will need to explicitly pass a rule that evaluates to true, eg. () => true, to all addRenderer() calls where you previously didn't pass any argument for the rule parameter. Note that renderers added without a rule will still be used by the ReaderView if no renderers with matching rules were added.
IContentDocumentData.mediaType and IContentDocument.getMediaType() can now return null if the media type is unknown.
IReaderPublicationNavigationItemData: isLocatorInPublication has been renamed to isTargetingReaderDocumentInSpine.
IReaderPublicationNavigationItem: isLocatorInPublication() has been renamed to isTargetingReaderDocumentInSpine()

Bugfixes

Fixed an issue where the PageProgressionTimeline failed to be created when loading an EPUB using a custom ResourceProvider that did not provide the size field for ResourceMetadata objects.
When creating an annotation from a text selection, the annotation will now properly highlight the line boxes instead of the containing element.
Fixed an issue when performing range requests to a resource within a ZIP file, the ZipResourceProvider often fetched an extra chunk from the backing RandomAccessDataSource unnecessarily.
ContentLocation.fetchContentBlockTargets() now works with ContentLocations that are ranges.