Skip to content

maxrave-dev/kotlin-footguns / skills/compose-screens-footguns

compose-screens-footguns

Verified

Compose screen and interaction traps: navigation, adaptive layout, window insets, pagers, toolbars, sheets, list drag and selection, sliders, text fields, settings UI, one-shot effects. Use when layout, gestures or navigation misbehave.

FileKindSize
SKILL.mdskill md21.6 KB
references/collapsing-parallax-toolbar.mdmarkdown8.4 KB
references/commit-a-text-field-on-an-explicit-action.mdmarkdown8.1 KB
references/control-range-must-cover-stored-values.mdmarkdown6.2 KB
references/custom-modal-sheet-family.mdmarkdown7.1 KB
references/custom-thin-media-slider.mdmarkdown8.3 KB
references/desktop-mini-player-window.mdmarkdown7.8 KB
references/edit-a-shape-as-a-shape.mdmarkdown7.1 KB
references/empty-state-must-keep-its-navigation.mdmarkdown7.0 KB
references/event-not-state-edge-for-one-shot-effects.mdmarkdown7.5 KB
references/expandable-and-linkified-text.mdmarkdown6.9 KB
references/floating-overlay-reserves-its-own-strip.mdmarkdown9.1 KB
references/fullscreen-video-gesture-overlay.mdmarkdown7.6 KB
references/hidden-setting-does-not-clear-the-stored-value.mdmarkdown6.3 KB
references/layered-video-backdrop-pager.mdmarkdown8.6 KB
references/lazy-item-grouping-beats-arrangement-gap.mdmarkdown8.2 KB
references/lazy-list-drag-reorder.mdmarkdown8.0 KB
references/lazy-scroll-helper-kit.mdmarkdown6.9 KB
references/nav-tab-registration-drift.mdmarkdown8.6 KB
references/nowplaying-pager-no-feedback-loop.mdmarkdown7.5 KB
references/progress-indicator-as-scrubber.mdmarkdown6.0 KB
references/responsive-gate-size-not-platform.mdmarkdown9.0 KB
references/scoped-composable-shadows-the-top-level-one.mdmarkdown5.3 KB
references/screen-shell-content-split.mdmarkdown7.2 KB
references/selection-mode-state-holder.mdmarkdown8.0 KB
references/self-hiding-child-cannot-hide-its-slot.mdmarkdown5.2 KB
references/settings-value-round-tripped-through-its-label.mdmarkdown6.2 KB
references/stacked-bars-double-consume-window-insets.mdmarkdown8.7 KB
references/story-reel-auto-pager.mdmarkdown8.5 KB
references/swipe-action-list-row.mdmarkdown7.7 KB
references/type-safe-nav-graph-organization.mdmarkdown7.6 KB
references/variant-layout-math-stays-in-the-variant.mdmarkdown5.8 KB
references/weight-fill-false-to-center-a-cluster.mdmarkdown8.6 KB

references/nowplaying-pager-no-feedback-loop.md

View on GitHub
---
name: nowplaying-pager-no-feedback-loop
description: A now-playing artwork pager that both follows the player and drives it, without the two writing to each other in a loop — the in-progress-scroll flag covers programmatic animation as well as drags, the seek is dispatched from the settled page only, and the page-difference decision is a pure function outside the UI runtime. Use when a swipe bounces back to the page it came from, when one swipe skips two tracks, when the pager stops following the player after a fast swipe, when swiping backwards restarts the current track instead of going back one, or when a far swipe under shuffle lands on the wrong song.
---

# Now-playing pager without a feedback loop

The pager is a **two-way** binding: it slides when the player advances, and it seeks when the user
settles on another page. Each direction writes what the other watches — keep one quiet at a time.

## Traps

**The in-progress-scroll flag is true for programmatic animation too.** It is the obvious way to mean
"the user is dragging" and it is wrong: the pager sets it identically for a drag and for the
animate-to-page call your own follow effect just made, so it blocks the follow while it runs. Use a
flag you own:

```kotlin
// adapted
var isAnimatingFromPlayer by remember { mutableStateOf(false) }
var isUserDraggingActive by remember { mutableStateOf(false) }
LaunchedEffect(pagerState) {
    snapshotFlow { pagerState.isScrollInProgress to isAnimatingFromPlayer }
        .collect { (scrolling, animating) -> isUserDraggingActive = scrolling && !animating }
}
```

**Bracket every programmatic scroll with that flag in a `try`/`finally`.** Not tidiness — the effect
is cancelled whenever its keys change, which is what happens when the track advances again
mid-animation, and a flag left `true` by that cancellation blocks every later write permanently.

```kotlin
// adapted
LaunchedEffect(currentIndex, queue.size) {
    val target = currentIndex
    if (!isUserDraggingActive && target in queue.indices && target != pagerState.currentPage) {
        isAnimatingFromPlayer = true
        try { pagerState.animateScrollToPage(target) } finally { isAnimatingFromPlayer = false }
    }
}
```

**Dispatch from the settled page, never the current or target page.** The current page flips as soon
as a drag crosses the halfway point and can flip back inside one gesture; the target page changes
with the fling. Either one sends a seek per crossing — "one swipe skipped two tracks":

```kotlin
// adapted
LaunchedEffect(pagerState, currentIndex, queue.size) {
    snapshotFlow { pagerState.settledPage }
        .distinctUntilChanged()
        .collect { settled ->
            if (isAnimatingFromPlayer) return@collect
            if (settled !in queue.indices) return@collect
            if (settled == currentIndex) return@collect
            dispatch(computeSeekAction(settled, currentIndex))
        }
}
```

The last guard is the loop-breaker: after the player moves and the follow effect slides the pager to
match, the pager settles and emits — without it, that emission goes back at the player as a seek it
has already done.

**Keep the decision a pure function, outside the composition** — four outcomes from one subtraction,
in a file importing a domain model and nothing from the UI toolkit, so it is exercisable with no UI:

```kotlin
// as written
internal fun computeSeekAction(
    newPage: Int,
    currentOrderIndex: Int,
): ArtworkSeekAction =
    when (newPage - currentOrderIndex) {
        0 -> ArtworkSeekAction.NoOp
        1 -> ArtworkSeekAction.Next
        -1 -> ArtworkSeekAction.Previous
        else -> ArtworkSeekAction.Skip(newPage)
    }
```

The branch exists because adjacent and far moves are different commands: a ±1 move reuses the
player's own next/previous, preserving whatever transition machinery the adapter runs between
neighbouring items (see `crossfade-dual-player`); a longer jump goes through seek-by-index.

**Use the skip-to-previous-*item* command for a backwards swipe.** Plain previous implements the
standard "restart the current track if the playhead is past a few seconds" rule — a literal position
threshold in the desktop adapter, a configurable maximum-seek-to-previous-position on the mobile
engine. Swipe backwards half a minute in and the player restarts that song, leaving the pager a page
away; the follow effect slides it back and the swipe bounces. Every other caller of "previous" still
wants the restart rule, so this is a second command, not a changed one.

**The page index is in play order; the engine's seek-by-index is in timeline order.** The pages are
the queue the user can see, which under shuffle is a permutation of the engine's list — full
treatment in `queue-index-vs-shuffle-space`. Route the far skip through the handler entry point that
converts (`if (shuffleModeEnabled) getUnshuffledIndex(index) else index`), or a far swipe under
shuffle plays a different song than the one under the finger. The ±1 branch is unaffected.

**Derive the page from the queue using the id the queue actually stores.** Engines are commonly
handed a decorated media id — a prefix naming which rendition is loaded, or a cache key — and
comparing that against the plain queue ids fails for exactly the decorated entries, so the pager
sits on page 0 whenever one of them plays.

```kotlin
// as written
internal fun deriveOrderIndex(
    queue: List<Track>,
    nowPlayingVideoId: String?,
): Int {
    if (queue.isEmpty() || nowPlayingVideoId.isNullOrEmpty()) return 0
    return queue
        .indexOfLast { it.videoId == nowPlayingVideoId }
        .coerceAtLeast(0)
}
```

The coercion keeps the pager on a valid page while the queue has been replaced and the now-playing
state has not caught up. Matching by id cannot tell two copies of one track apart, so read
`queue-index-vs-shuffle-space` first — and for the same reason **page keys must stay unique when the
queue is not**: build the key from the id **and** the index, or a repeat collides.

**Two edge states need explicit handling.** A queue that shrinks below the current page leaves the
pager past the end — watch the size and scroll to the last index. And with repeat-one on,
next/previous do not move, so a settled swipe is dragged straight back: disable scrolling
(`userScrollEnabled = !isRepeatOne && queue.isNotEmpty()`) instead of letting the user fight it.

## Verifying it

1. `grep -rn --include="*.kt" "isScrollInProgress\|animateScrollToPage\|settledPage\|scrollToPage(" .`
   — the four sync points together. Every *animated* scroll must sit inside the owned flag's
   `try`/`finally`; an instant `scrollToPage` snaps, so it emits no intermediate pages — but its one
   settled destination still reads as a swipe, so bracket it too unless the guards already drop it.
2. `grep -rn "^import" $(grep -rl --include="*.kt" "fun computeSeekAction" .)` — the decision file
   must import no UI-toolkit package at all; a domain model and nothing else is the expected listing.
3. `grep -rn --include="*.kt" "seekToPrevious()\|seekToPreviousMediaItem()" .` — both must exist on
   the player interface and every adapter, and the backwards branch must reach the media-item one.
4. By hand, in order: swipe forward one page (one advance, no bounce); let a track end on its own
   (the pager slides, no seek goes back); swipe backwards well past the restart threshold (previous
   track, not a restart); swipe several pages quickly (one jump, landing where you released); repeat
   with shuffle on, checking the audible track against the artwork; then turn repeat-one on.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall