Merge pull request #77 from JRufer/claude/mint-21-keybind-detection-v01u8t

Deliver hotkeys on Mint, and stop offering gestures that cannot work

Author: JRufer

Cargo.lock

@@ -44,15 +44,18 @@ mod linux {
 
     pub struct DictationInterface {
         pub state: Arc<Mutex<AppState>>,
-        /// Channels to send control commands back to the app coordinator
-        pub start_tx: tokio::sync::mpsc::Sender<()>,
+        /// Channels to send control commands back to the app coordinator. The
+        /// start channel carries the id of the binding that asked for it, so a
+        /// desktop shortcut can dictate into that binding's own targets. Empty
+        /// means "whichever binding the app would use by default".
+        pub start_tx: tokio::sync::mpsc::Sender<String>,
         pub stop_tx: tokio::sync::mpsc::Sender<()>,
     }
 
     #[interface(name = "ai.voxctrl.Dictation")]
     impl DictationInterface {
         async fn start_recording(&self) -> zbus::fdo::Result<()> {
-            let _ = self.start_tx.send(()).await;
+            let _ = self.start_tx.send(String::new()).await;
             Ok(())
         }
 
@@ -62,16 +65,17 @@ mod linux {
         }
 
         async fn toggle_recording(&self) -> zbus::fdo::Result<()> {
-            let status = {
-                let guard = self.state.lock().await;
-                guard.status.clone()
-            };
-            if status == DictationStatus::Recording {
-                let _ = self.stop_tx.send(()).await;
-            } else {
-                let _ = self.start_tx.send(()).await;
-            }
-            Ok(())
+            self.toggle(String::new()).await
+        }
+
+        /// Toggle dictation for one specific binding.
+        ///
+        /// This is what a Cinnamon/MATE native shortcut calls: the desktop owns
+        /// the key grab there, so the only way VoxCtrl learns *which* of the
+        /// user's bindings fired — and therefore which targets the text goes to
+        /// — is for the shortcut to name it.
+        async fn toggle_binding(&self, binding_id: String) -> zbus::fdo::Result<()> {
+            self.toggle(binding_id).await
         }
 
         async fn get_status(&self) -> zbus::fdo::Result<String> {
@@ -91,9 +95,25 @@ mod linux {
         async fn text_injected(ctx: &SignalContext<'_>, text: &str) -> zbus::Result<()>;
     }
 
+    impl DictationInterface {
+        /// Start `binding_id` if idle, stop whatever is running if not.
+        async fn toggle(&self, binding_id: String) -> zbus::fdo::Result<()> {
+            let status = {
+                let guard = self.state.lock().await;
+                guard.status.clone()
+            };
+            if status == DictationStatus::Recording {
+                let _ = self.stop_tx.send(()).await;
+            } else {
+                let _ = self.start_tx.send(binding_id).await;
+            }
+            Ok(())
+        }
+    }
+
     pub async fn start_service(
         state: Arc<Mutex<AppState>>,
-        start_tx: tokio::sync::mpsc::Sender<()>,
+        start_tx: tokio::sync::mpsc::Sender<String>,
         stop_tx: tokio::sync::mpsc::Sender<()>,
     ) -> Result<Connection> {
         let iface = DictationInterface {
@@ -141,7 +161,7 @@ pub use linux::{emit_status_changed, emit_text_injected, start_service};
 #[cfg(not(target_os = "linux"))]
 pub async fn start_service(
     _state: Arc<Mutex<AppState>>,
-    _start_tx: tokio::sync::mpsc::Sender<()>,
+    _start_tx: tokio::sync::mpsc::Sender<String>,
     _stop_tx: tokio::sync::mpsc::Sender<()>,
 ) -> Result<()> {
     tracing::warn!("DBus service not available on this platform");

crates/voxctrl-dbus/src/lib.rs

@@ -16,6 +16,10 @@ crossbeam-channel = { workspace = true }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 evdev = "0.12"
+# X11 raw key events (XInput2): global shortcuts on the X11 desktops that serve
+# no portal, with no permission setup. Pure Rust, so the AppImage needs no
+# libX11 from the host.
+x11rb = { version = "0.13", features = ["xinput"] }
 # The XDG GlobalShortcuts portal: the compositor owns the key grab, so VoxCtrl
 # receives its own shortcuts and never reads a keyboard device.
 ashpd = { workspace = true }

crates/voxctrl-hotkeys/Cargo.toml

@@ -14,6 +14,8 @@ use std::sync::{
     Mutex,
 };
 
+use voxctrl_routing::GestureType;
+
 /// Which mechanism is delivering shortcuts.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
 #[serde(rename_all = "snake_case")]
@@ -23,6 +25,13 @@ pub enum Backend {
     /// `org.freedesktop.portal.GlobalShortcuts` — the compositor owns the key
     /// grab and VoxCtrl reads no input devices.
     Portal,
+    /// X11 raw key events (XInput2). Needs no permissions, and sees every
+    /// press and release, so every gesture style works.
+    X11,
+    /// A native Cinnamon/MATE custom shortcut that pokes VoxCtrl over D-Bus.
+    /// The desktop runs a command on key-press and never reports the release,
+    /// so this can only ever serve `toggle`.
+    MintDbus,
     /// Reading `/dev/input/event*` directly. Only reachable when the user has
     /// already granted this process access to input devices.
     Evdev,
@@ -32,6 +41,45 @@ pub enum Backend {
     None,
 }
 
+/// Gesture styles a backend that only learns about key *presses* can serve.
+///
+/// A desktop that runs a command on key-down tells VoxCtrl nothing on key-up,
+/// so there is no release to end a hold with and no way to tell a tap from a
+/// hold. Only `toggle` survives that.
+const PRESS_ONLY_GESTURES: &[GestureType] = &[GestureType::Toggle];
+
+/// Every gesture style, for the backends that see raw presses and releases.
+const ALL_GESTURES: &[GestureType] = &[
+    GestureType::Hold,
+    GestureType::Toggle,
+    GestureType::DoubleTap,
+    GestureType::DoubleTapHold,
+];
+
+impl Backend {
+    /// Gesture styles this backend can actually deliver.
+    ///
+    /// The settings UI offers exactly these, so a user is never given a choice
+    /// that silently does nothing on their desktop.
+    pub fn gestures(self) -> &'static [GestureType] {
+        match self {
+            Self::MintDbus => PRESS_ONLY_GESTURES,
+            // `Starting` and `None` are not verdicts about what this machine can
+            // do — one has not finished deciding and the other is broken in a
+            // way the setup window explains properly. Narrowing the choices on
+            // either would hide gestures that do work here.
+            Self::Portal | Self::X11 | Self::Evdev | Self::WindowsHook | Self::Starting
+            | Self::None => ALL_GESTURES,
+        }
+    }
+
+    /// True when VoxCtrl watches the key stream itself, so a trigger need not be
+    /// expressible as a desktop accelerator — bare modifiers included.
+    pub fn sees_raw_keys(self) -> bool {
+        matches!(self, Self::X11 | Self::Evdev | Self::WindowsHook)
+    }
+}
+
 /// One shortcut as the compositor actually bound it.
 #[derive(Debug, Clone, serde::Serialize)]
 pub struct BoundShortcut {
@@ -56,6 +104,10 @@ pub struct ListenerHealth {
     backend: Mutex<Option<Backend>>,
     /// Why the portal could not be used, if it could not.
     portal_error: Mutex<Option<String>>,
+    /// Why the X11 backend could not be used, if it could not. Separate from
+    /// the portal's reason: "no shortcuts portal" and "not an X11 session" are
+    /// different facts and a user on Wayland-Cinnamon needs both.
+    x11_error: Mutex<Option<String>>,
     /// The portal is present and answered, but refused the session. A different
     /// problem from "this desktop has no portal", and it needs different advice.
     portal_refused: AtomicBool,
@@ -110,6 +162,17 @@ impl ListenerHealth {
         self.portal_refused.load(Ordering::Relaxed)
     }
 
+    /// Why the X11 backend was not used. `None` means it was, or was never
+    /// reached because something better answered first.
+    pub fn x11_error(&self) -> Option<String> {
+        self.x11_error.lock().ok().and_then(|e| e.clone())
+    }
+
+    /// Gesture styles the running backend can deliver.
+    pub fn gestures(&self) -> &'static [GestureType] {
+        self.backend().gestures()
+    }
+
     pub fn bound_shortcuts(&self) -> Vec<BoundShortcut> {
         self.bound_shortcuts.lock().map(|s| s.clone()).unwrap_or_default()
     }
@@ -120,7 +183,7 @@ impl ListenerHealth {
             return true;
         }
         match self.backend() {
-            Backend::Portal | Backend::WindowsHook => true,
+            Backend::Portal | Backend::WindowsHook | Backend::X11 | Backend::MintDbus => true,
             Backend::Evdev => self.keyboards_open() > 0,
             // Still deciding which backend to use — don't report a problem yet.
             Backend::Starting => true,
@@ -137,7 +200,10 @@ impl ListenerHealth {
 
     /// Shortcuts are working without VoxCtrl having any access to input devices.
     pub fn is_private(&self) -> bool {
-        matches!(self.backend(), Backend::Portal | Backend::WindowsHook)
+        matches!(
+            self.backend(),
+            Backend::Portal | Backend::WindowsHook | Backend::MintDbus
+        )
     }
 
     pub fn set_supported(&self, supported: bool) {
@@ -162,6 +228,12 @@ impl ListenerHealth {
         }
     }
 
+    pub fn set_x11_error(&self, error: String) {
+        if let Ok(mut e) = self.x11_error.lock() {
+            *e = Some(error);
+        }
+    }
+
     pub fn set_portal_refused(&self, refused: bool) {
         self.portal_refused.store(refused, Ordering::Relaxed);
     }
@@ -302,4 +374,57 @@ mod tests {
         assert!(!h.is_active());
         assert!(h.bound_shortcuts().is_empty());
     }
+
+    #[test]
+    fn the_x11_backend_is_active_and_serves_every_gesture() {
+        let h = ListenerHealth::default();
+        h.set_supported(true);
+        h.set_portal_error("no such interface".to_string());
+        h.set_backend(Backend::X11);
+
+        assert!(h.is_active());
+        assert!(!h.is_private(), "raw X11 key events are every keystroke");
+        assert!(
+            !h.permission_blocked(),
+            "X11 raw events need no device permission, so nothing is blocked"
+        );
+        assert_eq!(h.gestures().len(), 4);
+        assert!(h.backend().sees_raw_keys());
+    }
+
+    #[test]
+    fn a_press_only_backend_advertises_toggle_and_nothing_else() {
+        // A Cinnamon custom shortcut runs a command on key-down and reports no
+        // release: a hold has no end and a tap cannot be told from a hold. The
+        // settings UI offers exactly what this returns, so getting it wrong
+        // means offering a gesture that silently does nothing.
+        let h = ListenerHealth::default();
+        h.set_supported(true);
+        h.set_backend(Backend::MintDbus);
+
+        assert_eq!(h.gestures(), &[GestureType::Toggle]);
+        assert!(h.is_active());
+        assert!(h.is_private(), "the desktop holds the grab, VoxCtrl reads nothing");
+        assert!(
+            !h.backend().sees_raw_keys(),
+            "a bare modifier cannot be registered as a desktop accelerator"
+        );
+    }
+
+    #[test]
+    fn a_backend_that_watches_keys_itself_never_hides_a_gesture() {
+        // Hiding a style on these would take away something that works.
+        for backend in [Backend::X11, Backend::Evdev, Backend::WindowsHook, Backend::Portal] {
+            assert_eq!(backend.gestures().len(), 4, "{backend:?} lost a gesture");
+        }
+    }
+
+    #[test]
+    fn an_undecided_or_broken_backend_still_offers_every_gesture() {
+        // Neither is a verdict about what this machine can do, and an empty
+        // gesture list would leave the settings UI with nothing to show.
+        for backend in [Backend::Starting, Backend::None] {
+            assert_eq!(backend.gestures().len(), 4, "{backend:?} narrowed the choices");
+        }
+    }
 }

crates/voxctrl-hotkeys/src/health.rs

@@ -7,6 +7,8 @@ pub mod trigger;
 mod linux;
 #[cfg(target_os = "linux")]
 pub mod portal;
+#[cfg(target_os = "linux")]
+mod x11;
 #[cfg(target_os = "windows")]
 mod windows;
 
@@ -34,11 +36,12 @@ pub fn channel() -> (GestureSender, GestureReceiver) {
 /// the returned handle.
 ///
 /// On Linux this prefers the XDG desktop portal, where the compositor owns the
-/// key grab and VoxCtrl is told nothing except that its own shortcut fired. The
-/// evdev fallback is only used when the portal is unavailable *and* the user
-/// has already given this process access to input devices — VoxCtrl never asks
-/// for that access, because granting it lets every program running as the user
-/// read the keyboard, not just this one.
+/// key grab and VoxCtrl is told nothing except that its own shortcut fired.
+/// Failing that it reads X11 raw key events, which any X client may ask for and
+/// which need no setup. The evdev fallback is only used when neither is
+/// available *and* the user has already given this process access to input
+/// devices — VoxCtrl never asks for that access, because granting it lets every
+/// program running as the user read the keyboard, not just this one.
 ///
 /// `ListenerHandle::health` reports which of those happened, so the app can say
 /// so at launch instead of failing silently.