fix(media-overlay): gate resource-first fallback on cross-resource navigation - #228
Merged
ddfreiling merged 1 commit intoSep 15, 2026
Conversation
…vigation When a ToC entry's fragment points at an element with no narration cue (e.g. a chapter heading `chap1.xhtml#title`), the text→audio mapper previously behaved inconsistently across platforms: - iOS/Android: returned nil → audio kept playing at wrong position (desync). - Web: always fell back to the resource's first cue, even within the current chapter (spurious rewind). Now all three platforms apply the same policy: fall back to the resource's first cue only when tapping *into a different resource* than the one currently playing. An uncued anchor within the current chapter leaves audio untouched. Implementation: - `FlutterMediaOverlay.itemFromLocator` (iOS) and `findItemFromLocator` (Android) gain an `allowResourceFallback` flag (default true) that gates both the new unmatched-id fallback and the existing no-fragment/html fallback. Exact matches (by time or matched id) are unaffected. - `textLocatorToAudioLocator` (web) gains the same flag. - Each navigator computes `crossResource` from the currently-playing item's text file vs. the tapped locator's href, and passes it as the flag. No current position (initial play / play-from-locator) → true → fallback allowed, preserving existing behaviour for those paths. - iOS: new `FlutterMediaOverlayTests` unit tests cover exact-match, unmatched-id (flag true/false), no-fragment (flag true/false), wrong-href. - Web: extended `syncNarration.test.ts` with `allowResourceFallback=false` cases for both fallback branches. - Android: `FlutterMediaOverlayItem` depends on `android.os.Parcelable` and `android.util.Log`, blocking plain-JVM unit tests; gating logic is covered by the iOS tests (identical pattern) and E2E integration tests. Fixes Notalib#139 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
SifAa
approved these changes
Sep 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes Media Overlay navigation when a ToC or bookmark anchor has no matching narration cue.
Bug
A ToC entry can point to an element without a narration cue, for example
chapter.xhtml#titlewhen narration starts at#p1. Previously, Web always sought to the resource start, while iOS and Android left audio at its prior location. This caused either an unexpected same-chapter rewind or visual/audio desynchronization across chapters.Validation
bin/formatbin/analyzebin/typecheckbin/update_web_example:flutter_readium:testDebugUnitTestRunnerTestson simulatorRemaining Manual Check
Fixes #139