fix(macos): make moveToBack/moveToFront actually visible (v6.4.4)

`CGSOrderWindow(below)` alone was a no-op when the lowered window's app
was the active app — every active-app window sits above every
inactive-app window on macOS, regardless of within-app z-order. So
pressing Shift+Ctrl+Cmd+Left moved nothing visible.

Fix: after lowering, activate the next app's frontmost window so the
lowered app drops into the inactive layer. Then remember the lowered
PID in a module-local `Mutex<Option<i32>>` so the next moveToFront can
target that PID instead of "currently focused window" (which is now
the app we just activated to push the original behind). The remembered
PID is consumed on first front-call after a back, giving a natural
back/front-pair undo. Falls back to focused window when no memory is
set. Windows/Linux don't need this trick (no active-app grouping).

Default keybinding switched from window-toggle to app-scope so the
visible behavior matches macOS reality:
  Shift+Ctrl+Super+Left  → command/app/moveToBack
  Shift+Ctrl+Super+Right → command/app/moveToFront

Also added `tiling::run_zorder_selftest()` — a debug aid behind
`DISPLAY_DJ_ZORDER_SELFTEST=1` that runs all 6 z-order commands with
state snapshots between steps. Each platform's
`is_focused_window_at_front()` is now `pub(super)` so the shared
self-test can observe live state.

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

Author: synle

CLAUDE.md

@@ -198,7 +198,9 @@ Lives in the `tiling/` module — shares focused-window resolution and AX/Win32/
 - `command/window/moveToBack`, `command/app/moveToBack`
 - `command/window/toggleFrontBack`, `command/app/toggleFrontBack`
 
-**Default keybindings**: `Shift+Ctrl+Super+Left` = window toggle, `Shift+Ctrl+Super+Right` = app toggle (mnemonic: Left = single window, Right = many windows; `Super` = Cmd/Win/Super).
+**Default keybindings**: `Shift+Ctrl+Super+Left` = `command/app/moveToBack`, `Shift+Ctrl+Super+Right` = `command/app/moveToFront` (mnemonic: Left = back/away, Right = front/toward you; `Super` = Cmd/Win/Super). App-scope rather than window-scope so the visible behavior is symmetric on macOS — see "Back" below for why single-window scope can't visibly lower the active app's only window.
+
+**Self-test (debug aid)**: Set `DISPLAY_DJ_ZORDER_SELFTEST=1` before launching. Five seconds after startup, `tiling::run_zorder_selftest()` runs all 6 z-order commands on whatever window is currently focused, with state snapshots between steps. Logs everything with a `[zorder-selftest]` prefix. Off by default — running on every launch would manipulate the user's focused window.
 
 Parsing centralized in `tiling::parse_zorder_command()`; dispatch in `tiling::execute_zorder()` which forwards to platform impls. Dispatched in-process from `tray.rs::execute_command()` on a background thread (no sidecar HTTP), so `build_command_url()` returns `None`.
 
@@ -210,7 +212,7 @@ Parsing centralized in `tiling::parse_zorder_command()`; dispatch in `tiling::ex
 
 ### Back
 
-- **macOS**: no public AX API to lower — uses private `CGSOrderWindow(cid, wid, -1, 0)` (CoreGraphics SkyLight, `kCGSOrderBelow`), the standard approach in yabai/Rectangle/AeroSpace. CGS extern declared next to existing `CGSGetActiveSpace`/`CGSMoveWindowsToManagedSpace` in `tiling/macos.rs`. `move_window_to_back` resolves AX → CGWindowID via `_AXUIElementGetWindow`. `move_app_to_back` iterates AXWindows front-first, lowering each — preserves within-app relative order at the bottom of the stack.
+- **macOS**: no public AX API to lower — uses private `CGSOrderWindow(cid, wid, -1, 0)` (CoreGraphics SkyLight, `kCGSOrderBelow`), the standard approach in yabai/Rectangle/AeroSpace. CGS extern declared next to existing `CGSGetActiveSpace`/`CGSMoveWindowsToManagedSpace` in `tiling/macos.rs`. `move_window_to_back` resolves AX → CGWindowID via `_AXUIElementGetWindow`. `move_app_to_back` iterates AXWindows front-first, lowering each — preserves within-app relative order at the bottom of the stack. **Critical: `CGSOrderWindow` alone is invisible when the lowered window's app is the active app** — every window of the active app sits above every window of every inactive app on macOS, regardless of within-app z-order. After lowering, `activate_next_app_excluding_pid()` activates the frontmost window's PID from `get_all_windows()` whose owner differs from the lowered app, dropping the lowered app into the inactive layer. The lowered PID is then stored in the module-local `LAST_BACKED_PID: Mutex<Option<i32>>` so a subsequent `move_window_to_front` / `move_app_to_front` can bring that PID back even though focus has shifted to the app we activated. The remembered PID is consumed (cleared) on the first front call after a back, giving natural back/front-pair undo semantics; once consumed, front falls back to "currently focused window." Windows and Linux do not need this trick (no active-app grouping at the WM level), so the remembered-PID logic is macOS-only.
 - **Windows**: `SetWindowPos(HWND_BOTTOM, …, SWP_NOACTIVATE)` (Windows transfers focus automatically). App scope iterates HWNDs front-to-back so each `HWND_BOTTOM` drops one window to the absolute bottom.
 - **Linux**: `ConfigureWindow(stack_mode = BELOW)` via `lower_window()` — honored by Mutter/KWin/xfwm4.
 

src-tauri/src/config.rs

@@ -382,17 +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.
+                // Z-order: send all windows of focused app to back / bring
+                // them all to front. Mnemonic: Left = back (away), Right =
+                // front (toward you). 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()),
+                    command: CommandValue::Single("command/app/moveToBack".into()),
                 },
                 KeyBinding {
                     key: "Shift+Ctrl+Super+Right".into(),
-                    command: CommandValue::Single("command/app/toggleFrontBack".into()),
+                    command: CommandValue::Single("command/app/moveToFront".into()),
                 },
             ],
             profiles: vec![

src-tauri/src/lib.rs

@@ -623,6 +623,29 @@ pub fn run() {
                 }
             }
 
+            // Z-order self-test (debug aid — opt-in via env var).
+            // When DISPLAY_DJ_ZORDER_SELFTEST=1, spawn a background thread
+            // that runs `run_zorder_selftest`. The routine sleeps 5s before
+            // doing anything (so the operator has time to focus the window
+            // they want to test), then exercises all 6 z-order commands
+            // with snapshots between steps. Logs everything with a
+            // `[zorder-selftest]` prefix. Defaults OFF — running this on
+            // every launch would be jarring (it manipulates whatever
+            // window is focused).
+            #[cfg(any(target_os = "macos", target_os = "windows", target_os = "linux"))]
+            {
+                if std::env::var("DISPLAY_DJ_ZORDER_SELFTEST")
+                    .ok()
+                    .filter(|v| !v.is_empty() && v != "0")
+                    .is_some()
+                {
+                    let selftest_handle = app.handle().clone();
+                    std::thread::spawn(move || {
+                        tiling::run_zorder_selftest(&selftest_handle);
+                    });
+                }
+            }
+
             // Start night mode schedule checker
             let schedule_handle = app.handle().clone();
             std::thread::spawn(move || {

src-tauri/src/tiling/linux.rs

@@ -852,7 +852,10 @@ pub fn move_app_to_back(_app: &AppHandle) {
 /// `_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 {
+///
+/// `pub(super)` so the shared z-order self-test in `tiling/mod.rs` can read
+/// live front/back state when `DISPLAY_DJ_ZORDER_SELFTEST=1`.
+pub(super) fn is_focused_window_at_front() -> bool {
     let (conn, screen_num) = match connect() {
         Some(c) => c,
         None => return false,

src-tauri/src/tiling/macos.rs

@@ -9,8 +9,37 @@
 //! System Settings > Privacy & Security > Accessibility.
 
 use std::ffi::{c_char, c_void, CString};
+use std::sync::Mutex;
 use tauri::{AppHandle, Manager};
 
+/// Remembers the PID of the app most recently sent to back via
+/// `move_window_to_back` / `move_app_to_back`, so the next
+/// `move_window_to_front` / `move_app_to_front` can target that app instead
+/// of "whatever is currently focused" — which would just be the *other*
+/// app we activated to push the original behind.
+///
+/// Acts as a single-slot LIFO stack: each back overwrites the previous
+/// memory; each front consumes it. If the memory is empty (or the stored
+/// PID is no longer alive / has no visible window), front falls back to the
+/// currently focused window.
+static LAST_BACKED_PID: Mutex<Option<i32>> = Mutex::new(None);
+
+/// Record `pid` as "the app we just sent to back," so a subsequent
+/// move-to-front can bring it back even though focus has shifted to a
+/// different app. Logs at info level.
+fn remember_backed_pid(pid: i32) {
+    if let Ok(mut g) = LAST_BACKED_PID.lock() {
+        *g = Some(pid);
+        log::info!("remember_backed_pid: stored pid={} for next moveToFront", pid);
+    }
+}
+
+/// Take the remembered backed PID, if any. Returns the PID and clears the
+/// memory so the next call after this one falls back to the focused window.
+fn take_backed_pid() -> Option<i32> {
+    LAST_BACKED_PID.lock().ok().and_then(|mut g| g.take())
+}
+
 use super::{
     build_sorted_window_list, calculate_target_rect, find_display_for_window,
     layout_across_displays, plan_expose, plan_expose_app, plan_layout_preset, Rect,
@@ -933,6 +962,25 @@ pub fn move_window_to_front(_app: &AppHandle) {
         log::warn!("move_window_to_front: Accessibility permission not granted");
         return;
     }
+    // If the most recent action was a moveToBack, the focused app is
+    // whatever we activated to push the original app behind — not the
+    // window the user wants to bring forward. Prefer the remembered
+    // "last backed PID" so a back/front pair forms a natural undo.
+    if let Some(remembered_pid) = take_backed_pid() {
+        unsafe {
+            activate_app_by_pid(remembered_pid);
+            // Raise the frontmost AX window of that app so it's the
+            // topmost window within the (now-active) app.
+            if let Some((w, _wid)) = get_all_ax_windows_for_pid(remembered_pid).into_iter().next() {
+                raise_window(&w);
+            }
+        }
+        log::info!(
+            "move_window_to_front: brought back remembered pid={} (was sent to back earlier)",
+            remembered_pid,
+        );
+        return;
+    }
     unsafe {
         let window = match get_focused_window() {
             Some(w) => w,
@@ -941,10 +989,16 @@ pub fn move_window_to_front(_app: &AppHandle) {
                 return;
             }
         };
-        if let Some(pid) = get_window_pid(&window) {
-            activate_app_by_pid(pid);
+        let wid = get_window_id(&window);
+        let pid = get_window_pid(&window);
+        if let Some(p) = pid {
+            activate_app_by_pid(p);
         }
         raise_window(&window);
+        log::info!(
+            "move_window_to_front: dispatched (pid={:?}, wid={:?})",
+            pid, wid,
+        );
     }
 }
 
@@ -962,20 +1016,62 @@ pub fn move_app_to_front(_app: &AppHandle) {
         log::warn!("move_app_to_front: Accessibility permission not granted");
         return;
     }
+    // Same back/front-pair reasoning as `move_window_to_front`: if a
+    // moveToBack just ran, the focused app is the one we activated to
+    // push the original behind. Prefer the remembered PID so all of its
+    // windows come back together.
+    let remembered = take_backed_pid();
     unsafe {
-        let focused = match get_focused_window() {
-            Some(w) => w,
-            None => {
-                log::info!("move_app_to_front: no focused window");
-                return;
-            }
-        };
-        let pid = match get_window_pid(&focused) {
-            Some(p) => p,
-            None => {
-                log::info!("move_app_to_front: could not resolve PID for focused window");
-                return;
+        let (focused, pid) = if let Some(p) = remembered {
+            // Synthesize a "focused window" from the first AX window of
+            // the remembered app. If it has no AX windows, fall through
+            // to the regular focused-window path below.
+            match get_all_ax_windows_for_pid(p).into_iter().next() {
+                Some((w, _wid)) => {
+                    log::info!(
+                        "move_app_to_front: bringing back remembered pid={} (was sent to back earlier)",
+                        p,
+                    );
+                    (w, p)
+                }
+                None => {
+                    log::info!(
+                        "move_app_to_front: remembered pid={} has no AX windows; falling back to focused",
+                        p,
+                    );
+                    let f = match get_focused_window() {
+                        Some(w) => w,
+                        None => {
+                            log::info!("move_app_to_front: no focused window");
+                            return;
+                        }
+                    };
+                    let fp = match get_window_pid(&f) {
+                        Some(fp) => fp,
+                        None => {
+                            log::info!("move_app_to_front: could not resolve PID for focused window");
+                            return;
+                        }
+                    };
+                    (f, fp)
+                }
             }
+        } else {
+            let f = match get_focused_window() {
+                Some(w) => w,
+                None => {
+                    log::info!("move_app_to_front: no focused window");
+                    return;
+                }
+            };
+            let fp = match get_window_pid(&f) {
+                Some(fp) => fp,
+                None => {
+                    log::info!("move_app_to_front: could not resolve PID for focused window");
+                    return;
+                }
+            };
+            (f, fp)
         };
         // Activate with NSApplicationActivateAllWindows so macOS raises every
         // window of the app above other apps' windows.
@@ -998,6 +1094,41 @@ unsafe fn send_window_to_back_by_id(wid: u32) {
     let _ = CGSOrderWindow(cid, wid, -1, 0);
 }
 
+/// Activate the next visible app (any window from a different PID than
+/// `excluded_pid`) so the excluded app loses "active app" status.
+///
+/// On macOS, every window of the active app sits above every window of every
+/// inactive app — that grouping is enforced by the window server. So calling
+/// `CGSOrderWindow(below, 0)` on a window of the *active* app only reorders
+/// it within that app's windows, leaving it visually on top of all other
+/// apps' windows. To genuinely push the user's window behind everything, we
+/// also have to activate a different app, which makes the original app
+/// inactive and drops all its windows below the newly active one.
+///
+/// Picks the frontmost window in the global z-order whose PID differs from
+/// `excluded_pid`. Returns true if an app was activated, false if no other
+/// app has a visible normal-layer window (e.g. only one app is on screen).
+unsafe fn activate_next_app_excluding_pid(excluded_pid: i32) -> bool {
+    // get_all_windows() returns normal-layer (layer 0), on-screen,
+    // non-tiny windows in front-to-back z-order — exactly the candidate
+    // set we want for "what should become active instead".
+    for w in get_all_windows() {
+        if w.owner_pid != excluded_pid && w.owner_pid > 0 {
+            log::info!(
+                "activate_next_app_excluding_pid: activating pid={} ('{}') wid={}",
+                w.owner_pid, w.owner_name, w.window_id,
+            );
+            activate_app_by_pid(w.owner_pid);
+            return true;
+        }
+    }
+    log::info!(
+        "activate_next_app_excluding_pid: no other app with a visible window (excluded_pid={})",
+        excluded_pid,
+    );
+    false
+}
+
 /// Send the focused window to the back of the global z-order.
 ///
 /// There is no public AX API for "lower window," so we use the private
@@ -1026,7 +1157,23 @@ pub fn move_window_to_back(_app: &AppHandle) {
                 return;
             }
         };
+        let pid = get_window_pid(&window).unwrap_or(0);
         send_window_to_back_by_id(wid);
+        // Lowering alone is not visible if this window's app is the active
+        // app on macOS — the active app's windows always sit above every
+        // other app's windows. Activate another app to drop this app
+        // (and its now-lowered window) into the inactive layer.
+        if pid > 0 {
+            activate_next_app_excluding_pid(pid);
+            // Remember which PID we just sent back so a subsequent
+            // moveToFront can bring it back, even though focus has now
+            // shifted to the app we just activated.
+            remember_backed_pid(pid);
+        }
+        log::info!(
+            "move_window_to_back: CGSOrderWindow sent (wid={}, pid={})",
+            wid, pid,
+        );
     }
 }
 
@@ -1062,6 +1209,14 @@ pub fn move_app_to_back(_app: &AppHandle) {
         for (_w, wid) in get_all_ax_windows_for_pid(pid) {
             send_window_to_back_by_id(wid);
         }
+        // Same reasoning as `move_window_to_back`: lowering is invisible
+        // while this app is the active app. Activate another app to push
+        // every window of this app into the inactive layer.
+        activate_next_app_excluding_pid(pid);
+        // Remember which PID we just sent back so a subsequent
+        // moveToFront can bring its windows back.
+        remember_backed_pid(pid);
+        log::info!("move_app_to_back: dispatched (pid={})", pid);
     }
 }
 
@@ -1070,7 +1225,10 @@ pub fn move_app_to_back(_app: &AppHandle) {
 /// `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 {
+///
+/// `pub(super)` so the shared z-order self-test in `tiling/mod.rs` can read
+/// live front/back state when `DISPLAY_DJ_ZORDER_SELFTEST=1`.
+pub(super) 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,