hyper_render_epub #

EPUB container support for HyperRender. Unzips an .epub, parses its OPF manifest/spine/table-of-contents, and resolves each chapter to content HyperViewer can render directly.

Status: v0.1.0 #

What the package does today:

✅ EpubBook.open(bytes) — unzips the archive, locates the OPF through META-INF/container.xml, and parses metadata, manifest, spine and table of contents (EPUB3 nav.xhtml, falling back to EPUB2 toc.ncx).
✅ Per-chapter transform — <img src> inlined as base64 data: URIs, <link rel="stylesheet"> and <style> collected into EpubChapter.css in document order (a <head> <style> would otherwise be lost with the rest of the head), body content extracted.
✅ epubImageLoader — a HyperImageLoader that decodes those data: URIs (EPUB images live inside the zip, not at a fetchable http(s):// URL), falling back to the normal network loader for anything else.
✅ EpubReader + EpubReaderController — chapter-at-a-time reading, TOC/cross-chapter href resolution, link taps wired. Rendering only; the chrome around it is yours.
❌ Seamless pagination across chapter boundaries — see the note on pagination below.

Structural damage throws EpubFormatException (not a zip, no OPF, no spine). Partial damage never does: a spine item whose file is missing is skipped, an unparsable TOC yields an empty tableOfContents, and an <img> whose target is absent keeps its original src.

Installation #

dependencies:
  hyper_render_epub: ^0.1.0

Usage #

import 'dart:io';
import 'package:hyper_render_epub/hyper_render_epub.dart';

final book = await EpubBook.open(await File('book.epub').readAsBytes());
final controller = EpubReaderController(book: book); // dispose() when done

Column(children: [
  Expanded(child: EpubReader(controller: controller)),
  Row(children: [
    TextButton(
      onPressed: controller.hasPrevious ? controller.previous : null,
      child: const Text('Previous'),
    ),
    TextButton(
      onPressed: controller.hasNext ? controller.next : null,
      child: const Text('Next'),
    ),
  ]),
])

EpubReaderController is a ChangeNotifier, so a chapter title, a progress bar and a table-of-contents panel can all watch the same position:

ListenableBuilder(
  listenable: controller,
  builder: (context, _) => ListView(
    children: [
      for (final entry in book.tableOfContents)
        ListTile(
          title: Text(entry.title),
          selected: controller.chapterIndexForHref(entry.href) ==
              controller.chapterIndex,
          onTap: () {
            final index = controller.chapterIndexForHref(entry.href);
            if (index != null) controller.goTo(index);
          },
        ),
    ],
  ),
)

Links inside a chapter are resolved on tap: one pointing at another chapter moves the controller, anything else (an http(s):// reference, a broken path) is handed to onExternalLinkTap.

Rendering chapters yourself #

EpubReader is thin on purpose. Everything it does is available directly:

HyperViewer(
  html: chapter.html,
  customCss: chapter.css,      // the chapter's own <link>/<style> CSS
  imageLoader: epubImageLoader, // required — chapter images are data: URIs
  mode: HyperRenderMode.paged,
)

The one thing not to skip is imageLoader: the default network loader cannot decode a data: URI, so every image in the book silently fails without it.

A note on pagination #

HyperRenderMode.paged paginates one document — page-turns stay inside a chapter, and chapter boundaries are crossed through the controller (next() / previous()), which is what EpubReader is built around. A single continuously-swipeable surface spanning the whole book is a possible future addition, not something this package (or HyperRender's engine) does today.

API #

Type	What it is
`EpubBook.open(Uint8List)`	`Future<EpubBook>` — the whole parse. Throws `EpubFormatException` on structural damage
`EpubBook`	`title`, `author`, `coverImage` + `coverMediaType`, `chapters`, `tableOfContents`
`EpubChapter`	`id`, `href` (OPF-relative), `title`, `html`, `css`, `linear`
`EpubTocEntry`	`title`, `href` (OPF-relative, may carry `#fragment`), `level`, `children`
`EpubReaderController`	`ChangeNotifier` — `chapterIndex`, `chapter`, `next`/`previous`/`goTo`, `chapterIndexForHref`, `openHref`
`EpubReader`	Renders the controller's current chapter through `HyperViewer`
`epubImageLoader`	`HyperImageLoader` decoding the inline `data:` URIs chapters carry
`EpubFormatException`	Not a zip / no OPF / no spine

Chapters marked linear="no" in the spine (covers, colophons, note collections) stay in chapters — dropping content silently is worse — and are flagged via EpubChapter.linear so a reader can present them out of the main flow.

SVG images #

<img src="cover.svg"> is replaced by the SVG file's markup inline, not by a data: URI: UrlSafety blocks data:image/svg outright (an SVG can carry <script>), while an inline <svg> element is explicitly preserved by HyperRender's sanitizer — scripts and event handlers stripped — and rendered through flutter_svg.

That renderer is chained in by HyperViewer (hyper_render), not by core's HyperRenderWidget, so an SVG-illustrated book needs the root package. EpubReader uses HyperViewer, so it just works.

EpubBook.coverImage is likewise handed back undecoded, with coverMediaType alongside it — an SVG cover is a real cover, it just needs SvgPicture.memory instead of Image.memory.

What this package deliberately does not rewrite #

Cross-chapter <a href> links are left as authored (e.g. text/chapter3.xhtml#note) in EpubChapter.html. EpubReader resolves them at tap time via EpubReaderController.chapterIndexForHref; if you render chapters yourself, do the same.
url(...) inside collected CSS is not rewritten, because the properties that use it are not rendered anyway (see below).

Known CSS gaps this package inherits from the engine #

Verified against hyper_render_core, not assumed:

background-image: url(...) is parsed into ComputedStyle.backgroundImage but never painted — HyperRender's canvas paint layer doesn't read it. A chapter stylesheet with background images will not error, it will just render without them.
@font-face src: url(...) has no support anywhere in the engine (no dynamic/runtime font loading API at all), so embedded EPUB fonts are not applied. Chapters fall back to whatever font the surrounding app uses.

Neither is planned for this package to work around — both are engine-level gaps, not something a container/CSS-inlining layer can paper over.

HyperRender Ecosystem #

Package	Description
hyper_render	Main package — `HyperViewer` widget, HTML + Markdown rendering
hyper_render_core	Core engine: UDT model, `RenderHyperBox`, plugin API
hyper_render_html	HTML + CSS → UDT parser
hyper_render_markdown	Markdown (GFM) → UDT parser
hyper_render_highlight	Syntax highlighting for `<code>` / `<pre>` blocks
hyper_render_clipboard	Image copy / save / share (opt-in)
hyper_render_math	LaTeX / MathML rendering
hyper_render_epub	EPUB container support ← you are here
hyper_render_devtools	Flutter DevTools inspector

Source · Issues · Changelog

License #

MIT — see LICENSE.

hyper_render_epub 0.1.1
hyper_render_epub: ^0.1.1 copied to clipboard

Metadata

hyper_render_epub #

Status: v0.1.0 #

Installation #

Usage #

Rendering chapters yourself #

API #

SVG images #

What this package deliberately does not rewrite #

Known CSS gaps this package inherits from the engine #

HyperRender Ecosystem #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

Dependencies

More

hyper_render_epub 0.1.1 hyper_render_epub: ^0.1.1 copied to clipboard

Metadata

hyper_render_epub #

Status: v0.1.0 #

Installation #

Usage #

Rendering chapters yourself #

A note on pagination #

API #

SVG images #

What this package deliberately does not rewrite #

Known CSS gaps this package inherits from the engine #

HyperRender Ecosystem #

License #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

Topics

License

Dependencies

More

hyper_render_epub 0.1.1
hyper_render_epub: ^0.1.1 copied to clipboard