# How Vorssaint-utils Leverages Accessibility APIs for Window Control Takeover on macOS > Discover how Vorssaint-utils uses macOS Accessibility APIs to control and animate any application window. Enhance your window management with this powerful utility. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: deep-dive - Published: 2026-09-12 --- **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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.