Ream
A minimal EPUB reader that renders like Webnovel's dark night-mode:
Merriweather 18px / 1.8 line-height, #1f2129 page, #83848f text,
ragged-left, no indent, spaced paragraphs. Chapters are read one at a time
with an end-of-chapter "Previous / Next chapter" break.
Everything runs locally in the browser — no book ever leaves your device.
Features
- Open any
.epub (button, or drag & drop the file anywhere)
- Chapters menu (drawer) — jump to any chapter, current one highlighted
- One chapter per view, with an end-of-chapter Previous/Next block
- Phone reading chrome: a permanent top bar (menu · title · chapter tools) and
a bottom bar (‹ Previous · ⤒ top · ⤓ end · Next ›, its top edge filling with
the chapter's progress) that hides as you read and returns on scroll-up, a
tap, or the chapter's top / end. After a jump, that button offers the way
back ("↩ 38 %"); a jump never counts as reading.
- Resumes the last book and reading position automatically (IndexedDB)
- Installable, fully offline PWA (service worker via
vite-plugin-pwa)
- Asks the browser to keep the library's storage persistent, and keeps the
screen awake while you read — released after 5 minutes without a scroll or tap
- Designed for the phone, with a full tablet / desktop layout (see below)
- Soul Sea (Shadow Slave only) — Sunny's Memories, Echoes, Shadows, Attributes
and Aspect as of where you are, in the book's own words (
scripts/soul-sea/)
On a computer
The phone design is the reference; wider screens get their own arrangement of
the same pieces (src/wide.css, two tiers: ≥ 640 px tablet, ≥ 1024 px desktop):
- Library — a centred shelf with as many cover columns as fit, the search
field always in the header (
/ focuses it), and a drop-anywhere import target.
Right-click is the long-press: on a series it opens its menu, on a book it
starts multi-select (so does ⌘/Ctrl-click); the selection toolbar floats at
the bottom.
- Book / series page — the cover beside the title and description, then
volumes + chapters on the left and details on the right.
- Reader — the menu button docks the chapter list beside the text (remembered);
a hairline under the top bar shows progress through the chapter.
Keys:
Space / Shift+Space, PageUp / PageDown, ↑ / ↓, Home /
End scroll — also with focus in the text.
- Sheets become centred dialogs, the
⋯ menu a popover, editors a modal.
Run (development)
npm install
npm run dev # http://localhost:5173 (also printed on your LAN IP)
Open the LAN URL (e.g. http://192.168.1.40:5173) on your phone while on the
same WiFi to read on mobile. Note: the service worker / offline install only
activates over HTTPS (or localhost), so LAN dev is online-only — see below
to install it as a real offline app.
Logo & icons
The mark — five stacked lines, the current one lit — is pure geometry in
src/lib/ream-mark.js. It is drawn live in two places (src/brand.js): the
Library header, where the stack scrolls with the shelf, and the reader's menu
button (in place of a burger), where it scrolls at half the text's pace (one
line per two lines of text) as you read; npm run icons renders the same geometry
into public/ (icon.svg, the PWA PNGs, the maskable icon and
apple-touch-icon.png). Re-run it after touching the mark and commit the output.
Build
npm run build # static site + service worker in dist/
npm run preview # serve the built site locally
dist/ is a plain static bundle: HTML, JS, CSS, the Merriweather fonts, and a
Workbox service worker that precaches the whole app shell.
Put it on your phone (offline app)
The service worker needs HTTPS, so host the built dist/ on any free static
host, then "Add to Home Screen". After the first load the app runs with no
network at all — your books are opened locally from the phone's Files /
iCloud Drive / Downloads and kept in the browser; nothing is ever uploaded.
Pick one (run from the project root after npm run build):
# Cloudflare Pages — root domain, ideal for a PWA
npx wrangler pages deploy dist
# Netlify
npx netlify deploy --prod --dir dist
# Surge
npx surge dist
GitHub Pages also works (base is ./, so a project subpath is fine): push the
repo and serve dist/ from a Pages workflow or the gh-pages branch.
On the phone: open the deployed URL in Safari (iOS) or Chrome (Android) →
Share / menu → Add to Home Screen. Launch it once online to cache, then
it opens offline forever.
Layout
The app is plain ES modules (no framework); Vite bundles them into one file, so
the split is purely for readability — there is no runtime cost. Each module owns
one concern:
src/main.js — entry: pulls the modules together, wires the static chrome, bootssrc/db.js — IndexedDB primitivessrc/state.js — in-memory library data + persistence (single source of truth)src/reading.js — derived reading state (percentages, ordinals, titles)src/dom.js — element builder, icons, cover cache, element refs, touch gesturessrc/sheets.js — action sheet + confirm / name / suggest promptssrc/router.js — routing + the overlay/Back history stacksrc/import.js — .epub parsing, import/grouping, dev-seedsrc/library.js — home screen + multi-selectsrc/info.js — info page + editors + volume sheetsrc/chapters.js — chapters screen + shared chapter-preview componentsrc/reader.js — reading surface, drawer, resume, chapter-nav injectionsrc/readbar.js — the phone's auto-hiding bottom bar (chapter steps, top / end)src/pwa.js — install prompt + service-worker update bannersrc/device.js — persistent-storage request + reading wake locksrc/lib/ — pure, unit-tested helpers (text, chapters, format math)src/style.css — app chrome (top bar, drawer, landing) — the phone designsrc/wide.css — tablet / desktop layer on top of it (min-width queries only)src/reader-theme.css — the Webnovel-dark theme injected into each chapterpublic/fonts/ — Merriweather (OFL) static facesscripts/fetch-seed.mjs — downloads the dev-seed books into public/seed/vite.config.js — Vite + PWA (service worker, manifest) config
Quality checks
npm test # Vitest unit tests over the pure logic in src/lib
npm run lint # ESLint (flat config)
npm run format # Prettier (pure-logic modules, tests, config)
The deploy workflow runs npm test and npm run lint before building, so a
failing check blocks the release.
Dev seeding
For design/QA there is a hidden reset that fills the library with a fixed set
of real, public-domain books (from Project Gutenberg) covering every case the
design needs — with/without cover, started/unstarted, loose volumes, and
shelves. Long-press the Import tile (or the empty-state Import button) and
confirm. It is a reset: it wipes the current library first, so it never
duplicates. The books live in public/seed/ (committed, excluded from the PWA
precache); regenerate them with npm run seed:fetch.
