How the Modular Installation System in vorssaint-utils Works: Dynamic Feature Loading Explained

The modular installation system in vorssaint-utils uses a central FeatureManager to dynamically instantiate only the features you enable, storing active module identifiers in user defaults and loading them at launch while leaving dormant code completely inactive to preserve system resources.

The vorssaint-utils repository implements a feature-centric architecture that ships as a single binary containing numerous independent utilities. Instead of forcing users to install multiple separate applications, the codebase allows granular control over which capabilities run at any given time. This design ensures that only selected modules consume CPU, memory, or battery life while inactive features remain dormant within the binary.

Architecture of the Modular Installation System

The system treats every utility as a discrete feature that can be toggled independently. Rather than compiling separate apps for each tool, vorssaint-utils bundles all Swift implementations into one executable and relies on runtime checks to determine which objects to initialize.

Feature-Centric Design vs. Monolithic Apps

Traditional macOS utilities often install as standalone apps with fixed resource footprints. In contrast, vorssaint-utils stores a list of enabled feature identifiers in the app's user defaults. When the application launches, Sources/Vorssaint/main.swift initializes the FeatureManager, which reads this list and instantiates only the corresponding feature objects. Unselected modules are never loaded into memory, resulting in zero runtime cost for disabled functionality.

The Role of FeatureManager

The FeatureManager class, defined in Sources/Vorssaint/FeatureManager.swift, serves as the central registry for all modular operations. It maintains the activeFeatures set, handles permission validation for macOS privacy APIs, and coordinates the registration of UI panels and background services. Each feature implementation in Sources/Vorssaint/Features/*.swift (such as WindowSwitcherFeature.swift or BatteryMonitorFeature.swift) conforms to a protocol that the manager uses to standardize lifecycle methods across all modules.

How Features Are Loaded and Installed

Installation in vorssaint-utils is purely logical—no additional files are written to disk when enabling a feature. The process involves updating the persisted state list and triggering the manager's instantiation logic.

Bundle-Based Feature Selection

First-run setup presents three one-click feature bundles: Essentials, Windows, and Battery. Each bundle is simply a predefined array of feature identifiers that the FeatureManager enables atomically. Users can also toggle individual features from the Settings panel. The UI displays energy badges next to each feature, indicating which system resources remain active while the module is installed (e.g., network sockets, audio callbacks, or location monitoring).

Dynamic Instantiation at Runtime

When a user enables a feature, the FeatureManager immediately calls the feature's initialization method, registers its menu bar panel, and starts any background services. The Swift objects are created on-demand; if a feature identifier is absent from the user defaults list, the corresponding class is never allocated. This dynamic loading mechanism ensures that a user running only the Battery bundle, for example, never executes code associated with window management utilities.

Persisting State with User Defaults

Enabling or disabling a feature writes its identifier to UserDefaults under the application's suite. On subsequent launches, main.swift reconstructs the active feature set by reading this persisted list. This guarantees that installation state survives app restarts and system reboots without requiring external databases or configuration files.

// Enable a feature programmatically from the Command Bar or a script
import VorssaintCore

FeatureManager.shared.enable(.windowSwitcher)   // Activates Window Switcher UI
FeatureManager.shared.enable(.batteryMonitor)   // Starts battery-level monitoring

Managing Features Programmatically

Developers and power users can interact with the modular system directly through the FeatureManager API. This allows scripting of installation workflows and inspection of current module status without navigating the graphical interface.

Disabling Features and Resource Cleanup

When FeatureManager.shared.disable(.featureIdentifier) is called, the manager invokes the feature's teardown method. This unregisters keyboard shortcuts, closes network connections, removes menu bar items, and deallocates the Swift object. The identifier is simultaneously removed from user defaults, ensuring the feature remains inactive on the next launch.

// Disable a feature immediately tears down its UI and background jobs
FeatureManager.shared.disable(.windowSwitcher)

Querying Active Installations

To audit which utilities are currently running, access the activeFeatures property. This returns a set of identifiers representing instantiated modules, useful for debugging or creating conditional scripts that depend on specific capabilities being available.

// Inspect which features are currently installed
let installed = FeatureManager.shared.activeFeatures
print("Installed features: \(installed)")

Uninstalling Features and Complete Removal

The modular installation system supports both granular feature removal and complete application uninstallation.

The Uninstaller Panel Mechanism

Users can drag any enabled feature into the Uninstaller panel in Settings. This action triggers the same disable() logic but provides a visual queue for batch removal. Once the feature identifier is deleted from user defaults, the FeatureManager guarantees that no associated resources remain allocated. For complete removal of the application and all its data, the repository includes Tools/uninstall.sh, which deletes the binary, clears user defaults, and removes cached feature data.

Energy-Aware Design Benefits

Each feature declares its required macOS permissions and resource dependencies upfront. The Settings UI translates these declarations into energy badges, allowing users to make informed decisions about which modules justify their background activity. Because disabled features consume zero CPU cycles and allocate no memory, the modular system keeps the app's baseline resource usage minimal regardless of how many utilities are bundled in the binary.

Summary

• Single binary, multiple features: All utilities ship in one executable, but code remains dormant until explicitly enabled.
• FeatureManager orchestration: The FeatureManager class in Sources/Vorssaint/FeatureManager.swift controls instantiation, teardown, and state persistence.
• User defaults storage: Installation state persists via feature identifiers stored in the app's user defaults, read at launch by Sources/Vorssaint/main.swift.
• Zero-cost dormant features: Disabled modules are never instantiated, consuming no system resources.
• Bundle and individual selection: Users can install predefined bundles (Essentials, Windows, Battery) or toggle specific features with energy-badge guidance.
• Programmatic control: Swift API supports enabling, disabling, and querying features via FeatureManager.shared.

Frequently Asked Questions

Where does vorssaint-utils store which features are installed?

The installation state is stored in the application's user defaults as a list of feature identifiers. When the app launches, FeatureManager reads this list from UserDefaults and instantiates only the corresponding Swift objects. This persistence mechanism ensures your selected modules remain active across system restarts without requiring external configuration files.

How does vorssaint-utils handle uninstalling a specific feature?

Uninstalling a feature removes its identifier from user defaults and triggers the FeatureManager to execute the feature's teardown method. This immediately deallocates the Swift object, unregisters its UI panels, and closes any associated background services or file handles. For complete application removal, the Tools/uninstall.sh script deletes the binary and wipes all persisted feature data.

What are feature bundles in the vorssaint-utils modular system?

Feature bundles are predefined collections of feature identifiers that can be enabled with one click during first-run setup. The three default bundles—Essentials, Windows, and Battery—simultaneously activate multiple related utilities. Bundles are logical groupings only; you can still toggle individual features within a bundle on or off independently through the Settings panel.

Does disabling a feature in vorssaint-utils free up system resources immediately?

Yes. When you disable a feature through the Settings panel or programmatically via FeatureManager.shared.disable(), the manager immediately tears down all associated resources. This includes deallocating memory, unregistering audio or network callbacks, and removing menu bar icons. Because the feature's code is never executed again until re-enabled, the system resources remain available for other processes.

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