Proposal: Cross-platform EPUBView (iOS + macOS)

[grighakobian]

Proposal: Cross-platform EPUBView (iOS + macOS)

Status: Draft
Targets: iOS 15+, macOS 12+
Scope: API surface and architecture

---

Motivation

The current EPUB navigator is built around EPUBNavigatorViewController, EPUBNavigatorViewModel, and a UIKit-only PaginationView.

Over time, the EPUB rendering implementation evolved beyond a generic pagination container. EPUB-specific concerns such as reading preferences and settings resolution, Readium CSS integration, decorations, editing actions, selection handling, location and viewport tracking, resource preloading, JavaScript coordination, and web content lifecycle management are currently implemented across the EPUB navigator stack, including EPUBNavigatorViewController, navigator models, PaginationView, and supporting rendering components.

As a result, EPUB rendering behavior does not have a single owning abstraction. Responsibilities are distributed across multiple layers, making the rendering pipeline more difficult to reason about, test, and reuse independently from the existing navigator implementation.

This proposal introduces EPUBView, a reusable cross-platform rendering component that consolidates EPUB rendering responsibilities behind a dedicated view abstraction.

The goal of this proposal is not to replace EPUBNavigatorViewController or the existing Navigator APIs. Instead, it extracts rendering concerns into a reusable component that can be hosted by EPUBNavigatorViewController, embedded directly in custom applications, or exposed through SwiftUI.

By separating reading semantics from platform rendering, the EPUB rendering stack becomes platform-agnostic. Since WKWebView provides an equivalent API on iOS and macOS, most of the rendering infrastructure can be shared across platforms, enabling macOS support and a unified SwiftUI integration with minimal platform-specific code.

---

Design Overview

Current Architecture

Current Architecture

        EPUBNavigatorViewController
               │
      ┌────────┴────────┐
      ▼                 ▼
EPUBNavigatorViewModel  PaginationView

EPUBNavigatorViewController coordinates both the navigator state and rendering layers. It owns an EPUBNavigatorViewModel responsible for navigation and reading state, while PaginationView is responsible for rendering and pagination.

EPUB-specific responsibilities such as preferences, settings resolution, decorations, JavaScript coordination, viewport tracking, editing actions, and content lifecycle management are distributed across these components and supporting rendering infrastructure.

As a result, EPUB rendering behavior does not have a single owning abstraction.

Proposed Architecture

EPUBNavigatorViewController
        │
        ▼
      EPUBView
        │
        ├── EPUBEngine
        │
        └── EPUBViewRenderer
                 │
                 ▼
            EPUBViewLayout
                 │
                 ▼
      UICollectionView /
      NSCollectionView
                 │
                 ▼
              WKWebView

Layer	Responsibility
EPUBNavigatorViewController	Navigator implementation and application-facing APIs
EPUBView	EPUB rendering surface
EPUBEngine	Reading semantics and state management
EPUBViewRenderer	Platform rendering abstraction
EPUBViewLayout	EPUB-specific layout and pagination behavior
Platform UI	Native scrolling, layout, and input handling

The engine owns reading behavior. The renderer and layout own presentation.

Rendering Strategy

The renderer is built on top of a custom EPUBViewLayout rather than platform-provided flow layouts.

EPUBViewLayout is implemented as a custom UICollectionViewLayout on iOS and a custom NSCollectionViewLayout on macOS. It encapsulates EPUB-specific pagination and positioning behavior while remaining independent from navigation and reading semantics.

The layout supports:

• Horizontal paginated reading
• Vertical scrolling reading modes
• Dynamic switching between scrolling and paginated layouts
• Single-page and synthetic spread presentation
• Leading and trailing page offsets
• First-page offsetting (offsetFirstPage)
• Publication-specific spread positioning
• Custom snapping and pagination behavior
• Future layout extensions without affecting Navigator APIs

EPUBViewRenderer uses EPUBViewLayout as the platform rendering primitive, while EPUBEngine remains unaware of layout implementation details.

---

Components

Type	Visibility	Responsibility
EPUBNavigatorViewController	Public	Navigator implementation
EPUBView	Public	EPUB rendering surface
EPUBEngine	Internal	Reading semantics and state management
EPUBViewRenderer	Public	Platform rendering abstraction
EPUBViewLayout	Public	EPUB-specific layout and pagination behavior
EPUBViewRepresentable	Public	SwiftUI integration

---

EPUBView

EPUBView is a reusable rendering component for EPUB content.

It can be hosted by EPUBNavigatorViewController, embedded directly into UIKit/AppKit applications, or wrapped by SwiftUI.

All APIs are @MainActor.

public final class EPUBView: PlatformView {

    /// The EPUB publication being rendered.
    public let publication: Publication

    /// Reading order driving pagination.
    public let readingOrder: ReadingOrder

    /// Receives navigation, viewport, selection, and lifecycle callbacks.
    public weak var delegate: EPUBViewDelegate?

    /// Initialization-time renderer configuration.
    public let configuration: Configuration

    /// Navigation and location management.
    public let navigation: Navigation

    /// Reading preferences, Readium CSS configuration,
    /// and resolved EPUB settings.
    public let preferences: Preferences

    /// JavaScript evaluation and messaging.
    public let scripting: Scripting

    /// Resource preloading configuration.
    public let preloading: Preloading

    /// Decorations and highlight management.
    public let decorations: Decorations

    /// Selection menu customization.
    public let editingActions: EditingActions

    /// Pointer and keyboard observation.
    public let inputObservation: InputObservation

    /// Current text selection management.
    public let selection: Selection
}

Usage Examples

Navigation

epubView.navigation.goForward()

await epubView.navigation.go(to: locator)

let location = epubView.navigation.currentLocation

Preferences

let preferences = EPUBPreferences(
    fontFamily: .serif,
    fontSize: 2.0,
    publisherStyles: false
)

epubView.preferences.submit(preferences)

JavaScript

epubView.scripting.evaluate(
    "document.title"
) { result in
    ...
}

Decorations

let highlights: [Decoration] = [...]

epubView.decorations.apply(
    highlights,
    in: .highlights
)

Selection

epubView.selection.clear()

---

EPUBEngine

EPUBEngine is an internal, platform-agnostic kernel responsible for:

• Navigation state management
• Locator resolution
• Reading progression tracking
• Viewport tracking
• Preference and settings resolution
• Decoration storage
• JavaScript message routing
• Input observer registration

The engine contains no platform UI dependencies and no direct knowledge of scrolling primitives.

---

EPUBViewRenderer

EPUBViewRenderer is the boundary between the engine and platform UI.

The engine issues logical rendering commands:

• Reload pagination
• Navigate to a spread
• Scroll within a spread
• Attach content views
• Detach content views

The renderer reports logical events:

• Visible spread changed
• Progression changed
• Pagination completed
• User interaction events

Renderer Implementations

Platform	Implementation
iOS	UICollectionView + EPUBViewLayout
macOS	NSCollectionView + EPUBViewLayout

The renderer delegates layout and pagination behavior to EPUBViewLayout.

---

SwiftUI

EPUBViewRepresentable(
    publication: publication
)

The representable is a thin wrapper around EPUBView and uses a coordinator to bridge delegate events into SwiftUI state.

---

Relationship with EPUBNavigatorViewController

EPUBNavigatorViewController remains the primary Navigator implementation and continues to expose the existing Navigator APIs.

This proposal does not introduce a new navigation model and does not deprecate any existing Navigator interfaces.

Internally, EPUBNavigatorViewController may host an EPUBView instance to provide rendering capabilities, but applications can continue using the navigator exactly as they do today.

---

Benefits

• Dedicated EPUB rendering abstraction
• Clear separation between navigation and rendering concerns
• Shared rendering architecture across iOS and macOS
• Platform-independent reading engine
• Improved testability
• Reduced coupling between rendering and navigator infrastructure
• First-class SwiftUI integration
• Reusable rendering foundation for future navigator implementations
• Support for both paginated and scrolling reading modes
• Flexible layout system supporting first-page offsets and custom spread positioning
• No changes required to existing Navigator APIs

[mickael-menu]

Hi Grigor, thanks for the proposal. macOS support and a native SwiftUI navigator are definitely part of our long-term vision, so the intent is very much aligned.

That said, a few concerns before we go further.

On macOS support: This is a worthy goal, but the navigator is the last piece. All other modules need to be made macOS-compatible first. And it's something we'd only take on after shipping v4 with Swift 6 support. So a revised navigator proposal would be premature at this stage.

On design direction: Keeping ⁠EPUBNavigatorViewController is a non-goal. It's already legacy due to UIKit. A future cross-platform navigator would target SwiftUI natively. Two references worth keeping in mind for when the time comes:

• Apple's WebKit for SwiftUI API, which separates rendering (⁠WebView) from behavior (⁠WebPage).
• The new Kotlin Compose navigator in the Kotlin toolkit developed by @qnga. Since SwiftUI and Jetpack Compose are close in spirit, we'll want both toolkits to align where possible while staying idiomatic to each platform.