How a Wayland tray icon and popup actually work
On X11, a tray icon and a popup menu were mostly one trick. On Wayland they are two separate mechanisms, and a tray applet needs both.
The icon: StatusNotifierItem
The tray icon is not a Wayland feature at all. It uses StatusNotifierItem, a D-Bus protocol on the session bus. An application registers an item with a watcher service. A tray host, such as the waybar tray module, reads the registered items and draws their icons. Clicks come back to the application over D-Bus. This is why rnetapplet needs a tray host running: the applet publishes the item, and something else has to display it.
The popup: wlr-layer-shell
A normal Wayland window cannot choose where it appears on screen, because the compositor decides. A popup that sits under a bar in the top right corner needs to be placed. The wlr-layer-shell protocol lets a client create a surface on a layer such as overlay or top and anchor it to screen edges with margins. Bars, launchers and notification daemons all use it.
The protocol comes from the wlroots project, and compositors built on wlroots such as Sway, river and niri support it. Some desktops do not offer it, which is why tools built on it list a layer-shell compositor as a requirement. On GTK4, the gtk4-layer-shell library turns an ordinary window into a layer surface.
Putting them together
An applet like rnetapplet therefore has two halves. The D-Bus half publishes the tray item and talks to NetworkManager. The Wayland half draws the popup in the right place. Keeping them on separate threads, with GTK on the main thread, stops slow D-Bus calls from freezing the interface.
Debugging tips
If no icon appears, check that a tray host is running and that the item is registered on the bus. If the popup never shows, check that your compositor lists the layer-shell surface. Most problems come down to one of those two missing pieces. The full story of one applet built this way is in the rnetapplet write-up.