Focus-follows-mouse: implementation proposal addressing design questions

[EdenRochmanSharabi]

Context

I'd like to propose an implementation for focus-follows-mouse (#12). Before opening a PR, I want to address the design questions raised by @nikitabobko and get feedback.

Addressing the open questions

1. How should users be able to access the menu bar?

The macOS menu bar does not steal window focus when the mouse moves over it — this is built-in macOS behavior. So focus-follows-mouse can coexist with the menu bar without special handling.

For users who want extra safety, a future enhancement could add a modifier key (like yabai's mouse_modifier) that temporarily disables FFM when held. But this is not needed for an initial implementation.

2. If the cursor is within the previously focused window after a keybinding focus change, should it refocus?

Yes — any mouse movement triggers a re-evaluation of which window should be focused. This is consistent with i3/sway behavior.

Users who want the cursor to follow keyboard focus can combine it with the existing on-focus-changed callback:

on-focus-changed = ['move-mouse window-lazy-center']

This moves the cursor to the center of the newly focused window, avoiding the re-focus issue entirely.

3. How should floating windows be handled?

CGWindowListCopyWindowInfo returns windows in z-order (front-to-back). By iterating in this order, floating windows that are visually on top are checked first. This naturally prioritizes the topmost window under the cursor.

Proposed implementation

• New config option: focus-follows-mouse = true (default: false)
• Subscribe to NSEvent.addGlobalMonitorForEvents(matching: .mouseMoved)
• 50ms debounce via cancellable Task to avoid excessive focus changes
• Skip focus changes while left mouse button is held (drag operations)
• Use CGWindowListCopyWindowInfo for fast bounds lookup with z-order
• Reinstall monitor on config reload

Inspired by @Dadams2's implementation in #12.

Happy to hear feedback before I open a PR.