Release notes Web Framework 3

WARNING

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 or :after pseudo selectors.

Improvements

• Improved building TTS SyncMediaTimeline performance.

3.12.0 2024-09-12

API Docs

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.
• Fixed a bug where the "keydown" engine event's modifiers.shift always was false, even if shift was pressed.

Improvements

• 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.

3.11.0 2024-05-22

API Docs

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

API Docs

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

API Docs

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

API Docs

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

API Docs

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 ContentLocation.fetchNavigationItemReferences to return an error on very old versions of Chrome.
• Fixed an issue where iOS Safari failed to play large audio files.

Improvements

• 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

API Docs

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

API Docs

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

API Docs

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

API Docs

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 method ReaderViewTransformModel.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.platformWorkaroundOptions 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.

Bug fixes

• 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

API Docs

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.

Bug fixes

• 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

API Docs

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.

Bug fixes

• 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

API Docs

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.

Bug fixes

• 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

API Docs

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:

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.

// 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(), zoomToPublicationViewportPosition(), zoomToClientPosition() (replaces deprecated zoomToPointerEvent()).
• 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.

Bug fixes

• 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

API Docs

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.

Bug fixes

• 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 EPUB 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.