fix: prefer newer server progress over stale local EPUB locator

[bruno-b-martins]

Closes #276

Problem

Opening an EPUB always used the locator saved on the device, so progress made on another device was ignored and the book reopened at the old position, even though the book card showed the right percentage.

Fix

The reader now follows the fresh BookOrbit percent only when it is:

• more than 2 points ahead of the saved locator (smaller gaps are renderer drift, Progress sync out of sync after update to 1.5.0 #96; progress that moved backwards is never followed), and
• not this device's own write, meaning it is not within 1 point of the percent this device last reported.

Otherwise the exact local locator is kept. When the server wins, the reader positions from the server percent alone, starts the reading session from where it opens, and drops the old narration position unless narration is still playing.

The server percent is set only by a progress fetch that matched the file. Locators without a total progression (narration, annotations) are compared using the book's own positions.

Verification

• Not built or run. The sandbox had no Android SDK, so CI is the first real build (it needs maintainer approval for this fork PR).
• Not tested on devices, including the two-device scenario from EPUB resumes from stale local position instead of newer BookOrbit progress from another device #276.

Known limitations

• Progress that moved backwards on another device is not followed.
• Relaunching straight into an active reader (cold start or process death) keeps the local locator. Downloaded EPUBs restore through a local-only startup pass, so covering this means changing the startup flow.
• Own writes are recognized only if the server returns the reported percent within 1 point. How BookOrbit rounds is not documented and was not checked.
• Another client's write that lands ahead of the locator (for example marking a book as read) is followed.
• Offline opens, and PDF and comic readers, are unchanged. Komga already passes the server locator.

🤖 Generated with Claude Code

[van-geaux]

Thanks for the thorough investigation and implementation work on this.

I had not anticipated Lagrange being used across multiple devices with the same server configuration, so this uncovered an important gap in the EPUB resume behavior. Your work provides a strong basis for addressing it.

During review, I identified one remaining edge case around narration cleanup. When server progress wins, stale TTS position cleanup currently occurs from updateLocation() only if the TTS service is already bound. If the initial location update happens before the asynchronous service connection completes, cleanup can be skipped. An old narration position could then be reused later even though the reader resumed from newer server progress.

We are happy to take ownership of that remaining part. We will add a helper that can complete the cleanup from both updateLocation() and the TTS service onConnected callback, while preserving an active narration session, and add regression coverage for the service-binding race.

Version 2.0.0 is currently being prepared, so this work will be scheduled for a post-2.0.0 release. We will approve the completed implementation after the maintainer follow-up and validation are finished.

Thank you again for identifying and addressing this previously unanticipated multi-device use case.

[bruno-b-martins]

Thanks for the review and for catching the binding race! To save you the follow-up, I've pushed 699ccb7: the cleanup now lives in a small StaleNarrationPositionCleanup and is completed from both updateLocation() and the TTS service onConnected callback, whichever comes last, still preserving an active narration session. It includes unit tests for both orderings. Happy for you to adjust or replace it however suits the post-2.0.0 plan.

🤖 Generated with Claude Code

[bruno-b-martins]

One more follow-up: 0b3bca9 keeps a pending narration cleanup across reader recreation (rotation or process death). The server progress is consumed when it wins, so a reader recreated before the cleanup completed would otherwise restore the old narration position. The pending flag is now saved with the instance state and the cleanup resumes in the recreated reader, with unit tests covering it.

🤖 Generated with Claude Code

[van-geaux]

Thanks for the detailed implementation and for working through the TTS and recreation edge cases. I checked the current BookOrbit API and found that it does expose an updatedAt value in the book progress response. The underlying progress record also has more specific fields such as lastReadAt, textUpdatedAt, and narrationUpdatedAt.

There are some important caveats, though. BookOrbit’s server code does not treat updatedAt as a universal “last read” timestamp. Its meaning varies by writer, and the KOReader path deliberately freezes it. The more precise timestamp fields are available from the file-level progress endpoint, but not from the book-level endpoint that Lagrange currently uses.

Because of that, I’m not sure we can safely replace the current percentage-based rule with a simple timestamp comparison yet. Would you be open to discussing whether Lagrange should consume the file-level progress data, whether BookOrbit should expose a provider-neutral progress revision or authoritative text-position timestamp, or whether the current percentage fallback is the right short-term approach?

If we keep the percentage logic for now, I think we should document its thresholds and limitations clearly, then consider a server revision or text-position timestamp as a future improvement.