How Atmos Detects and Maps Cursor States

One of the reasons Atmos cursor skins feel more native than a simple overlay is that they are not static. The app does not just draw one pointer image all the time. It tries to follow the cursor state that macOS is currently using.

That means Atmos needs to detect when the system cursor changes from an arrow to text, from text to a resize handle, or from a pointer to a crosshair. This guide explains how that mapping works.

Cursor skins are state-based, not single-image overlays

Atmos defines a set of cursor states that custom skins can respond to. These include:

• arrow
• text cursor
• crosshair
• pointing hand
• blocked cursor
• horizontal and vertical resize states
• diagonal resize states
• move
• a few less common states like help, pen, pin, wait, and app starting

This is why a cursor skin can feel contextual instead of decorative. Atmos is constantly deciding which state should be shown, then pulling the matching image or animation from the active skin bundle.

Atmos maps real system cursors to its own state list

The core detection model is based on mapping real NSCursor objects to Atmos cursor states.

Atmos builds a lookup table of known system cursors and the state each one should correspond to. That includes obvious mappings like:

• arrow to arrow
• I-beam to text
• pointing hand to pointer
• crosshair to crosshair
• operation not allowed to blocked

It also maps interaction cursors like open-hand and closed-hand into the move state so cursor skins still behave sensibly during drag-like interactions.

Resize support covers both older and newer macOS cursor APIs

Resize cursors are more complicated than they look because Apple’s APIs changed over time.

Atmos explicitly supports:

• legacy resize cursors used on older macOS versions
• newer frame-resize cursors on modern macOS
• row and column resize cursors used for dividers and edges

That matters because window resizing and divider dragging are some of the easiest places for a custom cursor system to feel incomplete. Atmos covers both generations of cursor APIs so resize states keep working across more versions of macOS.

Diagonal resizes are normalized into stable skin states

Atmos does not need a separate asset for every possible system cursor object. Instead, it normalizes multiple low-level cursor variations into a smaller set of stable skin states.

For example, different top-left, bottom-right, top-right, and bottom-left frame-resize positions are mapped into the two diagonal resize families:

• northwest-southeast
• northeast-southwest

That gives skin authors a manageable set of states while still letting the app respond correctly to real macOS resize behavior.

Detection is cached so the engine is not doing full work every tick

Cursor state detection runs inside the cursor engine, so it has to be efficient.

Atmos keeps track of the last cursor object it saw. If the current system cursor object has not changed, the engine reuses the last detected state instead of re-running the full mapping logic again.

That is a small hidden optimization, but it matters. Cursor rendering is already doing real-time work, so avoiding unnecessary detection churn helps keep the feature smooth.

Unknown cursor objects fall back to hotspot heuristics

Not every system cursor will match the known lookup table exactly. Some private or special-purpose system cursors use different pixel data even when they behave like familiar cursor categories.

When fingerprint matching fails, Atmos does not immediately give up. It falls back to a hotspot-based heuristic.

In practice, that means it looks at the cursor image size and hotspot position. If the hotspot is close to the center, Atmos treats the cursor like a crosshair-style state. Otherwise, it falls back to the standard arrow state.

This is especially useful for system-managed tools like screenshot-style crosshairs and other private cursor objects that still follow familiar hotspot conventions.

Some states are especially important for uploads

Atmos also distinguishes between the full internal state list and the smaller set of states that are actually worth uploading custom art for.

That keeps custom cursor pack creation more practical. Instead of forcing creators to design assets for every obscure cursor state, the app focuses uploads around the states that users actually encounter most often:

• arrow
• text
• crosshair
• pointer
• blocked
• resize directions
• move

This is a good example of Atmos balancing completeness with usability. The engine can understand more states than most people need to customize manually.

Smart positioning works on top of state detection

Once Atmos knows the current state, it still has to place the custom cursor correctly. That is where hotspot resolution comes in.

Each cursor state has a default hotspot expectation, but if Smart Positioning is enabled, Atmos analyzes the visible pixels of the state image and estimates a better hotspot automatically.

This means state detection and hotspot positioning are separate layers:

• first Atmos figures out what kind of cursor the system is showing
• then it figures out where the click point of the custom image should be

That separation is part of why custom skins can stay usable even when their art style differs a lot from the system default.

Hidden behaviors worth knowing

There are a few subtle details here that are easy to miss:

• open-hand and closed-hand are both treated as move-style states
• newer frame-resize cursors are normalized into the same state family as older resize cursors
• unknown cursor objects still get a best-effort mapping instead of failing completely
• the engine caches the last detected cursor object to avoid repeated work
• private system cursors can still map correctly through hotspot heuristics

These behaviors help Atmos feel more complete in everyday macOS use, not just in the most common arrow and text cases.

What this means in practice

When you move through text fields, buttons, draggable areas, resize edges, or screenshot-style interfaces, Atmos is continuously trying to interpret the system cursor state and swap to the best matching skin asset.

That is why a good cursor skin in Atmos can feel responsive instead of cosmetic. The app is not just replacing the look of the arrow. It is actively tracking the cursor language that macOS is using and translating that into the custom skin system.