feat: lyrics view smooth scrolling, manual browsing, and timing nudge

[LargeModGames]

Summary

Reworks the lyrics view around the existing bordered renderer, now extracted to src/tui/ui/lyrics.rs:

• Smooth scrolling: the column glides between lines with a 300ms cubic ease-in-out (driven by the 16ms animation tick, same mechanism as the Analysis view) instead of hard-snapping. Fixed-duration easing keeps the whole-row steps evenly spaced, which reads much smoother in a terminal than exponential smoothing.
• Manual browsing: Up/Down (or j/k, mouse wheel) scroll through the lyrics to read ahead or behind. Auto-follow pauses while browsing (browsed line highlighted in the hovered color, hint row at the bottom) and resumes via f, Esc, or after 8s idle. Ctrl+d/Ctrl+u page 5 lines, Ctrl+a/Ctrl+e jump to first/last line. Esc only closes the view when not browsing; q always closes.
• Timing nudge: Right/Left shift lyric timing 0.5s earlier/later per press for misaligned community LRC files. The offset shows in the block title (e.g. Lyrics (offset +2.0s)) and resets on track change.
• Estimated-timing label: when LRCLIB only has plain lyrics and timestamps are synthesized, the title reads Lyrics (timing estimated) so fake sync is not presented as real.
• Nicer two-line loading/not-found/not-playing state messages.

State lives in a new LyricsViewState on App; fetching and sync mechanics are unchanged.

Testing

• 450 tests pass (cargo test --no-default-features --features telemetry), including new unit tests for the easing, browse resnap timeout, offset math, and TestBackend render tests for the view states.
• cargo fmt and cargo clippy -D warnings clean; full-feature and cover-art builds compile.
• Smoke-tested live: glide animation, browsing, wheel scroll, resnap, and the nudge against a misaligned track.

Summary by CodeRabbit

• New Features
  • Enhanced the lyrics view with smooth/eased scrolling and active-line highlighting.
  • Added manual lyric browsing (up/down paging, start/end jumps) that pauses auto-follow, plus a way to resume following the current line.
  • Added lyric timing nudges in ±0.5s steps, with the current offset shown in the block title and an “estimated timing” indicator when applicable.
  • Resets manual browsing and timing offset when changing tracks.
• Bug Fixes
  • Updated Escape behavior to exit manual browsing before leaving the lyrics view.
  • Improved mouse wheel scrolling in the lyrics view while avoiding playbar interactions.
• Documentation
  • Updated lyrics-view help text with the new navigation, resume, and timing controls.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 309e2879-2936-4149-9bc3-9a663dd856c1

📥 Commits

Reviewing files that changed from the base of the PR and between 1114dbb and 45ff7d4.

📒 Files selected for processing (4)

• spotatui.wiki
• src/infra/network/utils.rs
• src/tui/handlers/lyrics_view.rs
• src/tui/ui/help.rs

💤 Files with no reviewable changes (1)

• src/tui/handlers/lyrics_view.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• src/tui/ui/help.rs
• src/infra/network/utils.rs

---

📝 Walkthrough

Walkthrough

The lyrics view now supports eased scrolling, manual browsing, follow resumption, paging and jump controls, timing nudges, synced-versus-plain lyric indicators, and dedicated rendering with updated UI wiring and tests.

Changes

Lyrics view

Layer / File(s)	Summary
Lyrics state and playback integration src/core/app.rs, src/infra/network/utils.rs, src/tui/runner.rs	App state tracks eased scrolling, manual browsing, timing offsets, and whether fetched lyrics are synchronized. Tick updates animate scrolling, while track changes reset lyrics state.
Lyrics browsing and timing controls src/tui/handlers/lyrics_view.rs, src/tui/handlers/mod.rs, src/tui/handlers/mouse.rs, src/tui/ui/help.rs	Keyboard, Escape, and mouse-wheel handling supports browsing, paging, jumps, follow resumption, timing nudges, and corresponding help text.
Dedicated lyrics rendering and module wiring src/tui/ui/lyrics.rs, src/tui/ui/mod.rs, src/tui/ui/player.rs, CHANGELOG.md	Lyrics rendering moves into its own module with active-line styling, fractional scrolling, status messages, timing hints, browsing hints, tests, and changelog documentation.

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

Sequence Diagram(s)

sequenceDiagram
  participant Player
  participant App
  participant LyricsView
  participant User
  Player->>App: update playback tick
  App->>LyricsView: advance lyric scroll
  User->>LyricsView: browse or nudge timing
  LyricsView->>App: update lyrics_view state
  App->>LyricsView: render adjusted lyric position

Loading

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title uses the required conventional-commit prefix and clearly describes the main lyrics view changes.
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 feature/lyrics-view-improvements

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature/lyrics-view-improvements

---

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/infra/network/utils.rs (1)

83-91: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Reset lyrics_synced alongside lyrics when a new lookup starts.

lyrics_synced is only written in the two "found" branches below (lines 117, 125). Every other outcome (Loading start here, all NotFound/error branches, and the podcast/nothing-playing paths in runner.rs) leaves it holding the previous track's value. It's currently invisible because the UI only reads it when lyrics_status == Found, but resetting it here removes the dependency on that gate ever staying in sync.

🧹 Proposed fix

       app.lyrics_status = LyricsStatus::Loading;
       app.lyrics = None;
+      app.lyrics_synced = false;
     }

🤖 Prompt for 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.

In `@src/infra/network/utils.rs` around lines 83 - 91, Update the loading-state
initialization in the lookup flow to reset app.lyrics_synced alongside
app.lyrics when a new request begins. Use the same state update block guarded by
desired_lyrics_identity and preserve the existing LyricsStatus::Loading
behavior.

🤖 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 `@src/tui/handlers/lyrics_view.rs`:
- Around line 8-10: Update the like-action branch in the lyrics-view key handler
to match app.user_config.keys.like_track instead of the hard-coded 's' key,
while preserving the existing toggle_like_currently_playing_item call.

In `@src/tui/ui/help.rs`:
- Around line 156-170: Update the Lyrics view help rows in the help-screen
builder to derive displayed key values from key_bindings.move_up, move_down,
move_left, and move_right instead of hardcoded arrow labels. Include the
handler-supported Ctrl aliases where applicable, while preserving the existing
descriptions and Lyrics view category.

---

Nitpick comments:
In `@src/infra/network/utils.rs`:
- Around line 83-91: Update the loading-state initialization in the lookup flow
to reset app.lyrics_synced alongside app.lyrics when a new request begins. Use
the same state update block guarded by desired_lyrics_identity and preserve the
existing LyricsStatus::Loading behavior.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d6421f80-b2b2-4b47-9dae-797a20552179

📥 Commits

Reviewing files that changed from the base of the PR and between b7fc96c and 1114dbb.

📒 Files selected for processing (11)

• CHANGELOG.md
• src/core/app.rs
• src/infra/network/utils.rs
• src/tui/handlers/lyrics_view.rs
• src/tui/handlers/mod.rs
• src/tui/handlers/mouse.rs
• src/tui/runner.rs
• src/tui/ui/help.rs
• src/tui/ui/lyrics.rs
• src/tui/ui/mod.rs
• src/tui/ui/player.rs