Native: comic panel box (xywh) is ignored

[ddfreiling]

Summary

Guided-navigation cues for comics can carry a panel box, e.g. imgref: "image0001.jpg#xywh=pixel:44,113,757,226". Web reads it and pans/zooms to the panel while the audio plays. iOS and Android ignore it, so they turn the page but always show the whole page.

Where it stands today

Platform	Page turn on cue	Pan/zoom to panel
Web	✅	✅ comicRegion → FlutterDivinaNavigator.panToRegion
iOS	✅	❌ no xywh parsing anywhere
Android	✅ (after #234)	❌ no xywh parsing anywhere

Related defect on iOS

iOS passes the raw imgref through as the item's text reference:

// GuidedNavigationDocument.swift
if let audio = obj.audioref, let text = obj.textref ?? obj.imgref {

FlutterMediaOverlayItem then splits on # and publishes the fragment as a CSS selector:

locator.locations.otherLocations["cssSelector"] = .string("#\(frag!)")

For a panel cue that yields cssSelector: "#xywh=pixel:44,113,757,226" — not a DOM id, and not a valid selector. It reaches Dart on every comic cue. Android avoids this (#234 drops the fragment); iOS still needs it handled, ideally by parsing the box instead of discarding it.

Suggested work

1. Parse #xywh=pixel:x,y,w,h in the iOS and Android guided-navigation item models.
2. Carry the box on the cue locator, the way web puts comicRegion in otherLocations.
3. Pan/zoom the native comic navigators to the box, with the same auto-pan and manual-override gating web uses.
4. Stop publishing the box as a cssSelector on iOS.

Web reference: flutter_readium/web/src/mediaoverlay/syncNarration.ts (parseImgField, textLocatorForItem) and _syncDivinaToMediaOverlayLocator in ReadiumReader.ts.

[ddfreiling]

Alternative route tracked in #244: ask the Readium toolkits to consume the #xywh fragment themselves, or send them the patches. That would replace steps 1-3 here rather than sit beside them — worth deciding before anyone starts the native implementation.

[ddfreiling]

Upstream route (folded in from #244, now closed)

Before anyone starts steps 1-3 above, decide where the code lives. Readium's own navigators ignore the #xywh fragment too, so the alternative is to fix it upstream and carry no geometry code here at all.

Where upstream would need it:

Toolkit	DiViNa renderer	#xywh
kotlin-toolkit	ImageNavigatorFragment (readium/navigator/src/main/java/org/readium/r2/navigator/image/ImageNavigatorFragment.kt) — native PhotoView, no WebView	not handled
swift-toolkit	EPUBNavigatorViewController fixed-layout path; CBZNavigatorViewController is deprecated in 3.x	not handled
ts-toolkit	navigator	not checked

The Android and iOS renderers share nothing, so this is one ask per toolkit, not one shared change. Two ways to move it: file the request and let them schedule it, or write the patches and send the PRs ourselves.

The trade-off is plain. Upstream is the right home and removes the maintenance, but it is three separate native implementations on someone else's release schedule. Doing it here is faster and unblocks us, at the cost of owning the geometry code on both platforms forever.

Related upstream discussion: readium/webpub-manifest#84 (Divina: linkable rectangles in images).