SubMiner/changes/overlay-xwayland-stacking.md

type: fixed area: overlay

• Fixed the overlay intermittently dropping behind mpv on KDE Plasma and other non-Hyprland/Sway Wayland sessions, where it lost pause-on-hover and Yomitan lookups.
• SubMiner now forces XWayland for itself (--ozone-platform-hint=x11) and for every mpv it launches (Jellyfin/YouTube/launcher), binds the windowed overlay to tracked mpv with WM_TRANSIENT_FOR, and swaps to a focusable-false X11 override-redirect overlay while tracked mpv is fullscreen.
• Made Linux overlay stacking focus-sensitive: managed while mpv is windowed, override-redirect only while mpv is fullscreen, and released/hidden when another X11/XWayland app takes focus (detected via _NET_ACTIVE_WINDOW/xprop, falling back to xdotool getactivewindow) so normal foreground windows can cover it. The overlay is shown inactive so hovering subtitles does not reveal Plasma panels/docks over fullscreen mpv.
• Restored subtitle hover, pause-on-hover, and Yomitan lookups under X11/XWayland by tracking the cursor in the main process (Electron cannot forward mouse-move through a click-through window on X11), keeping the primary and secondary subtitle bars and the open sidebar as separate interactive regions while the space between them passes through to mpv — and reporting hit regions as soon as the first subtitle is measured so it is clickable immediately. Matches Windows/macOS.
• Kept normal foreground windows above the overlay while they are open, including SubMiner Settings, Yomitan Settings, AniList setup, Jellyfin setup, first-run setup, and unrelated apps, so hovering over subtitles or the sidebar under those windows no longer restacks the overlay in front.
• Right-clicking non-interactive overlay subtitles now raises tracked mpv together with the overlay, then keeps the overlay above mpv before toggling pause/play.
• Kept overlay bounds reconciled across fullscreen/windowed, minimize/restore, and modal transitions so the subtitle sidebar and secondary subtitles stay inside the mpv window, and ensured only one visible overlay window exists at a time.
• Avoided startup overlay glitches: the first reveal waits until the renderer has painted, the overlay stays hidden until the X11 tracker reports real mpv geometry, and the fullscreen restack hide/show is skipped when leaving fullscreen — preventing black flashes and a display-sized overlay that blocks the desktop before warmups finish.