Skip to content

fix(reader): refresh a cached page list that no longer matches the book - #1340

Merged
everpcpc merged 2 commits into
kmworks:mainfrom
spawvn:fix/refresh-stale-page-list
Nov 17, 2026
Merged

everpcpc merged 2 commits into
kmworks:mainfrom
spawvn:fix/refresh-stale-page-list

Conversation

@spawvn

@spawvn spawvn commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1339

Problem

When a book's file is replaced on the server with a version that has one more page, the reader keeps the page list it cached before. Page images are requested by number and come from the new file, while their sizes and the page count come from the old list. From the added page on, each page gets the size of the page after it: a spread opens as a single page, a portrait page opens as a spread, and the counter shows one page fewer. Details in #1339.

Root cause

  • ReaderContentService.loadPages(for:) and fetchSegmentPages(for:…) use the cached KomgaBook.pages whenever it exists, and refresh it from the server only when a page lacks dimensions.
  • Syncing a book (applyBook(dto:to:)) updates its media, including pagesCount, but leaves the cached page list alone.
  • Page images are requested by number (/api/v1/books/{id}/pages/{n}), which Komga resolves against its current analysis of the file.

Fix

  • A cached page list now also needs a refresh when its length differs from the book's media.pagesCount (cachedPagesMatch(_:book:)).
    • The reader syncs the book from the server before it loads pages, so that count is current.
    • Komga sets it to the length of the page list for every format the image reader opens: archives, image-only EPUBs and PDFs.
  • When the count no longer matches, the refresh also clears the book's page-image cache (CacheManager.clearCache(forBookId:)) and takes the server's list as is.
    • A changed file can reuse a page's number and file name for another image, and both key the cached images and the sizes the old list would fill in by file name.
    • The refresh for missing dimensions still keeps known sizes and cached images.
  • The check runs where the existing missing-dimensions refresh runs: online and not reading offline-first.
  • A downloaded book keeps its cached list even when the count differs. The reader shows its downloaded files, and that list describes them.
  • Lists that are already stale on devices, like the one in the report, are replaced the next time the book opens.
  • resolvePageDimensions is renamed resolvePages(for:…), and the refresh moves into refreshedCachedPages(_:for:).

Why this shape

  • The list is checked where the reader decides whether to trust it, against a count it already syncs, so there's no new stored state or migration. Invalidating the cache when a sync sees the media change would only cover future changes: a book whose new media is already synced would keep its stale list.
  • Refetching the page list on every open would also catch changes that keep the page count, but it adds a request to every open. The count covers the reported case, pages added or removed, at no cost.

Not changed

  • A downloaded book whose file later changes on the server keeps reading its downloaded copy. Noticing that a download is outdated would be a separate change.
  • Changes that keep the page count, such as one page replaced by another, are not detected.

Validation

  • Builds on iOS, macOS, and tvOS (make build-ios, make build-macos-ci, make build-tvos-ci).
  • iPad (A16) simulator, iOS 26.5, Komga 1.26.3, Split Wide Pages set to Scroll, Page Curl. Test books:
    • A 284-page CBZ with five two-page spreads, and a copy of it with one early page removed (283 pages).
    • A synthetic CBZ named by position, 001.png–004.png = A, B, C (spread), D, renumbered to 001.png–005.png = X, A, B, C (spread), D.
  • Checks 1, 2 and 4 ran on the first commit; 3 and 5 also ran on the final one.
    1. On main:
      • I opened the 283-page version, so the app cached its list.
      • I replaced the file at the same path with the 284-page version and deep-scanned the library. Komga kept the book ID and reported 284 pages.
      • I cleared the app's cached images for the book and opened it again.
      • The reader showed "/283", and the spread at page 282 opened as a single letterboxed page.
      • The portrait page at 280 looked normal with border cropping off. With cropping set to Conservative, it opened enlarged, cut off at the right, and pannable like a spread.
    2. With the fix, from that same state, with Conservative cropping and the images cached under the stale list left in place:
      • The reader showed "/284".
      • Page 280 opened as a normal page, and 281 and 282 opened as spreads.
    3. A downloaded book:
      • I downloaded the 284-page version in the app, then replaced the server's file with the 283-page version (deep scan).
      • Reopened online, the reader kept its list ("/284") and showed the downloaded pages: 280 as a normal page, and 281 and 282 as spreads.
    4. A book whose cached list matches the server (7 pages, a spread at page 2) opens as before: "2 / 7", with the spread at its start edge.
    5. Renumbered file. I opened the positional book at v1 and viewed every page, so all four images were cached as page/N/00N.png. Then I replaced it with v2 (deep scan) and reopened:
      • On the first commit, the reader showed "/5" but the cached images: A, B and D on pages 1, 2 and 4, and spread C letterboxed as a single page on page 3.
      • On the final commit, it showed X, A, B, C (as a spread) and D, with "5 / 5".
      • Going the other way (the app on v2's list, the server back on v1), the refresh emptied the cache and the reader showed A, B, C (spread) and D.
  • The macOS and tvOS builds weren't run.

🤖 Generated with Claude Code

The reader keeps each book's page list, with page sizes, in the local
database and reuses it on later opens, refreshing it from the server only
when a page lacks dimensions. When the book's file changes on the server
and Komga analyzes it again, the cached list stays as it was. Page images
are still requested by number, so they come from the new analysis while
their sizes and the page count come from the old one.

A file that gained a page early on shifts every later page by one: a
portrait page takes the size of the spread after it and opens as a spread,
a spread takes the size of the portrait page after it and opens as a
single page, and the reader shows one page fewer than the book has.

A cached list now also counts as stale when its length differs from the
book's page count, which the reader syncs from the server before loading
pages, and is refreshed then. Komga sets that count to the length of the
page list for every format the image reader opens. A downloaded book keeps
its cached list, since it describes the downloaded files the reader shows.

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

@everpcpc everpcpc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The count-based refresh is a good minimal way to repair stale page metadata, and the offline/downloaded handling looks consistent. However, the image-cache path still needs invalidation for renumbered replacement files; otherwise the reader can combine new page metadata with old cached images. I have left a blocking inline comment with a concrete example and the suggested invalidation scope.

…pages

A refresh triggered by the page-count check replaced the cached page list
but kept the book's cached page images, and filled sizes missing from the
server's list from the cached list by file name. The image cache is keyed
by page number and file name, and a renumbered file reuses both for other
images: after 001=A, 002=B became 001=X, 002=A, the refreshed page 2 still
showed the cached B. A size carried over by file name can likewise belong
to another image.

When the book has changed, the refresh now clears the book's page-image
cache and takes the server's page list as is. The refresh for missing
dimensions still keeps known sizes and cached images, and downloaded books
are still exempt.

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

spawvn commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

The failing iOS check isn't from this change. make build-ios-ci stopped before compiling, with Unable to find a device matching the provided destination specifier: { id:CAAFE82E-B73F-4CEC-BA71-BDBC99DE712E }. macOS and tvOS passed on the same commit, and iOS passed on the previous commit, so re-running the iOS job should go through.

The cause is the simulator selection in misc/xcode.py. In non-interactive mode, build asks select_device for a concrete simulator. list_simulators collects every available device from every iOS runtime in simctl list devices --json, and the first one is picked. On that runner, the first one (an iPhone 18 Pro) wasn't among the destinations xcodebuild offered for the scheme. Its list shows the iPhone 18 Pro under another ID, so the picked device presumably belongs to a runtime the selected Xcode doesn't support.

If you'd like to rule this out: a build needs no concrete device, so --ci builds could use the generic destination the script already has for build-only actions:

if normalized in ("ios", "tvos"):
    if ci_mode:
        destination = self._generic_simulator_destination(normalized)
    else:
        ...  # existing select_device logic

Alternatively, list_simulators could keep only devices that xcodebuild -showdestinations lists for the scheme.

🤖 Generated with Claude Code

@everpcpc everpcpc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The update resolves the blocking cache-coherence issue. Count-mismatch refreshes now clear the book’s cached images and no longer carry over dimensions by file name, while missing-dimensions refreshes and downloaded books retain their previous behavior. The positional-name validation covers the reported counterexample, including both adding and removing a page. I have no further code findings. The remaining iOS check failure appears to be the documented simulator-destination issue rather than a code failure; please rerun it before merge.

@everpcpc
everpcpc merged commit 5b053f9 into kmworks:main Nov 17, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A replaced book keeps its old page list, so pages get the wrong sizes and spreads are misdetected

2 participants