From 180c9f2890eeb429ad44d75633c5083c1245877f Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Wed, 10 Dec 2025 15:17:22 +1000
Subject: [PATCH] proto: add a blurb about events to send during stop_emulating

This should've been specified from day one but better late than never.
Since stop_emulating is supposed to signal termination of a client
emulating input, a logical assumption is that the device is set back to
neutral. Let's point it out that the real behavior is within EIS but
clients should behave predictably.

Part-of: <https://gitlab.freedesktop.org/libinput/libei/-/merge_requests/368>
---
 proto/protocol.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/proto/protocol.xml b/proto/protocol.xml
index 02411b8..b86186b 100644
--- a/proto/protocol.xml
+++ b/proto/protocol.xml
@@ -645,6 +645,12 @@
 
         It is a protocol violation to send this request for a client
         of an ei_handshake.context_type other than sender.
+
+        It is up to the EIS implementation to reset the device state when a
+        stop_emulating event is received. The recommendation is that the device
+        is set to a neutral state such that all touches, buttons, keys are logically up.
+        A client should send the corresponding events before stop_emulating
+        to avoid any ambiguity on event interpretation.
       </description>
       <arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
     </request>
@@ -1247,6 +1253,10 @@
 
         It is a protocol violation to send this request for a client
         of an ei_handshake.context_type other than sender.
+
+        A client should send a ei_button.button release event before
+        ei_device.stop_emulating to avoid any ambiguity on interpretation
+        of button events.
       </description>
       <arg name="button" type="uint32" summary="button code"/>
       <arg name="state" type="uint32" enum="button_state"/>
@@ -1323,6 +1333,10 @@
 
         It is a protocol violation to send this request for a client
         of an ei_handshake.context_type other than sender.
+
+        A client should send a ei_key.key release event before
+        ei_device.stop_emulating to avoid any ambiguity on interpretation
+        of key events.
       </description>
       <arg name="key" type="uint32" summary="the key code"/>
       <arg name="state" type="uint32" enum="key_state" summary="logical state of the key"/>
@@ -1475,6 +1489,10 @@
 
         It is a protocol violation to send a touch down in the same
         frame as a touch motion or touch up.
+
+        A client should send a ei_touch.up or ei_touch.cancel event before
+        ei_device.stop_emulating to avoid any ambiguity on interpretation of touch
+        events.
       </description>
       <arg name="touchid" type="uint32" summary="a unique touch id to identify this touch"/>
       <arg name="x" type="float" summary="touch x coordinate in logical pixels"/>