Skip to main content
  • Send to AI

Overview

Repository: gitlab.com/publicala/volpe

Overview​

The "reader," codename Volpe, is a single-page web application (SPA) designed for the sole purpose of enabling users to read, listen to, and interact with content. While content can originate from various formats such as PDF, EPUB, or Audiobooks, all content undergoes preprocessing and optimization before being used within the reader.

The reader is always embedded within a host, referred to as volpe_host. The host is responsible for:

  • Bootstrapping the reader.
  • Providing essential metadata and session details.
  • Acting as a proxy or gateway between the reader and the broader Publica.la platform.

The reader cannot function independently; it must be embedded within a host.

Embedding Methods​

The reader is embedded differently depending on the host type:

  • Web: Embedded using a secured <iframe>.
  • Mobile and Desktop Apps: Embedded using a WebView (platform-specific implementations for iOS, Android, and Electron).

Reader Host Interaction​

Host Components​

  1. reader-host-template.html:

    • Contains an <iframe> element for loading the reader.
    • Initially, the <iframe> does not have an src attribute, allowing controlled loading.

  2. reader-host-manager.js:

    • Responsible for bootstrapping the reader (Volpe).
    • Sends publication metadata and configuration to the reader.
    • Acts as a communication bridge between the reader and the host.

Reader Load Sequence​

  1. The host initiates the loading of the reader's index.html.

  2. When the onload event triggers, the host sends a setHostLocation event to the reader, including the host's location:

    {
      "hostLocation": "window.location.href"
    }
    • This ensures precise communication between the host and the reader using the postMessage API.

  3. The reader continues loading and, once ready, emits a readerInitialized event.

  4. The host listens for readerInitialized and responds with readingSessionData, providing full session details to complete the loading process.

Events and Communication​

Events from Reader to Host​

The reader communicates key events to the host, including:

  1. readerInitialized - Signals that the reader is ready to receive content and configuration.
  2. close - Requests the host to close the reader.
  3. locationChanged - Notifies the host of content position changes.
  4. shareContent - Provides shareable content details for the OS's native sharing UI.
  5. favoriteIssuesToggler - Requests the host to toggle a publication as a favorite.

Events from Host to Reader​

The reader expects the following events from the host:

  1. setHostLocation - Provides the host's URL for accurate communication.
  2. readingSessionData - Provides full session details (user, content, entitlements) after the reader emits readerInitialized.
  3. sessionExpired - Tells the reader the session has expired. The reader displays a modal and blocks further interaction.
  4. goBack - Requests the reader to exit smart zoom or close.
  5. goToPosition - Navigates to a specific position (page for PDF, CFI for EPUB, track + seek for audio).
  6. showToast - Renders a toast notification inside the reader UI.

Audio playback uses a parallel set of external* controls: externalPlayTrack, externalPauseTrack, externalNextTrack, externalPreviousTrack, and externalSeekToPosition. These let the host transport (lock-screen controls, media keys, native players) drive Volpe's audio engine.

The bridge also exposes domain-specific request/response operations on top of the event surface (notes CRUD, analytics tracking, dictionary lookup, translation, TTS synthesis, AI generation). See Plugin Communication Protocol for the full contract.

X

Graph View