Thaw

https://github.com/stonerl/thaw
Admin
Thaw is a powerful menu bar management tool for macOS, designed to hide and show menu bar items and...
Tokens:33,030
Snippets:555
Trust Score:8.4
License:GPL-3.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure Custom Hotkey

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Example demonstrating hotkey creation, setup, disabling, and updating the key combination.

```swift
// Create the hotkey
let hotkey = Hotkey(
    action: .toggleHidden,
    keyCombination: KeyCombination(
        key: .h,
        modifiers: [.control, .option]
    )
)

// Initialize it
hotkey.performSetup(with: appState)

// Later, disable it
hotkey.disable()

// Or change the key combination
hotkey.keyCombination = KeyCombination(
    key: .j,
    modifiers: [.command, .shift]
)
```

--------------------------------

### MenuBarItemManager.performSetup(with:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Initializes the manager and starts periodic enumeration of menu bar items.

```APIDOC
## performSetup(with:)

### Description
Initializes the manager and starts periodic enumeration.

### Signature
`func performSetup(with appState: AppState)`
```

--------------------------------

### URI Handler Implementation Examples

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Examples of opening a Thaw URI to set a configuration value with a callback.

```swift
NSWorkspace.shared.open(
    URL(string: "thaw://set?key=autoRehide&value=true&callback=myapp://settings")!
)
```

```bash
open "thaw://set?key=autoRehide&value=true&callback=com.example.MyApp://response"
```

--------------------------------

### EventMonitor Setup

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Initializes the event monitoring system.

```swift
func performSetup(with appState: AppState)
```

--------------------------------

### Implement AppDelegate Setup

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Handles the application lifecycle and subsystem initialization within the AppDelegate.

```swift
@NSApplicationDelegate
final class AppDelegate: NSObject, NSApplicationDelegate {
    let appState = AppState()
    
    func applicationDidFinishLaunching(_ notification: Notification) {
        appState.performSetup(launchOptions: NSApplication.shared.launchOptions)
        // At this point all subsystems are initialized and ready
    }
}
```

--------------------------------

### Hotkey Setup and Lifecycle Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Methods for registering, enabling, and disabling the hotkey functionality.

```swift
func performSetup(with appState: AppState)
```

```swift
func enable()
```

```swift
func disable()
```

--------------------------------

### ObjectStorage Usage Example

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Demonstrates using ObjectStorage to persist settings in a class.

```swift
class Settings {
    @ObjectStorage(key: "appearance", defaultValue: MenuBarAppearanceConfiguration())
    var appearance: MenuBarAppearanceConfiguration
}
```

--------------------------------

### DiagnosticLogger Usage Example

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Demonstrates initializing the logger and recording various log levels.

```swift
let log = DiagnosticLogger(category: "MenuBarManager")
log.info("Menu bar enumeration started")
log.warning("Item detection timeout")
log.error("Failed to move item: \(error)")
```

--------------------------------

### Get All Settings via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Retrieves the full settings configuration via a callback URL.

```text
thaw://get?key=all&callback=<yourapp://response>&requestId=<id>
```

```bash
open "thaw://get?key=all&callback=droppy://thaw-response&requestId=abc123"
```

--------------------------------

### Getting Settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/INDEX.md

Retrieve current application settings with an optional callback mechanism.

```APIDOC
## Getting Settings

### Description
Request current settings and receive the response via a callback URL.

### Endpoint
`thaw://get?key=[key]&callback=[url]&requestId=[id]`

### Parameters
- **key** (string) - The setting key to retrieve (e.g., 'all').
- **callback** (string) - The URL scheme to send the response to.
- **requestId** (string) - An identifier to correlate the request and response.
```

--------------------------------

### App Version Response JSON

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Example of the JSON structure returned for an app version request.

```json
{
  "requestId": "abc123",
  "status": "success",
  "key": "version",
  "data": {
    "value": "2.0.0",
    "build": "47",
    "type": "string"
  }
}
```

--------------------------------

### Manage Menu Bar Items

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Provides examples for retrieving, moving, and observing changes to menu bar items.

```swift
// Get current items
let items = appState.menuBarManager.sections[0].items  // visible section

// Find specific item
if let finder = items.first(where: { $0.sourceApplication?.bundleIdentifier == "com.example.Finder" }) {
    // Move to hidden section
    appState.menuBarManager.moveItem(finder, to: appState.menuBarManager.sections[1])
}

// Listen for item changes
appState.menuBarManager.menuBarItemManager.addObserverForItemChanges {
    print("Menu bar items changed")
}
```

--------------------------------

### Settings Response JSON

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Example of the JSON structure returned by the callback URL for a full settings request.

```json
{
  "requestId": "abc123",
  "status": "success",
  "data": {
    "appVersion": {
      "value": "2.0.0",
      "build": "47"
    },
    "global": {
      "autoRehide": {"value": true, "type": "boolean"},
      "rehideInterval": {"value": 15.0, "type": "double", "range": {"min": 1, "max": 300}},
      "rehideStrategy": {"value": "smart", "rawValue": 0, "type": "enum", "validValues": {"smart": 0, "timed": 1, "focusedApp": 2}}
    },
    "displays": {
      "37D8832A-2D66-02CA-B9F7-8F30A301B230": {
        "uuid": "37D8832A-2D66-02CA-B9F7-8F30A301B230",
        "name": "Built-in Retina Display",
        "isConnected": true,
        "isPrimary": true,
        "hasNotch": true,
        "resolution": "2560x1600",
        "useIceBar": true,
        "iceBarLocation": "mousePointer",
        "alwaysShowHiddenItems": false
      }
    }
  }
}
```

--------------------------------

### Single Setting Response JSON

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Example of the JSON structure returned for a single setting request.

```json
{
  "requestId": "uuid",
  "status": "success",
  "key": "autoRehide",
  "data": {"value": true, "type": "boolean"}
}
```

--------------------------------

### Control Event Monitoring

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Methods to start and stop the event monitoring process.

```swift
func start()
```

```swift
func stop()
```

--------------------------------

### Get Per-Display Setting via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Retrieves a setting specific to a display identified by its UUID.

```text
thaw://get?key=<setting>&display=<UUID>&callback=<yourapp://response>
```

```bash
open "thaw://get?key=useIceBar&display=37D8832A-...&callback=droppy://thaw-response"
```

--------------------------------

### Get Single Setting via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Retrieves a specific setting value via the callback URL.

```text
thaw://get?key=<setting>&callback=<yourapp://response>
```

```bash
open "thaw://get?key=autoRehide&callback=droppy://thaw-response"
```

--------------------------------

### Get Display Information via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Retrieves information for all connected displays or a specific display.

```text
thaw://get?key=displays&callback=<yourapp://response>
```

```text
thaw://get?key=display&display=<UUID>&callback=<yourapp://response>
```

--------------------------------

### Managing Custom Hotkeys

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Register and configure hotkeys using KeyCombination. Changes to hotkey properties take effect immediately after setup.

```swift
// Create a hotkey
let hotkey = Hotkey(
    action: .toggleHidden,
    keyCombination: KeyCombination(
        key: .h,
        modifiers: [.command, .option]
    )
)

// Setup and enable
hotkey.performSetup(with: appState)

// Later, disable or change
hotkey.keyCombination = KeyCombination(key: .j, modifiers: [.command, .shift])

// Check if enabled
if hotkey.isEnabled {
    print("Hotkey is active")
}
```

--------------------------------

### Listen to Mouse Events

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Example of adding a mouse down monitor; monitoring stops automatically when the monitor object is deallocated.

```swift
let mouseDownMonitor = appState.eventMonitor.addMouseDownMonitor { event in
    print("Mouse down at \(event.locationInWindow)")
}

// When done, simply let mouseDownMonitor be deallocated
// Monitoring automatically stops
```

--------------------------------

### Get App Version via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Retrieves the current application version without requiring authorization.

```text
thaw://get?key=version&callback=<yourapp://response>&requestId=<id>
```

--------------------------------

### GET thaw://set

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Updates a specific setting in Thaw and triggers a callback to the provided URL with the result.

```APIDOC
## GET thaw://set

### Description
Updates a configuration setting and returns the result to the specified callback URL.

### Endpoint
thaw://set?key={key}&value={value}&callback={url}

### Parameters
#### Query Parameters
- **key** (string) - Required - The setting key to update
- **value** (string) - Required - The value to set
- **callback** (string) - Required - The URL scheme to receive the response
```

--------------------------------

### GET thaw://get

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Requests settings data via a distributed notification broadcast. Note that this returns an acknowledgement only; full data retrieval requires a callback URL.

```APIDOC
## GET thaw://get

### Description
Broadcasts a request for settings via DistributedNotificationCenter. Returns an acknowledgement status.

### Endpoint
thaw://get?key={key}&broadcast=true&requestId={id}

### Parameters
#### Query Parameters
- **key** (string) - Required - The setting key to retrieve (e.g., 'all')
- **broadcast** (boolean) - Required - Must be set to true
- **requestId** (string) - Required - Unique identifier for the request

### Response
#### Success Response (200)
- **requestId** (string) - The original request ID
- **status** (string) - Status of the request ('ack')
- **message** (string) - Informational message

#### Response Example
{
  "requestId": "abc123",
  "status": "ack",
  "message": "Use callback URL to receive full settings data"
}
```

--------------------------------

### performSetup(launchOptions:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Initializes all application subsystems, including hotkey registration, event monitoring, and settings persistence. This method should be called once during application launch.

```APIDOC
## performSetup(launchOptions:)

### Description
Initializes all subsystems. Called once during application launch.

### Signature
`func performSetup(launchOptions: [NSApplication.LaunchOptionsKey: Any]?)`

### Parameters
- **launchOptions** ([NSApplication.LaunchOptionsKey: Any]?) - Optional - Optional launch options from NSApplication

### Notes
- Sets up hotkey registry, event monitors, settings persistence
- Initiates menu bar enumeration
- Restores previous profile or loads default layout
```

--------------------------------

### performSetup(with:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Initializes the menu bar manager and all its subsystems.

```APIDOC
## func performSetup(with appState: AppState)

### Description
Initializes the menu bar manager and all its subsystems.

### Parameters
- **appState** (AppState) - Required - The application state instance to initialize with.
```

--------------------------------

### Initialize AppState subsystems

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

The performSetup method initializes all subsystems during application launch.

```swift
func performSetup(launchOptions: [NSApplication.LaunchOptionsKey: Any]?)
```

--------------------------------

### MenuBarAppearanceEditor.performSetup(with:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Initializes the menu bar appearance editor with the provided application state.

```APIDOC
## func performSetup(with appState: AppState)

### Description
Initializes the editor with the given application state.

### Parameters
- **appState** (AppState) - Required - The application state to initialize the editor with.
```

--------------------------------

### Get application accessibility element

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Retrieves the accessibility element for a specific process ID.

```swift
static func getApplication(pid: pid_t) -> AXUIElement?
```

--------------------------------

### Retrieve All Settings via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/README.md

Requests all application settings and returns them to a specified callback URL.

```bash
open "thaw://get?key=all&callback=myapp://response&requestId=123"
```

--------------------------------

### Initialize Thaw Application

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Defines the main entry point for the application using the @main attribute and an NSApplicationDelegateAdaptor.

```swift
@main
struct IceApp: App {
    @NSApplicationDelegateAdaptor var appDelegate: AppDelegate
    
    var body: some Scene {
        SettingsWindow(appState: appDelegate.appState)
        PermissionsWindow(appState: appDelegate.appState)
    }
}
```

--------------------------------

### Open Settings URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Opens the application settings window.

```text
thaw://open-settings
```

```bash
open "thaw://open-settings"
```

--------------------------------

### Import Application Settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Loads appearance and hotkey settings from the Ice application.

```swift
static func importSettings() -> AppSettings?
```

--------------------------------

### Get window frame in screen coordinates

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Calculates the screen-coordinate bounds of a given accessibility window.

```swift
static func getWindowFrameInScreenCoordinates(_ window: AXUIElement) -> NSRect?
```

--------------------------------

### Bring settings window to front

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

Brings the settings window to the front and makes it key.

```swift
func orderFront(sender: Any?)
```

--------------------------------

### Define DisplayConfiguration

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Snapshot structure for per-display settings.

```swift
struct DisplayConfiguration: Codable {
    var displayID: CGDirectDisplayID
    var useIceBar: Bool
    var iceBarLocation: IceBarLocation
    var iceBarLayout: IceBarLayout
    var gridColumns: Int
    var alwaysShowHiddenItems: Bool
}
```

--------------------------------

### Initialize Hotkey

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Creates a new hotkey instance with a specified action and optional key combination.

```swift
init(action: HotkeyAction, keyCombination: KeyCombination? = nil)
```

--------------------------------

### thaw://open-settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Opens the settings window.

```APIDOC
## thaw://open-settings

### Description
Opens the Thaw settings window.

### Usage
`open "thaw://open-settings"`
```

--------------------------------

### Snapshot Pattern for Settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/INDEX.md

Capture and apply settings snapshots to manage profile persistence.

```swift
struct GeneralSettingsSnapshot: Codable {
    static func capture(from settings: GeneralSettings) -> Self { ... }
    func apply(to settings: GeneralSettings) { ... }
}
```

--------------------------------

### Initialize KeyCombination

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Initializes a new key combination instance.

```swift
init(key: KeyCode, modifiers: Modifiers)
```

```swift
let combo = KeyCombination(key: .h, modifiers: [.control, .option])
// Represents Ctrl+Opt+H
```

--------------------------------

### Basic URI Scheme Actions

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/INDEX.md

Trigger application actions such as toggling sections or opening interfaces via the command line.

```bash
# Toggle sections
open "thaw://toggle-hidden"
open "thaw://toggle-always-hidden"

# Open interfaces
open "thaw://search"
open "thaw://open-settings"
```

--------------------------------

### Use Modifiers

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Demonstrates creating and checking modifier sets.

```swift
let mods = Modifiers([.command, .shift])
// Represents ⌘⇧

if mods.contains(.command) { /* ... */ }
```

--------------------------------

### MenuBarSection Show Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Shows the section and all its items.

```swift
func show(animated: Bool = true)
```

--------------------------------

### WindowInfo.allWindows()

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Enumerates all windows visible to the window server, returned as an array of WindowInfo objects sorted by Z order.

```APIDOC
## static func allWindows() -> [WindowInfo]

### Description
Enumerates all windows visible to the window server.

### Returns
- **[WindowInfo]** - Array of visible windows sorted by Z order (top to bottom)
```

--------------------------------

### Integrate Thaw with Raycast via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Use these bash scripts as Raycast extensions to trigger Thaw actions or retrieve settings via URI schemes.

```bash
#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Toggle Thaw Hidden Section
# @raycast.mode silent
# @raycast.icon 🥶

# Make the request
open "thaw://toggle-hidden"
```

```bash
#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Get Thaw Settings
# @raycast.mode silent
# @raycast.icon 🥶

open "thaw://get?key=all&callback=raycast://callback&requestId=$(uuidgen)"
```

--------------------------------

### Access Application State in Swift

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/README.md

Demonstrates programmatic access to menu bar items and general settings within the Swift codebase.

```swift
let items = appState.menuBarManager.sections[0].items
appState.menuBarManager.moveItem(item, to: hiddenSection)
appState.settings.general.showOnHover = true
```

--------------------------------

### Analyze Menu Bar Colors

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Uses screen capture to determine brightness and saturation for dynamic UI tinting.

```swift
// Analyze menu bar colors
if let image = ScreenCapture.captureMenuBar(on: displayID),
   let colorInfo = ScreenCapture.analyzeAverageColor(of: image) {
    
    // Check brightness
    if colorInfo.isLight {
        // Use dark overlay
        appearance.tintColor = NSColor.black.withAlphaComponent(0.3)
    } else {
        // Use light overlay
        appearance.tintColor = NSColor.white.withAlphaComponent(0.3)
    }
    
    // Check saturation for gradient
    if colorInfo.saturation > 0.5 {
        appearance.tintKind = .gradient
    } else {
        appearance.tintKind = .solid
    }
}
```

--------------------------------

### Retrieve Display Information

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Use system_profiler to identify display UUIDs required for per-display settings.

```bash
system_profiler SPDisplaysDataType
```

--------------------------------

### Configure Display Settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Access screen information, detect display notches, and apply settings to specific displays.

```swift
// Get all displays
let displays = NSScreen.screens

// Get main display
let mainDisplay = NSScreen.main

// Check for notch
if let frame = mainDisplay?.safeAreaInsets {
    print("Display has notch")
}

// Apply per-display settings
for screen in displays {
    let displayID = screen.displayID
    appState.settings.displaySettings.setUseIceBar(true, for: displayID)
    appState.settings.displaySettings.setIceBarLocation(.mousePointer, for: displayID)
}
```

--------------------------------

### Configure and use DiagnosticLogger

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Initialize a logger with a category and record events across various severity levels.

```swift
let log = DiagnosticLogger(category: "MyModule")

// Log at different levels
log.debug("Detailed information")
log.info("General information")
log.notice("Important notice")
log.warning("Warning condition")
log.error("Error occurred")
log.fault("Critical system failure")

// View logs
// log stream --level debug --predicate 'process == "Thaw"'
```

--------------------------------

### thaw://get

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Retrieves configuration data and returns it to a specified callback URL.

```APIDOC
## thaw://get

### Description
Fetches configuration data and sends the result to the provided callback URI.

### Endpoint
thaw://get

### Query Parameters
- **key** (string) - Required - The configuration key to retrieve.
- **callback** (string) - Required - The URI scheme to receive the response data.
```

--------------------------------

### Define MenuBarAverageColorInfo and Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Structures and methods for analyzing menu bar color properties.

```swift
struct MenuBarAverageColorInfo: Hashable {
    var averageColor: NSColor
    var isLight: Bool
    var brightness: CGFloat  // 0–1
    var saturation: CGFloat  // 0–1
}
```

```swift
func isContrasting(with color: NSColor) -> Bool
```

--------------------------------

### MenuBarAppearanceEditor.previewAppearance(_:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Applies an appearance configuration temporarily for preview purposes without persisting changes.

```APIDOC
## func previewAppearance(_ appearance: MenuBarAppearanceConfiguration)

### Description
Temporarily applies appearance for preview without saving.

### Parameters
- **appearance** (MenuBarAppearanceConfiguration) - Required - The configuration to preview.
```

--------------------------------

### ProfileManager.importProfile(from:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Imports a profile from a file URL.

```APIDOC
## func importProfile(from: URL) throws -> UUID

### Description
Imports a profile from a file. Returns the UUID of the imported profile.

### Parameters
- **from** (URL) - Required - The file URL to import from.
```

--------------------------------

### MenuBarItemManager.enumerateItems()

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Discovers all menu bar items using XPC communication.

```APIDOC
## enumerateItems()

### Description
Discovers all menu bar items using XPC. This method updates the cached items property and triggers layout reconciliation if items have changed.

### Signature
`func enumerateItems() async throws -> [MenuBarItem]`

### Throws
`MenuBarItemServiceError` if XPC communication fails.

### Returns
`[MenuBarItem]` - Array of discovered items with current state.
```

--------------------------------

### Migration Execution

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Checks the current version and applies necessary data migrations.

```swift
static func migrateIfNeeded()
```

--------------------------------

### Define SettingsWindow class

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

Defines the main settings window inheriting from NSWindow.

```swift
@MainActor
final class SettingsWindow: NSWindow
```

--------------------------------

### Ice Settings Import

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Imports settings from the legacy Ice application.

```swift
static func importIceSettings()
```

--------------------------------

### Execute Thaw URI Commands

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Use the open command in the terminal to trigger Thaw URI schemes for specific display configurations.

```bash
# Enable Thaw Bar on specific display
open "thaw://set?key=useIceBar&value=true&display=37D8832A-2D66-02CA-B9F7-8F30A301B230"

# Set Thaw Bar location on specific display
open "thaw://set?key=iceBarLocation&value=iceIcon&display=ABC12345-..."

# Toggle on specific display
open "thaw://toggle?key=useIceBar&display=XYZ789-..."
```

--------------------------------

### SpaceInfo Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Methods for retrieving space IDs and active space information.

```swift
static func getAllSpaces() -> [Int]
```

```swift
static func getActiveSpace(on displayID: CGDirectDisplayID) -> Int?
```

--------------------------------

### GeneralSettingsSnapshot Structure

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Represents a snapshot of all General settings for profile persistence.

```swift
struct GeneralSettingsSnapshot: Codable {
    var showIceIcon: Bool
    var iceIcon: ControlItemImageSet
    var customIceIconIsTemplate: Bool
    var useIceBar: Bool
    var useIceBarOnlyOnNotchedDisplay: Bool
    var iceBarLocation: IceBarLocation
    var iceBarLocationOnHotkey: Bool
    var showOnClick: Bool
    var showOnDoubleClick: Bool
    var showOnHover: Bool
    var showOnScroll: Bool
    var autoRehide: Bool
    var rehideStrategyRawValue: Int
    var rehideInterval: TimeInterval
}
```

--------------------------------

### Define AppSettings class

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

The main container for user-configurable preferences, marked as an ObservableObject on the MainActor.

```swift
@MainActor
final class AppSettings: ObservableObject
```

--------------------------------

### IceSettingsImporter.importSettings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Loads appearance and hotkey settings from the legacy Ice application.

```APIDOC
## static func importSettings() -> AppSettings?

### Description
Loads all settings (appearance, hotkeys) from Ice.

### Returns
- (AppSettings?) - The imported application settings if available.
```

--------------------------------

### ProfileManager Load Profile Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Loads a complete profile from disk by its ID.

```swift
func loadProfile(id: UUID) throws -> Profile
```

--------------------------------

### Import Menu Bar Layout

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Loads the saved menu bar layout configuration from the Ice application.

```swift
static func importLayout() -> MenuBarItemLayout?
```

--------------------------------

### Implement custom view modifiers and event monitors

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Create reactive UI components using HotkeyRecorder or local event monitoring.

```swift
// Using custom modifier for hotkey recording
struct HotkeyRecorderView: View {
    @State private var keyCombination: KeyCombination?
    
    var body: some View {
        VStack {
            HotkeyRecorder(keyCombination: $keyCombination)
            Text("Selected: \(keyCombination?.description ?? "None")")
        }
    }
}

// Using local event monitor
struct InteractiveView: View {
    @State private var lastEvent: NSEvent?
    
    var body: some View {
        VStack {
            Text("Last event: \(lastEvent?.description ?? "None")")
        }
        .onLocalEvent(.leftMouseDown) { event in
            lastEvent = event
        }
    }
}
```

--------------------------------

### MenuBarOverlayPanel Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Methods for updating the appearance, positioning, and visibility of the overlay panel.

```swift
func updateAppearance(_ appearance: MenuBarAppearanceConfiguration)
```

```swift
func setPosition(menuBarFrame: NSRect)
```

```swift
func hide()
```

--------------------------------

### MenuBarAppearanceEditor.applyChanges()

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Saves the current working copy of appearance settings to the active configuration.

```APIDOC
## func applyChanges()

### Description
Saves changes from the working copy to the active appearance configuration.
```

--------------------------------

### Apply Layout

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Applies the saved layout configuration to the menu bar manager.

```swift
func apply(to manager: MenuBarItemManager, appState: AppState)
```

--------------------------------

### MenuBarAppearanceEditor Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Methods for initializing, saving, reverting, previewing, and resetting menu bar appearance settings.

```swift
func performSetup(with appState: AppState)
```

```swift
func applyChanges()
```

```swift
func revertChanges()
```

```swift
func previewAppearance(_ appearance: MenuBarAppearanceConfiguration)
```

```swift
func resetToDefaults()
```

--------------------------------

### MenuBarItemSpacingManager.applySpacing(_:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Applies custom spacing between menu bar items.

```APIDOC
## func applySpacing(_ spacing: CGFloat) async throws

### Description
Applies spacing between menu bar items via system spacing commands. May cause menu bar apps to relaunch and triggers a confirmation dialog if spacing differs per-display.

### Parameters
- **spacing** (CGFloat) - Required - The spacing in points (0–20 typical range)

### Throws
- MenuBarItemSpacingError if the spacing operation fails
```

--------------------------------

### HotkeyRegistry.register(hotkey:eventKind:action:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Registers a hotkey with the system event tap to trigger a specific action.

```APIDOC
## func register(hotkey: EventKind: action:)

### Description
Registers a hotkey with the system event tap. Returns a registration ID used for unregistration.

### Parameters
- **hotkey** (Hotkey) - Required - The hotkey instance
- **eventKind** (EventKind) - Required - .keyDown or .keyUp for when the action fires
- **action** (() -> Void) - Required - Closure to execute when the hotkey triggers

### Returns
- **UInt32?** - A registration ID, or nil if registration fails
```

--------------------------------

### ProfileManager Create Profile Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Creates a new profile with the given name and layout, returning its UUID.

```swift
func createProfile(name: String, layout: MenuBarItemLayout) throws -> UUID
```

--------------------------------

### HIDEventManager Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Methods for initializing HID handling, synthesizing mouse clicks, and managing synthetic tracking.

```swift
func performSetup(with appState: AppState)
```

```swift
func postMouseEvent(at location: NSPoint, clickCount: Int = 1)
```

```swift
func postMouseEvent(type: CGEventType, at location: NSPoint)
```

```swift
func startSyntheticMouseTracking()
```

```swift
func stopSyntheticMouseTracking()
```

--------------------------------

### Implement Thaw Unit Tests

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Use XCTest to verify state transitions and hotkey registration logic within the Thaw application.

```swift
@MainActor
class ThawTests: XCTestCase {
    var appState: AppState!
    
    override func setUp() {
        appState = AppState()
        appState.performSetup(launchOptions: nil)
    }
    
    func testSectionToggle() {
        let section = appState.menuBarManager.sections[1]
        let initialState = section.isHidden
        
        appState.menuBarManager.toggleSection(section)
        XCTAssertNotEqual(section.isHidden, initialState)
    }
    
    func testHotkey() {
        let hotkey = Hotkey(action: .toggleHidden)
        hotkey.performSetup(with: appState)
        
        XCTAssertFalse(hotkey.isEnabled)  // No key combo yet
        
        hotkey.keyCombination = KeyCombination(key: .h, modifiers: [.command])
        XCTAssertTrue(hotkey.isEnabled)
    }
}
```

--------------------------------

### Set Boolean Settings via URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Sets a boolean configuration key to true or false.

```text
thaw://set?key=<setting>&value=<true|false>
```

```bash
# Enable auto-rehide
open "thaw://set?key=autoRehide&value=true"

# Disable hover reveal
open "thaw://set?key=showOnHover&value=false"

# Enable Thaw Bar on active display
open "thaw://set?key=useIceBar&value=true"
```

--------------------------------

### isContrasting(with:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Checks if a provided color has sufficient contrast with the average color of the menu bar.

```APIDOC
## func isContrasting(with color: NSColor) -> Bool

### Description
Checks if another color has sufficient contrast with the average color.

### Parameters
- **color** (NSColor) - The color to compare against the average color.

### Returns
- **Bool** - Returns true if the colors have sufficient contrast, false otherwise.
```

--------------------------------

### MenuBarSection.show(animated:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Shows the menu bar section and its items.

```APIDOC
## func show(animated: Bool = true)

### Description
Shows the section and all its items.

### Parameters
- **animated** (Bool) - Optional - Whether the transition should be animated.
```

--------------------------------

### CustomTooltip

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

A custom styled SwiftUI tooltip component that follows mouse movement.

```APIDOC
## CustomTooltip

### Properties
- **text** (String) - Tooltip text to display
- **delay** (TimeInterval) - Delay before showing (default: 0.5s)
```

--------------------------------

### ProfileManager.createProfile(name:layout:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Creates a new profile with the specified name and layout.

```APIDOC
## func createProfile(name: String, layout: MenuBarItemLayout) throws -> UUID

### Description
Creates a new profile with the given name and layout.

### Parameters
- **name** (String) - Required - The name of the profile.
- **layout** (MenuBarItemLayout) - Required - The layout configuration.

### Returns
- **UUID** - The unique identifier of the created profile.
```

--------------------------------

### HookRunner.run(script:withInput:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Executes a shell script and returns its output.

```APIDOC
## HookRunner.run(script:withInput:)

### Description
Executes a shell script and returns its output.

### Method
`func run(script: String, withInput input: String? = nil) async throws -> String`

### Parameters
- **script** (String) - Required - Shell script content
- **withInput** (String?) - Optional - Optional stdin data

### Returns
- **String** - Captured stdout

### Throws
- **HookError** - Thrown on execution failure
```

--------------------------------

### Migration.migrateIfNeeded

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Checks the current application version and applies necessary data migrations.

```APIDOC
## static func migrateIfNeeded()

### Description
Checks the current version and applies necessary migrations to ensure data compatibility.
```

--------------------------------

### WindowInfo Retrieval Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Methods for enumerating all visible windows or retrieving information for a specific window ID.

```swift
static func allWindows() -> [WindowInfo]
```

```swift
static func window(withID: CGWindowID) -> WindowInfo?
```

--------------------------------

### SpaceInfo.getAllSpaces()

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Retrieves the identifiers for all available spaces across all connected displays.

```APIDOC
### static func getAllSpaces() -> [Int]

Returns an array of integers representing the IDs of all spaces on all displays.
```

--------------------------------

### ProfileManager Import Profile Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Imports a profile from a file and returns the new UUID.

```swift
func importProfile(from: URL) throws -> UUID
```

--------------------------------

### AXHelpers.getApplication(pid:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Retrieves the accessibility element for a specific application using its process ID.

```APIDOC
## static func getApplication(pid:)

### Description
Gets the accessibility element for an application.

### Parameters
- **pid** (pid_t) - Required - Process ID of the application

### Returns
- **AXUIElement?** - AXUIElement for the app or nil if inaccessible
```

--------------------------------

### HotkeyRecorder

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

A SwiftUI view component for capturing and recording keyboard combinations.

```APIDOC
## HotkeyRecorder

### Properties
- **keyCombination** (Binding<KeyCombination?>) - Binding to the recorded key combination
- **isRecording** (State<Bool>) - Whether the recorder is listening for input
```

--------------------------------

### openItem(withIdentifier:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Opens a menu bar item's menu (used by per-item hotkeys).

```APIDOC
## func openItem(withIdentifier identifier: String)

### Description
Opens a menu bar item's menu (used by per-item hotkeys).

### Parameters
- **identifier** (String) - Required - The unique identifier of the menu bar item.
```

--------------------------------

### Extend NSRunningApplication

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Adds helper properties to check the frontmost status and retrieve the process name of an application.

```swift
extension NSRunningApplication {
    var isFrontmost: Bool
    var processName: String?
}
```

--------------------------------

### Configure Thaw via URI Scheme

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Use the thaw:// protocol to set specific keys or toggle features on a target display identified by its UUID.

```text
thaw://set?key=<setting>&value=<value>&display=<UUID>
```

--------------------------------

### Managing Menu Bar Profiles

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Capture current menu bar layouts as snapshots and manage profile persistence through the profileManager.

```swift
// Create a profile from current state
let layoutSnapshot = MenuBarItemLayout(
    visibleItems: appState.menuBarManager.sections[0].items.map { $0.tag },
    hiddenItems: appState.menuBarManager.sections[1].items.map { $0.tag },
    alwaysHiddenItems: appState.menuBarManager.sections[2].items.map { $0.tag }
)

let profileID = try appState.profileManager.createProfile(
    name: "Work Setup",
    layout: layoutSnapshot
)

// Load and apply a profile
let profile = try appState.profileManager.loadProfile(id: profileID)
appState.profileManager.applyProfile(profile, to: appState, previousProfileID: nil)
```

--------------------------------

### Manage Search Panel and Item Discovery

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Control the search panel visibility, trigger searches via URI, or programmatically select results.

```swift
// Open search panel from hotkey
appState.menuBarManager.searchPanel.show()

// Or via URI
open "thaw://search"

// Programmatically search
appState.menuBarManager.searchPanel.updateQuery("finder")
if let firstResult = appState.menuBarManager.searchPanel.results.first {
    appState.menuBarManager.searchPanel.selectResult(at: 0)
}
```

--------------------------------

### ProfileManager Apply Profile Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Applies a profile's layout and settings to the current state.

```swift
func applyProfile(_ profile: Profile, to appState: AppState, previousProfileID: UUID?)
```

--------------------------------

### MenuBarOverlayPanel.updateAppearance(_:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Applies a new appearance configuration to the menu bar overlay.

```APIDOC
## func updateAppearance(_ appearance: MenuBarAppearanceConfiguration)

### Description
Applies the provided appearance configuration to the overlay window.

### Parameters
- **appearance** (MenuBarAppearanceConfiguration) - The configuration object defining the visual style.
```

--------------------------------

### Capture menu bar image

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Captures the menu bar of a specific display; requires Screen Recording permissions.

```swift
static func captureMenuBar(on displayID: CGDirectDisplayID) -> NSImage?
```

--------------------------------

### Hotkey Management

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Methods for configuring and controlling hotkey behavior.

```APIDOC
## performSetup(with:)

### Description
Initializes the hotkey with the provided application state.

## disable()

### Description
Disables the active hotkey.

## keyCombination (Property)

### Description
Allows updating the key combination (key and modifiers) for an existing hotkey.
```

--------------------------------

### EventTap

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/04-hotkeys-events.md

Methods for creating and controlling system event taps.

```APIDOC
## EventTap

### init(options:eventMask:handler:)
Creates an event tap with the given configuration.
- **options** (CGEventTapOptions) - Optional (default: .default)
- **eventMask** (CGEventMask) - Required
- **handler** ((CGEventTapProxy, CGEventType, CGEvent) -> CGEvent?) - Required

### enable()
Activates the event tap.

### disable()
Deactivates the event tap.
```

--------------------------------

### Handle MenuBarItemService and Spacing errors

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Use do-catch blocks to handle specific service errors and spacing operation failures.

```swift
do {
    // Enumerate menu bar items
    let items = try await appState.menuBarManager.menuBarItemManager.enumerateItems()
} catch let error as MenuBarItemServiceError {
    switch error {
    case .connectionFailure:
        log.error("Cannot connect to menu bar service")
    case .xpcError(let err):
        log.error("XPC error: \(err)")
    case .invalidResponse:
        log.error("Invalid response from service")
    case .timeout:
        log.error("Enumeration timeout")
    }
}

// Spacing errors
do {
    try await appState.menuBarManager.menuBarItemManager.applySpacing(8)
} catch let error as MenuBarItemSpacingError {
    switch error {
    case .permissionDenied:
        print("Need accessibility permission")
    case .unsupported:
        print("Spacing not supported on this Mac")
    case .commandFailed(let reason):
        print("Spacing failed: \(reason)")
    case .timeout:
        print("Spacing operation timed out")
    }
}
```

--------------------------------

### Handle System Permissions in Swift

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Check and request accessibility or screen recording permissions using the PermissionsManager and PermissionsWindow.

```swift
let permManager = appState.permissionsManager

// Check if granted
if permManager.isGranted(.accessibility) {
    print("Accessibility permission is granted")
} else {
    // Request permission (shows system dialog)
    let window = PermissionsWindow(appState: appState)
    window.showAccessibilityPermissionRequest()
}

// Screen Recording (optional)
if permManager.isGranted(.screenRecording) {
    // Can capture screenshots for tooltips
} else {
    // Request permission
    window.showScreenRecordingPermissionRequest()
}
```

--------------------------------

### Basic Actions

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/INDEX.md

Trigger application-level actions such as toggling UI sections or opening specific interfaces.

```APIDOC
## Basic Actions

### Description
Perform common application actions like toggling visibility or opening settings.

### Endpoints
- `thaw://toggle-hidden` - Toggles the hidden section.
- `thaw://toggle-always-hidden` - Toggles the always-hidden section.
- `thaw://search` - Opens the search interface.
- `thaw://open-settings` - Opens the settings window.
```

--------------------------------

### ProfileManager.applyProfile(_:to:previousProfileID:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/02-appstate-core.md

Applies a profile to the current application state.

```APIDOC
## func applyProfile(_ profile: Profile, to appState: AppState, previousProfileID: UUID?)

### Description
Applies a profile's layout and settings to the current state.

### Parameters
- **profile** (Profile) - Required - The profile to apply.
- **appState** (AppState) - Required - The target application state.
- **previousProfileID** (UUID?) - Optional - The ID of the previous profile.
```

--------------------------------

### MenuBarItemServiceConnection.enumerateMenuBarItems(on:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Requests menu bar item enumeration via XPC for a specific display.

```APIDOC
## func enumerateMenuBarItems(on displayID: CGDirectDisplayID) async throws -> [MenuBarItem]

### Description
Requests menu bar item enumeration via XPC.

### Parameters
- **displayID** (CGDirectDisplayID) - Required - The display to enumerate (typically CGMainDisplayID())

### Throws
- MenuBarItemServiceError on XPC failures

### Returns
- [MenuBarItem] - Array of items on the specified display
```

--------------------------------

### LayoutSolver presentationMode Method

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Calculates the presentation mode for a given section based on application state and available space.

```swift
static func presentationMode(
    for section: MenuBarSection,
    appState: AppState
) -> MenuBarSection.PresentationMode
```

--------------------------------

### Define Profile structure

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Represents the complete profile data structure containing settings and configuration snapshots.

```swift
struct Profile: Codable {
    var metadata: ProfileMetadata
    var layout: MenuBarItemLayout
    var generalSettings: GeneralSettingsSnapshot
    var advancedSettings: AdvancedSettingsSnapshot
    var appearanceLight: MenuBarAppearanceConfiguration
    var appearanceDark: MenuBarAppearanceConfiguration
}
```

--------------------------------

### MouseHelpers Methods

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Utility methods for querying mouse position and display information.

```APIDOC
## MouseHelpers.getMouseLocation()
- **Description**: Gets the current mouse position in screen coordinates.
- **Returns**: NSPoint

## MouseHelpers.isMouseOverMenuBar(on:)
- **Description**: Checks if the mouse is currently over the menu bar.
- **Parameters**: displayID (CGDirectDisplayID)
- **Returns**: Bool

## MouseHelpers.getDisplay(containing:)
- **Description**: Finds the display that contains a screen coordinate.
- **Parameters**: point (NSPoint)
- **Returns**: CGDirectDisplayID
```

--------------------------------

### Define Permission

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Represents system-level permissions required or requested by Thaw.

```swift
enum Permission: Hashable {
    case accessibility  // Required for moving items
    case screenRecording  // Optional: for tooltips and previews
}
```

--------------------------------

### Execute shell script with HookRunner

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Runs a shell script and returns the captured output, throwing HookError on failure.

```swift
func run(script: String, withInput input: String? = nil) async throws -> String
```

--------------------------------

### Preview appearance mode in Swift

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/06-appearance-styling.md

Sets the preview mode for the appearance editor to either light or dark.

```swift
// In the editor
appearanceEditor.previewMode = .light  // or .dark
```

--------------------------------

### WindowInfo Structure Definition

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Defines the structure for retrieving macOS window information from the window server.

```swift
struct WindowInfo
```

--------------------------------

### Define MenuBarSearchModel class

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

Initializes the search model as an observable object on the main actor.

```swift
@MainActor
final class MenuBarSearchModel: ObservableObject
```

--------------------------------

### Customize Menu Bar Appearance

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Configure tinting, shadows, borders, and shapes using the MenuBarAppearanceConfiguration object.

```swift
var appearance = MenuBarAppearanceConfiguration()

// Tinting
appearance.tintKind = .gradient
appearance.tintColor = NSColor.blue
appearance.tintColorEnd = NSColor.purple
appearance.tintOpacity = 0.8

// Styling
appearance.shadowOpacity = 0.3
appearance.shadowRadius = 6
appearance.borderOpacity = 0.5
appearance.borderWidth = 1
appearance.borderColor = NSColor.gray

// Shapes
appearance.shape.useRoundedCorners = true
appearance.shape.cornerRadius = 8

// Apply to manager
appState.menuBarManager.menuBarAppearanceManager.updateAppearance()
```

--------------------------------

### ScreenCapture.captureMenuBar(on:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Captures the menu bar on the specified display.

```APIDOC
## ScreenCapture.captureMenuBar(on:)

### Description
Captures the menu bar on the specified display. Requires Screen Recording permission.

### Method
`static func captureMenuBar(on displayID: CGDirectDisplayID) -> NSImage?`

### Parameters
- **displayID** (CGDirectDisplayID) - Required - Display ID from Core Graphics

### Returns
- **NSImage?** - NSImage of the menu bar or nil on failure
```

--------------------------------

### IceSettingsImporter.importLayout

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Loads the saved menu bar layout from the legacy Ice application.

```APIDOC
## static func importLayout() -> MenuBarItemLayout?

### Description
Loads the saved menu bar layout from Ice.

### Returns
- (MenuBarItemLayout?) - The imported layout configuration if available.
```

--------------------------------

### MenuBarItemManager.addObserverForItemChanges(perform:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/03-menubar-api.md

Registers a callback to be executed when the menu bar item list changes.

```APIDOC
## addObserverForItemChanges(perform:)

### Description
Registers a callback that fires when the item list changes.

### Signature
`func addObserverForItemChanges(perform block: @escaping () -> Void)`

### Parameters
- **block** (escaping closure) - The callback to execute upon item list changes.
```

--------------------------------

### WindowInfo.window(withID:)

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/09-utilities-accessibility.md

Retrieves information for a specific window identified by its CGWindowID.

```APIDOC
## static func window(withID: CGWindowID) -> WindowInfo?

### Description
Retrieves info for a specific window ID.

### Parameters
- **withID** (CGWindowID) - Required - The Quartz window ID to retrieve.

### Returns
- **WindowInfo?** - The window information if found, otherwise nil.
```

--------------------------------

### Show MenuBarSearchPanel

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/05-ui-components.md

Displays the search panel and focuses the search field.

```swift
func show()
```

--------------------------------

### Define MenuBarItemTag.Namespace

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/08-types-reference.md

Identifies the system subsystem that owns a specific menu bar item.

```swift
enum Namespace: String, CaseIterable, Codable {
    case systemUIServer      // System status items (battery, volume, clock)
    case controlCenter       // macOS 26+ Control Center modules
    case passwords           // Keychain/password management
    case weather             // Weather app items
    case textInputMenuAgent  // Text input method menu
    case thaw                // Thaw's own control items
    case unknown             // Unclassified items
}
```

--------------------------------

### Configuring Application Settings

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Modify general, advanced, and display-specific settings via appState. Changes are automatically persisted to UserDefaults.

```swift
// General settings
appState.settings.general.showOnHover = true
appState.settings.general.rehideInterval = 10

// Advanced settings
appState.settings.advanced.enableAlwaysHiddenSection = false
appState.settings.advanced.showMenuBarTooltips = true

// Display-specific settings
let displayID = CGMainDisplayID()
appState.settings.displaySettings.setUseIceBar(true, for: displayID)

// All changes are automatically persisted to UserDefaults
```

--------------------------------

### thaw://set

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/10-patterns-examples.md

Sets a specific configuration key to a provided value.

```APIDOC
## thaw://set

### Description
Updates a configuration setting by key.

### Endpoint
thaw://set

### Query Parameters
- **key** (string) - Required - The configuration key to update.
- **value** (string) - Required - The value to assign to the key.
```

--------------------------------

### Open Search Panel URI

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Opens the search interface and focuses the search field.

```text
thaw://search
```

```bash
open "thaw://search"
```

--------------------------------

### thaw://authorize

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Requests whitelist authorization.

```APIDOC
## thaw://authorize

### Description
Requests whitelist authorization for the calling application to access settings URIs.

### Behavior
- If app is already whitelisted: silent no-op
- If app is new: shows permission dialog with app name and intent
- After approval: app can use all settings URIs

### Usage
`open "thaw://authorize"`
```

--------------------------------

### thaw://toggle-application-menus

Source: https://github.com/stonerl/thaw/blob/main/_autodocs/07-uri-schemes.md

Toggles application menu visibility.

```APIDOC
## thaw://toggle-application-menus

### Description
Shows or hides application menu titles (File, Edit, View, etc.).

### Usage
`open "thaw://toggle-application-menus"`
```
Tokens:
Raw