How Vorssaint Handles Window Snapping and Layout Management in macOS

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:

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:

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:

_ = 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:

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 (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 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 provides a graphical interface for toggling these zones without requiring manual UserDefaults editing.

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