How the Window Snapping Feature Works in Vorssaint-Utils: A Deep Dive into the Swift Implementation

The window snapping feature in vorssaint-utils is implemented as a pure Swift engine that runs entirely inside the app, using three core components—a screen model, snap zone definitions, and a calculation engine—to detect pointer proximity to screen edges and compute target window rectangles without external binaries or system extensions.

The vorssaint-utils repository provides a self-contained window management toolkit for macOS. Its window snapping feature (also called edge snapping) allows users to drag windows to screen edges and corners to automatically resize them into predefined zones. The implementation relies on geometric calculations performed in real-time during drag operations, with all logic contained within the app's service layer.

Core Architecture of the Window Snapping Engine

The snapping system revolves around three interconnected concepts defined primarily in Sources/Vorssaint/Services/WindowLayout/WindowGestureSupport.swift.

Screen Geometry Model

The WindowEdgeSnapScreen struct, defined at lines 42–45, represents a physical display with two coordinate spaces:

• frame: The complete physical bounds of the screen
• visibleFrame: The usable area excluding the menu bar and Dock

struct WindowEdgeSnapScreen {
    let frame: CGRect
    let visibleFrame: CGRect
}

This distinction is critical because snapping calculations use visibleFrame to ensure windows never position themselves under system UI elements.

Snap Zone Definitions

The WindowEdgeSnapZone enum (lines 49–64) defines the eight possible drop locations: four edges plus four corners, plus a special maximize zone for the top edge center. Each zone maps to a WindowLayoutAction such as .leftHalf, .topRight, or .maximize.

The enum also persists user preferences. The methods disabledZones(from:) and disabledZonesStorageValue(_:) at lines 69–78 convert between a Set<WindowEdgeSnapZone> and a comma-separated string stored in UserDefaults, allowing users to disable specific zones via the UI.

The Snap Engine Entry Point

The WindowEdgeSnapSupport enum contains the static method target(at:screens:enabledZones:), which serves as the engine's entry point (lines 506–592). This method accepts a pointer location, an array of screen models, and a set of enabled zones, returning an optional WindowEdgeSnapTarget containing the target frame and zone identifier.

How Window Snapping Detection Works

When a user drags a window's title bar, the WindowLayoutService creates a WindowEdgeSnapPointerInput containing the current pointer location in screen coordinates and forwards it to the snap engine.

Pointer Proximity and Edge Detection

The engine first sorts screens by distance to the pointer, then checks whether the pointer lies within a configurable activation distance (default 12 points) of any screen edge. The logic distinguishes between edge types:

• Horizontal edges: The top edge uses a corner width of approximately 18% of screen width (clamped between 96–180 points) to differentiate between corner snaps and the center maximize zone (lines 444–451).
• Vertical edges: Left and right edges use a corner height of approximately 18% of screen height (clamped 80–160 points) to identify corner versus edge snaps (lines 464–470).

Handling Multi-Monitor Seam Crossings

A helper function hasNeighbor(beyond:point:distance:frames:) (lines 610–621) prevents false snapping when dragging across the seam between two displays. It checks whether another screen exists within the activation distance across an edge. If a neighbor is detected, the seam is not treated as a snap edge, allowing windows to cross freely between monitors without triggering unwanted resizes.

Zone Classification Logic

The engine uses a nested conditional structure to determine which of the eight zones is active based on the pointer's position relative to the calculated corner widths and heights. If the pointer is within the central region of a horizontal edge, it triggers the maximize action; if within the outer regions, it triggers corner snaps like .topLeft or .topRight.

Computing and Applying Snap Targets

Once a zone is identified, the engine translates the logical zone into concrete screen coordinates.

Building Target Rectangles with WindowLayoutGeometry

The engine calls WindowLayoutGeometry.rect(for:current:visibleFrame:windowGap:screenGap:) to compute the exact frame. This method accounts for user-configured gaps between windows and screen edges, returning pixel-aligned rectangles that respect the visibleFrame boundaries.

let targetFrame = WindowLayoutGeometry.rect(
    for: action,
    current: screen.visibleFrame,
    visibleFrame: screen.visibleFrame,
    windowGap: WindowLayoutGaps.windowGap,
    screenGap: WindowLayoutGaps.screenGap
)

The resulting WindowEdgeSnapTarget bundles the zone identifier, target frame, and reference screen (lines 585–591).

Integration with WindowLayoutService

Back in Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift, the service receives the target and validates the snap through applyEdgeSnap(_:target:). This method first checks WindowEdgeSnapSupport.isSystemTilingEnabled to avoid conflicts with macOS native tiling, then applies the frame:

func applyEdgeSnap(_ drag: WindowEdgeSnapDrag, target: WindowEdgeSnapTarget) {
    guard !WindowEdgeSnapSupport.isSystemTilingEnabled else { return }
    drag.window.setFrame(target.frame, display: true, animate: true)
}

The animation provides the characteristic "snap-into-place" feedback users expect from window snapping features.

User Configuration and Edge Cases

The implementation includes sophisticated handling for macOS system behaviors and user customization.

Enabling and Disabling Snap Zones

The UI layer in Sources/Vorssaint/UI/WindowGestureControls.swift provides the WindowEdgeSnapZonePicker view. This component displays a 3×3 grid where each cell represents a snap zone. Toggling a cell updates the disabledZonesStorage string binding, which the engine reads on subsequent drag operations to filter available zones.

System Gesture Avoidance and Resize Handle Detection

The engine includes specific guards against macOS system behaviors:

• Mission Control avoidance: When snapping to the top edge, the engine shifts the pointer coordinate to y = minY + 1 (lines 44–53) to prevent triggering Mission Control, which activates when dragging to the absolute top pixel of the screen.
• Resize handle detection: The startsAtResizeHandle check (lines 55–69) suppresses snapping if the drag initiated near a window's resize handles, preventing interference with native resizing operations.
• Drag classification: The classify(initialFrame:currentFrame:pointerStart:pointerNow:) method (lines 77–99) distinguishes between window moves, resizes, and unrelated drags, ensuring snapping only activates during genuine move operations.

Summary

• Pure Swift implementation: The window snapping feature requires no external binaries or system extensions, with all logic contained in WindowGestureSupport.swift.
• Three-tier architecture: Screen models provide geometry, snap zones define logical actions, and the WindowEdgeSnapSupport.target method calculates targets.
• Smart edge detection: The engine uses percentage-based corner calculations (18% of screen dimensions) and checks for multi-monitor seams to avoid false snaps.
• System integration: The feature respects macOS native tiling settings and avoids triggering Mission Control or interfering with resize handles.
• User customization: Snap zones can be individually enabled or disabled via UserDefaults, with changes reflected immediately in the drag handling logic.

Frequently Asked Questions

How does vorssaint-utils prevent window snapping between two connected displays?

The engine uses the hasNeighbor(beyond:point:distance:frames:) helper method in WindowGestureSupport.swift to detect when another screen exists across an edge. If a neighboring display is found within the activation distance, the seam is treated as non-snappable, allowing the window to cross smoothly between monitors without triggering a snap action.

Can users disable specific snap zones while keeping others active?

Yes. The WindowEdgeSnapZone enum provides disabledZones(from:) and disabledZonesStorageValue(_:) methods that serialize disabled zones as a comma-separated string in UserDefaults. The WindowEdgeSnapZonePicker UI in WindowGestureControls.swift exposes this functionality as a 3×3 grid where users can toggle individual zones, and the engine filters these out during the target(at:screens:enabledZones:) calculation.

Why does the window snapping feature shift the pointer when snapping to the top edge?

To avoid triggering macOS Mission Control—which activates when dragging a window to the absolute top pixel of the screen—the engine applies a one-point offset (y = minY + 1) when the top snap zone is active. This adjustment, implemented in the coordinate conversion logic, prevents the system gesture while still allowing the window to maximize or snap to the top half of the screen.

What happens if macOS native window tiling is enabled?

The WindowLayoutService checks WindowEdgeSnapSupport.isSystemTilingEnabled before applying any snap target. If the system tiling feature is active, the applyEdgeSnap method returns early without modifying the window frame, preventing conflicts between vorssaint-utils snapping and macOS built-in window management.

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