From 25837401d554402fdc064007f2c44a8589e0612d Mon Sep 17 00:00:00 2001
From: Nicolas Fella <nicolas.fella@kde.org>
Date: Sun, 1 Mar 2026 13:44:38 +0100
Subject: [PATCH] dbus_annotation: New protocol

The protocol allows surfaces to be associated
with DBus objects and interfaces.

There's several use cases for this:

- associating surfaces with (AT-SPI) accessibility trees
- associating surfaces with DBus-exported menus

The protocol is designed in such a way that it allows apps/compositors
to use it for additional tasks without spec changes, allowing to replace
custom protocols currently in use for this task.

Signed-off-by: Nicolas Fella <nicolas.fella@kde.org>
---
 meson.build                                   |   1 +
 staging/xdg-dbus-annotation/README            |   4 +
 .../xdg-dbus-annotation-v1.xml                | 127 ++++++++++++++++++
 3 files changed, 132 insertions(+)
 create mode 100644 staging/xdg-dbus-annotation/README
 create mode 100644 staging/xdg-dbus-annotation/xdg-dbus-annotation-v1.xml

diff --git a/meson.build b/meson.build
index 4eda373..0ce05da 100644
--- a/meson.build
+++ b/meson.build
@@ -74,6 +74,7 @@ staging_protocols = {
 	'single-pixel-buffer': {'v1': []},
 	'tearing-control': {'v1': []},
 	'xdg-activation': {'v1': []},
+	'xdg-dbus-annotation': {'v1': []},
 	'xdg-dialog': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
 	'xdg-session-management': {'v1': ['stable/xdg-shell/xdg-shell.xml']},
 	'xdg-system-bell': {'v1': []},
diff --git a/staging/xdg-dbus-annotation/README b/staging/xdg-dbus-annotation/README
new file mode 100644
index 0000000..448535c
--- /dev/null
+++ b/staging/xdg-dbus-annotation/README
@@ -0,0 +1,4 @@
+DBus annotation protocol
+
+Maintainers:
+Nicolas Fella <nicolas.fella@kde.org>
diff --git a/staging/xdg-dbus-annotation/xdg-dbus-annotation-v1.xml b/staging/xdg-dbus-annotation/xdg-dbus-annotation-v1.xml
new file mode 100644
index 0000000..a90faf8
--- /dev/null
+++ b/staging/xdg-dbus-annotation/xdg-dbus-annotation-v1.xml
@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_dbus_annotation_v1">
+  <copyright><![CDATA[
+    Copyright © 2017 David Edmundson
+    Copyright © 2023 Janet Blackquill
+    Copyright © 2026 Nicolas Fella
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  ]]></copyright>
+
+  <description summary="Wayland protocol for associating D-Bus objects with surfaces">
+    The dbus_annotation_manager allows a client to annotate surfaces with information
+    about associated DBus objects.
+
+    Clients should request the creation of an dbus_annotation object when they create a relevant
+    D-Bus object, and should release the annotation when they destroy a D-Bus object associated
+    with their wl_surface.
+
+    Each surface can only have one annotation with a given interface name.
+    The already_annotated protocol error will be raised if the client requests more than
+    one dbus_annotation object with a given interface name for a surface.
+  </description>
+
+  <interface name="xdg_dbus_annotation_manager_v1" version="1">
+    <description summary="controller object for registering dbus objects associated with wl_surfaces">
+      An object that provides access to the creation of dbus_annotation objects.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="release the memory for the application menu manager object">
+        Destroy the xdg_dbus_annotation_manager object. xdg_dbus_annotation objects created from this
+        object remain valid and should be destroyed separately.
+      </description>
+    </request>
+
+    <request name="annotate_surface">
+      <description summary="create surface annotation">
+        Creates an annotation associated with a given wl_surface.
+      </description>
+      <arg name="interface" type="string">
+        <description summary="identifies what kind of dbus object this is expected to be">
+          The interface other D-Bus clients can expect the object specified by the
+          annotation to implement.
+        </description>
+      </arg>
+      <arg name="id" type="new_id" interface="xdg_dbus_annotation_v1"/>
+      <arg name="surface" type="object" interface="wl_surface">
+        <description summary="the surface to annotate">
+          The surface to associate the annotation with.
+        </description>
+      </arg>
+    </request>
+
+    <enum name="error">
+      <entry name="already_annotated" value="0" summary="given wl_surface already has a dbus_annotation with the same interface"/>
+    </enum>
+  </interface>
+
+  <interface name="xdg_dbus_annotation_v1" version="1">
+    <description summary="annotation object for a surface">
+      An object that provides access to clients to notify the compositor of
+      associated D-Bus objects for a wl_surface.
+
+      This state is double-buffered, see wl_surface.commit.
+
+      If not applicable, clients should remove this object.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="release the dbus annotation object"/>
+    </request>
+
+    <enum name="bus_enum">
+      <entry name="session" value="0"
+             summary="the session bus"/>
+      <entry name="system" value="1"
+             summary="the system bus"/>
+      <entry name="atspi" value="2"
+             summary="the AT-SPI2 accessibility bus"/>
+    </enum>
+
+    <request name="set_bus">
+      <description summary="notify the compositor of a dbus object's bus">
+        Set or update the bus corresponding to the
+        D-Bus object.
+      </description>
+      <arg name="bus" type="uint" enum="bus_enum" summary="the dbus bus of a dbus object"/>
+    </request>
+
+    <request name="set_bus_name">
+      <description summary="notify the compositor of a dbus object's bus name">
+        Set or update the pending bus name corresponding to the
+        D-Bus object.
+
+        Strings should be formatted according to the relevant D-Bus specifications.
+      </description>
+      <arg name="bus_name" type="string" summary="the dbus bus name of a dbus object"/>
+    </request>
+
+    <request name="set_object_path">
+      <description summary="notify the compositor of a dbus object's object path">
+        Set or update the pending object path corresponding to the
+        D-Bus object.
+
+        Strings should be formatted according to the relevant D-Bus specifications.
+      </description>
+      <arg name="object_path" type="string" summary="the dbus object path of a dbus object"/>
+    </request>
+  </interface>
+</protocol>