Books (built-in plugin)
The built-in Books reader for EPUB and PDF books you own: importing a book onto the shelf, the paginated EPUB reader and its reading settings, the separate PDF path, highlighting and notes in EPUBs, where a book's data and reading position are stored, and how the plugin is changed.
On this page
What it is
Books is a personal reader for EPUB and PDF books you own. Import a book from your computer and it lands on a shelf; open it to read. EPUBs get a paginated reader with a table of contents and reading settings (font, size, line spacing, margins, justify, and a light/sepia/dark theme); PDFs get a page-by-page pdf.js reader. Either way it remembers your place per book. EPUBs also support highlights and notes (EPUB only); AI study tools are still planned (Phase 4). It shows up in the sidebar as "Books" once you switch it on in Marketplace → Installed.
It is a plugin — but a bundled built-in, not Marketplace-only
Books is a first-party, sandboxed plugin living at src/plugins/books/, but
unlike a Marketplace-only plugin (e.g. Reading Queue) it is bundled into the
app: it is not in plugin-loader.ts's BUILTIN_EXCLUDE, so it ships and loads as a
built-in with no separate install. Like every built-in it is off until switched on in
Marketplace → Installed.
- Its UI is hand-authored vanilla JS served into an isolated webview — no React, no
bundler, no build step, and no access to the app's component kit. It reaches the host
only through the
window.AgentMCbridge (itsdbnamespace); it cannot importsrc/renderer/**or@shared/**. - Strict CSP. The webview runs under
script-src 'self'with nounsafe-inline— every handler is attached withaddEventListenerinplugin.js, so no inline handler is ever needed (deliberately stricter than its sibling plugins).
Where to find it
Books ships inside the app as a built-in plugin, so there is no separate install, but it is off until you switch it on in Marketplace → Installed; then it appears as its own entry in the sidebar. Open it to see your shelf, import a book from your computer, then click a book to start reading.
How it behaves
Reading a book (the reader engine)
Opening a book mounts a vendored foliate-js
fork (7 modules, pinned by SHA) in the webview. The subtle part is HOW chapters are
served — same-origin, never blob::
- The main process already unpacked the EPUB at import and serves its files under a
scoped
@datapath (/plugin/books/@data/<dir>/<href>), each response carrying a strictscript-src 'none'CSP. - foliate is driven over those same-origin files:
reader-engine.jsuses foliate only to PARSE (spine, table of contents, CFI) via afetch-backed loader, then overrides eachsection.load()to return the same-origin@dataURL. foliate's native loader would mint ablob:URL per chapter, which the plugin CSP floor forbids (frame-src 'self') — and a blob doc carries no response CSP, so the same-origin path is also the stricter one. - Your place is saved as
{ sectionIndex, progression, cfi }in the book'spositioncolumn (throttled, and when you leave), and restored on open (precise CFI first, then a clamped section index). Fixed-layout EPUBs are refused with a message (that renderer is not vendored). - Reading settings (the "Aa" panel) — font, size, line spacing, margins, justify,
and a light/sepia/dark theme — become a stylesheet (
lib/typography.jscssFromPrefs, html/body!importantso a book's own CSS can't win) applied viaview.renderer.setStyles, which foliate re-applies on every chapter load. They persist in the plugin's KV storage (amc.storage, thestoragepermission) and are normalized on read, so a stale value can never break the reader.
PDFs take a separate path — they bypass foliate entirely. The importer stores the
file as book.pdf and validates it in the main process via pdf.js (page count +
metadata, with scripting and eval off); a password-protected, empty, or corrupt PDF is
refused with a friendly message and no half-imported book. The reader fetches those
bytes same-origin from the @data route (never navigating to them) and draws the
current page onto a canvas with
vendored pdf.js — one visible page
at a time, fit to width, at a capped resolution so a very large page can't exhaust
memory. Page turns use the same arrow / on-screen controls, your page is saved as
{ pdfPage } (in the same position column EPUBs use for their CFI), and the
EPUB-only contents + "Aa" controls are hidden. A PDF shows a placeholder cover on the
shelf (page-1 thumbnails are a later polish). Because Books is a built-in plugin its
CSP already allows what pdf.js needs (the same-origin worker + eval), so no CSP change
was required.
Highlighting and taking notes (EPUB only)
Select text in an EPUB and a small toolbar floats over it: pick one of four colours to highlight, or tap Note to highlight and attach a comment. Tap an existing highlight to recolour it, edit its note, or delete it (with an Undo). A per-book highlights drawer (a toggle beside Contents / "Aa") lists everything you marked — filter by colour, tap a row to jump straight to that passage. Highlights render on the page as you read.
A few things make this trustworthy:
- They never vanish and are never silently lost. foliate itself doesn't remember highlights when you turn between chapters, so the reader owns them and redraws each chapter's as it loads. If a highlight's saved spot ever can't be found (e.g. a future reading-engine upgrade shifts positions), it is kept and marked "couldn't locate in this version" with your text still visible — never deleted.
- Delete is reversible — a soft delete with an in-reader Undo, not a destroy.
- Your text is safe to display. The book's quoted passage and your note are escaped before rendering (the same boundary the shelf uses), so a book can't smuggle markup into the drawer.
- PDF highlighting is deliberately deferred — the PDF reader draws each page as a flat image with no selectable text, so annotations there need machinery a later phase adds.
Highlights live in the plugin's own annotations collection over the same
AgentMC.db bridge the shelf uses (no special privileged method), each carrying its
precise location, the quoted text, and your note.
Full invariants + the tests that lock them: books-plugin-contract.md.
How it stores data
The plugin owns a books collection declared in its manifest (storage.collections)
— the host creates and evolves the table. Each row records the book's title,
author, format, on-disk dir, cover_path, spine (JSON), added_at, a
progress fraction, the exact reading position (JSON — { sectionIndex, progression, cfi } for an EPUB, { pdfPage } for a PDF), last_opened_at, and a content_hash. No
PDF-specific column was needed (the page count is read live from the document at open).
New fields are added additively — a manifest column plus a plugin.version bump, and
the host runs ALTER TABLE ADD COLUMN on upgrade (existing books untouched); a whole new
collection is likewise manifest-only (the host creates its table on next load).
Highlights and notes live in a second annotations collection — one row per highlight
(book, colour, kind, location, quoted text, note, a soft-delete flag). The content_hash
powers re-import de-dup: importing a byte-identical book you already have reunites
with the existing copy — same book, highlights intact — instead of making a duplicate.
Usage telemetry
Books is tracked in FEATURE_REGISTRY (id books, status instrumented) — importing
a book emits an imported feature_events datum so the feature's usage is counted,
like every other tracked surface. Only the anonymous action is recorded; no book
content or personal data is sent.
Related
- reading-queue.md — a sibling reading plugin, but Marketplace-only
Last verified 2026-11-05