Skip to main content

Scripture Reader

The scripture reader is the heart of GospeLib. It is designed around a central premise: every tool is present but invisible until needed. Power lives one gesture below the surface of a clean, paper-like reading environment.

Overview​

The reader displays all LDS canonical texts -- Book of Mormon, Doctrine and Covenants, Pearl of Great Price, and KJV Bible -- along with pseudepigraphical texts (1 Enoch, Jubilees, Testaments of the Twelve Patriarchs, and 20+ ancient texts). Users navigate by book and chapter, with continuous scrolling across chapter boundaries.

The reading surface uses a "paper" personality: warm texture, parchment-toned background, and warm shadows. The surrounding application chrome uses a clean, flat "chrome" personality. This two-surface system creates visual separation between sacred content and UI controls.

Reading Modes​

The reader supports three primary modes:

ModePurposeActivation
ReadingDefault clean reading experienceDefault
StudyReveals annotation tools, cross-references, and study sidebarLong-press a verse
InterlinearWord-by-word original language with transliteration and glossScholar tier, toolbar toggle

Reading Density​

Three density presets control line height, paragraph spacing, and font size:

  • Spacious -- Maximum whitespace, ideal for contemplative reading
  • Comfortable -- Balanced default
  • Compact -- Dense layout for reference work and comparison

Density transitions animate over 300ms with scroll position preservation.

Theming​

Three theme modes with distinct visual characters:

  • Light -- Warm parchment tones, the default experience
  • Study Dark -- Deep navy background with warm text, reduced eye strain for extended study
  • Blackout -- True black background, WCAG AAA contrast, OLED-friendly

A "Night Warm" independent overlay adds amber tinting for late-night reading, available in any theme mode.

Chrome Behavior​

The reader chrome (top bar, bottom bar, toolbars) auto-hides after 3 seconds of reading to maximize the text area. Chrome reappears on:

  • Single-tap in the margin area
  • Scrolling up (configurable)
  • Any toolbar interaction

The bottom bar shows chapter navigation (previous/next) and a reading progress indicator. The top bar shows the current location as a breadcrumb (Corpus > Book > Chapter) with a flyout navigation panel.

Within a Book​

Continuous bidirectional infinite scroll loads chapters as the user reads. The useInfiniteScroll hook uses IntersectionObserver with TanStack Query prefetching (1 chapter ahead and behind). A 5-second dwell-time threshold prevents accidental chapter commits when scrolling quickly.

Across Books​

The breadcrumb minimap navigation panel provides a flyout below the top bar with horizontal book silhouette bars, proportional chapter segments, three zoom levels (corpus, volume/book, chapter), and drag-to-scrub with verse preview.

The command palette (Cmd+K) provides three-tier ranked results: instant fuzzy search, FalkorDB context suggestions, and AI suggestions. Reference parsing recognizes standard scripture citation formats.

Visual Navigation Aids​

  • Verse Map -- Fixed left-edge canvas strip (8px, expands on hover) with 8 marker types: verse ticks, viewport indicator, current verse, highlight bars, note dots, bookmark flags, cross-ref density diamonds, and search match ticks
  • Three-Column Minimap -- Fixed right-edge strip showing chapters in book, books in volume, and all volumes
  • Page Gutters -- Scrolling margins flanking the scripture column with annotation markers at exact verse positions

Focus Modes​

Three progressive levels of immersion:

  1. Minimize UI (Shift+\) -- Collapse sidebars and top bar, toolbar at 30% opacity
  2. Focus Mode (F) -- Full-bleed per-pane layout, 680px max-width for scripture
  3. Full Focus (F again) -- Maximum immersion, all UI removed

Escape steps back one level.

Deep Dive: Architecture​

The reader is implemented as a Next.js page at apps/web/app/(app)/reader/. The core components are:

  • ScripturePage -- Paper surface with scroll and gesture detection
  • VerseBlock -- Verse number + text + annotation layers
  • ChapterHeader -- Drop cap, corpus color bar, three style variants
  • ReaderChrome -- Auto-hide/summon wrapper for top and bottom bars

The reader loads scripture data through the content service via @gospelib/sdk, which queries the FalkorDB graph. Passage responses include the text, cross-references, footnotes, word alignments (for interlinear mode), and manuscript witnesses.

Plugins extend the reader through contribution types defined in the plugin manifest: pane types, sidebar widgets, toolbar actions, hover card tabs, gutter markers, and context menu items.