Research: Wayland Layer Shell for Linux Floating Overlay

[sewandev]

Following community feedback from Reddit, we have some excellent starting points for porting the Windows-exclusive Floating Overlay to Linux using Wayland's Layer Shell protocol.

Technical Pointers

1. Wayland Layer Shell: This is the protocol used to draw surfaces above normal windows (status bars, overlays, notifications). Protocol spec: wlr-layer-shell-unstable-v1.
2. Smithay Client Toolkit: A Rust library for Wayland clients. It recently added a \simple_layer.rs\ example that demonstrates how to render a layer shell surface:
   • https://github.com/Smithay/client-toolkit/blob/master/examples/simple_layer.rs
3. Wayscriber: An open-source Rust project that allows annotations over anything on the screen. Excellent reference implementation for a Wayland overlay in Rust:
   • https://github.com/devmobasa/wayscriber

Challenges

Since Reverbic is a TUI application built on
atatui, combining it with a native graphical Wayland surface might require rendering text graphically onto the layer surface rather than running it through a terminal emulator.

Alternative / Workaround

As a short-term workaround for Linux users, we could document using a terminal emulator with built-in overlay capabilities, such as the Kitty kitten panel.

[sewandev]

@

Key finding — reframes the rendering challenge

After auditing the current implementation, the premise in the "Challenges" section needs a correction: the Floating Overlay is not the ratatui TUI. src/overlay.rs does not use ratatui at all — it is a standalone Win32 window drawn by hand with GDI (FillRect, TextOutW, Segoe UI fonts, an animated VU meter). It is a 2D graphical panel that runs independently of the terminal.

This actually simplifies the port: there is no need to embed a terminal emulator into a layer-shell surface, and no need to "render terminal text graphically." The real work is reimplementing the same 2D layout with a Linux 2D stack:

• Surface/protocol: smithay-client-toolkit + wlr-layer-shell. The Overlay layer gives always-on-top natively (replaces WS_EX_TOPMOST), anchors give the corner positioning natively (replaces the overlay_coords math), and an empty input region gives click-through (replaces WS_EX_TRANSPARENT).
• 2D rasterization: tiny-skia drawing into an ARGB SHM buffer (what the simple_layer.rs example does manually). Alternative: raqote.
• Text: cosmic-text (fontconfig-backed, handles font fallback) or a lighter ab_glyph/fontdue with a bundled font (Segoe UI does not exist on Linux).

The hard part is therefore text/shape rasterization + the surface protocol, not TUI integration.

Scope note

This issue should be scoped strictly to displaying the floating surface with playback state. Ducking, game detection, media keys, tray and notifications are separate WASAPI/Win32 features — on Linux their idiomatic equivalents are PipeWire (ducking) and MPRIS over D-Bus (now-playing / media keys), and warrant their own issues.

Compositor reality

wlr-layer-shell works on wlroots (Sway, Hyprland) and KDE/KWin, but not on GNOME (Mutter never implemented it) nor on X11. A "Wayland layer-shell first, X11 later" strategy is recommended, with the Kitty panel kitten documented as the short-term workaround for unsupported environments.
@