fix(mobile): 修正朗讀跳過純標題/圖片頁時無聲中斷的問題

[Retsomm]

跨章節後若下一個 spine 項目沒有文字內容（例如純標題頁/圖片頁，如
xxxt.xhtml），getChapterText() 量到空字串，原本邏輯重試一次就直接放棄
朗讀，導致跟三個合法停止條件（手動停止、睡眠計時、全書結尾）無關的
情況下朗讀就中斷。改成持續往後翻頁跳過空白頁，直到找到真正有文字的
頁面才開始念。

同時在 tts.ts 的 speakChunk 與 useTTSReading.ts 的跨章節決策點加上 DEV 診斷 log，方便之後同類問題排查。

Summary by CodeRabbit

• Bug Fixes
  • Improved text-to-speech reading continuity when chapters contain no readable text.
  • Reading now stops correctly at the end of a book or when no further readable content is available.
  • Added recovery for navigation that becomes stuck, allowing the reader to continue to the next chapter when possible.
• Diagnostics
  • Added development-only logging to help troubleshoot chapter navigation and audio playback issues.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
travel-in-time	Ready	Preview	Aug 1, 2026 5:58am

[coderabbitai]

Warning

Review limit reached

@Retsomm, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7c817014-f508-4d49-9633-40f386566bcf

📥 Commits

Reviewing files that changed from the base of the PR and between 3337543 and 9acf385.

📒 Files selected for processing (2)

• mobile/hooks/reader/useTTSReading.ts
• mobile/reader-web/index.ts

📝 Walkthrough

Walkthrough

The reader now recovers from stalled chapter navigation, skips empty chapters during TTS continuation, and records development-only diagnostics for chapter advancement and speech playback.

Changes

TTS navigation and playback

Layer / File(s)	Summary
Stalled navigation recovery mobile/reader-web/index.ts	Repeated unchanged CFIs now trigger navigation to the next linear spine item through gotoTarget.
Empty-chapter continuation mobile/hooks/reader/useTTSReading.ts	Chapter continuation checks up to 20 relocated chapters, stops on failure or end of book, and starts TTS at the first chapter with readable text.
Speech playback diagnostics mobile/lib/tts.ts	Development-only logs now cover chunk completion, playback start, stale callbacks, stop events, and playback errors.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Retsomm/TravelInTime#10: Modifies the same TTS and reader navigation files.
• Retsomm/TravelInTime#5: Modifies navigation recovery and gotoTarget spine navigation.
• Retsomm/TravelInTime#7: Modifies speech flow and chapter advancement logic.

Sequence Diagram(s)

sequenceDiagram
  participant useTTSReading
  participant advanceToNextChapter
  participant readerWeb
  participant speakChunk
  useTTSReading->>advanceToNextChapter: Request chapter advancement
  advanceToNextChapter->>readerWeb: Relocate to next chapter
  readerWeb-->>useTTSReading: Return chapter text or navigation result
  useTTSReading->>speakChunk: Speak first non-empty chapter text
  speakChunk-->>useTTSReading: Report completion or playback error

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main fix: preventing silent interruption when reading skips title-only or image-only pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mobile/hooks/reader/useTTSReading.ts`:
- Around line 83-97: Update the readNextAndContinue retry loop so the
destination reached by the twentieth navigation is checked for readable text
before stopping. At hop === 19, perform the final relocation without another
navigation, then request and process that destination’s text, while preserving
the existing atEndRef handling and retry limit.

In `@mobile/reader-web/index.ts`:
- Line 141: Reset consecutiveStuckNext alongside the other per-book relocation
state at the start of loadBook, ensuring each book begins with a zero recovery
counter and does not inherit stalled-relocation state from the previous book.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 35071d07-71f8-47a8-b184-3f54a2e3e4ed

📥 Commits

Reviewing files that changed from the base of the PR and between 14b04f4 and 3337543.

⛔ Files ignored due to path filters (1)

• mobile/lib/readerHtml.generated.ts is excluded by !**/*.generated.*

📒 Files selected for processing (3)

• mobile/hooks/reader/useTTSReading.ts
• mobile/lib/tts.ts
• mobile/reader-web/index.ts