mod: Phase 3 — Re-port unmerged upstream PRs

Re-applied upstream PRs not yet merged to upstream/master: - #1055: Byte-level framebuffer writes (fillPhysicalHSpan*, optimized fillRect/drawLine/fillRectDither/fillPolygon) - #1027: Word-width cache (FNV-1a, 128-entry) and hyphenation early exit in ParsedText for 7-9% layout speedup - #1068: Already present in upstream — URL hyphenation fix - #1019: Already present in upstream — file extensions in browser - #1090/#1185/#1217: KOReader sync improvements — binary credential store, document hash caching, ChapterXPathIndexer integration - #1209: OPDS multi-server — OpdsBookBrowserActivity accepts OpdsServer, directory picker for downloads, download-complete prompt with open/back options - #857: Dictionary activities already ported in Phase 1/2 - #1003: Placeholder cover already integrated in Phase 2 Also fixed: STR_OFF i18n string, include paths, replaced Epub::isValidThumbnailBmp with Storage.exists, replaced StringUtils::checkFileExtension with FsHelpers equivalents. Made-with: Cursor
2026-03-07 16:15:42 -05:00
parent 30473c27d3
commit 60a3e21c0e
25 changed files with 811 additions and 295 deletions
--- a/lib/KOReaderSync/KOReaderCredentialStore.cpp
+++ b/lib/KOReaderSync/KOReaderCredentialStore.cpp
@@ -3,81 +3,73 @@
 #include <HalStorage.h>
 #include <Logging.h>
 #include <MD5Builder.h>
-#include <ObfuscationUtils.h>
 #include <Serialization.h>

-#include "../../src/JsonSettingsIO.h"
-
 // Initialize the static instance
 KOReaderCredentialStore KOReaderCredentialStore::instance;

 namespace {
-// File format version (for binary migration)
+// File format version
 constexpr uint8_t KOREADER_FILE_VERSION = 1;

-// File paths
-constexpr char KOREADER_FILE_BIN[] = "/.crosspoint/koreader.bin";
-constexpr char KOREADER_FILE_JSON[] = "/.crosspoint/koreader.json";
-constexpr char KOREADER_FILE_BAK[] = "/.crosspoint/koreader.bin.bak";
+// KOReader credentials file path
+constexpr char KOREADER_FILE[] = "/.crosspoint/koreader.bin";

 // Default sync server URL
 constexpr char DEFAULT_SERVER_URL[] = "https://sync.koreader.rocks:443";

-// Legacy obfuscation key - "KOReader" in ASCII (only used for binary migration)
-constexpr uint8_t LEGACY_OBFUSCATION_KEY[] = {0x4B, 0x4F, 0x52, 0x65, 0x61, 0x64, 0x65, 0x72};
-constexpr size_t LEGACY_KEY_LENGTH = sizeof(LEGACY_OBFUSCATION_KEY);
-
-void legacyDeobfuscate(std::string& data) {
-  for (size_t i = 0; i < data.size(); i++) {
-    data[i] ^= LEGACY_OBFUSCATION_KEY[i % LEGACY_KEY_LENGTH];
-  }
-}
+// Obfuscation key - "KOReader" in ASCII
+// This is NOT cryptographic security, just prevents casual file reading
+constexpr uint8_t OBFUSCATION_KEY[] = {0x4B, 0x4F, 0x52, 0x65, 0x61, 0x64, 0x65, 0x72};
+constexpr size_t KEY_LENGTH = sizeof(OBFUSCATION_KEY);
 }  // namespace

+void KOReaderCredentialStore::obfuscate(std::string& data) const {
+  for (size_t i = 0; i < data.size(); i++) {
+    data[i] ^= OBFUSCATION_KEY[i % KEY_LENGTH];
+  }
+}
+
 bool KOReaderCredentialStore::saveToFile() const {
+  // Make sure the directory exists
  Storage.mkdir("/.crosspoint");
-  return JsonSettingsIO::saveKOReader(*this, KOREADER_FILE_JSON);
-}

-bool KOReaderCredentialStore::loadFromFile() {
-  // Try JSON first
-  if (Storage.exists(KOREADER_FILE_JSON)) {
-    String json = Storage.readFile(KOREADER_FILE_JSON);
-    if (!json.isEmpty()) {
-      bool resave = false;
-      bool result = JsonSettingsIO::loadKOReader(*this, json.c_str(), &resave);
-      if (result && resave) {
-        saveToFile();
-        LOG_DBG("KRS", "Resaved KOReader credentials to update format");
-      }
-      return result;
-    }
-  }
-
-  // Fall back to binary migration
-  if (Storage.exists(KOREADER_FILE_BIN)) {
-    if (loadFromBinaryFile()) {
-      if (saveToFile()) {
-        Storage.rename(KOREADER_FILE_BIN, KOREADER_FILE_BAK);
-        LOG_DBG("KRS", "Migrated koreader.bin to koreader.json");
-        return true;
-      } else {
-        LOG_ERR("KRS", "Failed to save KOReader credentials during migration");
-        return false;
-      }
-    }
-  }
-
-  LOG_DBG("KRS", "No credentials file found");
-  return false;
-}
-
-bool KOReaderCredentialStore::loadFromBinaryFile() {
  FsFile file;
-  if (!Storage.openFileForRead("KRS", KOREADER_FILE_BIN, file)) {
+  if (!Storage.openFileForWrite("KRS", KOREADER_FILE, file)) {
    return false;
  }

+  // Write header
+  serialization::writePod(file, KOREADER_FILE_VERSION);
+
+  // Write username (plaintext - not particularly sensitive)
+  serialization::writeString(file, username);
+  LOG_DBG("KRS", "Saving username: %s", username.c_str());
+
+  // Write password (obfuscated)
+  std::string obfuscatedPwd = password;
+  obfuscate(obfuscatedPwd);
+  serialization::writeString(file, obfuscatedPwd);
+
+  // Write server URL
+  serialization::writeString(file, serverUrl);
+
+  // Write match method
+  serialization::writePod(file, static_cast<uint8_t>(matchMethod));
+
+  file.close();
+  LOG_DBG("KRS", "Saved KOReader credentials to file");
+  return true;
+}
+
+bool KOReaderCredentialStore::loadFromFile() {
+  FsFile file;
+  if (!Storage.openFileForRead("KRS", KOREADER_FILE, file)) {
+    LOG_DBG("KRS", "No credentials file found");
+    return false;
+  }
+
+  // Read and verify version
  uint8_t version;
  serialization::readPod(file, version);
  if (version != KOREADER_FILE_VERSION) {
@@ -86,25 +78,29 @@ bool KOReaderCredentialStore::loadFromBinaryFile() {
    return false;
  }

+  // Read username
  if (file.available()) {
    serialization::readString(file, username);
  } else {
    username.clear();
  }

+  // Read and deobfuscate password
  if (file.available()) {
    serialization::readString(file, password);
-    legacyDeobfuscate(password);
+    obfuscate(password);  // XOR is symmetric, so same function deobfuscates
  } else {
    password.clear();
  }

+  // Read server URL
  if (file.available()) {
    serialization::readString(file, serverUrl);
  } else {
    serverUrl.clear();
  }

+  // Read match method
  if (file.available()) {
    uint8_t method;
    serialization::readPod(file, method);
@@ -114,7 +110,7 @@ bool KOReaderCredentialStore::loadFromBinaryFile() {
  }

  file.close();
-  LOG_DBG("KRS", "Loaded KOReader credentials from binary for user: %s", username.c_str());
+  LOG_DBG("KRS", "Loaded KOReader credentials for user: %s", username.c_str());
  return true;
 }

--- a/lib/KOReaderSync/KOReaderCredentialStore.h
+++ b/lib/KOReaderSync/KOReaderCredentialStore.h
@@ -8,17 +8,10 @@ enum class DocumentMatchMethod : uint8_t {
  BINARY = 1,    // Match by partial MD5 of file content (more accurate, but files must be identical)
 };

-class KOReaderCredentialStore;
-namespace JsonSettingsIO {
-bool saveKOReader(const KOReaderCredentialStore& store, const char* path);
-bool loadKOReader(KOReaderCredentialStore& store, const char* json, bool* needsResave);
-}  // namespace JsonSettingsIO
-
 /**
 * Singleton class for storing KOReader sync credentials on the SD card.
- * Passwords are XOR-obfuscated with the device's unique hardware MAC address
- * and base64-encoded before writing to JSON (not cryptographically secure,
- * but prevents casual reading and ties credentials to the specific device).
+ * Credentials are stored in /sd/.crosspoint/koreader.bin with basic
+ * XOR obfuscation to prevent casual reading (not cryptographically secure).
 */
 class KOReaderCredentialStore {
 private:
@@ -31,10 +24,8 @@ class KOReaderCredentialStore {
  // Private constructor for singleton
  KOReaderCredentialStore() = default;

-  bool loadFromBinaryFile();
-
-  friend bool JsonSettingsIO::saveKOReader(const KOReaderCredentialStore&, const char*);
-  friend bool JsonSettingsIO::loadKOReader(KOReaderCredentialStore&, const char*, bool*);
+  // XOR obfuscation (symmetric - same for encode/decode)
+  void obfuscate(std::string& data) const;

 public:
  // Delete copy constructor and assignment
--- a/lib/KOReaderSync/KOReaderDocumentId.cpp
+++ b/lib/KOReaderSync/KOReaderDocumentId.cpp
@@ -4,6 +4,8 @@
 #include <Logging.h>
 #include <MD5Builder.h>

+#include <functional>
+
 namespace {
 // Extract filename from path (everything after last '/')
 std::string getFilename(const std::string& path) {
@@ -15,6 +17,131 @@ std::string getFilename(const std::string& path) {
 }
 }  // namespace

+std::string KOReaderDocumentId::getCacheFilePath(const std::string& filePath) {
+  // Mirror the Epub cache directory convention so the hash file shares the
+  // same per-book folder as other cached data.
+  return std::string("/.crosspoint/epub_") + std::to_string(std::hash<std::string>{}(filePath)) +
+         "/koreader_docid.txt";
+}
+
+std::string KOReaderDocumentId::loadCachedHash(const std::string& cacheFilePath, const size_t fileSize,
+                                               const std::string& currentFingerprint) {
+  if (!Storage.exists(cacheFilePath.c_str())) {
+    return "";
+  }
+
+  const String content = Storage.readFile(cacheFilePath.c_str());
+  if (content.isEmpty()) {
+    return "";
+  }
+
+  // Format: "<filesize>:<fingerprint>\n<32-char-hex-hash>"
+  const int newlinePos = content.indexOf('\n');
+  if (newlinePos < 0) {
+    return "";
+  }
+
+  const String header = content.substring(0, newlinePos);
+  const int colonPos = header.indexOf(':');
+  if (colonPos < 0) {
+    LOG_DBG("KODoc", "Hash cache invalidated: header missing fingerprint");
+    return "";
+  }
+
+  const String sizeTok = header.substring(0, colonPos);
+  const String fpTok = header.substring(colonPos + 1);
+
+  // Validate the filesize token – it must consist of ASCII digits and parse
+  // correctly to the expected size.
+  bool digitsOnly = true;
+  for (size_t i = 0; i < sizeTok.length(); ++i) {
+    const char ch = sizeTok[i];
+    if (ch < '0' || ch > '9') {
+      digitsOnly = false;
+      break;
+    }
+  }
+  if (!digitsOnly) {
+    LOG_DBG("KODoc", "Hash cache invalidated: size token not numeric ('%s')", sizeTok.c_str());
+    return "";
+  }
+
+  const long parsed = sizeTok.toInt();
+  if (parsed < 0) {
+    LOG_DBG("KODoc", "Hash cache invalidated: size token parse error ('%s')", sizeTok.c_str());
+    return "";
+  }
+  const size_t cachedSize = static_cast<size_t>(parsed);
+  if (cachedSize != fileSize) {
+    LOG_DBG("KODoc", "Hash cache invalidated: file size or fingerprint changed (%zu -> %zu)", cachedSize, fileSize);
+    return "";
+  }
+
+  // Validate stored fingerprint format (8 hex characters)
+  if (fpTok.length() != 8) {
+    LOG_DBG("KODoc", "Hash cache invalidated: bad fingerprint length (%zu)", fpTok.length());
+    return "";
+  }
+  for (size_t i = 0; i < fpTok.length(); ++i) {
+    char c = fpTok[i];
+    bool hex = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F');
+    if (!hex) {
+      LOG_DBG("KODoc", "Hash cache invalidated: non-hex character '%c' in fingerprint", c);
+      return "";
+    }
+  }
+
+  {
+    String currentFpStr(currentFingerprint.c_str());
+    if (fpTok != currentFpStr) {
+      LOG_DBG("KODoc", "Hash cache invalidated: fingerprint changed (%s != %s)", fpTok.c_str(),
+              currentFingerprint.c_str());
+      return "";
+    }
+  }
+
+  std::string hash = content.substring(newlinePos + 1).c_str();
+  // Trim any trailing whitespace / line endings
+  while (!hash.empty() && (hash.back() == '\n' || hash.back() == '\r' || hash.back() == ' ')) {
+    hash.pop_back();
+  }
+
+  // Hash must be exactly 32 hex characters.
+  if (hash.size() != 32) {
+    LOG_DBG("KODoc", "Hash cache invalidated: wrong hash length (%zu)", hash.size());
+    return "";
+  }
+  for (char c : hash) {
+    if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'))) {
+      LOG_DBG("KODoc", "Hash cache invalidated: non-hex character '%c' in hash", c);
+      return "";
+    }
+  }
+
+  LOG_DBG("KODoc", "Hash cache hit: %s", hash.c_str());
+  return hash;
+}
+
+void KOReaderDocumentId::saveCachedHash(const std::string& cacheFilePath, const size_t fileSize,
+                                        const std::string& fingerprint, const std::string& hash) {
+  // Ensure the book's cache directory exists before writing
+  const size_t lastSlash = cacheFilePath.rfind('/');
+  if (lastSlash != std::string::npos) {
+    Storage.ensureDirectoryExists(cacheFilePath.substr(0, lastSlash).c_str());
+  }
+
+  // Format: "<filesize>:<fingerprint>\n<hash>"
+  String content(std::to_string(fileSize).c_str());
+  content += ':';
+  content += fingerprint.c_str();
+  content += '\n';
+  content += hash.c_str();
+
+  if (!Storage.writeFile(cacheFilePath.c_str(), content)) {
+    LOG_DBG("KODoc", "Failed to write hash cache to %s", cacheFilePath.c_str());
+  }
+}
+
 std::string KOReaderDocumentId::calculateFromFilename(const std::string& filePath) {
  const std::string filename = getFilename(filePath);
  if (filename.empty()) {
@@ -49,6 +176,28 @@ std::string KOReaderDocumentId::calculate(const std::string& filePath) {
  }

  const size_t fileSize = file.fileSize();
+
+  // Compute a lightweight fingerprint from the file's modification time.
+  // The underlying FsFile API provides getModifyDateTime which returns two
+  // packed 16-bit values (date and time).  Concatenate these as eight hex
+  // digits to produce the token stored in the cache header.
+  uint16_t date = 0, time = 0;
+  if (!file.getModifyDateTime(&date, &time)) {
+    date = 0;
+    time = 0;
+  }
+  char fpBuf[9];
+  snprintf(fpBuf, sizeof(fpBuf), "%04x%04x", date, time);
+  const std::string fingerprintTok(fpBuf);
+
+  // Return persisted hash if the file size and fingerprint haven't changed.
+  const std::string cacheFilePath = getCacheFilePath(filePath);
+  const std::string cached = loadCachedHash(cacheFilePath, fileSize, fingerprintTok);
+  if (!cached.empty()) {
+    file.close();
+    return cached;
+  }
+
  LOG_DBG("KODoc", "Calculating hash for file: %s (size: %zu)", filePath.c_str(), fileSize);

  // Initialize MD5 builder
@@ -92,5 +241,7 @@ std::string KOReaderDocumentId::calculate(const std::string& filePath) {

  LOG_DBG("KODoc", "Hash calculated: %s (from %zu bytes)", result.c_str(), totalBytesRead);

+  saveCachedHash(cacheFilePath, fileSize, fingerprintTok, result);
+
  return result;
 }
--- a/lib/KOReaderSync/KOReaderDocumentId.h
+++ b/lib/KOReaderSync/KOReaderDocumentId.h
@@ -42,4 +42,31 @@ class KOReaderDocumentId {

  // Calculate offset for index i: 1024 << (2*i)
  static size_t getOffset(int i);
+
+  // Hash cache helpers
+  // Returns the path to the per-book cache file that stores the precomputed hash.
+  // Uses the same directory convention as the Epub cache (/.crosspoint/epub_<hash>/).
+  static std::string getCacheFilePath(const std::string& filePath);
+
+  // Returns the cached hash if the file size and fingerprint match, or empty
+  // string on miss/invalidation.
+  //
+  // The fingerprint is derived from the file's modification timestamp.  We
+  // call `FsFile::getModifyDateTime` to retrieve two 16‑bit packed values
+  // supplied by the filesystem: one for the date and one for the time.  These
+  // are concatenated and represented as eight hexadecimal digits in the form
+  // <date><time> (high 16 bits = packed date, low 16 bits = packed time).
+  //
+  // The resulting string serves as a lightweight change signal; any modification
+  // to the file's mtime will alter the packed date/time combo and invalidate
+  // the cache entry.  Since the full document hash is expensive to compute,
+  // using the packed timestamp gives us a quick way to detect modifications
+  // without reading file contents.
+  static std::string loadCachedHash(const std::string& cacheFilePath, size_t fileSize,
+                                    const std::string& currentFingerprint);
+
+  // Persists the computed hash alongside the file size and fingerprint (the
+  // modification-timestamp token) used to generate it.
+  static void saveCachedHash(const std::string& cacheFilePath, size_t fileSize, const std::string& fingerprint,
+                             const std::string& hash);
 };
--- a/lib/KOReaderSync/ProgressMapper.cpp
+++ b/lib/KOReaderSync/ProgressMapper.cpp
@@ -2,8 +2,11 @@

 #include <Logging.h>

+#include <algorithm>
 #include <cmath>

+#include "ChapterXPathIndexer.h"
+
 KOReaderPosition ProgressMapper::toKOReader(const std::shared_ptr<Epub>& epub, const CrossPointPosition& pos) {
  KOReaderPosition result;

@@ -16,8 +19,13 @@ KOReaderPosition ProgressMapper::toKOReader(const std::shared_ptr<Epub>& epub, c
  // Calculate overall book progress (0.0-1.0)
  result.percentage = epub->calculateProgress(pos.spineIndex, intraSpineProgress);

-  // Generate XPath with estimated paragraph position based on page
-  result.xpath = generateXPath(pos.spineIndex, pos.pageNumber, pos.totalPages);
+  // Generate the best available XPath for the current chapter position.
+  // Prefer element-level XPaths from a lightweight XHTML reparse; fall back
+  // to a synthetic chapter-level path if parsing fails.
+  result.xpath = ChapterXPathIndexer::findXPathForProgress(epub, pos.spineIndex, intraSpineProgress);
+  if (result.xpath.empty()) {
+    result.xpath = generateXPath(pos.spineIndex);
+  }

  // Get chapter info for logging
  const int tocIndex = epub->getTocIndexForSpineIndex(pos.spineIndex);
@@ -36,34 +44,69 @@ CrossPointPosition ProgressMapper::toCrossPoint(const std::shared_ptr<Epub>& epu
  result.pageNumber = 0;
  result.totalPages = 0;

-  const size_t bookSize = epub->getBookSize();
-  if (bookSize == 0) {
+  if (!epub || epub->getSpineItemsCount() <= 0) {
    return result;
  }

-  // Use percentage-based lookup for both spine and page positioning
-  // XPath parsing is unreliable since CrossPoint doesn't preserve detailed HTML structure
-  const size_t targetBytes = static_cast<size_t>(bookSize * koPos.percentage);
-
-  // Find the spine item that contains this byte position
  const int spineCount = epub->getSpineItemsCount();
-  bool spineFound = false;
-  for (int i = 0; i < spineCount; i++) {
-    const size_t cumulativeSize = epub->getCumulativeSpineItemSize(i);
-    if (cumulativeSize >= targetBytes) {
-      result.spineIndex = i;
-      spineFound = true;
-      break;
+
+  float resolvedIntraSpineProgress = -1.0f;
+  bool xpathExactMatch = false;
+  bool usedXPathMapping = false;
+
+  int xpathSpineIndex = -1;
+  if (ChapterXPathIndexer::tryExtractSpineIndexFromXPath(koPos.xpath, xpathSpineIndex) && xpathSpineIndex >= 0 &&
+      xpathSpineIndex < spineCount) {
+    float intraFromXPath = 0.0f;
+    if (ChapterXPathIndexer::findProgressForXPath(epub, xpathSpineIndex, koPos.xpath, intraFromXPath,
+                                                  xpathExactMatch)) {
+      result.spineIndex = xpathSpineIndex;
+      resolvedIntraSpineProgress = intraFromXPath;
+      usedXPathMapping = true;
    }
  }

-  // If no spine item was found (e.g., targetBytes beyond last cumulative size),
-  // default to the last spine item so we map to the end of the book instead of the beginning.
-  if (!spineFound && spineCount > 0) {
-    result.spineIndex = spineCount - 1;
+  if (!usedXPathMapping) {
+    const size_t bookSize = epub->getBookSize();
+    if (bookSize == 0) {
+      return result;
+    }
+
+    if (!std::isfinite(koPos.percentage)) {
+      return result;
+    }
+
+    const float sanitizedPercentage = std::clamp(koPos.percentage, 0.0f, 1.0f);
+    const size_t targetBytes = static_cast<size_t>(bookSize * sanitizedPercentage);
+
+    bool spineFound = false;
+    for (int i = 0; i < spineCount; i++) {
+      const size_t cumulativeSize = epub->getCumulativeSpineItemSize(i);
+      if (cumulativeSize >= targetBytes) {
+        result.spineIndex = i;
+        spineFound = true;
+        break;
+      }
+    }
+
+    if (!spineFound && spineCount > 0) {
+      result.spineIndex = spineCount - 1;
+    }
+
+    if (result.spineIndex < epub->getSpineItemsCount()) {
+      const size_t prevCumSize = (result.spineIndex > 0) ? epub->getCumulativeSpineItemSize(result.spineIndex - 1) : 0;
+      const size_t currentCumSize = epub->getCumulativeSpineItemSize(result.spineIndex);
+      const size_t spineSize = currentCumSize - prevCumSize;
+
+      if (spineSize > 0) {
+        const size_t bytesIntoSpine = (targetBytes > prevCumSize) ? (targetBytes - prevCumSize) : 0;
+        resolvedIntraSpineProgress = static_cast<float>(bytesIntoSpine) / static_cast<float>(spineSize);
+        resolvedIntraSpineProgress = std::max(0.0f, std::min(1.0f, resolvedIntraSpineProgress));
+      }
+    }
  }

-  // Estimate page number within the spine item using percentage
+  // Estimate page number within the selected spine item
  if (result.spineIndex < epub->getSpineItemsCount()) {
    const size_t prevCumSize = (result.spineIndex > 0) ? epub->getCumulativeSpineItemSize(result.spineIndex - 1) : 0;
    const size_t currentCumSize = epub->getCumulativeSpineItemSize(result.spineIndex);
@@ -71,12 +114,9 @@ CrossPointPosition ProgressMapper::toCrossPoint(const std::shared_ptr<Epub>& epu

    int estimatedTotalPages = 0;

-    // If we are in the same spine, use the known total pages
    if (result.spineIndex == currentSpineIndex && totalPagesInCurrentSpine > 0) {
      estimatedTotalPages = totalPagesInCurrentSpine;
-    }
-    // Otherwise try to estimate based on density from current spine
-    else if (currentSpineIndex >= 0 && currentSpineIndex < epub->getSpineItemsCount() && totalPagesInCurrentSpine > 0) {
+    } else if (currentSpineIndex >= 0 && currentSpineIndex < epub->getSpineItemsCount() && totalPagesInCurrentSpine > 0) {
      const size_t prevCurrCumSize =
          (currentSpineIndex > 0) ? epub->getCumulativeSpineItemSize(currentSpineIndex - 1) : 0;
      const size_t currCumSize = epub->getCumulativeSpineItemSize(currentSpineIndex);
@@ -91,24 +131,24 @@ CrossPointPosition ProgressMapper::toCrossPoint(const std::shared_ptr<Epub>& epu

    result.totalPages = estimatedTotalPages;

-    if (spineSize > 0 && estimatedTotalPages > 0) {
-      const size_t bytesIntoSpine = (targetBytes > prevCumSize) ? (targetBytes - prevCumSize) : 0;
-      const float intraSpineProgress = static_cast<float>(bytesIntoSpine) / static_cast<float>(spineSize);
-      const float clampedProgress = std::max(0.0f, std::min(1.0f, intraSpineProgress));
-      result.pageNumber = static_cast<int>(clampedProgress * estimatedTotalPages);
+    if (estimatedTotalPages > 0 && resolvedIntraSpineProgress >= 0.0f) {
+      const float clampedProgress = std::max(0.0f, std::min(1.0f, resolvedIntraSpineProgress));
+      result.pageNumber = static_cast<int>(clampedProgress * static_cast<float>(estimatedTotalPages));
      result.pageNumber = std::max(0, std::min(result.pageNumber, estimatedTotalPages - 1));
+    } else if (spineSize > 0 && estimatedTotalPages > 0) {
+      result.pageNumber = 0;
    }
  }

-  LOG_DBG("ProgressMapper", "KOReader -> CrossPoint: %.2f%% at %s -> spine=%d, page=%d", koPos.percentage * 100,
-          koPos.xpath.c_str(), result.spineIndex, result.pageNumber);
+  LOG_DBG("ProgressMapper", "KOReader -> CrossPoint: %.2f%% at %s -> spine=%d, page=%d (%s, exact=%s)",
+          koPos.percentage * 100, koPos.xpath.c_str(), result.spineIndex, result.pageNumber,
+          usedXPathMapping ? "xpath" : "percentage", xpathExactMatch ? "yes" : "no");

  return result;
 }

-std::string ProgressMapper::generateXPath(int spineIndex, int pageNumber, int totalPages) {
-  // Use 0-based DocFragment indices for KOReader
-  // Use a simple xpath pointing to the DocFragment - KOReader will use the percentage for fine positioning within it
-  // Avoid specifying paragraph numbers as they may not exist in the target document
-  return "/body/DocFragment[" + std::to_string(spineIndex) + "]/body";
+std::string ProgressMapper::generateXPath(int spineIndex) {
+  // Fallback path when element-level XPath extraction is unavailable.
+  // KOReader uses 1-based XPath predicates; spineIndex is 0-based internally.
+  return "/body/DocFragment[" + std::to_string(spineIndex + 1) + "]/body";
 }
--- a/lib/KOReaderSync/ProgressMapper.h
+++ b/lib/KOReaderSync/ProgressMapper.h
@@ -27,9 +27,16 @@ struct KOReaderPosition {
 * CrossPoint tracks position as (spineIndex, pageNumber).
 * KOReader uses XPath-like strings + percentage.
 *
- * Since CrossPoint discards HTML structure during parsing, we generate
- * synthetic XPath strings based on spine index, using percentage as the
- * primary sync mechanism.
+ * Forward mapping (CrossPoint -> KOReader):
+ * - Prefer element-level XPath extracted from current spine XHTML.
+ * - Fallback to synthetic chapter XPath if extraction fails.
+ *
+ * Reverse mapping (KOReader -> CrossPoint):
+ * - Prefer incoming XPath (DocFragment + element path) when resolvable.
+ * - Fallback to percentage-based approximation when XPath is missing/invalid.
+ *
+ * This keeps behavior stable on low-memory devices while improving round-trip
+ * sync precision when KOReader provides detailed paths.
 */
 class ProgressMapper {
 public:
@@ -45,8 +52,9 @@ class ProgressMapper {
  /**
   * Convert KOReader position to CrossPoint format.
   *
-   * Note: The returned pageNumber may be approximate since different
-   * rendering settings produce different page counts.
+   * Uses XPath-first resolution when possible and percentage fallback otherwise.
+   * Returned pageNumber can still be approximate because page counts differ
+   * across renderer/font/layout settings.
   *
   * @param epub The EPUB book
   * @param koPos KOReader position
@@ -60,8 +68,7 @@ class ProgressMapper {
 private:
  /**
   * Generate XPath for KOReader compatibility.
-   * Format: /body/DocFragment[spineIndex+1]/body
-   * Since CrossPoint doesn't preserve HTML structure, we rely on percentage for positioning.
+   * Fallback format: /body/DocFragment[spineIndex + 1]/body
   */
-  static std::string generateXPath(int spineIndex, int pageNumber, int totalPages);
+  static std::string generateXPath(int spineIndex);
 };