How Atmos Positions and Restores the Main Window

Atmos does not behave like a normal macOS app window. It is a floating, menu-bar-driven panel that can be shown, hidden, dragged freely, and even pushed partly off-screen.

That means the app needs custom logic for positioning, restoring, and dragging the main window. This guide explains how that system works.

Atmos treats the main panel like a floating utility surface

Instead of relying on a standard document-window setup, Atmos configures its main panel as a borderless floating window with a custom appearance and behavior.

That lets the app do a few things a normal window would not handle as gracefully:

• appear and disappear from the menu bar
• stay visually compact
• move freely without a title bar
• allow partial off-screen placement
• behave more like a controllable desktop utility than a regular app window

This is why the Atmos panel feels different from a typical Mac app the moment you use it.

The window starts hidden and is shown on demand

On startup, the main window is configured but not immediately presented as a normal foreground window. Atmos starts it hidden and ignores mouse events until the menu bar flow explicitly shows it.

When the app decides to show the panel, it posts a show notification and passes along a saved frame if one exists. The window is then promoted, activated, made interactive again, and faded into view.

That is part of what makes the menu bar interaction feel clean. The window is not just sitting there waiting in plain sight. It is being explicitly summoned.

Atmos saves the exact window frame before hiding

When the panel hides, Atmos captures the full window frame and stores it so it can restore that exact position later.

This is an important detail. It is not just saving a rough location or a centered state. It preserves the precise frame, which means the panel can come back where the user last left it.

That saved frame is reused the next time the panel is shown, unless there is no valid saved position. In that fallback case, Atmos centers the window.

The panel uses manual dragging instead of normal window dragging

Atmos does not rely on isMovableByWindowBackground for dragging. Instead, it tracks mouse down, drag, and mouse up events itself and moves the window with direct frame updates.

The reason is subtle but important. Some Atmos sub-screens include native AppKit controls like switches and sliders, and those can interfere with normal server-side background dragging behavior.

By using manual drag logic, Atmos avoids that fragility and keeps the panel draggable even after moving through more complex UI states.

This is one of the app's hidden stability features. The dragging system is custom because the default macOS behavior was not reliable enough for this layout.

Atmos allows full off-screen movement

The panel is also configured to bypass the normal macOS frame constraints that usually stop windows from moving too far off-screen.

Atmos does this intentionally so the window can slide partly or fully beyond the normal top or bottom bounds of the visible screen area.

That is not accidental looseness. It is part of the product behavior. The app wants the panel to feel more fluid and dismissible than a standard fixed utility window.

Bottom-edge hiding has a special stub behavior

If you drag the Atmos window mostly off the bottom of the screen, the app snaps it so a small visible stub remains.

This is a useful hidden interaction. Instead of completely losing the panel, Atmos leaves just enough visible area to suggest that the window is still there and can be restored.

The app decides this using a threshold based on how much of the window has moved off-screen. If more than roughly half the height is pushed below the visible area, Atmos snaps it into that stub-hidden position.

Clicking it can restore it back to the center

When the panel is in that bottom-edge hidden state, Atmos has restore logic that brings it back toward the center of the screen.

This happens when the app detects interaction with the visible panel area and recognizes that the window is effectively in a stub-hidden state. It then animates the window back into a centered position inside the visible frame.

That means the off-screen behavior is not just about hiding. It also has a recovery path designed to keep the window easy to bring back.

The window is animated in both directions

Atmos uses short animation timings for both hiding and showing the panel:

• fade out when hiding
• fade in when showing
• smooth motion when snapping or restoring position

Those transitions are a small but important piece of polish. The panel feels intentional because it moves like a controlled UI surface, not like a raw AppKit window being abruptly reordered.

Global and local mouse handling both shape the experience

Atmos uses both global and local mouse monitoring around the main window.

This helps it support behaviors like:

• reactivating when clicked while visible
• collapsing state when clicked outside
• tracking drag origin correctly
• distinguishing long press from drag
• avoiding accidental button activation after long press

This is another example of the app being more window-manager-like than a normal single-view app.

Hidden behaviors worth knowing

There are several easy-to-miss details in the window system:

• the main panel is configured once and then reused across SwiftUI view recreation
• the window frame is saved before hide so later show actions can restore it exactly
• dragging uses direct frame movement instead of default window background drag
• macOS frame constraints are intentionally bypassed
• bottom-edge hiding keeps a small stub visible rather than losing the window completely
• restoring from that hidden edge state is animated and recenters the panel

These are not headline features, but they shape how Atmos feels every time you open or move the window.

What this means in practice

When Atmos feels easy to summon, easy to move, and hard to lose, that is coming from this custom window logic. The app is not relying on standard macOS window behavior alone. It is actively managing position, visibility, drag handling, and restoration to make the main panel feel lightweight and forgiving.

That is a big part of why the Atmos window feels more like a refined desktop control surface than a traditional app frame.