Warp the mouse cursor from the edge of one screen to the edge of another screen to simulate external monitors being placed side by side.

This is most useful for PaperWM.spoon, which need to arrange screens vertically to avoid off-screen windows overlapping with adjacent screens.

In the MacOS display settings, arrange the screens vertically. WarpMouse.spoon will transform the direction of screens from vertical (top to bottom) to horizontal (left to right).

In the above example, screen 1 will be to the left of screen 2 and screen 3 will be to the right of screen 2.

When you move the mouse to the left edge of screen 2, the cursor will warp to the right edge of screen 1. When you move the mouse to the right edge of screen 2, the cursor will warp to the left edge of screen 3. The cursor will not be warped when the mouse is moved to an edge at an end display (eg the left edge of screen 1 or the right edge of screen 3).

You can also drag floating windows to a new screen through a warped edge.

You can still move the mouse between screens through the top and bottom edges. PaperWM needs to be able to drag windows between screens when using the hotkey to move a window to a new space.

WarpMouse.spoon will hot reload it's screen arangement without intervention when a screen is added / removed or the layout in the display settings is changed.

Example Hammerspoon config:

WarpMouse = hs.loadSpoon("WarpMouse")
WarpMouse.margin = 8  -- optionally set how far past a screen edge the mouse should warp, default is 2 pixels
WarpMouse:start()