# How Vorssaint Intercepts the Green Traffic Light Button on macOS

> Learn how Vorssaint intercepts macOS green traffic light button clicks. Discover its low-level event tap and hit-testing techniques for window maximization. Full technical breakdown.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-06

---

**Vorssaint installs a low-level CGEvent tap that monitors left-mouse-down and left-mouse-up events, hit-tests against the green zoom button using WindowServer queries, and either maximizes the window or falls back to native behavior.**

Vorssaint's open-source utility (vorssaint/vorssaint-utils) replaces macOS's default fullscreen behavior with space-local maximization. The implementation centers on [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift), which intercepts clicks on the green traffic light button before they reach the standard window server. This approach requires Accessibility permissions and uses Core Graphics event taps to intercept user input at the system level.

## How the CGEvent Tap Captures Clicks

The interception begins in `start()` at lines 61-78 of [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift). This method creates a session-wide event tap using `CGEvent.tapCreate` that listens specifically for `.leftMouseDown` and `.leftMouseUp` events. When the user clicks anywhere on screen, the system routes the event to the private `handle(type:event:)` method before the window server processes it.

```swift
// Install the tap when the feature is enabled
WindowMaximizer.shared.start()

// Event handler that receives all left-mouse events
private func handle(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
    if type == .leftMouseDown,
       let target = target(at: event.location) {
        pendingClick = target          // Store the click target
        return nil                     // Block the original event
    }
    // Handle mouse up...
    return Unmanaged.passUnretained(event)
}

```

## Hit-Testing the Green Traffic Light Button

When `handle` receives a mouse-down event, it calls `target(at:)` (lines 40-45) to determine if the click landed on a traffic light. This method first queries `WindowServerTrafficLightHitTest.candidate(at:button:)` (lines 24-32 of [`WindowServerTrafficLightHitTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowServerTrafficLightHitTest.swift)) for a fast WindowServer lookup. If a candidate window exists and isn't fullscreen, `greenButtonFrame(in:containing:)` (lines 5-15) calculates the exact geometry of the green button to verify the hit.

The hit-test explicitly excludes fullscreen windows. If the window is in fullscreen mode, the method returns `nil` and the event passes through unmodified.

## Storing and Validating the Click Target

Upon confirming a green button hit, `WindowMaximizer` stores a `ClickTarget` instance in the `pendingClick` property (line 16). On `leftMouseUp`, the code validates whether the release point falls within the stored button's tolerance using `acceptsMouseUp(at:tolerance:)`.

Only if the mouse-up occurs within the tolerance zone does the system proceed to `toggle(_:)`. If the user drags the mouse away from the button before releasing, the pending click is discarded and the event is released to the system.

```swift
case .leftMouseUp:
    guard let target = pendingClick else { return Unmanaged.passUnretained(event) }
    pendingClick = nil
    if target.acceptsMouseUp(at: event.location, tolerance: clickTolerance) {
        _ = toggle(target)            // Attempt maximization
    }
    return nil

```

## Maximization Logic and Native Fallback

The `toggle(_:)` method compares the window's current frame against the screen's visible frame using `changeFrame(to:of:completion:)`. If the window already occupies the maximized frame, it restores the previous dimensions saved in `originalFrames`. Otherwise, it saves the current frame and animates the window to fill the screen.

If maximization fails or the window doesn't support resizing, `pressNativeButtonIfSafe(_:)` (lines 79-82) executes `AXUIElementPerformAction` to trigger the native green button behavior. This fallback only occurs when `allowsNativeFallback` is `true`, ensuring the green button never becomes unresponsive while respecting user preferences.

## Summary

- **CGEvent Tap**: `start()` creates a system-wide tap in [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift) lines 61-78 to intercept mouse events before native processing.
- **Hit-Testing**: `target(at:)` uses `WindowServerTrafficLightHitTest` for fast candidate lookup and `greenButtonFrame` for precise geometry validation.
- **State Management**: Mouse-down stores a `ClickTarget` in `pendingClick`; mouse-up validates tolerance before invoking `toggle(_:)`.
- **Maximization**: `toggle(_:)` animates windows to screen bounds or restores saved frames, with fallback to `pressNativeButtonIfSafe` when native behavior is required.

## Frequently Asked Questions

### Does WindowMaximizer require Accessibility permissions to intercept the green button?

Yes. The event tap implementation in [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift) relies on Core Graphics accessibility APIs to monitor system-wide mouse events. Without Accessibility access granted in System Preferences, `CGEvent.tapCreate` fails silently or returns nil, bypassing the interception logic entirely.

### What happens if the window is already fullscreen when clicking the green button?

The `target(at:)` method explicitly checks for fullscreen state before processing. If the candidate window is fullscreen, the hit-test returns nil, causing `WindowMaximizer` to release the event unmodified. This allows the system to handle the click normally without triggering the custom maximization logic.

### How does Vorssaint distinguish between the green, yellow, and red traffic light buttons?

The `candidate(at:button:)` method in [`WindowServerTrafficLightHitTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowServerTrafficLightHitTest.swift) accepts a button parameter to specify which traffic light to query. For the green button specifically, `greenButtonFrame(in:containing:)` calculates the precise frame coordinates, ensuring only clicks on the zoom button trigger maximization while ignoring close or minimize buttons.

### Can WindowMaximizer fall back to native macOS behavior if maximization fails?

Yes. The `pressNativeButtonIfSafe(_:)` method (lines 79-82 of [`WindowMaximizer.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowMaximizer.swift)) calls `AXUIElementPerformAction` on the green button element when `allowsNativeFallback` is true. This occurs when the window cannot be resized or when the user preference permits native fullscreen behavior, ensuring the app never leaves buttons unresponsive.