The Reader organizes each EPUB workflow around a Reading Session and its Marginalia. Second Pass
Library owns server data; the browser owns interaction state and sends EPUB operations through the
Reader engine boundary. Durable product records call the machine anchor location; for EPUB Books
that value is an EPUB CFI string. Renderer state is transient.
Web-authored progress, bookmarks, highlights, and notes use compact epubcfi(...) locations:
structural path steps, character offsets, simple ranges, and structural element ID assertions such
as /4[element-id]. A text-location assertion after an offset, such as :17[surrounding text], is
outside the durable profile. Temporal and spatial offsets and CFI extensions or parameters are
also unsupported. All clients must author this compact structural profile for interoperability.
epub-ts creates and interprets Web locations. Progress and annotation writes guard against
unsupported authored forms; this lightweight guard is not a full CFI parser. The Library validates
the wire profile and stores accepted location strings byte-for-byte without opening EPUBs, resolving locations,
or repairing anchors. Quote repair context belongs in the separate text, prefix, and suffix
fields, never inside a CFI. Chapter labels and percentages are presentation metadata, not anchors.
Glasp quote matching generates a new EPUB range CFI through epub-ts. Second Pass Marginalia location hints containing EPUB CFIs are probed against the EPUB and retained unchanged when accepted; structural ID assertions are valid. Existing server/import validation handles unsupported imported values. Continuation and copy-forward retain an accepted CFI unchanged.
src/app/AppReaderOpen.Controller.ts owns both supported opening paths:
- With
onlineorunknownconnectivity, it loads Book metadata, opens or resumes the server Reading Session, downloads the EPUB, and creates the publication object URL. - With explicit
offlineconnectivity, it requires the verified account namespace, retained Book metadata, and a complete EPUB whose format and checksum pass the offline publication policy. It then restores local Reader continuity without mounting server request owners.
An arbitrary server failure never falls back to retained bytes. Both paths use the same Reader route and object URL cleanup. If an online-open Reader later observes explicit offline connectivity, it keeps the mounted EPUB engine and hands progress and current-Reading-Session Marginalia to durable local ownership. Reconnect uses the normal authority and outbox replay pipeline; that Reader remains local-first until it closes.
The handoff retains authored state, not publication bytes. A Book that was not explicitly made Available offline cannot be reopened offline after the mounted Reader closes. Unknown connectivity, request failure, authentication repair, and namespace loss do not trigger the handoff.
See offline-mode.md for local authoring, outbox, sync, and cleanup behavior.
src/app/AppReaderOpen.Controller.tsopens the requested Book and owns object URL replacement.src/features/reader/ReadingActivity.Orchestrator.tsxcomposes Reader chrome, panels, imports, and completion controls.src/features/reader/session/ReadingSession.Orchestrator.tsxconnects Reading Session state and Marginalia to renderer-neutral capabilities.src/features/reader/shell/ReadingShell.Orchestrator.tsxowns the viewport and shell lifecycles.src/features/reader/engine/EpubTsBook.Engine.tsprovides the public EPUB engine facade.
Direct navigation to #/reader/:bookId uses the same opening path. A search query parameter starts
an in-book search after the search capability becomes readable.
| Owner | Responsibility |
|---|---|
ReaderActivityImport.Controller.ts |
Import review, activation handoff, manual completion, cleanup, and layout resize requests |
ReaderActivityCompletion.Controller.ts |
End-of-book state, next-Series lookup, close-dialog transitions, return-target persistence, and post-close navigation |
ReaderActivityHeader.UI.tsx |
Reader header controls and status |
ReaderActivitySidePanels.UI.tsx |
Search, import, Marginalia, and annotation workspace composition |
ReaderActivityDialogs.UI.tsx |
Import, Reading Session close, and end-of-book dialogs |
Import code clears temporary search and staging state before hiding, clearing, skipping, or handing confirmed annotation intent to the Reading Session layer. It does not call annotation endpoints directly.
ReadingSession.Orchestrator.tsx mounts the server-backed and local-first owners, then exposes one
selected current-session authoring authority to the activity. Connectivity does not define the
authority mode: after an online Reader hands off, the selected authority remains local-first until
that Reader closes.
| Owner | Responsibility |
|---|---|
CurrentSessionAuthority.Controller.ts |
Unconditional online/local owner composition, one explicit authority selection, annotation mutation capability, and progress status/close coordination |
ReadingSessionBridge.Controller.ts |
Coherent renderer capability, shell events, sequenced commands, Book-scoped location state, and temporary search marks |
annotations/SessionAnnotations.Controller.ts |
Current Reading Session annotation loading, generation reset, and CFI descriptions |
annotations/SessionAnnotations.Presenter.ts |
Annotation view models and durable renderer marks |
annotations/CurrentSessionAnnotation.Controller.ts |
Serialized current Reading Session mutations with generation checks |
annotations/CurrentSessionAnnotation.Actions.ts |
Bookmark and highlight action composition |
annotations/OfflineCurrentSessionAnnotation.Controller.ts |
Local-first annotation mutation and durable intent |
annotations/CurrentSessionAnnotation.Types.ts |
Canonical bookmark/highlight upsert and delete intent |
annotations/ServerCurrentSessionAnnotation.Adapter.ts |
Commits canonical intent through the server authority |
progress/ReadingProgressAutosave.Controller.ts |
Debounced, serialized online progress replacement |
progress/ReadingProgressAutosave.Lifecycle.ts |
Progress seeding, bounded exit flush, and shutdown before close |
progress/OfflineReadingProgress.Controller.ts |
Local progress persistence and outbox intent |
previousSession/PreviousSessionLayers.Controller.ts |
Selected read-only Marginalia from previous Reading Sessions |
CurrentSessionMetadata.Controller.ts |
Active Reading Session metadata loading and updates |
ReadingSessionClose.Actions.ts |
Metadata update and atomic close with final progress |
ReadingSessionRender.Presenter.ts |
Render state, toolbar items, and ordered durable marks |
Authority modes are server, local, and unavailable. A server or local authority reports
writable, initializing, or read-only status as applicable and exposes annotation mutation
commands only while writable. Reading Session metadata and close remain a separate server-owned
administration interface; previous-session Marginalia remains a separate read-only concern.
All current-session authoring uses the same mutation vocabulary and normalization builders in
ReadingSessionMarginalia.Actions.ts, including confirmed imports and exact-CFI highlight updates.
The orchestrator selects server or local-first authority. Server responses remain authoritative;
local-first commits persist annotation projection and delivery intent atomically before reporting
saved status. Replay delivers that durable intent, and continuation reuses the same local commit
repository. These authority changes do not rebuild the Reader engine.
Current Reading Session owners may mutate. Previous Reading Session layers are read-only and never enter current-session mutation actions.
POST /books/:id/open/returns the one active Reading Session:201creates it and200reuses it. The server enforces one active Reading Session per user and Book; clients do not choose among competing sessions.GET /books/:id/active-session/may return no Reading Session. A concurrent close can also make anopenresponse contain a closed snapshot. Closed snapshots render read-only and do not start progress autosave.- Closing from the Reader drains and stops progress writes, then sends the latest stable
locationand location label so metadata, final progress, and closed status commit atomically. - Progress
409 SESSION_CLOSEDmeans the server has closed the Reading Session. Autosave stops further writes for it while leaving the Reader usable.
ReadingShell.Orchestrator.tsx holds composition refs and renders the viewport. Its lifecycle
modules own the behavior below.
| Owner | Responsibility |
|---|---|
ReaderEngineBootstrap.Lifecycle.ts |
Engine generation, initial marks and display, capability readiness, and teardown |
ReaderCapabilityPublication.Lifecycle.ts |
Generation-safe publication of one renderer-neutral describe, probe, display, and search capability |
ReaderCommandRouting.Lifecycle.ts |
Pre-ready deferral, command routing, navigation classification, and failure reporting |
ReaderLocationPublication.Lifecycle.ts |
Viewport location, progress events, staged-selection decisions, toolbar close, and re-anchor requests |
ReaderSettingsReflow.Lifecycle.ts |
Settings and Reader-width reflow triggers without engine recreation |
ReaderRuntime.Controller.ts |
Generation-safe viewport serialization and the protected-anchor, durable-mark, and staged-toolbar reflow protocol |
ReaderStagedToolbar.Controller.ts |
Staged-selection behavior and toolbar rendering |
ReaderStagedSelection.Controller.ts |
Staged state, mark handoff, commit, cancel, and keyboard cleanup |
ReaderStagedSelectionReanchor.Controller.ts |
Staged-toolbar measurement and latest-request positioning |
StagedSelection.Lifecycle.ts |
Relocation ownership during import and layout operations |
ReaderDurableAnnotationToolbar.Controller.ts |
Durable annotation toolbar state and staged cancellation |
ReaderBootstrapProgressGuard.State.ts |
Bootstrap relocation quarantine and restored-CFI protection |
Attaching the engine does not make it ready. Readiness requires a readable display or relocation. The shell publishes one renderer capability only when describe, probe, display, search, and staged selection are all usable for the current generation. Teardown withdraws the capability as one value; retained methods still reject stale-generation work.
Runtime imports of @likecoin/epub-ts stay under src/features/reader/engine/.
| Owner | Responsibility |
|---|---|
EpubTsBook.Engine.ts |
Book and rendition construction, events, navigation, selection, CFI operations, TOC, and destruction |
EpubTsBookSearch.Engine.ts |
Serialized section search |
ReaderSearch.Controller.ts |
Exclusive full-Book section traversal |
EpubTsHighlightRenderer.Engine.ts |
Durable, staged, and temporary mark reconciliation |
EpubTsImportRangeRepair.Engine.ts |
DOM range reconstruction and epub-ts CFI conversion |
EpubImportRangeRepair.Policy.ts |
Normalized-text and punctuation-tolerant repair matching |
EpubTsRenditionSettings.Engine.ts |
Scoped rendition theme and style application |
EpubTsLocation.Mapper.ts |
Renderer locations and TOC entries mapped to Reader domain values |
EpubSelection.Adapter.ts |
Browser selection and quote-context extraction |
EpubVisibleCfiRangeAnchor.Placement.ts |
Visible range geometry for toolbar placement |
ReaderReflowTarget.Policy.ts |
CFI selection across resize and settings reflow |
Known library defects and limits belong in the epub-ts support ledger.
locationis the durable restore and spatial-anchor field. Its current EPUB value is a CFI; href, labels, and percentage are display metadata.- Drawer, menu, dialog, Settings, import, annotation, toolbar, and connectivity state must not recreate the EPUB engine.
- Viewport mutations run through
ReaderRuntime.Controller.ts; competing display, navigation, resize, or settings operations must not bypass it. - Opened progress seeds autosave. Bootstrap relocation quarantine prevents intermediate startup relocations from overwriting the restored CFI.
- Unrelated navigation cancels staged selection. Import staging and layout reflow protect their own relocations and request toolbar re-anchoring.
- Post-ready reflow intent goes through the runtime, which preserves the protected/current anchor, applies settings or size, refreshes marks, then re-anchors the staged toolbar.
- Temporary search marks clear before staged or durable handoff. Staged marks clear before commit or cancel completes. Canonical annotation state restores durable marks.
- epub-ts identifies marks by CFI and renderer type. A same-CFI staged preview temporarily replaces the durable mark; an exact same-CFI commit in the current Reading Session updates the existing application annotation.
- Marginalia from previous Reading Sessions remains read-only.
- Cleanup is generation-safe: stale asynchronous work cannot publish capabilities, mutate the active runtime, or retain an obsolete engine.
- Reader settings and themes are browser-local preferences.
- In-book search runs on explicit submission or an initial Reader search route, not every keystroke.
- Search uses epub-ts section traversal. There is no general fuzzy-search engine, and import range repair does not cross spine sections.
- Import accepts Glasp CSV and a single-Reading-Session Second Pass Marginalia JSON export. Import jobs stay in memory, are reviewed row by row, and do not survive reload.
- Import does not persist provenance or perform import-level duplicate detection. Confirmed rows use the normal annotation path and same-CFI update policy.
- Highlight CFIs are immutable after creation. Changing an anchor requires deleting and recreating the highlight; endpoint drag editing is unsupported.
- Marginalia from previous Reading Sessions is display-only context.
Debug logging is opt-in. Categories are reader, imports, and staged-selection.
localStorage.setItem("secondpass.debug.logs", "reader,imports,staged-selection")Use * to enable every category and remove the key to disable logging. Settings > Tools provides
the same controls.
Full import text previews require a separate setting:
localStorage.setItem("secondpass.debug.logs.imports.verbose", "1")Enable verbose previews only with non-sensitive fixture data. Never log bearer tokens, authorization values, or private URLs.
Diagnostic owners:
imports/ReaderImportDebug.Diagnostics.tsimports/ReaderRangeRepairDebug.Adapter.tsshell/ReaderStagedSelection.Diagnostics.ts
Run after Reader changes:
npm.cmd test -- --run <focused Reader test paths>
npm.cmd run verify