# FeatureCatalog.swift in Vorssaint: Centralized Feature Management Deep Dive

> Explore FeatureCatalog.swift in vorssaint utils for centralized feature management. Discover how it governs features UI permissions and persistence in one Swift file.

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

---

**FeatureCatalog.swift serves as the single source of truth for all switchable capabilities in Vorssaint, governing feature enumeration, UI representation, permission requirements, and persistence in one unified Swift file.**

This core architectural component in the [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) repository defines how the macOS utility suite exposes, groups, and controls access to every functional module. Located at [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift), it enables the entire feature-toggle system that drives settings, menu panels, permission flows, and service lifecycle management.

---

## Core Responsibilities of FeatureCatalog.swift

The file consolidates ten distinct architectural concerns into a single catalog. Understanding each helps explain why Vorssaint's feature system remains maintainable as capabilities expand.

### Enumerating Every Togglable Feature

At its foundation, [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) declares the `AppFeature` enum—an exhaustive list of every module users can enable or disable. This includes window layout controls, mouse acceleration tweaks, clipboard history, fan management, and more.

```swift
enum AppFeature: String, CaseIterable {
    case windowLayout
    case mouseAcceleration
    case clipboardHistory
    case fanControl
    // ... additional features
}

```

**Reference:** Lines 15-35 define this enumeration, making every feature discoverable at compile time.

### Grouping Features for UI Organization

Features aren't presented as a flat list. The `FeatureGroup` enum (lines 38-40) creates logical sections—Windows & Dock, Mouse & Keyboard, Tools, etc.—that determine both Settings panel organization and menu bar presentation.

```swift
let toolsFeatures = AppFeature.features(in: .tools)

```

This static method maps groups to their member features, letting the UI iterate structurally without hardcoded arrays.

### Mapping Features to Visual Identity

Every feature carries an SF Symbol name via the `symbolName` computed property (lines 20-82). This eliminates icon string duplication across views:

```swift
let iconName = AppFeature.switcher.symbolName  // → "rectangle.on.rectangle"

```

### Controlling Availability and Persistence

[`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) implements a two-tier activation system. The `availabilityKey` property generates a `UserDefaults` key storing whether a feature *can* be enabled. The `isAvailable` computed property (lines 85-94) reads this:

```swift
let isDockPreviewAvailable = AppFeature.dockPreview.isAvailable

```

Separately, `enabledKeys` lists which individual defaults must be true for a feature to be considered *engaged* (lines 99-124). Features with empty `enabledKeys` operate on-demand—for example, a menu panel tile that activates when clicked rather than running continuously.

### Specifying System Permission Requirements

macOS utilities require varied entitlements. The `permissions` property (lines 150-177) declares which permissions each feature needs:

- **Accessibility** for window manipulation
- **Screen Recording** for display-related features
- **Full Disk Access** for deep system integration

The `onboardingPermissions` computed property (lines 186-204) filters these to determine which permissions require user explanation during first-time feature activation.

### Supporting Runtime Queries and Testing

Static helpers like `activeFeatures(using:permission:defaults:)` (lines 221-279 and 398-405) let the app query active features without touching production `UserDefaults`—enabling comprehensive unit testing:

```swift
let activeAccessibilityFeatures = AppFeature.activeFeatures(
    using: .accessibility,
    defaults: UserDefaults.standard
)

```

### Linking Monitor Alerts to Features

The `monitorAlertPairs` static property (lines 381-390) connects default keys to monitoring features, allowing the system hub to determine alert relevance without hardcoded mappings elsewhere.

### Exporting Default Availability Values

Finally, `availabilityDefaults` (lines 311-319) supplies a `[String: Any]` dictionary of default values—most features enabled, with selective opt-in betas requiring explicit activation.

---

## How Vorssaint Components Consume FeatureCatalog.swift

The catalog's centralized design lets multiple subsystems derive authoritative answers without redundancy.

| Consumer | Interaction Pattern |
|----------|---------------------|
| **SettingsView.swift** | Iterates `FeatureGroup` values, queries `AppFeature.features(in:)` for each section, renders tiles using `symbolName` and `isAvailable` |
| **MenuPanelView.swift** | Builds panel tiles by checking `isAvailable`; uses `symbolName` for icon display |
| **FeatureRuntime.swift** | Instantiates or tears down services based on availability changes and `enabledKeys` status |
| **Permission flows** | Consults `permissions` and `onboardingPermissions` to request and explain required entitlements |
| **Defaults.swift** | Defines the `DefaultsKey` constants that [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) references for persistence keys |

This architecture ensures that adding a new feature requires changes only in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) and the feature's implementation—UI, permissions, and runtime automatically adapt.

---

## Summary

[`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) in Vorssaint embodies several architectural best practices:

- **Single source of truth**: All feature metadata lives in one compile-time-verified location
- **Separation of availability from activation**: `isAvailable` controls exposure; `enabledKeys` control runtime engagement
- **Declarative permission requirements**: Features specify needs, the system orchestrates requests
- **Testable query interfaces**: Static methods accept injectable `UserDefaults` instances
- **UI-agnostic representation**: SF Symbol names and groupings serve multiple presentation layers

These qualities make the file indispensable to Vorssaint's modularity and maintainability.

---

## Frequently Asked Questions

### How does FeatureCatalog.swift differ from a simple feature flag system?

FeatureCatalog.swift extends beyond boolean flags. It bundles visual identity (`symbolName`), organizational grouping (`FeatureGroup`), permission requirements (`permissions`), persistence keys (`availabilityKey`), and dependency chains (`enabledKeys`) into type-safe Swift enums. According to the Vorssaint source code, this consolidation prevents the fragmentation typically seen when these concerns scatter across configuration files and view code.

### Can features be dynamically enabled without app updates?

Partially. The `isAvailable` property reads from `UserDefaults`, so availability can toggle at runtime based on user preferences or remote configuration. However, the `AppFeature` enum itself is compile-time fixed—adding entirely new capabilities requires code changes and redistribution. The architecture cleanly separates "which features exist" (static) from "which features are exposed" (dynamic).

### What happens when a feature's required permission is denied?

The `permissions` property declaratively specifies requirements, but enforcement happens in consuming code. [`FeatureRuntime.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureRuntime.swift) and permission-portal logic use these declarations to gate functionality: a feature with unmet permission requirements typically shows as unavailable or presents onboarding guidance via `onboardingPermissions` rather than failing silently.

### Why does FeatureCatalog.swift separate `availabilityKey` from `enabledKeys`?

This separation supports Vorssaint's two-stage activation model. `availabilityKey` determines whether a feature appears in the UI at all—useful for gradual rollouts or beta programs. `enabledKeys` then controls which sub-functionalities are active within an available feature. For example, a feature might be available (visible) but have its background monitoring disabled (specific key false) while its menu panel remains accessible (no enabled keys required).