How Vorssaint Uses macOS Accessibility APIs for Programmatic Window Positioning

Vorssaint relies on the native macOS Accessibility (AX) framework, Core Graphics window identifiers, and AppKit screen geometry to programmatically move, resize, and animate windows via system-level attribute manipulation.

The open-source utility vorssaint/vorssaint-utils implements advanced window management by directly interfacing with macOS system APIs rather than using high-level scripting. Its programmatic window positioning logic centers on the Accessibility framework, which grants low-level access to UI elements through AXUIElement references. The implementation is concentrated in the WindowMaximizer service, with supplemental support from window layout and switcher modules that reuse the same primitive AX operations.

Core macOS Accessibility Framework

Vorssaint’s window positioning engine is built on the Accessibility (AX) framework, a private-user-interface bridge that allows assistive technologies to inspect and control applications. The code manipulates window geometry through a six-step workflow that combines element discovery, attribute validation, and value mutation.

Locating Target Windows

To begin repositioning, Vorssaint must first obtain a reference to the window’s underlying UI element. The system calls AXUIElementCopyElementAtPosition on the system-wide accessibility element to retrieve an AXUIElement representing the window under the cursor or at a specified coordinate. This element acts as the handle for all subsequent positioning operations.

Reading Frame Attributes

Once the window element is acquired, Vorssaint reads its current geometry using AXUIElementCopyAttributeValue. The function queries for the kAXPositionAttribute and kAXSizeAttribute keys, returning AXValue objects that are unwrapped into CGPoint and CGSize structures. These conversions occur in helper methods within WindowMaximizer (referenced as pointAttribute and sizeAttribute in the source), establishing the baseline coordinates before any transformation.

Writing Position and Size

Actual window movement happens through AXUIElementSetAttributeValue, the primary API for programmatic window positioning in Vorssaint. The code wraps target coordinates in AXValue objects using AXValueCreate, then writes them to the element:

func setPosition(_ point: CGPoint, on element: AXUIElement) -> Bool {
    var point = point
    guard let value = AXValueCreate(.cgPoint, &point) else { return false }
    return AXUIElementSetAttributeValue(element,
                                        kAXPositionAttribute as CFString,
                                        value) == .success
}

func setSize(_ size: CGSize, on element: AXUIElement) -> Bool {
    var size = size
    guard let value = AXValueCreate(.cgSize, &size) else { return false }
    return AXUIElementSetAttributeValue(element,
                                        kAXSizeAttribute as CFString,
                                        value) == .success
}

These functions return boolean success indicators based on the AXError status code, allowing the service to detect permission failures or unsupported windows.

Validating Modification Permissions

Before attempting to reposition a window, Vorssaint checks whether the target attributes are writable. The canSetFrame method in Source/Vorssaint/Services/WindowMaximizer.swift calls AXUIElementIsAttributeSettable for both position and size attributes:

private func canSetFrame(on window: AXUIElement) -> Bool {
    var positionSettable = DarwinBoolean(false)
    var sizeSettable     = DarwinBoolean(false)

    let positionStatus = AXUIElementIsAttributeSettable(window,
                                 kAXPositionAttribute as CFString,
                                 &positionSettable)
    let sizeStatus = AXUIElementIsAttributeSettable(window,
                                 kAXSizeAttribute as CFString,
                                 &sizeSettable)

    return positionStatus == .success && sizeStatus == .success &&
           positionSettable.boolValue && sizeSettable.boolValue
}

This validation prevents runtime errors when encountering system windows or applications with accessibility protections enabled.

Animation and Coordinate Translation

Beyond static positioning, Vorssaint implements smooth window transitions using a Timer-based animation loop that interpolates between the current AXFrame and the target frame, repeatedly invoking the set-attribute calls at each step. This creates the visual effect of the window gliding into position without relying on private animation APIs.

Core Graphics Integration

To translate between the AX coordinate system and screen-space geometry, Vorssaint utilizes CoreGraphics (CG...) utilities. CGWindowID uniquely identifies windows for metadata retrieval, while CGEvent tap code intercepts mouse clicks that trigger resize operations. These identifiers bridge the gap between the accessibility element handles and the window server’s display composition.

AppKit Screen Geometry

For calculating maximization bounds and multi-monitor positioning, Vorssaint leverages AppKit’s NSScreen enumerations. Methods like bestScreen and menuBarScreenTopY compute the target frame’s origin and dimensions based on the visible trackpad area, menu bar insets, and display scaling factors. This ensures that programmatically positioned windows respect the user’s display arrangement and dock settings.

WindowMaximizer Implementation

The WindowMaximizer service orchestrates the complete positioning workflow. Its core toggle logic demonstrates how Vorssaint combines attribute reading, frame calculation, and attribute writing to switch between restored and maximized states:

// Inside WindowMaximizer.toggle(_:)
// 1️⃣ Get the current frame
guard let current = frame(of: target.window) else { return false }

// 2️⃣ Compute the maximised frame for the screen that contains the window
let maximized = axFrame(fromAppKit: screen.visibleFrame)

// 3️⃣ If the window is already near the maximised size, restore the original frame
if current.isClose(to: maximized, tolerance: frameTolerance),
   let original = originalFrames[target.windowID] {
    changeFrame(to: original, of: target) { _ in … }
} else {
    // 4️⃣ Otherwise store the original frame and move to the maximised one
    originalFrames[target.windowID] = current
    changeFrame(to: maximized, of: target) { _ in … }
}

This implementation stores original frames in a dictionary keyed by CGWindowID, enabling restoration after maximization.

Fallback to Native Actions

When the Accessibility-based change fails (indicated by AXUIElementSetAttributeValue returning an error), Vorssaint falls back to AXUIElementPerformAction for the window’s zoom button. This native UI action triggers the application’s built-in maximize behavior as a less precise but more compatible alternative.

Supporting Services Using the Same APIs

Several other components in vorssaint-utils reuse these programmatic window positioning primitives:

• WindowLayoutService (Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift): Orchestrates tiled window layouts by invoking the same AXUIElementSetAttributeValue calls to snap windows into grid positions.

• WindowLayoutSupport (Sources/Vorssaint/Services/WindowLayout/WindowLayoutSupport.swift): Provides helper enums that translate layout actions (left-half, right-half, etc.) into specific AX position/size write operations.

• WindowEnumerator (Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift): Retrieves window positions via AXUIElementCopyAttributeValue to build sorted navigation lists for the switcher interface.

• WindowActivator (Sources/Vorssaint/Services/Switcher/WindowActivator.swift): Restores window positions after activation using the stored AX position attributes, ensuring the switcher returns windows to their pre-navigation coordinates.

Summary

• Vorssaint implements programmatic window positioning primarily through the macOS Accessibility (AX) framework, specifically using AXUIElementSetAttributeValue to modify kAXPositionAttribute and kAXSizeAttribute.
• Before moving windows, the code validates permissions via AXUIElementIsAttributeSettable in the canSetFrame method of WindowMaximizer.swift.
• CoreGraphics (CGWindowID, CGEvent) and AppKit (NSScreen) provide coordinate translation and screen geometry calculations.
• Animation is achieved through a Timer-based loop that interpolates frame changes over time, repeatedly calling the AX set-attribute methods.
• The same AX primitives are shared across WindowMaximizer, WindowLayoutService, and the window switcher components to maintain consistent behavior throughout the application.

Frequently Asked Questions

Which specific API does Vorssaint call to physically move a window on screen?

Vorssaint calls AXUIElementSetAttributeValue with the kAXPositionAttribute key to programmatically move windows. This function requires a valid AXUIElement reference and an AXValue wrapping a CGPoint structure. The call returns an AXError status that indicates success or failure based on the target application’s accessibility permissions.

How does Vorssaint handle windows that refuse Accessibility-based resizing?

When AXUIElementIsAttributeSettable returns false or AXUIElementSetAttributeValue fails, Vorssaint falls back to AXUIElementPerformAction targeting the window’s zoom button. This triggers the native maximize behavior built into the application, providing a reliable alternative when direct frame manipulation is restricted by the target app’s sandbox or permissions.

Does Vorssaint use any private or undocumented APIs for window positioning?

No, Vorssaint relies on documented public frameworks: the Accessibility framework for UI control, CoreGraphics for window identification, and AppKit for screen metrics. All function signatures used—such as AXUIElementCopyAttributeValue, AXUIElementSetAttributeValue, and CGWindowID—are part of Apple’s public SDK, though they require the user to grant Accessibility permissions in System Settings.

Where is the core window positioning logic located in the repository?

The primary implementation resides in Sources/Vorssaint/Services/WindowMaximizer.swift. This file contains the setPosition, setSize, and canSetFrame methods that wrap the AX APIs. Supplemental positioning logic appears in Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift for tiling and Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift for position retrieval.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}