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

> Explore the pure Swift engine behind vorssaint-utils window snapping. Learn how its screen model, snap zones, and calculation engine detect proximity and compute target rectangles without external binaries.

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

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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

```swift
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.

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.