spike(epub): native column paging — fix paginated reflowable foreground resume drift

[raphi011]

Summary

Spike (draft, fork-only — not for upstream yet) that fixes the paginated-reflowable "resume one column back, with a brief visible flash" bug on a background→foreground transition, by having the navigator own the column paging instead of delegating it to UIScrollView.isPagingEnabled. Opened against the fork's integration branch so the diff footprint is reviewable before deciding whether to pitch it to readium/swift-toolkit.

This PR is self-contained; everything needed to review it is below.

---

The bug

Open a paginated reflowable EPUB, read a few pages, send the app to the background (Home / app switcher), wait ~2 s, foreground it again — no rotation, no settings change. The reader is now showing the previous page (one column back). A second, quieter symptom rides along: that stale position is treated as linear reading and can be persisted over the correct one. The wrong column is also briefly visible on the way back (the "flash").

Reproduced reliably on iPhone simulator (single-column paginated reflowable).

Root cause (measured)

Instrumented the four layers across the scenePhase .active transition (SwiftUI container size, container/navigator bounds, and the spread WKWebView's scrollView.contentOffset.x / contentSize.width). On a representative run (single column, page width 402):

moment	active spread contentOffset.x	column	contentSize.width
background	9246	23 / 27	10854
returning	8844	22 / 27	10854

• contentSize.width is identical (10854) → no relayout; the column grid is not recomputed.
• The SwiftUI-measured container size is constant and viewDidLayoutSubviews never fires → the app-side hierarchy is innocent.
• The only thing that moves is contentOffset.x: 9246 → 8844, exactly −402 = one column, and it moves while backgrounded (already drifted at the first return event, before any foreground layout).
• Both offsets are exact page multiples (23×402, 22×402).

That last point is the tell. An exact one-page step with no relayout is the signature of a UIScrollView paging re-snap: isPagingEnabled keeps its own notion of the current page, but reflowable column navigation here is driven from JavaScript (window.scrollBy for page turns; progression read from window.scrollX), not from UIKit. The two notions desync, and when iOS restores the paging scroll view on resume it re-snaps contentOffset to its believed page — one column back. On foreground the navigator reads the moved offset and emits a drifted Locator, and the live web view is revealed at the wrong column before any client signal can correct it (the flash).

EPUBReflowableSpreadView already scrolls page turns via JS specifically to avoid setContentOffset glitches (see the comment referencing readium#737), which is exactly why UIKit's paging state and the real column position drift apart.

The fix — 2 commits

1. Own the column paging instead of UIScrollView.isPagingEnabled.
Disable isPagingEnabled for paginated reflowable spreads, set decelerationRate = .fast, and snap a free-scrolling drag to the nearest column boundary in scrollViewWillEndDragging (a clear fling advances one column). With UIKit no longer owning a page index, there is nothing for it to re-snap on resume. Adds overridable column-scroll delegate hooks on EPUBSpreadView, mirroring the existing scrollViewDidScroll override pattern.

2. Make the column index the source of truth and re-assert it across a same-width relayout.
Track currentColumn, captured only from genuine intent (user drag end, programmatic go), never from a passive scroll report. After a layoutSubviews pass whose page width is unchanged, re-derive contentOffset.x from currentColumn, so any external re-snap (e.g. an OS scroll-view restore on foreground) is corrected deterministically. A width change (rotation / font size / Split View) re-baselines instead and defers to the navigator's existing locator re-pin — the column index is meaningless once the grid reflows.

Design principle: in a paginated column layout the page index is the durable position; the pixel contentOffset is a derived value that must be recomputed for the current geometry, never trusted across a layout event.

Status

• ✅ Compiles — xcodebuild -scheme Readium-Package -destination 'generic/platform=iOS Simulator', clean derived data, ** BUILD SUCCEEDED **.
• ❌ Behaviour NOT verified on device. The JS-scroll ↔ native re-assert seam is the Noticeable screen flicker/flash during page turns between EPUB resources readium/swift-toolkit#737 glitch surface and needs validation.

Reviewer checklist (on device / simulator)

• Does the drift + flash actually disappear on background→foreground?
• Does commit 1 alone fix it? If isPagingEnabled = false is sufficient, commit 2's re-assert can be dropped (≈50-line change, much lower risk). The commits are split precisely to test this.
• Page-turn fidelity: edge-tap, arrow keys, and swipe-drag snap feel; decelerationRate feel.
• RTL — snap/re-assert run in non-negative UIKit column space (reading-direction agnostic in theory), but unverified.
• Scrub / ToC jump / cross-device resume land on the right column and aren't reverted by the re-assert.
• Whether layoutSubviews even fires on the foreground transition (if not, commit 1 must be the load-bearing fix).
• Scroll mode (viewModel.scroll) is untouched — guards bail out early; confirm no regression.

Open questions for an eventual upstream pitch

• Narrow (commit 1 only) vs. general (both commits).
• This is the same "don't trust the raw column offset across a relayout" mechanism that would also address the relayout-restore family — Improve position restoration after changing the font size readium/swift-toolkit#645 (position lost on font-size change) and EPUB page does not snap correctly when layout changed in the multitasking Split View  readium/swift-toolkit#321 (Split View snap). An upstream issue is likely better framed around that general principle than around the foreground case alone.

Files changed

• Sources/Navigator/EPUB/EPUBReflowableSpreadView.swift (+126)
• Sources/Navigator/EPUB/EPUBSpreadView.swift (+16)

[raphi011]

Closing — the spike's premise didn't survive measurement. The foreground resume drift turned out to be app-side, not a WebKit offset re-clamp: a color-scheme flip during the backgrounded snapshot pass triggered a theme-only preference update, whose reflow re-anchor (go(to: firstVisibleElementLocator)) lands one column back through snapOffset's floor bias. Fixed in the app by skipping the anchor restore for theme-only preference changes, so owning the paging natively isn't needed. Corrected analysis summarized on readium#839.