docs: add 2025 Bible reader design and implementation plan

docs/plans/2025-01-11-bible-reader-2025-design.md

@@ -0,0 +1,288 @@
+# 2025 Modern Bible Reader Design
+
+**Date**: 2025-01-11
+**Status**: Approved Design
+**Objective**: Create a state-of-the-art, distraction-free Bible reader with comprehensive customization, offline-first capability, and seamless sync across devices.
+
+---
+
+## Core Philosophy
+
+The Bible reader is built around three non-negotiable principles:
+
+1. **Content-first design**: Text is the hero; everything else supports it
+2. **Progressive disclosure**: Basic reading is immediately accessible; advanced features reveal on demand
+3. **Smart offline-first**: Works seamlessly online and offline with automatic sync
+
+---
+
+## Key Features & Requirements
+
+### 1. Reading Interface & Layout
+
+#### Desktop/Tablet Layout
+- **Header**: Minimal - book/chapter reference and reading time estimate (collapses on tablet)
+- **Main text area**: Full width, centered column for readability, generous margins, scalable fonts
+- **Right sidebar**: Chapter overview, verse numbers on hover (collapsible on tablet)
+- **Bottom bar**: Navigation controls (previous/next, search, settings) - subtle and de-emphasized
+
+#### Mobile Layout
+- **Full-screen text** with header and footer hidden until needed
+- **Swipe left/right**: Navigate chapters (intuitive, touch-native)
+- **Tap top third**: Show header; tap bottom third: show navigation controls
+- **Search button**: Always available in floating action button (bottom right)
+
+#### Touch-Optimized Navigation
+- **Tap verse reference** (e.g., "Genesis 1:1") → Search input pre-filled
+- **Keyboard**: Type book name or chapter reference with auto-complete suggestions
+- **Results**: Touch-friendly list with book icons, chapter counts, quick jump buttons
+- **Verse numbers**: Large tap targets (min 48px height on mobile)
+
+### 2. Reading Customization System
+
+#### Smart Preset Profiles (4 curated options)
+
+**Default**: Serif font (Georgia/EB Garamond), comfortable line-height, warm background, optimized spacing
+
+**Dyslexia-friendly**: Dyslexia-optimized font (e.g., Atkinson Hyperlegible), increased letter spacing, sans-serif, larger default size, muted colors
+
+**High contrast**: Bold sans-serif, maximum contrast, dark background with bright text or vice versa, minimalist
+
+**Minimal**: Smallest overhead, pure black text on white, no decorative elements
+
+#### Full Customization Options
+Users can fine-tune any preset:
+- **Font family**: 6-8 curated options (serif, sans-serif, dyslexia-friendly)
+- **Font size**: 12px-32px with live preview
+- **Line height**: 1.4x - 2.2x for readability
+- **Letter spacing**: Normal to 0.15em for spacing
+- **Text alignment**: Left (default), justified, center
+- **Background color**: Light, warm, sepia, dark mode, custom
+- **Text color**: Auto-adjusted based on background for contrast
+- **Margins**: Narrow, normal, wide (affects text width/readability)
+
+#### Customization Persistence
+- Stored in localStorage (device)
+- Synced to cloud (user account)
+- Live preview as user adjusts sliders
+- "Reset to preset" button always available
+- Custom profiles can be saved
+
+### 3. Layered Details Panel & Annotations
+
+**Design principle**: Main text stays clean; detailed information reveals on demand.
+
+#### Panel Behavior
+- Triggered by clicking/tapping a verse
+- Appears as right sidebar (desktop) or bottom sheet (mobile)
+- Verse reference sticky at top, always visible
+
+#### Tabs/Accordions
+- **Notes**: Rich text editor inline, add/edit without leaving reading flow
+- **Highlights**: Color-coded (yellow, orange, pink, blue), one swipe to highlight, another to change color
+- **Cross-References**: Collapsible list showing related verses, tap to jump
+- **Commentary**: Expandable summaries, lazy-loaded, tap to expand full text
+
+#### Annotation Features
+- **Bookmarks**: One-tap heart icon to mark verses as important
+- **Highlights**: Auto-saved with timestamp, searchable across all highlights
+- **Personal Notes**: Rich text editor with optional voice-to-text (mobile)
+- **Cross-References**: System generates suggestions, user can add custom links
+- **Sync behavior**: All annotations sync automatically when online, queued offline
+
+### 4. Smart Offline & Sync Strategy
+
+#### Caching Approach (Not Full Downloads)
+- **On read**: When user opens a chapter, it's cached to IndexedDB
+- **Prefetching**: Automatically cache next 2-3 chapters in background
+- **Cache management**: Keep last 50 chapters read (~5-10MB typical)
+- **Storage limit**: 50MB mobile, 200MB desktop
+- **Expiration**: Auto-expire chapters after 30 days or when quota exceeded
+
+#### Online/Offline Detection
+- Service Worker monitors connection status
+- Seamless switching between online and offline modes
+- Status indicator in header: green (online), yellow (syncing), gray (offline)
+- User can force offline-mode for distraction-free reading
+
+#### Automatic Sync Queue
+- All annotations queued locally on creation
+- Auto-sync to server when connection detected
+- Reading position synced every 30 seconds when online
+- Sync status: "Syncing...", then "Synced ✓" briefly shown
+- User can manually trigger sync from settings
+
+#### Conflict Resolution
+- **Strategy**: Last-modified-timestamp wins
+- **Safety**: No data loss - version history kept server-side
+- **Warning**: User notified if sync fails (rare), manual sync available
+- **User control**: Toggle "offline-first mode" to disable auto-sync
+
+### 5. Component Architecture
+
+```
+BibleReaderApp (main container)
+├── SearchNavigator (search + auto-complete, touch-optimized)
+├── ReadingView (responsive layout management)
+│   ├── Header (book/chapter reference, reading time)
+│   ├── MainContent (centered text column)
+│   │   └── VerseRenderer (verse numbers, highlighting, click handling)
+│   └── NavFooter (prev/next, mobile controls)
+├── VersDetailsPanel (reveals on verse click)
+│   ├── TabsContainer
+│   │   ├── NotesTab (rich editor)
+│   │   ├── HighlightsTab (color selection)
+│   │   ├── CrossRefsTab (linked verses)
+│   │   └── CommentaryTab (lazy-loaded)
+├── ReadingSettings (customization presets + sliders)
+├── OfflineSyncManager (background sync, status indicator)
+└── ServiceWorkerManager (offline detection, cache strategies)
+```
+
+### 6. State Management & Data Flow
+
+#### Local Storage
+- Current book/chapter/verse position
+- User reading preferences (font, size, colors, etc.)
+- Custom preset names and settings
+
+#### IndexedDB
+- Cached Bible chapters with expiration timestamps
+- All annotations: bookmarks, highlights, notes
+- Sync queue (pending changes)
+- Reading history
+
+#### Cloud/Server
+- Master copy of user data (preferences, annotations)
+- Reconciles with local state on sync
+- Manages version history for conflict resolution
+- Provides commentary and cross-reference data
+
+#### Data Flow Sequence
+1. User opens app → Check IndexedDB for cached chapter
+2. If cached and fresh, render immediately (instant UX)
+3. Fetch fresh version from server in background (if online)
+4. User reads, annotations stored locally with sync timestamp
+5. Background sync worker pushes changes when connection available
+6. Service Worker manages cache invalidation and offline fallback
+
+### 7. Error Handling & Resilience
+
+- **Network failures**: Toast notification, automatic retry queue
+- **Sync conflicts**: Timestamp-based resolution, log for user review
+- **Corrupted cache**: Auto-clear and re-fetch from server
+- **Quota exceeded**: Prompt user to clear old cached chapters
+- **Service Worker issues**: Graceful fallback to online-only mode
+
+### 8. Success Metrics
+
+- **Performance**: First render < 500ms (cached), < 1.5s (fresh fetch)
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Mobile**: Touch targets min 48px, responsive down to 320px width
+- **Offline**: Works without internet for last 50 chapters read
+- **Sync**: Auto-sync completes within 5 seconds when online
+- **User satisfaction**: Dyslexia-friendly preset reduces reading friction
+
+---
+
+## Design Decisions Rationale
+
+### Why Smart Caching Over Full Downloads?
+- Reduces initial storage requirements (50MB vs 100+MB for full Bible)
+- Users only cache what they actually read
+- Simpler UX: no complex download management
+- Works great for mobile with limited storage
+
+### Why Presets + Full Customization?
+- Accessibility: Preset handles 90% of needs, reduces choice paralysis
+- Power users: Full control when needed
+- Discovery: Users learn what customization options exist through presets
+- Inclusivity: Dyslexia preset built-in, not an afterthought
+
+### Why Layered Panel for Details?
+- Keeps reading flow uninterrupted
+- Details don't clutter main text
+- Touch-friendly: panel slides in from bottom on mobile
+- Scalable: easy to add more annotation features later
+
+### Why Search-First Navigation?
+- Fastest for known passages (type "Genesis 1" instantly)
+- Modern pattern: matches how users navigate other apps
+- Mobile-friendly: better than scrolling long book lists
+- Supports reference system: users familiar with biblical citations
+
+---
+
+## Implementation Priorities
+
+### Phase 1 (MVP): Core Reading Experience
+- Search-first navigation
+- Responsive reading layout (desktop, tablet, mobile)
+- Basic customization (presets only)
+- Verse highlighting and basic bookmarks
+- Simple offline support (cache as read)
+
+### Phase 2: Rich Annotations
+- Notes editor
+- Color-coded highlights
+- Cross-references
+- Auto-sync (offline/online detection)
+
+### Phase 3: Polish & Advanced
+- Commentary integration
+- Smart linking (theological themes)
+- Advanced customization (full sliders)
+- Sync conflict resolution
+- Analytics and reading history
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- Search filtering and auto-complete logic
+- Sync queue management and conflict resolution
+- Cache expiration logic
+- Customization preset application
+
+### Integration Tests
+- Online/offline switching
+- Cache hit/miss behavior
+- Annotation persistence across sessions
+- Sync conflict resolution
+
+### E2E Tests
+- Complete reading flow (search → read → bookmark → sync)
+- Offline reading with sync on reconnection
+- Cross-device sync behavior
+- Touch navigation on mobile
+- Customization persistence
+
+### Manual Testing
+- Desktop browsers (Chrome, Firefox, Safari)
+- Mobile Safari (iOS)
+- Chrome Mobile (Android)
+- Tablet layouts (iPad, Android tablets)
+- Network throttling (fast 3G, slow 3G, offline)
+
+---
+
+## Future Enhancements
+
+- Voice reading (text-to-speech)
+- Reading plans integration
+- Social sharing (annotated verses)
+- Collaborative notes (study groups)
+- Advanced search (full-text, by topic)
+- Statistics dashboard (chapters read, time spent)
+- Dark mode improvements (true black on OLED)
+- Predictive prefetching (learns reading patterns)
+
+---
+
+## References
+
+- Current implementation: `/root/biblical-guide/components/bible/reader.tsx`
+- Offline support (started): `/root/biblical-guide/components/bible/offline-bible-reader.tsx`
+- Type definitions: `/root/biblical-guide/types/index.ts`
+- API endpoints: `/root/biblical-guide/app/api/bible/`