feat(plugin): add a searchable Mac Settings workspace with live controls and portable profiles

[xcv58]

Summary

Add a dedicated Mac Settings plugin that provides a searchable, unified workspace for viewing and changing supported macOS settings.

The primary use case is everyday control of the current Mac:

• Search for a setting without navigating through System Settings
• Toggle switches directly
• Adjust sliders and menus inline
• Favorite frequently used settings
• Review recently changed settings
• See when a setting requires a logout, restart, permission, supported device, or manual System Settings step

Profiles, import/export, comparison, and sharing are secondary advanced capabilities. They should support device migration and reusable configurations without dominating the normal interface.

The plugin should begin with a small, curated catalog of well-tested settings rather than attempting to expose every macOS preference.

---

Motivation

macOS contains many useful settings that are individually easy to change but difficult to discover, remember, and manage together.

Examples include:

• Three Finger Drag
• Pointer size
• Keyboard shortcuts for screen zoom
• Tap to Click
• Natural Scrolling
• Tracking speed
• Key repeat rate
• Show all filename extensions
• Finder path and status bars
• Dock auto-hide and position
• Screenshot format and destination

These settings are spread across different System Settings pages, and some change location or terminology between macOS versions.

Existing MacTools plugins already expose several system controls, but there is no single searchable interface for discovering and managing a broader set of current-Mac settings.

The intended experience is:

Open Mac Settings, search for a setting, and change it directly without hunting through System Settings.

---

Product principles

1. Current Mac first

The default screen must focus on the current Mac and its current values.

Profiles, migration, export, and comparison are advanced features reached through secondary navigation or contextual actions.

2. Inline control

Users should be able to change many settings from one searchable list without opening a separate editor for every row.

3. Honest capability reporting

MacTools must distinguish between settings that are:

• Directly changeable and verifiable
• Directly changeable but require logout or restart
• Backed by another MacTools plugin
• Hardware-dependent
• Guided manual changes
• Managed-only
• Unsupported or too fragile to expose
• Sensitive and never portable

A setting that cannot be safely changed should open the correct System Settings destination rather than displaying a nonfunctional toggle.

4. Curated rather than exhaustive

The first release should include approximately 20–30 carefully tested settings.

Reliability is more important than catalog size.

5. Dedicated plugin ownership

The feature, setting catalog, UI, profiles, history, and setting-specific behavior belong to a standalone plugin.

The host should provide only common infrastructure that is already shared or clearly reusable by multiple plugins.

6. Safe and reversible

Changes should be verified whenever possible.

Profile application and other multi-setting operations should support preview, partial selection, structured results, and rollback where the setting is known to be reversible.

---

Proposed plugin

Working plugin identity:

Directory: Plugins/MacSettings
Plugin ID: mac-settings
Display name: Mac Settings
Category: system
Settings capability: workspace

The final display name may be revisited, but the product should not be called “Mac Setup” because setup and migration are not the primary use cases.

Other possible names:

• Settings Hub
• System Controls
• Mac Controls

---

Primary user experience

Default destination: All Settings

Opening the plugin should show the current Mac’s supported settings.

The workspace should not open on a profile library, setup assistant, or comparison screen.

Suggested navigation:

Current Mac
  All Settings
  Favorites
  Recently Changed
  Needs Attention

Categories
  Accessibility
  Trackpad & Mouse
  Keyboard
  Finder
  Desktop & Dock
  Screenshots
  Display
  Power
  Network

Advanced
  Profiles
  Import & Export
  Change History

Profiles should not receive equal top-level visual weight with the live settings experience.

---

All Settings workspace

The primary workspace contains:

• Search
• Category navigation
• Inline controls
• Current values
• Favorites
• Recently changed settings
• Availability and requirement badges
• Setting details under progressive disclosure
• Optional comfortable and compact density modes

Example:

Accessibility

  Three Finger Drag
  Drag windows and items with three fingers.                [ On ]

  Pointer Size
  Make the pointer easier to see.                —————●—    1.6×

  Keyboard Shortcuts to Zoom
  Use Option–Command shortcuts to zoom.                     [ Off ]

Trackpad & Mouse

  Tap to Click                                              [ On ]
  Natural Scrolling                                         [ On ]
  Tracking Speed                                 ———————●—    7

---

Inline controls

Use controls appropriate to the setting value type:

Value type	Control
Boolean	Native switch
Small enumeration	Menu or picker
Continuous numeric value	Slider with visible value
Discrete numeric value	Stepped slider, field, or stepper
File or folder destination	Path summary and Choose action
Color	Native color well
Keyboard shortcut	Shared shortcut recorder
Guided manual setting	Open System Settings
Unsupported setting	Disabled row with explanation

The common operation should remain inline. Selecting or expanding a row may show additional information but should not be required for ordinary changes.

---

Search behavior

Search is a primary navigation mechanism, not only a way to navigate to another page.

Search results must remain directly controllable.

Search should match:

• Display title
• Description
• Category
• Apple’s current System Settings terminology
• Older macOS terminology
• Common aliases
• Natural-language phrases
• Localized synonyms

Examples:

Query	Expected result
drag window trackpad	Three Finger Drag
large cursor	Pointer Size
show extension	Show All Filename Extensions
dock disappear	Automatically Hide the Dock
screenshot jpg	Screenshot Format
zoom keyboard	Keyboard Shortcuts to Zoom

Search metadata should be defined by the setting catalog rather than embedded in the view.

---

Favorites

Users can favorite frequently changed settings.

Favorites should:

• Appear in a dedicated workspace filter
• Remain directly controllable
• Preserve user ordering where practical
• Optionally populate the plugin’s compact Feature Panel contribution

Example favorites:

• Natural Scrolling
• Dock Auto-hide
• Screenshot Format
• Pointer Size
• Stage Manager
• Tracking Speed

---

Recently Changed

Store a bounded local history of settings changed through MacTools.

Example:

Today, 3:42 PM
Natural Scrolling: On → Off

Today, 3:40 PM
Tracking Speed: 5 → 7

Yesterday
Show All Filename Extensions: Off → On

The history should help users answer:

Which recent setting change caused this behavior?

History requirements:

• Local only
• Bounded by count and age
• No sensitive values
• Clearable
• Setting-specific rollback where known to be safe
• Clear distinction between verified and unverified outcomes

Detecting changes made externally by System Settings is optional and should not be required for the MVP.

---

Needs Attention

Show only settings with an actionable issue, such as:

• Required permission missing
• Logout or restart pending
• Required hardware unavailable
• Existing provider/plugin unavailable
• Last apply attempt failed
• Manual System Settings step incomplete
• Current value could not be verified

Do not create an empty permanent diagnostics dashboard when nothing needs attention.

---

Feature Panel contribution

The plugin may contribute a compact Feature Panel section for selected favorites and status.

Example:

Mac Settings
4 favorites · 1 needs attention

Natural Scrolling              [ On ]
Dock Auto-hide                 [ Off ]
Three Finger Drag              [ On ]
Screenshot Format              JPEG

Open All Settings…

The Feature Panel is a quick-access surface. The complete catalog belongs in the plugin workspace.

---

Advanced profiles

Profiles are a secondary feature for:

• Moving selected settings to another Mac
• Sharing a configuration
• Testing a received profile
• Reapplying a known group of desired values
• Keeping reusable configurations such as Travel or Accessibility Focus

Profiles should be reachable through the Advanced section and contextual actions such as:

• Save Selected Settings as Profile
• Capture Current Category as Profile
• Import Profile
• Export Profile
• Apply Profile

The default workspace must not require users to understand profiles.

---

Profile inclusion model

A profile setting requires three logical states:

Not included
Included with desired value Off
Included with desired value On

A Boolean switch alone cannot represent the difference between:

• “Turn this setting off”
• “Do not change this setting”

Use a separate inclusion control plus the normal value control.

Example:

☑  Three Finger Drag       Current: Off        Desired: [ On ]
☐  Full Keyboard Access   Current: Off        Desired: [ Off ]

Rules:

• The leading checkmark means the profile manages this setting.
• The normal control represents the desired value.
• Changing the desired value automatically includes the setting.
• Unchecking the row removes the setting from the profile without changing its current Mac value.
• Category-level Select All and Deselect All should be available.
• Off remains a real desired value and must not be treated as excluded.

This model should also work for sliders, menus, colors, paths, and other non-Boolean settings.

---

Profile import and apply flow

Comparison is a contextual step, not a permanent main destination.

Suggested flow:

Import or choose profile
        ↓
Preview profile metadata
        ↓
Compare with current Mac
        ↓
Select individual differences
        ↓
Create rollback point
        ↓
Apply and verify

The comparison view should show:

Setting	Current	Desired	Apply	Status
Three Finger Drag	Off	On	Selected	Ready
Pointer Size	1.0	1.6	Selected	Ready
Tap to Click	On	On	Not selected	Already matches
Dock Position	Bottom	Left	Selected	Requires logout
Privacy permission	Not granted	Granted	Not selected	Manual

Users must be able to skip any individual change without modifying the saved profile.

Applying a profile should never be one opaque “restore everything” operation.

---

Structured apply results

Report results separately:

• Applied and verified
• Already matched
• Applied but pending logout or restart
• Skipped by user
• Guided manual step
• Unsupported on this Mac
• Provider unavailable
• Failed and rolled back
• Failed without a safe rollback
• Verification unavailable

Partial success must not be displayed as complete success.

---

Profile format

Use a versioned MacTools-specific format, such as:

My Settings.mactoolsprofile

The format should contain:

• Format version
• Creation and modification dates
• Source macOS version
• Source MacTools version
• Optional profile name and description
• Stable setting IDs
• Typed desired values
• Optional category metadata
• Compatibility metadata where useful

It must not contain:

• Arbitrary shell commands
• Raw implementation paths
• Passwords
• Keychain data
• Apple Account information
• Wi-Fi credentials
• TCC privacy grants
• FileVault recovery data
• Touch ID data
• Secure tokens
• SIP state
• Certificates or private keys
• Device enrollment information
• Machine identifiers
• Browser cookies or authentication data

Import should always provide a preview before applying anything.

---

Setting capability model

Every setting should be assigned an execution class.

Suggested model:

enum SystemSettingExecutionClass: Codable, Sendable {
    case directVerified
    case directRequiresLogout
    case directRequiresRestart
    case existingPluginProvider
    case guidedManual
    case hardwareDependent
    case managedOnly
    case unsupported
}

Additional metadata should describe:

• Minimum and maximum supported macOS versions
• Required hardware
• Required permissions
• Portability
• Sensitivity
• Whether the value can be reset
• Whether the change can be rolled back
• Whether verification is available
• Search keywords and synonyms
• Exact System Settings destination where applicable

---

Illustrative value model

enum SystemSettingValue: Codable, Equatable, Sendable {
    case boolean(Bool)
    case integer(Int)
    case decimal(Double)
    case choice(id: String)
    case string(String)
    case url(URL)
    case color(SystemSettingColor)
}

A saved profile stores stable IDs and typed values. It should not store implementation commands.

---

Plugin ownership

The Mac Settings plugin should own:

• Setting catalog
• Setting metadata
• Search synonyms
• Categories
• Current-value presentation
• Read/write/verification adapters
• Favorites
• Recently changed history
• Needs Attention state
• Profile models and storage
• Profile import/export
• Compare and apply UI
• Setting-specific rollback behavior
• Feature Panel contribution
• Canonical Mac Settings actions
• Plugin workspace UI

Suggested source organization:

Plugins/MacSettings/
  Bundle/
  Resources/
  Sources/
    MacSettingsPlugin.swift
    MacSettingsWorkspaceView.swift
    MacSettingsController.swift

    Catalog/
      SystemSettingDefinition.swift
      SystemSettingCatalog.swift
      SystemSettingMetadata.swift
      SystemSettingValue.swift

    Adapters/
      AccessibilitySettingAdapters.swift
      FinderSettingAdapters.swift
      DockSettingAdapters.swift
      ScreenshotSettingAdapters.swift

    Profiles/
      SystemSettingsProfile.swift
      SystemSettingsProfileStore.swift
      SystemSettingsProfileImport.swift
      SystemSettingsProfilePlanner.swift
      SystemSettingsProfileApplyCoordinator.swift

    History/
      SystemSettingChangeHistory.swift
      SystemSettingRollback.swift

  Tests/

The exact structure may change during implementation.

---

Host boundary

The host should continue owning shared infrastructure that already serves multiple plugins, such as:

• Plugin workspace hosting
• Plugin lifecycle
• Canonical action registration and execution
• Global shortcut assignment
• Unified Search navigation
• Common permission presentation
• Common progress and cancellation presentation
• Safe deep links
• Portable plugin preference backup bridge
• Shared system context where already justified

The host should not own:

• The Mac Settings catalog
• The Mac Settings sidebar or workspace
• Profile creation
• Profile comparison
• Setting-specific compatibility rules
• Setting-specific rollback
• The profile file format
• Import/export screens

Do not add a host-wide system-setting platform solely for this first implementation.

---

Existing plugin integration

Several existing plugins already own behavior relevant to this workspace, including appearance, Dock behavior, menu-bar behavior, Stage Manager, input behavior, display controls, and other system toggles.

Mac Settings should not create competing implementations.

Preferred integration order:

1. Reuse an existing shared service

Where an existing plugin already delegates to a reusable service, Mac Settings should use the same service.

2. Explicit state and desired-value integration

For a simple setting, the provider may expose:

• Current value
• Explicit Set On operation
• Explicit Set Off operation
• Availability
• Verification result

A toggle-only action is insufficient for profiles because applying a desired value must be deterministic.

3. Plugin-owned adapter

For settings not represented elsewhere, Mac Settings may own the adapter directly.

A future optional contribution protocol may be introduced only after a concrete need is demonstrated.

Illustrative future shape:

@MainActor
public protocol PluginSystemSettingContributing: AnyObject {
    var systemSettingContributions: [PluginSystemSettingContribution] { get }
}

This protocol is not required for the first implementation.

---

Initial candidate settings

The exact list depends on the Phase 0 feasibility audit.

Accessibility

• Three Finger Drag
• Pointer Size
• Keyboard Shortcuts to Zoom
• Scroll Gesture with Modifier to Zoom
• Full Keyboard Access
• Sticky Keys
• Slow Keys

Trackpad and Mouse

• Tap to Click
• Natural Scrolling
• Tracking Speed
• Secondary Click
• Scroll Speed where reliably supported

Keyboard

• Key Repeat Rate
• Delay Until Repeat
• Function Key behavior where reliable

Finder

• Show All Filename Extensions
• Show Path Bar
• Show Status Bar
• New Finder Window Destination
• Search Current Folder preference

Desktop and Dock

• Automatically Hide the Dock
• Dock Position
• Dock Magnification
• Menu Bar Auto-hide
• Stage Manager where existing integration is available

Screenshots

• Screenshot Format
• Screenshot Destination
• Show Floating Thumbnail
• Include Window Shadow

Appearance

• System, Light, or Dark appearance
• Other appearance settings only where they can be safely read, applied, and verified

This list is exploratory. Inclusion in the issue does not guarantee technical support.

---

Phase 0: feasibility audit

Before committing the final MVP catalog, audit every candidate setting.

For each setting, record:

• Current-value read method
• Write method
• Verification method
• Supported macOS versions
• Required hardware
• Required permission
• Whether an existing MacTools plugin already owns the behavior
• Logout or restart requirement
• Rollback behavior
• Portability
• Sensitivity
• System Settings destination
• Relevant tests
• Whether the method relies on public, documented, private, or preference-domain behavior

Classify every candidate as:

Direct and verifiable
Direct but requires logout/restart
Existing MacTools provider
Guided manual only
Hardware-dependent
Managed-only
Unsupported or too fragile

Do not expose a direct control until its behavior and limitations are understood.

---

Proposed implementation phases

Phase 1 — Plugin foundation and live catalog

• Add the Mac Settings plugin package
• Add typed setting IDs, values, schemas, and metadata
• Add the setting registry inside the plugin
• Add capability and compatibility evaluation
• Add read, apply, and verify contracts
• Add deterministic test adapters
• Complete the Phase 0 audit for the first catalog
• Implement 10–15 representative settings

Phase 2 — Current Mac workspace

• Add All Settings as the default destination
• Add category navigation
• Add searchable inline controls
• Add search synonyms and natural-language keywords
• Add direct, restart-dependent, manual, and unsupported row states
• Add setting detail disclosure
• Add keyboard navigation and VoiceOver
• Add verification feedback
• Expand the catalog toward approximately 20–30 settings

Phase 3 — Everyday organization

• Add Favorites
• Add favorite ordering
• Add Recently Changed
• Add Needs Attention
• Add bounded local history
• Add per-setting rollback where supported
• Add compact Feature Panel favorites
• Consider comfortable and compact workspace density

Phase 4 — Profiles

• Add profile models and versioned storage
• Add separate inclusion and desired-value controls
• Add profile creation from selected current settings
• Add category-level inclusion controls
• Add profile import and export
• Add import validation and preview
• Add current-versus-desired comparison
• Add per-change selection
• Add immutable apply plans
• Add pre-apply rollback snapshots
• Add structured partial results
• Add rollback for supported settings

Phase 5 — Integration and extension

• Reuse existing MacTools plugin behavior where appropriate
• Publish useful canonical actions
• Add safe deep links to settings and categories
• Evaluate a contribution protocol based on concrete integrations
• Add reviewed built-in profile templates
• Consider optional organization-signed profiles in a later proposal

---

Canonical actions

Potential actions include:

• Open Mac Settings
• Open Favorites
• Open a category
• Search Mac Settings
• Set a supported Boolean setting explicitly On
• Set a supported Boolean setting explicitly Off
• Apply a saved profile
• Create a snapshot
• Undo the most recent supported change

Avoid generating an excessive permanent action catalog for every possible value.

Parameterized actions may be preferable for settings that can be safely represented through typed schemas.

Actions must use the same setting adapters and verification path as the workspace.

---

Privacy and security

Requirements:

• No network service is required for the primary feature.
• Current setting values remain local.
• Sensitive values are never written to logs or histories.
• Profiles exclude credentials and privacy grants.
• Imported files are size-bounded and schema-validated.
• Unknown setting IDs are preserved only where safe and never automatically executed.
• Arbitrary commands, paths, preference domains, and scripts are rejected.
• Applying a profile cannot bypass normal MacTools safety or permission handling.
• Managed-only settings are never represented as locally enforceable.
• Manual settings must clearly state that MacTools cannot verify completion unless a supported read method exists.

---

Accessibility

The workspace must be fully keyboard and VoiceOver accessible.

Suggested behavior:

• Command-F focuses search.
• Arrow keys move through rows.
• Space toggles a selected Boolean control.
• Return expands setting details.
• Tab navigation follows visible controls.
• Search results remain directly operable.
• Category navigation exposes selected state.
• Included profile settings expose both inclusion and desired value.

Example VoiceOver description:

Three Finger Drag, included in profile, desired value On, current value Off.

Do not expose inclusion and value as one ambiguous switch.

---

Performance

• Reading the workspace must not synchronously block on slow system queries.
• Setting values should load incrementally.
• Expensive reads should be cached with explicit freshness.
• Opening search must not scan hardware or invoke shell commands synchronously.
• Applying one setting should update only the affected row.
• Plugin deactivation must stop active observers and cancellable work.
• Change-history storage must be bounded.

---

Testing

Add focused coverage for:

Catalog and schemas

• Stable setting IDs
• Duplicate IDs
• Invalid value schemas
• Invalid desired values
• Search metadata
• Localization fallback
• Compatibility evaluation

Setting adapters

• Read success and failure
• Apply success and failure
• Verification success and mismatch
• Unsupported macOS version
• Missing hardware
• Missing permission
• Logout or restart requirement
• Existing plugin provider unavailable
• Rollback support

Workspace

• Search ranking
• Category filtering
• Inline control updates
• Optimistic versus verified state
• Failure presentation
• Favorites
• Recently changed
• Needs Attention
• Keyboard navigation
• VoiceOver labels

Profiles

• Inclusion versus Boolean Off
• Changing a value automatically includes the setting
• Excluding a setting leaves the current Mac untouched
• Import validation
• Unknown setting IDs
• Unsupported setting types
• Current-versus-desired comparison
• Already-matching values
• Per-change selection
• Partial success
• Rollback
• Logout or restart pending state
• Manual steps
• No sensitive values in exported profiles

Lifecycle

• Plugin activation and deactivation
• Cancellation
• App relaunch
• macOS setting changed outside MacTools
• Permission changed while the workspace is open
• Hardware connected or removed
• Existing provider plugin installed, updated, or removed

---

Acceptance criteria

Current Mac experience

• Mac Settings is delivered as a dedicated plugin.
• Opening the plugin defaults to All Settings for the current Mac.
• Users can search settings by title, description, aliases, and category.
• Search results remain directly controllable.
• Supported settings use native inline controls.
• Users can change multiple settings without leaving the list.
• Direct changes are verified where possible.
• Verification failures are visible and do not appear successful.
• Logout, restart, permission, hardware, managed-only, manual, and unsupported states are clearly distinguished.
• Guided settings open an appropriate System Settings destination.
• The first release includes a curated, tested catalog rather than every discoverable preference.

Organization

• Users can favorite settings.
• Favorites remain directly controllable.
• MacTools records a bounded local history of plugin-originated changes.
• Needs Attention contains only actionable states.
• The Feature Panel can expose selected favorite settings without duplicating the full workspace.

Profiles

• Profiles are secondary to the current-Mac experience.
• Profiles store only explicitly included settings.
• Boolean Off is distinct from not included.
• Changing a desired value includes the setting automatically.
• Imports are previewed before application.
• Applying a profile shows current and desired values.
• Users can skip individual changes without editing the saved profile.
• Already-matching settings are not applied unnecessarily.
• Apply results distinguish success, partial success, manual steps, unavailable settings, restart requirements, and failures.
• A rollback point can be created before applying supported profile changes.
• Profiles never contain prohibited sensitive data or arbitrary executable commands.

Ownership and integration

• The plugin owns its catalog, UI, profiles, history, and setting-specific behavior.
• The host is changed only for common infrastructure with demonstrated reuse.
• Existing MacTools setting behavior is reused rather than independently duplicated.
• A host-wide setting contribution API is not required for the first version.
• Any future shared protocol preserves PluginKit compatibility.

---

Non-goals

• Replacing the macOS System Settings application
• Exposing every hidden defaults key
• Generic editing of arbitrary preference domains
• Backing up the entire Mac
• Replacing Migration Assistant
• Migrating applications, files, or user accounts
• Managing Apple Account or iCloud authentication
• Exporting passwords or Keychain contents
• Exporting Wi-Fi credentials
• Granting or transferring TCC permissions
• Managing Touch ID
• Managing FileVault recovery information
• Changing SIP or other security boundaries
• Device enrollment or full MDM replacement
• Installing arbitrary configuration profiles
• Running arbitrary shell commands from imported profiles
• Automatically applying imported profiles without review
• Enterprise compliance reporting
• Comparing several profiles as a primary navigation mode
• Building a profile recommendation engine
• Shipping hundreds of unverified settings in the first release
• Moving the feature UI or product model into the MacTools host

---

Open questions

1. Should the final display name be Mac Settings, Settings Hub, or System Controls?
2. Which 10–15 settings best represent the first implementation slice?
3. Which candidate settings already have reusable behavior in existing plugins?
4. Should comfortable and compact density both ship in the first release?
5. Should Recently Changed initially track only MacTools-originated changes?
6. How much setting detail should appear inline versus under disclosure?
7. Should profiles ship in the first plugin release or as a second phase after live controls are stable?
8. What should the final profile file extension be?
9. Should setting actions use one parameterized provider or selected static actions?
10. Which reusable host progress and rollback components already exist?
11. When is a shared plugin contribution protocol justified?
12. Which settings rely on undocumented behavior that should be excluded despite appearing technically possible?

---

UX reference

Existing exploratory mockups demonstrate:

• Searchable live controls
• Inline switches, sliders, and menus
• Profile inclusion separate from desired value
• Current-versus-desired comparison
• Selective application

The mockups should be treated as conceptual references rather than final hierarchy.

Before implementation, revise them so that:

• All Settings is the default and dominant screen.
• Profiles move under Advanced.
• The permanent My Mac / Profiles / Compare & Apply segmented control is removed.
• Compare & Apply appears only during an import or profile-application flow.
• Favorites, Recently Changed, and Needs Attention receive more emphasis.
• The Feature Panel demonstrates quick access to selected favorites.