How internetarchive/bookreader works
Project Type and Purpose
• This is an open-source, browser-based JavaScript library (BookReader v5) that renders paginated content (books) in a viewer.
• It combines a core rendering engine (jQuery-based), a Web Components layer for side navigation (LitElement), and a plugin system to extend functionality (search, TTS, resume, etc.).
• It ships as an NPM package and is deployed on archive.org, with demo HTML pages, CI/CD, and a comprehensive test suite.
Main Components
a. Core Engine (src/BookReader & jQuery)
• Responsible for layout modes (1-up, 2-up, gallery), page drawing, scrolling, resizing, history management.
• Exports a BookReader API emitting CustomEvents (events.js).
b. BookNavigator (src/BookNavigator & LitElement)
• Listens to core’s CustomEvents.
• Implements side-panel web components (bookmarks, search, downloads, visual adjustments, sharing).
c. Plugin Layer (src/plugins)
• Mixins augment the core prototype to add features: autoplay, search UI, IIIF support, iframe embedding, TTS, URL syncing, resume.
• Each plugin registers event handlers and public API hooks.
d. Demo Harness (BookReaderDemo + index.html)
• Static HTML + JS demos illustrating usage patterns (simple embed, full, IIIF, multi-volume, iframe).
e. Build & Tooling
• Node.js build pipeline: Babel, Webpack (webpack.config.js), scripts/preversion.js, scripts/postversion.js.
• Config files: babel.config.cjs, jsconfig.json, netlify.toml.
• CI workflows (.github/workflows/node.js.yml, npm-publish.yml).
f. Testing
• Unit tests (Jest under tests/jest).
• End-to-end tests (TestCafe under tests/e2e).
• Test harness helpers and CI integration with codecov.
Relationships & Data Flows
• Core Engine emits CustomEvents → BookNavigator components subscribe and update UI.
• Plugins hook into Core Engine events and public methods → extend behavior.
• Build pipeline consumes src/, outputs bundled assets (JS, CSS) → deployed via Netlify and published to NPM.
• Demo pages fetch built assets → user interactions drive Core Engine + Plugins.
• Tests drive Core Engine and Plugin APIs → validate event flows and rendering.
• External Services: optional IIIF manifest fetch (demo-iiif.html), Internet Archive search API.
Architectural Patterns
• Hybrid MVC/Event-Driven: Core acts like a Model/View engine publishing events; Navigator acts as the Controller/View for side UI.
• Plugin/Mixin: decoupled feature modules augment core behavior.
• Web Components: LitElement-based encapsulation of UI panels.
• Build & CI/CD: automated bundling, versioning, testing, publishing.
Layer 1: User / Browser
• Demo HTML / Archive.org embed
Layer 2: BookReader Runtime
• Core Engine (jQuery)
• Plugins (search, TTS, iframe, resume…)
• BookNavigator Web Components
Layer 3: Build, Packaging & Deployment
• Webpack / Babel → dist bundle
• Netlify / NPM publish
• GitHub Actions CI
Layer 4: Testing
• Jest (unit)
• TestCafe (e2e)
Layer 5: External Dependencies
• IIIF manifest endpoints
• Internet Archive search API
• Browser APIs (CustomEvent, postMessage)