BREAKING CHANGE: Unify ebook reader type system to match actual data structures
Problem:
- ReflowableBook type had direct properties (spine, resources, toc, metadata)
- UniversalReader wraps EbookCIF in cif property with runtime state
- Type mismatch caused unsafe 'as any' casts and runtime errors
- Two conflicting UniversalReader definitions existed (reader-shell vs reader-context)
Root Cause:
- Parsers return EbookCIF (nested structure)
- ReflowableBook expected flat structure
- Code mixed both approaches causing confusion
Changes:
Type System Updates:
- Replace all ReflowableBook references with UniversalReader
- Remove duplicate UniversalReader definition in reader-context.ts
- Import UniversalReader from canonical source (reader-shell.ts)
- Update all function signatures across reflowable module
Property Access Patterns:
- book.cif.spine instead of book.spine
- book.cif.resources instead of book.resources
- book.cif.toc instead of book.toc
- book.cif.metadata instead of book.metadata
Fixed Modules:
- reader-shell.ts: UniversalReader object construction
- reader-context.ts: Remove duplicate interface, import from reader-shell
- reader-navigation.ts: Remove unsafe type casts, fix property access
- reader-services.ts: Align with UniversalReader structure
- reflowable/navigation.ts: Update all navigation function signatures
- reflowable/progress-tracker.ts: Update tracker function signatures
- reflowable/parser.ts: Return UniversalReader with proper structure
- reflowable/page-calculator.ts: Update calculation function signatures
- reflowable/ebook/search.ts: Fix property access patterns
- types/reader.d.ts: Remove duplicate type definitions
Impact:
- ✅ Type-safe throughout ebook reader
- ✅ Matches actual data structures from parsers
- ✅ No more unsafe type casts
- ✅ Single source of truth for UniversalReader
- ✅ Aligns with EbookCIF format from API/parsers
Files changed: 10
Lines changed: +320, -180
Implement complete modularization of reader code by separating format-specific
functionality into dedicated modules. This replaces the monolithic structure
with a clean, maintainable architecture that separates concerns by format type.
## New Architecture
### Format-Specific Modules
- **formats/reflowable/**: EPUB, FB2, TXT, HTML (page-based pagination)
- types.ts: Shared type definitions for reflowable formats
- page-calculator.ts: Word-count based pagination with HTML slicing
- navigation.ts: Page-based navigation logic
- progress-tracker.ts: CFI-based progress tracking
- content-renderer.ts: DOM rendering for page content
- parser.ts: Unified parser interface for all reflowable formats
- ebook/**: Migrated ebook-specific features
- **formats/pdf/**: PDF format support
- Core PDF functionality (navigation, text selection, annotations)
- Advanced features (bookmarks, search, outlines, dual-page)
- Page cache and rendering optimizations
- **formats/comic/**: Comic format support
- Background color, chapter markers, page caching
- Page ordering, gap adjustments
- **formats/manga/**: Manga format support
- RTL navigation, vertical scrolling, reading direction
## Key Improvements
1. **Separation of Concerns**: Each format has its own dedicated module
2. **No Circular Dependencies**: Clean import structure
3. **Type Safety**: Comprehensive TypeScript types throughout
4. **Functional Programming**: Pure functions, no OOP complexity
5. **Scalability**: Easy to add new formats without touching core code
## Migration Path
- Old format-specific code in reader/, ebook/, pdf/, comic/, manga/
- New code in formats/[format]/ structure
- Maintains backward compatibility during transition
- Core reader logic remains format-agnostic
This change enables the implementation of page-based pagination for reflowable
formats while keeping PDF, comic, and manga functionality unchanged.
john-okeefe