Add paragraph index LUT for accurate KOReader position sync

Store per-page paragraph indices in section cache to enable precise
XPath-to-page and page-to-XPath mapping without reparsing XHTML.

Forward path (upload): generates XPath directly from paragraph LUT
instead of byte-offset estimation, eliminating drift in chapters
with non-uniform content density.

Reverse path (download): resolves incoming KOReader XPath p[N] to
the exact page via paragraph LUT lookup.

Paragraph counter counts all <p> elements including display:none
to match ChapterXPathIndexer and crengine's standard XPath counting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lib/Epub/Epub/Section.cpp

@@ -10,10 +10,21 @@
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 18;
-constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) + sizeof(bool) + sizeof(uint8_t) +
-                                 sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint16_t) + sizeof(bool) + sizeof(bool) +
-                                 sizeof(uint8_t) + sizeof(uint32_t) + sizeof(uint32_t);
+constexpr uint8_t SECTION_FILE_VERSION = 20;
+constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) +   // SECTION_FILE_VERSION
+                                 sizeof(int) +       // fontId
+                                 sizeof(float) +     // lineCompression
+                                 sizeof(bool) +      // extraParagraphSpacing
+                                 sizeof(uint8_t) +   // paragraphAlignment
+                                 sizeof(uint16_t) +  // viewportWidth
+                                 sizeof(uint16_t) +  // viewportHeight
+                                 sizeof(uint16_t) +  // pageCount (stored as 16-bit in header)
+                                 sizeof(bool) +      // hyphenationEnabled
+                                 sizeof(bool) +      // embeddedStyle
+                                 sizeof(uint8_t) +   // imageRendering
+                                 sizeof(uint32_t) +  // page LUT offset
+                                 sizeof(uint32_t) +  // anchor map offset
+                                 sizeof(uint32_t);   // paragraph LUT offset
 }  // namespace
 
 uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
@@ -44,7 +55,8 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
   static_assert(HEADER_SIZE == sizeof(SECTION_FILE_VERSION) + sizeof(fontId) + sizeof(lineCompression) +
                                    sizeof(extraParagraphSpacing) + sizeof(paragraphAlignment) + sizeof(viewportWidth) +
                                    sizeof(viewportHeight) + sizeof(pageCount) + sizeof(hyphenationEnabled) +
-                                   sizeof(embeddedStyle) + sizeof(imageRendering) + sizeof(uint32_t) + sizeof(uint32_t),
+                                   sizeof(embeddedStyle) + sizeof(imageRendering) + sizeof(uint32_t) +
+                                   sizeof(uint32_t) + sizeof(uint32_t),
                 "Header size mismatch");
   serialization::writePod(file, SECTION_FILE_VERSION);
   serialization::writePod(file, fontId);
@@ -59,6 +71,7 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
   serialization::writePod(file, pageCount);  // Placeholder for page count (will be initially 0, patched later)
   serialization::writePod(file, static_cast<uint32_t>(0));  // Placeholder for LUT offset (patched later)
   serialization::writePod(file, static_cast<uint32_t>(0));  // Placeholder for anchor map offset (patched later)
+  serialization::writePod(file, static_cast<uint32_t>(0));  // Placeholder for paragraph LUT offset (patched later)
 }
 
 bool Section::loadSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
@@ -249,11 +262,20 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     serialization::writePod(file, page);
   }
 
-  // Patch header with final pageCount, lutOffset, and anchorMapOffset
-  file.seek(HEADER_SIZE - sizeof(uint32_t) * 2 - sizeof(pageCount));
+  // Write per-page paragraph index LUT for XPath-to-page resolution
+  const uint32_t paragraphLutOffset = file.position();
+  const auto& paragraphPerPage = visitor.getParagraphIndexPerPage();
+  serialization::writePod(file, static_cast<uint16_t>(paragraphPerPage.size()));
+  for (const uint16_t& pIdx : paragraphPerPage) {
+    serialization::writePod(file, pIdx);
+  }
+
+  // Patch header with final pageCount, lutOffset, anchorMapOffset, and paragraphLutOffset
+  file.seek(HEADER_SIZE - sizeof(uint32_t) * 3 - sizeof(pageCount));
   serialization::writePod(file, pageCount);
   serialization::writePod(file, lutOffset);
   serialization::writePod(file, anchorMapOffset);
+  serialization::writePod(file, paragraphLutOffset);
   file.close();
   if (cssParser) {
     cssParser->clear();
@@ -266,7 +288,7 @@ std::unique_ptr<Page> Section::loadPageFromSectionFile() {
     return nullptr;
   }
 
-  file.seek(HEADER_SIZE - sizeof(uint32_t) * 2);
+  file.seek(HEADER_SIZE - sizeof(uint32_t) * 3);
   uint32_t lutOffset;
   serialization::readPod(file, lutOffset);
   file.seek(lutOffset + sizeof(uint32_t) * currentPage);
@@ -286,7 +308,7 @@ std::optional<uint16_t> Section::getPageForAnchor(const std::string& anchor) con
   }
 
   const uint32_t fileSize = f.size();
-  f.seek(HEADER_SIZE - sizeof(uint32_t));
+  f.seek(HEADER_SIZE - sizeof(uint32_t) * 2);
   uint32_t anchorMapOffset;
   serialization::readPod(f, anchorMapOffset);
   if (anchorMapOffset == 0 || anchorMapOffset >= fileSize) {
@@ -311,3 +333,91 @@ std::optional<uint16_t> Section::getPageForAnchor(const std::string& anchor) con
   f.close();
   return std::nullopt;
 }
+
+std::optional<uint16_t> Section::getPageForParagraphIndex(const uint16_t pIndex) const {
+  FsFile f;
+  if (!Storage.openFileForRead("SCT", filePath, f)) {
+    return std::nullopt;
+  }
+
+  const uint32_t fileSize = f.size();
+
+  // Read paragraph LUT offset from end of header
+  f.seek(HEADER_SIZE - sizeof(uint32_t));
+  uint32_t paragraphLutOffset;
+  serialization::readPod(f, paragraphLutOffset);
+  if (paragraphLutOffset == 0 || paragraphLutOffset >= fileSize) {
+    f.close();
+    return std::nullopt;
+  }
+
+  f.seek(paragraphLutOffset);
+  uint16_t count;
+  serialization::readPod(f, count);
+  if (count == 0) {
+    f.close();
+    return std::nullopt;
+  }
+
+  // Validate that all entries fit within the file
+  const uint32_t lutEnd = paragraphLutOffset + sizeof(uint16_t) + count * sizeof(uint16_t);
+  if (lutEnd > fileSize) {
+    f.close();
+    return std::nullopt;
+  }
+
+  // Find the first page whose paragraph index >= pIndex.
+  // Each entry stores the <p> index at the time that page was completed.
+  uint16_t resultPage = count - 1;  // default to last page
+  for (uint16_t i = 0; i < count; i++) {
+    uint16_t pagePIdx;
+    serialization::readPod(f, pagePIdx);
+    if (pagePIdx >= pIndex) {
+      resultPage = i;
+      break;
+    }
+  }
+
+  f.close();
+  return resultPage;
+}
+
+std::optional<uint16_t> Section::getParagraphIndexForPage(const uint16_t page) const {
+  FsFile f;
+  if (!Storage.openFileForRead("SCT", filePath, f)) {
+    return std::nullopt;
+  }
+
+  const uint32_t fileSize = f.size();
+
+  f.seek(HEADER_SIZE - sizeof(uint32_t));
+  uint32_t paragraphLutOffset;
+  serialization::readPod(f, paragraphLutOffset);
+  if (paragraphLutOffset == 0 || paragraphLutOffset >= fileSize) {
+    f.close();
+    return std::nullopt;
+  }
+
+  f.seek(paragraphLutOffset);
+  uint16_t count;
+  serialization::readPod(f, count);
+  if (count == 0 || page >= count) {
+    f.close();
+    return std::nullopt;
+  }
+
+  // Validate that the target entry fits within the file
+  const uint32_t entryEnd = paragraphLutOffset + sizeof(uint16_t) + (page + 1) * sizeof(uint16_t);
+  if (entryEnd > fileSize) {
+    f.close();
+    return std::nullopt;
+  }
+
+  // Seek to the entry for the requested page
+  f.seek(paragraphLutOffset + sizeof(uint16_t) + page * sizeof(uint16_t));
+  uint16_t pIdx;
+  serialization::readPod(f, pIdx);
+
+  f.close();
+  return pIdx;
+}

lib/Epub/Epub/Section.h

@@ -42,4 +42,14 @@ class Section {
 
   // Look up the page number for an anchor id from the section cache file.
   std::optional<uint16_t> getPageForAnchor(const std::string& anchor) const;
+
+  // Look up the page number for a paragraph index (1-based, from XPath p[N]).
+  // Uses the per-page paragraph index LUT stored in the section cache.
+  // Returns nullopt if the paragraph LUT is not available (old cache format).
+  std::optional<uint16_t> getPageForParagraphIndex(uint16_t pIndex) const;
+
+  // Look up the paragraph index for a given page number.
+  // Returns the 1-based paragraph index of the last <p> element on or before the page.
+  // Returns nullopt if the paragraph LUT is not available (old cache format).
+  std::optional<uint16_t> getParagraphIndexForPage(uint16_t page) const;
 };

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -451,6 +451,19 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
     }
   }
 
+  // Track body element depth for paragraph index counting
+  if (strcmp(name, "body") == 0 && self->xpathBodyDepth < 0) {
+    self->xpathBodyDepth = self->depth;
+  }
+
+  // Count <p> sibling indices at body-child level. Must happen BEFORE the display:none
+  // check so that hidden <p> elements are still counted, matching ChapterXPathIndexer's
+  // counting (pure XML, no CSS). This ensures paragraph indices in the section cache LUT
+  // align with KOReader's crengine XPath indices.
+  if (self->xpathBodyDepth >= 0 && self->depth == self->xpathBodyDepth + 1 && strcmp(name, "p") == 0) {
+    self->xpathParagraphIndex++;
+  }
+
   if (matches(name, SKIP_TAGS, NUM_SKIP_TAGS)) {
     // start skip
     self->skipUntilDepth = self->depth;
@@ -1034,6 +1047,7 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
       anchorData.push_back({std::move(pendingAnchorId), static_cast<uint16_t>(completedPageCount)});
       pendingAnchorId.clear();
     }
+    paragraphIndexPerPage.push_back(xpathParagraphIndex);
     completePageFn(std::move(currentPage));
     completedPageCount++;
     currentPage.reset();
@@ -1052,6 +1066,7 @@ void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
   }
 
   if (currentPageNextY + lineHeight > viewportHeight) {
+    paragraphIndexPerPage.push_back(xpathParagraphIndex);
     completePageFn(std::move(currentPage));
     completedPageCount++;
     currentPage.reset(new Page());

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -75,6 +75,14 @@ class ChapterHtmlSlimParser {
   std::vector<std::pair<std::string, uint16_t>> anchorData;
   std::string pendingAnchorId;  // deferred until after previous text block is flushed
 
+  // Paragraph index tracking for XPath-to-page lookup table.
+  // Counts <p> sibling indices (1-based, matching XPath convention) during page building.
+  // Stored per page in the section cache so that XPath p[N] can be resolved to a page
+  // without reparsing, and current page can generate an XPath without reparsing.
+  uint16_t xpathParagraphIndex = 0;             // current <p> sibling index (1-based)
+  int xpathBodyDepth = -1;                      // depth of the <body> element (-1 = not yet seen)
+  std::vector<uint16_t> paragraphIndexPerPage;  // <p> index at each page completion
+
   // Footnote link tracking
   bool insideFootnoteLink = false;
   int footnoteLinkDepth = -1;
@@ -126,4 +134,5 @@ class ChapterHtmlSlimParser {
   bool parseAndBuildPages();
   void addLineToPage(std::shared_ptr<TextBlock> line);
   const std::vector<std::pair<std::string, uint16_t>>& getAnchors() const { return anchorData; }
+  const std::vector<uint16_t>& getParagraphIndexPerPage() const { return paragraphIndexPerPage; }
 };

lib/I18n/translations/english.yaml

@@ -264,6 +264,8 @@ STR_SYNCING_TIME: "Syncing time..."
 STR_CALC_HASH: "Calculating document hash..."
 STR_HASH_FAILED: "Failed to calculate document hash"
 STR_FETCH_PROGRESS: "Fetching remote progress..."
+STR_MAPPING_REMOTE: "Mapping remote position..."
+STR_MAPPING_LOCAL: "Calculating local position..."
 STR_UPLOAD_PROGRESS: "Uploading progress..."
 STR_NO_CREDENTIALS_MSG: "No credentials configured"
 STR_KOREADER_SETUP_HINT: "Set up KOReader account in Settings"

lib/KOReaderSync/ChapterXPathIndexer.cpp

@@ -599,3 +599,43 @@ bool ChapterXPathIndexer::tryExtractSpineIndexFromXPath(const std::string& xpath
   outSpineIndex = static_cast<int>(parsed) - 1;
   return true;
 }
+
+bool ChapterXPathIndexer::tryExtractParagraphIndexFromXPath(const std::string& xpath, uint16_t& outParagraphIndex) {
+  outParagraphIndex = 0;
+  if (xpath.empty()) {
+    return false;
+  }
+
+  const std::string normalized = normalizeXPath(xpath);
+
+  // Find /p[ after the second /body/ (the inner body inside DocFragment)
+  const std::string bodyKey = "/body";
+  size_t secondBody = normalized.find(bodyKey);
+  if (secondBody != std::string::npos) {
+    secondBody = normalized.find(bodyKey, secondBody + bodyKey.size());
+  }
+
+  const std::string pKey = "/p[";
+  const size_t pos = normalized.find(pKey, secondBody != std::string::npos ? secondBody : 0);
+  if (pos == std::string::npos) {
+    return false;
+  }
+
+  const size_t start = pos + pKey.size();
+  size_t end = start;
+  while (end < normalized.size() && std::isdigit(static_cast<unsigned char>(normalized[end]))) {
+    end++;
+  }
+
+  if (end == start || end >= normalized.size() || normalized[end] != ']') {
+    return false;
+  }
+
+  const long parsed = std::strtol(normalized.substr(start, end - start).c_str(), nullptr, 10);
+  if (parsed < 1 || parsed > UINT16_MAX) {
+    return false;
+  }
+
+  outParagraphIndex = static_cast<uint16_t>(parsed);
+  return true;
+}

lib/KOReaderSync/ChapterXPathIndexer.h

@@ -64,4 +64,16 @@ class ChapterXPathIndexer {
    *         (converted to 0-based outSpineIndex); false otherwise
    */
   static bool tryExtractSpineIndexFromXPath(const std::string& xpath, int& outSpineIndex);
+
+  /**
+   * Extract the paragraph index from a KOReader XPath.
+   * Looks for the first /p[N] segment after /body/ and returns N (1-based).
+   *
+   * Example: "/body/DocFragment[7]/body/p[685]/text().96" → outParagraphIndex = 685
+   *
+   * @param xpath KOReader XPath
+   * @param outParagraphIndex 1-based paragraph index
+   * @return true if a /p[N] segment was found
+   */
+  static bool tryExtractParagraphIndexFromXPath(const std::string& xpath, uint16_t& outParagraphIndex);
 };

lib/KOReaderSync/ProgressMapper.cpp

@@ -19,12 +19,17 @@ 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 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);
+  // Generate XPath for the current position.
+  // Prefer paragraph index from the section cache LUT (exact element mapping) over
+  // byte-offset estimation (which can drift in chapters with non-uniform content density).
+  if (pos.hasParagraphIndex && pos.paragraphIndex > 0) {
+    result.xpath = "/body/DocFragment[" + std::to_string(pos.spineIndex + 1) + "]/body/p[" +
+                   std::to_string(pos.paragraphIndex) + "]";
+  } else {
+    result.xpath = ChapterXPathIndexer::findXPathForProgress(epub, pos.spineIndex, intraSpineProgress);
+    if (result.xpath.empty()) {
+      result.xpath = generateXPath(pos.spineIndex);
+    }
   }
 
   // Get chapter info for logging
@@ -64,6 +69,12 @@ CrossPointPosition ProgressMapper::toCrossPoint(const std::shared_ptr<Epub>& epu
       resolvedIntraSpineProgress = intraFromXPath;
       usedXPathMapping = true;
     }
+    // Extract paragraph index from XPath for direct page lookup via section cache
+    uint16_t pIndex = 0;
+    if (ChapterXPathIndexer::tryExtractParagraphIndexFromXPath(koPos.xpath, pIndex)) {
+      result.paragraphIndex = pIndex;
+      result.hasParagraphIndex = true;
+    }
   }
 
   if (!usedXPathMapping) {

lib/KOReaderSync/ProgressMapper.h

@@ -8,9 +8,11 @@
  * CrossPoint position representation.
  */
 struct CrossPointPosition {
-  int spineIndex;  // Current spine item (chapter) index
-  int pageNumber;  // Current page within the spine item
-  int totalPages;  // Total pages in the current spine item
+  int spineIndex;                  // Current spine item (chapter) index
+  int pageNumber;                  // Current page within the spine item (estimated if no paragraph LUT)
+  int totalPages;                  // Total pages in the current spine item
+  uint16_t paragraphIndex = 0;     // 1-based <p> index from XPath (0 if unavailable)
+  bool hasParagraphIndex = false;  // True when paragraphIndex was resolved from XPath
 };
 
 /**