fix: Switch to xpath map for paragraph level syncing in KOSync (#1686)

Switch KOReader sync progress mapping from chapter matching to
XPath-based mapping.

- resolves KOReader positions using real XHTML ancestry paths
- supports paragraph-based upload mapping with text offsets
where needed
- passes the current paragraph index into sync so uploads map
back to KOReader more accurately

No HTTP client changes are included. No reader-state or resume-flow
changes are included.

---------

Co-authored-by: jpirnay <jens@pirnay.com>

lib/KOReaderSync/ChapterXPathResolver.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <Epub.h>
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+class ChapterXPathResolver {
+ public:
+  /**
+   * Resolve the Nth paragraph in a spine item to its real XHTML ancestry path.
+   *
+   * Returns a KOReader-compatible path like:
+   * /body/DocFragment[8]/body/div[2]/section[1]/p[4]
+   *
+   * An empty string means parsing failed or the paragraph index was not found.
+   */
+  static std::string findXPathForParagraph(const std::shared_ptr<Epub>& epub, int spineIndex, uint16_t paragraphIndex);
+
+  /**
+   * Resolve intra-spine progress to a real XHTML ancestry path plus text offset.
+   *
+   * Returns a KOReader-compatible path like:
+   * /body/DocFragment[8]/body/div[2]/section[1]/p[4]/text().96
+   *
+   * An empty string means parsing failed or the location could not be resolved.
+   */
+  static std::string findXPathForProgress(const std::shared_ptr<Epub>& epub, int spineIndex, float intraSpineProgress);
+};