# How the Window Layout and Snapping System Works in Vorssaint-utils

> Explore the window layout and snapping system in Vorssaint-utils. Learn how this Swift engine snaps windows to halves thirds corners and more using WindowEdgeSnapZone and drag classification.

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

---

**Vorssaint-utils implements a full-featured window-layout engine that lets users snap windows to halves, thirds, corners, maximise, and restore through a clean, test-able Swift architecture driven by the `WindowEdgeSnapZone` enum and drag classification logic.**

Vorssaint-utils provides a robust **window layout and snapping system** that enables precise window management across multiple displays. The architecture separates zone definitions from gesture detection, allowing users to customize which snap regions are active while maintaining compatibility with macOS native tiling features.

## Core Architecture and Snap Zones

The foundation of the snapping system rests on a strongly-typed enumeration that maps visual screen regions to layout actions.

### WindowEdgeSnapZone Enum

In [`Sources/Vorssaint/Services/WindowLayout/WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowGestureSupport.swift), the `WindowEdgeSnapZone` enum defines eight visual drop-areas around a screen perimeter. Each case maps to a specific `WindowLayoutAction` (e.g., `.topLeft` → `WindowLayoutAction.topLeft`). The enum uses `String` raw values to ensure user-saved preferences remain stable even if the UI presentation order changes.

```swift
// WindowGestureSupport.swift (line 49)
enum WindowEdgeSnapZone: String, CaseIterable {
    case topLeft, top, topRight
    case left, right
    case bottomLeft, bottom, bottomRight
}

```

### Zone State Management

Users can toggle individual zones on or off. The system persists disabled zones as a comma-separated string in `UserDefaults`, parsed by helper functions in the same file:

- `disabledZones(from:)` – Parses the stored string into a set of disabled zones
- `enabledZones(from:)` – Returns only active zones for the current screen
- `disabledZonesStorageValue(_:)` – Serializes the disabled set back to storage

## Drag Classification and Edge Detection

Before snapping can occur, the system must determine whether the user is moving, resizing, or performing an unrelated drag operation.

### Movement vs. Resize Detection

The `WindowEdgeSnapSupport.classify(initialFrame:currentFrame:pointerStart:pointerNow:)` method analyzes frame changes and pointer movement to return a `WindowEdgeDragClassification` value:

- `.waiting` – Insufficient movement to classify
- `.moving` – Translation without size change (eligible for snapping)
- `.resizing` – Frame dimensions changed
- `.unrelated` – Gesture does not involve window manipulation

### Activation Thresholds

The classification logic uses precise constants defined in [`WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureSupport.swift):

- **12 pt** – Activation distance for general snapping
- **12 pt** – Resize corner detection radius
- **5 pt** – Resize edge detection tolerance

These thresholds prevent accidental triggers while maintaining responsive interaction.

## macOS Integration and System Conflicts

The snapping engine detects and adapts to macOS system behaviors to prevent conflicts.

### System-Tiling Guard

macOS native edge-drag tiling can interfere with Vorssaint-utils snapping. The code checks the Apple "WindowManager" domain defaults using `isSystemTilingEnabled` and `systemTilingEnabled(valueFor:)` to detect whether `EnableTilingByEdgeDrag` is active. When system tiling is enabled, the engine disables overlapping zones to avoid double-handling window placement.

### Top-Edge Mission Control Workaround

macOS triggers Mission Control when the pointer rests exactly on the top screen edge. The helper `locationAvoidingSystemTopDrag(_:screenFrames:enabledZones:)` (line 44) automatically nudges the pointer location one pixel downward when the top-zone is active, preventing the system gesture from interrupting the snap operation.

## Directional Gesture Support

For users who prefer keyboard-driven layouts, the system supports "hold-shortcut pointer layout" mode.

### 8-Way Angular Detection

The `WindowDirectionalGestureSupport.action(from:to:)` method calculates the angle between drag start and end points, dividing the circle into 45° sectors to determine directional intent. Dragging up-right selects `topRight`, dragging left selects `leftHalf`, etc., without requiring proximity to screen edges.

## SwiftUI Configuration Interface

The user-facing controls live in [`Sources/Vorssaint/UI/WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/WindowGestureControls.swift).

### Zone Picker Control

`WindowEdgeSnapZonePicker` presents the eight zones as a grid of toggle buttons. The view uses `zoneRow(left:center:right:height:)` to build the visual layout and `toggle(_:)` to modify the disabled set. Users can reset to defaults via the `resetTitle` parameter.

```swift
import SwiftUI

struct SettingsView: View {
    @AppStorage("disabledSnapZones") var disabledZones = ""

    var body: some View {
        WindowEdgeSnapZonePicker(
            disabledZonesStorage: $disabledZones,
            text: WindowLayoutFeatureStrings(),
            resetTitle: "Reset snap zones",
            compact: false
        )
        .padding()
    }
}

```

### Modifier Key Selection

`WindowGestureModifierPicker` allows users to configure which modifier keys (`Control`, `Option`, `Command`) activate the directional gesture mode when held during pointer movement.

## Implementation Example

The following pattern demonstrates the complete snapping pipeline:

```swift
import Vorssaint

// 1. Classify the drag gesture
let classification = WindowEdgeSnapSupport.classify(
    initialFrame: oldFrame,
    currentFrame: newFrame,
    pointerStart: startPoint,
    pointerNow: currentPoint
)

guard classification == .moving else { return }

// 2. Detect the best snap target across available screens
let screen = WindowEdgeSnapScreen(frame: screenFrame, visibleFrame: visibleFrame)
let snapTarget = WindowEdgeSnapSupport.snapTarget(
    point: currentPoint,
    screens: [screen]
)

// 3. Resolve geometry and apply
if let target = snapTarget {
    let targetRect = WindowLayoutGeometry.rect(
        for: target.action,
        current: oldFrame,
        visibleFrame: visibleFrame
    )
    window.setFrame(targetRect, display: true, animate: true)
}

```

## Summary

- **WindowEdgeSnapZone** defines eight snap regions as a `String`-backed enum in [`WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureSupport.swift), ensuring stable preference persistence.
- The `classify()` method distinguishes between moves, resizes, and unrelated drags using 12 pt and 5 pt thresholds before allowing snaps.
- System compatibility checks detect macOS native tiling via `isSystemTilingEnabled` to prevent gesture conflicts.
- A one-pixel downward nudge in `locationAvoidingSystemTopDrag()` prevents Mission Control from interrupting top-edge snaps.
- Directional gestures use 45° angular sectors through `WindowDirectionalGestureSupport.action(from:to:)` for keyboard-driven layouts.
- SwiftUI controls in [`WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) provide visual zone toggles and modifier key configuration.

## Frequently Asked Questions

### How does Vorssaint-utils distinguish between moving and resizing a window?

The `WindowEdgeSnapSupport.classify(initialFrame:currentFrame:pointerStart:pointerNow:)` method compares the initial and current frame dimensions. If the size changes beyond the 12 pt corner or 5 pt edge thresholds, it returns `.resizing`; if the frame translates without size change, it returns `.moving`. Only `.moving` classifications proceed to snap detection.

### Can I disable specific snap zones in Vorssaint-utils?

Yes. The system stores disabled zones as a comma-separated string in `UserDefaults`, parsed by `disabledZones(from:)` and `enabledZones(from:)` in [`WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureSupport.swift). The `WindowEdgeSnapZonePicker` view in [`WindowGestureControls.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureControls.swift) provides a visual grid where you can toggle individual zones on or off.

### How does the system handle conflicts with macOS native window tiling?

The code checks `EnableTilingByEdgeDrag` and related keys in the "WindowManager" defaults domain via `isSystemTilingEnabled`. When macOS native tiling is active, Vorssaint-utils adjusts its behavior to disable overlapping zones, ensuring that system gestures and application snaps do not compete for the same screen edges.

### What constants control the snap sensitivity?

Three constants in [`WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureSupport.swift) define the interaction thresholds: **12 pt** for general snap activation distance, **12 pt** for resize corner detection, and **5 pt** for resize edge detection. These values determine how far the pointer must move before the system classifies the gesture as a move, resize, or snap candidate.