DOCSEARCHbyAlgolia
Submit Docs

Readium Web SDK

repository·develop·Indexed 40 days ago

https://github.com/readium/ts-toolkit

A next-generation SDK for handling publications within web applications. It provides core navigation, resource control, and visual overlay capabilities through modules like the Publication Parser, Navigators (HTML, Audio, Image), the Recognizer for gestures, and the @readium/decorator for text highlights and anchored elements.

Tokens
89.6K
Snippets
232
Records
319
Agent score
99%

What's inside Readium Web

  1. Overview of the @readium/navigator package

    develop
    The @readium/navigator package provides a web-based navigator implementation following the Readium Navigator specification. It is designed for web platforms and is adapted from the Readium Kotlin toolkit to meet web-specific requirements.

  2. Overview of @readium/navigator-html-injectables

    develop

    The @readium/navigator-html-injectables package provides a way to access and control a resource from a navigator within any modern browser or embedded browser frame. It is designed to work both inside reflowable (X)HTML content and in external JavaScript environments.

    This package serves as a web-based replacement for the JavaScript stubs used in mobile SDKs (such as the Kotlin toolkit).

    Important Compatibility Note: Because this package is often used within mobile app WebViews, which may run on outdated web engines, you must ensure your final build is compatible with older browsers beyond standard modern web support.

  4. Supported Publication Formats

    develop

    Readium Web supports three primary publication formats, each with different rendering and playback characteristics:

    • Reflowable: EPUB content with an adaptive flow. Content is fragmented, and overflow is handled via pagination or scrolling. It supports dynamic pagination where page dimensions are bound to the view size.
    • Fixed Layout: EPUB content presented as fixed pages (e.g., double-page spreads) with a fixed flow.
    • Audiobook: Non-visual reproduction where progression is mapped to time points rather than visual points. Includes playback controls (play/pause) and track-based progression.

  5. Understand the Readium Web User Interface components

    develop

    The Readium Web user interface is composed of several functional areas designed for reading and navigation:

    Action Bar

    Located at the top, providing global controls:

    • Exit / Home button: Returns to the previous state or home screen.
    • ToC menu: Opens the Table of Contents.
    • Bookmarks button: Accesses saved bookmarks.
    • Settings menu: Opens user preferences.
    • Full screen button: Toggles full-screen mode.

    Navigation Controls

    Used for moving through the publication:

    • Next/prev step (page): Incremental page navigation.
    • Next/prev section (chapter): Jumps between chapters.
    • Hold/resume navigation (play/pause): Controls automated navigation (e.g., text-to-speech or auto-scrolling).

    Navigation Display

    Provides different views for the Table of Contents:

    • Tree list: A hierarchical view of the publication structure.
    • Flat list: A linear view of all sections.

    Metadata and Progression

    • Metadata display: Shows the publication title and author.
    • Progression display: Includes a progress slider, current location/position, and page numbering.

    Settings Menu

    • Provides access to various user settings via switches.

  6. Understand the Readium Web toolkit philosophy

    develop

    The Readium Web project is not a full-featured application, but a toolkit designed to help developers build publication viewer applications based on the Readium Architecture.

    When using this toolkit, you should expect:

    • A Foundation, not a finished product: It provides core functionality common to all publication viewers and serves as a framework for advanced features.
    • Modular Design: It uses well-defined interfaces and APIs, allowing you to swap basic implementations with full-fledged replacements.
    • Decoupled UI: The UI is component-based and implementation-agnostic, meaning you can change the theme, look, and feel without refactoring the core logic.
    • Readium Compatibility: It is designed to process Readium Web Publications, utilize Readium shared modules, and work both with and without Readium Publication Servers.
    • Extensibility: The architecture is built to allow developers to add new functionality without needing to refactor existing code, preventing the need for divergent forks.

  7. Accessibility and Interaction Features

    develop

    Readium Web provides built-in support for accessibility and standard reading interactions:

    Accessibility

    • WCAG Compliance: Supports levels A, AA, or AAA.
    • Interface: UI accessibility, keyboard shortcuts, and screen reader support.
    • Content: Accessibility of the actual content material.

    Interaction

    • Gestures: Page-turn gestures and zoom gestures.
    • Navigation: Table of contents, bookmarks, and tap zones (left/center/right).
    • Actions: Selection actions and opening external links.

  8. Understand the Readium Web Architecture

    develop

    Readium Web provides guidelines and modules for implementing the Readium Architecture on web-based platforms. It is designed to work with the Open Web Platform, supporting offline use, low-spec clients, and assistive technologies.

    Key architectural components include:

    • Models: Representing the Publication, Locators, and Injectables.
    • Publication Parser: Converts a manifest into an in-memory model.
    • Navigators: Handle content progression (HTML, Audio, Image).
    • Decorator: Handles visual overlays like text highlights and anchored elements.
    • Recognizer: Manages user interactions, gestures, and text selection.

  9. Identify vulnerabilities in Web Publication protection

    develop

    When designing or implementing protection for Web Publications, be aware of several inherent vectors that allow for the over-sharing or unauthorized extraction of content. These vulnerabilities fall into several categories:

    Access and Discovery

    • Uncontrolled Access: Manifests and resources may be accessible without authorization, susceptible to replay attacks, or optimized for grabbing via multi-threaded scripts.
    • URL Discovery: Hyperlinks can reveal target URLs through user interaction (hover, touch, focus), and resource URLs may be predictable.

    Content Extraction

    • Textual Content: Users can select and copy text using standard mouse/keyboard interactions.
    • HTML Markup: The Web inspector/debugger and the browser "view source" feature provide direct access to HTML, CSS, and JavaScript.
    • Image Content: Images can be dragged-and-dropped, copied via context menus, or fetched directly if the URL is known.

    Network and Cache Vulnerabilities

    • Direct Fetching: Resources can be obtained via tools like curl or wget without appropriate HTTP referer headers, or intercepted by HTTP proxies.
    • Browser Cache: Non-obfuscated resources can be extracted directly from the browser's cache.

    Miscellaneous

    • Printing: Browser print features allow for easy export of individual documents.
    • Screen Capture: Tools like Snagit or Camtasia, combined with OCR, can be used to recreate publication content.

  10. Understand limitations of client-side content protection

    develop

    When implementing content protection using the Readium Navigator, be aware of the following limitations:

    1. Bypass Risk: Client-side protection can be bypassed by determined attackers.
    2. Defense in Depth: Protection features should be used in conjunction with server-side protection for robust security.
    3. UX/Accessibility Impact: Some protection features (like disabling copy or print) may negatively affect user experience and accessibility.

  11. How the Timeline is built and structured

    develop

    The Timeline is a lazy singleton on the Publication object. It is built using the reading order as the source of truth. Every item in the reading order becomes exactly one top-level TimelineItem.

    Title Resolution Logic:

    1. The reading order item's own title.
    2. A TOC entry whose href matches the start of the resource.
    3. A single fragment-based TOC entry referencing the resource.
    4. A placeholder like Resource N.

    Hierarchy:

    • The TOC is used to enrich items, not to create new top-level entries.
    • TOC entries that don't match a reading order item are ignored.
    • All TOC entries referencing a reading order resource become flat children of that item in declaration order. The API does not currently reconstruct parent-child relationships from the TOC hierarchy itself.

  12. Configure DecorationStyle with built-in types

    develop

    The DecorationStyle defines how a decoration looks. You can use BuiltinDecorationStyle by specifying a type from DecorationStyleType.

    Available DecorationStyleType values:

    • Highlight: Background-color overlay (default).
    • HighlightUnderline: Background-color overlay and underline (used for selection/focus).
    • Underline: Line drawn beneath the text.
    • Strikethrough: Line drawn through the middle of the text.
    • Outline: Border drawn around each text box.
    • TextColor: Changes text color directly (requires CSS Highlight API; falls back to wrap width in older browsers).
    • Mask: Dims everything outside the selection rects (use width: Page for block-level behavior).
    • Template: Custom HTML template (see HTMLDecorationTemplate).

    Layout and Width options:

    • DecorationLayout: Boxes (one element per line, default) or Bounds (single element covering the whole range).
    • DecorationWidth: Wrap (fits text exactly, default), Viewport (stretches to full viewport width), Page (fills the anchor page), or Bounds (fills the bounding region of all boxes).
    const style: BuiltinDecorationStyle = {
  type: DecorationStyleType.Highlight,
  tint: "#ffff00",
  layout: DecorationLayout.Boxes,
  width: DecorationWidth.Wrap,
  enforceContrast: true
};