Add on-monitor-changed config callback

Users often need to reload external tools (e.g. sketchybar) when monitors
are connected or disconnected. AeroSpace detects monitor changes internally
but doesn't expose a hook for it.

Uses CGDisplayReconfigurationCallback for reliable detection (NSApplication
notifications aren't delivered to agent apps). The callback fires after
layoutWorkspaces() so external tools see the final state.

Config syntax:
  on-monitor-changed = 'exec-and-forget sketchybar --reload'

Also adds monitor-changed to `aerospace subscribe` event types.

Author: willzeng274

Sources/AppBundle/GlobalObserver.swift

@@ -53,6 +53,16 @@ enum GlobalObserver {
         nc.addObserver(forName: NSWorkspace.activeSpaceDidChangeNotification, object: nil, queue: .main, using: onNotif)
         nc.addObserver(forName: NSWorkspace.didTerminateApplicationNotification, object: nil, queue: .main, using: onNotif)
 
+        // Detect monitor connect/disconnect via CoreGraphics callback.
+        CGDisplayRegisterReconfigurationCallback({ _, flags, _ in
+            // Only act on completion of a reconfiguration, not the begin phase
+            guard flags.contains(.beginConfigurationFlag) == false else { return }
+            Task { @MainActor in
+                if !TrayMenuModel.shared.isEnabled { return }
+                scheduleRefreshSession(.globalObserver("displayReconfiguration"))
+            }
+        }, nil)
+
         NSEvent.addGlobalMonitorForEvents(matching: .leftMouseUp) { _ in
             // todo reduce number of refreshSession in the callback
             //  resetManipulatedWithMouseIfPossible might call its own refreshSession

Sources/AppBundle/config/Config.swift

@@ -54,6 +54,7 @@ struct Config: ConvenienceCopyable {
     var onFocusChanged: [any Command] = []
     // var onFocusedWorkspaceChanged: [any Command] = []
     var onFocusedMonitorChanged: [any Command] = []
+    var onMonitorChanged: [any Command] = []
 
     var gaps: Gaps = .zero
     var workspaceToMonitorForceAssignment: [String: [MonitorDescription]] = [:]

Sources/AppBundle/config/parseConfig.swift

@@ -102,6 +102,7 @@ private let configParser: [String: any ParserProtocol<Config>] = [
     "on-focus-changed": Parser(\.onFocusChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     "on-mode-changed": Parser(\.onModeChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     "on-focused-monitor-changed": Parser(\.onFocusedMonitorChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
+    "on-monitor-changed": Parser(\.onMonitorChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     // "on-focused-workspace-changed": Parser(\.onFocusedWorkspaceChanged, { parseCommandOrCommands($0).toParsedConfig($1) }),
 
     "enable-normalization-flatten-containers": Parser(\.enableNormalizationFlattenContainers, parseBool),

Sources/AppBundle/layout/refresh.swift

@@ -41,6 +41,7 @@ func runRefreshSessionBlocking(
             SecureInputPanel.shared.refresh()
             try await normalizeLayoutReason()
             if shouldLayoutWorkspaces { try await layoutWorkspaces() }
+            checkOnMonitorChangedCallback()
         }
     }
 }

Sources/AppBundle/model/ServerEvent.swift

@@ -45,4 +45,8 @@ public struct ServerEvent: Codable, Sendable {
     public static func bindingTriggered(mode: String, binding: String) -> ServerEvent {
         ServerEvent(_event: .bindingTriggered, mode: mode, binding: binding)
     }
+
+    public static func monitorChanged(monitorCount: Int) -> ServerEvent {
+        ServerEvent(_event: .monitorChanged, monitorId: monitorCount)
+    }
 }

Sources/AppBundle/subscriptions.swift

@@ -30,7 +30,7 @@ func handleSubscribeAndWaitTillError(_ connection: NWConnection, _ args: Subscri
                         workspace: f.workspace.name,
                         monitorId_oneBased: f.workspace.workspaceMonitor.monitorId_oneBased ?? 0,
                     )
-                case .windowDetected, .bindingTriggered: continue
+                case .windowDetected, .bindingTriggered, .monitorChanged: continue
             }
             if await connection.writeAtomic(event, jsonEncoder).error != nil {
                 return

Sources/AppBundle/tree/Workspace.swift

@@ -132,13 +132,34 @@ extension Monitor {
     }
 }
 
+@MainActor
+var _previousMonitorCount: Int = NSScreen.screens.count
+
 @MainActor
 func gcMonitors() {
     if screenPointToVisibleWorkspace.count != monitors.count {
         rearrangeWorkspacesOnMonitors()
     }
 }
 
+/// Check if the monitor count changed since last check and fire the callback.
+/// Must be called AFTER layoutWorkspaces() so that external tools see the final state.
+@MainActor
+func checkOnMonitorChangedCallback() {
+    let current = monitors.count
+    if current != _previousMonitorCount {
+        _previousMonitorCount = current
+        broadcastEvent(.monitorChanged(monitorCount: current))
+        if config.onMonitorChanged.isEmpty { return }
+        guard let token: RunSessionGuard = .isServerEnabled else { return }
+        Task {
+            try await runLightSession(.onMonitorChanged, token) {
+                _ = try await config.onMonitorChanged.runCmdSeq(.defaultEnv, .emptyStdin)
+            }
+        }
+    }
+}
+
 extension CGPoint {
     @MainActor
     fileprivate func setActiveWorkspace(_ workspace: Workspace) -> Bool {

Sources/AppBundleTests/command/SubscribeCmdArgsTest.swift

@@ -31,7 +31,7 @@ final class SubscribeCmdArgsTest: XCTestCase {
             case .failure(let err):
                 assertEquals(err, """
                     ERROR: Can't parse 'unknown-event'.
-                           Possible values: (focus-changed|focused-monitor-changed|focused-workspace-changed|mode-changed|window-detected|binding-triggered)
+                           Possible values: (focus-changed|focused-monitor-changed|focused-workspace-changed|mode-changed|window-detected|binding-triggered|monitor-changed)
                     """)
         }
     }

Sources/Common/cmdArgs/impl/SubscribeCmdArgs.swift

@@ -61,4 +61,5 @@ public enum ServerEventType: String, Codable, CaseIterable, Sendable {
     case modeChanged = "mode-changed"
     case windowDetected = "window-detected"
     case bindingTriggered = "binding-triggered"
+    case monitorChanged = "monitor-changed"
 }

Sources/Common/util/commonUtil.swift

@@ -80,6 +80,8 @@ public enum RefreshSessionEvent: Sendable, CustomStringConvertible {
     case onFocusedMonitorChanged
     case onFocusChanged
     case onModeChanged
+    case focusFollowsMouse
+    case onMonitorChanged
 
     public var isStartup: Bool {
         if case .startup = self { return true } else { return false }
@@ -99,6 +101,8 @@ public enum RefreshSessionEvent: Sendable, CustomStringConvertible {
             case .onFocusedMonitorChanged: "onFocusedMonitorChanged"
             case .onFocusChanged: "onFocusChanged"
             case .onModeChanged: "onModeChanged"
+            case .focusFollowsMouse: "focusFollowsMouse"
+            case .onMonitorChanged: "onMonitorChanged"
         }
     }
 }