crosspoint-reader/docs/branch-comparison-summary.md

Branch Comparison Summary: crosspoint-ef vs 0.16.0

This document provides a comprehensive comparison between the crosspoint-ef branch and the upstream 0.16.0 release for merge planning and implementation decisions.

Branch History

Branch	Base	Commits Since Base	Status
crosspoint-ef	0.15.0	90+	Active development
0.16.0	0.15.0	30	Released

Both branches diverged from 0.15.0 at commit 3ce11f14.

---

Feature Comparison Matrix

Major Features

Feature	crosspoint-ef	0.16.0	Notes
Dictionary Support	Yes	No	StarDict format with word selection
Bookmark System	Yes	No	Per-book bookmarks with visual indicator
Quick Menu	Yes	No	Power button quick access
Library Search	Yes	No	Character picker with weighted search
CSS Parsing	Yes	No	Element, class, inline styles
Inline Images (PNG/JPEG)	Yes	No	With caching and dithering
Custom Fonts	Yes	No	Atkinson Hyperlegible, Fern Micro
Enhanced Web Server	Yes	Partial	File ops, MD5 API, mDNS
Companion App API	Yes	No	Deep links, WebSocket uploads
Reading Lists	Yes	No	With pinning support
Tab Bar Enhancements	Yes	No	Scrolling, overflow indicators
High Contrast Mode	Yes	No	System-wide
Bezel Compensation	Yes	No	Edge defect compensation
Sleep Screen Edge Detection	Yes	No	Dominant color fill
Recents Improvements	Yes	No	Badges, removal, clearing
Progress Bar Status Bar	Yes	Yes	Same feature
Spanish Hyphenation	No	Yes	Missing in crosspoint-ef
XTC/XTCH Author Extraction	No	Yes	Missing in crosspoint-ef
OTA Rework	No	Yes	Different implementation
KOReader MD5 Binary Matching	No	Yes	Missing in crosspoint-ef
Relative Position on Settings Change	No	Yes	Missing in crosspoint-ef
Multi-line Keyboard Entry	No	Yes	Missing in crosspoint-ef
Italics on Image Alt	No	Yes	Missing in crosspoint-ef
Page Turn on Button Press (UX)	No	Yes	When chapter skip disabled

Bug Fixes

Fix	crosspoint-ef	0.16.0	Notes
Large EPUB indexing O(n²)→O(n)	Yes	Yes	Same fix
Settings validation on read	Yes	Yes	Same fix
Line break fixes	Yes	Yes	Similar fixes
Rotate origin in drawImage	Yes	Yes	Same fix
Short-press power wakeup	Yes	Yes	Same fix
TXT books in recent tab	Yes	Yes	Same fix
B&W filters for covers	Yes	Yes	Same fix
Cover fit artifacts	Yes	Yes	Same fix
Grayscale state corruption	Yes	No	Unique to crosspoint-ef
Memory graceful degradation	Yes	No	Unique to crosspoint-ef
Chapter Selection UI (KOReader)	No	Yes	Missing in crosspoint-ef
Front layout in mapLabels()	No	Yes	Missing in crosspoint-ef

---

Files Changed Summary

crosspoint-ef Unique Files (New)

Category	Files
Dictionary	src/activities/dictionary/ (8 files), lib/StarDict/ (4 files)
Bookmarks	src/BookmarkStore.cpp/.h, src/activities/home/BookmarkListActivity.cpp/.h
Quick Menu	src/activities/util/QuickMenuActivity.cpp/.h
CSS	lib/Epub/Epub/css/ (3 files)
Images	lib/Epub/Epub/blocks/ImageBlock.cpp/.h, lib/Epub/Epub/converters/ (6 files)
Custom Fonts	src/customFonts.cpp, src/fontIds.h, lib/EpdFont/builtinFonts/custom/ (50+ files)
Utils	src/util/Md5Utils.cpp/.h, src/util/StringUtils.cpp/.h
Lists	src/BookListStore.cpp/.h
Docs	docs/webserver-api-reference.md, docs/companion-app-deep-link-API.md, docs/troubleshooting.md

crosspoint-ef Modified Files (Significant Changes)

File	Changes
src/network/CrossPointWebServer.cpp	+1083 lines (file ops, API, WebSocket)
src/activities/home/MyLibraryActivity.cpp	+700 lines (tabs, search, badges)
src/main.cpp	+255 lines (feature integration)
lib/GfxRenderer/GfxRenderer.cpp	+439 lines (contrast, bezel)
lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp	+596 lines (CSS integration)
src/CrossPointSettings.cpp/.h	New settings fields
src/activities/boot_sleep/SleepActivity.cpp	Edge detection, caching
src/RecentBooksStore.cpp	Badges, removal, metadata
src/ScreenComponents.cpp	Tab bar enhancements

0.16.0 Unique Files/Changes

File	Description
lib/Epub/Epub/hyphenation/generated/hyph-es.trie.h	Spanish hyphenation (removed in ef)
lib/KOReaderSync/	KOReader credential handling (removed in ef)
src/network/OtaUpdater.cpp	OTA rework

---

Merge Strategy Recommendations

Phase 1: Cherry-pick 0.16.0 Fixes into crosspoint-ef

Low Risk - Recommended First:

1. Spanish hyphenation support (#558)

   • Add hyph-es.trie.h back
   • Update LanguageRegistry.cpp

2. Render keyboard entry over multiple lines (#567)

   • Update KeyboardEntryActivity.cpp

3. Correctly render italics on image alt (#569)

   • Minimal change to text rendering

4. Page turning on button pressed (#451)

   • UX improvement when chapter skip disabled

5. Missing front layout in mapLabels() (#564)

   • Bug fix for button mapping

Medium Risk:

6. KOReader document MD5 binary matching (#529)

   • May conflict with MD5Utils changes

7. Chapter Selection UI bugs (#501)

   • Review for conflicts with tab bar changes

8. Relative position on settings change (#486)

   • Reader state management change

Higher Risk:

9. OTA feature rework (#509)

   • Compare implementations, may need reconciliation
   • crosspoint-ef has different OTA changes

10. Extract author from XTC/XTCH (#563)

    • XTC format was removed in crosspoint-ef
    • Evaluate if needed

Phase 2: Potential Upstream Contributions from crosspoint-ef

High Value, Moderate Complexity:

1. Dictionary Support

   • Self-contained feature
   • New files, minimal integration points
   • Requires shipping dictionary data

2. Bookmark System

   • Clean implementation
   • New files with reader integration

3. Quick Menu

   • Simple overlay feature
   • Depends on bookmark and dictionary

4. CSS Parsing

   • Significant EPUB improvement
   • Well-isolated in lib/Epub/Epub/css/

High Value, Higher Complexity:

5. Inline Image Support

   • Major EPUB enhancement
   • Multiple new converters
   • Memory management considerations

6. Library Search

   • Integrated into MyLibraryActivity
   • Tab bar changes included

7. Enhanced Web Server

   • Large changes to CrossPointWebServer
   • New API endpoints
   • WebSocket uploads

Medium Value:

8. Custom Fonts

   • Large binary additions (font headers)
   • Clean integration

9. Display Enhancements

   • High contrast, bezel compensation
   • Settings additions

10. Reading Lists

    • New feature with web API

---

Potential Conflicts

High Conflict Risk

Area	crosspoint-ef	0.16.0	Resolution
MyLibraryActivity.cpp	Major restructure	Minor fixes	Manual merge required
CrossPointWebServer.cpp	Extensive additions	Minimal changes	crosspoint-ef likely compatible
CrossPointSettings.h	Many new fields	Few changes	Additive, low conflict
main.cpp	Feature integration	Minor changes	Review integration points
OtaUpdater.cpp	Modified	Reworked (#509)	Compare implementations

Low Conflict Risk

Area	Notes
Dictionary files	All new, no conflicts
Bookmark files	All new, no conflicts
CSS parser files	All new, no conflicts
Image converter files	All new, no conflicts
Custom font files	All new, no conflicts
StarDict library	All new, no conflicts

---

Testing Considerations

Regression Testing Required

After any merge:

1. EPUB Reading

   • Page navigation
   • Chapter selection
   • CSS styling
   • Image rendering
   • Bookmark indicators

2. Library Functions

   • Tab navigation
   • Search functionality
   • Recent books display
   • List management

3. Dictionary

   • Word selection
   • Lookup accuracy
   • Definition display

4. Web Server

   • File upload/download
   • API endpoints
   • WebSocket uploads
   • mDNS discovery

5. Settings

   • All new settings persist correctly
   • Settings migration from older versions

6. Display

   • High contrast mode
   • Bezel compensation (all orientations)
   • Sleep screen variations

Memory Testing

crosspoint-ef includes memory optimization fixes. After merge:

1. Test with large EPUBs (2000+ chapters)
2. Test opening multiple books in sequence
3. Test anti-aliasing under memory pressure
4. Monitor for ghosting/artifacts

---

Priority Recommendations

Immediate (For crosspoint-ef Stability)

1. Cherry-pick Spanish hyphenation (#558)
2. Cherry-pick multi-line keyboard entry (#567)
3. Cherry-pick italics on image alt (#569)
4. Cherry-pick front layout fix (#564)

Short-term (Feature Completeness)

5. Evaluate OTA rework (#509) - compare implementations
6. Cherry-pick page turn UX (#451)
7. Cherry-pick relative position fix (#486)

Long-term (Upstream Contribution)

8. Prepare dictionary feature as PR
9. Prepare bookmark system as PR
10. Prepare CSS parsing as PR
11. Evaluate inline image support for upstream

---

File Inventory for Merge

Files to Add to 0.16.0 Base (for upstream contribution)

src/activities/dictionary/
  DictionaryMargins.h
  DictionaryMenuActivity.cpp
  DictionaryMenuActivity.h
  DictionaryResultActivity.cpp
  DictionaryResultActivity.h
  DictionarySearchActivity.cpp
  DictionarySearchActivity.h
  EpubWordSelectionActivity.cpp
  EpubWordSelectionActivity.h

src/activities/util/
  QuickMenuActivity.cpp
  QuickMenuActivity.h

src/activities/home/
  BookmarkListActivity.cpp
  BookmarkListActivity.h

src/
  BookmarkStore.cpp
  BookmarkStore.h
  BookListStore.cpp
  BookListStore.h
  customFonts.cpp
  fontIds.h
  BadgeConfig.h

src/util/
  Md5Utils.cpp
  Md5Utils.h
  StringUtils.cpp
  StringUtils.h

src/images/
  LockIcon.h

lib/StarDict/
  StarDict.cpp
  StarDict.h
  DictHtmlParser.cpp
  DictHtmlParser.h
  DictPrefixIndex.generated.h

lib/Epub/Epub/css/
  CssParser.cpp
  CssParser.h
  CssStyle.h

lib/Epub/Epub/blocks/
  ImageBlock.cpp
  ImageBlock.h
  BlockStyle.h

lib/Epub/Epub/converters/
  FramebufferWriter.cpp
  FramebufferWriter.h
  ImageDecoderFactory.cpp
  ImageDecoderFactory.h
  ImageToFramebufferDecoder.cpp
  ImageToFramebufferDecoder.h
  JpegToFramebufferConverter.cpp
  JpegToFramebufferConverter.h
  PngToFramebufferConverter.cpp
  PngToFramebufferConverter.h

lib/EpdFont/builtinFonts/custom/
  [All font header files]

docs/
  webserver-api-reference.md
  companion-app-deep-link-API.md
  troubleshooting.md
  crosspoint-ef-features.md
  crosspoint-ef-user-guide.md

Files to Merge Carefully

src/main.cpp
src/CrossPointSettings.cpp
src/CrossPointSettings.h
src/network/CrossPointWebServer.cpp
src/network/CrossPointWebServer.h
src/network/OtaUpdater.cpp
src/network/OtaUpdater.h
src/activities/home/MyLibraryActivity.cpp
src/activities/home/MyLibraryActivity.h
src/activities/reader/EpubReaderActivity.cpp
src/activities/settings/SettingsActivity.cpp
src/activities/settings/CategorySettingsActivity.cpp
src/ScreenComponents.cpp
src/ScreenComponents.h
src/RecentBooksStore.cpp
src/RecentBooksStore.h
lib/GfxRenderer/GfxRenderer.cpp
lib/GfxRenderer/GfxRenderer.h
lib/GfxRenderer/BitmapHelpers.cpp
lib/GfxRenderer/BitmapHelpers.h
lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h
lib/Epub/Epub/Section.cpp
lib/Epub/Epub/Section.h

---

Conclusion

The crosspoint-ef branch represents a significant enhancement over the 0.15.0 baseline with 14+ major features. Most features are cleanly isolated in new files, making selective upstream contribution feasible.

Recommended approach:

1. First, bring crosspoint-ef up to date with 0.16.0 bug fixes
2. Then, evaluate individual features for upstream PR submission
3. Prioritize dictionary, bookmarks, and CSS parsing as highest-value contributions

The grayscale state corruption fix in crosspoint-ef should also be submitted upstream as a critical bug fix, as it prevents display artifacts under memory pressure.