How Atmos Handles Multi-Monitor Cursor and Overlay Layouts

If you use Atmos with more than one display, you are interacting with one of the app's more technical layers. Atmos is not just drawing inside a normal window. It creates separate overlay systems for cursor skins, widgets, and wallpapers, and each of those systems handles multi-monitor layouts a little differently.

This guide explains what actually happens across multiple screens and why.

Not every Atmos layer uses the same screen model

One of the most important hidden details in Atmos is that its desktop-facing systems do not all target displays in the same way.

In practice:

• cursor skins span the full union of all connected screens
• widgets are currently built against the main screen
• wallpapers are also built from the current main screen

That is not inconsistency by accident. Each system has a different job, different coordinate needs, and different tradeoffs.

Cursor skins use one overlay that spans every monitor

Cursor skins need to follow the pointer anywhere it goes. Because of that, Atmos creates a borderless overlay window that spans the union of all connected screens, not just a single display.

This means the custom cursor canvas is built large enough to cover the entire multi-monitor layout as one continuous surface. Atmos then positions the rendered cursor inside that larger coordinate space by subtracting the overlay window origin from the real mouse location.

That is why the custom cursor can travel cleanly between displays instead of disappearing when the pointer crosses a screen boundary.

The cursor overlay rebuilds when monitor layouts change

Multi-monitor layouts are not static. Users connect displays, disconnect them, change arrangement order, and swap resolution or scaling.

Atmos listens for screen-parameter changes and rebuilds the cursor overlay when that happens. Instead of trying to stretch the existing overlay into a new layout, it tears it down and recreates it using the new union of all screen frames.

This is an important hidden behavior because it makes the cursor system more robust during dock and undock workflows.

Widgets currently use the main screen as their reference frame

Widgets work differently. The widget overlay is built from NSScreen.main, and the engine stores that screen's frame origin and size as the coordinate system for widget placement and hit testing.

That means widget positions are normalized relative to the main screen rather than the full multi-monitor union.

This is why widgets behave more like a desktop layer for the current primary display than a global wall spanning every monitor.

Widget drag and hit testing depend on screen origin and size

When widget edit mode is active, Atmos converts real mouse locations into overlay coordinates using the current screen origin and screen size.

That conversion is what lets the engine:

• decide which widget body was clicked
• determine whether the user hit delete, resize, or drag zones
• update drag offsets correctly
• map normalized saved positions back into real on-screen placement

Because that math is tied to the main screen frame, the widget system stays coherent within that screen's desktop space.

Wallpapers also use the current main screen

Wallpaper handling is closer to widgets than cursor skins. Atmos creates a desktop-level borderless window using the current main screen, sizes it to that frame, and positions it at that screen origin.

Then it places either:

• an image view for still backgrounds
• or a looping video layer for motion backgrounds

So while the cursor system is deliberately global across monitors, the wallpaper system is screen-specific around the active main display frame it was built from.

Why the systems differ

It helps to think about the underlying requirement of each feature:

• cursor skins must follow the pointer everywhere
• widgets need stable placement and edit interaction
• wallpapers need to behave like a desktop surface tied to a screen frame

Those are different problems. A full-screen union model makes sense for cursors, but for widgets and wallpapers it can introduce more complexity around placement, interaction, and expectations.

So Atmos uses the strategy that best fits each feature instead of forcing all desktop systems into a single coordinate model.

Screen origin matters more than most people realize

On multi-monitor systems, not every screen starts at (0, 0). Displays can sit to the left, right, above, or below one another, and their coordinate origins shift accordingly.

Atmos takes that seriously in its overlay math. For cursor skins, it uses the overlay window's frame origin when converting global mouse location into local draw coordinates. For widgets, it stores the main screen origin and converts mouse input into overlay space relative to that origin.

This is one of those implementation details that users never see directly, but without it the overlays would drift or become misaligned on real multi-monitor setups.

Hidden behaviors worth knowing

There are a few subtle behaviors here that are especially useful to understand:

• cursor skins are the most global desktop layer in Atmos
• widgets are tied to the main screen's frame, not the full display union
• wallpapers are also created from the main screen frame
• monitor arrangement changes trigger overlay rebuilding instead of in-place stretching
• coordinate conversion depends on screen origin, not just width and height

These details explain why different Atmos features can feel global or screen-local depending on what you are using.

What this means in practice

If you use Atmos across multiple displays, cursor skins are designed to follow you everywhere. Widgets and wallpapers, by contrast, are more tightly anchored to the main screen context they were built from.

That is not a bug in itself. It reflects how each system is designed. Atmos gives the cursor layer the broadest multi-monitor coverage, while keeping widgets and wallpapers tied to a more stable per-screen desktop frame.

Understanding that distinction makes a lot of the app's desktop behavior easier to predict.