# How the Feature Hub in Vorssaint-Utils Installs and Uninstalls Modular Features

> Learn how the Feature Hub in vorssaint-utils controls modular feature installation and uninstallation using UserDefaults flags and FeatureRuntime for service management.

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

---

**The feature hub in vorssaint-utils acts as a lightweight controller that toggles Boolean availability flags in `UserDefaults`, while the `FeatureRuntime` singleton handles the actual instantiation and teardown of feature services through registered bindings.**

The vorssaint-utils toolkit provides a modular macOS utility architecture where individual features can be dynamically enabled or disabled at runtime. Understanding how the feature hub coordinates these installations is essential for developers extending the framework or debugging feature availability issues.

## Architecture Overview

The feature hub UI is intentionally decoupled from feature implementations. According to the vorssaint-utils source code, the hub resides in [`Sources/Vorssaint/UI/Settings/FeatureHubSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/FeatureHubSettings.swift) and displays rows for each `AppFeature` defined in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift). The actual lifecycle management occurs in [`Sources/Vorssaint/App/FeatureRuntime.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/FeatureRuntime.swift), which maintains a static `bindings` dictionary containing the start and stop closures for every feature.

## The Installation and Uninstallation Flow

When a user clicks **Install** or **Uninstall** in the feature hub, the system executes a coordinated six-step process across the UI and runtime layers.

### UI Interaction and Method Invocation

Pressing a button in the hub triggers `FeatureHubRow.flip(to:)`, which immediately delegates to `FeatureRuntime.shared.setAvailable(_:,_)`. This method accepts an `AppFeature` enum case and a Boolean value indicating the desired availability state.

### Hardware Validation and Availability Gating

Before persisting any changes, `FeatureRuntime` validates the request through its internal `mayFlip` logic. Installation is permitted only when `feature.isHardwareSupported` returns `true` for the current Mac hardware. Uninstallation operations bypass this validation and are always allowed.

### Persisting State to UserDefaults

Once validated, the new availability state is written to `UserDefaults` using the key specified by `feature.availabilityKey` in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift). This persistence mechanism ensures feature states survive application restarts.

### Executing Feature Bindings

`FeatureRuntime` looks up the corresponding closure in its static `bindings` dictionary and executes it synchronously. These closures encapsulate the heavy lifting: creating service singletons, attaching observers, or cleaning up resources when tearing down a feature.

### Notifying Observers of State Changes

After processing all state changes, `FeatureRuntime` increments its `revision` property and broadcasts updates to the command-bar. Any UI components observing the runtime refresh automatically to reflect the new availability state.

## Bulk Operations for Installing and Uninstalling All Features

The hub provides **Install All** and **Uninstall All** buttons that invoke `FeatureRuntime.setAllAvailable(_:)`. This method iterates over every registered `AppFeature`, applies the same hardware-support validation, persists flags to `UserDefaults`, executes bindings for each feature, and finally bumps the revision once for the entire batch operation.

## Handling Restart Requirements After Uninstallation

Certain features create persistent UI elements such as panels or global shortcuts that remain active in the current session even after their services are stopped. When `FeatureRuntime` detects that a currently loaded feature has been uninstalled, it sets `needsRestartToUnload` to `true`, prompting the hub to display a restart banner informing users that a full application restart is required to complete the uninstallation.

## Programmatic Control of Feature Installation

Developers can bypass the UI and control feature states directly through the `FeatureRuntime` singleton:

```swift
// Install a single feature from code (e.g. from a preset)
FeatureRuntime.shared.setAvailable(.keepAwake, true)

// Uninstall a single feature
FeatureRuntime.shared.setAvailable(.keepAwake, false)

// Install every supported feature at once
FeatureRuntime.shared.setAllAvailable(true)

// Uninstall every feature (useful for a “reset” action)
FeatureRuntime.shared.setAllAvailable(false)

```

## Summary

- The feature hub in [`FeatureHubSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureHubSettings.swift) serves as a thin controller that delegates all logic to `FeatureRuntime`, keeping the UI completely decoupled from implementations.
- `FeatureRuntime.setAvailable(_:,_)` gates installation through hardware checks (`isHardwareSupported`) and persists state to `UserDefaults` via `availabilityKey`.
- Feature lifecycle management occurs through the `bindings` dictionary, which executes start/stop closures immediately upon state changes.
- Bulk operations use `setAllAvailable(_:)` to efficiently process multiple features with a single revision bump.
- Uninstalling active features may set `needsRestartToUnload`, requiring an app restart to fully release UI resources.

## Frequently Asked Questions

### What happens if I try to install a feature on unsupported hardware?

The `FeatureRuntime` checks `feature.isHardwareSupported` before allowing installation. If the current Mac does not meet the hardware requirements, the `setAvailable` call returns early without persisting the flag or executing the binding.

### Where is feature availability stored between app launches?

Availability states are persisted in `UserDefaults` using keys defined by `feature.availabilityKey` in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift). This allows `FeatureRuntime` to restore the previous configuration automatically on startup.

### Can I install or uninstall features programmatically without using the UI?

Yes. The `FeatureRuntime` singleton exposes `setAvailable(_:,_)` for individual features and `setAllAvailable(_:)` for bulk operations, allowing programmatic control from setup wizards, command-line tools, or configuration presets.

### Why does the hub sometimes show a restart banner after uninstalling?

Certain features create persistent UI elements like panels or shortcuts that cannot be fully released until the application restarts. When `FeatureRuntime.needsRestartToUnload` becomes `true`, the hub displays a banner indicating that a restart is required to complete the uninstallation process.