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
Simplify and enhance reading progress updates:
- Simplify payload structure by flattening location object
- Add epubcfi field to preserve EPUB reading position
- Add percentage field for normalized progress tracking
- Remove unnecessary nested location structure
This aligns with the updated backend API and provides
better support for reflowable EPUB content position tracking.
- Add enhanced image path lookup (findImageInResources) that tries multiple
path variations: full path, relative path, filename only, without extension,
and common extensions (.jpg, .jpeg, .gif, .webp, .svg, .png)
- Fix keyboard navigation by focusing container on reader init
- Implement Kindle-style page display using pageCalculationResult for both
currentPage and totalPages instead of raw spine index
- Store computed currentPage in state during scroll for UI display
- Extend progress API to send character offset, chapter index, and percentage
for accurate cross-device sync (backend already supports these fields)
- reader-navigation.ts: add fallback for mediaItemId from page URL
- reader-navigation.ts: use getCurrentPageFromScroll for accurate page tracking
- reader-navigation.ts: use pageCalculationResult.totalPages for total
- reader-services.ts: validate mediaItemId before API call
- reader-services.ts: avoid double body consumption by checking response.ok
- 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
john-okeefe