Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
3105546
docs: plan the mini and fullscreen players
j0ker70 Nov 21, 2026
d61cb57
docs: record the maintainer's answers to the plan
j0ker70 Nov 21, 2026
79f8b4c
docs: apply the second plan check's notes
j0ker70 Nov 21, 2026
7cea4ad
docs: keep the fullscreen controls clear of the system bars
j0ker70 Nov 21, 2026
c14dba3
docs: apply the fourth plan check's notes
j0ker70 Nov 21, 2026
4f21a55
docs: fold the fifth plan check's notes into the plan
j0ker70 Nov 21, 2026
4319bf7
feat: add the fullscreen glyphs and the duration-scrim opacity
j0ker70 Nov 21, 2026
25fb4f1
feat: add the mini and fullscreen players
j0ker70 Nov 21, 2026
5de9fbc
docs: describe the mini and fullscreen players
j0ker70 Nov 21, 2026
1ca534d
fix: give fullscreen text a content color and take key focus
j0ker70 Nov 21, 2026
e49e2d6
docs: make the mini player's reopen check one that can be seen
j0ker70 Nov 21, 2026
042d3f4
fix: give the mini player's text a content color and its height back
j0ker70 Nov 21, 2026
61960ff
fix: keep a pause through a link refresh, and fullscreen's controls i…
j0ker70 Nov 21, 2026
b84153b
fix: keep fullscreen's control row at the bottom
j0ker70 Nov 21, 2026
aa4d9e3
fix: keep fullscreen's exit button when the times are wide
j0ker70 Nov 21, 2026
09af977
fix: keep fullscreen's controls while a finger is held down
j0ker70 Nov 21, 2026
084ee33
test: add the mini and fullscreen players' screenshot tests
j0ker70 Nov 21, 2026
dd37b38
fix: keep fullscreen's failure Banner clear of the title
j0ker70 Nov 21, 2026
4dc54ad
docs: archive the mini and fullscreen players change
j0ker70 Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ This section is updated whenever a phase's milestone closes.
| core/ | Core modules that every feature can use. docs/architecture.md describes each one |
| core/database/schemas/ | The Room database schemas that the build writes, one JSON file per database version |
| core/youtube/src/test/resources/youtube/ | The saved YouTube responses that the YouTube layer's tests replay, which the recorder writes |
| feature/ | Feature modules, two for each feature. Today the Search YouTube screen, the video screen, and the YouTube layer's debug screen, which only debug builds contain |
| feature/ | Feature modules, two for each feature. Today the Search YouTube screen, the video screen with the mini player and the fullscreen player, and the YouTube layer's debug screen, which only debug builds contain |
| feature/*-ui/src/screenshotTest/ | The screenshot tests: one-call @PreviewTest wrappers of the previews in src/main. The reference images they are compared with are in src/screenshotTestDefaultDebug/reference/ next to it. docs/testing.md#screenshot-tests explains them |
| build-logic/ | Convention plugins with the build settings that every module shares |
| lint-rules/ | Dewfall's own lint checks, which lint runs on every module of the app. They enforce ADR 0007's logging rules, and nothing from them ships |
Expand Down Expand Up @@ -93,12 +93,12 @@ These apply from Phase 2 on. A pull request that refines them updates this secti
- Kotlin, Jetpack Compose, Material 3, Hilt, Room, WorkManager and Media3.
- Follow Android's current official guidance, such as the app architecture recommendations and the Compose docs on developer.android.com. If the android CLI is installed, `android docs search` and `android docs fetch` read the same guidance from the Android Knowledge Base. For any API, library or Gradle setting that may have changed, check the current docs instead of relying on memory. Don't use deprecated APIs in new code. If the guidance conflicts with a rule in this file, follow this file and point out the conflict.
- Modules: `:app`, the plain Kotlin/JVM modules `:core:logging`, `:core:model`, `:core:mvi` and `:core:youtube` (the YouTube layer), and the Android libraries `:core:data`, `:core:database`, `:core:designsystem` and `:core:playback` (the player). The Search YouTube screen adds `:feature:youtube-search-logic` and `:feature:youtube-search-ui`, and the video screen adds `:feature:player-logic` and `:feature:player-ui`. The YouTube layer's debug screen adds `:feature:youtube-debug-logic` and `:feature:youtube-debug-ui`, which `:app` adds to debug builds only, with debugImplementation. The plain Kotlin/JVM module `:lint-rules` holds Dewfall's own lint checks, which the module plugins add to every module's lint, and which never ship. docs/architecture.md describes each one. Shared UI goes in `:core:designsystem`, or in `:core:ui` once it needs domain models, as docs/architecture.md describes.
- Each feature has two modules: `:feature:<name>-logic`, plain Kotlin/JVM, with the State, Intent, Effect and reducer, and `:feature:<name>-ui`, an Android library with the screens and the ViewModel. Feature modules depend on core modules, never on another feature's modules. A feature's `-ui` module also depends on its own `-logic` module. Only `:app` sees Navigation 3: a feature whose screen sits on `:app`'s back stack exposes one public composable from its `-ui` module, which takes plain values and actions, such as `onOpenVideo`, and `:app` turns those actions into navigation. The YouTube layer's debug screen has its own activity instead. Features reach YouTube only through repositories in `:core:data`, never through `:core:youtube`. The one exception is `:feature:youtube-debug-ui`, the debug screen, whose job is to call the YouTube layer's functions themselves. `:app`'s androidTest also depends on `:core:youtube`, for the layer's interfaces only, so the emulator tests can replace the layer with fakes. It is test code that ships nowhere, and no feature module can see the layer through it.
- Each feature has two modules: `:feature:<name>-logic`, plain Kotlin/JVM, with the State, Intent, Effect and reducer, and `:feature:<name>-ui`, an Android library with the screens and the ViewModel. Feature modules depend on core modules, never on another feature's modules. A feature's `-ui` module also depends on its own `-logic` module. Only `:app` sees Navigation 3: a feature whose screen sits on `:app`'s back stack exposes one public composable from its `-ui` module, which takes plain values and actions, such as `onOpenVideo`, and `:app` turns those actions into navigation. The one exception is `:feature:player-ui`, which also exposes the mini player, a bar that `:app` places under the back stack, as ADR 0002's note of November 21, 2026 records. The YouTube layer's debug screen has its own activity instead. Features reach YouTube only through repositories in `:core:data`, never through `:core:youtube`. The one exception is `:feature:youtube-debug-ui`, the debug screen, whose job is to call the YouTube layer's functions themselves. `:app`'s androidTest also depends on `:core:youtube`, for the layer's interfaces only, so the emulator tests can replace the layer with fakes. It is test code that ships nowhere, and no feature module can see the layer through it.
- Code that needs nothing from Android lives in plain Kotlin/JVM modules with no Android imports: the YouTube layer, the domain models, the MVI base types, the reducers and the logger. See ADR 0006.
- Only the YouTube layer module may use NewPipeExtractor. It maps every NewPipeExtractor type to Dewfall's own models, so nothing else in the app knows which library sits underneath.
- The YouTube layer's functions are main-safe suspend functions that return YouTubeResult and throw only CancellationException. No NewPipeExtractor exception leaves the module. Video and channel IDs are VideoId and ChannelId, never plain strings. See ADR 0008. The one exception is MediaRequests, the layer's client for the player's requests to googlevideo.com, whose calls throw IOException, as ADR 0008's note of November 20, 2026 says.
- Every request to YouTube asks for British English (en-GB), and for the device's country, or GB when YouTube doesn't support it. The subtitle download and MediaRequests name no country, because their links already carry the country of the call that made them, as ADR 0009's notes say. NewPipeExtractor reads some of YouTube's answers by their English text, so another language breaks the marks of upcoming streams and some error categories. See ADR 0009.
- Every screen uses MVI: an immutable State, an Intent sealed interface, one-time Effects, and a reducer that is a pure function. The ViewModel runs side effects. Every reducer has unit tests. An action that starts in the UI, changes no state and needs no business logic, such as opening or closing a screen, goes straight to `:app`'s navigation, with no intent or effect. Player commands from the video screen, such as play, pause and seek, go straight to the player through PlaybackConnection, not through intents, and the screen reads playback state through the player's state holders. See ADR 0002.
- Every screen uses MVI: an immutable State, an Intent sealed interface, one-time Effects, and a reducer that is a pure function. The ViewModel runs side effects. Every reducer has unit tests. An action that starts in the UI, changes no state and needs no business logic, such as opening or closing a screen, goes straight to `:app`'s navigation, with no intent or effect. Player commands from the video screen and the mini player, such as play, pause, seek and the mini player's close, go straight to the player through PlaybackConnection, not through intents, and they read playback state through the player's state holders. The mini player has no screen state and no ViewModel. See ADR 0002.
- Every screen's ViewModel extends MviViewModel from `:core:mvi`. Intents include the results of the ViewModel's work, and effects stay pending as state until the UI reports them handled. docs/architecture.md describes the MVI contract.
- Playback state never goes into screen state. The player lives in a MediaSessionService and exposes its state through its MediaController, which screens read with media3-ui-compose's state holders or as Flows. Position updates run only as often as the visible UI needs them.
- Download, sync and cleanup logic must not depend on any screen being open, because background WorkManager jobs reuse it. Background jobs run only on unmetered networks while charging.
Expand Down
11 changes: 6 additions & 5 deletions app/src/main/kotlin/io/github/dewfallapp/MainActivity.kt
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ import javax.inject.Inject

/**
* The app's only activity. It shows the Compose UI and is Hilt's entry point for it. It tells the
* player whether the app can be seen, so the player shows no picture in the background, whichever
* screen played the video. See docs/architecture.md#the-player.
* player when the app can be seen and when it stops, so the player shows no picture in the
* background and a video that hasn't played waits, whichever screen played it. See
* docs/architecture.md#the-player.
*/
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
Expand All @@ -27,12 +28,12 @@ class MainActivity : ComponentActivity() {

override fun onStart() {
super.onStart()
playback.setAppVisible(true)
playback.appStarted()
}

override fun onStop() {
super.onStop()
// A configuration change brings the activity back at once, and keeps the picture.
if (!isChangingConfigurations) playback.setAppVisible(false)
// A configuration change brings the activity back at once, so the connection does nothing.
playback.appStopped(changingConfigurations = isChangingConfigurations)
}
}
13 changes: 10 additions & 3 deletions app/src/main/kotlin/io/github/dewfallapp/navigation/BackStack.kt
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ internal fun MutableList<NavKey>.openVideo(videoId: VideoId) {
}

/**
* Closes the video screen of [key], if it is still on the back stack. A second tap on the close
* button, or one during the back gesture, finds it gone and does nothing, so Search YouTube always
* stays. An empty back stack would crash, because NavDisplay requires at least one entry.
* Closes the video screen of [key], if it is still on the back stack, as its minimize button does.
* Its playback goes on in the mini player. A second tap on the button, or one during the back
* gesture, finds it gone and does nothing, so Search YouTube always stays. An empty back stack
* would crash, because NavDisplay requires at least one entry.
*/
internal fun MutableList<NavKey>.close(key: PlayerKey) {
remove(key)
Expand All @@ -25,3 +26,9 @@ internal fun MutableList<NavKey>.close(key: PlayerKey) {
internal fun MutableList<NavKey>.goBack() {
if (size > 1) removeAt(lastIndex)
}

/**
* Whether the mini player shows under the back stack: while no video screen is on top. It draws
* nothing itself while the player has no video.
*/
internal fun List<NavKey>.showsMiniPlayer(): Boolean = lastOrNull() !is PlayerKey
Original file line number Diff line number Diff line change
@@ -1,41 +1,78 @@
package io.github.dewfallapp.navigation

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.onSizeChanged
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.ui.NavDisplay
import io.github.dewfallapp.feature.player.ui.MiniPlayer
import io.github.dewfallapp.feature.player.ui.PlayerRoute
import io.github.dewfallapp.feature.youtubesearch.ui.YouTubeSearch

/**
* The app's screens and the back stack between them. Only :app knows Navigation 3. Features take
* plain actions, such as opening a video, and never see each other. The back stack survives
* configuration changes and process death, and each entry keeps its own saved state and ViewModels,
* which are cleared when it leaves the back stack. See docs/architecture.md#navigation.
* The app's screens, the back stack between them, and the mini player under them. Only :app knows
* Navigation 3. Features take plain actions, such as opening a video, and never see each other. The
* back stack survives configuration changes and process death, and each entry keeps its own saved
* state and ViewModels, which are cleared when it leaves the back stack. See
* docs/architecture.md#navigation.
*
* The mini player sits under the screens while no video screen is on top, and the screens end at
* its top edge: the box above it gives up the mini player's height from the window insets at its
* bottom, so a screen's own safe drawing padding leaves out the navigation bar, and keeps the part
* of the keyboard that reaches above the mini player.
*/
@Composable
internal fun DewfallNavigation(modifier: Modifier = Modifier) {
val backStack = rememberNavBackStack(SearchKey)
NavDisplay(
backStack = backStack,
onBack = { backStack.goBack() },
modifier = modifier,
entryDecorators =
listOf(
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator(),
),
entryProvider =
entryProvider {
entry<SearchKey> {
YouTubeSearch(onOpenVideo = { videoId -> backStack.openVideo(videoId) })
}
entry<PlayerKey>(clazzContentKey = { key -> key.entryId }) { key ->
PlayerRoute(videoId = key.videoId, onClose = { backStack.close(key) })
}
},
)
val showsMiniPlayer = backStack.showsMiniPlayer()
var miniPlayerHeight by remember { mutableStateOf(0.dp) }
val density = LocalDensity.current
Column(modifier = modifier.fillMaxSize()) {
NavDisplay(
backStack = backStack,
onBack = { backStack.goBack() },
modifier =
Modifier.weight(1f)
.consumeWindowInsets(
PaddingValues(bottom = if (showsMiniPlayer) miniPlayerHeight else 0.dp),
),
entryDecorators =
listOf(
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator(),
),
entryProvider =
entryProvider {
entry<SearchKey> {
YouTubeSearch(onOpenVideo = { videoId -> backStack.openVideo(videoId) })
}
entry<PlayerKey>(clazzContentKey = { key -> key.entryId }) { key ->
PlayerRoute(videoId = key.videoId, onMinimize = { backStack.close(key) })
}
},
)
if (showsMiniPlayer) {
// The box reports 0 when the mini player draws nothing, such as after it closes, so
// the screens above get the navigation bar's inset back.
Box(
Modifier.onSizeChanged { miniPlayerHeight = with(density) { it.height.toDp() } },
) {
MiniPlayer(onOpenVideo = { videoId -> backStack.openVideo(videoId) })
Comment on lines +71 to +74

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Bound the mini player height so that Search keeps usable space.

The mini player has no maximum height. Its title has no line limit or overflow setting, and miniPlayerContent passes the item title through without a length limit. A long title can wrap onto many lines and grow the mini player. The mini player sits in an unweighted Box, which the parent Column measures before the weighted NavDisplay. On a short split-screen window at a large font size, the mini player can take all of the remaining height. Search then has no usable area while the mini player is open. The back gesture and the close control still work.

Keep the mini player at a bounded height so that NavDisplay always has usable space. Choose the bound: a title line limit, an ellipsis, or a maximum height. Check the result in a 320 dp high window at the largest font size.

Source: Path instructions

}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ import androidx.navigation3.runtime.NavKey
import io.github.dewfallapp.core.model.VideoId
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse
import kotlin.test.assertIs
import kotlin.test.assertTrue

private val VIDEO = VideoId("aqz-KE-bpKQ")
private val OTHER = VideoId("dQw4w9WgXcQ")
Expand Down Expand Up @@ -61,4 +63,15 @@ class BackStackTest {

assertEquals(listOf<NavKey>(SearchKey), backStack)
}

@Test
fun `the mini player shows on search, and not over a video screen`() {
assertTrue(backStack.showsMiniPlayer())

backStack.openVideo(VIDEO)
assertFalse(backStack.showsMiniPlayer())

backStack.goBack()
assertTrue(backStack.showsMiniPlayer())
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
package io.github.dewfallapp.core.designsystem.theme

/**
* Dewfall's opacities that Material 3's components don't already apply, from the opacity tokens in
* docs/design/claude-design/design-system/tokens.json. Each one comes with its first use. A token
* edit there is copied here by hand, and DesignTokensTest fails until both agree.
*/
object DewfallOpacity {
/**
* duration-scrim, 0.8. `surface` at this opacity behind the duration tag on a thumbnail, and
* behind the fullscreen player's controls over video.
*/
const val DURATION_SCRIM = 0.8f
}
18 changes: 18 additions & 0 deletions core/designsystem/src/main/res/drawable/ic_fullscreen.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
The fullscreen glyph from Material Symbols Rounded, weight 400, grade 0, optical size 24, outlined,
as the design system's Iconography asks. Copied from
symbols/android/fullscreen/materialsymbolsrounded/fullscreen_24px.xml in
github.com/google/material-design-icons at commit 10ecc14790, under the Apache License 2.0,
whose text is in docs/design/claude-design/design-system/licenses/MaterialSymbols-Apache-2.0.txt.
Screens tint it with a MaterialTheme color role.
-->
<vector xmlns:android="http://schemas.android.com/apk/res/android"
android:width="24dp"
android:height="24dp"
android:viewportWidth="960"
android:viewportHeight="960">
<path
android:fillColor="#FF000000"
android:pathData="M200,760L280,760Q297,760 308.5,771.5Q320,783 320,800Q320,817 308.5,828.5Q297,840 280,840L160,840Q143,840 131.5,828.5Q120,817 120,800L120,680Q120,663 131.5,651.5Q143,640 160,640Q177,640 188.5,651.5Q200,663 200,680L200,760ZM760,760L760,680Q760,663 771.5,651.5Q783,640 800,640Q817,640 828.5,651.5Q840,663 840,680L840,800Q840,817 828.5,828.5Q817,840 800,840L680,840Q663,840 651.5,828.5Q640,817 640,800Q640,783 651.5,771.5Q663,760 680,760L760,760ZM200,200L200,280Q200,297 188.5,308.5Q177,320 160,320Q143,320 131.5,308.5Q120,297 120,280L120,160Q120,143 131.5,131.5Q143,120 160,120L280,120Q297,120 308.5,131.5Q320,143 320,160Q320,177 308.5,188.5Q297,200 280,200L200,200ZM760,200L680,200Q663,200 651.5,188.5Q640,177 640,160Q640,143 651.5,131.5Q663,120 680,120L800,120Q817,120 828.5,131.5Q840,143 840,160L840,280Q840,297 828.5,308.5Q817,320 800,320Q783,320 771.5,308.5Q760,297 760,280L760,200Z" />
</vector>
Loading