How to Customize vorssaint-utils: A Deep Dive Into Its Modular Architecture

vorssaint-utils can be customized through three extensible layers—feature toggles, runtime settings, and custom data blobs—allowing users to enable modules, modify behaviors, and inject custom assets without modifying the core source code.

vorssaint-utils is built around a highly modular Swift architecture that supports deep customization via UserDefaults and enum-driven configuration. Whether you want to disable unused features, remap shortcuts, or provide custom icons and URL filtering rules, the repository provides explicit extension points in Sources/Vorssaint/Core/FeatureCatalog.swift and related settings files. This guide explores the specific mechanisms that allow vorssaint-utils to be customized at runtime.

Feature-Level Customization via AppFeature

The primary mechanism for controlling which functionality is available lives in Sources/Vorssaint/Core/FeatureCatalog.swift. Each capability is defined as a case in the AppFeature enum, and availability is controlled through dedicated UserDefaults keys.

Toggling Features at Runtime

Every feature exposes an availabilityKey derived from its raw value. When you toggle a feature in the UI, the app writes a boolean to this key, and the system automatically unloads or reloads the corresponding UI components and services without requiring an app restart.

// Disable the Window Layout feature programmatically
UserDefaults.standard.set(false, forKey: AppFeature.windowLayout.availabilityKey)

This logic appears in FeatureCatalog.swift at lines 85-86, where the availabilityKey property returns the persistent storage identifier. Because the Settings UI references AppFeature.allCases to build the Features hub, adding a new case automatically surfaces it in the interface without migration code.

Adding New Features to the Catalog

To extend the app with a new module, insert a case into the enum and provide metadata such as group classification, symbols, and required permissions:

enum AppFeature: String, CaseIterable {
    case windowLayout
    case screenRecorder
    case radialMenu
    case nightMode  // New custom feature
}

The FeatureGroup logic organizes these into the Settings interface, and the enabledKeys array (lines 95-108) determines which specific UserDefaults flags must be true for the system to consider that feature actively engaged.

Runtime Settings and DefaultsKey

Beyond binary on/off states, vorssaint-utils exposes granular behaviors through the DefaultsKey struct. These keys define UserDefaults entries for shortcut preferences, icon assets, and processing rules that take effect immediately.

Persistent Configuration Storage

Individual options bind directly to SwiftUI's @AppStorage or manual wrappers in SettingsView.swift. For example, enabling "focus follows mouse" writes to a specific defaults key:

UserDefaults.standard.set(true, forKey: DefaultsKey.focusFollowsMouseEnabled)

According to the source code in FeatureCatalog.swift (lines 95-108), a feature's enabledKeys property lists which defaults must evaluate to true for the system to consider that feature active. This allows features to remain dormant until specific sub-options are enabled, preserving user configuration across toggle cycles.

Custom Data Blobs: Icons, URLs, and Date Patterns

The deepest layer of customization involves storing rich user-defined data as Data objects in UserDefaults. This supports custom radial menu icons, URL-cleaning parameters, and date-formatting patterns without rebuilding the app.

Custom Radial Menu Icons

Users can assign custom images to radial menu items. These images are compressed and stored as Data under DefaultsKey.radialMenuItems. The RadialMenuIconStore handles encoding and decoding as implemented in RadialMenuSettings.swift:

import AppKit

func setCustomIcon(for itemID: UUID, image: NSImage) {
    guard let pngData = image.tiffRepresentation?.compressed(using: .zlib) else { return }
    var items = RadialMenuSupport.decode(UserDefaults.standard.data(forKey: DefaultsKey.radialMenuItems))
    if let index = items.firstIndex(where: { $0.id == itemID }) {
        items[index].customIconData = pngData
        UserDefaults.standard.set(RadialMenuSupport.encode(items), forKey: DefaultsKey.radialMenuItems)
    }
}

See Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift (lines 875-1098) for the full implementation of custom icon persistence and RadialMenuIconStore.customIcon(for:) retrieval logic.

URL Cleaner Custom Parameters

The URL cleaning feature allows users to define arbitrary query parameters to strip from copied URLs. These are stored as comma-separated strings and parsed via URLCleaning.customParameters(from:) in URLCleanerSettings.swift:

// Define custom tracking parameters to remove
let customNames = "ref,utm_source,session_id"
UserDefaults.standard.set(customNames, forKey: DefaultsKey.urlCleanerCustomNames)

The parsing logic resides at lines 271-306, where the function splits the string and applies it to URL processing. This allows users to customize URL hygiene rules without modifying the underlying cleaning engine.

Custom Date-Time Patterns for Text Snippets

Text snippets support user-defined date formats through DateVariableBuilder.swift (lines 165-170). When users select the "custom" style, the pattern string passes directly to DateFormatter via UserDefaults:

let customPattern = "dd/MM/yyyy HH:mm"
UserDefaults.standard.set(customPattern, forKey: DefaultsKey.textSnippetCustomPattern)

This allows arbitrary date formatting without code changes, as the snippet engine reads this key at runtime and applies it to timestamp generation.

Permission and Onboarding Customization

Each AppFeature declares required system permissions via the permissions and onboardingPermissions properties (lines 50-104 in FeatureCatalog.swift). This modular permission system means broad permissions like Accessibility or Screen Recording appear in the initial onboarding flow only if required by currently enabled features, while contextual permissions are requested on-demand when specific radial menu shortcuts trigger protected actions.

Summary

• vorssaint-utils can be customized at three distinct levels: feature availability, runtime settings, and rich custom data blobs stored in UserDefaults.
• Feature toggles use the AppFeature enum in FeatureCatalog.swift, where each case automatically generates a persistent availabilityKey that controls module loading.
• Settings persist via DefaultsKey entries that bind to SwiftUI controls in SettingsView.swift, allowing immediate behavior changes without relaunching.
• Custom data like radial menu icons, URL cleaning rules, and date patterns are encoded as Data objects and decoded by helper structs such as RadialMenuIconStore and URLCleaning.
• Extensions require only adding enum cases or defaults keys; end-users customize via the built-in UI without touching source code.

Frequently Asked Questions

Can vorssaint-utils be customized without recompiling the source code?

Yes. End-users can customize vorssaint-utils entirely through the built-in Settings interface. All customizations—including enabling features, setting shortcuts, and adding custom icons or URL rules—persist via UserDefaults and take effect immediately without code changes or recompilation.

How do I add a completely new feature to vorssaint-utils?

Adding a feature requires modifying Sources/Vorssaint/Core/FeatureCatalog.swift to insert a new case in the AppFeature enum, then rebuilding the app. Once added, the feature automatically appears in the Settings UI via AppFeature.allCases and maintains its own availability state through the availabilityKey property.

Where are custom radial menu icons stored in vorssaint-utils?

Custom icons are stored as compressed Data blobs in UserDefaults under DefaultsKey.radialMenuItems. The RadialMenuIconStore struct in RadialMenuSettings.swift (lines 875-1098) handles encoding and decoding, allowing user-provided images to persist across app restarts and feature toggles.

Can I customize which URL parameters vorssaint-utils removes?

Yes. The URL Cleaner feature supports custom parameters through DefaultsKey.urlCleanerCustomNames. Users provide a comma-separated list of parameter names, which URLCleaning.customParameters(from:) parses in URLCleanerSettings.swift (lines 271-306) and applies to all copied URLs automatically.

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