Seems like it was built on top of overlay PR branch, better to separate them

Rebased

How well does this work? I was doing some light testing in #61 on the KOReader side of things by replacing its own sync function with a percentage based look-up. If you do this, then the syncing can technically be two-way preserved.

But, I think KOReader bases its % on ‘page index / total pages’, not book size as crosspoint does. So text based books should probably be pretty close in terms of syncing, but books with a lot of images might be a bit off.

I don’t own an X4, so I could be very wrong.

Caveat; I dont use a loot of books containing images, so YMMV
The relative position within a file will probably be different if the reader would include graphics as the rendered images will consume space.
For my use cases, it was close enough

But, I think KOReader bases its % on ‘page index / total pages’, not book size as crosspoint does. So text based books should probably be pretty close in terms of syncing, but books with a lot of images might be a bit off.

GetCumulativeSize function that percentage calculation relies on uses uncompressed sizes of each spine item file (the XHTML/HTML/other spine href targets) and accumulates those sizes; it does not include images referenced inside those files. So it should work the same for image-heavy books as for non-image books

@osteotek Do you happen to know if there are methods already implemented to achieve a ‘current page / total pages’ calculation instead of using the size? Or does the file have to be fully indexed before that can be done? I don't think that should replace all references to % as already done, but in this specific domain of KOSync, it's probably valuable to try and match up so that it'll work regardless of the file being synced.

@jpirnay I’ve tested this, and it appears to work better than before. At least, it doesn’t always sync to the beginning of the chapter on the Crosspoint side. However, syncing from crosspoint to the remote server and then fetching progress on another Koreader always puts me at the beginning of the next chapter (not the same one I’ve been reading on Crosspoint). Is this the same for you?

@jpirnay I’ve tested this, and it appears to work better than before. At least, it doesn’t always sync to the beginning of the chapter on the Crosspoint side. However, syncing from crosspoint to the remote server and then fetching progress on another Koreader always puts me at the beginning of the next chapter (not the same one I’ve been reading on Crosspoint). Is this the same for you?

You are pointing our a very important issue:
The XPath being handed over is a synthetic, chapter-level XPath pointing to the DocFragment corresponding to the current spine item (chapter). It is not the XPath of the closest text fragment, as CrossPoint does not preserve detailed HTML structure during parsing—only the linear spine and page counts.

We are assuming KOReader uses the XPath to identify the DocFragment and the percentage for fine positioning within it (thats how Crosspoint does it when reading something). However, based on KOReader's syncToProgress implementation, it only uses GotoXPointer(xPath) for EPUB, ignoring percentage. This results in positioning at the start of the specified DocFragment (chapter start), not an exact location.

Reality: Sync achieves approximate, chapter-level positioning, not pixel-perfect sync. KOReader lands at the beginning of the DocFragment because the XPath lacks detailed element paths (e.g., no <p> or <div> tags). Real KOReader XPaths are detailed (e.g., /body/DocFragment/body/div/div[4]/ul/li[3]...), but CrossPoint can't generate them.

If KOReader were modified to use percentage for intra-DocFragment positioning, sync would be more accurate. As-is, this is the best CrossPoint can do. It works for round-trip CrossPoint sync, and provides chapter-level KOReader positioning.

@jpirnay thanks for the analysis, seems like we can't solve this without modifications to how crosspoint stores text, or without reparsing html doc on every sync. PR in its current form looks like a good addition, I've tested it, works good.

For the brave of heart, @iandchasse pointed out a solution for better KOReader sync behaviour, which requires the patching of a single file though: #61 (comment)

@jpirnay would it be possible to fix merge conflicts here?

@jpirnay would it be possible to fix merge conflicts here?

Done

No actionable comments were generated in the recent review. 🎉

Learnt from: Levrk
Repo: crosspoint-reader/crosspoint-reader PR: 909
File: src/activities/reader/EpubReaderActivity.cpp:461-461
Timestamp: 2026-02-16T20:43:19.339Z
Learning: In src/activities/reader/EpubReaderActivity.cpp, when using ConfirmationActivity with enterNewActivity(), it's not necessary to call exitActivity() beforehand. The ConfirmationActivity operates as a modal dialog and cleanup is handled via the pendingSubactivityExit flag in the callback lambda. This differs from other activities like EpubReaderChapterSelectionActivity or KOReaderSyncActivity which do require exitActivity() before enterNewActivity().

Learnt from: GavinHigham
Repo: crosspoint-reader/crosspoint-reader PR: 966
File: src/activities/ActivityWithSubactivity.h:20-21
Timestamp: 2026-02-18T15:43:07.515Z
Learning: In the crosspoint-reader activity architecture, when using ActivityWithSubactivity, the currentActivity global variable remains at the top-level activity (e.g., ReaderActivity) even when nested subactivities are active. The supportsOrientation() delegation chain starts from the top-level activity and stops when it reaches a subactivity that overrides the method (e.g., EpubReaderActivity returns true). Deeper nested subactivities (like EpubReaderChapterSelectionActivity or EpubReaderPercentSelectionActivity) do not need to override supportsOrientation() because they never become the currentActivity and the delegation chain doesn't reach them.

sequenceDiagram
    participant Activity as KOReaderSyncActivity
    participant Mapper as ProgressMapper
    participant Epub as Epub
    participant UI as UI/RenderLock

    Activity->>Mapper: toCrossPoint(epub, koPos, currentSpineIndex, totalPagesInCurrentSpine)
    Mapper->>Epub: read spine boundaries / byte positions
    Epub-->>Mapper: spine byte map
    Mapper-->>Activity: CrossPointPosition (spineIndex, pageNumber, totalPages)
    Activity->>Activity: compare localProgress.percentage vs remoteProgress.percentage
    Activity->>UI: acquire RenderLock / update selected option
    UI-->>Activity: release RenderLock

_{Comment @coderabbitai help to get the list of available commands and usage tips.}