🎉 Add a backend for the COSMIC desktop

[sam-ludford]

Closes #738.

This adds a backend for the COSMIC desktop (cosmic-comp, Wayland), following the GNOME backend's shape: a thin D-Bus client talking to a small helper daemon that lives in its own repository, kando-cosmic-integration (Rust, MIT). I am happy to transfer that repository to the kando-menu organisation.

Why a helper

cosmic-comp exposes none of what the existing Wayland backends rely on: no pointer query, no zwlr_foreign_toplevel_manager_v1, no zwlr_virtual_pointer_manager_v1, and no GlobalShortcuts portal (forcing the Niri backend crashes in the native addon on the missing globals). What it does expose is zwlr_layer_shell_v1, ext_foreign_toplevel_list_v1 + zcosmic_toplevel_info_v1 / zcosmic_toplevel_manager_v1, zwp_virtual_keyboard_manager_v1, wp_pointer_warp_v1 and ext_workspace_v1. The helper builds Kando's needs on those:

Backend method	How
getWMInfo	pointer from wl_pointer.enter on a transparent layer-shell overlay (verified: cosmic-comp sends it without motion, ~5–150 ms); focused window from the activated toplevel state; panel-adjusted work area measured once and cached
getOpenWindows / focusWindow	toplevel list + activate
movePointer	wp_pointer_warp_v1 (cosmic-comp only honours it for the keyboard-focused surface, so the probe overlay briefly takes exclusive keyboard focus)
simulateKeys	virtual keyboard with the seat's keymap and an xkb state for modifiers, same a(ibi) shape as the GNOME extension
menu window size	cosmic-comp clamps floating windows to two thirds of the output and paints an opaque backdrop behind fullscreen windows, so the daemon maximizes the "Kando Menu" toplevel as soon as it maps

The helper ships a setup wizard (make install && make setup) that checks the compositor globals, adds the floating-window rule, creates a COSMIC custom shortcut for a menu and pre-creates the named workspaces used by the example menu, plus a doctor command to re-check.

Shortcuts: not possible on COSMIC. supportsShortcuts: false with a hint to bind kando --menu "Name" to a COSMIC custom shortcut. The backend also warns with the exact rule when the floating-window exception cosmic-comp needs is missing (there is no protocol to opt out of auto-tiling).

COSMIC example menu

The second commit adds example-menus/cosmic.json, used instead of linux.json when XDG_CURRENT_DESKTOP=COSMIC. Simulated compositor shortcuts (e.g. Super+M) do not trigger cosmic-comp bindings for virtual-keyboard input, so the generic Linux menu's window items would be dead there. The COSMIC menu instead runs helper commands: send the focused window to a named workspace (Coding / Browsing / Files / Chat / Media), switch workspaces, maximize / minimize / fullscreen / pin / close, COSMIC apps, screenshots, clipboard and system actions. If you would rather not ship a desktop-specific example menu, that commit can be dropped without affecting the backend.

Tested

Ubuntu 26.04, COSMIC (cosmic-comp 1.7), 4K single output: menu opens under the pointer via a custom shortcut and via a Solaar mouse-button rule, Escape closes it, focused window and app are reported correctly, workspace moves and window actions work. npm run prettier, npm run lint, npm run tscheck, npm test and reuse lint pass. Not tested: multi-monitor (the probe maps one overlay per output, so it should work), touch.

Docs

I have a matching section ready for installation-on-linux.mdx on the website and will open a PR on kando-menu.github.io once this lands.

🤖 Generated with Claude Code

[Schneegans]

Thank you very much for looking into this! This looks like you had even more trouble getting this to run on COSMIC than I had on GNOME or KDE...

I will happily merge this (and I think we can even include it in 3.0, since it's well decoupled and will not affect the other platforms). Yet I think we should maybe call it an "experimental" backend given that you haven't been able to test it thoroughly.

I think the only change to the code I would suggest is that you try avoid duplicating localization keys for the COSMIC example menu. There are several entries which have the same name as in the other example menus and this creates more work for the translators. Just use the matching key from the default Linux menu.

I guess we should move the integration daemon to the Kando organization. Then I would invite you and give you write access to that repo so that you can maintain it? What do you think?