# Port Upstream KOReader Sync PRs

## Task
Port three unmerged upstream PRs into the fork:
- PR #1185: Cache KOReader document hash
- PR #1217: Proper KOReader XPath synchronisation
- PR #1090: Push progress and sleep (with silent failure adaptation)

## Changes Made

### PR #1185 — Cache KOReader Document Hash
- **lib/KOReaderSync/KOReaderDocumentId.h**: Added private static helpers `getCacheFilePath`, `loadCachedHash`, `saveCachedHash`
- **lib/KOReaderSync/KOReaderDocumentId.cpp**: Cache lookup before hash computation, persist after; uses mtime fingerprint + file size for validation

### PR #1217 — Proper KOReader XPath Synchronisation
- **lib/KOReaderSync/ChapterXPathIndexer.h/.cpp**: New files — Expat-based on-demand XHTML parsing for bidirectional XPath/progress mapping
- **lib/KOReaderSync/ProgressMapper.h/.cpp**: XPath-first mapping in both directions, percentage fallback, DocFragment 1-based indexing fix, `std::clamp` sanitization
- **docs/contributing/koreader-sync-xpath-mapping.md**: Design doc

### PR #1090 — Push Progress & Sleep (adapted)
Adapted to fork's `ActivityWithSubactivity` + callback architecture (upstream uses `Activity` + `startActivityForResult`).

- **lib/I18n/translations/english.yaml** + auto-generated **I18nKeys.h**: Added `STR_PUSH_AND_SLEEP`
- **src/activities/reader/EpubReaderMenuActivity.h**: Added `PUSH_AND_SLEEP` to `MenuAction` enum and `buildMenuItems()`
- **src/activities/reader/KOReaderSyncActivity.h/.cpp**: Added `SyncMode::PUSH_ONLY`, `deferFinish()` mechanism, PUSH_ONLY paths in `performSync`/`performUpload`/`loop`
- **src/activities/reader/EpubReaderActivity.h/.cpp**: Added `pendingSleep` flag, `extern void enterDeepSleep()`, `PUSH_AND_SLEEP` case in `onReaderMenuConfirm`

**Silent failure**: Both `onCancel` and `onSyncComplete` callbacks set `pendingSleep = true`, so the device sleeps regardless of sync success/failure. No credentials also triggers sleep directly.

## Build
Compiles cleanly on `default` environment (ESP32-C3). RAM: 32.8%, Flash: 71.7%.

## Follow-up Items
- Changes are unstaged — commit when ready
- Other language YAML files will auto-fallback to English for `STR_PUSH_AND_SLEEP`