How Vorssaint-utils Leverages Accessibility APIs for Window Control Takeover on macOS

Vorssaint-utils implements window control takeover by directly interfacing with macOS’s Accessibility (AX) framework to read, manipulate, and animate window geometry across any application.

The open-source utility Vorssaint-utils provides advanced window management features—such as converting the green traffic-light button into a maximize toggle—by programmatically controlling other applications' windows. According to the source code in vorssaint/vorssaint-utils, this capability relies on a sophisticated integration with macOS Accessibility APIs that respects user permissions while enabling precise geometry manipulation.

Permission Gating with AXIsProcessTrusted

Before executing any window control operations, Vorssaint-utils validates that the process holds Accessibility privileges. In Sources/Vorssaint/Services/WindowMaximizer.swift, the syncWithPreferences method calls AXIsProcessTrusted() to verify authorization status between lines 32-38.

If the user has not granted Accessibility permissions, the event tap automatically disables itself to prevent the application from hanging on blocking AX calls. This safety mechanism ensures the utility fails gracefully rather than attempting unauthorized API access that would trigger system security dialogs or application freezes.

Locating Target Windows via Accessibility Queries

The window discovery process combines fast WindowServer lookups with precise Accessibility hierarchy traversal to minimize cross-process overhead.

Fast Pre-filtering with WindowServer

When the event tap intercepts a left-mouse click, the target(at:) method first invokes WindowServerTrafficLightHitTest.candidate(at:button:) defined in Sources/Vorssaint/Services/WindowServerTrafficLightHitTest.swift (lines 21-33). This lightweight hit-test scans the WindowServer’s on-screen window list to identify candidate windows without expensive AX queries.

This optimization prevents unnecessary Accessibility API calls for clicks that clearly miss window boundaries, reducing CPU overhead and latency.

Walking the Accessibility Hierarchy

Once a candidate is identified, the code creates a system-wide Accessibility element using AXUIElementCreateSystemWide() and queries the element under the cursor with AXUIElementCopyElementAtPosition(), as seen in WindowMaximizer.swift lines 49-55.

The topLevelWindow(from:) method (lines 76-88) then traverses up the AX hierarchy using elementAttribute, role, and pid comparisons until it locates the top-level AXWindow element belonging to the same process as the initial candidate. This upward walk ensures the utility targets the correct window container rather than individual sub-elements like buttons or toolbars.

Reading Window Geometry and State

After identifying the target window, Vorssaint-utils extracts its current dimensions and validates the interaction context using standard AX attributes.

The frame(of:) helper method (lines 96-104) retrieves the window’s current rectangle by querying kAXPositionAttribute and kAXSizeAttribute from the AXWindow element. These Core Foundation strings map to CGPoint and CGSize values that the utility converts to NSRect for internal calculations.

Additionally, the code verifies that the click originated from the green traffic-light button by querying kAXZoomButtonAttribute (lines 105-115). This validation determines whether to proceed with custom maximize logic or allow native fallback behavior, ensuring the utility only intercepts intentional maximize attempts.

Mutating Window State Programmatically

The core window manipulation logic resides in the toggle(_:) method, which decides whether to restore original dimensions or maximize to the current screen’s visible frame.

Frame Conversion and Validation

Before applying changes, Vorssaint-utils converts the target NSRect to an AX-compatible representation using axFrame(fromAppKit:) (lines 65-71). The canSetFrame(on:) method (lines 34-47) validates that the window accepts attribute modifications, preventing crashes when targeting protected system windows or applications with restricted AX interfaces.

The actual mutation occurs through AXUIElementSetAttributeValue calls within setPosition and setSize (lines 84-94), which write to kAXPositionAttribute and kAXSizeAttribute respectively. To handle applications that resist immediate resizing, the settleFrame routine implements a retry mechanism with animation frames before falling back to original geometry if the target application rejects the new size.

Handling Enhanced User Interface Mode

To prevent conflicts with screen readers and other assistive technologies, the code temporarily suspends the system’s "enhanced user interface" mode during window animations. The EnhancedUserInterfaceSuspension.suspend(forAppOf:) method (referenced in lines 88-92) disables this accessibility feature for the target application’s process, then automatically resumes it after the animation completes. This courtesy ensures Vorssaint-utils does not break VoiceOver navigation or other assistive workflows while manipulating window geometry.

Native Fallback Mechanisms

When Accessibility permissions are revoked or the target button does not support custom handling, Vorssaint-utils defers to standard macOS behavior. If AXIsProcessTrusted() returns false, or if the zoom button validation fails, the code passes the click through to AXUIElementPerformAction with kAXPressAction (lines 78-82), triggering the native green-button behavior without interception.

This fallback ensures the utility remains transparent when operating in restricted environments, maintaining system stability and user expectations for standard window controls.

Summary

• Permission awareness: Vorssaint-utils checks AXIsProcessTrusted() before any AX operations to prevent hangs and unauthorized access attempts.
• Two-stage window discovery: Combines fast WindowServer hit-testing (WindowServerTrafficLightHitTest.swift) with hierarchy traversal using AXUIElementCopyElementAtPosition().
• Geometry manipulation: Reads frames via kAXPositionAttribute and kAXSizeAttribute, then writes new dimensions using AXUIElementSetAttributeValue with validation guards.
• Assistive compatibility: Temporarily suspends Enhanced User Interface mode during animations to avoid disrupting screen readers.
• Graceful degradation: Falls back to native AXUIElementPerformAction when permissions are missing or windows resist modification.

Frequently Asked Questions

What Accessibility permissions does Vorssaint-utils require?

Vorssaint-utils requires the Accessibility permission in macOS System Settings to function. The code explicitly checks AXIsProcessTrusted() on every activation cycle in WindowMaximizer.swift, and automatically disables its event tap if permissions are revoked. Without this access, the utility cannot read window geometry or manipulate positions of other applications' windows.

How does Vorssaint-utils find the correct window to manipulate?

The utility employs a two-phase approach: first using WindowServerTrafficLightHitTest.candidate() to quickly locate potential windows based on the click location, then creating a system-wide AX element via AXUIElementCreateSystemWide() and walking up the hierarchy with topLevelWindow(from:) until it finds the parent AXWindow element matching the target process ID.

Can Vorssaint-utils resize windows that normally resist maximization?

Yes, within constraints. The canSetFrame(on:) method validates that the window accepts attribute changes before attempting writes. For resistant applications, the settleFrame routine implements retry logic with animations. However, if an application explicitly rejects AX size modifications, the utility preserves the original frame rather than forcing a change.

Does window manipulation interfere with VoiceOver or accessibility features?

No. The code specifically handles this in EnhancedUserInterfaceSuspension.swift, temporarily disabling the system’s Enhanced User Interface mode for the target application during animations. This prevents the utility’s geometry changes from confusing screen readers or breaking assistive navigation, then automatically restores the original accessibility state once the operation completes.

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