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.