# Upstream Sync: `upstream/master` into `mod/master`

**Date:** 2026-02-16  
**Task:** Synchronize recent upstream changes into the mod fork while preserving all mod-specific features.

## Strategy

- **Cherry-pick** approach (not full merge) for granular control
- 13 upstream commits cherry-picked across 3 phases; 4 skipped (mod already had enhanced implementations)
- Working branch `mod/sync-upstream` used, then fast-forwarded into `mod/master`

## Phases & Commits

### Phase 1 — Low-risk (6 commits)
| PR | Description | Notes |
|----|-------------|-------|
| #689 | Hyphenation optimization | Naming conflict resolved (mod's `OMIT_HYPH_*` guards preserved) |
| #832 | Settings size auto-calc | Mod's `sleepScreenLetterboxFill` added to new `SettingsWriter` |
| #840 | clang-format-fix shebang | Clean |
| #917 | SCOPE.md dictionary docs | Clean |
| #856 | Multiple author display | Clean |
| #858 | Miniz compilation warning | Clean |

### Phase 2 — Major refactors (3 commits)
| PR | Description | Notes |
|----|-------------|-------|
| #774 | Activity render() refactor | ~15 conflicts. Mod's 5 custom activities (Bookmarks, Dictionary) adapted to new `render(RenderLock&&)` pattern. Deadlock in `EpubReaderActivity.cpp` identified and fixed (redundant mutex around `enterNewActivity()`). |
| #916 | RAII RenderLock | Clean cherry-pick + audit of mod code for manual mutex usage |
| #728 | I18n system | ~15-20 conflicts. 16 new `StrId` keys added for mod strings. `DynamicEnum` font handling preserved. `SettingsList.h` and `SettingsActivity.cpp` adapted. |

### Phase 3 — Post-I18n fixes (4 commits)
| PR | Description | Notes |
|----|-------------|-------|
| #884 | Empty button icon fix | Clean |
| #906 | Webserver docs update | Clean |
| #792 | Translators doc | Clean |
| #796 | Battery icon alignment | Clean |

### Mod adaptation commits (3)
- `mod: adapt mod activities to #774 render() pattern` — Systematic refactor of 5 activity pairs
- `mod: convert remaining manual render locks to RAII RenderLock` — Audit & cleanup
- `mod: remove duplicate I18n.h include in HomeActivity.cpp` — Cleanup

## Skipped Upstream Commits (4)
- #676, #700 (image/cover improvements) — Mod already has enhanced pipeline
- #668 (JPEG support) — Already in mod
- #780 (cover fallback) — Already cherry-picked into mod

## Files Changed
111 files changed, ~23,700 insertions, ~17,700 deletions across hyphenation tries, I18n system, activity refactors, and documentation.

## Key Decisions
- **Image pipeline:** Kept mod's versions entirely; upstream's cover fixes were already ported
- **Deadlock fix:** Removed redundant `xSemaphoreTake`/`xSemaphoreGive` around `enterNewActivity()` in `EpubReaderActivity.cpp` — the new `RenderLock` inside `enterNewActivity()` would deadlock with the outer manual lock
- **I18n integration:** Added mod-specific `StrId` keys rather than keeping hardcoded strings

## Verification
- All mod features (bookmarks, dictionary, letterbox fill, placeholder covers, table rendering, embedded images) verified for code-path integrity post-sync
- No broken references or missing dependencies found

## Follow-up Items
- Full PlatformIO build on hardware to confirm compilation
- Runtime testing of all mod features on device