# How Vorssaint Handles Uninstalled Feature Settings: Complete Technical Guide

> Discover how Vorssaint handles uninstalled feature settings. Learn how feature uninstallation is a reversible state change, preserving settings for seamless reinstallation.

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

---

**Vorssaint treats feature uninstallation as a reversible state change rather than a destructive operation, preserving all settings in user defaults so features resume with their previous configuration upon re-installation.**

The **vorssaint/vorssaint-utils** project implements a modular architecture where users can selectively enable or disable individual utilities. Understanding how uninstalled feature settings are managed requires examining the interplay between the **FeatureCatalog**, **FeatureRuntime**, and the underlying `Defaults` persistence layer.

## The Uninstall-as-State-Change Architecture

Unlike traditional uninstall mechanisms that delete data, Vorssaint's approach centers on a single boolean flag. Each feature maintains an `installed` state alongside its dedicated preference keys under the namespace `com.vorssaint.utils.feature.<id>.settings`.

This design emerges from the project's "Install only what you use" philosophy, explicitly documented in the repository's README. The practical implication: users can experiment with features without fear of losing carefully tuned configurations.

## How the Runtime Filters Uninstalled Features

The **FeatureCatalog** ([`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift)) serves as the gatekeeper at application startup. It reads the persisted installation flags from `UserDefaults` and builds an **allow list** of features to instantiate.

```swift
// FeatureCatalog.swift – startup filtering logic
func loadInstalledFeatures() -> [Feature] {
    return allAvailableFeatures.filter { feature in
        Defaults.isFeatureInstalled(feature.id)  // Only true = loaded
    }
}

```

Uninstalled features never reach the **FeatureRuntime** ([`Sources/Vorssaint/App/FeatureRuntime.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/FeatureRuntime.swift)). This guarantees zero resource consumption—no memory allocation, no background processes, no UI registration.

## Persistent Settings Survive Uninstallation

The critical insight: **the `Defaults` system receives no deletion commands during uninstall**. The `setFeatureInstalled(false, for: id)` call only mutates the state flag, leaving all feature-specific preferences intact.

```swift
// Vorssaint's uninstall implementation preserves settings
func uninstallFeature(_ id: FeatureID) {
    Defaults.setFeatureInstalled(false, for: id)  // Toggle flag only
    // All preference keys remain in UserDefaults
}

```

This enables seamless restoration. When a user re-installs a feature, the previous `volumeLevel`, `hotkeyBindings`, or `customScripts` values are immediately available without migration or reconfiguration.

## In-Session Behavior and Memory Management

The uninstall action triggers **immediate UI feedback** but **deferred memory cleanup**. The feature's row disappears from Settings → Features, yet the underlying object persists until application termination.

This behavior surfaces in the user-facing strings defined in [`Sources/Vorssaint/Core/FeatureHubStrings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureHubStrings.swift):

```swift
// FeatureHubStrings.swift – user communication about restart requirement
static let restartNote = "Features uninstalled in this session stay loaded until the app restarts. Restart now to unload them from memory."

static let footerNote = "Uninstalling deletes nothing: the feature just leaves the app and stops loading. Install it again anytime and everything returns as it was."

```

The **restartButton** provides optional immediate cleanup, though users may continue working and restart at their convenience.

## Accessing Settings of Currently Uninstalled Features

Because preferences exist independently of installation state, code can retrieve values for inactive features. This supports migration tools, backup utilities, or analytics that need historical configuration data.

```swift
// Settings remain accessible regardless of installation state
let mixerVolume = Defaults.float(forKey: "vorssaint.feature.mixer.volume")
let uninstallerPaths = Defaults.stringArray(forKey: "vorssaint.feature.uninstaller.safePaths")

```

Direct key access bypasses the `FeatureCatalog` filter, enabling advanced use cases while the standard runtime path remains blocked.

## Complete Uninstallation and Deep Cleanup

For users requiring **irreversible removal**, the repository provides [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh). This shell script performs comprehensive teardown:

```bash

# uninstall.sh – destructive cleanup (external to app runtime)

defaults delete com.vorssaint.utils        # Removes ALL defaults including feature flags

rm -rf /Applications/Vorssaint.app

# Additional cleanup for login items, launch agents...

```

This script is **not invoked by in-app uninstall actions**—it requires deliberate manual execution, protecting against accidental data loss.

## Code Reference: The Complete Settings Lifecycle

```swift
import VorssaintCore

// 1. Verify installation status (runtime-gated)
let catalog = FeatureCatalog.shared
if catalog.isFeatureInstalled(.uninstaller) {
    let feature = catalog.instantiate(.uninstaller)
    feature.activate()
}

// 2. Toggle installation state (survives app restarts)
Defaults.setFeatureInstalled(false, for: .uninstaller)  // Uninstall
Defaults.setFeatureInstalled(true, for: .uninstaller)   // Re-install

// 3. Direct preference access (bypasses installation check)
let legacySetting = Defaults.object(forKey: "vorssaint.feature.uninstaller.legacyPaths")

```

## Summary

- **State-based filtering**: The `installed` flag in `UserDefaults` determines which features load at startup ([`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift)).
- **Non-destructive uninstall**: Only the state flag changes; all preference data persists for potential restoration.
- **Memory retention**: Uninstalled features remain in RAM until application restart, communicated via `FeatureHubStrings.restartNote`.
- **Explicit deep cleanup**: The separate [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) script handles irreversible removal when required.
- **Direct access possible**: Raw `Defaults` keys allow reading settings of uninstalled features outside the standard runtime path.

## Frequently Asked Questions

### Does uninstalling a Vorssaint feature delete my settings permanently?

No. The standard uninstall action toggles only the `installed` flag while preserving all preference keys. Your settings remain in `UserDefaults` and automatically restore when you re-install the feature.

### Why do I need to restart Vorssaint after uninstalling features?

The runtime keeps uninstalled features in memory for the current session to ensure stability. The `FeatureRuntime` only respects the updated `installed` flag at the next launch cycle. The UI displays `FeatureHubStrings.restartNote` to explain this temporary state.

### Can I backup settings from a feature I've already uninstalled?

Yes. Direct `Defaults` access using the feature's preference keys (e.g., `vorssaint.feature.<id>.settingName`) works regardless of installation status. The values were never cleared—just not loaded into the active runtime.

### How is this different from the [`uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/uninstall.sh) script?

The in-app uninstall is a **soft disable**: reversible, settings-preserving, and runtime-controlled. The [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) script performs **hard deletion**: it removes the application bundle and executes `defaults delete` to purge all persisted state including feature flags.