Skip to content

EPUB: link to an earlier reading-order resource doesn't navigate in scrolled mode (link to a later resource works) #229

Description

@a-martynyshyn

Environment

  • flutter_readium: 0.4.4
  • Platform: Android (reproduced on emulator, API 37)
  • EPUBPreferences.scroll = true (vertical continuous scroll, not paginated)

Summary

An internal EPUB link (<a href="otherfile.xhtml#anchor">) whose target is an earlier
resource in the reading order doesn't navigate — tapping it does nothing. The mirror-image link,
pointing to a later resource, navigates correctly. Both links are structurally identical and
the underlying EPUB markup is correct and symmetric on both sides (verified directly in the
decrypted .epub, see below) — this isn't a content-authoring issue.

Repro

EPUB has two reading-order items, e.g. chapter.xhtml (earlier) and notes.xhtml (later,
appears after chapter.xhtml in the spine). They cross-reference each other with a standard
noteref/backlink pair:

<!-- chapter.xhtml — reference, in the body text -->
<p>...some paragraph text<a id="ref_back" href="notes.xhtml#ref">[1]</a>.</p>

<!-- notes.xhtml — the note, with a link back to where it was referenced -->
<p><a href="chapter.xhtml#ref_back" id="ref">[1]</a> Note text...</p>
  1. Open the book with EPUBPreferences.scroll = true.
  2. From chapter.xhtml, tap the [1] reference → correctly navigates forward to notes.xhtml#ref.
  3. From notes.xhtml, tap the [1] backlink to return → does not navigate. Stays on
    notes.xhtml; no error, no locator change.

Step 2 (forward, to a later resource) works every time. Step 3 (backward, to an earlier
resource) never navigates, using the exact same markup pattern.

Why we're confident this isn't a content bug

Extracted the decrypted EPUB and confirmed both anchors are present, well-formed, and correctly
paired:

  • chapter.xhtml contains <a id="ref_back" href="notes.xhtml#ref">[1]</a> exactly where the
    note is referenced.
  • notes.xhtml contains <a href="chapter.xhtml#ref_back" id="ref">[1]</a> exactly matching it.

Both hrefs are valid relative paths and both target ids exist in the target document at the
expected location. There is no asymmetry in the markup that would explain why one direction
works and the other doesn't.

Notes

  • We initially suspected this was related to tap-zone/page-turn gesture handling in paginated
    mode (a separate, already-known class of issue where taps near screen edges can be captured by
    page-navigation zones instead of reaching a link). We specifically re-tested in scrolled
    mode, where there is no tap-zone concept at all (navigation is by scrolling, not discrete page
    taps), to rule that out. The backward-link failure reproduces the same way in scrolled mode, so
    it looks unrelated to tap zones — this looks like a goToLocator/internal-link-activation issue
    specific to navigating to a reading-order position before the current one.
  • Happy to provide a minimal reproduction EPUB if useful.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    investigateWe should investigate this issue when possible

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions