FeatureCatalog.swift in Vorssaint: Centralized Feature Management Deep Dive

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 repository defines how the macOS utility suite exposes, groups, and controls access to every functional module. Located at 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 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.

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.

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:

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

Controlling Availability and Persistence

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:

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:

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 references for persistence keys

This architecture ensures that adding a new feature requires changes only in FeatureCatalog.swift and the feature's implementation—UI, permissions, and runtime automatically adapt.

---

Summary

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 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).

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