# Port 5 Upstream PRs (#1329, #1143, #1172, #1320, #1325)

**Date:** 2026-03-08
**Task:** Port unmerged upstream PRs to the mod across 4 feature branches

## Summary

Ported 5 upstream PRs from `crosspoint-reader/crosspoint-reader` to the mod codebase, organized across 4 phased feature branches:

### Phase 1: PR #1329 — ReaderUtils refactor
**Branch:** `port/1329-reader-utils`
- Created `src/activities/reader/ReaderUtils.h` with shared reader utilities: `GO_HOME_MS`, `applyOrientation()`, `detectPageTurn()`, `displayWithRefreshCycle()`, `renderAntiAliased()`
- Refactored `EpubReaderActivity.cpp` and `TxtReaderActivity.cpp` to use ReaderUtils
- Applied CodeRabbit's `storeBwBuffer()` null-check suggestion

### Phase 2: PRs #1143 + #1172 — TOC fragment navigation + multi-spine TOC
**Branch:** `port/1143-1172-toc-navigation`
- Extended `Section.h/.cpp` with TOC boundary tracking (`tocBoundaries`, `buildTocBoundaries()`, page lookup methods)
- Added TOC anchor page breaks to `ChapterHtmlSlimParser` (chapters start on fresh pages)
- Added TOC-aware navigation to `EpubReaderActivity` (long-press walks TOC entries, status bar shows subchapter title)
- Updated `EpubReaderChapterSelectionActivity` to pass and accept `tocIndex`
- Added multi-spine chapter caching (`cacheMultiSpineChapter()`)
- Incremented `SECTION_FILE_VERSION` from 18 to 19
- Preserved mod's footnote support, image rendering options, and Activity base class

### Phase 3: PR #1320 — JPEG resource cleanup
**Branch:** `port/1320-jpeg-cleanup`
- Added `ScopedCleanup` RAII struct to `JpegToBmpConverter.cpp`
- Removed scattered `free()`/`delete` calls
- Changed `rowCount` from `uint16_t*` to `uint32_t*` to prevent overflow

### Phase 4: PR #1325 — Settings tab label
**Branch:** `port/1325-settings-label`
- Dynamic confirm label in `SettingsActivity.cpp` shows next category name when tab bar is focused

## Files changed

| File | Phase | Change type |
|------|-------|-------------|
| `src/activities/reader/ReaderUtils.h` | 1 | New file |
| `src/activities/reader/EpubReaderActivity.cpp` | 1, 2 | Refactored |
| `src/activities/reader/EpubReaderActivity.h` | 2 | Extended |
| `src/activities/reader/TxtReaderActivity.cpp` | 1 | Refactored |
| `lib/Epub/Epub/Section.h` | 2 | Extended |
| `lib/Epub/Epub/Section.cpp` | 2 | Extended |
| `lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h` | 2 | Extended |
| `lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp` | 2 | Extended |
| `src/activities/ActivityResult.h` | 2 | Extended |
| `src/activities/reader/EpubReaderChapterSelectionActivity.h` | 2 | Extended |
| `src/activities/reader/EpubReaderChapterSelectionActivity.cpp` | 2 | Extended |
| `lib/JpegToBmpConverter/JpegToBmpConverter.cpp` | 3 | Refactored |
| `src/activities/settings/SettingsActivity.cpp` | 4 | Modified |
| `mod/prs/MERGED.md` | Housekeeping | Updated |
| `mod/docs/upstream-sync.md` | Housekeeping | Updated |

## Follow-up items

- All 4 branches need hardware testing before merging to `mod/master`
- Test TOC navigation with multi-chapter spine EPUBs (short story collections, academic texts)
- Test JPEG resource cleanup with large image-heavy EPUBs
- Verify `SECTION_FILE_VERSION` bump invalidates old caches properly (delete `.crosspoint/` on SD card)
- When upstream merges these PRs, these ports should be dropped during the next sync