Create panel-dock-system.ts and navigator-panel.ts in features/
directory with proper init() implementations. Copy offline-manager
and reading-speed-tracker to features/ as well.
Fix bug where context parameter was unused in init() but referenced
throughout the file. Now properly stored as module-level variable
so all gesture handler functions can access it.
Convert view-modes.ts to init(context) pattern with:
- Paginated mode with pagination controls
- Scrolled mode for continuous reading
- Single and double column layouts
- Event-based navigation and mode switching
Complete the Feature Registration Pattern refactoring across all reader
modules. Each feature now exports an init(context) function and uses the
event-based architecture for loose coupling.
## Comic Features (6 files)
- background-color.ts: Background color picker with toggle
- chapter-markers.ts: Visual chapter indicators
- page-cache.ts: 5-page ahead prefetch with cleanup
- page-order.ts: Auto-detect Japanese vs Western order
- page-scrubber.ts: Quick navigation slider
- panel-gap.ts: Adjustable panel gap controls
## Ebook Features (6 files)
- copy-handler.ts: Text copying with citation
- dictionary-popup.ts: Word lookup integration
- font-loader.ts: 8 bundled libre fonts
- search.ts: Full-text search across spine
- typography-engine.ts: Font rendering and hyphenation
## Manga Features (4 files)
- reading-direction.ts: RTL/LTR/vertical detection
- rtl-navigator.ts: Reversed page turn direction
- settings.ts: Webtoon mode and transitions
- vertical-scroll-mode.ts: Infinite scroll with lazy loading
## PDF Features (3 files)
- pdf-navigation.ts: Page turning, zoom, fit modes
- pdf-text-selection.ts: Highlight creation via backend
- annotation-layer.ts: Render highlights and notes
## Root-Level Features (3 files)
- offline-manager.ts: PWA service worker and sync
- reading-speed-tracker.ts: Pages/words per minute tracking
- settings-manager.ts: Per-user settings with localStorage fallback
## Core Infrastructure (1 file)
- parser-manager.ts: Fixed import paths for all parsers
## Key Changes
- All features use init(context) pattern
- Event-based communication via context.events.on/emit
- No direct DOM manipulation in feature exports
- State managed within feature closures
- Clean initialization and teardown
- Zero functionality lost - all features preserved
Total: 23 files converted to unified architecture
- Delete gestures.ts: replaced by features/gestures.ts
- Delete keyboard-shortcuts.ts: replaced by features/keyboard-shortcuts.ts
- Delete progress-indicator.ts: replaced by features/progress-indicator.ts
- Old files used callback pattern, new files use init(context) pattern
- templates/reader.templ: add script tag to load main.js
- Enables reader shell and Alpine components to initialize
- internal/handlers/reader.go: add GetMediaReadingProgress handler
- Backend now supports fetching reading progress via API
- GET /api/media-items/:id/progress returns current progress
- Import reader/reader-shell to load reader functionality
- Ensures reader JavaScript is included in main.js bundle
- Reader features and Alpine components are now initialized
- Replace callback-based architecture with Feature Registration Pattern
- Add feature registry for modular feature initialization
- Create createNavigationAPI() for unified page/chapter navigation
- Implement renderCurrentPage() for PDF/comic/manga rendering
- Add updateProgress() to sync reading progress to backend
- Support ebook, PDF, comic, and manga readers in single interface
- Remove 600+ lines of callback wiring code
- reader-shell now acts as lightweight orchestrator
- Delegates specific functionality to feature modules
- Parse ebooks using parser-manager with format routing
- Initialize readers based on library type from metadata
- Update pdfjs-wrapper.ts: add initializePDFReader() function
- Configure PDF.js worker, standard fonts, and cmaps
- Load PDF documents and extract metadata
- Implement page rendering with canvas
- Support PDF page navigation and zoom
- Return PDFReader with current page tracking
- Integrates with feature-based reader architecture
- Update copy-handler.ts: export enableContextMenuCopy for text selection
- Update typography-engine.ts: export applyTypography and getFontStack
- Update view-modes.ts: export setViewMode and getCurrentViewMode
- Enable text copying with citation for ebooks
- Add typography engine with font loading and text formatting
- Add view mode support (paginated, scrolled, single/dual column)
- These features integrate with settings-manager for customization
- Add getReaderMetadata() to fetch media item metadata
- Add updateReadingProgress() to sync reading progress to backend
- Export ReaderMetadata and ReadingProgress types
- Enable reader to communicate with Go backend
- Move gestures.ts to features/ with init(context) pattern
- Move keyboard-shortcuts.ts to features/ with init(context) pattern
- Remove callback-based architecture
- Features now subscribe to events via ReaderContext
- Support touch gestures (swipe, tap, double-tap, pinch-to-zoom)
- Support keyboard shortcuts (navigation, zoom, fullscreen, bookmarks)
- Add panel-aware navigation for comics/manga
- Keyboard shortcuts include chapter navigation
- Add reader-context.ts: defines ReaderContext interface and factory
- Add reader-events.ts: event bus for feature communication
- Add reader-state.ts: centralized state management
- Add reader-navigation.ts: unified navigation and rendering API
- Add reader-services.ts: shared services (progress, chapters)
- Establishes foundation for Feature Registration Pattern
- settings.ts: Manga reading settings and configuration
- reading-direction.ts: Right-to-left reading direction support
- vertical-scroll-mode.ts: Webtoon/vertical scroll reading mode
- rtl-navigator.ts: RTL navigation for manga
- panel-detection.service.ts: Main orchestration with OpenCV → ML → Grid fallback chain
- panel-detection.opencv.ts: Edge detection using OpenCV for 80% of comics
- panel-detection.ml.ts: COCO-SSD object detection for irregular layouts
- panel-detector.ts: Unified detector interface
- panel-editor.ts: Manual panel editor UI for user corrections
- panel-ml-detector.ts: TensorFlow.js integration for ML detection
- page-cache.ts: Efficient page caching for large comics
- background-color.ts: Auto-detect comic background color
- chapter-markers.ts: Chapter detection and navigation
- page-scrubber.ts: Fast page scrubbing/thumbnails
- page-order.ts: RTL/LTR page ordering support
- panel-gap.ts: Panel gap detection
- Add @techstark/opencv-js for OpenCV-based edge detection
- Add @tensorflow/tfjs for ML model inference
- Add @tensorflow-models/coco-ssd for object detection fallback
- All packages are lazy-loaded to optimize initial load time
- Rename font files from VariableFont_wght/opsz,wght to Variable format
- Add reader-fonts.css with @font-face definitions for 10 serif fonts
- Fonts: Crimson Pro, EB Garamond, Literata, Noto Serif, Source Serif 4
- Each font includes regular and italic variants
Added Section 8: Manga Reader Implementation with 5 subsections:
8.1 RTL Navigator (Right-to-Left Reading)
- Reverse page turn direction for traditional manga
- Proper key bindings for RTL navigation
- Progress tracking adapted for RTL
8.2 Vertical Scroll Mode (Webtoon Style)
- Infinite vertical scroll for webtoons/manhwa
- Lazy loading with threshold-based prefetching
- Scroll position to page number mapping
- Memory-efficient blob URL cleanup
8.3 Reading Direction Detection
- Auto-detection from metadata (manga_type, reading_direction)
- Filename-based heuristics (manga, manhwa, webtoon)
- User preference support with fallback
- Integration with database schema
8.4 Manga Settings Integration
- Reading direction preference (auto/ltr/rtl/vertical)
- Vertical scroll speed control
- RTL page transition effects
- Settings persistence via API
8.5 Manga Page Cache (shared with comics)
- 5-page ahead prefetching
- Memory management with cleanup
- Shared caching strategy for comics and manga
This fills the gap where manga was architecturally planned but had no
implementation details. Database schema, types, and UI already supported
manga - now the implementation is documented.
Plan now has complete coverage for all 4 media types: ebook, comic, manga, pdf
Removed 3 duplicate/incomplete sections:
- Section 5.8 (incomplete typography-engine.ts without font support)
- Section 5.12 (duplicate search.ts - kept version in section 5.9)
- Section 5.10.4 (incomplete reader.templ template - kept complete version in section 12.1)
The plan now contains only complete, implementation-ready sections:
- Complete typography-engine.ts with getFontStack() and all 8 bundled fonts
- Complete search.ts matching actual implementation with export functions
- Complete reader.templ SSR template with Alpine.js integration
This resolves confusion about which version to follow and ensures the plan
matches the actual codebase implementation.
Add 8 libre font families optimized for extended reading:
Variable fonts (continuous weight range):
- Literata: Modern book typeface for Google Books
- Crimson Pro: Screen-optimized serif
- Source Serif 4: Adobe's professional serif with optical size axis
- EB Garamond: Classic elegance with smooth italics
Static fonts (multiple weights):
- Libertinus Serif: Academic/technical with excellent math support
- Noto Serif: Maximum language coverage
- Charis SIL: Multilingual specialist with extensive Latin support
- IBM Plex Serif: IBM's corporate serif family
All fonts provided in WOFF2 format for optimal compression. Variable fonts
offer continuous weight ranges (200-900) while static fonts provide specific
weights for predictable rendering. Total footprint: ~7.5MB.
These fonts provide excellent readability for extended reading sessions
across all supported languages and scripts.
- epub-parser.ts: EPUB2/EPUB3 parsing with container, encryption, and navigation support
- fb2-parser.ts: FictionBook 2.0/XML parser with metadata and TOC extraction
- txt-parser.ts: Plain text parser with encoding detection and chapter detection
- html-parser.ts: HTML document parser with metadata and structure extraction
All parsers convert their respective formats to the Common Intermediate Format (CIF)
for universal handling. Client-side parsing provides instant access without server
processing for common ebook formats.
Phase 1 focuses on these client-side parsers. Server-side parsers for MOBI, AZW3,
DOCX, and RTF will be implemented in Phase 2.5.
- html-renderer.ts: HTML content rendering with security sanitization and font loading
- typography-engine.ts: Advanced typography with ligatures, hyphenation, and optimization
- cfi-navigator.ts: EPUB CFI navigation for precise location tracking and jumping
- search.ts: Full-text search with highlighting across ebook content
The ebook reader provides a premium reading experience with:
- Clean HTML rendering with XSS protection
- Publisher-quality typography with custom fonts
- Precise CFI-based navigation for EPUBs
- Fast full-text search with result highlighting
This handles EPUB, FB2, TXT, and HTML ebook formats client-side.
- reader-shell.ts: Main initialization, Alpine.js integration, media type detection
- progress-indicator.ts: Reading progress tracking and display components
- settings-manager.ts: User settings persistence and retrieval
- panel-dock-system.ts: Dockable panel management with drag/drop and collapse
- parser-manager.ts: Parser selection and format detection system
These core modules provide the foundation for all reader types with
shared functionality for progress tracking, settings management, and
the flexible panel docking system.
Define comprehensive TypeScript interfaces for reader functionality:
- Common Intermediate Format (CIF) for universal ebook representation
- Parser capabilities and format detection types
- Reader metadata and chapter structure interfaces
- Panel layout and dock system types
- Reading progress and settings interfaces
- Dictionary and search functionality types
These types provide the foundation for type-safe reader implementation
across all media types (ebook, comic, manga, pdf).
- Update Section 1.4 with detailed data flow diagram showing SSR skeleton approach
- Add Section 1.5 documenting SSR vs Client-Side responsibilities
- Clarify that SSR provides HTML shell with initial data, TypeScript handles UI
- Document specific examples of what SSR renders vs what TypeScript manages
- Remove confusing 'embedded JSON' terminology for clearer hybrid approach
These changes make the implementation plan more precise and implementation-ready
by clearly separating SSR (Go template) from client-side (TypeScript) concerns.
- Fix function signatures in reader.go (c echo.Context -> c *echo.Context)
- Replace non-existent UserHasLibraryAccess with GetUserVisibleLibraries pattern
- Implement SSR reader route in router/reader.go with proper access control
- Add inline library access checking following existing codebase patterns
- Fix ReadingProgress struct to use LastReadAt instead of CreatedAt/UpdatedAt
- Ensure all reader endpoints use consistent library access validation
This provides the backend foundation for the reader feature with proper
access control and SSR rendering capabilities.
- Add panel_layout to getDefaultSettings() for dockable panels
- Remove template rendering from ShowReader (router handles SSR)
- Fix pgtype.Int4 marshaling to JSON (no explicit int conversion)
- Remove unused strings import from handlers
- Create templates/reader_templ.go with main Reader() function
- Implement reader shell with top/bottom chrome bars
- Add dockable panels: TOC, Settings (left side)
- Add dockable panels: Navigator, Bookmarks (right side)
- Include panel lock and window-shade toggle buttons
- Support all media types: ebook, comic, manga, pdf
- Initialize reader shell via Alpine.js data attribute
- Add modular dockable panel architecture with:
- Panel dock system (drag, lock, snap-back, window-shade)
- TOC, Settings, Navigator, Bookmarks as dockable components
- Lock toggle to prevent accidental moves
- Snap-back to last valid position if dropped in invalid area
- Per-user layout stored in reader_settings JSONB
- Update TypeScript types with PanelLayoutSettings and PanelState
- Add panel-dock-system.ts implementation to plan
- Add navigator-panel.ts for Affinity-style page navigation
- Update reader template with dockable panels and lock buttons
- Add Section 2.4 with database/Go implementation issues and fixes
- Document schema changes (DECIMAL -> REAL)
- Document all type fixes needed in reader.go
- Changed words_per_minute, pages_per_minute, total_reading_minutes from DECIMAL(6,2) / DECIMAL(8,2) to REAL
- REAL (pgtype.Float4) is sufficient for reading statistics and simplifies Go code
- No precision loss for typical reading speed values (200-400 wpm, 0.5-3.0 pages/min)
Major Architecture Changes:
- Added PDF support (Mozilla pdf.js) with text selection, highlights, search, bookmarks
- Universal reader with pluggable parser pipeline for all reflowable ebooks
- Common Intermediate Format (CIF) to standardize ebook parsing
- Server-side parsing for complex formats (MOBI, AZW3, DOCX, RTF)
- Client-side parsing for simple formats (EPUB, FB2, TXT, HTML)
- PDF-specific features: TOC navigation, bookmarks, dual-page view, mini-map
Procedural TypeScript:
- Refactored all code to follow PROJECT_GUIDELINES.md (no classes, no OOP)
- Functions and modules instead of classes
- Functional techniques where appropriate
New Components:
- Parser manager (router) to detect format and route to appropriate parser
- CIF types for universal ebook representation
- PDF reader with full feature set (text-layer, annotation, search, etc.)
- Server-side Go handlers for MOBI/AZW3/DOCX/RTF parsing
Database Schema:
- Added pdf_bookmarks table for custom PDF bookmarks
API Routes:
- Added PDF outline/TOC endpoint
- Added PDF thumbnail endpoint for mini-map
Theming:
- Added PDF-specific reading themes (5 options: light, sepia, dark, night, high-contrast)
- Hybrid approach maintained: chrome_theme for UI, reading_theme for content
Add <!-- markdownlint-disable MD013 --> comment at the top to prevent
vim from loading diagnostics for this file, matching the pattern used
in other documentation files.
john-okeefe