Panel by Panel Navigation

[adrenalin-labs]

Unsure how feasible this is. But Marvel Unlimited has an awesome navigation feature where you can read by Panel instead of by page. So it dynamically zooms in and out depending on the size of the panel when you use the gesture to page through.

[forkger]

Hi @everpcpc. Here's the short proposal. Focused on the data model and reader behaviour as you suggested.


• First let me correct myself as I wrongfully labeled panel-by-panel mode as a non-DIVINA mode. It is indeed a DIVINA mode. It's intended to be selected like the other reading modes and is mutually exclusive with them and when it's on, the page-flow modes (LTR/RTL/Vertical/Webtoon) are off.
• It's direction-symmetric: LTR and RTL are the same traversal run forward vs. reversed, parameterised by the book's reading-direction metadata, so there's no separate "manga path."
• The mode has two layers, so turning it on doesn't immediately disrupt reading:
  • Armed — the mode is on, but the page shows normally (full, fit). Page turns still work as usual.
  • Engaged — a double-tap starts panel-walking, beginning at the panel you tapped (you choose where to enter); another double-tap drops back to the full page. Within a page, taps step panel-to-panel and work bidirectionally from wherever you entered. At the page ends, a step turns the page.
• In the full-page state, a horizontal swipe turns pages directly, so you can move page-to-page without walking through panels.

How panel data is detected and stored:

• Detected via a pluggable provider with a narrow contract: given a page image and reading direction, return an ordered list of panel rects (normalised) in reading order OR empty that shows the whole page. The reader side depends only on that output, never on how detection happened, so the detection engine can iterate independently. (The detection engine itself is being investigated)

• Stored as computed output, not preferences: per-page panel sequences live in the module's own cache with a TTL and a size budget which is separate from the page-image cache and not on the KomgaBook record. So v1 needs no SwiftData migration; the only persisted preference is the mode toggle. Sequences are computed lazily (current page plus a small lookahead), so entering the mode doesn't block on detecting a whole volume.

Interaction with existing modes:

• The mode is self-contained: detection, panel-stepping and the panel cache share no code with the existing engines. It integrates as a small additive layer -> selected mutually-exclusively in the mode picker, owning the viewport and input while active, but delegating between-page traversal to the existing paged-navigation path rather than reimplementing it. That means progress, sync, segment-boundary handling, preload and jump-to-page all keep working unchanged. The integration currency is the current-page index: the module reports "I'm on page N" and everything book-level consumes that as it does today.

Format assumptions:

• Paged single-page content only. Gated by reading-direction metadata and only selectable for LTR/RTL, disabled for Webtoon/Vertical. Implies single-page presentation (including dual-page / split-wide) so panels and the whole-page view share one coordinate space.
• Pages with no detectable panels degrade cleanly such as splash pages, spreads or detection failure -> full page shown and a normal tap or swipe turns it, additionally a pinch zoom.

So the complete scope for v1:

• LTR + RTL paged content; per-book entry via the mode toggle, gated by metadata; double-tap to engage (at the tapped panel) / disengage; module-owned TTL cache, no migration; whole-page fallback; swipe-between-pages.
• Deferred: Whole-book precompute, sub-panel detail beats.

Does this overall shape work for you?

Cheers.

[everpcpc]

Hi @yorforkger, Thanks for the proposal. This overall shape looks good to me. I like the separation between the reader-facing panel sequence contract and the detection implementation, and keeping the panel data as computed cache rather than persisted book metadata makes sense for v1.

A few details I think we should tighten before implementation:

1. I would avoid modeling panel-by-panel as a plain new ReadingDirection. It still needs an underlying effective LTR/RTL direction for traversal, progress UI, tap-zone mirroring, and page navigation. So conceptually it should be something like “panel mode with effective direction = LTR/RTL”, rather than replacing the direction itself.

2. For v1, I think we should be stricter about layout. Single-page paged content is fine, but dual-page and split-wide need explicit rules. My preference is to force single-page layout while panel mode is active, and either disable split-wide for v1 or define whether detection happens on the original page image before splitting. Otherwise the panel coordinate space and tap-to-enter behavior can become ambiguous.

3. The panel cache key should include more than book/page index: page/image identity, detector version, effective reading direction, and any preprocessing/splitting version if applicable. That avoids stale panel rects after image updates or detection algorithm changes.

4. The armed vs engaged state model sounds good, but the gesture ownership should be specified carefully. In armed/full-page state, normal page turns and controls should behave like the existing paged reader. In engaged state, panel stepping owns taps, double-tap exits, and swipe/page-turn behavior should be explicitly defined so it does not conflict with existing tap zones, zoom, and dismiss gestures.

5. Lazy detection should be cancellable / stale-result-safe. If the user flips pages quickly or exits panel mode, late detection results should not update the wrong page/view.

If we lock those down, I think this is a good v1 scope: LTR/RTL paged content, lazy per-page detection with whole-page fallback, no SwiftData migration, and normal book-level progress/navigation remaining page-index based.

[forkger]

Thanks @everpcpc, glad the shape works! I'm adopting all five & here's how each one lands:

1. Effective direction, not a new ReadingDirection.
Adopting this. It's the cleaner model. Panel mode becomes an orthogonal flag, not a new ReadingDirection case: the book's effective LTR/RTL stays the source of truth and panel mode reads it rather than replacing it (so LTR/RTL aren't turned off; only Webtoon/Vertical are out of scope). Traversal order, progress UI, tap-zone mirroring and page navigation all need that effective direction and folding panel mode into the direction enum would throw it away (and force a .panel arm through every site that switches on direction). Keeping it orthogonal also makes the mode direction-symmetric for free: LTR and RTL are the same traversal run forward vs. reversed, parameterised by the direction already on the book.

2. Stricter layout rules.
Agreed. Force single-page while panel mode is active. For split-wide specifically: detection runs on the original page image before any split and split-wide is suppressed while engaged, so there's one image and one coordinate space for both the panel rects and tap-to-enter. A book configured for dual-page/split-wide overrides to single-page for the mode's duration.

3. Richer cache key.
Good catch. The key will include page/image identity (folding in the per-page dimensions and byte size the API exposes), detector version, effective reading direction and preprocessing/split version. So a re-imported or changed image produces a different key and misses the cache and stale rects can't survive an image update or a detector change.

4. Gesture ownership.
This is where the conflicts live, so here's the model in detail. Two layers:

• Armed (mode on, full page showing): the page shows normally and page turns, zoom and controls all work as today. One refinement from my original note (where I implied armed is identical to normal reading): tap input follows panel mode's own tap layout (described below) rather than your configured tap zones, so the geometry stays consistent when you start walking panels.
• Engaged (panel-walking): a double-tap engages at the panel you tapped (you choose where to enter); another double-tap drops back to the full page. While engaged, single taps step panel-to-panel, bidirectional from wherever you entered; at the page ends, a step delegates the actual page turn to the existing paged-navigation path rather than reimplementing it, so progress, sync and segment-boundary handling stay intact.

Conflict points I've accounted for:

• Double-tap-to-zoom is repurposed as the engage/disengage gesture while the mode is active; manual pinch-to-zoom stays (it's a separate gesture, unaffected) so we're just changing what triggers zoom.
• Because the mode keeps the page zoomed into a panel, its taps are captured by the mode's own overlay (sitting above the engine) rather than the normal tap path, which treats a zoomed page as "don't navigate" and would otherwise swallow panel-advance taps.

Dismiss (swipe-down-to-close) is unaffected. It’s the system's sheet-dismiss gesture, a presentation-layer gesture the reader already lives with today. Panel mode only owns taps, so it adds nothing that competes with it; and while you're zoomed into a panel, vertical drags pan within the page, so there's no accidental close mid-walk (the same as zooming into any page today).

5. Cancellable / stale-safe detection.
Agreed and important. In-flight detection is cancelled or discarded on page flip and on mode exit, and results are tagged to the page/view they were requested for, so a late result can never apply to the wrong page.

With those locked, the v1 scope you summarised works for me: LTR/RTL paged content, lazy per-page detection with whole-page fallback, no SwiftData migration and book-level progress/navigation staying page-index based.

---

One addition: tap zones. I should have folded this into the first proposal; here's the detailed version, since it's the most visible part of gesture ownership (point 4).

Motivation: panel-by-panel is a deliberately different interaction from the other DIVINA modes, and the main thing I want to avoid is a user accidentally hitting the controls while they're walking through panels. So the layout drops the centre controls zone and gives controls their own dedicated strip, clear of the stepping path.

Because panel mode owns input while it's active, it uses its own tap layout for the duration, and your normal tap zones resume the moment you switch the mode off. The layout is intentionally simple and stays the same on the full page and while walking panels, so nothing moves under your thumb:

• A full-width strip along the top = reader controls / overlay.
• The rest of the page splits into two halves — one side goes forward, the other backward — mirrored by the book's effective direction (the sides flip between LTR and RTL).

"Forward" always means forward in reading order: on the full page it turns the page; while walking panels it advances to the next panel -> same gesture, consistent meaning. A tap on the top strip while you're zoomed into a panel drops back to the full page and brings up the controls.

RTL

RTL on an empty page

Compared to the current default (left/centre/right with a centre controls zone), this is a thin overlay the mode installs while active. The one spot it meets existing code: on the full page nothing is zoomed, so the reader's normal tap handler is still active and would double up with the panel overlay and a small guard makes the existing handler defer while the mode is on, with no behaviour change when the mode is off. For unusually tall pages I'll tune the top strip's exact height/behaviour, but the model stays the same.

Does this tap layout look right to you?

[everpcpc]

Thanks, the direction/layout/cache parts look good to me.

I'm less convinced about introducing a separate tap-zone layout for panel mode, though.

To me, tap zones are user configuration and should remain consistent across reader modes. If the user configured centre controls, left/right-handed zones, mirrored RTL behaviour, or any custom tap layout, panel mode should not reinterpret the screen as a special top-strip + two-halves layout. That would make the mode feel surprising: the user turns on panel mode and suddenly their familiar tap areas behave differently.

I think the cleaner split is:

• The existing tap-zone system continues to resolve a tap into a semantic action: forward, backward, controls, etc.
• Panel mode only changes how navigation actions are dispatched while engaged:
  • forward = next panel, or next page at the end of the page;
  • backward = previous panel, or previous page at the beginning of the page;
  • controls = show the normal reader controls.

So panel mode should not own tap geometry. It should consume the same tap actions that the normal reader already produces.

This also keeps RTL/mirroring and user preferences in one place. We don't need a second set of mirroring rules for panel mode, and we avoid making panel walking feel like a different reader.

The real conflict you mentioned is that the normal reader may suppress tap navigation while the page is zoomed. I think that can be handled directly: when panel mode is engaged, taps should still be resolved through the normal tap-zone configuration, but the “zoomed page should not navigate” guard should not suppress panel stepping.

In short, I would prefer:

• no custom tap-zone layout in armed mode;
• no custom tap-zone layout in engaged mode either;
• panel mode reuses existing tap-zone semantics;
• only the execution of forward/backward changes while panel walking is engaged.

That gives us a simpler rule to explain to users:

Your tap zones stay the same. In panel mode, next/previous move between panels instead of pages.

[forkger]

Thanks, I follow the reasoning (tap zones as one user configuration, consistent across modes) and I'm willing to adopt that model, provided we pair it with the layout I describe at the end as a general, selectable option, because that's what addresses the concern behind it: keeping controls out of the stepping path. I'd treat the two as a package: panel mode reuses the existing tap-zone system, and there's a layout that keeps controls clear of the stepping path for anyone who wants it.

The model. A tap resolves to the same semantic action it always has (forward, backward, controls) through whatever layout the user picked, mirroring and all. Panel mode doesn't reinterpret geometry; while engaged it only changes what forward/backward do:

• forward: next panel, or next page at the end of the page;
• backward: previous panel, or previous page at the start of the page;
• controls: the normal reader controls.

The zoom carve-out you described is right: the "zoomed page shouldn't navigate" guard gets a panel-mode exception so stepping works while zoomed, without touching the rest of that guard.

One thing to confirm, since it sits outside the tap-zone system. Entering panel walking is a double-tap, not a single tap, so it never competes with the tap-zone actions above. Double-tap engages at the panel under your finger (you pick where to start), double-tap again returns to the full page; single taps then step via the existing tap zones. Pinch-to-zoom and swipe-to-dismiss are untouched. So "tap zones stay the same" holds for single taps, and double-tap stays the mode's own gesture.

The layout (the part I'd want in). I'd add a layout to the set (alongside default / edge / kindle / l-shape) built on a 50/50 left/right split for forward / backward, mirrored by direction like the others. The reason for this geometry: keeping controls out of the navigation path matters most when you are tapping quickly through a page. In other panel readers I regularly trip the controls by accident mid-read. A controls zone clear of the two halves avoids that (and its exact placement is the one piece I still want to revise and is under research). Either way the navigation stays the existing forward / backward / controls actions, it remains a general option any reader can select and panel mode just consumes it like any other layout, by your rule. I'm happy to build it, and it can land as its own small PR so it stands on its own.

Would that work? Your model for dispatch, plus this layout as a general option.

Cheers.

[everpcpc]

Thanks, this model works much better for me.

I agree with the split:

• tap zones remain the single source for resolving single taps into semantic actions;
• panel mode does not reinterpret tap geometry;
• while engaged, panel mode only changes the dispatch of forward/backward:
  • forward = next panel, or next page at the end;
  • backward = previous panel, or previous page at the start;
  • controls = normal reader controls.

The zoom carve-out also sounds right. If panel mode is engaged, the existing “zoomed page should not navigate” guard should not suppress panel stepping, but the rest of that guard can stay unchanged.

Double-tap being outside the tap-zone system is fine to me. It is the panel mode enter/exit gesture, while single taps still follow the configured tap-zone layout.

For the new 50/50 layout: I think that is fine as a general selectable tap-zone layout, but I would keep it independent from panel mode. Panel mode should not automatically switch to it, and it should not be required for panel mode to work. If the user chooses that layout, panel mode consumes its forward/backward/controls actions like any other reader mode; if the user chooses another layout, panel mode should respect that too.

So yes to the dispatch model, and yes to considering the 50/50 layout as a separate general option, ideally in its own small PR. I just would not couple panel mode behavior to that layout.

[forkger]

Thanks, this is a good split and works well for me.

On keeping the layout independent from panel mode: fully agreed. The 50/50 layout is just another tap-zone option, usable across the DIVINA modes with no knowledge of panel mode. And panel mode never auto-switches to it or requires it, it just consumes whatever layout the user picked.

Plan from here, in two separate PRs:

1. The 50/50 tap-zone layout on its own, as a general selectable option. It stands alone and any reader can use it.
2. Panel mode after that, as a PR focused on the data model and reader behaviour, with detection behind the pluggable provider contract we agreed.

Appreciate the thorough review on the design, looking forward to getting the PRs up.

Cheers!

[forkger]

Hi @everpcpc,

Quick progress update. The shape we agreed on is implemented and validated on iOS. Panel walking works end to end: arm per book, double-tap to engage at the panel you tap, single taps step panel to panel, page turns hand off to the existing paged navigation at the page ends and no-panel pages fall back to the whole page. It all runs behind the pluggable detection contract we discussed, a page image plus reading direction in and ordered normalised panel rects out or empty for whole page, with a module-owned cache and lazy lookahead for neighbours. Detection itself is currently a stub provider behind that contract, synthetic panels, which is what let me validate the reader integration end to end before the real detector exists.

So the reader side is essentially done. What is left is the detector itself, and that is what I am starting on next. The contract is detector-agnostic so I can iterate it without touching the reader. I have been looking to train my own model, which will live in its own open-source repository independent of KMReader, under a license compatible with bundling here. I also explored porting an existing model to Core ML, but the best options are not permissively licensed, so a clean port would need a model whose license allows bundling in an MIT app. If you have one in mind I am keen to hear it, otherwise training my own is the path. Everything else I will handle so it lands as a complete feature.

For concreteness, the entire detector contract is this:

protocol PanelDetectionProvider: Sendable {
    var version: String { get }
    func detect(image: CGImage, direction: ReadingDirection) async -> PanelSequence
}
// PanelSequence is .empty (show the whole page) or .panels([PanelRect]) in reading order.
// PanelRect is normalized to the page: x, y, width, height in 0...1.

A model plugs in by conforming and returning ordered normalised rects, or .empty to fall back to the whole page. The swap point is one line at PanelModeController(provider:) and version feeds the panel cache key so changing detectors invalidates stale results.

One scope note on macOS. Panel mode is a per-book setting gated to LTR and RTL, so it does not fit the app Settings window, which holds global reader defaults. Its natural home is the Reader menu next to Reading Direction and Page Layout, but that menu is not active while the reader window is open: the commands are attached to the main WindowGroup while the reader runs in a separate WindowGroup(id: "reader") so on macOS they disable when the reader window is key. That same wiring is why the Reader Settings sheet does not open on macOS either. Given that, I plan to ship panel mode for iOS and iPadOS in the panel-mode PR and treat macOS as a follow-up. I am happy to fix the Reader menu wiring separately so the per-book commands work on macOS, then add the panel toggle there. Would you rather I bundle that fix into it, keep it on its own or leave it to you?

Cheers!

[everpcpc]

Hi @yorforkger,

Great to hear that the reader side is already working end to end on iOS. That sounds like very good progress.

I do not have a detector model recommendation at the moment. Training your own model sounds like a good path to me, especially if it can live in a separate open-source repo with a license that is safe to bundle in KMReader.

For macOS, the Reader menu issue may have been broken by one of the recent reader-window changes. If you are interested in fixing that, feel free to open a separate PR for it.

For the first version of panel mode, I am totally fine with shipping iOS/iPadOS first and leaving macOS support for later. To be honest, I am also not sure panel-by-panel reading will be used much on macOS, so I would not block the first version on that.

Cheers.

[forkger]

Thanks, that all works for me. On the detector I will go with my own model in a separate open-source repo under a license that is safe to bundle, kept behind the existing provider contract so the reader side does not change.

On the macOS Reader menu, you were right that it came from the reader-window changes. The reader views clear their menu commands in onDisappear, which now fires transiently during the reader-window setup, so the handlers get wiped right after they register while the reader is still open. Window teardown already clears them through closeReader, so the inner clear was redundant. I have a fix that removes it across DIVINA, PDF and EPUB and will open a separate PR for it shortly.

And agreed on scope: panel mode ships iOS and iPadOS first, macOS can be iterated later if needed.