How Configurable Gaps Between Windows Work in Vorssaint

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 from geometric computation in 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. The implementation leverages SwiftUI's @AppStorage property wrapper to synchronize values with UserDefaults automatically.

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

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

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