[mrviduus]

Summary

The V2 Android reader gets its reading frame: top and bottom bars that hide while reading, tap zones, hardware back, keep-awake, safe areas, and a save when a book is closed or the app goes to the background. The route is still dev-only (__DEV__).

Stack: 3 of 4. Base is #1287 (page protocol), which sits on #1285. Merge order: #1285 → #1287 → this → web bars. Full CI runs here only after GitHub retargets this PR to main.

Slice

Wave 14, B4 (Android half) + B5. Fixes #1264. Refs #1263 (closed by the web bars PR).

Changes

V2ReaderScreen.tsx

• With a book open: a top bar (back, title) and a bottom bar (book %, section i/N, section title, previous / next page) over the WebView. They hide 3 s after an open, on an edge tap, a key turn, and on any relocate the reader caused (relocate.moved, either flow). A centre tap toggles them. A bar button, the taken offer, a re-layout or a sync jump does not hide them. Reduced motion: no slide or fade.
• Tap zones through the shared tapZone.mjs tapAction: the outer 25 % of each side turns the page in paginated flow and always for a fixed-layout book; the centre toggles; direction from the page's latest dir. A tap that dismisses a selection never arrives as a tap.
• A tap on text acts as a tap at the word's centre for now (readWordTap), so text, which is most of the screen, is not a dead zone. Slice V2 reader: word popup, translation and explain through the host #1269 (word popup) replaces this.
• Hardware keys through the shared keyAction; one press, one turn.
• Back: closes the offer, then the book (back to the list), then leaves the route. No exit prompt.
• Closing a book ends it: the page flushes its pending save, then answers book-closed; the host clears the open book and its per-book state. A later ready (renderer reclaimed in the background, Retry) reopens nothing. While no book is open the WebView is hidden from accessibility and its tap / key / word / selection messages are dropped.
• Keep-awake while a book is open; status bar and safe areas follow the bars without re-laying out the book.
• Saves: __fol.flush() when the app goes to the background and before a book is closed.
• Notices over a book can be dismissed (× "Dismiss").

chrome.mjs (shared, no React Native types): readRelocate (everything the chrome displays from relocate is validated: the page renders untrusted content), readWordTap, hidesBarsOnRelocate, createHostMoves, backAction, reopensOnReady, takenWithoutBook, CLOSE_BOOK_JS.

tapZone.mjs (+ .d.mts, test): byte-identical to the web bars branch's copy, so the two PRs merge cleanly.

Reused from the legacy reader: ReaderTopBar (highlights / TOC / settings buttons now optional, back button takes an accessible name), ReaderFooter (prev / next names can be passed in), useReaderBars (reduced motion, and a count as its re-arm trigger; the legacy reader gets reduced motion too), useKeepReaderAwake, useFlushOnBackground. New: useFlushOnLeave.

No native change: expo-keep-awake, expo-status-bar, react-native-safe-area-context are already in the app. The Expo fingerprint does not move.

Strings: reader.chrome.back, .prevPage, .nextPage, .dismiss in packages/shared/src/i18n/en.json (+ both golden fixtures).

Tests

• chrome.test.ts, tapZone.test.ts, useFlushOnLeave.test.ts, useReaderBars.test.ts: readers incl. hostile payloads, bars rule, back order, close script order (store before book-closed), a closed book not reopened on ready, messages dropped without a book, timer re-armed on a replayed open.
• Every guard was removed in turn; each removal fails a named test.
• mobile tsc 0, vitest 1488; shared vitest 755; web locale tests 28; check:v2-reader up to date (no page source edits).
• Not covered by a test (the screen cannot be rendered under vitest; each stands on a tested helper): endBook on book-closed, the effective flow passed to the zones, the crash count gated on a book being on screen, the accessibility props, the Dismiss button.
• Not run: no device or emulator.

Rollback plan

Revert the PR. No server, schema or stored-data change; the route is dev-only.

Docs: updated (apps/mobile/src/lib/v2reader/README.md "Reader chrome")

Notes

What the review changed (/code-review high, 10 findings; 8 fixed, 1 documented, 1 skipped)

• "Back to the list" only hid the book: it stayed loaded, focused and reopenable. A renderer reload pulled the reader back into a book they had closed; TalkBack and a hardware key still reached it.
• relocate fields went unvalidated into React children and styles (a non-string toc would crash the screen).
• The host guessed "the reader moved" from CFI differences; the page now says so (relocate.moved, feat(reading): V2 reader page protocol for bars: tap position, direction, keys, flush (#1263) #1287).
• Skipped: optional props on the legacy ReaderTopBar (deleted at R8).

Known and left

• A flush at unmount (a deep link replacing the route with a book open) cannot land: its store returns to a handler that is gone. Back and the top bar close the book first, which saves.
• Bars use the app theme colours until reader themes arrive with settings (V2 reader chrome: reading settings (size, family, line height, alignment, theme), saved per device #1260).
• Edge zones are 25 % per side; inside one, a tap on a word turns the page now and will open the word popup after V2 reader: word popup, translation and explain through the host #1269 (decide there).

Device checks owed by the owner

1. Edge taps at the very edge turn pages, portrait and landscape with a cutout (tap.x and the WebView width are in the same units).
2. Text tap: edge turns, centre toggles; a link tap never turns.
3. A CBZ or PDF turns at the edges even with the flow setting on scrolled.
4. A right-to-left book turns by its left edge and ArrowLeft.
5. Select text, tap an edge: the selection clears, no turn.
6. Hardware keyboard: one turn per press, Escape shows the bars.
7. A swipe or a scroll hides the bars; rotation, a font change, a sync jump, the ‹ › buttons do not.
8. Bars hide 3 s after open, also after reopening from the list; instant with "Remove animations".
9. Status bar follows the bars; no re-layout; nothing under the cutout or the gesture bar.
10. Back: offer → list → leave.
11. After closing a book: TalkBack does not reach it, keys do not turn it, the flow toggle works after a PDF, backgrounding never reopens it.
12. Turn a page, press back within 400 ms: the place holds. Turn, Home within 400 ms, kill, reopen: holds.
13. Full disk: the notice over the book can be dismissed.
14. Screen stays awake in a book, sleeps on the list.
15. TalkBack names back, previous page, next page, Dismiss.

🤖 Generated with Claude Code