# How Vorssaint Handles Window Snapping and Layout Management in macOS

> Learn how Vorssaint manages window snapping and layout in macOS. Discover its three-layer system that uses Accessibility APIs for efficient window arrangement.

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

---

**Vorssaint implements a three-layer, test-driven window snapping and layout system that intercepts pointer drags, maps them to eight edge-snap zones, and applies new window frames via macOS Accessibility APIs while respecting system tiling settings.**

Vorssaint's window snapping and layout management system provides a complete alternative to macOS's native tiling, working across multiple displays with user-configurable zones and keyboard shortcuts. The implementation in the `vorssaint/vorssaint-utils` repository divides functionality between gesture detection, snap-zone calculation, and frame application. Each layer operates through distinct Swift types in the `WindowLayout` service directory, ensuring type-safe coordination between user input and window manipulation.

## Architecture Overview

The system organizes window control into three distinct layers:

- **Input & Gesture Detection** – Captures pointer drags and classifies them as moving, resizing, or waiting using `WindowEdgeDragClassification`
- **Snapping Logic** – Maps pointer locations to eight discrete `WindowEdgeSnapZone` targets while filtering conflicts with macOS system tiling
- **Layout Application** – Translates snap targets into `WindowLayoutAction` instances and applies them via `WindowLayoutSupport.applyPlacement`

This separation allows Vorssaint to abort snapping operations early if a gesture is classified as a resize, preserving native macOS window behavior when appropriate.

## Gesture Detection and Classification

When a user begins dragging a window, `WindowLayoutService.makeEdgeSnapDrag` creates a `WindowEdgeSnapDrag` instance that tracks the initial window frame, pointer coordinates, and screen context. During the drag, the service repeatedly calls `WindowEdgeSnapSupport.classify` (defined in *WindowGestureSupport.swift*, lines 12–99) to determine intent.

The classification logic compares the initial and current window frames against pointer movement:

```swift
static func classify(initialFrame: CGRect,
                    currentFrame: CGRect,
                    pointerStart: CGPoint,
                    pointerNow: CGPoint) -> WindowEdgeDragClassification {
    // Size tolerance, movement threshold, and alignment checks determine
    // whether the gesture is .moving, .resizing, .waiting, or .unrelated
}

```

Only drags classified as `.moving` proceed to snap-zone evaluation. Resizing gestures are ignored by the snapping system, allowing the user to resize without triggering layout changes.

## Edge-Snap Zone Determination

Vorssaint divides each screen into eight visible zones represented by the `WindowEdgeSnapZone` enum. Each zone maps to a specific `WindowLayoutAction`—for example, the `.top` zone triggers `.maximize`.

The `WindowEdgeSnapSupport.target(at:screens:enabledZones:)` method evaluates the current pointer position against active screens:

```swift
let appKitPoint = CGPoint(x: point.x, y: menuBarScreenTopY - point.y)
let screens = NSScreen.screens.map {
    WindowEdgeSnapScreen(frame: $0.frame, visibleFrame: $0.visibleFrame)
}
return WindowEdgeSnapSupport.target(at: appKitPoint,
                                    screens: screens,
                                    enabledZones: enabledEdgeSnapZones)

```

Disabled zones are parsed from a comma-separated string stored in `UserDefaults` under `DefaultsKey.windowEdgeSnapDisabledZones`. The helper `WindowEdgeSnapSupport.locationAvoidingSystemTopDrag` adjusts coordinates to prevent accidental triggering of macOS's top-window-overview gesture.

## Conflict Handling and System Integration

Before applying any snap, Vorssaint validates three conditions in `WindowEdgeSnapSupport`:

1. **User preference**: `DefaultsKey.windowEdgeSnapEnabled` must be true
2. **Zone availability**: The target zone must exist in `enabledEdgeSnapZones`
3. **System tiling**: `WindowEdgeSnapSupport.isSystemTilingEnabled` must return false

If any check fails, the snap is discarded and the event passes through to macOS. This ensures Vorssaint never conflicts with native window management when users enable Apple's built-in tiling features.

## Layout Application

Once a valid `WindowEdgeSnapTarget` is confirmed, `WindowLayoutService.applyEdgeSnap` (lines 18–44 of *WindowLayoutService.swift*) orchestrates the frame change. It retrieves the current window frame via Accessibility APIs, constructs a `WindowLayoutTarget`, and delegates to `WindowLayoutSupport.applyPlacement`:

```swift
_ = applyPlacement(target.action,
                  to: layoutTarget,
                  visibleFrame: target.visibleFrame,
                  historyFrame: history,
                  cyclesRepeatedAction: false)

```

The `applyPlacement` function translates `WindowLayoutAction` values (such as `.leftHalf`, `.maximize`, or `.position(x:y:)`) into concrete `CGRect` values or full-screen requests. Each action supports a default global shortcut defined in `WindowLayoutAction.defaultShortcut` (lines 21–45 of *WindowLayoutSupport.swift*), allowing users to trigger layouts via keyboard without dragging.

## User Configuration and Persistence

Vorssaint stores user preferences in standard `UserDefaults`:

- **Disabled zones**: A CSV string under `DefaultsKey.windowEdgeSnapDisabledZones`, parsed by `WindowEdgeSnapZone.disabledZones(from:)` (lines 69–74)
- **Shortcuts**: String values under `DefaultsKey.windowLayoutShortcut…` keys, resolved through `WindowLayoutAction.savedShortcut` (lines 63–67)

Programmatically disabling a zone requires updating the set and persisting the CSV representation:

```swift
var disabled = WindowEdgeSnapZone.disabledZones(from: UserDefaults.standard.string(forKey: DefaultsKey.windowEdgeSnapDisabledZones))
disabled.insert(.top)  // Disable top zone
UserDefaults.standard.setValue(WindowEdgeSnapZone.disabledZonesStorageValue(disabled),
                               forKey: DefaultsKey.windowEdgeSnapDisabledZones)

```

## Visual Feedback

During active drags, Vorssaint displays a translucent preview panel via the `edgeSnapPreviewPanel` property. The `showEdgeSnapPreview` method positions this panel at the target frame calculated by the snap zone logic, using Core Animation fade transitions (lines 62–80) to provide visual confirmation without interfering with the drag operation.

## Testing Coverage

All snapping logic and gesture classification algorithms are validated in [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) (lines 5587–5720). These unit tests verify zone activation, disabled-zone filtering, and conflict handling across simulated multi-display configurations and edge-case pointer movements, ensuring consistent behavior regardless of screen geometry.

## Summary

- Vorssaint uses a three-layer architecture to separate gesture detection, snap-zone calculation, and frame application
- `WindowEdgeSnapSupport.classify` filters resize gestures from snap candidates using frame and pointer comparisons
- Eight configurable `WindowEdgeSnapZone` targets map to `WindowLayoutAction` values like `.maximize` and `.leftHalf`
- The system respects macOS native tiling by checking `isSystemTilingEnabled` before applying any layout
- User preferences for disabled zones and shortcuts persist in `UserDefaults` as comma-separated strings
- Visual previews provide real-time feedback during drag operations via Core Animation
- Comprehensive unit tests in [`MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MetricsTests.swift) cover multi-display scenarios and edge cases

## Frequently Asked Questions

### How does Vorssaint prevent conflicts with macOS native window tiling?

Vorssaint checks `WindowEdgeSnapSupport.isSystemTilingEnabled` before applying any snap target. If the user has enabled macOS system tiling, Vorssaint aborts the snap operation and allows the OS to handle the edge-drag gesture instead. This ensures the two systems never compete for control of window placement.

### Can Vorssaint's window snapping work across multiple monitors?

Yes. The `edgeSnapTarget(atQuartzPoint:)` method iterates over all available `NSScreen` instances, mapping them to `WindowEdgeSnapScreen` structs that include both full and visible frame data. The snapping logic evaluates the pointer location against every connected display's coordinate space, allowing seamless transitions between monitors during drag operations.

### What determines whether a drag gesture triggers window snapping?

The `WindowEdgeSnapSupport.classify` function analyzes the delta between the initial window frame and current frame, combined with pointer movement thresholds. Only gestures classified as `.moving` proceed to snapping; gestures classified as `.resizing` or `.waiting` are ignored. This prevents accidental layout changes when users intend to resize edges or perform other window operations.

### How can users disable specific snap zones without turning off the entire feature?

Users can disable individual zones by modifying the set returned from `WindowEdgeSnapZone.disabledZones(from:)`. The application stores disabled zones as a comma-separated string in `UserDefaults` under `DefaultsKey.windowEdgeSnapDisabledZones`. The UI layer in [`WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) provides a graphical interface for toggling these zones without requiring manual UserDefaults editing.