maxrave-dev/kotlin-footguns / skills/compose-screens-footguns
compose-screens-footguns
VerifiedCompose 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.
references/desktop-mini-player-window.md
View on GitHub---
name: desktop-mini-player-window
description: A second always-on-top, frameless desktop window for playback controls — its existence held as one boolean outside the composition, the same state object as the main window, a hand-rolled drag that anchors to absolute pointer coordinates, a native minimum size in device pixels, and geometry persisted without flooding the store. Use when the small window drifts or jitters while being dragged, when it cannot be resized past a corner, when it collapses below its content, when it disappears the moment the main window is closed, when it opens invisible, or when its state disagrees with the main window's.
---
# Desktop mini-player window
The mini player is **not** a second application. It is one more window in the same application
composition, whose existence is a boolean and whose contents read the same state holder the main
window reads:
```kotlin
// adapted
application {
Window(onCloseRequest = { isVisible = false }, visible = isVisible, …) { App() }
if (MiniPlayerManager.isOpen) {
MiniPlayerWindow(
stateHolder = playerStateHolder,
onCloseRequest = { MiniPlayerManager.isOpen = false },
)
}
}
```
That boolean lives outside the composition so anything can flip it — the tray menu, an in-app
button reached through a platform hook, the window's own close button — with no window handle and
no message passing:
```kotlin
// as written
object MiniPlayerManager {
var isOpen by mutableStateOf(false)
}
```
## Traps
**Pass the state holder in; never build a second graph.** The temptation with a second window is a
second dependency scope and a second view model "for the small one" — then both windows must be
told about each other, and in a media app a second graph means a second engine handle. Handing the
existing instance down means both collect the same flows and cannot disagree.
**Closing the main window must not end the application.** Route its close request to
`visible = false` and keep exactly one exit path — typically a tray "quit" item that releases the
player first. Otherwise the small window, the whole point of the feature, is destroyed by the
gesture users perform to get to it.
**If the main window falls back to a decorated, opaque window anywhere, the second one needs the
same fallback.** Transparent undecorated windows fail to render under some drivers, notably in
virtual machines, and the process stays healthy while nothing appears — the failure mode covered by
`compose-desktop-runtime-hardening`. A main window written `undecorated = !isVM, transparent =
!isVM` beside a second written `undecorated = true, transparent = true` can come up invisible on
exactly the machines where the first one was fixed.
**Undecorated means you own the drag — and a local drag delta is measured in a moving frame.** The
handle travels with the window, so each frame's delta is relative to a position that already
changed; accumulating it drifts and jitters. Anchor to the OS pointer position captured at drag
start, together with the window position, and compute from absolutes every frame:
```kotlin
// adapted — the gesture's own dragAmount is deliberately ignored
detectDragGestures(
onDragStart = {
val mouse = MouseInfo.getPointerInfo().location
dragStartMouse = mouse.x to mouse.y
val pos = windowState.position
if (pos is WindowPosition.Absolute) dragStartWindow = pos.x.value to pos.y.value
},
onDrag = { change, _ ->
change.consume()
val startMouse = dragStartMouse
val startWindow = dragStartWindow
if (startMouse != null && startWindow != null) {
val now = MouseInfo.getPointerInfo().location
windowState.position = WindowPosition(
(startWindow.first + (now.x - startMouse.first)).dp,
(startWindow.second + (now.y - startMouse.second)).dp,
)
}
},
onDragEnd = { dragStartMouse = null; dragStartWindow = null },
)
```
**Keep the drag handle off the resize edges.** A handle spanning the full top edge covers both top
resize corners, so the window cannot be resized from them at all; give it the middle portion of the
top edge and a fixed height. With no title bar, also set a move cursor on it — that is the only
signal the strip is draggable.
**The minimum size belongs on the native window, and it is in device pixels.** Window state sizes
are density-independent; the toolkit's minimum is not, so multiply by the display's scale transform
or the floor is off by that factor. Set it from inside the window's content, once it exists:
```kotlin
// adapted
LaunchedEffect(Unit) {
(window as? java.awt.Window)?.minimumSize = Dimension(
(minWidth * window.graphicsConfiguration.defaultTransform.scaleX).toInt(),
(minHeight * window.graphicsConfiguration.defaultTransform.scaleY).toInt(),
)
}
```
Enforcing the floor only in Compose lets the native resize go smaller and be corrected on the next
frame, which is visible as flicker at the edge of the drag.
**Persisted geometry has three separate hazards.** Only an *absolute* position can be written — the
sensible default is an alignment (bottom-right of the screen), which has no coordinates, so guard
the write on the position's type. Use a sentinel that cannot be a real coordinate for "never saved",
because zero is a legitimate position; a not-a-number float works. And clamp the restored size up to
the current minimum on read, since a size stored by an older build can be below it. Persist on drag
end or debounce, because **an effect keyed on the window position runs on every step of a drag** —
it writes the store continuously while the window moves, and any log line there goes at that rate.
**Choose the control set by measured size; let hover do feedback only.** The window resizes down to
a strip, so branch the layout on its constraints — an aspect-ratio test for a square or tall
window, then width thresholds for compact / medium / full — and drop optional buttons below a
width. Hover is right for affordances (a cover that scales a little, a panel that goes opaque) and
wrong as the only way to reach a control: it has no keyboard equivalent and no touch equivalent.
**Wire transport keys on the window, and consume only what you handle** — a frameless window with no
menu bar has nowhere else to put them. Match on key-down plus the key, act, return `true`; every
other event returns `false`, or tab focus and every shortcut you did not think of stop working.
## Verifying it
1. `grep -rn --include="*.kt" "isOpen" .` — every write of the open flag in one listing: the tray
items, the shared toggle hook, the window's own close request. Any of them holding a window
handle or posting an event instead is the path that will disagree with the tray label.
2. `grep -rn --include="*.kt" "exitApplication()" .` — one hit, not in the main window's close.
3. `grep -rn --include="*.kt" -A 3 "alwaysOnTop\|undecorated\|transparent =\|MouseInfo.getPointerInfo\|minimumSize" .`
— `transparent =` puts both window declarations in the listing; `-A 3` carries the minimum body
to the scale multiply. Side by side: the fallback on both; the pointer read in the drag *body*
as well as at start (only at start means local deltas); the minimum scaled by display transform.
4. `grep -rn --include="*.kt" -A 3 "LaunchedEffect(windowState" .` — anything writing to disk or
logging inside an effect keyed on position runs per drag step.
5. By hand: drag slowly across the screen and check it tracks the cursor exactly with no drift;
resize from all four corners; shrink to the floor and confirm no flicker; close the main window
and confirm the mini player and the audio survive; relaunch and confirm it reopens where and how
you left it; delete the stored preferences and confirm the first-run default position is used.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |