How Vorssaint Intercepts the Green Traffic Light Button on macOS

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, 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. 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.

// 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) 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.

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 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 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 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) 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.

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