Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
285cd0b
Merge pull request #21 from PapyrusReader/master
Eoic Nov 6, 2026
92ac272
build: generate EPUB worker and retire stale artifacts
Eoic Nov 7, 2026
a52d0e4
Merge pull request #23 from PapyrusReader/maintenance/generated-worke…
Eoic Nov 7, 2026
b4aafaf
feat: read additional book formats with cancellable preparation
Eoic Nov 8, 2026
f7846c1
fix: recognize Kindle HTML roots and await browser readiness
Eoic Nov 13, 2026
49eaee9
feat: improve PDF navigation, search and selection
Eoic Nov 13, 2026
8f5de8d
test: follow compact PDF toolbar in browser smoke checks
Eoic Nov 13, 2026
ba4ae26
test: wait for reader route instead of transient loading chrome
Eoic Nov 13, 2026
25cfb71
test: verify PDF scrolling within the visible page
Eoic Nov 13, 2026
26a27b5
Merge branch 'fix/format-browser-readiness' into fix/pdf-zoom
Eoic Nov 13, 2026
2750338
fix: honor explicit PDF locations over saved view centers
Eoic Nov 13, 2026
b47b763
test: wait for interactive reader viewport across loading frames
Eoic Nov 13, 2026
1888748
Merge branch 'fix/format-browser-readiness' into fix/pdf-zoom
Eoic Nov 13, 2026
119d1bc
Merge pull request #25 from PapyrusReader/feature/24-additional-book-…
Eoic Nov 13, 2026
237d2d1
Merge remote-tracking branch 'origin/development' into fix/pdf-zoom
Eoic Nov 13, 2026
70c7a5f
Merge pull request #27 from PapyrusReader/fix/pdf-zoom
Eoic Nov 13, 2026
2456b81
fix: restore the saved PDF page without an explicit locator
Eoic Nov 13, 2026
3dbe76b
Merge pull request #30 from PapyrusReader/fix/restore-saved-pdf-page
Eoic Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 4 additions & 16 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,11 @@ jobs:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.41.2'
flutter-version: '3.47.9'
channel: stable
cache: true
- run: flutter pub get --enforce-lockfile
- run: bash tool/build_epub_worker.sh --check
- run: dart format --output=none --set-exit-if-changed lib test example/lib example/test tool
- run: dart format --output=none --set-exit-if-changed bin lib test example/lib example/test tool
- run: flutter analyze
- run: flutter test
- run: flutter analyze
Expand All @@ -30,6 +29,7 @@ jobs:
working-directory: example
- run: flutter build web
working-directory: example
- run: python3 tool/check_worker_build.py
- uses: actions/setup-node@v4
with:
node-version: '22'
Expand All @@ -55,24 +55,12 @@ jobs:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
flutter-version: '3.41.2'
flutter-version: '3.47.9'
channel: stable
cache: true
- run: sudo apt-get update && sudo apt-get install -y libgtk-3-dev
if: matrix.target == 'linux'
- run: flutter pub get
working-directory: example
- run: flutter build ${{ matrix.target }}
if: matrix.target != 'macos'
working-directory: example
- run: flutter build macos --config-only --release
if: matrix.target == 'macos'
working-directory: example
# Flutter 3.41.2's universal build has an Xcode 27 architecture-check issue.
# Compile the runner architecture until flutter/flutter#188346 is fixed.
- run: >-
xcodebuild -workspace macos/Runner.xcworkspace -scheme Runner
-configuration Release -derivedDataPath build/macos -sdk macosx
ARCHS="$(uname -m)" ONLY_ACTIVE_ARCH=YES CODE_SIGNING_ALLOWED=NO build
if: matrix.target == 'macos'
working-directory: example
12 changes: 6 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This is an independent Flutter package and Git repository. The owning workspace
is one level up; use its `tools/flutter` and `tools/dart` SDK wrappers when present.
Read `docs/architecture.md` before changing architecture or expanding formats.
Read `docs/ARCHITECTURE.md` before changing architecture or expanding formats.

- Domain types are host-facing and serializable. Implement the current locator contract
without compatibility shims for older app versions.
Expand All @@ -13,11 +13,11 @@ Read `docs/architecture.md` before changing architecture or expanding formats.
- EPUB document processing is pure Dart in `lib/src/engine/epub/worker`. Native
isolates and browser workers use the same request/response protocol. Never
move ZIP, XML or chapter HTML parsing back onto the Flutter UI thread.
- Rebuild `assets/epub_worker.js` with `tool/build_epub_worker.sh` after modifying
worker source. The packaged JS lets dependent applications build without a
manual worker generation step. CI checks the generated asset for drift.
This package commits `pubspec.lock` and pins its CI SDK so the
browser worker and third-party notices are reproducible.
- Flutter 3.47 or newer generates the browser worker automatically during web
builds through `bin/compile_epub_worker.dart`. Keep its dependency report complete
so imported source and license changes invalidate the generated asset. Native
builds exclude it. Do not commit generated JavaScript or third-party notices.
This package commits `pubspec.lock` and pins its CI SDK.
- UI text measurement belongs in Flutter. Preserve semantic runs, Unicode,
illustrations and content offsets when reflowing. Layout must use actual viewport
constraints, system insets and text scaling.
Expand Down
49 changes: 33 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Papyrus Reader

`papyrus_reader` is a self-contained Flutter library for reading reflowable
EPUB 2/3 and PDF documents on Android, iOS, Web, Linux, macOS, and Windows.
EPUB 2/3, PDF, MOBI, AZW3, TXT, CBZ and CBR documents on Android, iOS, Web,
Linux, macOS, and Windows.

It provides versioned EPUB content locations, PDF page locations, TOC/outline navigation,
scroll and paginated layouts, configurable appearance, and a responsive
Expand Down Expand Up @@ -57,7 +58,7 @@ and a live `buildContent(context, scrollController)` builder without reader head
or framing. Return an unpushed `Route<void>`; the reader handles presentation,
activity tracking and cleanup. Connect the builder's scroll controller to your
sheet's scrolling coordinator. Omit this hook to use the standalone defaults.
See [Architecture](docs/architecture.md) for the presentation contract.
See [Architecture](docs/ARCHITECTURE.md) for the presentation contract.

## Example

Expand All @@ -67,36 +68,52 @@ flutter run
```

The six-platform example includes deterministic long EPUB and three-page PDF
assets, a local EPUB/PDF file picker, light/dark themes, and in-memory
assets, a local book file picker, light/dark themes, and in-memory
position/preference restoration. Example positions reset when the app restarts;
production persistence belongs to the host application.

## Current scope

The initial release supports reflowable EPUB 2/3 and PDF. Fixed-layout EPUBs
return `ReaderErrorCode.unsupportedFixedLayout`. MOBI/AZW3, TXT, comic
archives, search, bookmarks, highlights, and notes are planned extensions.
Supported inputs are reflowable EPUB 2/3, PDF, DRM-free MOBI/AZW3 (KF8), plain
text (UTF-8, BOM-marked UTF-16 and Windows-1252), CBZ and CBR (RAR4/RAR5).
Comic pages use natural filename order and support JPEG, PNG, GIF, WebP and BMP;
animations display as still pages. Password-protected archives, multi-volume
comics, Kindle Print Replica, Topaz and encrypted/DRM books are unsupported.
Fixed-layout EPUBs return `ReaderErrorCode.unsupportedFixedLayout`.

- [Architecture](docs/architecture.md)
- [Client integration](docs/integration.md)
- [Supported formats](docs/supported-formats.md)
Text and Kindle inputs use the reflow engine. Comics use a transient in-memory
page document for zoom, scrolling and facing pages; original library files are
never changed. Conversion runs in a cancellable isolate/browser worker before
opening; large comics may take longer and require memory for the page document.
Reflow uses EPUB-style content locators; comics use PDF-style page locators, so
saved positions, bookmarks and reading activity use the existing contracts.

EPUB and Kindle use semantic reflow: publisher
stylesheets, embedded fonts, advanced SVG/math, RTL progression and footnote
interaction are incomplete; complex tables render as readable rows.

- [Architecture](docs/ARCHITECTURE.md)
- [Client integration](docs/INTEGRATION.md)

## Development

```bash
flutter analyze
flutter test
./tool/build_epub_worker.sh
(cd example && flutter analyze && flutter test && flutter build web)
# From the reader repository, after building the example:
(cd tool/browser && npm ci && npx playwright install chromium && npm test)
```

Use the parent workspace's pinned SDK wrappers when available. The generated
browser worker is packaged so host applications need no extra build step; rebuild
it after changing worker source. Browser CSP must allow `worker-src blob:`.
Use `tool/build_epub_worker.sh --check` to check asset drift. Browser checks can
use an installed Chrome via `PAPYRUS_CHROME_EXECUTABLE` and save screenshots via
`PAPYRUS_SCREENSHOT_DIR`. See [Validation](docs/validation.md) for platform coverage.
Use the parent workspace's pinned SDK wrappers when available. Flutter 3.47 or
newer automatically compiles the browser worker from `tool/epub_worker.dart` during
web builds, using the host application's resolved dependencies. The one-line
`assets/epub_worker` file identifies that Dart entrypoint for the asset transformer.
The generated JavaScript includes dependency license notices; neither is checked
into this package.
Native builds omit this asset. Browser CSP must allow `worker-src blob:`.
Browser checks can use an installed Chrome via `PAPYRUS_CHROME_EXECUTABLE` and save
screenshots via `PAPYRUS_SCREENSHOT_DIR`. See [Validation](docs/VALIDATION.md) for
platform coverage.

Licensed under AGPL-3.0.
1 change: 1 addition & 0 deletions assets/epub_worker
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
tool/epub_worker.dart
Loading
Loading