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

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

// 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:

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

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.

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:

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, 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 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. The WindowEdgeSnapZonePicker view in 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 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.

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