Skip to main content

protocols

What Tuna Desktop advertises to clients, against what GNOME 51's Mutter advertises. Ledger row P-SY-06 tracks the gaps.

Source of the Mutter column. A wayland-info capture of GNOME Shell 51.0 / Mutter 51.0 (Fedora 45, headless, 1280x800): tests/protocols/gnome51-wayland-info.txt, made by scripts/tuna-gnome-wayland-info. Three globals do not appear headless (the DRM lease and syncobj managers need the native KMS backend; the Xwayland keyboard grab is offered to Xwayland only). They are listed from the interfaces built into the same libmutter-51.so, marked source in tests/protocols/gnome51-globals.tsv. This is upstream GNOME 51 in a Fedora container, not a capture from the Marlin baseline VM.

Native Marlin reference. Run 37196669447 also captured GNOME Shell/Mutter 51.0 in the derived Marlin GNOME 51 baseline on the shared four-vCPU, 6 GiB, 1280×800 QEMU/KVM profile. tests/protocols/marlin-gnome-wayland-info.txt retains its full output; marlin-roost-wayland-info.txt retains the same run's candidate capture. marlin-gnome51-source.json records capture digests, image/package identity, the trusted package source and the actual observer checkout. The Tuna Desktop package is source 7546647e5967825f522a352ee781e0908f889d1e, so this retained candidate capture does not certify subsequent implementation changes.

This native session exposes 41 globals. Its existing 40 match the headless capture's versions; wp_drm_lease_device_v1 is additionally observed at v1. tests/protocols/marlin-gnome51-globals.tsv preserves the same explicit Tuna Desktop version floors and deviations, marks the lease as captured, and keeps the two still-unobserved syncobj/Xwayland-private entries as source-derived floors. Bochs scanout still exposes dmabuf v3, so this VM does not establish the dmabuf feedback version of a GPU-capable Mutter backend. The headless reference remains a separate regression input.

Comparison. The proof stage G-WAYLAND-INFO runs wayland-info against the nested Tuna Desktop session (saved as the wayland-info.txt artifact) and scripts/tuna-wayland-info-compare checks it against tests/protocols/gnome51-globals.tsv. Every global marked match must be present at GNOME's version or newer, and every min: global at least at the version given. Known gaps are reported and do not fail the stage.

The same stage additionally compares against the native Marlin TSV, retaining wayland-info-marlin-compare.txt. Every native captured global is represented by a match, a version floor or a recorded deviation; a source-only floor is never described as a measured native version.

Golden test. crates/compositor/tests/protocols.rs asserts the exact list and versions an ordinary client sees (EXPECTED), that the supervised shell's connection sees exactly that plus SHELL_ONLY (layer-shell, the foreign toplevel list), and that a client inside a wp_security_context_v1 sees EXPECTED less SANDBOX_HIDDEN (session lock, security context). Adding or dropping a protocol updates the test and this page together.

Advertised by Tuna Desktop​

GlobalVersionNotes
wl_compositor6preferred buffer scale sent per surface, for the output it is on
wl_subcompositor1
wl_shm2
wl_seat9
wl_output4one per connected output
wl_data_device_manager3
zwp_primary_selection_device_manager_v11
xdg_wm_base6popups with positioner constraints and grabs; toplevels are told suspended as in Mutter (below)
zxdg_output_manager_v13
zwlr_layer_shell_v14Tuna Desktop's own shell draws through it. Only the supervised shell's connection may bind it: the native connection whose peer pid is the shell child the compositor spawned and still holds (tuna-shell-gtk, or the legacy tuna-shell-host), the same identity the session lock and control socket check. Every other client's registry omits it and a blind bind by name is a protocol error (#1048; ClientState::admit_supervised_shell, layer::is_shell_peer)
zwp_linux_dmabuf_v13only when the renderer reports formats
xdg_activation_v11focus policy below
wp_viewporter1
wp_fractional_scale_manager_v11preferred scale 1 until #59
wp_single_pixel_buffer_manager_v11
wp_cursor_shape_manager_v12shapes accepted; the compositor cursor is still the default arrow
zwp_idle_inhibit_manager_v11an inhibitor holds off the idle lock while its surface is mapped and on screen: one on an unmapped surface, a window that never drew, a hidden or occluded window or one off every output lapses, as the protocol says
zwp_text_input_manager_v31text fields reach the input method (#60)
zwp_input_method_manager_v21private to the compositor-supervised IBus connection, using the same server-owned transport authorization as virtual keyboard; ordinary applications cannot discover or force-bind it. This is not a public GNOME IME API. One exact live input-method resource owns the seat; unavailable objects and their inert child IDs cannot type, observe surrounding text, reserve popup roles, take grabs or retire the owner
zwp_pointer_gestures_v13swipes reach apps; three-finger swipes are the shell's (overview, workspaces)
zwp_relative_pointer_manager_v11raw motion from the DRM backend
zwp_tablet_manager_v22tablets, tools (pressure, tilt, distance, buttons, tool cursors) and pads (buttons, rings, strips, mode groups, application labels shown on the pad OSD) from libinput on the DRM backend; the vendored Smithay adds pads, labels and version 2 (third-party/smithay/TABLET-PAD-API-PATCH.diff); pad dials need libinput 1.26 (the input crate's libinput_1_26 feature), newer than Ubuntu 24.04's 1.25 (#344)
zwp_pointer_constraints_v11a locked pointer stays put; a confined one stays in its window
ext_session_lock_manager_v11the shell's lock screen; only the supervised shell's lock is granted, and only a password the compositor verified unlocks; while locked, input goes only to the lock surface (or nowhere without one), keyboard focus leaves applications as the session locks and returns to the focused window on unlock; duplicate_output is checked per lock object, so a refused or superseded lock does not make the shell's next lock on the same output a protocol error (third-party/smithay/SESSION-LOCK-OUTPUTS-PATCH.diff). Hidden from clients inside a security context
wp_presentation2CLOCK_MONOTONIC, as Mutter; see frame timing below
wp_fifo_manager_v11a barrier is released on the next refresh cycle
wp_commit_timing_manager_v11a timed update applies on the refresh cycle whose next presentation reaches its time; a tv_nsec of a second or more is an invalid_timestamp error, as in Mutter
xdg_wm_dialog_v11a modal dialog is attached to its parent: focusing the parent focuses the dialog (GNOME's attach-modal-dialogs)
zxdg_exporter_v2, zxdg_importer_v21xdg-foreign: the portal parents its dialogs to the app's window, which centres and attaches them like the app's own
xdg_system_bell_v11plays GNOME's bell-window-system sound through canberra-gtk-play when installed (Mutter's audible bell); a burst of rings is one sound
xdg_toplevel_tag_manager_v11each window keeps its tag and description
xdg_session_manager_v11window session save and restore as in Mutter 51 (P-SY-08): a client that opens a session gets its windows back after logout or reboot (workspace, position and size, maximized, tiled, fullscreen, output; minimized is not restored, as in Mutter); store $XDG_DATA_HOME/tuna/window-sessions.json, written 3 s after a change and at exit (crates/compositor/src/xdg_session.rs)
zwp_keyboard_shortcuts_inhibit_manager_v11after Allow, the focused window gets every key, the shell's grabs, Super and Alt+Tab included; Super+Escape (Mutter's restore-shortcuts) takes them back until the window is focused again
wp_pointer_warp_v11honoured while the surface has pointer focus from the enter serial it names; nested, the host pointer stays where it is
wp_security_context_manager_v11a sandbox engine (Flatpak) creates a listener; every client accepted on it joins the display tagged with the context (sandbox engine, app id, instance id: ClientState::security_context) until the engine closes the context's close fd. Such a client is refused every privileged global whatever else it is (layer-shell, the foreign toplevel list, input-method, virtual keyboard, mutter_x11_interop: ClientState::privileged), does not see the session lock, and does not see this manager, so it cannot nest. The published sandboxed-app-id stays the one read from the live peer, not the engine's claim (#1046)
ext_idle_notifier_v12idle and resumed from the clock org.gnome.Mutter.IdleMonitor keeps: every timestamped input event restarts it, and the notifications are checked on the same loop tick and deadline. get_idle_notification honours the idle inhibitors the idle lock honours (zwp_idle_inhibitor_v1 and org.gnome.SessionManager's idle flag): it never idles while one is held, an idle one resumes when one appears, and its timeout restarts when the last goes. get_input_idle_notification counts input alone (crates/compositor/src/idle_notify.rs, #1046)
wp_content_type_manager_v11the hint is kept per surface and applied on commit (protocols::surface_content_type); recorded for future VRR and frame scheduling, nothing acts on it yet (#1046)
ext_foreign_toplevel_list_v11the supervised shell's alone, like layer-shell: window titles and app ids are published only to the shell and the portal picker (docs/security-model.md), so every other registry omits it and a blind bind is a protocol error. A handle per window in the window model, native and X11 alike, with its title and app id (empty when unknown), updated when either changes and closed when the window unmaps (#1046)
wp_alpha_modifier_v11the multiplier applies wherever a surface is drawn: Smithay's WaylandSurfaceRenderElement, which every surface draw goes through, multiplies it into the element's alpha (#1046)

xdg-activation policy​

A token is valid only when the client that asks for it holds keyboard focus and attaches an input serial. It works once, within 10 seconds. A valid request focuses the window and raises it unless org.gnome.desktop.wm.preferences raise-on-click is off (Mutter activates these as META_CLIENT_TYPE_APPLICATION). This is Mutter's focus-stealing prevention in its simplest form: a background app cannot mint its way to the front.

Frame timing​

presentation-time, fifo and commit-timing follow the frame path (crates/compositor/src/frame_timing.rs):

  • Feedback is taken from the surfaces a frame drew. On hardware it is marked presented at that output's page flip with the kernel's vblank time and sequence and Mutter's KMS flags (vsync, hardware clock, hardware completion). Nested, it is marked when the host takes the frame, timed by the compositor's clock, with no flags (Mutter's nested backends cannot vouch for the host either). A surface not drawn (a hidden workspace, the lock screen up) keeps its feedback until it is, or until a newer update discards it.
  • Fifo barriers and commit timers advance once per refresh cycle (the primary output's page flip; nested, each frame) on every surface that receives frame callbacks, drawn or not, so a client on a hidden workspace never stalls.

Suspended windows​

The xdg_toplevel suspended state (xdg-shell v6) follows Mutter's window suspend state (update_suspend_state in src/core/window.c, crates/compositor/src/suspend.rs):

  • A window is shown while a frame draws any of it: on the active workspace (or both during a workspace slide), not minimized, and not wholly under opaque windows; while the overview, the window switcher or a cast shows window clones, every window is. While the screen is locked none is (GNOME Shell hides its window group under the lock).
  • A window not shown for 3 s (Mutter's SUSPEND_HIDDEN_TIMEOUT_S) gets a configure with suspended. It gets one without it as soon as it is shown again, before the frame that draws it (a culled window uncovered by a moving window is told right after that frame).
  • Only a change of state is configured; a client older than v6 is never told, and keeps the hidden windows' frame callbacks.
  • A hidden window gets frame callbacks about once a second; once told it is suspended, none, as Mutter sends hidden surfaces none, until it is shown again. A configure it has not acknowledged keeps full-rate callbacks meanwhile.
  • suspended_windows in the compositor state lists the suspended windows.

Activation changes are configured the same way: a window losing focus gets one configure, never a second identical one.

Keyboard shortcuts inhibit​

Tuna Desktop asks before letting a focused, mapped app take shortcuts. The GTK shell shows a modal with Deny and Allow and explains Super+Escape. Only Allow activates the inhibitor; Deny cannot be undone by refocusing. Known desktop apps use GNOME's PermissionStore (gnome table, shortcuts-inhibitor id, GRANTED/DENIED values), so remembered grants skip the dialog. Unknown apps are never remembered. An unavailable store opens the dialog. Background requests, stale responses, destroyed surfaces and requests outstanding at lock or a switch to another app fail closed. The non-GTK fallback shell has no consent UI and keeps requests inactive. Super+Escape always takes granted shortcuts back until the window is focused again. GNOME's configurable Xwayland exemption rules are not implemented. scripts/tuna-shortcut-proof exercises Allow, Deny, refocus, emergency restore, stale focus and lock through a real Wayland test client.

GNOME D-Bus interfaces​

GNOME's portal backend (xdg-desktop-portal-gnome) talks to GNOME Shell and Mutter over D-Bus, not Wayland. Tuna Desktop serves those interfaces itself, as niri does, so the stock portal works.

InterfaceTuna DesktopNotes
org.gnome.Shell.ScreenshotScreenshot, ScreenshotWindowsaves a PNG of the screen or the focused window; the name is left to a real GNOME Shell when one runs (nested preview)
org.gnome.Mutter.ScreenCastCreateSession, RecordMonitor, RecordWindow, Start, Stopmonitor and window streams over PipeWire (BGRx, shared memory, up to 30 fps), adapted from niri; window streams follow resizes and end when the window closes
org.gnome.Mutter.DisplayConfigGetCurrentState, ApplyMonitorsConfigthe portal's monitor picker and GNOME Settings' Displays panel (modes, refresh, scale, position, rotation, mirroring, disabling; Mutter 51 verify/temporary/persistent with confirmation)
org.gnome.Mutter.InputCaptureCreateSession, SupportedCapabilities; Session: GetZones, AddBarrier, ClearBarriers, Enable, Disable, Release, ConnectToEIS, Close; Activated, Deactivated, ZonesChanged, Disabled, Closedthe portal's InputCapture (Input Leap, Deskflow): pointer barriers on outer monitor edges, then pointer and keyboard go to the session's EIS receiver instead of clients until Release; installed portal only, never while locked (#1040, input capture)
org.gnome.Shell.Introspectyeswindow list for the portal's window picker and running apps (with sandboxed-app-id) for its Background portal; desktop-portal callers only, like GNOME Shell (#61). As in GNOME 51, the same /org/gnome/Shell/Introspect object also answers under org.gnome.Shell, where xdg-desktop-portal-gnome's Background portal asks: the GTK shell relays it to the compositor, which admits the original caller with the same rule (#410)
org.freedesktop.PolicyKit1.AuthenticationAgentBeginAuthentication, CancelAuthenticationthe GTK shell registers as this session's polkit agent (system bus, again whenever polkit restarts) and shows GNOME's Authentication Required dialog; passwords go to polkit's helper as libpolkit-agent-1 sends them: through /run/polkit/agent-helper.socket (socket-activated polkit-agent-helper@.service, polkit ≥ 127) first, else the setuid polkit-agent-helper-1. A wrong password restarts the conversation as GNOME does; a helper that fails before asking waits for Authenticate instead of respawning (#884)
org.gnome.Mutter.IdleMonitorGetIdletime, AddIdleWatch, AddUserActiveWatch, RemoveWatch, WatchFiredthe session's idle time and watches, served by the compositor; gnome-settings-daemon dims and blanks on it, and banners wait for an away user
org.gnome.ShellShowOSD, FocusSearch, ShowApplications, GrabAccelerator(s), UngrabAccelerator(s), AcceleratorActivated, AcceleratorDeactivated; Mode, OverviewActive, ShellVersionserved by the GTK shell: gnome-settings-daemon's media keys grab their keys here (the compositor keeps them from apps, in the action modes they ask for, the lock screen included) and show the volume and brightness OSD; GNOME's caller allowlist (Settings, media keys, the GNOME portal backend); a caller's grabs go when it leaves the bus. Grab flags IGNORE_AUTOREPEAT and TRIGGER_RELEASE are honoured (others refuse the grab): a held key's release reaches its caller as AcceleratorDeactivated, never across a lock or to a re-created grab. As Mutter's synchronous grab, a (un)grab call returns only once the compositor has installed the changed table (its CommandResult), so a key pressed after the reply meets it

Accelerator mutations are serialized: only their own request's CommandResult commits the proposed grab table and completes the D-Bus call. A denied or lost admission returns an error and cannot reappear in a subsequent table; a denied ungrab keeps the installed owner. Internal rebinding keeps the installed action callbacks until their replacement is acknowledged, accepting either generation's already-emitted events within the same control drain. Every full table, including one sent for an external grab, retains an Rc snapshot of its actual internal callback generation until its own result; maps are not copied per external call. Request identities also retain the local control-connection generation: if another send redials between GTK socket pumps, old-link calls fail, while admissions already sent on the new link remain pending normally.

Gaps against Mutter​

From the GNOME 51 capture. The globals not listed here are offered at GNOME's version.

ProtocolGNOME 51Tuna DesktopWhy, and where tracked
xdg_wm_base76Smithay 0.7 creates the global at 6 and implements nothing newer; bumps with Smithay (#89)
wl_seat109Smithay 0.7 creates the seat at 9 and implements nothing newer; bumps with Smithay (#89)
zwp_text_input_manager_v321Smithay 0.7 implements v1 only; bumps with Smithay (#60)
zxdg_exporter_v1, zxdg_importer_v11missingGTK3 exports with v1; Smithay 0.7 implements v2 only and keeps its handle table private, so a v1 handle could not be imported by the portal's v2 (#61)
xdg_toplevel_drag_manager_v11missingnot in Smithay 0.7: a window attached to a drag-and-drop operation and moved with it (detachable browser tabs) (#89)
wp_color_manager_v1 (v2), wp_color_representation_manager_v12, 1missingnot in Smithay 0.7: needs a colour-managed renderer (ICC/HDR, YUV conversion); the GLES path is sRGB only (#89)
ext_background_effect_manager_v11missingnot in Smithay 0.7: needs a blur pass in the renderer (#89)
wl_fixes1missingnot in wayland-server 0.31; its destroy_registry frees a registry object, which wayland-backend owns (#89)
wp_drm_lease_device_v11 (native Marlin capture)missinglease needs connectors to hand out for VR headsets; recorded deviation, not exercised by the nested session (#68, #89)
wp_linux_drm_syncobj_manager_v1source-derived floor 1; absent in this VM capturemissingexplicit sync needs the DRM backend's syncobj import; GPU-capable native acceptance remains open (#68, #89)
zwp_xwayland_keyboard_grab_manager_v1 (Xwayland only; from source)—missingonly rootful Xwayland with -host-grab uses it, and Mutter allows grabs only per xwayland-grab-access-rules; Tuna Desktop runs rootless Xwayland (#89)
gtk_shell17missingnot planned: GTK4 needs none of it on a GNOME session
zwp_linux_dmabuf_v1 feedback (v4+)native backend onlyversion 3#89

Deliberate differences​

  • xdg-decoration is absent, as in Mutter. GNOME is client-side decorations only, and the golden test asserts the absence.
  • layer-shell is present, unlike Mutter. Tuna Desktop's shell is a separate process and draws its panel, overview and banners through it. Only that supervised shell can see or bind it; applications cannot, so they have no more surface-placement reach than on GNOME.
  • security-context, ext-idle-notify, content-type, ext-foreign-toplevel-list and alpha-modifier are present, though Mutter 51 advertises none of them (#1046). Smithay 0.7 implements them and they cost GNOME apps nothing: security-context lets Flatpak mark its clients so they are kept from every privileged global, idle-notify serves idle daemons from the idle clock GNOME's IdleMonitor already uses, content-type is only recorded, and alpha-modifier only changes how a client's own surface is blended. The foreign toplevel list is offered to the supervised shell only, so applications learn no more about other windows than on GNOME.

The clipboard outlives the client that copied it, as Mutter's meta-clipboard-manager.c keeps it. When a client sets the clipboard (wl_data_device or data control), the compositor copies its most preferred supported type in Mutter's order (images up to 200 MiB, plain text up to 4 MiB; a larger copy is cut at the limit, as Mutter's is). When that owner clears the clipboard, destroys its source or disconnects, the compositor offers the finished copy, that one type only, as its own selection. The primary selection is not retained, as in Mutter. Unlike Mutter, a RemoteDesktop session's selection is not copied (crates/compositor/src/clipboard_manager.rs, #1033).

xdg_toplevel_icon_manager_v1 v1 accepts square SHM icons and sanitized theme names, applied on the next surface commit. PNGs live in a private, bounded compositor cache. X11 _NET_WM_ICON and legacy square TrueColor WM_HINTS pixmaps (24/32-bit color, optional 1-bit transparency mask) are read on a bounded worker for mapped window identities. Palette and unsupported visuals fall back to a generic app icon.