[Hallmark] Give full-player expand/collapse spatial continuity and predictive Back #102

Open
opened 2026-09-27 14:48:21 +02:00 by alexander · 2 comments
Owner

Purpose

Make the mini-player → full-player transition communicate that these are two presentations of the same playback session.

Related hierarchy work: #96 mini-player and #97 full-player controls. App-wide route/motion language is tracked separately.

Reviewed against current main at f9f7feba8e7bb499c6001bf0cc19a38357b7494a on 2026-09-27.

Current behavior

MainActivity conditionally inserts/removes FullPlayer when isExpanded changes. FullPlayer uses a normal BackHandler that collapses it.

The architecture is good:

  • full player is an overlay, not a duplicate navigation destination;
  • collapsing reveals the exact underlying screen and scroll position;
  • player cannot accidentally appear twice in the route stack.

Keep that architecture.

The missing part is visual/gesture continuity.

Proposed transition

Expand

Mini-player → full player:

  • full-player surface rises from the bottom;
  • subtle opacity transition;
  • roughly Standard/Large BookWave motion timing from the shared motion vocabulary;
  • no bounce/elastic overshoot;
  • underlying route remains in place.

The mini-player should not perform an unrelated exit flourish underneath the player.

Collapse

Reverse the spatial relationship:

  • full-player surface moves down toward the mini-player;
  • exit may be slightly shorter than entry;
  • reveal the existing underlying screen without resetting scroll/state.

Do not build an elaborate all-controls morph as the first implementation.

Predictive Back

Replace/augment the all-or-nothing custom Back interception with predictive-back-aware collapse on supported Android versions.

The edge gesture should:

  • progressively reveal the screen beneath;
  • move/collapse the full-player layer with gesture progress;
  • cancel cleanly back to fully expanded if the user abandons the gesture;
  • finish at the mini-player/underlying screen if committed.

Toolbar collapse and system Back must end in the same state.

Possible later continuity

After #96/#97 stabilize layouts, evaluate whether the cover artwork alone should participate in stronger shared spatial continuity between mini and full player.

Do not block this issue on a shared-element implementation. A clean surface transition is the acceptance baseline.

State interactions

Verify:

  • active playback;
  • paused;
  • buffering/loading;
  • playback failure/retry notice;
  • active sleep countdown;
  • audio output chooser;
  • chapter/history/speed/sleep/bookmark sheets;
  • book stopping while full player is expanded.

Opening a modal sheet from the full player must not collapse the player.

If playback stops and the player currently collapses automatically, preserve that product behavior unless a separate issue changes it.

Accessibility / reduced motion

  • Full-player focus order must remain stable after transition.
  • Reduced/disabled animation scale must still collapse/expand immediately and correctly.
  • Do not delay Back navigation waiting for ornamental animation.
  • Predictive Back must not create duplicate TalkBack surfaces from the underlying screen during an incomplete gesture.

Implementation starting points

  • app/src/main/kotlin/com/example/shelfplayer/MainActivity.kt — player overlay ownership
  • app/src/main/kotlin/com/example/shelfplayer/feature/player/FullPlayer.kt — Back handling and player surface
  • app/src/main/kotlin/com/example/shelfplayer/feature/player/MiniPlayer.kt only as required to coordinate state

Acceptance

  • Expand/collapse visually reads as one player changing size/layer.
  • No bounce.
  • Underlying route and scroll position are preserved.
  • Predictive Back follows finger progress and can cancel safely.
  • Toolbar/system/predictive Back agree.
  • Sheets remain correctly layered above full player.
  • Verify gesture/button navigation on supported Android hardware/emulator, plus reduced motion and TalkBack.
  • Do not turn the full player into a NavHost destination.
## Purpose Make the mini-player → full-player transition communicate that these are two presentations of the same playback session. Related hierarchy work: #96 mini-player and #97 full-player controls. App-wide route/motion language is tracked separately. Reviewed against current `main` at `f9f7feba8e7bb499c6001bf0cc19a38357b7494a` on 2026-09-27. ## Current behavior `MainActivity` conditionally inserts/removes `FullPlayer` when `isExpanded` changes. `FullPlayer` uses a normal `BackHandler` that collapses it. The architecture is good: - full player is an overlay, not a duplicate navigation destination; - collapsing reveals the exact underlying screen and scroll position; - player cannot accidentally appear twice in the route stack. Keep that architecture. The missing part is visual/gesture continuity. ## Proposed transition ### Expand Mini-player → full player: - full-player surface rises from the bottom; - subtle opacity transition; - roughly Standard/Large BookWave motion timing from the shared motion vocabulary; - no bounce/elastic overshoot; - underlying route remains in place. The mini-player should not perform an unrelated exit flourish underneath the player. ### Collapse Reverse the spatial relationship: - full-player surface moves down toward the mini-player; - exit may be slightly shorter than entry; - reveal the existing underlying screen without resetting scroll/state. Do not build an elaborate all-controls morph as the first implementation. ## Predictive Back Replace/augment the all-or-nothing custom Back interception with predictive-back-aware collapse on supported Android versions. The edge gesture should: - progressively reveal the screen beneath; - move/collapse the full-player layer with gesture progress; - cancel cleanly back to fully expanded if the user abandons the gesture; - finish at the mini-player/underlying screen if committed. Toolbar collapse and system Back must end in the same state. ## Possible later continuity After #96/#97 stabilize layouts, evaluate whether the **cover artwork alone** should participate in stronger shared spatial continuity between mini and full player. Do not block this issue on a shared-element implementation. A clean surface transition is the acceptance baseline. ## State interactions Verify: - active playback; - paused; - buffering/loading; - playback failure/retry notice; - active sleep countdown; - audio output chooser; - chapter/history/speed/sleep/bookmark sheets; - book stopping while full player is expanded. Opening a modal sheet from the full player must not collapse the player. If playback stops and the player currently collapses automatically, preserve that product behavior unless a separate issue changes it. ## Accessibility / reduced motion - Full-player focus order must remain stable after transition. - Reduced/disabled animation scale must still collapse/expand immediately and correctly. - Do not delay Back navigation waiting for ornamental animation. - Predictive Back must not create duplicate TalkBack surfaces from the underlying screen during an incomplete gesture. ## Implementation starting points - `app/src/main/kotlin/com/example/shelfplayer/MainActivity.kt` — player overlay ownership - `app/src/main/kotlin/com/example/shelfplayer/feature/player/FullPlayer.kt` — Back handling and player surface - `app/src/main/kotlin/com/example/shelfplayer/feature/player/MiniPlayer.kt` only as required to coordinate state ## Acceptance - Expand/collapse visually reads as one player changing size/layer. - No bounce. - Underlying route and scroll position are preserved. - Predictive Back follows finger progress and can cancel safely. - Toolbar/system/predictive Back agree. - Sheets remain correctly layered above full player. - Verify gesture/button navigation on supported Android hardware/emulator, plus reduced motion and TalkBack. - Do not turn the full player into a NavHost destination.
Author
Owner

Hallmark Slice 1 — design/readiness

Current main audit at 8ea2122fc3c1d32bcfc5f0eb295b3521be562ed4:

  • Architecture is correct: MainActivity owns the full-player overlay, PlayerSurface owns expanded/collapsed state, and the player is not a NavHost destination.
  • Current transition is binary: if (isExpanded) inserts/removes FullPlayer; FullPlayer uses ordinary BackHandler.
  • Current Activity Compose is 1.13.0, Navigation Compose 2.9.8, compile/target SDK 36, so the supported Activity Compose predictive-back path is available without a custom edge recognizer.

Slice change:

  • Keep overlay ownership and the single PlayerSurface.collapse() final state.
  • Add restrained bottom-up + opacity Large motion for expand/collapse, with no spring overshoot.
  • Predictive Back directly drives player-layer translation/opacity from gesture progress, cancels back to expanded, and commits through the same collapse callback as toolbar/system Back.
  • Disable player-level Back interception while a player modal owns Back, so sheets dismiss before the player collapses.
  • Compose-owned animation remains presentation-only; playback/session state is untouched.

Expected files:

  • MainActivity.kt
  • FullPlayer.kt only as required for presentation/back coordination
  • shared PlayerMotion.kt
  • focused overlay/back tests where practical

Accessibility/reduced motion:

  • Underlying route remains composed but must not become an interactive duplicate while the overlay owns focus.
  • Standard Compose animation scaling is used so disabled/reduced system animation remains correct; predictive Back remains direct manipulation.
  • Cancel/commit must leave one unambiguous expanded/collapsed state.
## Hallmark Slice 1 — design/readiness Current `main` audit at `8ea2122fc3c1d32bcfc5f0eb295b3521be562ed4`: - Architecture is correct: `MainActivity` owns the full-player overlay, `PlayerSurface` owns expanded/collapsed state, and the player is not a NavHost destination. - Current transition is binary: `if (isExpanded)` inserts/removes `FullPlayer`; `FullPlayer` uses ordinary `BackHandler`. - Current Activity Compose is 1.13.0, Navigation Compose 2.9.8, compile/target SDK 36, so the supported Activity Compose predictive-back path is available without a custom edge recognizer. Slice change: - Keep overlay ownership and the single `PlayerSurface.collapse()` final state. - Add restrained bottom-up + opacity Large motion for expand/collapse, with no spring overshoot. - Predictive Back directly drives player-layer translation/opacity from gesture progress, cancels back to expanded, and commits through the same collapse callback as toolbar/system Back. - Disable player-level Back interception while a player modal owns Back, so sheets dismiss before the player collapses. - Compose-owned animation remains presentation-only; playback/session state is untouched. Expected files: - `MainActivity.kt` - `FullPlayer.kt` only as required for presentation/back coordination - shared `PlayerMotion.kt` - focused overlay/back tests where practical Accessibility/reduced motion: - Underlying route remains composed but must not become an interactive duplicate while the overlay owns focus. - Standard Compose animation scaling is used so disabled/reduced system animation remains correct; predictive Back remains direct manipulation. - Cancel/commit must leave one unambiguous expanded/collapsed state.
Author
Owner

Hallmark Slice 1 — implementation staged

Branch: mcp/hallmark-slice-1-player
Base: 8ea2122fc3c1d32bcfc5f0eb295b3521be562ed4
Current HEAD: f4f90f10a624e310cb87d6abe20482aea444bcb2

Implemented for #102:

  • full player remains a MainActivity overlay backed by the existing singleton PlayerSurface; no NavHost destination was introduced;
  • expansion uses a restrained bottom-up + opacity Large transition and collapse reverses it slightly faster;
  • the underlying route remains composed throughout, preserving route/scroll state;
  • underlying semantics are suppressed for the full lifetime of the overlay transition, avoiding duplicate TalkBack surfaces during enter/exit;
  • PredictiveBackHandler consumes gesture progress directly and translates/fades the full-player layer with the gesture;
  • cancellation animates the player back to fully expanded; commit calls the same actions.onCollapse path as toolbar collapse;
  • player Back yields while History/Sleep/Speed/Chapter/Bookmark sheets are open;
  • player Back also yields to the output chooser and the new More menu before collapsing;
  • no custom edge recognizer or shared-element infrastructure was introduced;
  • animations are Compose-owned tweens, so platform animation-duration scaling remains authoritative; predictive gesture progress itself stays direct manipulation.

Tests were added/updated for PlayerSurface ownership and normal Android Back resolving through the same collapse callback. Predictive gesture-progress quality remains a physical/device acceptance item.

Verification note: no automated checks or workflow runs were started, per owner instruction.

## Hallmark Slice 1 — implementation staged Branch: `mcp/hallmark-slice-1-player` Base: `8ea2122fc3c1d32bcfc5f0eb295b3521be562ed4` Current HEAD: `f4f90f10a624e310cb87d6abe20482aea444bcb2` Implemented for #102: - full player remains a `MainActivity` overlay backed by the existing singleton `PlayerSurface`; no NavHost destination was introduced; - expansion uses a restrained bottom-up + opacity Large transition and collapse reverses it slightly faster; - the underlying route remains composed throughout, preserving route/scroll state; - underlying semantics are suppressed for the full lifetime of the overlay transition, avoiding duplicate TalkBack surfaces during enter/exit; - `PredictiveBackHandler` consumes gesture progress directly and translates/fades the full-player layer with the gesture; - cancellation animates the player back to fully expanded; commit calls the same `actions.onCollapse` path as toolbar collapse; - player Back yields while History/Sleep/Speed/Chapter/Bookmark sheets are open; - player Back also yields to the output chooser and the new More menu before collapsing; - no custom edge recognizer or shared-element infrastructure was introduced; - animations are Compose-owned tweens, so platform animation-duration scaling remains authoritative; predictive gesture progress itself stays direct manipulation. Tests were added/updated for `PlayerSurface` ownership and normal Android Back resolving through the same collapse callback. Predictive gesture-progress quality remains a physical/device acceptance item. Verification note: no automated checks or workflow runs were started, per owner instruction.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#102
No description provided.