Omniscio

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.AgentMC bridge (its db namespace); it cannot import src/renderer/** or @shared/**.
  • Strict CSP. The webview runs under script-src 'self' with no unsafe-inline — every handler is attached with addEventListener in plugin.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 @data path (/plugin/books/@data/<dir>/<href>), each response carrying a strict script-src 'none' CSP.
  • foliate is driven over those same-origin files: reader-engine.js uses foliate only to PARSE (spine, table of contents, CFI) via a fetch-backed loader, then overrides each section.load() to return the same-origin @data URL. foliate's native loader would mint a blob: 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's position column (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.js cssFromPrefs, html/body !important so a book's own CSS can't win) applied via view.renderer.setStyles, which foliate re-applies on every chapter load. They persist in the plugin's KV storage (amc.storage, the storage permission) 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.

Last verified 2026-11-05