feat: add command/window/toggleFrontBack and command/app/toggleFrontBack

Stateless z-order toggle: if the focused window is the global topmost,
the toggle sends it (or the whole app) to the back; otherwise, it brings
it to the front. The current state is read from the live z-order on
every call — no saved state. Bumps version to 6.4.2 (patch — additive).

- New shared pure helper `tiling::is_window_at_front(focused_id, &z)`
  takes a front-to-back z-ordered list and returns true iff focused_id
  is the first entry. Each platform builds its own front-to-back list
  before calling — keeps the toggle semantic identical across platforms
  and is fully testable without a window server.
  - macOS: CGWindowListCopyWindowInfo (already front-to-back).
  - Windows: EnumWindows filtered by IsWindowVisible +
    should_skip_system_window (Program Manager, TextInputHost, etc.).
  - Linux/X11: _NET_CLIENT_LIST_STACKING reversed to front-to-back,
    filtered to non-hidden normal windows. Falls back to
    _NET_CLIENT_LIST if the WM doesn't expose stacking.

- Default keybindings (added to config.rs default key_bindings):
  - Shift+Ctrl+Super+Left  → command/window/toggleFrontBack
  - Shift+Ctrl+Super+Right → command/app/toggleFrontBack
  Mnemonic: Left = single (one window), Right = many (whole app).
  `Super` = Cmd on macOS, Win on Windows, Super on Linux. Both combos
  are unbound by default in all three OSes. The two existing default-
  count tests in config.rs (26 → 28) are updated.

- Tests: 6 new unit tests — toggleFrontBack parsing for both scopes,
  is_window_at_front pure helper (true / false at non-front /
  missing-id / empty list), and the all-six-actions distinctness check.
  build_command_url tests cover the new commands return None (in-process
  dispatch, not HTTP-routed).

- Tray.rs dispatch is unchanged — the wildcard match on
  command/window/* and command/app/* added in cycle 2 already routes
  any new command through parse_zorder_command, so the toggle variants
  light up automatically.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Author: synle

CLAUDE.md

@@ -382,6 +382,18 @@ impl Default for Preferences {
                     key: "Ctrl+Down".into(),
                     command: CommandValue::Single("command/tile/exposeApp".into()),
                 },
+                // Z-order: toggle focused window front/back.
+                // Mnemonic: Left = single (one window), Right = many (whole app).
+                // Shift+Ctrl+Super (Cmd on macOS, Win on Windows, Super on Linux)
+                // is unbound by default in all three OSes.
+                KeyBinding {
+                    key: "Shift+Ctrl+Super+Left".into(),
+                    command: CommandValue::Single("command/window/toggleFrontBack".into()),
+                },
+                KeyBinding {
+                    key: "Shift+Ctrl+Super+Right".into(),
+                    command: CommandValue::Single("command/app/toggleFrontBack".into()),
+                },
             ],
             profiles: vec![
                 Profile {
@@ -807,7 +819,7 @@ mod tests {
         let prefs = Preferences::default();
         assert!(!prefs.show_individual_displays);
         assert_eq!(prefs.min_brightness, 10);
-        assert_eq!(prefs.key_bindings.len(), 26);
+        assert_eq!(prefs.key_bindings.len(), 28);
     }
 
     #[test]
@@ -1021,7 +1033,7 @@ mod tests {
         let loaded: Preferences =
             serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
         assert_eq!(loaded.min_brightness, 10);
-        assert_eq!(loaded.key_bindings.len(), 26);
+        assert_eq!(loaded.key_bindings.len(), 28);
 
         std::fs::remove_dir_all(&dir).ok();
     }

src-tauri/src/config.rs

@@ -847,6 +847,74 @@ pub fn move_app_to_back(_app: &AppHandle) {
     }
 }
 
+/// Check if the focused window is the global topmost.
+///
+/// `_NET_CLIENT_LIST_STACKING` returns windows in bottom-to-top z-order,
+/// so the LAST entry is topmost. Filter to normal+non-hidden windows
+/// (hidden = minimized in EWMH) before comparing.
+fn is_focused_window_at_front() -> bool {
+    let (conn, screen_num) = match connect() {
+        Some(c) => c,
+        None => return false,
+    };
+    let root = conn.setup().roots[screen_num].root;
+    let focused = match get_focused_window(&conn, root) {
+        Some(w) => w,
+        None => return false,
+    };
+    let stacking_atom = match intern_atom(&conn, "_NET_CLIENT_LIST_STACKING") {
+        Some(a) => a,
+        None => return false,
+    };
+    // Reverse to get front-to-back order, then filter out non-normal /
+    // minimized windows so the comparison reflects what the user sees.
+    let mut front_to_back: Vec<i64> = get_window_list(&conn, root, stacking_atom)
+        .into_iter()
+        .rev()
+        .filter(|&w| is_normal_window(&conn, w) && !is_window_hidden(&conn, w))
+        .map(|w| w as i64)
+        .collect();
+    // If the WM doesn't expose _NET_CLIENT_LIST_STACKING, fall back to
+    // _NET_CLIENT_LIST (mapping order — not z-order, but better than nothing).
+    if front_to_back.is_empty() {
+        if let Some(client_list_atom) = intern_atom(&conn, "_NET_CLIENT_LIST") {
+            front_to_back = get_window_list(&conn, root, client_list_atom)
+                .into_iter()
+                .rev()
+                .filter(|&w| is_normal_window(&conn, w) && !is_window_hidden(&conn, w))
+                .map(|w| w as i64)
+                .collect();
+        }
+    }
+    super::is_window_at_front(focused as i64, &front_to_back)
+}
+
+/// Toggle the focused window's z-order: front if it isn't, back if it is.
+pub fn toggle_window_front_back(app: &AppHandle) {
+    if !is_x11_available() {
+        log::warn!("toggle_window_front_back: X11 not available");
+        return;
+    }
+    if is_focused_window_at_front() {
+        move_window_to_back(app);
+    } else {
+        move_window_to_front(app);
+    }
+}
+
+/// Toggle the focused app's z-order: front if it isn't, back if it is.
+pub fn toggle_app_front_back(app: &AppHandle) {
+    if !is_x11_available() {
+        log::warn!("toggle_app_front_back: X11 not available");
+        return;
+    }
+    if is_focused_window_at_front() {
+        move_app_to_back(app);
+    } else {
+        move_app_to_front(app);
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

src-tauri/src/tiling/linux.rs

@@ -1065,6 +1065,51 @@ pub fn move_app_to_back(_app: &AppHandle) {
     }
 }
 
+/// Check if the focused window is the global topmost window.
+///
+/// `CGWindowListCopyWindowInfo` (via `get_all_windows()`) returns normal
+/// (layer-0) on-screen windows in front-to-back z-order. We compare the
+/// focused window's CGWindowID against the first entry.
+fn is_focused_window_at_front() -> bool {
+    let focused_id = unsafe {
+        match get_focused_window().and_then(|w| get_window_id(&w)) {
+            Some(id) => id as i64,
+            None => return false,
+        }
+    };
+    let z_order: Vec<i64> = get_all_windows().iter().map(|w| w.window_id).collect();
+    super::is_window_at_front(focused_id, &z_order)
+}
+
+/// Toggle: if the focused window is the global topmost, send it to back;
+/// otherwise bring it to front. Stateless — decided per-call from the live
+/// z-order, not from saved state.
+pub fn toggle_window_front_back(app: &AppHandle) {
+    if !unsafe { AXIsProcessTrusted() } {
+        log::warn!("toggle_window_front_back: Accessibility permission not granted");
+        return;
+    }
+    if is_focused_window_at_front() {
+        move_window_to_back(app);
+    } else {
+        move_window_to_front(app);
+    }
+}
+
+/// Toggle: if the focused window is the global topmost, send the whole app
+/// to back; otherwise bring the whole app to front.
+pub fn toggle_app_front_back(app: &AppHandle) {
+    if !unsafe { AXIsProcessTrusted() } {
+        log::warn!("toggle_app_front_back: Accessibility permission not granted");
+        return;
+    }
+    if is_focused_window_at_front() {
+        move_app_to_back(app);
+    } else {
+        move_app_to_front(app);
+    }
+}
+
 /// Set a window rect by PID and CGWindowID. Used by shared plan_* functions.
 fn set_window_rect_by_id(pid: i32, wid: u32, rect: &Rect) {
     unsafe {

src-tauri/src/tiling/macos.rs

@@ -1136,8 +1136,8 @@ pub fn start_tile_snap(app: AppHandle) {
 
 /// Z-order action requested via `command/window/...` or `command/app/...`.
 ///
-/// Two scopes (focused window vs. all windows of focused app) × two directions
-/// (front, back) are exposed. The toggle variant will be added in a later cycle.
+/// Two scopes (focused window vs. all windows of focused app) × three actions
+/// (front, back, toggle).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum WindowZOrderAction {
     /// Raise the focused window above all other windows (across apps).
@@ -1151,25 +1151,45 @@ pub enum WindowZOrderAction {
     WindowToBack,
     /// Lower every window of the focused app below all other apps' windows.
     AppToBack,
+    /// If the focused window is the global topmost → send it to back;
+    /// otherwise → bring it to the front. Stateless (decided per-call from
+    /// the live z-order, not from any saved state).
+    WindowToggleFrontBack,
+    /// If the focused window is the global topmost → send the whole app's
+    /// windows to back; otherwise → bring the whole app to front.
+    AppToggleFrontBack,
 }
 
 /// Parse a z-order command string. Returns `None` if it isn't a z-order command.
 ///
 /// Recognized commands:
-///   - `command/window/moveToFront` → [`WindowZOrderAction::WindowToFront`]
-///   - `command/app/moveToFront`    → [`WindowZOrderAction::AppToFront`]
-///   - `command/window/moveToBack`  → [`WindowZOrderAction::WindowToBack`]
-///   - `command/app/moveToBack`     → [`WindowZOrderAction::AppToBack`]
+///   - `command/window/moveToFront`     → [`WindowZOrderAction::WindowToFront`]
+///   - `command/app/moveToFront`        → [`WindowZOrderAction::AppToFront`]
+///   - `command/window/moveToBack`      → [`WindowZOrderAction::WindowToBack`]
+///   - `command/app/moveToBack`         → [`WindowZOrderAction::AppToBack`]
+///   - `command/window/toggleFrontBack` → [`WindowZOrderAction::WindowToggleFrontBack`]
+///   - `command/app/toggleFrontBack`    → [`WindowZOrderAction::AppToggleFrontBack`]
 pub fn parse_zorder_command(command: &str) -> Option<WindowZOrderAction> {
     match command {
         "command/window/moveToFront" => Some(WindowZOrderAction::WindowToFront),
         "command/app/moveToFront" => Some(WindowZOrderAction::AppToFront),
         "command/window/moveToBack" => Some(WindowZOrderAction::WindowToBack),
         "command/app/moveToBack" => Some(WindowZOrderAction::AppToBack),
+        "command/window/toggleFrontBack" => Some(WindowZOrderAction::WindowToggleFrontBack),
+        "command/app/toggleFrontBack" => Some(WindowZOrderAction::AppToggleFrontBack),
         _ => None,
     }
 }
 
+/// Pure helper: true iff `focused_id` is the first entry in a front-to-back
+/// z-ordered window list. Each platform builds its own front-to-back list
+/// (CGWindowList on macOS, EnumWindows on Windows, reversed
+/// `_NET_CLIENT_LIST_STACKING` on Linux) and calls this helper to keep the
+/// "is at front" semantic identical across platforms.
+pub fn is_window_at_front(focused_id: i64, front_to_back_z_order: &[i64]) -> bool {
+    front_to_back_z_order.first().copied() == Some(focused_id)
+}
+
 /// Execute a z-order action. Dispatches to the active platform implementation.
 /// No-op (with a warning log) on platforms where z-order is not supported.
 pub fn execute_zorder(app: &AppHandle, action: WindowZOrderAction) {
@@ -1226,6 +1246,32 @@ pub fn execute_zorder(app: &AppHandle, action: WindowZOrderAction) {
                 log::warn!("zorder: app/moveToBack not supported on this platform");
             }
         }
+        WindowZOrderAction::WindowToggleFrontBack => {
+            #[cfg(target_os = "macos")]
+            macos::toggle_window_front_back(app);
+            #[cfg(target_os = "windows")]
+            windows::toggle_window_front_back(app);
+            #[cfg(target_os = "linux")]
+            linux::toggle_window_front_back(app);
+            #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
+            {
+                let _ = app;
+                log::warn!("zorder: window/toggleFrontBack not supported on this platform");
+            }
+        }
+        WindowZOrderAction::AppToggleFrontBack => {
+            #[cfg(target_os = "macos")]
+            macos::toggle_app_front_back(app);
+            #[cfg(target_os = "windows")]
+            windows::toggle_app_front_back(app);
+            #[cfg(target_os = "linux")]
+            linux::toggle_app_front_back(app);
+            #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
+            {
+                let _ = app;
+                log::warn!("zorder: app/toggleFrontBack not supported on this platform");
+            }
+        }
     }
 }
 
@@ -2502,16 +2548,72 @@ mod tests {
         assert_eq!(parse_zorder_command("command/window/movetoback"), None);
     }
 
-    /// All four z-order actions are distinct.
+    /// All six z-order actions are distinct.
     #[test]
     fn test_zorder_actions_are_distinct() {
-        let front_window = parse_zorder_command("command/window/moveToFront");
-        let front_app = parse_zorder_command("command/app/moveToFront");
-        let back_window = parse_zorder_command("command/window/moveToBack");
-        let back_app = parse_zorder_command("command/app/moveToBack");
-        assert_ne!(front_window, front_app);
-        assert_ne!(front_window, back_window);
-        assert_ne!(back_window, back_app);
-        assert_ne!(front_app, back_app);
+        let actions = [
+            parse_zorder_command("command/window/moveToFront"),
+            parse_zorder_command("command/app/moveToFront"),
+            parse_zorder_command("command/window/moveToBack"),
+            parse_zorder_command("command/app/moveToBack"),
+            parse_zorder_command("command/window/toggleFrontBack"),
+            parse_zorder_command("command/app/toggleFrontBack"),
+        ];
+        for (i, a) in actions.iter().enumerate() {
+            assert!(a.is_some(), "action {} should parse", i);
+            for (j, b) in actions.iter().enumerate() {
+                if i != j {
+                    assert_ne!(a, b, "actions {} and {} should differ", i, j);
+                }
+            }
+        }
+    }
+
+    /// `command/window/toggleFrontBack` parses to WindowToggleFrontBack.
+    #[test]
+    fn test_parse_zorder_window_toggle() {
+        assert_eq!(
+            parse_zorder_command("command/window/toggleFrontBack"),
+            Some(WindowZOrderAction::WindowToggleFrontBack),
+        );
+    }
+
+    /// `command/app/toggleFrontBack` parses to AppToggleFrontBack.
+    #[test]
+    fn test_parse_zorder_app_toggle() {
+        assert_eq!(
+            parse_zorder_command("command/app/toggleFrontBack"),
+            Some(WindowZOrderAction::AppToggleFrontBack),
+        );
+    }
+
+    /// `is_window_at_front` is true when the window ID is the first in the
+    /// front-to-back z-order list.
+    #[test]
+    fn test_is_window_at_front_true() {
+        let z_order = vec![100, 200, 300];
+        assert!(is_window_at_front(100, &z_order));
+    }
+
+    /// `is_window_at_front` is false when the window is below another in the stack.
+    #[test]
+    fn test_is_window_at_front_false() {
+        let z_order = vec![100, 200, 300];
+        assert!(!is_window_at_front(200, &z_order));
+        assert!(!is_window_at_front(300, &z_order));
+    }
+
+    /// `is_window_at_front` is false when the window is not in the list at all.
+    #[test]
+    fn test_is_window_at_front_missing() {
+        let z_order = vec![100, 200, 300];
+        assert!(!is_window_at_front(999, &z_order));
+    }
+
+    /// `is_window_at_front` is false on an empty list (no windows on screen).
+    #[test]
+    fn test_is_window_at_front_empty() {
+        let z_order: Vec<i64> = Vec::new();
+        assert!(!is_window_at_front(100, &z_order));
     }
 }

src-tauri/src/tiling/mod.rs

@@ -644,6 +644,57 @@ pub fn move_app_to_back(_app: &AppHandle) {
     }
 }
 
+/// Check if the focused window is the global topmost. On Windows the
+/// foreground window is generally the topmost, so this almost always
+/// returns true unless the user's app is covered by a topmost (always-on-top)
+/// system overlay or the focus is on a non-foreground window. Used by the
+/// toggle dispatch.
+fn is_focused_window_at_front() -> bool {
+    let foreground = match get_foreground_hwnd() {
+        Some(h) => h,
+        None => return false,
+    };
+    let foreground_id = foreground.0 as isize as i64;
+    // Build a front-to-back list of visible top-level HWNDs (filtering
+    // skip-list system windows like Program Manager / TextInputHost).
+    let mut z_order: Vec<i64> = Vec::new();
+    unsafe extern "system" fn cb(hwnd: HWND, lparam: LPARAM) -> BOOL {
+        let z = &mut *(lparam.0 as *mut Vec<i64>);
+        if !IsWindowVisible(hwnd).as_bool() {
+            return TRUE;
+        }
+        let process = get_process_name(hwnd);
+        let title = get_window_title(hwnd);
+        if super::should_skip_system_window(&process, &title) {
+            return TRUE;
+        }
+        z.push(hwnd.0 as isize as i64);
+        TRUE
+    }
+    unsafe {
+        let _ = EnumWindows(Some(cb), LPARAM(&mut z_order as *mut Vec<i64> as isize));
+    }
+    super::is_window_at_front(foreground_id, &z_order)
+}
+
+/// Toggle the focused window's z-order: front if it isn't, back if it is.
+pub fn toggle_window_front_back(app: &AppHandle) {
+    if is_focused_window_at_front() {
+        move_window_to_back(app);
+    } else {
+        move_window_to_front(app);
+    }
+}
+
+/// Toggle the focused app's z-order: front if it isn't, back if it is.
+pub fn toggle_app_front_back(app: &AppHandle) {
+    if is_focused_window_at_front() {
+        move_app_to_back(app);
+    } else {
+        move_app_to_front(app);
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------