gitpane 1.0.0__py3-none-any.whl

gitpane/ui/window_control/wayland_activation.py

@@ -0,0 +1,695 @@
+"""Use the Wayland compositor's activation protocol on Qt's own connection.
+
+Mutter lets a started program bring its window to the front only when the token it received names a surface of the
+program that asked for it together with an input serial still valid for that surface: the serial that gave that
+surface the keyboard, a key still held, or the last button press of the pointer while the pointer is still on it. It
+checks the token when the started program uses it, not when GitPane asks for it, so the token is asked for when the
+user clicks and stays valid as long as GitPane keeps the keyboard.
+
+GitPane also brings one of its own windows back to the front with such a token: it asks for a token named on the
+surface that has the keyboard, then hands it at once to the compositor's activate request for the window to bring back.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import functools
+import logging
+import os
+import select
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtGui import QGuiApplication, QNativeInterface
+
+from gitpane.config import ACTIVATION_TOKEN_MAX_LENGTH, MILLISECONDS_PER_SECOND, WAYLAND_ACTIVATION_TOKEN_TIMEOUT_MS
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QWindow
+
+# Workaround: Qt asks for activation tokens itself but keeps that request private, and PySide6 gives no access to it.
+# A program GitPane starts for a click only comes to the front under GNOME Wayland when it receives a token naming a
+# GitPane surface and an input serial the compositor still accepts for it, and Mutter refuses a token asked for on a
+# second connection, which has no surface with the focus. This binds xdg_activation_v1 again on Qt's connection, on an
+# event queue of its own as Qt itself does for xdg-foreign, and waits a bounded time for each click. The serial is the
+# one that gave GitPane the keyboard, read from a short-lived keyboard object of GitPane's own: Qt only keeps the serial
+# of the last press, which names a context menu's surface once the menu has closed, and the pointer may have left the
+# window by then, so that press alone would leave the started program behind GitPane.
+
+WAYLAND_CLIENT_LIBRARY_NAME = "libwayland-client.so.0"
+ACTIVATION_GLOBAL_NAME = "xdg_activation_v1"
+TOKEN_INTERFACE_NAME = "xdg_activation_token_v1"
+SURFACE_INTERFACE_NAME = "wl_surface"
+SEAT_INTERFACE_NAME = "wl_seat"
+ACTIVATION_VERSION = 1
+# Interfaces of the core protocol, taken from the Wayland client library itself rather than described again here.
+LIBRARY_INTERFACE_SYMBOL_BY_NAME = {
+    "wl_registry": "wl_registry_interface",
+    "wl_callback": "wl_callback_interface",
+    SURFACE_INTERFACE_NAME: "wl_surface_interface",
+    SEAT_INTERFACE_NAME: "wl_seat_interface",
+    "wl_keyboard": "wl_keyboard_interface",
+}
+
+# Request numbers of the core protocol (wayland.xml): the position of each request in its interface.
+DISPLAY_SYNC_OPCODE = 0
+DISPLAY_GET_REGISTRY_OPCODE = 1
+REGISTRY_BIND_OPCODE = 0
+SEAT_GET_KEYBOARD_OPCODE = 1
+KEYBOARD_RELEASE_OPCODE = 0
+# wl_keyboard.release exists from this version of the seat on; an older seat keeps its keyboard objects for good.
+KEYBOARD_RELEASE_SINCE_VERSION = 3
+# Request numbers of xdg-activation-v1: the position of each request in ACTIVATION_INTERFACE and TOKEN_INTERFACE below.
+ACTIVATION_DESTROY_OPCODE = 0
+ACTIVATION_GET_TOKEN_OPCODE = 1
+ACTIVATION_ACTIVATE_OPCODE = 2
+TOKEN_SET_SERIAL_OPCODE = 0
+TOKEN_SET_APP_ID_OPCODE = 1
+TOKEN_SET_SURFACE_OPCODE = 2
+TOKEN_COMMIT_OPCODE = 3
+TOKEN_DESTROY_OPCODE = 4
+# Flags of wl_proxy_marshal_array_flags: WL_MARSHAL_FLAG_DESTROY destroys the proxy once its destructor request is sent.
+NO_MARSHAL_FLAG = 0
+MARSHAL_DESTROY_FLAG = 1
+# Characters accepted in a token received from the compositor: visible ASCII only, so it can go into an environment
+# variable and a D-Bus argument as it is.
+FIRST_TOKEN_CHARACTER = "!"
+LAST_TOKEN_CHARACTER = "~"
+# A C array whose address is handed to the library holds at least one element, even for a message without arguments.
+MINIMUM_ARRAY_LENGTH = 1
+
+
+@dataclass(frozen=True)
+class ProtocolMessage:
+    """One request or event of a Wayland interface, as the protocol file writes it."""
+
+    name: str
+    signature: str
+    # Interface named by each argument of the signature, None for an argument that names none.
+    type_names: tuple[str | None, ...] = ()
+
+
+@dataclass(frozen=True)
+class ProtocolInterface:
+    """A Wayland interface the client library does not carry, described from its protocol file."""
+
+    name: str
+    version: int
+    requests: tuple[ProtocolMessage, ...]
+    events: tuple[ProtocolMessage, ...] = ()
+
+
+# xdg-activation-v1, version 1, from the wayland-protocols file staging/xdg-activation/xdg-activation-v1.xml.
+TOKEN_INTERFACE = ProtocolInterface(
+    name=TOKEN_INTERFACE_NAME,
+    version=ACTIVATION_VERSION,
+    requests=(
+        ProtocolMessage("set_serial", "uo", (None, SEAT_INTERFACE_NAME)),
+        # Never sent: the identifier names the program that will start, and GNOME Shell would show GitPane as starting.
+        ProtocolMessage("set_app_id", "s", (None,)),
+        ProtocolMessage("set_surface", "o", (SURFACE_INTERFACE_NAME,)),
+        ProtocolMessage("commit", ""),
+        ProtocolMessage("destroy", ""),
+    ),
+    events=(ProtocolMessage("done", "s", (None,)),),
+)
+ACTIVATION_INTERFACE = ProtocolInterface(
+    name=ACTIVATION_GLOBAL_NAME,
+    version=ACTIVATION_VERSION,
+    requests=(
+        ProtocolMessage("destroy", ""),
+        ProtocolMessage("get_activation_token", "n", (TOKEN_INTERFACE_NAME,)),
+        ProtocolMessage("activate", "so", (None, SURFACE_INTERFACE_NAME)),
+    ),
+)
+# Described in this order because the activation interface names the token interface.
+OWN_PROTOCOL_INTERFACES = (TOKEN_INTERFACE, ACTIVATION_INTERFACE)
+
+
+class WaylandMessage(ctypes.Structure):
+    """struct wl_message of the Wayland client library."""
+
+    _fields_ = [("name", ctypes.c_char_p), ("signature", ctypes.c_char_p), ("types", ctypes.POINTER(ctypes.c_void_p))]
+
+
+class WaylandInterface(ctypes.Structure):
+    """struct wl_interface of the Wayland client library."""
+
+    _fields_ = [("name", ctypes.c_char_p), ("version", ctypes.c_int), ("method_count", ctypes.c_int), ("methods", ctypes.POINTER(WaylandMessage)),
+                ("event_count", ctypes.c_int), ("events", ctypes.POINTER(WaylandMessage))]
+
+
+class WaylandArgument(ctypes.Union):
+    """union wl_argument of the Wayland client library, for the argument kinds this module sends."""
+
+    _fields_ = [("i", ctypes.c_int32), ("u", ctypes.c_uint32), ("s", ctypes.c_char_p), ("o", ctypes.c_void_p), ("n", ctypes.c_uint32)]
+
+
+@dataclass(frozen=True)
+class KeyboardFocus:
+    """The GitPane surface that has the keyboard, with the serial the compositor gave when it got it."""
+
+    surface: int
+    serial: int
+
+
+@dataclass(frozen=True)
+class _ActivationBinding:
+    """GitPane's own event queue on Qt's connection, with the activation global bound on it."""
+
+    queue: int
+    display_wrapper: int
+    activation: int
+
+
+# Answers of the compositor, written by the event handlers below and read by the function waiting for them. Keyed by
+# the address of the proxy the event came for; only the window's thread dispatches GitPane's queue.
+_activation_global_name_by_registry: dict[int, int] = {}
+_finished_callback_set: set[int] = set()
+_token_by_proxy: dict[int, bytes] = {}
+_keyboard_focus_by_proxy: dict[int, KeyboardFocus | None] = {}
+# Activation binding of each Wayland connection, None when GitPane cannot have one there; see _activation_binding.
+_activation_binding_by_display: dict[int, _ActivationBinding | None] = {}
+
+
+def _on_registry_global(_data: int | None, registry: int | None, name: int, interface_name: bytes | None, _version: int) -> None:
+    """Note the number of the activation global when the compositor lists it."""
+    if registry is not None and interface_name == ACTIVATION_GLOBAL_NAME.encode():
+        _activation_global_name_by_registry[registry] = name
+
+
+def _on_registry_global_remove(_data: int | None, registry: int | None, name: int) -> None:
+    """Forget the activation global if the compositor withdraws it."""
+    if registry is not None and _activation_global_name_by_registry.get(registry) == name:
+        del _activation_global_name_by_registry[registry]
+
+
+def _on_callback_done(_data: int | None, callback: int | None, _callback_data: int) -> None:
+    """Note that the compositor answered everything sent before a sync request."""
+    if callback is not None:
+        _finished_callback_set.add(callback)
+
+
+def _on_token_done(_data: int | None, token: int | None, value: bytes | None) -> None:
+    """Keep the token the compositor handed out."""
+    if token is not None:
+        _token_by_proxy[token] = value or b""
+
+
+def _on_keyboard_keymap(_data: int | None, _keyboard: int | None, _format: int, descriptor: int, _size: int) -> None:
+    """Close the keymap file the compositor sends to every new keyboard object: only the focus is read here."""
+    try:
+        os.close(descriptor)
+    except OSError:
+        pass
+
+
+def _on_keyboard_enter(_data: int | None, keyboard: int | None, serial: int, surface: int | None, _keys: int | None) -> None:
+    """Note which GitPane surface has the keyboard, with the serial that gave it."""
+    if keyboard is not None and surface:
+        _keyboard_focus_by_proxy[keyboard] = KeyboardFocus(surface, serial)
+
+
+def _on_keyboard_leave(_data: int | None, keyboard: int | None, _serial: int, _surface: int | None) -> None:
+    """Forget the focus when the keyboard leaves GitPane."""
+    if keyboard is not None:
+        _keyboard_focus_by_proxy[keyboard] = None
+
+
+def _on_keyboard_key(_data: int | None, _keyboard: int | None, _serial: int, _time: int, _key: int, _state: int) -> None:
+    """Ignore a key: Qt's own keyboard object handles the typing."""
+
+
+def _on_keyboard_modifiers(_data: int | None, _keyboard: int | None, _serial: int, _depressed: int, _latched: int, _locked: int, _group: int) -> None:
+    """Ignore the modifiers: Qt's own keyboard object handles them."""
+
+
+def _on_keyboard_repeat_info(_data: int | None, _keyboard: int | None, _rate: int, _delay: int) -> None:
+    """Ignore the key repeat settings: Qt's own keyboard object handles them."""
+
+
+# C signatures of the event handlers: void handler(void *data, struct wl_proxy *proxy, <event arguments>).
+REGISTRY_GLOBAL_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_char_p, ctypes.c_uint32)
+REGISTRY_GLOBAL_REMOVE_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32)
+CALLBACK_DONE_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32)
+TOKEN_DONE_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p)
+KEYBOARD_KEYMAP_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_int32, ctypes.c_uint32)
+KEYBOARD_ENTER_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p, ctypes.c_void_p)
+KEYBOARD_LEAVE_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p)
+KEYBOARD_KEY_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32)
+KEYBOARD_MODIFIERS_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32)
+KEYBOARD_REPEAT_INFO_HANDLER_TYPE = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int32, ctypes.c_int32)
+
+# Kept at module level: the client library calls these pointers for as long as the objects they listen to exist,
+# and the registry lives as long as the process.
+REGISTRY_HANDLERS = (REGISTRY_GLOBAL_HANDLER_TYPE(_on_registry_global), REGISTRY_GLOBAL_REMOVE_HANDLER_TYPE(_on_registry_global_remove))
+CALLBACK_HANDLERS = (CALLBACK_DONE_HANDLER_TYPE(_on_callback_done),)
+TOKEN_HANDLERS = (TOKEN_DONE_HANDLER_TYPE(_on_token_done),)
+# In the order of the wl_keyboard events: keymap, enter, leave, key, modifiers, repeat_info.
+KEYBOARD_HANDLERS = (KEYBOARD_KEYMAP_HANDLER_TYPE(_on_keyboard_keymap), KEYBOARD_ENTER_HANDLER_TYPE(_on_keyboard_enter), KEYBOARD_LEAVE_HANDLER_TYPE(_on_keyboard_leave),
+                     KEYBOARD_KEY_HANDLER_TYPE(_on_keyboard_key), KEYBOARD_MODIFIERS_HANDLER_TYPE(_on_keyboard_modifiers),
+                     KEYBOARD_REPEAT_INFO_HANDLER_TYPE(_on_keyboard_repeat_info))
+
+
+def _listener(handlers: tuple[object, ...]) -> ctypes.Array[ctypes.c_void_p]:
+    """Build the C table of event handlers the client library calls, in event order."""
+    pointers: list[int | None] = []
+    for handler in handlers:
+        pointers.append(ctypes.cast(handler, ctypes.c_void_p).value)
+    return (ctypes.c_void_p * len(pointers))(*pointers)
+
+
+REGISTRY_LISTENER = _listener(REGISTRY_HANDLERS)
+CALLBACK_LISTENER = _listener(CALLBACK_HANDLERS)
+TOKEN_LISTENER = _listener(TOKEN_HANDLERS)
+KEYBOARD_LISTENER = _listener(KEYBOARD_HANDLERS)
+
+
+@functools.cache
+def _wayland_library() -> ctypes.CDLL:
+    """Use the Wayland client library Qt already loaded, and declare the calls this module makes.
+
+    RTLD_NOLOAD never loads a second copy beside Qt's: outside a Wayland session the library is not loaded and this
+    raises OSError instead.
+    """
+    library = ctypes.CDLL(WAYLAND_CLIENT_LIBRARY_NAME, mode=os.RTLD_NOLOAD | os.RTLD_LAZY)
+    pointer = ctypes.c_void_p
+    library.wl_display_create_queue.argtypes = [pointer]
+    library.wl_display_create_queue.restype = pointer
+    library.wl_event_queue_destroy.argtypes = [pointer]
+    library.wl_event_queue_destroy.restype = None
+    library.wl_proxy_create_wrapper.argtypes = [pointer]
+    library.wl_proxy_create_wrapper.restype = pointer
+    library.wl_proxy_wrapper_destroy.argtypes = [pointer]
+    library.wl_proxy_wrapper_destroy.restype = None
+    library.wl_proxy_set_queue.argtypes = [pointer, pointer]
+    library.wl_proxy_set_queue.restype = None
+    library.wl_proxy_marshal_array_flags.argtypes = [pointer, ctypes.c_uint32, pointer, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(WaylandArgument)]
+    library.wl_proxy_marshal_array_flags.restype = pointer
+    library.wl_proxy_add_listener.argtypes = [pointer, pointer, pointer]
+    library.wl_proxy_add_listener.restype = ctypes.c_int
+    library.wl_proxy_get_version.argtypes = [pointer]
+    library.wl_proxy_get_version.restype = ctypes.c_uint32
+    library.wl_proxy_destroy.argtypes = [pointer]
+    library.wl_proxy_destroy.restype = None
+    library.wl_display_prepare_read_queue.argtypes = [pointer, pointer]
+    library.wl_display_prepare_read_queue.restype = ctypes.c_int
+    library.wl_display_read_events.argtypes = [pointer]
+    library.wl_display_read_events.restype = ctypes.c_int
+    library.wl_display_cancel_read.argtypes = [pointer]
+    library.wl_display_cancel_read.restype = None
+    library.wl_display_dispatch_queue_pending.argtypes = [pointer, pointer]
+    library.wl_display_dispatch_queue_pending.restype = ctypes.c_int
+    library.wl_display_flush.argtypes = [pointer]
+    library.wl_display_flush.restype = ctypes.c_int
+    library.wl_display_get_fd.argtypes = [pointer]
+    library.wl_display_get_fd.restype = ctypes.c_int
+    return library
+
+
+@dataclass(frozen=True)
+class _ProtocolStructures:
+    """The C descriptions of the interfaces this module uses, kept alive as long as the library may read them."""
+
+    address_by_name: dict[str, int]
+    kept_objects: tuple[object, ...]
+
+
+@functools.cache
+def _protocol_structures() -> _ProtocolStructures:
+    """Build the C descriptions of xdg-activation-v1 from ProtocolInterface, pointing at the library's own core interfaces."""
+    library = _wayland_library()
+    address_by_name: dict[str, int] = {}
+    kept_objects: list[object] = []
+    for name, symbol in LIBRARY_INTERFACE_SYMBOL_BY_NAME.items():
+        address_by_name[name] = ctypes.addressof(WaylandInterface.in_dll(library, symbol))
+    for description in OWN_PROTOCOL_INTERFACES:
+        interface = WaylandInterface()
+        kept_objects.append(interface)
+        address_by_name[description.name] = ctypes.addressof(interface)
+        interface.name = description.name.encode()
+        interface.version = description.version
+        interface.method_count = len(description.requests)
+        interface.methods = _message_array(description.requests, address_by_name, kept_objects)
+        interface.event_count = len(description.events)
+        interface.events = _message_array(description.events, address_by_name, kept_objects)
+    return _ProtocolStructures(address_by_name, tuple(kept_objects))
+
+
+def _message_array(descriptions: tuple[ProtocolMessage, ...], address_by_name: dict[str, int], kept_objects: list[object]) -> ctypes._Pointer[WaylandMessage] | None:
+    """Build the C array of messages of one interface, each with the interfaces its arguments name."""
+    if not descriptions:
+        return None
+    messages = (WaylandMessage * len(descriptions))()
+    kept_objects.append(messages)
+    for index, description in enumerate(descriptions):
+        types = (ctypes.c_void_p * max(len(description.type_names), MINIMUM_ARRAY_LENGTH))()
+        kept_objects.append(types)
+        for type_index, type_name in enumerate(description.type_names):
+            types[type_index] = address_by_name[type_name] if type_name is not None else None
+        name = description.name.encode()
+        signature = description.signature.encode()
+        kept_objects.extend((name, signature))
+        messages[index].name = name
+        messages[index].signature = signature
+        messages[index].types = ctypes.cast(types, ctypes.POINTER(ctypes.c_void_p))
+    return ctypes.cast(messages, ctypes.POINTER(WaylandMessage))
+
+
+def _marshal(library: ctypes.CDLL, proxy: int, opcode: int, arguments: list[WaylandArgument], *, interface: int | None = None, version: int | None = None,
+             flags: int = NO_MARSHAL_FLAG) -> int | None:
+    """Send one request on a proxy, the way the generated protocol functions do, and return the object it creates, if any."""
+    argument_array = (WaylandArgument * max(len(arguments), MINIMUM_ARRAY_LENGTH))(*arguments)
+    request_version = version if version is not None else library.wl_proxy_get_version(proxy)
+    return library.wl_proxy_marshal_array_flags(proxy, opcode, interface, request_version, flags, argument_array)
+
+
+def _new_id_argument() -> WaylandArgument:
+    """The placeholder the client library replaces with the number of the object a request creates."""
+    argument = WaylandArgument()
+    argument.o = None
+    return argument
+
+
+def _dispatch_until(library: ctypes.CDLL, display: int, queue: int, is_done: Callable[[], bool], deadline: float) -> bool:
+    """Read the compositor's answers for GitPane's queue until is_done, never waiting past deadline (time.monotonic()).
+
+    Reads cooperate with Qt's own reading thread through the client library's prepare and read protocol: whichever
+    reader comes last reads the socket and hands each event to its queue.
+    """
+    descriptor = library.wl_display_get_fd(display)
+    while not is_done():
+        if library.wl_display_prepare_read_queue(display, queue) != 0:
+            if library.wl_display_dispatch_queue_pending(display, queue) < 0:
+                raise OSError("The Wayland connection failed.")
+            continue
+        library.wl_display_flush(display)
+        remaining = deadline - time.monotonic()
+        readable_descriptors: list[int] = []
+        if remaining > 0:
+            readable_descriptors, _writable_descriptors, _failed_descriptors = select.select([descriptor], [], [], remaining)
+        if not readable_descriptors:
+            library.wl_display_cancel_read(display)
+            return False
+        if library.wl_display_read_events(display) < 0:
+            raise OSError("The Wayland connection failed.")
+        if library.wl_display_dispatch_queue_pending(display, queue) < 0:
+            raise OSError("The Wayland connection failed.")
+    return True
+
+
+def _roundtrip(library: ctypes.CDLL, display: int, binding_queue: int, display_wrapper: int, deadline: float) -> None:
+    """Wait until the compositor has answered every request sent so far on the connection, or raise TimeoutError."""
+    structures = _protocol_structures()
+    callback = _marshal(library, display_wrapper, DISPLAY_SYNC_OPCODE, [_new_id_argument()], interface=structures.address_by_name["wl_callback"])
+    if not callback:
+        raise OSError("The compositor could not be asked for an answer.")
+    library.wl_proxy_add_listener(callback, CALLBACK_LISTENER, None)
+    try:
+        if not _dispatch_until(library, display, binding_queue, lambda: callback in _finished_callback_set, deadline):
+            raise TimeoutError("The compositor did not answer in time.")
+    finally:
+        _finished_callback_set.discard(callback)
+        library.wl_proxy_destroy(callback)
+
+
+def _activation_binding(display: int, deadline: float) -> _ActivationBinding | None:
+    """Bind the activation global once per connection, on an event queue of GitPane's own; None when GitPane cannot.
+
+    Kept for the whole process, a failure included: a registry has no request that destroys it, so binding again for
+    every click would leave one more object on the compositor each time. A compositor that has no activation global, or
+    that does not answer before deadline the first time, is therefore not asked again until GitPane restarts; the
+    started programs then open as they do without a token.
+    """
+    if display in _activation_binding_by_display:
+        return _activation_binding_by_display[display]
+    try:
+        binding = _bind_activation(display, deadline)
+    except OSError:
+        _activation_binding_by_display[display] = None
+        raise
+    _activation_binding_by_display[display] = binding
+    return binding
+
+
+def _bind_activation(display: int, deadline: float) -> _ActivationBinding | None:
+    """Create GitPane's event queue on the connection and bind the activation global on it; None when the compositor has none.
+
+    What it created is freed again on GitPane's side when it returns None or fails, so a binding that is not kept
+    leaves neither an event queue nor a registry listening on the connection.
+    """
+    library = _wayland_library()
+    structures = _protocol_structures()
+    binding_queue = library.wl_display_create_queue(display)
+    if not binding_queue:
+        raise OSError("No event queue could be created on the Wayland connection.")
+    display_wrapper = None
+    registry = None
+    try:
+        display_wrapper = library.wl_proxy_create_wrapper(display)
+        if not display_wrapper:
+            raise OSError("The Wayland connection could not be wrapped.")
+        library.wl_proxy_set_queue(display_wrapper, binding_queue)
+        registry = _marshal(library, display_wrapper, DISPLAY_GET_REGISTRY_OPCODE, [_new_id_argument()], interface=structures.address_by_name["wl_registry"])
+        if not registry:
+            raise OSError("The compositor's registry could not be read.")
+        library.wl_proxy_add_listener(registry, REGISTRY_LISTENER, None)
+        _roundtrip(library, display, binding_queue, display_wrapper, deadline)
+        global_name = _activation_global_name_by_registry.get(registry)
+        if global_name is not None:
+            name_argument = WaylandArgument()
+            name_argument.u = global_name
+            interface_argument = WaylandArgument()
+            interface_argument.s = ACTIVATION_GLOBAL_NAME.encode()
+            version_argument = WaylandArgument()
+            version_argument.u = ACTIVATION_VERSION
+            activation = _marshal(library, registry, REGISTRY_BIND_OPCODE, [name_argument, interface_argument, version_argument, _new_id_argument()],
+                                  interface=structures.address_by_name[ACTIVATION_GLOBAL_NAME], version=ACTIVATION_VERSION)
+            if not activation:
+                raise OSError("The activation protocol could not be bound.")
+            return _ActivationBinding(binding_queue, display_wrapper, activation)
+    except BaseException:
+        _release_binding_setup(library, binding_queue, display_wrapper, registry)
+        raise
+    _release_binding_setup(library, binding_queue, display_wrapper, registry)
+    return None
+
+
+def _release_binding_setup(library: ctypes.CDLL, binding_queue: int, display_wrapper: int | None, registry: int | None) -> None:
+    """Free, on GitPane's side, the registry, display wrapper and event queue of a binding that is not kept."""
+    if registry:
+        _activation_global_name_by_registry.pop(registry, None)
+        # A registry has no request that destroys it: this frees GitPane's proxy only, the compositor keeps its object.
+        library.wl_proxy_destroy(registry)
+    if display_wrapper:
+        library.wl_proxy_wrapper_destroy(display_wrapper)
+    library.wl_event_queue_destroy(binding_queue)
+
+
+def activation_deadline() -> float:
+    """Return the monotonic time by which one click must have its token, binding, keyboard focus and token included."""
+    return time.monotonic() + WAYLAND_ACTIVATION_TOKEN_TIMEOUT_MS / MILLISECONDS_PER_SECOND
+
+
+def read_keyboard_focus(display: int, seat: int, deadline: float) -> KeyboardFocus | None:
+    """Return the GitPane surface that has the keyboard of seat, with the serial that gave it, or None when GitPane has not.
+
+    A new keyboard object receives at once the current focus and its serial when the focus is on one of GitPane's
+    surfaces; it is released as soon as that answer is read. Call only with a seat that has a keyboard: the protocol
+    forbids asking a keyboard of a seat that never had one.
+    """
+    library = _wayland_library()
+    binding = _activation_binding(display, deadline)
+    if binding is None:
+        return None
+    seat_version = library.wl_proxy_get_version(seat)
+    keyboard_interface = WaylandInterface.from_address(_protocol_structures().address_by_name["wl_keyboard"])
+    if seat_version < KEYBOARD_RELEASE_SINCE_VERSION or keyboard_interface.event_count > len(KEYBOARD_HANDLERS):
+        return None
+    seat_wrapper = library.wl_proxy_create_wrapper(seat)
+    if not seat_wrapper:
+        raise OSError("The seat could not be wrapped.")
+    try:
+        library.wl_proxy_set_queue(seat_wrapper, binding.queue)
+        keyboard = _marshal(library, seat_wrapper, SEAT_GET_KEYBOARD_OPCODE, [_new_id_argument()], interface=ctypes.addressof(keyboard_interface), version=seat_version)
+    finally:
+        library.wl_proxy_wrapper_destroy(seat_wrapper)
+    if not keyboard:
+        raise OSError("No keyboard object could be created.")
+    _keyboard_focus_by_proxy[keyboard] = None
+    library.wl_proxy_add_listener(keyboard, KEYBOARD_LISTENER, None)
+    try:
+        _roundtrip(library, display, binding.queue, binding.display_wrapper, deadline)
+        return _keyboard_focus_by_proxy.get(keyboard)
+    finally:
+        _keyboard_focus_by_proxy.pop(keyboard, None)
+        _marshal(library, keyboard, KEYBOARD_RELEASE_OPCODE, [], flags=MARSHAL_DESTROY_FLAG)
+
+
+def request_activation_token(display: int, seat: int, serial: int, surface: int, deadline: float) -> str:
+    """Ask the compositor for a token naming surface and serial on seat, and return it once checked, or an empty text.
+
+    Never names the program that will start: GNOME Shell would take GitPane for it. Each request starts the
+    compositor's startup notice (a busy pointer outside the windows) until a program uses the token, for 15 s at most
+    under Mutter, so it is only asked for when a program is about to start.
+    """
+    library = _wayland_library()
+    binding = _activation_binding(display, deadline)
+    if binding is None:
+        return ""
+    structures = _protocol_structures()
+    token = _marshal(library, binding.activation, ACTIVATION_GET_TOKEN_OPCODE, [_new_id_argument()], interface=structures.address_by_name[TOKEN_INTERFACE_NAME])
+    if not token:
+        raise OSError("No activation token object could be created.")
+    library.wl_proxy_add_listener(token, TOKEN_LISTENER, None)
+    try:
+        if serial and seat:
+            serial_argument = WaylandArgument()
+            serial_argument.u = serial
+            seat_argument = WaylandArgument()
+            seat_argument.o = seat
+            _marshal(library, token, TOKEN_SET_SERIAL_OPCODE, [serial_argument, seat_argument])
+        if surface:
+            surface_argument = WaylandArgument()
+            surface_argument.o = surface
+            _marshal(library, token, TOKEN_SET_SURFACE_OPCODE, [surface_argument])
+        _marshal(library, token, TOKEN_COMMIT_OPCODE, [])
+        if not _dispatch_until(library, display, binding.queue, lambda: token in _token_by_proxy, deadline):
+            raise TimeoutError("The compositor did not hand out a token in time.")
+        return _checked_token(_token_by_proxy[token])
+    finally:
+        _token_by_proxy.pop(token, None)
+        _marshal(library, token, TOKEN_DESTROY_OPCODE, [], flags=MARSHAL_DESTROY_FLAG)
+
+
+def _checked_token(raw: bytes) -> str:
+    """Return a token received from the compositor when it is visible ASCII of a bounded length, an empty text otherwise.
+
+    The token goes into a started program's environment and into a D-Bus argument: a control character, a
+    non-ASCII character or an oversized value is refused rather than passed on.
+    """
+    if not raw or len(raw) > ACTIVATION_TOKEN_MAX_LENGTH:
+        return ""
+    try:
+        text = raw.decode("ascii")
+    except UnicodeDecodeError:
+        return ""
+    for character in text:
+        if not FIRST_TOKEN_CHARACTER <= character <= LAST_TOKEN_CHARACTER:
+            return ""
+    return text
+
+
+def wayland_native_interface_type() -> type | None:
+    """Return Qt's Wayland native interface class, or None where PySide6 has none.
+
+    PySide6 only exposes QNativeInterface.QWaylandApplication when its Qt was built with Wayland support: the Windows
+    wheel has only QNativeInterface.QWindowsScreen, and reading the Wayland name there raises AttributeError.
+    """
+    return getattr(QNativeInterface, "QWaylandApplication", None)
+
+
+def wayland_activation_token() -> str:
+    """Return a token for the user's last action in GitPane, or an empty text when there is nothing to name.
+
+    Read on the window's thread when the user clicks, before any worker starts. The token names the GitPane surface
+    that has the keyboard with the serial that gave it the keyboard, which the compositor accepts for as long as GitPane
+    keeps the keyboard, wherever the pointer went, a context menu that reached past the window included. Without the
+    keyboard, it names the focused window with the last press Qt saw. The value is never written to the log.
+    """
+    native = wayland_native_interface()
+    if native is None:
+        return ""
+    deadline = activation_deadline()
+    try:
+        display = native.display()
+        seat = native.seat()
+        if seat and native.keyboard():
+            focus = read_keyboard_focus(display, seat, deadline)
+            if focus is not None:
+                return _logged_token(request_activation_token(display, seat, focus.serial, focus.surface, deadline))
+        window = QGuiApplication.focusWindow()
+        serial = native.lastInputSerial()
+        last_input_seat = native.lastInputSeat()
+        if window is None or not serial or not last_input_seat:
+            logging.getLogger(__name__).debug("no activation token: no GitPane window has the keyboard or a press")
+            return ""
+        # Under Qt's Wayland plugin, a window's identifier is its wl_surface.
+        return _logged_token(request_activation_token(display, last_input_seat, serial, int(window.winId()), deadline))
+    except (OSError, AttributeError, ctypes.ArgumentError, ValueError) as error:
+        logging.getLogger(__name__).debug("no activation token: %s", type(error).__name__)
+        return ""
+
+
+def _logged_token(token: str) -> str:
+    """Log whether a token came, never its value, and return it."""
+    logging.getLogger(__name__).debug("activation token received" if token else "no activation token: the compositor's answer was refused")
+    return token
+
+
+def wayland_native_interface() -> object | None:
+    """Return the native interface of Qt's own Wayland connection, or None without an application or outside Qt's Wayland platform.
+
+    The one place that decides whether GitPane runs on Qt's Wayland connection, for the token request and for the
+    activation alike.
+    """
+    application = QGuiApplication.instance()
+    if application is None:
+        return None
+    native = application.nativeInterface()
+    wayland_interface_type = wayland_native_interface_type()
+    if wayland_interface_type is None or not isinstance(native, wayland_interface_type):
+        return None
+    return native
+
+
+def _wayland_display() -> int | None:
+    """Return the address of Qt's own Wayland connection, or None outside Qt's Wayland platform."""
+    native = wayland_native_interface()
+    if native is None:
+        return None
+    return native.display()
+
+
+def activate_surface(token: str, surface: int) -> bool:
+    """Ask the compositor to activate a GitPane surface with an activation token, and tell whether the request was sent.
+
+    Sent on GitPane's own binding of the activation protocol, then flushed at once as the token request is, so the
+    compositor reads it without waiting for Qt's next write. Nothing is sent without a token, a surface or a binding;
+    the compositor decides alone whether the token lets the window come to the front.
+    """
+    if not token or not surface:
+        return False
+    try:
+        display = _wayland_display()
+        if not display:
+            return False
+        binding = _activation_binding(display, activation_deadline())
+        if binding is None:
+            return False
+        library = _wayland_library()
+        token_argument = WaylandArgument()
+        token_argument.s = token.encode("ascii")
+        surface_argument = WaylandArgument()
+        surface_argument.o = surface
+        _marshal(library, binding.activation, ACTIVATION_ACTIVATE_OPCODE, [token_argument, surface_argument])
+        library.wl_display_flush(display)
+    except (OSError, AttributeError, ctypes.ArgumentError, ValueError) as error:
+        logging.getLogger(__name__).debug("window not activated: %s", type(error).__name__)
+        return False
+    return True
+
+
+def activate_window_with_keyboard_token(window: QWindow) -> bool:
+    """Bring a GitPane window to the front with a token named on the GitPane surface that has the keyboard, and tell whether it was asked.
+
+    The token is used at once on GitPane's own surface and never written to the log nor handed to another program.
+    """
+    token = wayland_activation_token()
+    if not token:
+        return False
+    # Under Qt's Wayland plugin, a window's identifier is its wl_surface.
+    return activate_surface(token, int(window.winId()))