john-okeefe
d2f87254e0
Add complete implementation guide for reader modularization and page-based pagination system. This plan provides production-ready code with zero TODOs or deferred work. ## Features Implemented ### 1. Reader Modularization - Separate format-specific modules (reflowable, pdf, comic, manga) - Format-agnostic UI components - Clean separation of concerns with no OOP ### 2. Page-Based Pagination for Reflowable Formats - Pre-calculated page boundaries using word count estimation - HTML page slicing with DOM-based extraction - Discrete page navigation (no scrolling within pages) - Accurate progress tracking using EPUB CFI ### 3. EPUB CFI Implementation - Full W3C EPUB CFI spec compliance - Proper special character escaping - CFI parsing and generation - Standards-based progress tracking ## Implementation Details ### New Files Created (8 total) - formats/reflowable/types.ts - Type definitions - formats/reflowable/page-calculator.ts - Word count pagination with HTML slicing - formats/reflowable/navigation.ts - Page-based navigation logic - formats/reflowable/progress-tracker.ts - CFI progress tracking - formats/reflowable/content-renderer.ts - DOM rendering - formats/reflowable/parser.ts - Unified parser interface - ui/page-display.ts - Page X of Y display - ui/progress-indicator.ts - Progress bar (moved from features/) ### Files Modified (2 total) - reader-navigation.ts - Integrate reflowable navigation - reader-shell.ts - Initialize reflowable books with pagination ### Key Algorithms #### HTML Page Slicing - Uses DOMParser to parse HTML content - Traverses text nodes and calculates cumulative character counts - Extracts HTML slices between character boundaries - Preserves HTML structure and tag boundaries #### CFI Generation - Follows W3C EPUB CFI specification - Escapes special characters: [\](),;= - Supports spine item IDs: /6/4[chapter1] - Format: epubcfi(/6/spine_index!/path/element:offset) #### Word Count Pagination - Estimates words per page based on viewport size and font settings - Adjusts for font size, line height, and viewport area - Splits spine content into page-sized chunks - Creates page-to-spine mappings ## Technical Improvements - No unused variables or imports - No circular dependencies - Proper ES6 imports throughout - All functions are pure (no side effects) - Bug fixes: Fixed spine lookup in getPageContent() ## Migration Path 1. Create new directory structure (formats/, ui/) 2. Move existing format-specific code 3. Create new reflowable module files 4. Update existing integration files 5. Update imports across codebase 6. Delete obsolete files 7. Test all formats ## Compatibility - PDF reader: Unchanged, continues working - Comic reader: Unchanged, continues working - Manga reader: Unchanged, continues working - Panel detection: Unchanged, continues working This plan is ready for immediate implementation with no additional research or code development required.
📚 Bookhoard
A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring universal cross-device sync, beautiful dark themes, and comprehensive media management.
✨ Why Bookhoard?
🔄 Universal Sync: Your reading progress, highlights, and notes sync automatically across all your devices - KOReader, Kobo, web, and mobile.
📱 Multi-Library: Organize your ebooks, comics, and manga with per-library folders and smart collections.
🎨 Beautiful UI: 11 gorgeous dark themes with responsive design that works on any device.
🔒 Secure: JWT authentication, bcrypt password hashing, rate limiting, and no passwords on devices.
🚀 Quick Start
Prerequisites
- Podman (recommended) or Docker
- 5 minutes of your time
Installation
# 1. Clone the repository
git clone https://github.com/yourusername/bookhoard.git
cd bookhoard
# 2. Set up environment
cp .env.example .env
# Generate secure passwords (no special characters):
# JWT_SECRET: openssl rand -hex 32
# DBPASS: openssl rand -hex 16
# Edit .env with your generated values
# 3. Start the server
podman-compose up --build -d # or: docker-compose up --build -d
# 4. Open your browser
open http://localhost:8765
The first user to register automatically becomes an admin.
📖 Key Features
Universal Cross-Platform Sync
- Real-Time Progress: Turn a page on your Kindle, see it on your phone
- Format-Aware: EPUB CFI, page numbers, percentages - all handled correctly
- Offline Queue: Changes sync when you reconnect, priority-processed
- Conflict Resolution: Smart handling when same book read on multiple devices
- Book Matching: Automatic matching using SHA-256, ISBN, UUID
- OPDS Catalog: Wireless book delivery to e-readers over Wi-Fi
- Format Conversion: On-the-fly EPUB→KEPUB for Kobo devices
Media Management
- Calibre Integration: Automatic metadata import from Calibre
metadata.opfsidecar files - Smart Search: Partial matching with fuzzy search fallback for typos
- Advanced Filtering: Filter by author, series, genre, language, year, cover images
- Dynamic Sorting: By title, author, date added, published date, page count, series
- Rich Metadata: Title, author, series, publisher, ISBN, language, edition, tags
- 5-Star Ratings: Half-star precision (1-10 scale)
- Notes & Highlights: Color-coded annotations with linked notes
- Usage Analytics: Reading statistics, device usage, popular books
Smart Collections
- Auto-Assign Rules: Automatically add books based on genre, author, series, tags, language, publisher, year
- Device Shelf Mappings: Sync collections to Kobo shelves and KOReader categories
- Test Before Creating: Preview which books match your rules
Library Organization
- Multi-Library Support: Ebooks, Comics, and Manga with type-specific file formats
- Multiple Folders: Add multiple scanning folders per library
- Visibility Control: Admins control which libraries each user can see
- Background Scanning: Auto-scan with per-user frequency settings
- Watch Mode: Real-time file system monitoring for instant updates
Security
- JWT Authentication: Short-lived access tokens (1 hour) with refresh tokens (7 days)
- Strong Passwords: Complexity requirements enforced (8+ chars, uppercase, lowercase, number, special)
- Account Lockout: 5 failed attempts = 15-minute lockout
- Rate Limiting: 10 requests/minute on auth endpoints
- Input Validation: Comprehensive validation on all inputs
- No Passwords on Devices: Web-based device approval with QR codes
📚 Documentation
For Users & Self-Hosters
- docs/user/calibre-integration.md - Calibre library integration
- docs/user/sync-guide.md - Understanding and using universal sync
- docs/user/devices/kobo-setup.md - Kobo e-reader configuration
- docs/user/devices/koreader-setup.md - KOReader configuration
- docs/user/user-guide.md - General user guide
- docs/user/admin-guide.md - Admin features and configuration
- docs/user/settings-guide.md - Settings and preferences
For Developers
- docs/developer/api/api-reference.md - Complete API documentation
- docs/contributing/DEVELOPMENT.md - Development workflow
🎯 Supported Devices
| Platform | Sync | OPDS | Status |
|---|---|---|---|
| Web Browser | ✅ | ✅ | Full support |
| KOReader | ✅ | ✅ | Kindle, Kobo, PocketBook |
| Kobo Devices | ✅ | ✅ | Clara, Libra, Sage, etc. |
| Mobile Apps | 🚧 | 🚧 | Coming Q2 2026 |
🛠 Tech Stack
- Backend: Go 1.25+ with Echo framework
- Database: PostgreSQL 15+ with pgx v5
- Frontend: HTMX + Tailwind CSS + Templ
- Auth: JWT tokens with bcrypt password hashing
- Container: Podman (Docker compatible)
🧪 Testing
# Run all tests
make test-all
# Run integration tests (with test mode)
make test-integration
# Run Bruno OpenCollection YAML API tests
npm install -g @usebruno/cli
bruno run
📊 Project Status
Version: 1.0
License: GPL-3.0
Status: Production-ready ✅
🤝 Contributing
We welcome contributions! Please see docs/DEVELOPMENT.md for guidelines.
📄 License
GPL-3.0 - See LICENSE file for details.
Built with ❤️ using Go, PostgreSQL, HTMX, and Tailwind CSS