From 3a4105dd425ef14577b8e51b81acecb6986eb62d Mon Sep 17 00:00:00 2001
From: kossLAN <kosslan@kosslan.dev>
Date: Sat, 6 Jun 2026 20:05:20 -0400
Subject: [PATCH] add mouse_follows_focus

---
 book/src/configuration/misc.md                | 13 ++++++++++++
 crates/jay-config/src/input.rs                | 14 ++++++++++---
 .../toml-config/src/config/parsers/config.rs  | 15 ++++++++++----
 crates/toml-config/src/lib.rs                 |  5 +----
 crates/toml-spec/spec/spec.generated.json     |  6 +++++-
 crates/toml-spec/spec/spec.generated.md       | 19 ++++++++++++++----
 crates/toml-spec/spec/spec.yaml               | 20 ++++++++++++++-----
 src/ifs/wl_seat.rs                            |  2 +-
 8 files changed, 72 insertions(+), 22 deletions(-)

diff --git a/book/src/configuration/misc.md b/book/src/configuration/misc.md
index 33f0c8ba..75bcf0b1 100644
--- a/book/src/configuration/misc.md
+++ b/book/src/configuration/misc.md
@@ -145,6 +145,19 @@ focus.
 focus-follows-mouse = true  # default
 ```
 
+## Mouse Follows Focus
+
+When enabled, moving focus with keyboard commands centers the pointer on the
+newly focused window.
+
+```toml
+mouse-follows-focus = true  # default
+```
+
+Set it to `false` if you want shortcuts such as `focus-left`, `focus-right`,
+`focus-prev`, `focus-next`, and workspace switching to leave the pointer where
+it is.
+
 ## Window Management Key
 
 Designates a key that, while held, enables window management mode. In this
diff --git a/crates/jay-config/src/input.rs b/crates/jay-config/src/input.rs
index c052bba7..70dbc025 100644
--- a/crates/jay-config/src/input.rs
+++ b/crates/jay-config/src/input.rs
@@ -699,12 +699,20 @@ impl Seat {
     /// Sets whether the cursor should automatically move to the center of a window
     /// when focus changes via keyboard commands (move-left, focus-right, show-workspace, etc.).
     ///
-    /// The default is `false`.
-    #[deprecated = "This setting is unstable and might be removed in the future"]
-    pub fn unstable_set_mouse_follows_focus(self, enabled: bool) {
+    /// The default is `true`.
+    pub fn set_mouse_follows_focus(self, enabled: bool) {
         get!().seat_set_mouse_follows_focus(self, enabled)
     }
 
+    /// Sets whether the cursor should automatically move to the center of a window
+    /// when focus changes via keyboard commands (move-left, focus-right, show-workspace, etc.).
+    ///
+    /// The default is `true`.
+    #[deprecated = "Use `set_mouse_follows_focus` instead"]
+    pub fn unstable_set_mouse_follows_focus(self, enabled: bool) {
+        self.set_mouse_follows_focus(enabled)
+    }
+
     /// Toggles tabbed mode on the focused window's parent container.
     pub fn toggle_tab(self) {
         get!().seat_toggle_tab(self)
diff --git a/crates/toml-config/src/config/parsers/config.rs b/crates/toml-config/src/config/parsers/config.rs
index ed3b1e70..f5aab054 100644
--- a/crates/toml-config/src/config/parsers/config.rs
+++ b/crates/toml-config/src/config/parsers/config.rs
@@ -154,10 +154,10 @@ impl Parser for ConfigParser<'_> {
                 show_titles,
                 fallback_output_mode_val,
                 clean_logs_older_than_val,
-                mouse_follows_focus,
+                unstable_mouse_follows_focus,
                 animations_val,
             ),
-            (scratchpads_val, autotile),
+            (scratchpads_val, autotile, mouse_follows_focus),
         ) = ext.extract((
             (
                 opt(val("keymap")),
@@ -219,7 +219,11 @@ impl Parser for ConfigParser<'_> {
                 recover(opt(bol("unstable-mouse-follows-focus"))),
                 opt(val("animations")),
             ),
-            (opt(val("scratchpads")), recover(opt(bol("autotile")))),
+            (
+                opt(val("scratchpads")),
+                recover(opt(bol("autotile"))),
+                recover(opt(bol("mouse-follows-focus"))),
+            ),
         ))?;
         let mut keymap = None;
         if let Some(value) = keymap_val {
@@ -633,7 +637,10 @@ impl Parser for ConfigParser<'_> {
             workspace_display_order,
             simple_im,
             fallback_output_mode,
-            mouse_follows_focus: mouse_follows_focus.despan(),
+            mouse_follows_focus: mouse_follows_focus
+                .despan()
+                .or_else(|| unstable_mouse_follows_focus.despan())
+                .or(Some(true)),
             scratchpads,
             autotile: autotile.despan(),
         })
diff --git a/crates/toml-config/src/lib.rs b/crates/toml-config/src/lib.rs
index 33bc3343..42c1f04f 100644
--- a/crates/toml-config/src/lib.rs
+++ b/crates/toml-config/src/lib.rs
@@ -1849,10 +1849,7 @@ fn load_config(initial_load: bool, auto_reload: bool, persistent: &Rc<Persistent
         persistent.seat.set_fallback_output_mode(v);
     }
     if let Some(mouse_follows_focus) = config.mouse_follows_focus {
-        #[expect(deprecated)]
-        persistent
-            .seat
-            .unstable_set_mouse_follows_focus(mouse_follows_focus);
+        persistent.seat.set_mouse_follows_focus(mouse_follows_focus);
     }
     if let Some(v) = config.autotile {
         set_autotile(v);
diff --git a/crates/toml-spec/spec/spec.generated.json b/crates/toml-spec/spec/spec.generated.json
index 61312cf6..98c831b5 100644
--- a/crates/toml-spec/spec/spec.generated.json
+++ b/crates/toml-spec/spec/spec.generated.json
@@ -1120,9 +1120,13 @@
           "type": "boolean",
           "description": "Configures whether moving the mouse over a window automatically moves the keyboard\nfocus to that window.\n\nThe default is `true`.\n"
         },
+        "mouse-follows-focus": {
+          "type": "boolean",
+          "description": "Configures whether the mouse cursor is automatically centered on the active window\nwhen focus changes via keyboard commands.\n\nWhen enabled, the cursor will be automatically positioned to the center of the\nactive window when focus changes through keyboard commands such as `focus-left`,\n`focus-right`, `show-workspace`, etc.\n\nThe default is `true`.\n\n- Example:\n\n  ```toml\n  mouse-follows-focus = false\n  ```\n"
+        },
         "unstable-mouse-follows-focus": {
           "type": "boolean",
-          "description": "Configures whether the mouse cursor is automatically centered on the active window\nwhen focus changes via keyboard commands.\n\nWhen enabled, the cursor will be automatically positioned to the center of the\nactive window when focus changes through keyboard commands such as `focus-left`,\n`focus-right`, `show-workspace`, etc.\n\nThe default is `false`.\n\nThis option is unstable due to various issues. It is not subject to the usual\nsemver guarantees.\n\n- Example:\n\n  ```toml\n  unstable-mouse-follows-focus = true\n  ```\n"
+          "description": "Legacy alias for `mouse-follows-focus`.\n\nPrefer `mouse-follows-focus` in new configurations.\n\n- Example:\n\n  ```toml\n  unstable-mouse-follows-focus = true\n  ```\n"
         },
         "window-management-key": {
           "type": "string",
diff --git a/crates/toml-spec/spec/spec.generated.md b/crates/toml-spec/spec/spec.generated.md
index 27a25895..fd307ab2 100644
--- a/crates/toml-spec/spec/spec.generated.md
+++ b/crates/toml-spec/spec/spec.generated.md
@@ -2142,7 +2142,7 @@ The table has the following fields:
 
   The value of this field should be a boolean.
 
-- `unstable-mouse-follows-focus` (optional):
+- `mouse-follows-focus` (optional):
 
   Configures whether the mouse cursor is automatically centered on the active window
   when focus changes via keyboard commands.
@@ -2151,10 +2151,21 @@ The table has the following fields:
   active window when focus changes through keyboard commands such as `focus-left`,
   `focus-right`, `show-workspace`, etc.
 
-  The default is `false`.
+  The default is `true`.
 
-  This option is unstable due to various issues. It is not subject to the usual
-  semver guarantees.
+  - Example:
+
+    ```toml
+    mouse-follows-focus = false
+    ```
+
+  The value of this field should be a boolean.
+
+- `unstable-mouse-follows-focus` (optional):
+
+  Legacy alias for `mouse-follows-focus`.
+
+  Prefer `mouse-follows-focus` in new configurations.
 
   - Example:
 
diff --git a/crates/toml-spec/spec/spec.yaml b/crates/toml-spec/spec/spec.yaml
index 6c3b96dc..51c9d832 100644
--- a/crates/toml-spec/spec/spec.yaml
+++ b/crates/toml-spec/spec/spec.yaml
@@ -2903,7 +2903,7 @@ Config:
         focus to that window.
 
         The default is `true`.
-    unstable-mouse-follows-focus:
+    mouse-follows-focus:
       kind: boolean
       required: false
       description: |
@@ -2914,10 +2914,20 @@ Config:
         active window when focus changes through keyboard commands such as `focus-left`,
         `focus-right`, `show-workspace`, etc.
 
-        The default is `false`.
-        
-        This option is unstable due to various issues. It is not subject to the usual
-        semver guarantees.
+        The default is `true`.
+
+        - Example:
+
+          ```toml
+          mouse-follows-focus = false
+          ```
+    unstable-mouse-follows-focus:
+      kind: boolean
+      required: false
+      description: |
+        Legacy alias for `mouse-follows-focus`.
+
+        Prefer `mouse-follows-focus` in new configurations.
 
         - Example:
 
diff --git a/src/ifs/wl_seat.rs b/src/ifs/wl_seat.rs
index bbf03945..b0a1c3c8 100644
--- a/src/ifs/wl_seat.rs
+++ b/src/ifs/wl_seat.rs
@@ -410,7 +410,7 @@ impl WlSeatGlobal {
             simple_im_enabled: Cell::new(true),
             warp_mouse_to_focus_scheduled: Cell::new(false),
             warp_mouse_to_focus_skip_target_check: Cell::new(false),
-            mouse_follows_focus: Cell::new(false),
+            mouse_follows_focus: Cell::new(true),
             focus_grab: Default::default(),
         });
         slf.pointer_cursor.set_owner(slf.clone());