# How Configurable Gaps Between Windows Work in Vorssaint

> Learn how Vorssaint implements configurable gaps between windows using @AppStorage properties for precise window tiling and layout control. Optimize your workspace.

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

---

**Vorssaint implements configurable gaps through two independent `@AppStorage` properties—`windowLayoutWindowGap` and `windowLayoutScreenGap`—that shrink the usable screen area and offset adjacent window edges during tiling calculations.**

Vorssaint is an open-source macOS window manager that provides granular control over window spacing through persistent user preferences. The architecture separates gap configuration in [`WindowLayoutSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutSettings.swift) from geometric computation in [`WindowLayoutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutSupport.swift), ensuring that configurable gaps between windows are applied consistently across both keyboard-driven and gesture-based layout actions.

## The Two Types of Configurable Gaps in Vorssaint

Vorssaint distinguishes between two spatial padding concepts that govern how windows occupy screen real estate.

### Window Gap

The **window gap** defines the distance maintained between adjacent tiled windows. Stored under the key `windowLayoutWindowGap`, this value represents the total space users want between two neighboring windows. During layout execution, Vorssaint halves this value and applies it to the shared edge of each window, ensuring the combined separation equals the full user-defined gap.

### Screen Gap

The **screen gap** (stored as `windowLayoutScreenGap`) creates an inset margin between the display edges and the tiling grid. This prevents windows from touching monitor bezels or the macOS menu bar. The system enforces a minimum safe boundary of **80 points** on any axis to prevent unusable window sizes.

## How Gap Values Are Stored and Persisted

User preferences for configurable gaps between windows live in [`Sources/Vorssaint/UI/Settings/WindowLayoutSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/WindowLayoutSettings.swift). The implementation leverages **SwiftUI's `@AppStorage`** property wrapper to synchronize values with `UserDefaults` automatically.

```swift
@AppStorage(DefaultsKey.windowLayoutWindowGap) var windowGap: GapPreset = .g16
@AppStorage(DefaultsKey.windowLayoutScreenGap) var screenGap: GapPreset = .g32

```

The UI presents discrete options through `WindowLayoutGaps.presets`, offering specific pixel values: 0 px, 8 px, 16 px, 32 px, 64 px, and 128 px. The `gapPresetTitle` helper formats these for display (e.g., "Tiny (8 px)"), providing intuitive selection without freeform text input that could yield invalid geometries.

## Runtime Gap Calculation Logic

When a tiling action triggers, `WindowLayoutService` delegates geometric computation to `WindowLayoutSupport.rect(...)`. This function in [`Sources/Vorssaint/Services/WindowLayout/WindowLayoutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutSupport.swift) applies gaps in two distinct phases.

### Applying Screen Gap Insets

First, `screenGapFrame(_:screenGap:)` calculates the usable tiling area by inseting the visible screen frame on all sides by the `screenGap` value. The function guards against excessive insets by maintaining a minimum 80 pt margin on each axis, preventing the layout grid from becoming too small to be practical.

### Distributing Window Gaps

Next, `windowGapped(_:for:in:windowGap:)` handles the spacing between individual windows. The function accepts the base layout rectangle and the configured window gap, then halves the gap value and applies it to the edges that share a boundary with another window. This halving strategy ensures that when two windows sit adjacent to one another, the total distance between them equals the user-specified `windowGap`—each window contributes half the separation.

```swift
// Example: Computing a left-half tile with gaps
let targetRect = WindowLayoutSupport.rect(
    for: .leftHalf,
    current: currentWindowFrame,
    visibleFrame: screenFrame,
    windowGap: CGFloat(16),  // 16 points between windows
    screenGap: CGFloat(32)   // 32 points from screen edges
)

```

## Integrating Gaps into Layout Operations

`WindowLayoutService` acts as the coordinator between user settings and window positioning. When executing layout commands, it retrieves current gap values from `@AppStorage` and passes them as `CGFloat` parameters to `WindowLayoutSupport.rect(...)`. The same gap configuration applies to gesture-based operations through [`WindowGestureSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowGestureSupport.swift), ensuring consistent spacing whether users trigger actions via keyboard shortcuts or trackpad gestures.

## Summary

- Vorssaint uses **two independent gap settings**: `windowLayoutWindowGap` for inter-window spacing and `windowLayoutScreenGap` for screen-edge margins.
- Settings persist via `@AppStorage` in [`WindowLayoutSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutSettings.swift), exposing preset values ranging from 0 to 128 pixels.
- `screenGapFrame(_:screenGap:)` insets the usable screen area while enforcing an 80 pt minimum safety margin.
- `windowGapped(_:for:in:windowGap:)` splits the window gap equally between adjacent windows to achieve precise spacing.
- `WindowLayoutService` bridges UI preferences to the layout engine, passing gap values to `WindowLayoutSupport.rect(...)` during tiling operations.

## Frequently Asked Questions

### How does Vorssaint prevent windows from becoming too small when large screen gaps are configured?

The `screenGapFrame` function in [`WindowLayoutSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowLayoutSupport.swift) enforces a hard minimum of 80 points on each axis after applying the screen gap inset. If the calculated usable area would drop below this threshold, the function prevents further reduction, ensuring windows remain operable regardless of user gap preferences.

### Why does Vorssaint halve the window gap value when applying it to individual windows?

Vorssaint divides the user-configured window gap by two in `windowGapped(_:for:in:windowGap:)` because adjacent windows both contribute to the shared boundary space. By applying half the gap to each window's edge, the final distance between the two windows equals the full configured value, maintaining mathematical precision in the layout grid.

### Where are gap preferences stored in the system?

Gap settings persist in macOS `UserDefaults` under the keys `windowLayoutWindowGap` and `windowLayoutScreenGap`, accessed through SwiftUI's `@AppStorage` property wrapper in [`Sources/Vorssaint/UI/Settings/WindowLayoutSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/WindowLayoutSettings.swift). This allows the preferences to sync across app launches and remain accessible to both the settings UI and the layout service.

### Can users set arbitrary pixel values for window gaps, or only presets?

The settings UI restricts gap selection to predefined presets (0, 8, 16, 32, 64, and 128 pixels) via the `WindowLayoutGaps.presets` array. While the underlying storage uses integer values and could theoretically accept any number programmatically, the preset picker ensures users select spacing values that tessellate cleanly across common display resolutions.