public import AppKit import ApplicationServices public import ParcelCore public import ParcelPlatform public enum EngineMenuShortcutError: Error, Equatable, Sendable { case unavailable, applicationChanged } public enum NativeDiscoverySkipReason: String, Equatable, Sendable { case deadlineExceeded, focusDeadlineExceeded, unresponsive, ownerBusy, threadUnavailable, inventoryIncomplete } public struct NativeDiscoverySkippedApplication: Equatable, Sendable { public let app: AppID public let name: String public let reason: NativeDiscoverySkipReason } public enum NativeDiscoveryError: Error, Equatable, Sendable { case timedOut } public enum NativeWindowObservation: Equatable, Sendable { case windowsChanged case frameChanged(WindowFrame) } /// A cached observation, not a live query. Workspace is the last admitted workspace, /// not proof of the window's current Space; it is nil when none was observed. public struct MinimizedWindow: Equatable, Sendable { public let window: ManagedWindow /// The last observed global frame before minimization, or the first minimized snapshot's frame. public let frame: Rect public let lastKnownWorkspace: WorkspaceKey? fileprivate let worldID: UUID fileprivate let lifetime: UInt64 fileprivate let appGeneration: UInt64 fileprivate let revision: UInt64 fileprivate let validity: AppThreadOperationValidity } public enum MinimizedWindowRestoreError: Error, Equatable, Sendable { case staleWindow(WindowID) case busy(WindowID) case unconfirmed(WindowID) } @MainActor public final class NativeEngineWorld: EngineWindowWorld, EngineSpaceWorld, EngineWindowInspectionProviding, EngineCommandWindowProviding { public var accessibilityPermissionGranted: Bool? { backend.accessibilityPermissionGranted } private struct Admission { let window: ManagedWindow let workspace: WorkspaceKey } private let identity = UUID() private let backend: any NativeEngineBackend private let scheduler: any EngineScheduler private let readUnmanagedMenuShortcuts: @MainActor (Int32) async throws -> [MenuShortcut] private let spaceController: SpaceController? private var spaceCommandActive = false private var pointerIsDown = false private var receive: (@MainActor (EnginePlatformEvent) -> Void)? private var applications: [AppID: any NativeEngineApplication] = [:] private var appInfo: [AppID: NativeApplicationInfo] = [:] private var tasks: [AppID: Task] = [:] private var refreshTask: Task? private var refreshing: [AppID: Task] = [:] private var initialInventoryApps: Set = [] private var refreshDeadlines: [AppID: any EngineCancellation] = [:] private var activeDiscoveryReads: [AppID: Int] = [:] private var initialDiscoveryDeadline: (any EngineCancellation)? private var focusDeadline: (any EngineCancellation)? private var focusTaskApp: AppID? private var discoveryWaiters: [UUID: AsyncStream>.Continuation] = [:] private var skippedReasons: [AppID: NativeDiscoverySkipReason] = [:] private var retryTurns: [AppID: any EngineCancellation] = [:] private var fullscreenReconciliations: [WindowID: (app: AppID, turn: any EngineCancellation)] = [:] private var retryTokens: [AppID: UUID] = [:] private var retryDelays: [AppID: Double] = [:] private static let discoveryBudget: Double = 2 private static let initialFocusTailBudget: Double = 0.5 private var initialDiscoveryExpired = false public private(set) var discoveryCompleted = false public var onDiscoverySkippedApplicationsChanged: (@MainActor ([NativeDiscoverySkippedApplication]) -> Void)? /// Cached partial-discovery outcomes. Names come from Workspace, never a blocked AX app. public var discoverySkippedApplications: [NativeDiscoverySkippedApplication] { skippedReasons.sorted { if $0.key.pid != $1.key.pid { return $0.key.pid < $1.key.pid } return $0.key.bundleID < $1.key.bundleID }.map { app, reason in let name = appInfo[app]?.name let identifier = app.bundleID.isEmpty ? "PID \(app.pid)" : app.bundleID return NativeDiscoverySkippedApplication( app: app, name: name.flatMap { $0.isEmpty ? nil : $0 } ?? identifier, reason: reason) } } private var focusTask: Task? private var focusActions: [UUID: (app: AppID, task: Task, completion: @MainActor (EnginePlatformFailure?) -> Void)] = [:] private var focusTaskRevision: UInt64? private var unresponsiveApps: Set = [] private var probeTurns: [AppID: any EngineCancellation] = [:] private var probeTasks: [AppID: Task] = [:] private var probeDelays: [AppID: Double] = [:] private var transitionDeadline: (any EngineCancellation)? private var suspensionSince: [DisplayID: [DisplaySuspension.Reason: Date]] = [:] private var spaceReadFailed = false private var appSuspensionExpired = false private var callbackFocusedWindows: [AppID: WindowID] = [:] private var transitioningDisplays: Set = [] private var spaceTransitionApps: [DisplayID: Set] = [:] private var placementState: State? private let newWindowTargets = NativeNewWindowTargets() private var settlingTask: Task? private var settlingTurn: (any EngineCancellation)? private var settlingApps: Set = [] private var settleRevision: UInt64 = 0 private var writingWindows: [WindowID: UInt64] = [:] private var turn: (any EngineCancellation)? private var pendingInfo: [AppID: NativeApplicationInfo] = [:] private var pendingExits: Set = [] private var pendingApps: Set = [] private var pendingFocus: AppID? private var visibilityAfterFocus: Set = [] private var detectionSource: (any DetectionTraceSource)? private var pendingDetections: [AppID: [DetectionTrace]] = [:] private var activeDetections: [ObjectIdentifier: (trace: DetectionTrace, references: Int)] = [:] private var focusSequence: UInt64 = 0 private var errorBursts: [AppID: Int] = [:] private var errorRecoveryPending: Set = [] private var pendingSpaces = false private var spaceRevision: UInt64 = 0 private var awaitingSpaceMap = false private var checkingSpaces = false private var spaceRefreshFailures: Set = [] private var spaceFailureDisplays: Set = [] private var spaceSuspended: Set = [] private var systemConflict: SystemWindowConflict? private var pendingVisibility = false private var latestVisible = NativeVisibleWindows(frames: [:], owners: [:]) private var snapshots: [WindowID: NativeWindowSnapshot] = [:] private var minimized: [WindowID: MinimizedWindow] = [:] { didSet { for (id, entry) in oldValue where minimized[id]?.revision != entry.revision { entry.validity.invalidate() restoredWorkspaces[id] = nil } } } private var restoredWorkspaces: [WindowID: WorkspaceKey] = [:] private var classifier: WindowClassifier? private var nextMinimizedRevision: UInt64 = 0 private var restoring: [WindowID: UInt64] = [:] private var admitted: [WindowID: Admission] = [:] private var lastWorkspaces: [WindowID: WorkspaceKey] = [:] private var knownFrames: [WindowID: Rect] = [:] private var screenFrames: [DisplayID: Rect] = [:] private var spaces: [DisplayID: SpaceID] = [:] private var changedSpaceDisplays: Set = [] private var confirmedWindowSpaces: [WindowID: Set] = [:] private var lifetime: UInt64 = 0 private var nextAppGeneration: UInt64 = 0 private var appGenerations: [AppID: UInt64] = [:] private var observationRevisions: [AppID: UInt64] = [:] private var refreshChanges: [AppID: Set] = [:] private enum RefreshOutcome { case applied, stale, failed } private var dropNextDestroyedEvent = false private var failNextSpaceRead = false var hasPendingReconciliation: Bool { turn != nil || refreshTask != nil || !refreshing.isEmpty || focusTask != nil || settlingTurn != nil || settlingTask != nil } var onReconciliationIdle: (@MainActor () -> Void)? public private(set) var observedFocusedWindow: WindowID? public var onWindowObservation: (@MainActor (NativeWindowObservation) -> Void)? private func signalReconciliationIdle() { guard !hasPendingReconciliation else { return } if receive != nil, initialInventoryApps.isEmpty, !discoveryCompleted { discoveryCompleted = true initialDiscoveryDeadline?.cancel() initialDiscoveryDeadline = nil finishDiscoveryWaiters(.success(())) } onReconciliationIdle?() } /// Waits for startup admissions and the final native-focus read, including explicitly skipped apps. /// A global Space/window-server stall is an error, not a partial-discovery success. public func awaitInitialDiscovery(timeout: Double = 3) async throws { precondition(timeout.isFinite && timeout > 0) try Task.checkCancellation() guard receive != nil else { throw EngineError.stopped } if discoveryCompleted { return } let id = UUID() let results = AsyncStream>.makeStream() discoveryWaiters[id] = results.continuation let deadline = scheduler.schedule(after: timeout) { results.continuation.yield(.failure(NativeDiscoveryError.timedOut)) results.continuation.finish() } defer { deadline.cancel() discoveryWaiters[id] = nil results.continuation.finish() } try await withTaskCancellationHandler { for await result in results.stream { try Task.checkCancellation() try result.get() return } throw CancellationError() } onCancel: { results.continuation.finish() } } /// Refreshes the running-app inventory and retries incomplete discovery before Tidy captures windows. public func prepareTourDiscovery() async throws { try await awaitInitialDiscovery() for _ in 0..<2 { try Task.checkCancellation() guard receive != nil else { throw EngineError.stopped } let running = backend.runningApplications() let live = Set(running.map(\.id)) for app in Set(appInfo.keys).subtracting(live) { pendingExits.insert(app) } discoveryCompleted = false initialDiscoveryExpired = false initialInventoryApps = live for info in running { cancelRetry(info.id, resetDelay: false) pendingInfo[info.id] = info if activeDiscoveryReads[info.id] == nil { recovered(info.id) pendingApps.insert(info.id) } else { initialInventoryApps.remove(info.id) } } pendingVisibility = true scheduleTurn() try await awaitInitialDiscovery() if skippedReasons.isEmpty { break } } } private func finishDiscoveryWaiters(_ result: Result) { let waiters = discoveryWaiters.values discoveryWaiters.removeAll() for waiter in waiters { waiter.yield(result) waiter.finish() } } private func finishedDiscoveryRead(_ app: AppID, generation: UInt64, appGeneration: UInt64) { guard lifetime == generation, appGenerations[app] == appGeneration else { return } guard let active = activeDiscoveryReads[app], active > 0 else { preconditionFailure("A discovery read finished without an active owner") } let remaining = active - 1 if remaining == 0 { activeDiscoveryReads[app] = nil scheduleProbe(app) scheduleTurn() } else { activeDiscoveryReads[app] = remaining } } private func skipDiscovery(_ app: AppID, reason: NativeDiscoverySkipReason, reportsTimeout: Bool = true) { refreshing.removeValue(forKey: app)?.cancel() refreshDeadlines.removeValue(forKey: app)?.cancel() if focusTaskApp == app { focusTask?.cancel() focusTask = nil focusTaskRevision = nil focusTaskApp = nil focusDeadline?.cancel() focusDeadline = nil } let newlySkipped = unresponsiveApps.insert(app).inserted let changed = skippedReasons[app] != reason skippedReasons[app] = reason releaseSpaceTransition(app) spaceRefreshFailures.remove(app) spaceFailureDisplays = displaysAffectedByFailedApps(latestVisible) newWindowTargets.clear() publishSuspension() scheduleProbe(app) if newlySkipped { receive?(.appResponsivenessChanged(app, isResponsive: false)) if reportsTimeout { receive?(.failure(.timedOut(app))) } } if changed { onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) } finishInitialInventory(app) scheduleTurn() signalReconciliationIdle() } public convenience init(applicationFilter: @escaping @MainActor (NSRunningApplication) -> Bool = { _ in true }) { self.init( backend: SystemNativeEngineBackend(applicationFilter: applicationFilter), scheduler: RunLoopEngineScheduler(), spaceController: SpaceController(reader: NativeSpaceReader())) } init( backend: any NativeEngineBackend, scheduler: any EngineScheduler, spaceController: SpaceController? = nil, readUnmanagedMenuShortcuts: @escaping @MainActor (Int32) async throws -> [MenuShortcut] = { try await MenuShortcutReader.read(pid: $0) } ) { self.backend = backend self.scheduler = scheduler self.spaceController = spaceController self.readUnmanagedMenuShortcuts = readUnmanagedMenuShortcuts } public func spaceSnapshot() async throws -> [NativeDisplaySpaces] { guard let spaceController else { throw SpaceCommandError.displayUnavailable } return try await spaceController.snapshot() } public func executeSpaceCommand( _ destination: SpaceDestination, display: DisplayID, window: WindowID?, follow: Bool ) async throws -> SpaceCommandResult { guard let spaceController else { throw SpaceCommandError.displayUnavailable } guard !spaceCommandActive else { throw SpaceCommandError.busy } spaceCommandActive = true newWindowTargets.clear() defer { spaceCommandActive = false invalidateSpaces() pendingVisibility = true scheduleTurn() } let drag: SpaceDragWindow? if let window { guard let app = snapshots[window]?.window.app, let application = applications[app] else { throw SpaceCommandError.windowUnavailable } drag = try await application.spaceDragWindow(window) } else { drag = nil } return try await spaceController.execute(destination, displayID: display.rawValue, window: drag, follow: follow) { [weak self] preparation in guard let self else { throw EngineError.stopped } try await self.prepareSpaceSwitch(preparation, excluding: window) } } public func updatePlacementState(_ state: State, classifier: WindowClassifier?, allowsSpeculation: Bool) { placementState = state self.classifier = classifier newWindowTargets.update( state, classifier: classifier, enabled: allowsSpeculation && receive != nil && !checkingSpaces && systemConflict == nil && !spaceCommandActive) } private func prepareSpaceSwitch(_ preparation: SpaceController.SwitchPreparation, excluding window: WindowID?) async throws { let interval = NativeEventTrace.spaceRetile(preparation.destination) defer { NativeEventTrace.endSpaceRetile(interval) } guard receive != nil else { throw EngineError.stopped } guard let state = placementState else { return } let displays = state.displays.values.filter { preparation.displayID == "Main" || $0.id.rawValue.caseInsensitiveCompare(preparation.displayID) == .orderedSame } var batches: [AppID: [WindowFrame]] = [:] for display in displays.sorted(by: { $0.id < $1.id }) { let key = WorkspaceKey(display: display.id, space: SpaceID(rawValue: preparation.destination)) var destination = state if let window, let managed = state.windows[window], state.workspace(containing: window)?.display == display.id { destination = reduce(state, .windowAppeared(managed, workspace: key, frame: display.frame)).0 } guard let workspace = destination.workspaces[key] else { continue } let frames = LayoutEngine.arrange(workspace, in: display.frame, windows: destination.windows).frames for (id, frame) in frames where id != window { guard let app = destination.windows[id]?.app else { continue } pendingApps.insert(app) guard applications[app] != nil else { receive?(.failure(.appUnavailable(app))) continue } guard !unresponsiveApps.contains(app), refreshing[app] == nil else { continue } batches[app, default: []].append(WindowFrame(window: id, frame: frame)) } } guard !batches.isEmpty else { return } let generation = lifetime let completion = AsyncStream.makeStream() let deadline = scheduler.schedule(after: 0.1) { completion.continuation.finish() } // AX calls cannot be interrupted; the command must not wait for their task scope to drain. let preparations = batches.map { app, frames in Task { @MainActor [weak self] in defer { completion.continuation.yield(app) } guard let self, self.isCurrent(generation), let application = self.applications[app], let appGeneration = self.appGenerations[app] else { return } do { let requests = frames.sorted(by: { $0.window < $1.window }).map { EngineFrameWrite( window: $0.window, frame: $0.frame, transaction: generation, capturesInitialFrame: true) } let receipt = try await application.writeFrames(requests) guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } for failure in receipt.failures { self.receive?(.failure(failure)) } let confirmed = Set(receipt.frames.map(\.window)) for frame in frames where !confirmed.contains(frame.window) { self.receive?( .failure( Self.failure( AXPlatformError.unexpectedValue("Space preparation readback"), app: app, window: frame.window))) } for frame in receipt.frames { if let initial = receipt.initialFrames.first(where: { $0.window == frame.window }), let request = requests.first(where: { $0.window == frame.window }) { self.emit( .placementReadBack(initial: initial.frame, target: request.frame, final: frame.frame)) } self.knownFrames[frame.window] = frame.frame self.snapshots[frame.window]?.frame = frame.frame } } catch { guard self.isCurrent(generation) else { return } self.report(error, app: app) } } } defer { deadline.cancel() completion.continuation.finish() for task in preparations { task.cancel() } } var unfinished = Set(batches.keys) for await app in completion.stream { unfinished.remove(app) if unfinished.isEmpty { break } } try Task.checkCancellation() for app in unfinished { for frame in batches[app] ?? [] { receive?(.failure(Self.failure(AXPlatformError.timedOut, app: app, window: frame.window))) } } } public func inspectionWindow(_ id: WindowID) -> ManagedWindow? { snapshots[id]?.window } /// Returns only windows known to be minimized, without querying Accessibility or WindowServer. /// Native snapshots do not identify a minimized window's current Space or display. public var minimizedWindows: [MinimizedWindow] { minimized.values.filter { isTabViewEligible($0.window) }.sorted { $0.window.id < $1.window.id } } /// Restores the observed window and schedules reconciliation. Tile placement is not guaranteed. public func restore(window: MinimizedWindow) async throws { let id = window.window.id let app = window.window.app try Task.checkCancellation() guard window.worldID == identity, isCurrent(window.lifetime), appGenerations[app] == window.appGeneration, minimized[id]?.revision == window.revision, isTabViewEligible(window.window), let application = applications[app] else { throw MinimizedWindowRestoreError.staleWindow(id) } guard restoring[id] == nil else { throw MinimizedWindowRestoreError.busy(id) } restoring[id] = window.revision defer { if restoring[id] == window.revision { restoring[id] = nil } if receive != nil, lifetime == window.lifetime, appGenerations[app] == window.appGeneration { reconcile([app]) } } refreshChanges[app]?.insert(id) do { try await application.restore(id, validity: window.validity) try Task.checkCancellation() guard isCurrent(window.lifetime), appGenerations[app] == window.appGeneration, minimized[id]?.revision == window.revision else { throw MinimizedWindowRestoreError.staleWindow(id) } refreshChanges[app]?.insert(id) observationRevisions[app, default: 0] &+= 1 if let snapshot = snapshots[id] { var managed = snapshot.window managed.facts?.isMinimized = false snapshots[id] = NativeWindowSnapshot( window: managed, frame: snapshot.frame, excluded: managed.facts?.isFullScreen == true, validity: snapshot.validity) } minimized[id] = nil if let state = placementState { var candidate = window.window var facts = candidate.facts ?? WindowFacts( bundleID: app.bundleID, role: candidate.role, subrole: candidate.subrole, title: candidate.title ) facts.isMinimized = false let classification = (classifier ?? WindowClassifier()).classify(facts) candidate.isFloating = classification.disposition == .float if case .rule = classification.reason { candidate.managementReason = .rule } restoredWorkspaces[id] = state.minimizedRestoreWorkspace(for: candidate) } } catch is CancellationError { throw CancellationError() } catch let error as MinimizedWindowRestoreError { throw error } catch { if isCurrent(window.lifetime), appGenerations[app] == window.appGeneration { recordError(error, app: app) } throw Self.failure(error, app: app, window: id) } } public func focusedCommandWindow() async throws -> ManagedWindow? { guard receive != nil else { throw EngineError.stopped } guard let app = backend.focusedApplication() else { throw EngineWindowCommandError.noFocusedWindow } guard applications[app] != nil else { throw EnginePlatformFailure.appUnavailable(app) } do { guard let window = try await focusedInspectionWindow(pid: app.pid) else { throw EngineWindowCommandError.noFocusedWindow } return window } catch is CancellationError { throw CancellationError() } catch let error as EngineWindowCommandError { throw error } catch { throw Self.failure(error, app: app) } } public func focusedInspectionWindow(pid: Int32) async throws -> ManagedWindow? { guard receive != nil, let (app, application) = applications.first(where: { $0.key.pid == pid }) else { return nil } let generation = lifetime let appGeneration = appGenerations[app] let id = try await application.focusedWindow() guard isCurrent(generation), appGenerations[app] == appGeneration else { throw EnginePlatformFailure.appUnavailable(app) } return id.flatMap { snapshots[$0]?.window } } public func menuShortcuts(pid: Int32) async throws -> [MenuShortcut] { try Task.checkCancellation() // Setup checks run before the world has started; stopping still invalidates every in-flight read. guard receive != nil || lifetime == 0 else { throw EngineMenuShortcutError.unavailable } let generation = lifetime if receive != nil, !applications.keys.contains(where: { $0.pid == pid }), let info = backend.runningApplications().first(where: { $0.id.pid == pid }) { attach(info) pendingApps.insert(info.id) scheduleTurn() guard applications[info.id] != nil else { throw EngineMenuShortcutError.unavailable } } if let (app, application) = applications.first(where: { $0.key.pid == pid }) { let appGeneration = appGenerations[app] let shortcuts = try await application.menuShortcuts() try Task.checkCancellation() guard isCurrent(generation), appGenerations[app] == appGeneration else { throw EngineMenuShortcutError.applicationChanged } return shortcuts } let shortcuts = try await readUnmanagedMenuShortcuts(pid) try Task.checkCancellation() guard lifetime == generation else { throw EngineMenuShortcutError.applicationChanged } return shortcuts } public func setDetectionTracing(_ source: (any DetectionTraceSource)?) { if source == nil, detectionSource == nil { return } precondition(receive == nil, "Detection tracing must be configured before starting") detectionSource = source backend.setDetectionTracing(source) } private func emit(_ event: EnginePlatformEvent, detections: [DetectionTrace]? = nil) { if let detections { receive?(.detected(event, traces: detections)) } else { receive?(event) } } private func trackDetections(_ traces: [DetectionTrace]?) { for trace in traces ?? [] { trace.retainDelivery() let id = ObjectIdentifier(trace) let references = activeDetections[id]?.references ?? 0 activeDetections[id] = (trace, references + 1) } } private func releaseDetections(_ traces: [DetectionTrace]?) { for trace in traces ?? [] { let id = ObjectIdentifier(trace) if let active = activeDetections[id] { precondition(active.references > 0) activeDetections[id] = active.references == 1 ? nil : (trace, active.references - 1) } trace.releaseDelivery() } } private func retainDetection(_ trace: DetectionTrace?, for app: AppID) { guard detectionSource != nil, let trace else { return } trace.retainDelivery() pendingDetections[app, default: []].append(trace) } public func start(receive: @escaping @MainActor (EnginePlatformEvent) -> Void) throws { guard self.receive == nil else { return } lifetime += 1 self.receive = receive let generation = lifetime let environment = ProcessInfo.processInfo.environment dropNextDestroyedEvent = Self.e2eDropOneDestroyedArmed(environment) #if DEBUG failNextSpaceRead = environment["PARCEL_E2E"] == "1" && environment["PARCEL_E2E_FAIL_FIRST_SPACE_READ"] == "1" && !(environment["PARCEL_E2E_TOKEN"] ?? "").isEmpty #endif do { let targets = newWindowTargets backend.setNewWindowTarget { targets.take($0) } try backend.start { [weak self] event in guard let self, self.lifetime == generation, self.receive != nil else { return } self.route(event) } updateDisplays(try backend.currentDisplays()) let running = backend.runningApplications() initialInventoryApps = Set(running.map(\.id)) for info in running { pendingInfo[info.id] = info pendingApps.insert(info.id) } if initialInventoryApps.isEmpty { scheduleInitialFocus() } scheduleTurn() } catch { stop() throw error } } private func startInitialDiscoveryDeadline(generation: UInt64) { guard !discoveryCompleted, !initialDiscoveryExpired, initialDiscoveryDeadline == nil else { return } // Only AX work shares this deadline; global discovery stalls have their own waiter's timeout. initialDiscoveryDeadline = scheduler.schedule(after: Self.discoveryBudget) { [weak self] in guard let self, self.lifetime == generation, !self.discoveryCompleted else { return } self.initialDiscoveryDeadline = nil self.initialDiscoveryExpired = true let focused = self.focusTaskApp let focusRevision = self.focusTaskRevision let reading = self.initialInventoryApps.filter { self.refreshing[$0] != nil } for app in reading { self.skipDiscovery(app, reason: .deadlineExceeded) } if let focused, self.focusTaskRevision == focusRevision { self.skipDiscovery(focused, reason: .focusDeadlineExceeded) } self.signalReconciliationIdle() } } private func finishInitialInventory(_ app: AppID) { guard initialInventoryApps.remove(app) != nil, initialInventoryApps.isEmpty else { return } scheduleInitialFocus() } private func scheduleInitialFocus() { // Background startup admissions can change reducer focus, so read native focus after the whole inventory. pendingFocus = nil focusSequence &+= 1 guard let app = backend.focusedApplication() else { return } startFocusRead(app, generation: lifetime, revision: focusSequence, detections: nil) } public func stop() { let wasPending = hasPendingReconciliation backend.stop() lifetime += 1 receive = nil observedFocusedWindow = nil cancelFocusActions() cancelSettleReconciliation(notifyIdle: false) writingWindows.removeAll() pointerIsDown = false turn?.cancel() turn = nil refreshTask?.cancel() refreshTask = nil for task in refreshing.values { task.cancel() } refreshing.removeAll() initialInventoryApps.removeAll() for deadline in refreshDeadlines.values { deadline.cancel() } refreshDeadlines.removeAll() activeDiscoveryReads.removeAll() initialDiscoveryDeadline?.cancel() initialDiscoveryDeadline = nil initialDiscoveryExpired = false focusDeadline?.cancel() focusDeadline = nil focusTaskApp = nil discoveryCompleted = false finishDiscoveryWaiters(.failure(EngineError.stopped)) skippedReasons.removeAll() for retry in retryTurns.values { retry.cancel() } retryTurns.removeAll() for pending in fullscreenReconciliations.values { pending.turn.cancel() } fullscreenReconciliations.removeAll() retryTokens.removeAll() retryDelays.removeAll() focusTask?.cancel() focusTask = nil focusTaskRevision = nil unresponsiveApps.removeAll() for turn in probeTurns.values { turn.cancel() } for task in probeTasks.values { task.cancel() } probeTurns.removeAll() probeTasks.removeAll() probeDelays.removeAll() transitionDeadline?.cancel() transitionDeadline = nil suspensionSince.removeAll() spaceReadFailed = false appSuspensionExpired = false callbackFocusedWindows.removeAll() refreshChanges.removeAll() transitioningDisplays.removeAll() spaceTransitionApps.removeAll() placementState = nil newWindowTargets.reset() for task in tasks.values { task.cancel() } tasks.removeAll() for application in applications.values { application.shutdown() } applications.removeAll() appInfo.removeAll() appGenerations.removeAll() observationRevisions.removeAll() visibilityAfterFocus.removeAll() pendingInfo.removeAll() pendingExits.removeAll() pendingApps.removeAll() pendingFocus = nil for traces in pendingDetections.values { for trace in traces { trace.finish(.dropped) } } pendingDetections.removeAll() for active in activeDetections.values { active.trace.finish(.dropped) } activeDetections.removeAll() detectionSource = nil backend.setDetectionTracing(nil) focusSequence &+= 1 errorBursts.removeAll() errorRecoveryPending.removeAll() pendingSpaces = false spaceRevision &+= 1 checkingSpaces = false awaitingSpaceMap = false spaceRefreshFailures.removeAll() spaceFailureDisplays.removeAll() spaceSuspended.removeAll() systemConflict = nil pendingVisibility = false snapshots.removeAll() minimized.removeAll() restoredWorkspaces.removeAll() classifier = nil restoring.removeAll() admitted.removeAll() lastWorkspaces.removeAll() knownFrames.removeAll() screenFrames.removeAll() spaces.removeAll() changedSpaceDisplays.removeAll() confirmedWindowSpaces.removeAll() dropNextDestroyedEvent = false failNextSpaceRead = false if wasPending { signalReconciliationIdle() } } isolated deinit { stop() } // The e2e harness drops one event to reproduce a missed AX notification deterministically. private static func e2eDropOneDestroyedArmed(_ environment: [String: String]) -> Bool { #if DEBUG environment["PARCEL_E2E"] == "1" && environment["PARCEL_E2E_DROP_ONE_DESTROYED"] == "1" && !(environment["PARCEL_E2E_TOKEN"] ?? "").isEmpty #else false #endif } public func write( _ frames: [EngineFrameWrite], for app: AppID, completion: @escaping @MainActor (EngineWriteReceipt) -> Void ) { guard let application = applications[app] else { completion(EngineWriteReceipt(frames: [], failures: [.appUnavailable(app)], duration: 0)) return } guard !unresponsiveApps.contains(app) else { completion(EngineWriteReceipt(frames: [], failures: [.timedOut(app)], duration: 0)) return } cancelSettleReconciliation() let generation = lifetime let appGeneration = appGenerations[app] for write in frames { writingWindows[write.window] = write.generation } let interval = MotionWriteTrace.beginBatch() var pending = true var deadline: (any EngineCancellation)? let finish: @MainActor (EngineWriteReceipt) -> Void = { receipt in guard pending else { return } pending = false deadline?.cancel() deadline = nil MotionWriteTrace.endBatch(interval, jobDuration: receipt.duration) if self.lifetime == generation, self.receive != nil, self.appGenerations[app] == appGeneration { for observed in receipt.frames { self.knownFrames[observed.window] = observed.frame self.snapshots[observed.window]?.frame = observed.frame self.onWindowObservation?(.frameChanged(observed)) } for write in frames where write.isFinal || !receipt.failures.isEmpty { if self.writingWindows[write.window] == write.generation { self.writingWindows[write.window] = nil } } for failure in receipt.failures { self.recordError(failure, app: app) } } completion(receipt) } let task = Task { @MainActor in let receipt: EngineWriteReceipt do { receipt = try await application.writeFrames(frames) } catch { receipt = EngineWriteReceipt(frames: [], failures: [Self.failure(error, app: app)], duration: 0) } guard pending else { return } if self.isCurrent(generation), self.appGenerations[app] == appGeneration, receipt.failures.contains(where: { failure in switch failure { case .timedOut: true case .accessibility(_, _, let cause): cause == .timedOut case .appThread(_, let cause): cause == .operationOverdue default: false } }) { self.skipDiscovery(app, reason: .deadlineExceeded, reportsTimeout: false) } finish(receipt) } deadline = scheduler.schedule(after: Self.discoveryBudget) { guard pending else { return } task.cancel() if self.lifetime == generation, self.receive != nil, self.appGenerations[app] == appGeneration { self.skipDiscovery(app, reason: .deadlineExceeded) } finish(EngineWriteReceipt(frames: [], failures: [.timedOut(app)], duration: Self.discoveryBudget)) } } public func stopRestoringFrameWrites() async -> [EnginePlatformFailure] { let stopping = applications stop() var failures: [EnginePlatformFailure] = [] for (app, application) in stopping { do { try await application.finishShutdown() } catch { failures.append(Self.failure(error, app: app)) } } return failures } public func cancelFrameWrites(_ window: WindowID, for app: AppID, throughGeneration: UInt64) { guard let application = applications[app] else { return } if let active = writingWindows[window], active <= throughGeneration { writingWindows[window] = nil } let generation = lifetime let appGeneration = appGenerations[app] Task { @MainActor in do { try await application.cancelFrameWrites(window, throughGeneration: throughGeneration) } catch { guard isCurrent(generation), appGenerations[app] == appGeneration else { return } report(error, app: app, window: window) } } } public func reconcileFrames(_ apps: Set) { guard receive != nil else { return } settlingApps.formUnion(apps.filter { applications[$0] != nil }) guard !settlingApps.isEmpty, settlingTurn == nil, settlingTask == nil else { return } settlingTurn = scheduler.schedule(after: 0) { [weak self] in self?.reconcileSettledFrames() } } private func reconcileSettledFrames() { settlingTurn = nil let apps = settlingApps settlingApps.removeAll() let generation = lifetime let revision = settleRevision settlingTask = Task(priority: .utility) { @MainActor in defer { if revision == settleRevision { settlingTask = nil if !settlingApps.isEmpty { reconcileFrames(settlingApps) } signalReconciliationIdle() } } do { let visible = try await backend.visibleWindows() guard !Task.isCancelled, isCurrent(generation), revision == settleRevision else { return } var missingApps: Set = [] for id in snapshots.keys.sorted() { guard var observed = snapshots[id], apps.contains(observed.window.app), writingWindows[id] == nil else { continue } if let frame = visible.frames[id] { if knownFrames[id] != frame { observed.frame = frame snapshots[id] = observed observe(observed, origin: .reconciled) } } else if let anchored = visibleSnapshot(observed, in: visible.frames) { snapshots[id] = anchored observe(anchored, origin: .reconciled) } else if admitted[id] != nil, !isOnInactiveSpace(id), appInfo[observed.window.app]?.isHidden != true { missingApps.insert(observed.window.app) } } reconcile(missingApps) MotionWriteTrace.reconcile(axCalls: 0) } catch { guard !Task.isCancelled, isCurrent(generation), revision == settleRevision else { return } receive?(.failure(Self.failure(error))) } } } private func cancelSettleReconciliation(notifyIdle: Bool = true) { let wasPending = onReconciliationIdle != nil && (settlingTurn != nil || settlingTask != nil) settleRevision += 1 settlingTurn?.cancel() settlingTurn = nil settlingTask?.cancel() settlingTask = nil settlingApps.removeAll() if wasPending && notifyIdle { signalReconciliationIdle() } } public func reconcile(_ apps: Set) { guard receive != nil else { return } let available = apps.filter { applications[$0] != nil } guard !available.isEmpty else { return } pendingApps.formUnion(available) pendingVisibility = true scheduleTurn() } public func focus(_ window: WindowID, completion: @escaping @MainActor (EnginePlatformFailure?) -> Void) { perform(window, completion: completion) { try await $0.focus(window) } } public func raise(_ window: WindowID, completion: @escaping @MainActor (EnginePlatformFailure?) -> Void) { perform(window, completion: completion) { try await $0.raise(window) } } public func close(_ window: WindowID) async throws { try await close(window) { _ in true } } public func toggleFullscreen(_ window: WindowID) async throws { guard let app = snapshots[window]?.window.app else { throw EnginePlatformFailure.vanished(window) } guard let application = applications[app] else { throw EnginePlatformFailure.appUnavailable(app) } let generation = lifetime let appGeneration = appGenerations[app] let entering = snapshots[window]?.window.facts?.isFullScreen != true do { try Task.checkCancellation() try await application.toggleFullscreen(window) guard isCurrent(generation), appGenerations[app] == appGeneration else { throw EngineError.stopped } reconcile([app]) scheduleFullscreenReconciliation(window, app: app, entering: entering) } catch is CancellationError { throw CancellationError() } catch { if isCurrent(generation), appGenerations[app] == appGeneration { recordError(error, app: app) } if let commandError = error as? EngineWindowCommandError { throw commandError } throw Self.failure(error, app: app, window: window) } } private func scheduleFullscreenReconciliation( _ window: WindowID, app: AppID, entering: Bool, remaining: Int = 8 ) { fullscreenReconciliations.removeValue(forKey: window)?.turn.cancel() guard remaining > 0, receive != nil, let appGeneration = appGenerations[app] else { return } let generation = lifetime let turn = scheduler.schedule(after: 0.4) { [weak self] in guard let self else { return } self.fullscreenReconciliations[window] = nil guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } let observed = self.snapshots[window] if observed?.window.app == app, observed?.window.facts?.isFullScreen == entering, entering ? observed?.excluded == true : self.admitted[window] != nil { return } // AX fullscreen readback can precede the animation and omit its final inventory notification. self.reconcile([app]) self.scheduleFullscreenReconciliation(window, app: app, entering: entering, remaining: remaining - 1) } fullscreenReconciliations[window] = (app, turn) } public func close( _ window: WindowID, confirm: @escaping @MainActor (Bool?) async -> Bool ) async throws { guard let app = snapshots[window]?.window.app else { throw EnginePlatformFailure.vanished(window) } guard let application = applications[app] else { throw EnginePlatformFailure.appUnavailable(app) } let generation = lifetime let appGeneration = appGenerations[app] do { let edited = try await application.edited(window) guard await confirm(edited) else { return } try Task.checkCancellation() guard isCurrent(generation), appGenerations[app] == appGeneration, snapshots[window]?.window.app == app else { throw EnginePlatformFailure.vanished(window) } if edited != false { try await application.focus(window) } try Task.checkCancellation() guard isCurrent(generation), appGenerations[app] == appGeneration, snapshots[window]?.window.app == app else { throw EnginePlatformFailure.vanished(window) } try await application.close(window) reconcile([app]) } catch is CancellationError { throw CancellationError() } catch { throw Self.failure(error, app: app, window: window) } } private func perform( _ window: WindowID, completion: @escaping @MainActor (EnginePlatformFailure?) -> Void, operation: @escaping @MainActor (any NativeEngineApplication) async throws -> Void ) { guard let app = snapshots[window]?.window.app else { completion(.vanished(window)) return } guard let application = applications[app] else { completion(.appUnavailable(app)) return } let generation = lifetime let appGeneration = appGenerations[app] let revision = spaceRevision let workspace = admitted[window]?.workspace let id = UUID() let task = Task { @MainActor in guard !Task.isCancelled, isCurrent(generation), appGenerations[app] == appGeneration, spaceRevision == revision, !checkingSpaces, !spaceCommandActive, let workspace, admitted[window]?.workspace == workspace, admitted[window]?.window.app == app, spaces[workspace.display] == workspace.space, suspensionSince[workspace.display] == nil else { focusActions.removeValue(forKey: id)?.completion(nil) return } do { try await operation(application) focusActions.removeValue(forKey: id)?.completion(nil) } catch { guard let action = focusActions.removeValue(forKey: id) else { return } if isCurrent(generation), appGenerations[app] == appGeneration { recordError(error, app: app) } action.completion(Self.failure(error, app: app, window: window)) } } focusActions[id] = (app, task, completion) } private func cancelFocusActions(for app: AppID? = nil) { for (id, queued) in focusActions where app == nil || queued.app == app { guard let action = focusActions.removeValue(forKey: id) else { continue } action.task.cancel() action.completion(nil) } } public func displayLink(for display: DisplayID) throws -> any EngineDisplayLink { for screen in NSScreen.screens { guard let number = screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber, let uuid = CGDisplayCreateUUIDFromDisplayID(number.uint32Value)?.takeRetainedValue(), let string = CFUUIDCreateString(nil, uuid) else { continue } if (string as String).caseInsensitiveCompare(display.rawValue) == .orderedSame { return ScreenEngineDisplayLink(screen: screen) } } throw EnginePlatformFailure.operation(.displayLinkUnavailable(display)) } private func route(_ event: NativeEngineEvent) { cancelSettleReconciliation() switch event { case .launched(let info): pendingApps.insert(info.id) errorRecoveryPending.remove(info.id) pendingInfo[info.id] = info if applications[info.id] == nil { attach(info) pendingApps.insert(info.id) } else if pendingExits.contains(info.id) { pendingApps.insert(info.id) } case .hidden(let info), .unhidden(let info): errorRecoveryPending.remove(info.id) pendingInfo[info.id] = info pendingApps.insert(info.id) case .activated(let info): errorRecoveryPending.remove(info.id) pendingInfo[info.id] = info if applications[info.id] == nil { pendingApps.insert(info.id) } // Workspace callbacks can arrive after another PID has become frontmost. if backend.focusedApplication() == info.id { visibilityAfterFocus.insert(info.id) pendingFocus = info.id focusSequence &+= 1 } case .terminated(let app): if let identity = appInfo[app]?.launchIdentity, backend.runningApplications().contains(where: { $0.id == app && $0.launchIdentity == identity }) { return } pendingExits.insert(app) pendingInfo[app] = nil pendingApps.remove(app) if pendingFocus == app || backend.focusedApplication() == app { if pendingFocus == app { pendingFocus = nil } focusSequence &+= 1 } case .spaceChanged: NativeEventTrace.spaceNotification() awaitingSpaceMap = true errorRecoveryPending.removeAll() invalidateSpaces() pendingVisibility = true case .woke: awaitingSpaceMap = true errorRecoveryPending.removeAll() invalidateSpaces() pendingVisibility = true pendingApps.formUnion(applications.keys) case .displaysChanged(let displays): updateDisplays(displays) case .pointerButton(let isDown): guard !spaceCommandActive else { return } pointerIsDown = isDown receive?(.pointerButton(isDown: isDown)) if isDown && !spaceRefreshFailures.isEmpty { pendingApps.formUnion(spaceRefreshFailures) pendingVisibility = true scheduleTurn() } return case .preferencesChanged(let snapshot): let conflict = Self.conflict(snapshot) if conflict != systemConflict { systemConflict = conflict if conflict != nil { newWindowTargets.clear() } receive?(.systemWindowConflictChanged(conflict)) publishSuspension() } invalidateSpaces() pendingVisibility = true pendingApps.formUnion(spaceRefreshFailures) case .failure(let error): receive?(.failure(Self.failure(error))) return } if checkingSpaces { pendingSpaces = true } scheduleTurn() } private func updateDisplays(_ updated: [ParcelCore.Display]) { errorRecoveryPending.removeAll() screenFrames = Dictionary(uniqueKeysWithValues: updated.map { ($0.id, $0.frame) }) spaces = spaces.filter { screenFrames[$0.key] != nil } invalidateSpaces() receive?(.observed(.displaySetChanged(updated))) pendingVisibility = true pendingApps.formUnion(applications.keys) scheduleTurn() } private func invalidateSpaces() { spaceRevision &+= 1 checkingSpaces = true pendingSpaces = true cancelFocusActions() newWindowTargets.clear() publishSuspension() } private func publishSuspension() { let now = Date() var reasons: [DisplayID: Set] = [:] for display in screenFrames.keys { var current: Set = [] switch systemConflict { case .stageManager: current.insert(.stageManager) case .nativeTiling: current.insert(.nativeTiling) case .both: current.formUnion([.stageManager, .nativeTiling]) case .unverified: current.insert(.systemPreferencesUnverified) case nil: break } if spaceReadFailed { current.insert(.spaceReadFailed) } if spaces[display] == nil { current.insert(.spaceUnavailable) } if spaceSuspended.contains(display) { current.insert(.fullscreenSpace) } if checkingSpaces && changedSpaceDisplays.contains(display) { current.insert(.spaceTransition) } if !appSuspensionExpired { if transitioningDisplays.contains(display) { current.insert(.spaceTransition) } if spaceFailureDisplays.contains(display) { current.insert(.applicationRefreshFailed) } } if !current.isEmpty { reasons[display] = current } } suspensionSince = Dictionary( uniqueKeysWithValues: reasons.map { display, current in ( display, Dictionary( uniqueKeysWithValues: current.map { reason in (reason, suspensionSince[display]?[reason] ?? now) }) ) }) let suspensions = suspensionSince.keys.sorted().flatMap { display in (suspensionSince[display] ?? [:]).sorted { $0.key.rawValue < $1.key.rawValue }.map { reason, since in DisplaySuspension(display: display, reason: reason, since: since) } } let provisionalDisplays: Set = awaitingSpaceMap ? Set(screenFrames.keys) : [] receive?(.suspendedDisplaysChanged(provisionalDisplays.union(reasons.keys))) receive?(.displaySuspensionsChanged(suspensions, provisionalDisplays: provisionalDisplays)) if !checkingSpaces, appSuspensionExpired || spaceFailureDisplays.union(transitioningDisplays).isEmpty { transitionDeadline?.cancel() transitionDeadline = nil } if !reasons.isEmpty || checkingSpaces { for app in Set(probeTurns.keys).union(probeTasks.keys) { cancelProbe(app) } } else { for app in unresponsiveApps { scheduleProbe(app) } } } private func releaseSpaceTransition(_ app: AppID) { for display in spaceTransitionApps.keys { spaceTransitionApps[display]?.remove(app) if spaceTransitionApps[display]?.isEmpty == true { transitioningDisplays.remove(display) } } } private func beginTransitionDeadline() { transitionDeadline?.cancel() appSuspensionExpired = false let generation = lifetime transitionDeadline = scheduler.schedule(after: 0.3) { [weak self] in guard let self, self.lifetime == generation, self.receive != nil else { return } self.transitionDeadline = nil self.appSuspensionExpired = true self.transitioningDisplays.removeAll() self.spaceTransitionApps.removeAll() self.publishSuspension() } } private func cancelProbe(_ app: AppID) { probeTurns.removeValue(forKey: app)?.cancel() probeTasks.removeValue(forKey: app)?.cancel() probeDelays[app] = nil } private func recovered(_ app: AppID) { guard unresponsiveApps.remove(app) != nil else { return } cancelProbe(app) skippedReasons[app] = nil onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) pendingApps.insert(app) scheduleTurn() receive?(.appResponsivenessChanged(app, isResponsive: true)) } private func scheduleProbe(_ app: AppID) { guard receive != nil, suspensionSince.isEmpty, !checkingSpaces, unresponsiveApps.contains(app), activeDiscoveryReads[app] == nil, probeTurns[app] == nil, probeTasks[app] == nil, let appGeneration = appGenerations[app] else { return } let delay = probeDelays[app] ?? 0.5 let generation = lifetime probeTurns[app] = scheduler.schedule(after: delay) { [weak self] in guard let self, self.isCurrent(generation), self.appGenerations[app] == appGeneration, self.suspensionSince.isEmpty, !self.checkingSpaces else { return } self.probeTurns[app] = nil self.probeTasks[app] = Task { @MainActor [weak self] in guard let self, self.isCurrent(generation), self.appGenerations[app] == appGeneration, self.suspensionSince.isEmpty, !self.checkingSpaces, let application = self.applications[app] else { return } do { try await application.probeResponsiveness() guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } self.probeTasks[app] = nil self.recovered(app) } catch { guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } self.probeTasks[app] = nil if (error as? AXPlatformError) != .timedOut { self.report(error, app: app) } self.probeDelays[app] = min(delay * 2, 5) self.scheduleProbe(app) } } } } private static func conflict(_ snapshot: SystemWindowPreferencesSnapshot) -> SystemWindowConflict? { let stage = snapshot.stageManagerGloballyEnabled if stage == .enabled { return .stageManager } // Native tiling preferences are coexistence information, not a placement blocker. if stage.confirmedBoolOrNil == nil { return .unverified } return nil } private func scheduleTurn() { guard receive != nil, !spaceCommandActive, turn == nil, refreshTask == nil, !pendingInfo.isEmpty || !pendingExits.isEmpty || pendingApps.contains(where: { activeDiscoveryReads[$0] == nil && !unresponsiveApps.contains($0) }) || pendingFocus != nil || pendingSpaces || pendingVisibility else { return } let generation = lifetime turn = scheduler.schedule(after: 0) { [weak self] in guard let self, self.lifetime == generation, self.receive != nil else { return } self.turn = nil self.refreshTask = Task { @MainActor [weak self] in await self?.refreshPending(generation: generation) guard let self, self.lifetime == generation else { return } self.refreshTask = nil self.scheduleTurn() self.signalReconciliationIdle() } } } } extension NativeEngineWorld { private func refreshPending(generation: UInt64) async { let detections = detectionSource == nil ? [:] : pendingDetections.filter { refreshing[$0.key] == nil || pendingExits.contains($0.key) } if detectionSource != nil { for app in detections.keys { pendingDetections[app] = nil } for traces in detections.values { trackDetections(traces) for trace in traces { trace.releaseDelivery() } } } defer { for traces in detections.values { releaseDetections(traces) } } let infos = pendingInfo let exits = pendingExits var apps = Set(pendingApps.filter { activeDiscoveryReads[$0] == nil && !unresponsiveApps.contains($0) }) apps.formUnion( spaceRefreshFailures.filter { activeDiscoveryReads[$0] == nil && !unresponsiveApps.contains($0) }) let focused = pendingFocus let focusRevision = focusSequence let readSpaces = pendingSpaces || checkingSpaces || screenFrames.keys.contains { spaces[$0] == nil } let spaceReadRevision = spaceRevision let refreshCachedVisibility = pendingVisibility || readSpaces let readVisibility = refreshCachedVisibility || !apps.isEmpty pendingInfo.removeAll() pendingExits.removeAll() pendingApps.subtract(apps) pendingFocus = nil pendingSpaces = false pendingVisibility = false defer { if isCurrent(generation), spaceRevision != spaceReadRevision { pendingApps.formUnion(apps) if focusSequence == focusRevision, pendingFocus == nil { pendingFocus = focused } } } for app in exits { remove(app, detections: detections[app]) } for info in infos.values { attach(info, detections: detections[info.id]) } let suspended = readSpaces ? await refreshSpaces(generation: generation, revision: spaceReadRevision) : nil guard isCurrent(generation) else { return } let visibilityRevisions = observationRevisions guard let visible = await readVisibleWindows( needed: readVisibility, discoverOwners: refreshCachedVisibility, apps: &apps, generation: generation) else { return } guard isCurrent(generation), spaceRevision == spaceReadRevision else { return } // Until the map is verified, absence from the visible list says nothing about an existing tile. guard !readSpaces || suspended != nil || admitted.isEmpty else { return } guard await confirmWindowSpaces(in: visible, generation: generation, revision: spaceReadRevision) else { return } let staleApps = readVisibility ? Set( applications.keys.filter { observationRevisions[$0, default: 0] != visibilityRevisions[$0, default: 0] }) : [] if !staleApps.isEmpty { pendingVisibility = true } if readVisibility { for (id, admission) in admitted where visible.frames[id] == nil { let app = admission.window.app guard appInfo[app]?.isHidden != true, !isOnInactiveSpace(id), let observed = snapshots[id], visibleSnapshot(observed, in: visible.frames) == nil else { continue } apps.insert(app) } } let blocked = apps.filter { activeDiscoveryReads[$0] != nil || unresponsiveApps.contains($0) || staleApps.contains($0) } pendingApps.formUnion(blocked) apps.subtract(blocked) if let suspended, spaceRevision == spaceReadRevision { checkingSpaces = false spaceSuspended = suspended beginTransitionDeadline() for display in transitioningDisplays { let waiting = apps.union(refreshing.keys).subtracting(unresponsiveApps).filter { app in snapshots.values.contains { snapshot in snapshot.window.app == app && (admitted[snapshot.window.id]?.workspace.display == display || Self.intersection( screenFrames[display], visible.frames[snapshot.window.id] ?? snapshot.frame) > 0) } } spaceTransitionApps[display] = waiting } transitioningDisplays = Set(spaceTransitionApps.filter { !$0.value.isEmpty }.keys) } for app in apps { startRefresh( app, visible: visible, generation: generation, spaceReadRevision: spaceReadRevision, checksSpaceFailure: readSpaces || spaceRefreshFailures.contains(app), focusRevision: focused == app ? focusRevision : nil, detections: detections[app]) } if refreshCachedVisibility { refreshCachedWindows(visible: visible.frames, refreshed: apps.union(refreshing.keys), skipping: staleApps) } if let focused, !apps.contains(focused) { startFocusRead(focused, generation: generation, revision: focusRevision, detections: detections[focused]) } if !checkingSpaces, readVisibility { spaceFailureDisplays = displaysAffectedByFailedApps(visible) publishSuspension() } onWindowObservation?(.windowsChanged) } private func startRefresh( _ app: AppID, visible: NativeVisibleWindows, generation: UInt64, spaceReadRevision: UInt64, checksSpaceFailure: Bool, focusRevision: UInt64?, detections: [DetectionTrace]? ) { guard activeDiscoveryReads[app] == nil, let appGeneration = appGenerations[app] else { return } startInitialDiscoveryDeadline(generation: generation) trackDetections(detections) activeDiscoveryReads[app, default: 0] += 1 refreshDeadlines[app] = scheduler.schedule(after: Self.discoveryBudget) { [weak self] in guard let self, self.lifetime == generation, self.appGenerations[app] == appGeneration else { return } self.skipDiscovery(app, reason: .deadlineExceeded) } refreshing[app] = Task { @MainActor [weak self] in guard let self else { return } defer { self.releaseDetections(detections) self.finishedDiscoveryRead(app, generation: generation, appGeneration: appGeneration) } let refreshed = await self.refresh( app, visible: visible, generation: generation, spaceObservationRevision: spaceReadRevision, detections: detections) guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } if self.spaceRevision == spaceReadRevision { if checksSpaceFailure { switch refreshed { case .applied: self.spaceRefreshFailures.remove(app) case .failed: self.spaceRefreshFailures.insert(app) case .stale: break } } if refreshed != .stale { self.releaseSpaceTransition(app) } self.spaceFailureDisplays = self.displaysAffectedByFailedApps(visible) self.publishSuspension() } if let focusRevision, !self.unresponsiveApps.contains(app) { await self.refreshFocus( app, generation: generation, focusRevision: focusRevision, detections: detections) } guard self.isCurrent(generation), self.appGenerations[app] == appGeneration else { return } self.refreshing[app] = nil self.refreshDeadlines.removeValue(forKey: app)?.cancel() if refreshed != .stale { self.finishInitialInventory(app) } self.onWindowObservation?(.windowsChanged) self.scheduleTurn() self.signalReconciliationIdle() } } private func startFocusRead(_ app: AppID, generation: UInt64, revision: UInt64, detections: [DetectionTrace]?) { guard !unresponsiveApps.contains(app), let appGeneration = appGenerations[app] else { return } startInitialDiscoveryDeadline(generation: generation) focusTask?.cancel() focusDeadline?.cancel() focusTaskApp = app focusTaskRevision = revision activeDiscoveryReads[app, default: 0] += 1 let budget = !discoveryCompleted && initialDiscoveryExpired ? Self.initialFocusTailBudget : Self.discoveryBudget focusDeadline = scheduler.schedule(after: budget) { [weak self] in guard let self, self.lifetime == generation, self.appGenerations[app] == appGeneration, self.focusTaskRevision == revision else { return } self.skipDiscovery(app, reason: .focusDeadlineExceeded) } trackDetections(detections) focusTask = Task { @MainActor [weak self] in guard let self else { return } defer { self.releaseDetections(detections) self.finishedDiscoveryRead(app, generation: generation, appGeneration: appGeneration) if self.lifetime == generation, self.focusTaskRevision == revision { self.focusTask = nil self.focusTaskRevision = nil self.focusTaskApp = nil self.focusDeadline?.cancel() self.focusDeadline = nil self.signalReconciliationIdle() } } if let refresh = self.refreshing[app] { await refresh.value } guard self.isCurrent(generation), self.appGenerations[app] == appGeneration, self.focusSequence == revision, self.backend.focusedApplication() == app else { return } await self.refreshFocus(app, generation: generation, focusRevision: revision, detections: detections) } } private func refreshSpaces(generation: UInt64, revision: UInt64) async -> Set? { let interval = NativeEventTrace.spaceRead() defer { NativeEventTrace.endSpaceRead(interval) } do { if failNextSpaceRead { failNextSpaceRead = false throw SpaceCommandError.malformedSnapshot } let updated = try await backend.currentSpaces(for: screenFrames.keys.sorted()) guard isCurrent(generation), spaceRevision == revision else { return nil } if let snapshot = updated.snapshot { let confirmed = try NativeSpaceMapping.currentSpaces(snapshot, displays: screenFrames.keys.sorted()) guard confirmed == updated.spaces else { throw SpaceCommandError.malformedSnapshot } try await spaceController?.observe(snapshot) } guard isCurrent(generation), spaceRevision == revision else { return nil } spaceReadFailed = false awaitingSpaceMap = false changedSpaceDisplays.formUnion( updated.spaces.keys.filter { spaces[$0] != updated.spaces[$0] || spaceSuspended.contains($0) != updated.suspended.contains($0) }) changedSpaceDisplays.formIntersection(screenFrames.keys) transitioningDisplays = changedSpaceDisplays spaceTransitionApps.removeAll() spaces = updated.spaces spaceSuspended = updated.suspended publishSuspension() guard isCurrent(generation), spaceRevision == revision else { return nil } for display in updated.spaces.keys.sorted() { guard let space = updated.spaces[display] else { preconditionFailure("Missing refreshed space") } receive?(.observed(.activeSpaceChanged(display: display, space: space))) } guard Set(updated.spaces.keys) == Set(screenFrames.keys) else { return nil } return updated.suspended } catch { guard isCurrent(generation), spaceRevision == revision else { return nil } spaceReadFailed = true transitioningDisplays = Set(screenFrames.keys) publishSuspension() receive?(.failure(Self.failure(error))) return nil } } private func readVisibleWindows( needed: Bool, discoverOwners: Bool, apps: inout Set, generation: UInt64 ) async -> NativeVisibleWindows? { guard needed else { return NativeVisibleWindows(frames: [:], owners: [:]) } do { let server = try await backend.visibleWindows() guard isCurrent(generation) else { return nil } if discoverOwners { let unknownOwners = Set( server.owners.compactMap { window, pid in snapshots[window] == nil ? pid : nil }) apps.formUnion(applications.keys.filter { unknownOwners.contains($0.pid) }) } latestVisible = server return server } catch { guard isCurrent(generation) else { return nil } receive?(.failure(Self.failure(error))) return nil } } private func confirmWindowSpaces( in inventory: NativeVisibleWindows, generation: UInt64, revision: UInt64 ) async -> Bool { guard isCurrent(generation), spaceRevision == revision else { return false } let candidates = admitted.filter { id, admission in guard inventory.catalogOwners[id] == admission.window.app.pid else { return false } if changedSpaceDisplays.contains(admission.workspace.display) || (confirmedWindowSpaces[id] != nil && inventory.frames[id] == nil) || (inventory.frames[id] != nil && spaces[admission.workspace.display] != admission.workspace.space) { return true } guard let frame = inventory.frames[id], let display = screenFrames.keys.sorted().max(by: { Self.intersection(screenFrames[$0], frame) < Self.intersection(screenFrames[$1], frame) }) else { return false } return display != admission.workspace.display && Self.intersection(screenFrames[display], frame) > 0 } guard !candidates.isEmpty else { changedSpaceDisplays.removeAll() return true } do { let membership = try await backend.windowSpaces(for: Set(candidates.keys)) guard isCurrent(generation), spaceRevision == revision else { return false } for (id, previous) in candidates where admitted[id]?.window.app == previous.window.app { confirmedWindowSpaces[id] = membership[id] } changedSpaceDisplays.removeAll() return true } catch { guard isCurrent(generation), spaceRevision == revision else { return false } checkingSpaces = true spaceReadFailed = true publishSuspension() receive?(.failure(Self.failure(error))) return false } } private func hasConfirmedWorkspace(_ id: WindowID, in inventory: NativeVisibleWindows) -> Bool { guard let admission = admitted[id], let observed = snapshots[id], !observed.excluded, observed.window.facts?.isMinimized != true, observed.window.facts?.isFullScreen != true, appInfo[admission.window.app]?.isHidden != true, inventory.catalogOwners[id] == admission.window.app.pid, let frame = inventory.catalogFrames[id], frame.isValid, frame.size.width > 0, frame.size.height > 0, confirmedWindowSpaces[id]?.contains(admission.workspace.space) == true else { return false } return spaces[admission.workspace.display] == admission.workspace.space } private func displaysAffectedByFailedApps(_ visible: NativeVisibleWindows) -> Set { guard !spaceRefreshFailures.isEmpty else { return [] } guard Set(visible.frames.keys) == Set(visible.owners.keys) else { return Set(screenFrames.keys) } let failedPIDs = Set(spaceRefreshFailures.subtracting(unresponsiveApps).map(\.pid)) var affected: Set = [] for (window, pid) in visible.owners where failedPIDs.contains(pid) { guard let frame = visible.frames[window] else { return Set(screenFrames.keys) } let displays = screenFrames.keys.filter { Self.intersection(screenFrames[$0], frame) > 0 } guard !displays.isEmpty else { return Set(screenFrames.keys) } affected.formUnion(displays) if let previous = admitted[window]?.workspace.display, screenFrames[previous] != nil { affected.insert(previous) } } return affected } private func visibleSnapshot( _ observed: NativeWindowSnapshot, in visible: [WindowID: Rect], allowDirectVisibility: Bool = true, currentWindowIDs: Set = [] ) -> NativeWindowSnapshot? { guard !observed.excluded, appInfo[observed.window.app]?.isHidden != true else { return nil } if allowDirectVisibility, let frame = visible[observed.window.id] { return NativeWindowSnapshot(window: observed.window, frame: frame, validity: observed.validity) } guard observed.window.facts?.hasNativeTabs == true else { return nil } let peers = snapshots.values.filter { peer in guard peer.window.id != observed.window.id, !peer.excluded, visible[peer.window.id] != nil || (currentWindowIDs.contains(peer.window.id) && visible[observed.window.id] != nil) else { return false } return observed.window.sharesNativeTabGroup(with: peer.window, frame: observed.frame, peerFrame: peer.frame) || visible[peer.window.id].map { observed.window.sharesNativeTabGroup(with: peer.window, frame: observed.frame, peerFrame: $0) } == true } guard peers.count == 1, let peer = peers.first, let frame = visible[peer.window.id] ?? visible[observed.window.id] else { return nil } return NativeWindowSnapshot(window: observed.window, frame: frame, validity: observed.validity) } private func nativeMember( _ cached: NativeWindowSnapshot, alongside windows: [NativeWindowSnapshot], inventory: NativeVisibleWindows ) -> NativeWindowSnapshot? { guard !cached.excluded, inventory.catalogOwners[cached.window.id] == cached.window.app.pid, let frame = inventory.catalogFrames[cached.window.id], frame.isValid, frame.size.width > 0, frame.size.height > 0 else { return nil } let candidates = windows.compactMap { peer -> NativeWindowSnapshot? in guard !peer.excluded, peer.window.app == cached.window.app, peer.window.facts?.hasNativeTabs == true, let group = peer.window.facts?.nativeTabGroup, var facts = cached.window.facts else { return nil } switch group { case .windowIDs(let ids): guard ids.contains(cached.window.id) else { return nil } case .titles(let titles): guard titles.contains(cached.window.title), !cached.window.title.isEmpty, snapshots.values.filter({ $0.window.app == cached.window.app && $0.window.title == cached.window.title }).count == 1 else { return nil } } facts.hasNativeTabs = true facts.nativeTabGroup = group var window = cached.window window.facts = facts guard window.sharesNativeTabGroup( with: peer.window, frame: frame, peerFrame: inventory.catalogFrames[peer.window.id] ?? peer.frame) else { return nil } return NativeWindowSnapshot(window: window, frame: frame, validity: cached.validity) } guard candidates.count == 1 else { return nil } return candidates.first } private func refreshCachedWindows(visible: [WindowID: Rect], refreshed apps: Set, skipping: Set) { for id in snapshots.keys.sorted() { guard var observed = snapshots[id] else { preconditionFailure("Missing cached native window") } if skipping.contains(observed.window.app) || apps.contains(observed.window.app) { continue } if visible[id] == nil { if let anchored = visibleSnapshot(observed, in: visible) { observe(anchored) } else if !isOnInactiveSpace(id), !hasConfirmedWorkspace(id, in: latestVisible) { disappear(id) } } else { if let frame = visible[id] { observed.frame = frame } snapshots[id] = observed observe(observed) } } } } extension NativeEngineWorld { private func attach(_ info: NativeApplicationInfo, detections: [DetectionTrace]? = nil) { for old in appInfo.values where old.id.pid == info.id.pid && (old.id != info.id || (old.launchIdentity != nil && info.launchIdentity != nil && old.launchIdentity != info.launchIdentity)) { remove(old.id) } appInfo[info.id] = info if info.isHidden { for id in snapshots.keys where snapshots[id]?.window.app == info.id { disappear(id, detections: detections) } } guard applications[info.id] == nil, retryTurns[info.id] == nil else { return } do { let application = try backend.application(info.id) applications[info.id] = application nextAppGeneration += 1 let appGeneration = nextAppGeneration appGenerations[info.id] = appGeneration let generation = lifetime tasks[info.id] = Task { @MainActor [weak self] in for await event in application.events { guard let self, self.isCurrent(generation), self.appGenerations[info.id] == appGeneration else { return } await self.handle(event, app: info.id, appGeneration: appGeneration) } } receive?(.appAvailable(info.id)) if let launchedAt = info.launchedAt { receive?(.appLaunched(info.id, at: launchedAt)) } } catch { receive?(.failure(Self.failure(error, app: info.id))) let busy: Bool = if case .alreadyOwned = error as? AppThreadFailure { true } else { false } markIncomplete(info.id, reason: busy ? .ownerBusy : .threadUnavailable) if !busy { receive?(.failure(.appUnavailable(info.id))) } finishInitialInventory(info.id) } } private func remove(_ app: AppID, detections: [DetectionTrace]? = nil) { cancelFocusActions(for: app) for (window, pending) in fullscreenReconciliations where pending.app == app { pending.turn.cancel() fullscreenReconciliations[window] = nil } cancelRetry(app) refreshing[app]?.cancel() refreshing[app] = nil refreshDeadlines.removeValue(forKey: app)?.cancel() activeDiscoveryReads[app] = nil skippedReasons[app] = nil onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) unresponsiveApps.remove(app) cancelProbe(app) callbackFocusedWindows[app] = nil releaseSpaceTransition(app) refreshChanges[app] = nil publishSuspension() tasks[app]?.cancel() tasks[app] = nil applications[app]?.shutdown() applications[app] = nil appInfo[app] = nil appGenerations[app] = nil observationRevisions[app] = nil visibilityAfterFocus.remove(app) errorBursts[app] = nil errorRecoveryPending.remove(app) spaceRefreshFailures.remove(app) for id in snapshots.keys where snapshots[id]?.window.app.pid == app.pid { snapshots[id] = nil minimized[id] = nil restoredWorkspaces[id] = nil restoring[id] = nil admitted[id] = nil confirmedWindowSpaces[id] = nil lastWorkspaces[id] = nil knownFrames[id] = nil } emit(.appExited(app), detections: detections) finishInitialInventory(app) } private func isCurrent(_ generation: UInt64) -> Bool { receive != nil && lifetime == generation && !Task.isCancelled } private func isTabViewEligible(_ window: ManagedWindow) -> Bool { var facts = window.facts ?? WindowFacts( bundleID: window.app.bundleID, role: window.role, subrole: window.subrole, title: window.title) facts.isMinimized = false return (classifier ?? WindowClassifier()).classify(facts).disposition != .ignore } private func cache(_ observed: NativeWindowSnapshot) { let id = observed.window.id let previous = snapshots[id] snapshots[id] = observed guard observed.window.facts?.isMinimized == true, let appGeneration = appGenerations[observed.window.app] else { if restoring[id] == nil { minimized[id] = nil } return } if let entry = minimized[id], entry.appGeneration == appGeneration, entry.validity.isValid { minimized[id] = MinimizedWindow( window: observed.window, frame: entry.frame, lastKnownWorkspace: entry.lastKnownWorkspace, worldID: entry.worldID, lifetime: entry.lifetime, appGeneration: entry.appGeneration, revision: entry.revision, validity: entry.validity) } else { nextMinimizedRevision &+= 1 minimized[id] = MinimizedWindow( window: observed.window, frame: previous?.frame ?? observed.frame, lastKnownWorkspace: lastWorkspaces[id], worldID: identity, lifetime: lifetime, appGeneration: appGeneration, revision: nextMinimizedRevision, validity: AppThreadOperationValidity(parent: observed.validity ?? previous?.validity)) } } private func refresh( _ app: AppID, visible inventory: NativeVisibleWindows, generation: UInt64, spaceObservationRevision: UInt64, detections: [DetectionTrace]? = nil ) async -> RefreshOutcome { let visible = inventory.frames guard let application = applications[app], let appGeneration = appGenerations[app] else { return .failed } let interval = NativeEventTrace.refresh(app.pid) defer { NativeEventTrace.endRefresh(interval) } let carried = detections let detections = carried ?? detectionSource.map { [$0.begin()] } if carried == nil { trackDetections(detections) } defer { if carried == nil { releaseDetections(detections) } } refreshChanges[app] = [] defer { if appGenerations[app] == appGeneration { refreshChanges[app] = nil } } do { let windows = try await application.windows().map { observed in let frame = visible[observed.window.id] ?? inventory.catalogFrames[observed.window.id] return NativeWindowSnapshot( window: observed.window, frame: frame ?? observed.frame, excluded: observed.excluded, validity: observed.validity) } guard isCurrent(generation), appGenerations[app] == appGeneration else { return .failed } guard spaceRevision == spaceObservationRevision else { pendingApps.insert(app) return .stale } let changed = refreshChanges[app] ?? [] errorBursts[app] = nil errorRecoveryPending.remove(app) let present = Set(windows.map(\.window.id)) let missing = inventory.discoveryCandidates.contains { id in guard inventory.owners[id] == app.pid, !present.contains(id), !changed.contains(id) else { return false } if let cached = snapshots[id], nativeMember(cached, alongside: windows, inventory: inventory) != nil { return false } return true } if missing && appInfo[app]?.isRegular == true { markIncomplete(app, reason: .inventoryIncomplete) } else if !unresponsiveApps.contains(app) { cancelRetry(app) if skippedReasons.removeValue(forKey: app) != nil { onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) receive?(.appResponsivenessChanged(app, isResponsive: true)) } } for observed in windows where !changed.contains(observed.window.id) { cache(observed) } for id in snapshots.keys where snapshots[id]?.window.app == app && !present.contains(id) && !changed.contains(id) { if !isOnInactiveSpace(id), let cached = snapshots[id] { if let member = nativeMember(cached, alongside: windows, inventory: inventory) { snapshots[id] = member if let anchored = visibleSnapshot( member, in: visible, allowDirectVisibility: false, currentWindowIDs: present) { observe(anchored, detections: detections) } else { disappear(id, detections: detections) } } else { // An incomplete AX list is not a close while the compositor still confirms this owner. if !cached.excluded, inventory.catalogOwners[id] == app.pid, inventory.owners[id] == app.pid, visible[id] != nil { var retained = cached if let frame = visible[id] ?? inventory.catalogFrames[id] { retained.frame = frame } snapshots[id] = retained observe(retained, detections: detections) continue } if cached.excluded, cached.window.facts?.isFullScreen == true, inventory.catalogOwners[id] == app.pid, let frame = inventory.catalogFrames[id], frame.isValid, frame.size.width > 0, frame.size.height > 0 { continue } let wasMinimized = minimized[id] != nil snapshots[id] = nil minimized[id] = nil lastWorkspaces[id] = nil disappear(id, force: wasMinimized, detections: detections) } } } for observed in windows where !changed.contains(observed.window.id) { if let anchored = visibleSnapshot(observed, in: visible) { observe(anchored, detections: detections) } else if !isOnInactiveSpace(observed.window.id), !hasConfirmedWorkspace(observed.window.id, in: inventory) { disappear( observed.window.id, minimized: observed.window.facts?.isMinimized == true, detections: detections) } } return .applied } catch { guard isCurrent(generation), appGenerations[app] == appGeneration else { return .failed } report(error, app: app) if applications[app] != nil { markIncomplete(app, reason: .inventoryIncomplete) } if (error as? AXPlatformError) == .timedOut { skipDiscovery(app, reason: .unresponsive, reportsTimeout: false) } guard spaceRevision == spaceObservationRevision else { return .failed } let changed = refreshChanges[app] ?? [] for (id, admission) in admitted where admission.window.app == app && visible[id] == nil { guard !changed.contains(id), !isOnInactiveSpace(id), !hasConfirmedWorkspace(id, in: inventory), let observed = snapshots[id], visibleSnapshot(observed, in: visible) == nil else { continue } disappear(id, detections: detections) } return .failed } } private func refreshFocus( _ app: AppID, generation: UInt64, focusRevision: UInt64, detections: [DetectionTrace]? = nil ) async { guard isCurrent(generation), focusSequence == focusRevision, backend.focusedApplication() == app, let application = applications[app], let appGeneration = appGenerations[app] else { return } let carried = detections let detections = carried ?? detectionSource.map { [$0.begin()] } if carried == nil { trackDetections(detections) } defer { if carried == nil { releaseDetections(detections) } } do { let id = try await application.focusedWindow() guard isCurrent(generation), appGenerations[app] == appGeneration, focusSequence == focusRevision, backend.focusedApplication() == app else { return } observedFocusedWindow = id emit(.observed(.focusChanged(id)), detections: detections) onWindowObservation?(.windowsChanged) reconcileVisibilityAfterFocus(app) } catch { guard isCurrent(generation), appGenerations[app] == appGeneration, focusSequence == focusRevision, backend.focusedApplication() == app else { return } report(error, app: app) } } private func reconcileVisibilityAfterFocus(_ app: AppID) { guard visibilityAfterFocus.remove(app) != nil else { return } pendingVisibility = true scheduleTurn() } private func frameCallbackOrigin(_ window: WindowID, app: AppID, source: AppThreadEventOrigin) -> FrameChangeOrigin? { guard !checkingSpaces, !spaceCommandActive, !isOnInactiveSpace(window), admitted[window].map({ !spaceSuspended.contains($0.workspace.display) }) != false, writingWindows[window] == nil else { return nil } if case .possiblySelfGenerated = source { reconcileFrames([app]) return nil } return pointerIsDown && observedFocusedWindow == window && backend.focusedApplication() == app ? .user : .reconciled } private func handle( _ event: AppThreadEvent, app: AppID, appGeneration: UInt64, detection: DetectionTrace? = nil ) async { let generation = lifetime let detections = detection.map { [$0] } if refreshChanges[app] != nil { switch event { case .windowCreatedWithFacts(let created): refreshChanges[app]?.insert(WindowID(rawValue: created.windowID)) case .windowDestroyed(let raw), .windowMinimized(let raw): refreshChanges[app]?.insert(WindowID(rawValue: raw)) default: break } } switch event { case .detected(let event, let trace): precondition(detection == nil, "Nested detection metadata") if detectionSource == nil { trace.finish(.dropped) await handle(event, app: app, appGeneration: appGeneration) } else { let traces = [trace] trackDetections(traces) defer { releaseDetections(traces) } await handle(event, app: app, appGeneration: appGeneration, detection: trace) } case .windowDestroyed(let raw), .windowMinimized(let raw): observationRevisions[app, default: 0] &+= 1 let id = WindowID(rawValue: raw) if case .windowDestroyed = event { fullscreenReconciliations.removeValue(forKey: id)?.turn.cancel() newWindowTargets.forget(id) #if DEBUG let environment = ProcessInfo.processInfo.environment let requestedID = environment["PARCEL_E2E_DESTROY_WINDOW_ID"].flatMap(UInt32.init) if dropNextDestroyedEvent, requestedID == nil || requestedID == raw { dropNextDestroyedEvent = false if let path = environment["PARCEL_E2E_DESTROY_RECEIPT"] { struct DroppedDestroy: Encodable { let token: String let pid: Int32 let windowID: UInt32 } do { let receipt = DroppedDestroy( token: environment["PARCEL_E2E_TOKEN"] ?? "", pid: app.pid, windowID: raw) try JSONEncoder().encode(receipt).write( to: URL(fileURLWithPath: path), options: .atomic) } catch { emit(.failure(Self.failure(error, app: app, window: id))) } } return } #endif snapshots[id] = nil minimized[id] = nil restoredWorkspaces[id] = nil lastWorkspaces[id] = nil } else if let existing = snapshots[id] { var window = existing.window var facts = window.facts ?? WindowFacts( bundleID: window.app.bundleID, role: window.role, subrole: window.subrole, title: window.title) facts.isMinimized = true window.facts = facts cache( NativeWindowSnapshot( window: window, frame: existing.frame, excluded: true, validity: existing.validity)) } else { pendingApps.insert(app) scheduleTurn() } let wasDestroyed: Bool if case .windowDestroyed = event { wasDestroyed = true } else { wasDestroyed = false } disappear(id, minimized: !wasDestroyed, force: wasDestroyed, detections: detections) onWindowObservation?(.windowsChanged) case .windowMoved(let raw, let source), .windowResized(let raw, let source): let id = WindowID(rawValue: raw) guard let origin = frameCallbackOrigin(id, app: app, source: source) else { return } cancelSettleReconciliation() guard admitted[id] != nil else { onWindowObservation?(.windowsChanged) if snapshots[id] == nil { pendingApps.insert(app) retainDetection(detection, for: app) scheduleTurn() } return } guard let application = applications[app] else { return } let revision = spaceRevision do { let frame = try await application.frame(id) guard isCurrent(generation), appGenerations[app] == appGeneration, spaceRevision == revision, admitted[id]?.window.app == app, writingWindows[id] == nil else { return } let resized: Bool if case .windowResized = event { resized = true } else { resized = false } refreshChanges[app]?.insert(id) knownFrames[id] = frame snapshots[id]?.frame = frame emit(.frameChanged(id, frame: frame, resized: resized, origin: origin), detections: detections) onWindowObservation?(.frameChanged(WindowFrame(window: id, frame: frame))) } catch { guard isCurrent(generation), appGenerations[app] == appGeneration else { return } report(error, app: app, window: WindowID(rawValue: raw)) } case .focusedWindowRead(let raw): callbackFocusedWindows[app] = raw.map { WindowID(rawValue: $0) } guard app == backend.focusedApplication() else { if let raw, admitted[WindowID(rawValue: raw)] == nil { retainDetection(detection, for: app) pendingApps.insert(app) pendingVisibility = true scheduleTurn() } return } let wasPending = focusTask != nil focusTask?.cancel() focusTask = nil focusTaskRevision = nil if wasPending { signalReconciliationIdle() } errorRecoveryPending.remove(app) focusSequence &+= 1 let id = raw.map { WindowID(rawValue: $0) } if id.flatMap({ snapshots[$0]?.window.facts?.hasNativeTabs }) == true { visibilityAfterFocus.insert(app) } if let id, snapshots[id]?.window.app != app || admitted[id] == nil { visibilityAfterFocus.insert(app) retainDetection(detection, for: app) pendingApps.insert(app) pendingFocus = app scheduleTurn() } else { retainDetection(detection, for: app) pendingFocus = app scheduleTurn() } case .focusedWindowChanged: retainDetection(detection, for: app) errorRecoveryPending.remove(app) pendingApps.insert(app) if app == backend.focusedApplication() { visibilityAfterFocus.insert(app) pendingFocus = app focusSequence &+= 1 } pendingVisibility = true scheduleTurn() case .applicationActivated: guard app == backend.focusedApplication() else { return } retainDetection(detection, for: app) errorRecoveryPending.remove(app) pendingFocus = app focusSequence &+= 1 if !snapshots.values.contains(where: { $0.window.app == app }) { pendingApps.insert(app) } scheduleTurn() case .windowCreatedWithFacts(let created): observationRevisions[app, default: 0] &+= 1 let id = WindowID(rawValue: created.windowID) let window = ManagedWindow( id: id, app: app, title: created.facts.title ?? "", role: created.facts.role ?? "", subrole: created.facts.subrole, facts: created.facts) let snapshot = NativeWindowSnapshot( window: window, frame: Rect(created.frame), excluded: created.facts.isMinimized == true || created.facts.isFullScreen == true, validity: created.validity) if minimized[id] != nil { disappear(id, force: true, detections: detections) } minimized[id] = nil lastWorkspaces[id] = nil snapshots[id] = nil cache(snapshot) if !created.isOnScreen || spaces.isEmpty || checkingSpaces || spaceCommandActive { retainDetection(detection, for: app) pendingApps.insert(app) scheduleTurn() } else { observe(snapshot, detections: detections) if let initial = created.placementInitialFrame, let target = created.placementTarget { emit(.placementReadBack(initial: Rect(initial), target: Rect(target), final: Rect(created.frame))) } onWindowObservation?(.windowsChanged) } case .windowMovedWithFrame(let raw, let frame, let source), .windowResizedWithFrame(let raw, let frame, let source): defer { applications[app]?.acknowledgeMotion(raw) } let id = WindowID(rawValue: raw) guard let origin = frameCallbackOrigin(id, app: app, source: source) else { return } cancelSettleReconciliation() guard admitted[id] != nil else { if snapshots[id] == nil { pendingApps.insert(app) retainDetection(detection, for: app) scheduleTurn() } return } let frame = Rect(frame) let resized: Bool if case .windowResizedWithFrame = event { resized = true } else { resized = knownFrames[id]?.size != frame.size } refreshChanges[app]?.insert(id) knownFrames[id] = frame snapshots[id]?.frame = frame emit( .frameChanged(id, frame: frame, resized: resized, origin: origin), detections: detections) onWindowObservation?(.frameChanged(WindowFrame(window: id, frame: frame))) case .windowCreated, .windowDeminimized, .windowTitleChanged, .windowList, .reconciliation: retainDetection(detection, for: app) errorRecoveryPending.remove(app) pendingApps.insert(app) scheduleTurn() case .applicationTerminated: retainDetection(detection, for: app) pendingExits.insert(app) scheduleTurn() case .unresponsive: skipDiscovery(app, reason: .unresponsive) case .responsive: recovered(app) case .failure(let failure): report(failure, app: app) if failure == .operationOverdue { skipDiscovery(app, reason: .deadlineExceeded) } case .applicationDeactivated: break } } func excludedWindow(_ id: WindowID) -> ManagedWindow? { guard let window = snapshots[id]?.window, window.facts?.isMinimized == true || window.facts?.isFullScreen == true else { return nil } return window } private func isOnInactiveSpace(_ id: WindowID) -> Bool { guard let key = admitted[id]?.workspace, let current = spaces[key.display] else { return false } return key.space != current } private func disappear( _ id: WindowID, minimized: Bool = false, force: Bool = false, detections: [DetectionTrace]? = nil ) { knownFrames[id] = nil confirmedWindowSpaces[id] = nil let wasAdmitted = admitted.removeValue(forKey: id) != nil guard wasAdmitted || force else { return } emit(.observed(minimized ? .windowMinimized(id) : .windowDisappeared(id)), detections: detections) } private func observe( _ observed: NativeWindowSnapshot, detections: [DetectionTrace]? = nil, origin: FrameChangeOrigin = .unknown ) { guard !spaceCommandActive, !checkingSpaces || spaces.isEmpty else { return } var window = observed.window guard applications[window.app] != nil else { return } if observed.excluded || appInfo[window.app]?.isHidden == true { if window.facts?.isFullScreen == true && isOnInactiveSpace(window.id) { return } disappear(window.id, minimized: window.facts?.isMinimized == true, detections: detections) return } guard let display = screenFrames.keys.sorted().max(by: { Self.intersection(screenFrames[$0], observed.frame) < Self.intersection(screenFrames[$1], observed.frame) }) else { receive?(.failure(.operation(.missingSpace(window.id, display: nil)))) disappear(window.id, detections: detections) return } guard Self.intersection(screenFrames[display], observed.frame) > 0 else { disappear(window.id, detections: detections) return } guard let space = spaces[display] else { receive?(.failure(.operation(.missingSpace(window.id, display: display)))) disappear(window.id, detections: detections) return } guard !spaceSuspended.contains(display) else { return } let observedWorkspace = WorkspaceKey(display: display, space: space) if let membership = confirmedWindowSpaces[window.id], !membership.contains(space), !(membership.isEmpty && window.facts?.hasNativeTabs == true) { return } let target = restoredWorkspaces[window.id].flatMap { key in spaces[key.display] == key.space && screenFrames[key.display] != nil ? key : nil } let workspace = target ?? observedWorkspace window.isRestoringMinimized = target != nil if target == observedWorkspace { restoredWorkspaces[window.id] = nil } lastWorkspaces[window.id] = workspace let previousFrame = knownFrames[window.id] var admittedWindow = window admittedWindow.isRestoringMinimized = false if admitted[window.id]?.window != admittedWindow || admitted[window.id]?.workspace != workspace { admitted[window.id] = Admission(window: admittedWindow, workspace: workspace) emit( .observed(.windowAppeared(window, workspace: workspace, frame: previousFrame ?? observed.frame)), detections: detections) } if let previousFrame, previousFrame != observed.frame { emit( .frameChanged( window.id, frame: observed.frame, resized: previousFrame.size != observed.frame.size, origin: origin), detections: detections) } knownFrames[window.id] = observed.frame } private static func intersection(_ screen: Rect?, _ frame: Rect) -> Double { guard let screen else { return 0 } return max(0, min(screen.maxX, frame.maxX) - max(screen.minX, frame.minX)) * max(0, min(screen.maxY, frame.maxY) - max(screen.minY, frame.minY)) } private func report(_ error: any Error, app: AppID, window: WindowID? = nil) { receive?(.failure(Self.failure(error, app: app, window: window))) recordError(error, app: app) } private func recordError(_ error: any Error, app: AppID) { if let failure = error as? EnginePlatformFailure { switch failure { case .accessibility(_, _, let cause): recordError(cause, app: app) return case .appThread(_, let cause): recordError(cause, app: app) return case .unexpected(let failure): recordError(failure.cause, app: app) return default: break } } if Self.isUnavailable(error) { errorBursts[app] = nil makeUnavailable(app) } else if !errorRecoveryPending.contains(app), error is AXPlatformError || error is AppThreadFailure || error is FrameWriteFailure || error is AppThreadWriteBatchFailure { let count = errorBursts[app, default: 0] + 1 if count >= 3 { errorBursts[app] = nil errorRecoveryPending.insert(app) pendingApps.insert(app) pendingVisibility = true if checkingSpaces { pendingSpaces = true } scheduleTurn() } else { errorBursts[app] = count } } } private func cancelRetry(_ app: AppID, resetDelay: Bool = true) { retryTurns.removeValue(forKey: app)?.cancel() retryTokens[app] = nil if resetDelay { retryDelays[app] = nil } } private func markIncomplete(_ app: AppID, reason: NativeDiscoverySkipReason) { if skippedReasons[app] != reason { skippedReasons[app] = reason onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) } // A replacement owner is recovered only after its first complete inventory. guard reason == .ownerBusy || reason == .threadUnavailable || retryDelays[app] != nil, receive != nil, appInfo[app] != nil, retryTurns[app] == nil else { return } let delay = retryDelays[app] ?? 0.1 retryDelays[app] = min(delay * 2, 5) let token = UUID() retryTokens[app] = token let generation = lifetime retryTurns[app] = scheduler.schedule(after: delay) { [weak self] in guard let self, self.isCurrent(generation), self.retryTokens[app] == token else { return } self.cancelRetry(app, resetDelay: false) guard let info = self.backend.runningApplications().first(where: { $0.id == app }) else { self.remove(app) return } self.pendingInfo[app] = info self.pendingApps.insert(app) self.pendingVisibility = true self.scheduleTurn() } } private func makeUnavailable(_ app: AppID) { cancelFocusActions(for: app) let wasRefreshing = refreshing[app] != nil refreshing[app]?.cancel() refreshing[app] = nil refreshDeadlines.removeValue(forKey: app)?.cancel() activeDiscoveryReads[app] = nil skippedReasons[app] = nil onDiscoverySkippedApplicationsChanged?(discoverySkippedApplications) pendingApps.remove(app) unresponsiveApps.remove(app) cancelProbe(app) callbackFocusedWindows[app] = nil releaseSpaceTransition(app) refreshChanges[app] = nil spaceRefreshFailures.remove(app) spaceFailureDisplays = displaysAffectedByFailedApps(latestVisible) publishSuspension() tasks[app]?.cancel() tasks[app] = nil applications[app]?.shutdown() applications[app] = nil appGenerations[app] = nil for id in snapshots.keys where snapshots[id]?.window.app == app { minimized[id] = nil restoredWorkspaces[id] = nil restoring[id] = nil lastWorkspaces[id] = nil } markIncomplete(app, reason: .threadUnavailable) receive?(.failure(.appUnavailable(app))) finishInitialInventory(app) if wasRefreshing { signalReconciliationIdle() } } private static func isUnavailable(_ error: any Error) -> Bool { if case EnginePlatformFailure.appUnavailable = error { return true } guard let failure = error as? AppThreadFailure else { return false } return switch failure { case .stopped, .runLoopUnavailable, .initialization, .observerCreation: true default: false } } static func failure(_ error: any Error, app: AppID? = nil, window: WindowID? = nil) -> EnginePlatformFailure { if let failure = error as? EnginePlatformFailure { return failure } if let failure = error as? EngineOperationFailure { return .operation(failure) } if let app { if let error = error as? AXPlatformError { return .accessibility(app, window: window, cause: error) } if let error = error as? AppThreadFailure { if case .accessibility(let cause) = error { return .accessibility(app, window: window, cause: cause) } return .appThread(app, cause: error) } } return .unexpected(EngineUnexpectedFailure(cause: error)) } }