Something went wrong. Try again.
An auto tiler for macOS
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692import ApplicationServicesimport CoreFoundationpublic import CoreGraphicsimport Darwinpublic import Foundationpublic import ParcelCoreimport Synchronizationimport os
public struct AppThreadCreatedWindow: Sendable, Equatable { public let windowID: CGWindowID public let facts: WindowFacts public let frame: CGRect public let isOnScreen: Bool public let parentWindowID: CGWindowID? package var validity: AppThreadOperationValidity? package var placementInitialFrame: CGRect? package var placementTarget: CGRect?
public init( windowID: CGWindowID, facts: WindowFacts, frame: CGRect, isOnScreen: Bool, parentWindowID: CGWindowID? = nil ) { self.windowID = windowID self.facts = facts self.frame = frame self.isOnScreen = isOnScreen self.parentWindowID = parentWindowID }}
/// Events contain window server IDs rather than AX objects, which stay on the app thread.public enum AppThreadEvent: Sendable, Equatable { indirect case detected(AppThreadEvent, trace: DetectionTrace) case windowCreated(CGWindowID) case windowCreatedWithFacts(AppThreadCreatedWindow) case windowDestroyed(CGWindowID) case windowMoved(CGWindowID, origin: AppThreadEventOrigin) case windowResized(CGWindowID, origin: AppThreadEventOrigin) case windowMovedWithFrame(CGWindowID, frame: CGRect, origin: AppThreadEventOrigin) case windowResizedWithFrame(CGWindowID, frame: CGRect, origin: AppThreadEventOrigin) case windowTitleChanged(CGWindowID) case windowMinimized(CGWindowID) case windowDeminimized(CGWindowID) case focusedWindowChanged case focusedWindowRead(CGWindowID?) case applicationActivated case applicationDeactivated case applicationTerminated case windowList([CGWindowID]) case reconciliation(AppThreadReconciliation) case unresponsive case responsive case failure(AppThreadFailure)}
extension AppThreadEvent { static func observing(source: (any DetectionTraceSource)?, _ observation: () -> AppThreadEvent?) -> AppThreadEvent? { guard let trace = source?.begin() else { return observation() } guard let event = observation() else { trace.finish(.dropped) return nil } return .detected(event, trace: trace) }}
/// A snapshot, not a claim that every window server entry should have an AX counterpart.public struct AppThreadReconciliation: Sendable, Equatable { public let axWindowIDs: [CGWindowID] public let serverWindows: [WindowServer.Window] public let axOnly: [CGWindowID] public let serverOnly: [CGWindowID]
init(pid: pid_t, axWindowIDs: [CGWindowID], serverWindows: [WindowServer.Window]) { let axIDs = Set(axWindowIDs) let windows = serverWindows.filter { $0.pid == pid }.sorted { $0.number < $1.number } let serverIDs = Set(windows.map(\.number)) self.axWindowIDs = axIDs.sorted() self.serverWindows = windows self.axOnly = axIDs.subtracting(serverIDs).sorted() self.serverOnly = serverIDs.subtracting(axIDs).sorted() }}
/// AX has no transaction IDs; recent write notifications are attributed provisionally.public enum AppThreadEventOrigin: Sendable, Equatable { case unattributed case possiblySelfGenerated(UUID)}
public enum AppThreadFailure: Error, Sendable, Equatable { case accessibility(AXPlatformError) case stopped case runLoopUnavailable case operationOverdue case alreadyOwned(pid_t) case initialization(String) case observerCreation(Int32) case observerRegistration(notification: String, windowID: CGWindowID?, code: Int32) case observerRegistrationExhausted(notifications: [String]) case observerRemoval(notification: String, windowID: CGWindowID, code: Int32) case windowEnumeration(String) case windowServer(String) case windowIdentification(String) case windowFacts(String) case windowFrame(String) case frameWriteCleanup(String) case windowNotFound(CGWindowID)}
package struct AppThreadIdentifiedWindow { package let element: AXElement package let windowID: CGWindowID package let validity: AppThreadOperationValidity}
/// Owns one application's AX objects and observer on a dedicated run-loop thread.public final class AppThread: Sendable { public let events: AsyncStream<AppThreadEvent> private let worker: AppThreadWorker private let executor: AppThreadExecutor private let exitObserver: AppProcessObserver private let assistiveTechnology = AssistiveTechnologyState.shared private let technologySubscription: UUID
public init( pid: pid_t, timeout: Float = 0.35, timeoutThreshold: Int = 3, detectionSource: (any DetectionTraceSource)? = nil, factsContext: WindowFactsContext = .init(bundleID: ""), newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? = nil ) throws { precondition(timeout > 0 && timeout.isFinite) precondition(timeoutThreshold > 0) guard AppThreadOwnerRegistry.shared.acquire(pid) else { throw AppThreadFailure.alreadyOwned(pid) } let (events, continuation) = AsyncStream<AppThreadEvent>.makeStream() self.events = events let worker = AppThreadWorker( pid: pid, timeout: timeout, timeoutThreshold: timeoutThreshold, events: continuation, detectionSource: detectionSource, factsContext: factsContext, newWindowTarget: newWindowTarget) self.worker = worker let executor = AppThreadExecutor( start: { worker.start() }, stop: { let error = worker.stop() AppThreadOwnerRegistry.shared.release(pid) worker.shutdownResult.complete(error) }, failure: { worker.executorFailed() } ) self.executor = executor self.exitObserver = AppProcessObserver(pid: pid) { [weak executor] in worker.stopWatchdog() continuation.yield(.applicationTerminated) executor?.shutdown() } self.technologySubscription = AssistiveTechnologyState.shared.subscribe { [weak executor] in executor?.submit(run: { worker.assistiveTechnologyChanged() }, cancel: {}) } }
/// The closure runs on the owning thread. Neither it nor its result may transfer AX objects. public func perform<Value: Sendable>( _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker let validity = AppThreadOperationValidity() return try await withTaskCancellationHandler { try Task.checkCancellation() return try await withCheckedThrowingContinuation { continuation in executor.submit( run: { worker.perform(operation, validity: validity, continuation: continuation) }, cancel: { continuation.resume(throwing: AppThreadFailure.stopped) } ) } } onCancel: { validity.invalidate() } }
/// Reads windows and repairs their observer registrations on the owning thread. package func performWithWindows<Value: Sendable>( _ operation: @escaping @Sendable ([AppThreadIdentifiedWindow]) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in let candidates = try AppThreadWindowLookup.includingAttachedSheets( in: application.windows, children: { try $0.inventoryChildren() }, role: { element in try optionalWindowFact { try element.role } }, onFailure: { worker.reportWindowIdentificationFailure($0) }) let windows = try worker.repairWindowObservers(candidates, validity: application.operationValidity) return try operation( windows.map { AppThreadIdentifiedWindow( element: $0.window, windowID: $0.id, validity: worker.validity(for: $0.id)) }) } }
public func performWindow<Value: Sendable>( windowID: CGWindowID, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { try await performWindow(windowID: windowID, validity: nil, operation) }
package func performWindow<Value: Sendable>( windowID: CGWindowID, validity: AppThreadOperationValidity?, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in do { let resolve = { try worker.resolveWindow(windowID, application: application) } if let validity { return try validity.perform(resolve: resolve, operation: operation) } return try operation(resolve()) } catch AXPlatformError.elementInvalid { worker.evictCachedWindow(windowID) throw AXPlatformError.elementInvalid } } }
package func retainWindow(windowID: CGWindowID) async throws -> AppThreadWindowRequest { let worker = self.worker return try await perform { application in let window = try worker.resolveWindow(windowID, application: application) return worker.retainedWindows.insert(window.withoutCallTracking(), windowID: windowID) } }
package func performWindow<Value: Sendable>( request: AppThreadWindowRequest, _ operation: @escaping @Sendable (AXElement) throws -> Value ) async throws -> Value { let worker = self.worker return try await perform { application in let window = try worker.retainedWindows.window(for: request) return try operation(window.trackingCalls(of: application)) } }
package func releaseWindow(_ request: AppThreadWindowRequest) async { let worker = self.worker await withCheckedContinuation { continuation in executor.submit( run: { worker.retainedWindows.remove(request) continuation.resume() }, cancel: { continuation.resume() }) } }
/// Only final receipts prove window geometry; ongoing motion deliberately avoids AX reads. /// Final release preserves ownership; cancellation requires a larger generation before another write. public func writeFrames(_ requests: [AppThreadFrameWrite]) async throws -> AppThreadWriteBatchReceipt { var ids: Set<CGWindowID> = [] for request in requests where !ids.insert(request.windowID).inserted { throw AppThreadFrameWriteError.duplicateWindow(request.windowID) } let cancellation = AppThreadWriteCancellation() let worker = self.worker let executor = self.executor return try await withTaskCancellationHandler { await assistiveTechnology.prepare() try Task.checkCancellation() return try await executor.performBounded(timeout: 2, onAbort: { cancellation.cancel() }) { try worker.writeFrames(requests, cancellation: cancellation) } } onCancel: { cancellation.cancel() executor.submit(run: { worker.cancelFrameWritesReporting(requests) }, cancel: {}) } }
public func cancelFrameWrites( windowIDs: Set<CGWindowID>? = nil, throughGeneration: UInt64? = nil ) async throws { let worker = self.worker try await perform { application in try worker.cancelFrameWrites( windowIDs: windowIDs, throughGeneration: throughGeneration, application: application) } }
/// Tags matching move/resize notifications conservatively; callers must not treat a tag as proof. public func writeFrame(windowID: CGWindowID, target: CGRect, writeID: UUID = UUID()) async throws -> CGRect { await assistiveTechnology.prepare() let worker = self.worker return try await withCheckedThrowingContinuation { continuation in executor.submit( run: { do { continuation.resume( returning: try worker.writeFrame(windowID: windowID, target: target, writeID: writeID)) } catch { continuation.resume(throwing: error) } }, cancel: { continuation.resume(throwing: AppThreadFailure.stopped) }) } }
/// Call after handling a frame payload, including on error, to release its latest pending sibling. public func acknowledgeMotion(windowID: CGWindowID) { let worker = self.worker executor.submit(run: { worker.acknowledgeMotion(windowID: windowID) }, cancel: {}) }
/// Requests shutdown without waiting for an in-flight AX call to return. public func shutdown() { exitObserver.cancel() assistiveTechnology.unsubscribe(technologySubscription) worker.shutdownRequested.cancel() worker.stopWatchdog() executor.shutdown() }
/// Unlike event delivery, this receipt remains available after the event consumer has stopped. public func shutdownRestoringFrameWrites() async throws { shutdown() try await worker.shutdownResult.wait() }
deinit { exitObserver.cancel() assistiveTechnology.unsubscribe(technologySubscription) worker.shutdownRequested.cancel() worker.stopWatchdog() executor.shutdown() }}
final class AppProcessObserver: @unchecked Sendable { private let source: any DispatchSourceProcess
init( pid: pid_t, queue: DispatchQueue = .global(qos: .utility), onRegistration: @escaping @Sendable () -> Void = {}, onExit: @escaping @Sendable () -> Void ) { source = DispatchSource.makeProcessSource(identifier: pid, eventMask: .exit, queue: queue) source.setRegistrationHandler(handler: onRegistration) source.setEventHandler(handler: onExit) source.resume() }
func cancel() { source.cancel() }
deinit { source.cancel() }}
final class AppThreadOwnerRegistry: Sendable { static let shared = AppThreadOwnerRegistry() private let owners = Mutex<Set<pid_t>>([])
func acquire(_ pid: pid_t) -> Bool { owners.withLock { $0.insert(pid).inserted } }
func release(_ pid: pid_t) { owners.withLock { _ = $0.remove(pid) } }}
// This object is accessed only by its executor's thread, including observer callbacks.private final class AppThreadWorker: @unchecked Sendable { let shutdownResult = AppThreadShutdownResult() let shutdownRequested = AppThreadWriteCancellation() private let pid: pid_t private let timeout: Float private let events: AsyncStream<AppThreadEvent>.Continuation private let detectionSource: (any DetectionTraceSource)? private let factsContext: WindowFactsContext private let newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? private let watchdog: AXCallWatchdog private var timeouts: AppThreadTimeoutTracker private var application: AXElement? private var startupFailure: AppThreadFailure? private var observer: AXObserver? private var windows: [(raw: AXUIElement, id: CGWindowID)] = [] private var windowCache = AppThreadWindowCache<AXElement>() var retainedWindows = AppThreadRetainedWindows<AXElement>() private var windowValidities: [CGWindowID: AppThreadOperationValidity] = [:] private let frameWriter = AppThreadFrameWriter() private var frameWrites = AppThreadFrameWriteTracker() private var registrations = AppThreadRegistrationTracker() private var registrationBackoff: AppThreadRegistrationBackoff? private var registrationTimer: CFRunLoopTimer? private var initialWindowsEmitted = false private var createdWindows = AppThreadCreatedWindowTracker() private var motionMailbox = AppThreadMotionMailbox()
init( pid: pid_t, timeout: Float, timeoutThreshold: Int, events: AsyncStream<AppThreadEvent>.Continuation, detectionSource: (any DetectionTraceSource)?, factsContext: WindowFactsContext, newWindowTarget: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? ) { self.pid = pid self.timeout = timeout self.events = events self.detectionSource = detectionSource self.factsContext = factsContext self.newWindowTarget = newWindowTarget let deadline = max(1, Double(timeout) * 2) self.watchdog = AXCallWatchdog( deadline: deadline, overdue: { events.yield(.failure(.operationOverdue)) }) self.timeouts = AppThreadTimeoutTracker(threshold: timeoutThreshold) }
func start() { do { let application = try AXElement(applicationPID: pid, timeout: timeout, watchdog: watchdog) self.application = application var observer: AXObserver? let token = watchdog.begin() let result = AXObserverCreate( pid, { _, element, notification, context in guard let context else { return } let worker = Unmanaged<AppThreadWorker>.fromOpaque(context).takeUnretainedValue() worker.receive(element: element, notification: notification as String) }, &observer) watchdog.end(token) guard result == .success, let observer else { let failure = AppThreadFailure.observerCreation(result.rawValue) startupFailure = failure events.yield(.failure(failure)) return } self.observer = observer CFRunLoopAddSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(observer), .defaultMode) registrationBackoff = AppThreadRegistrationBackoff() registerApplicationNotifications() } catch { record(error) let failure = AppThreadFailure.initialization(String(describing: error)) startupFailure = failure events.yield(.failure(failure)) } }
func executorFailed() { events.yield(.failure(.runLoopUnavailable)) }
// Shutdown can cancel deadlines while the owning thread is blocked inside AX. func stopWatchdog() { watchdog.stop() }
func stop() -> (any Error)? { stopWatchdog() cancelRegistrationTimer() motionMailbox.removeAll() var cleanupError: (any Error)? if let application { do { try cancelFrameWrites(application: application) } catch { cleanupError = error events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } if let observer { CFRunLoopRemoveSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(observer), .defaultMode) } observer = nil windows.removeAll() windowCache.removeAll() retainedWindows.removeAll() for validity in windowValidities.values { validity.invalidate() } windowValidities.removeAll() application = nil events.finish() return cleanupError }
func reportWindowIdentificationFailure(_ error: any Error) { events.yield(.failure(.windowIdentification(String(describing: error)))) }
@discardableResult func repairWindowObservers( _ current: [AXElement], validity: AppThreadOperationValidity? = nil ) throws -> [(window: AXElement, id: CGWindowID)] { try validity?.check() let identified = try AppThreadWindowLookup.identified( in: current, identify: AppThreadWindowLookup.windowID, onFailure: { events.yield(.failure(.windowIdentification(String(describing: $0)))) }) try validity?.check() registerApplicationNotifications(initialWindows: identified.map(\.window), validity: validity) for window in identified { try validity?.check() observe(window.window, identifiedID: window.id, validity: validity) } let present = Set(identified.map(\.id)) let missing = windows.filter { !present.contains($0.id) } windows.removeAll { !present.contains($0.id) } for window in missing { forgetWindow(window.id) frameWrites.clear(windowID: window.id) registrations.remove(windowID: window.id) if let observer { for notification in Self.windowNotifications { try validity?.check() let token = watchdog.begin() let result = AXObserverRemoveNotification(observer, window.raw, notification as CFString) watchdog.end(token) if result != .success && result != .notificationNotRegistered { events.yield( .failure( .observerRemoval(notification: notification, windowID: window.id, code: result.rawValue) )) } } } } return identified }
func perform<Value: Sendable>( _ operation: @Sendable (AXElement) throws -> Value, validity: AppThreadOperationValidity, continuation: CheckedContinuation<Value, any Error> ) { if let startupFailure { continuation.resume(throwing: startupFailure) return } guard let application else { continuation.resume(throwing: AppThreadFailure.stopped) return } let activity = AXCallActivity(validity: validity) do { try validity.check() let result = try operation(application.tracking(activity)) try validity.check() for event in timeouts.observe(activity) { events.yield(event) } continuation.resume(returning: result) } catch { for event in timeouts.observe(activity) { events.yield(event) } continuation.resume(throwing: error) } }
func evictCachedWindow(_ windowID: CGWindowID) { windowCache[windowID] = nil }
func resolveWindow(_ windowID: CGWindowID, application: AXElement) throws -> AXElement { try windowCache.resolve(windowID) { let window = try AppThreadWindowLookup.find( in: application.windows, windowID: windowID, identify: AppThreadWindowLookup.windowID, focused: { try optionalWindowFact { try application.focusedWindow } }, onFailure: { events.yield(.failure(.windowIdentification(String(describing: $0)))) }) guard let window else { throw AppThreadFailure.windowNotFound(windowID) } observe(window) return window }.trackingCalls(of: application) }
func writeFrame(windowID: CGWindowID, target: CGRect, writeID: UUID) throws -> CGRect { let request = AppThreadFrameWrite( windowID: windowID, target: target, writeID: writeID, generation: frameWriter.generationForStandaloneWrite(for: windowID), phase: .final) let batch = try writeFrames([request], cancellation: AppThreadWriteCancellation()) let errors = batch.windows.compactMap(\.error) + batch.cleanupErrors if errors.count == 1 { throw errors[0] } if !errors.isEmpty { throw AppThreadWriteBatchFailure(errors: errors) } guard let actual = batch.windows.first?.actual else { throw AppThreadFailure.windowFrame("A final write did not return its readback") } return actual }
func writeFrames( _ requests: [AppThreadFrameWrite], cancellation: AppThreadWriteCancellation ) throws -> AppThreadWriteBatchReceipt { if let startupFailure { throw startupFailure } guard let application else { throw AppThreadFailure.stopped } guard AssistiveTechnologyState.shared.current != nil else { throw AppThreadFailure.initialization("Assistive technology observation has not started") } let interval = AppThreadWriteTrace.begin() let started = DispatchTime.now().uptimeNanoseconds let activity = AXCallActivity() let trackedApplication = application.tracking(activity) let result = frameWriter.write( requests, application: trackedApplication, assistiveTechnology: { guard let current = AssistiveTechnologyState.shared.current else { preconditionFailure("Initialized assistive technology state must remain available") } return current }, resolve: { try self.resolveWindow($0, application: trackedApplication) }, isCancelled: { cancellation.isCancelled || self.shutdownRequested.isCancelled }) for (request, receipt) in zip(requests, result.windows) { if receipt.error is AppThreadFrameWriteError { continue } frameWrites.clear(windowID: request.windowID) if let actual = receipt.actual { frameWrites.record( windowID: request.windowID, writeID: request.writeID, before: receipt.before, actual: actual, attempted: request.target) } if receipt.error as? AXPlatformError == .elementInvalid { evictCachedWindow(request.windowID) } } for event in timeouts.observe(activity) { events.yield(event) } let duration = Double(DispatchTime.now().uptimeNanoseconds - started) / 1_000_000_000 AppThreadWriteTrace.end( interval, calls: activity.results.count, duration: duration, windows: requests.count, final: requests.allSatisfy { $0.phase == .final }) return AppThreadWriteBatchReceipt( windows: result.windows, duration: duration, cleanupErrors: result.cleanupErrors, axCallCount: activity.results.count) }
func cancelFrameWrites( windowIDs: Set<CGWindowID>? = nil, throughGeneration: UInt64? = nil, application: AXElement ) throws { let cancelled = try frameWriter.cancel( windowIDs: windowIDs, throughGeneration: throughGeneration, application: application) for id in cancelled { frameWrites.clear(windowID: id) } }
func cancelFrameWritesReporting(_ requests: [AppThreadFrameWrite]) { guard let application else { return } for request in requests { do { try cancelFrameWrites( windowIDs: [request.windowID], throughGeneration: request.generation, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } } }
func assistiveTechnologyChanged() { guard let application, let technology = AssistiveTechnologyState.shared.current else { return } do { try frameWriter.refreshAssistiveTechnology(technology, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } }
func validity(for id: CGWindowID) -> AppThreadOperationValidity { guard let validity = windowValidities[id] else { preconditionFailure("An observed window must have an owner-thread identity") } return validity }
private func forgetWindow(_ id: CGWindowID) { windowValidities.removeValue(forKey: id)?.invalidate() windowCache[id] = nil createdWindows.remove(id) motionMailbox.remove(id) guard let application else { return } do { try frameWriter.forget(id, application: application) } catch { record(error) events.yield(.failure(.frameWriteCleanup(String(describing: error)))) } }
private static let applicationNotifications = [kAXWindowCreatedNotification] + AppThreadFocusReader.notifications + [kAXApplicationActivatedNotification, kAXApplicationDeactivatedNotification] private static let windowNotifications = [ kAXUIElementDestroyedNotification, kAXWindowMovedNotification, kAXWindowResizedNotification, kAXTitleChangedNotification, kAXWindowMiniaturizedNotification, kAXWindowDeminiaturizedNotification, ]
private func registerApplicationNotifications( initialWindows: [AXElement]? = nil, validity: AppThreadOperationValidity? = nil ) { guard let application, observer != nil, !shutdownRequested.isCancelled, validity?.isValid != false else { return } registerNotifications(Self.applicationNotifications, on: application.raw, windowID: nil, validity: validity) guard !shutdownRequested.isCancelled else { cancelRegistrationTimer() return } let missing = Self.applicationNotifications.filter { registrations.needs($0, windowID: nil) } guard missing.isEmpty else { guard registrationTimer == nil, registrationBackoff != nil else { return } guard let delay = registrationBackoff?.nextDelay() else { registrationBackoff = nil events.yield(.failure(.observerRegistrationExhausted(notifications: missing))) return } guard let timer = CFRunLoopTimerCreateWithHandler( nil, CFAbsoluteTimeGetCurrent() + delay, 0, 0, 0, { [weak self] timer in if let timer { CFRunLoopTimerInvalidate(timer) } guard let self else { return } self.registrationTimer = nil self.registerApplicationNotifications() }) else { registrationBackoff = nil events.yield(.failure(.runLoopUnavailable)) return } registrationTimer = timer CFRunLoopAddTimer(CFRunLoopGetCurrent(), timer, .defaultMode) return } registrationBackoff = nil cancelRegistrationTimer() guard !initialWindowsEmitted else { return } do { let windows: [AXElement] if let initialWindows { windows = initialWindows } else { windows = try application.windows recordSuccess() } initialWindowsEmitted = true for window in windows { guard validity?.isValid != false else { return } emitCreatedWindow(window, speculate: false) } } catch { record(error) events.yield(.failure(.windowEnumeration(String(describing: error)))) } }
private func cancelRegistrationTimer() { if let registrationTimer { CFRunLoopTimerInvalidate(registrationTimer) } registrationTimer = nil }
private func registerNotifications( _ notifications: [String], on element: AXUIElement, windowID: CGWindowID?, validity: AppThreadOperationValidity? = nil ) { for notification in notifications where registrations.needs(notification, windowID: windowID) { guard validity?.isValid != false else { return } register(notification, on: element, windowID: windowID) } }
private func register(_ notification: String, on element: AXUIElement, windowID: CGWindowID?) { guard let observer else { return } let token = watchdog.begin() defer { watchdog.end(token) } let start = DispatchTime.now().uptimeNanoseconds let result = AXObserverAddNotification( observer, element, notification as CFString, Unmanaged.passUnretained(self).toOpaque()) let elapsed = Double(DispatchTime.now().uptimeNanoseconds - start) / 1_000_000_000 registrations.record(result, notification: notification, windowID: windowID) if result == .success || result == .notificationAlreadyRegistered { if result == .success { recordSuccess() } } else { if result == .cannotComplete && elapsed >= Double(timeout) * 0.9 { if timeouts.timedOut() { events.yield(.unresponsive) } } else { timeouts.otherFailure() } events.yield( .failure(.observerRegistration(notification: notification, windowID: windowID, code: result.rawValue))) } }
private func cacheWindow(_ window: AXElement, identifiedID: CGWindowID? = nil) throws -> CGWindowID? { if let known = windows.first(where: { CFEqual($0.raw, window.raw) }) { windowCache[known.id] = window.withoutCallTracking() return known.id } guard let id = try identifiedID ?? AppThreadWindowLookup.windowID(window) else { return nil } if windows.contains(where: { $0.id == id }) { forgetWindow(id) registrations.remove(windowID: id) frameWrites.clear(windowID: id) windows.removeAll { $0.id == id } } windowValidities[id] = AppThreadOperationValidity() recordSuccess() windows.append((window.raw, id)) windowCache[id] = window.withoutCallTracking() return id }
private func observe( _ window: AXElement, identifiedID: CGWindowID? = nil, validity: AppThreadOperationValidity? = nil ) { do { guard let id = try cacheWindow(window, identifiedID: identifiedID) else { return } registerNotifications(Self.windowNotifications, on: window.raw, windowID: id, validity: validity) } catch { record(error) events.yield(.failure(.windowIdentification(String(describing: error)))) } }
private func createdWindowEvent(_ window: AXElement, speculate: Bool = true) -> AppThreadEvent? { let id: CGWindowID do { guard let identified = try cacheWindow(window) else { return nil } id = identified } catch { record(error) return .failure(.windowIdentification(String(describing: error))) } guard createdWindows.claim(id) else { return nil } let snapshot: AppThreadCreatedWindow do { snapshot = try readCreatedWindow(window, windowID: id) } catch { events.yield(.failure(.callback(error, fallback: AppThreadFailure.windowFacts))) return .windowCreated(id) } do { let maySpeculate = speculate && !shutdownRequested.isCancelled && !frameWriter.suppressesFrameNotification(windowID: id, pointerIsDown: false) && !CGEventSource.buttonState(.combinedSessionState, button: .left) let placed = try AppThreadSpeculativePlacement.place( snapshot, speculate: maySpeculate, assistiveTechnology: AssistiveTechnologyState.shared.current, read: newWindowTarget ) { target in let interval = AppThreadCallbackTrace.beginSpeculativeWrite(windowID: id) defer { AppThreadCallbackTrace.endSpeculativeWrite(interval) } return try writeFrame(windowID: id, target: target, writeID: UUID()) } return .windowCreatedWithFacts(placed) } catch { events.yield(.failure(.callback(error, fallback: AppThreadFailure.windowFrame))) return .windowCreatedWithFacts(snapshot) } }
private func readCreatedWindow(_ window: AXElement, windowID: CGWindowID) throws -> AppThreadCreatedWindow { let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } let isOnScreen = try WindowServer().isOnScreen(windowID: windowID) var snapshot = try WindowFactsReader.gatherCreatedWindow( window: window.tracking(activity), windowID: windowID, context: factsContext, isOnScreen: isOnScreen) snapshot.validity = validity(for: windowID) return snapshot }
private func emitCreatedWindow(_ window: AXElement, speculate: Bool) { let event = AppThreadEvent.observing(source: detectionSource) { createdWindowEvent(window, speculate: speculate) } if let event { yieldEvent(event) } if let id = windows.first(where: { CFEqual($0.raw, window.raw) })?.id { registerNotifications(Self.windowNotifications, on: window.raw, windowID: id) } }
private func receive(element: AXUIElement, notification: String) { let interval = AppThreadCallbackTrace.begin(notification: notification) defer { AppThreadCallbackTrace.end(interval) } if notification != kAXWindowMovedNotification, notification != kAXWindowResizedNotification, let id = windows.first(where: { CFEqual($0.raw, element) })?.id, let pending = motionMailbox.flush(id) { deliver(pending) } let event = AppThreadEvent.observing(source: detectionSource) { notificationEvent(element: element, notification: notification) } if let event { yieldEvent(event) } if notification == kAXWindowCreatedNotification, let id = windows.first(where: { CFEqual($0.raw, element) })?.id { registerNotifications(Self.windowNotifications, on: element, windowID: id) } }
private func yieldEvent(_ event: AppThreadEvent) { if let pending = motionMailbox.flushBefore(event) { deliver(pending) } guard let ready = motionMailbox.offer(event) else { return } deliver(ready) }
private func deliver(_ marker: AppThreadEvent) { let event = AppThreadMotionMailbox.materialize(marker) { id in guard let window = windowCache[id] else { throw AppThreadFailure.windowNotFound(id) } let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } return try window.tracking(activity).frame } if let id = marker.motionWindowID, event.motionWindowID == nil { motionMailbox.remove(id) } switch events.yield(event) { case .enqueued: break case .dropped(let dropped): dropped.finishDroppedTrace() case .terminated: event.finishDroppedTrace() motionMailbox.removeAll() @unknown default: preconditionFailure("Unknown app event delivery result") } }
func acknowledgeMotion(windowID: CGWindowID) { if let event = motionMailbox.acknowledge(windowID) { deliver(event) } }
private func notificationEvent(element: AXUIElement, notification: String) -> AppThreadEvent? { switch notification { case kAXWindowCreatedNotification: do { let window = try AXElement(raw: element, timeout: timeout, watchdog: watchdog) return createdWindowEvent(window) } catch { record(error) return .failure(.windowIdentification(String(describing: error))) } case let name where AppThreadFocusReader.notifications.contains(name): guard let application else { return .failure(.stopped) } let activity = AXCallActivity() defer { for event in timeouts.observe(activity) { events.yield(event) } } return AppThreadFocusReader.event(for: name) { try application.tracking(activity).focusedWindowIDForCallback() } case kAXApplicationActivatedNotification: return .applicationActivated case kAXApplicationDeactivatedNotification: return .applicationDeactivated default: guard let index = windows.firstIndex(where: { CFEqual($0.raw, element) }) else { return .failure(.windowIdentification("Notification for an unobserved window: \(notification)")) } let id = windows[index].id switch notification { case kAXUIElementDestroyedNotification: windows.remove(at: index) forgetWindow(id) frameWrites.clear(windowID: id) registrations.remove(windowID: id) return .windowDestroyed(id) case kAXWindowMovedNotification: guard !didSuppressFrameNotification(windowID: id) else { return nil } return frameNotification(windowID: id, axis: .position) case kAXWindowResizedNotification: guard !didSuppressFrameNotification(windowID: id) else { return nil } return frameNotification(windowID: id, axis: .size) case kAXTitleChangedNotification: return .windowTitleChanged(id) case kAXWindowMiniaturizedNotification: return .windowMinimized(id) case kAXWindowDeminiaturizedNotification: return .windowDeminimized(id) default: break } } return nil }
private func frameNotification(windowID: CGWindowID, axis: AppThreadFrameWriteTracker.Axis) -> AppThreadEvent { let origin = frameOrigin(windowID: windowID, axis: axis) switch axis { case .position: return .windowMoved(windowID, origin: origin) case .size: return .windowResized(windowID, origin: origin) } }
private func didSuppressFrameNotification(windowID: CGWindowID) -> Bool { let pointerIsDown = CGEventSource.buttonState(.combinedSessionState, button: .left) return frameWriter.suppressesFrameNotification(windowID: windowID, pointerIsDown: pointerIsDown) }
private func frameOrigin(windowID: CGWindowID, axis: AppThreadFrameWriteTracker.Axis) -> AppThreadEventOrigin { frameWrites.origin( windowID: windowID, axis: axis, pointerIsDown: CGEventSource.buttonState(.combinedSessionState, button: .left)) }
private func record(_ error: any Error) { let timedOut: Bool if let axError = error as? AXPlatformError, case .timedOut = axError { timedOut = true } else if let frameError = error as? FrameWriteFailure { timedOut = Self.isTimeout(frameError.writeError) || Self.isTimeout(frameError.restoreError) } else { timedOut = false } if timedOut { if timeouts.timedOut() { events.yield(.unresponsive) } } else { timeouts.otherFailure() } }
private static func isTimeout(_ error: any Error) -> Bool { guard let error = error as? AXPlatformError, case .timedOut = error else { return false } return true }
private func recordSuccess() { if timeouts.succeeded() { events.yield(.responsive) } }}
enum AppThreadWindowReconciler { static func event( pid: pid_t, axWindowIDs: [CGWindowID], read: (CGWindowListOption) throws -> [WindowServer.Window] ) -> AppThreadEvent { do { return .reconciliation( AppThreadReconciliation(pid: pid, axWindowIDs: axWindowIDs, serverWindows: try read(.optionAll))) } catch { return .failure(.windowServer(String(describing: error))) } }}
package struct AppThreadWindowRequest: Hashable, Sendable { fileprivate let token: UUID fileprivate let windowID: CGWindowID}
struct AppThreadRetainedWindows<Window> { private var windows: [AppThreadWindowRequest: Window] = [:]
mutating func insert(_ window: Window, windowID: CGWindowID) -> AppThreadWindowRequest { let request = AppThreadWindowRequest(token: UUID(), windowID: windowID) windows[request] = window return request }
func window(for request: AppThreadWindowRequest) throws -> Window { guard let window = windows[request] else { throw AppThreadFailure.windowNotFound(request.windowID) } return window }
mutating func remove(_ request: AppThreadWindowRequest) { windows[request] = nil } mutating func removeAll() { windows.removeAll() }}
enum AppThreadWindowLookup { static func includingAttachedSheets<Window>( in windows: [Window], children: (Window) throws -> [Window], role: (Window) throws -> String?, onFailure: (any Error) -> Void ) throws -> [Window] { var result = windows for window in windows { let candidates: [Window] do { candidates = try children(window) } catch { guard isElementLocalFailure(error) else { throw error } onFailure(error) continue } for child in candidates { do { if try role(child) == kAXSheetRole { result.append(child) } } catch { guard isElementLocalFailure(error) else { throw error } onFailure(error) } } } return result }
private static func isElementLocalFailure(_ error: any Error) -> Bool { guard let error = error as? AXPlatformError else { return false } return error == .elementInvalid || error == .noValue || error == .attributeUnsupported || error == .other(AXError.illegalArgument.rawValue) }
static func windowID(_ window: AXElement) throws -> CGWindowID? { try windowID(identify: { try window.windowID() }, role: { try window.role }) }
static func windowID(identify: () throws -> CGWindowID, role: () throws -> String) throws -> CGWindowID? { do { return try identify() } catch let error as AXPlatformError { // Finder includes its desktop scroll area in AXWindows; it has no window identity. if error == .other(AXError.illegalArgument.rawValue), try role() == kAXScrollAreaRole { return nil } throw error } }
static func identified<Window>( in windows: [Window], identify: (Window) throws -> CGWindowID?, onFailure: (any Error) -> Void ) throws -> [(window: Window, id: CGWindowID)] { var identified: [(window: Window, id: CGWindowID)] = [] var present: Set<CGWindowID> = [] for window in windows { do { guard let id = try identify(window) else { continue } guard id != 0 else { throw AXPlatformError.noValue } guard present.insert(id).inserted else { continue } identified.append((window: window, id: id)) } catch let error as AXPlatformError { // Element-local identity failures must not hide the app's other real windows. guard error == .elementInvalid || error == .noValue || error == .attributeUnsupported || error == .other(AXError.illegalArgument.rawValue) else { throw error } onFailure(error) } } return identified }
static func find<Window>( in windows: [Window], windowID: CGWindowID, identify: (Window) throws -> CGWindowID?, focused: () throws -> Window? = { nil }, onFailure: (any Error) -> Void ) throws -> Window? { var firstError: (any Error)? for window in windows { do { if try identify(window) == windowID { return window } } catch { if firstError == nil { firstError = error } onFailure(error) } } // AXWindows may omit a native fullscreen window while its focused AX element remains live. if let window = try focused(), try identify(window) == windowID { return window } if let firstError { throw firstError } return nil }}
extension AppThreadFailure { static func callback(_ error: any Error, fallback: (String) -> Self) -> Self { if let error = error as? AXPlatformError { return .accessibility(error) } return fallback(String(describing: error)) }}
enum AppThreadFocusReader { static let notifications = [kAXFocusedWindowChangedNotification, kAXMainWindowChangedNotification]
static func event(for notification: String, readID: () throws -> CGWindowID?) -> AppThreadEvent? { guard notifications.contains(notification) else { return nil } if notification == kAXMainWindowChangedNotification { return .focusedWindowChanged } return event(readID: readID) }
static func event(readID: () throws -> CGWindowID?) -> AppThreadEvent { do { return .focusedWindowRead(try readID()) } catch { return .failure(.callback(error, fallback: AppThreadFailure.windowIdentification)) } }
static func read<Window>( focusedWindow: () throws -> Window, identify: (Window) throws -> CGWindowID ) throws -> CGWindowID? { guard let window = try optionalWindowFact(focusedWindow) else { return nil } return try optionalWindowFact { try identify(window) } }}
struct AppThreadMotionMailbox { private var inFlight: [CGWindowID: Int] = [:] private var latest: [CGWindowID: AppThreadEvent] = [:]
var inFlightCount: Int { inFlight.count } var pendingCount: Int { latest.count }
mutating func offer(_ event: AppThreadEvent) -> AppThreadEvent? { guard let id = event.motionWindowID else { return event } guard inFlight[id] == nil else { let previous = latest[id] latest[id] = previous?.motionOrigin == .unattributed ? event.withMotionOrigin(.unattributed) : event previous?.finishDroppedTrace() return nil } inFlight[id] = 1 return event }
mutating func flush(_ id: CGWindowID) -> AppThreadEvent? { guard let event = latest.removeValue(forKey: id) else { return nil } inFlight[id, default: 0] += 1 return event }
mutating func flushBefore(_ event: AppThreadEvent) -> AppThreadEvent? { guard event.motionWindowID == nil, let id = event.windowID else { return nil } return flush(id) }
static func materialize( _ event: AppThreadEvent, readFrame: (CGWindowID) throws -> CGRect ) -> AppThreadEvent { if case .detected(let observation, let trace) = event { return .detected(materialize(observation, readFrame: readFrame), trace: trace) } do { switch event { case .windowMoved(let id, let origin): return .windowMovedWithFrame(id, frame: try readFrame(id), origin: origin) case .windowResized(let id, let origin): return .windowResizedWithFrame(id, frame: try readFrame(id), origin: origin) default: return event } } catch let error as AppThreadFailure { return .failure(error) } catch { return .failure(.callback(error, fallback: AppThreadFailure.windowFrame)) } }
mutating func acknowledge(_ id: CGWindowID) -> AppThreadEvent? { guard let outstanding = inFlight[id] else { return nil } if outstanding > 1 { inFlight[id] = outstanding - 1 return nil } if let event = latest.removeValue(forKey: id) { return event } inFlight[id] = nil return nil }
mutating func remove(_ id: CGWindowID) { latest.removeValue(forKey: id)?.finishDroppedTrace() inFlight[id] = nil }
mutating func removeAll() { for event in latest.values { event.finishDroppedTrace() } latest.removeAll() inFlight.removeAll() }}
extension AppThreadEvent { var motionWindowID: CGWindowID? { switch self { case .detected(let event, _): return event.motionWindowID case .windowMoved(let id, _), .windowResized(let id, _), .windowMovedWithFrame(let id, _, _), .windowResizedWithFrame(let id, _, _): return id default: return nil } }
var windowID: CGWindowID? { switch self { case .detected(let event, _): return event.windowID case .windowCreated(let id), .windowDestroyed(let id), .windowTitleChanged(let id), .windowMinimized(let id), .windowDeminimized(let id): return id case .windowCreatedWithFacts(let window): return window.windowID case .focusedWindowRead(let id): return id default: return motionWindowID } }
fileprivate var motionOrigin: AppThreadEventOrigin? { switch self { case .detected(let event, _): return event.motionOrigin case .windowMoved(_, let origin), .windowResized(_, let origin), .windowMovedWithFrame(_, _, let origin), .windowResizedWithFrame(_, _, let origin): return origin default: return nil } }
fileprivate func withMotionOrigin(_ origin: AppThreadEventOrigin) -> AppThreadEvent { switch self { case .detected(let event, let trace): return .detected(event.withMotionOrigin(origin), trace: trace) case .windowMoved(let id, _): return .windowMoved(id, origin: origin) case .windowResized(let id, _): return .windowResized(id, origin: origin) case .windowMovedWithFrame(let id, let frame, _): return .windowMovedWithFrame(id, frame: frame, origin: origin) case .windowResizedWithFrame(let id, let frame, _): return .windowResizedWithFrame(id, frame: frame, origin: origin) default: return self } }
func finishDroppedTrace() { if case .detected(let event, let trace) = self { trace.dropIfUnowned() event.finishDroppedTrace() } }}
struct AppThreadCreatedWindowTracker { private var emitted: Set<CGWindowID> = [] mutating func claim(_ id: CGWindowID) -> Bool { emitted.insert(id).inserted } mutating func remove(_ id: CGWindowID) { emitted.remove(id) }}
struct AppThreadRegistrationBackoff { static let maximumAgeNanoseconds: UInt64 = 1_000_000_000 static let maximumAttempts = 16 private let startedAt: UInt64 private var step = 0
init(now: UInt64 = DispatchTime.now().uptimeNanoseconds) { startedAt = now }
mutating func nextDelay(now: UInt64 = DispatchTime.now().uptimeNanoseconds) -> Double? { guard step < Self.maximumAttempts, now >= startedAt, now - startedAt < Self.maximumAgeNanoseconds else { return nil } let remaining = Self.maximumAgeNanoseconds - (now - startedAt) let delay = min(UInt64(5_000_000) << min(step, 4), remaining) step += 1 return Double(delay) / 1_000_000_000 }}
enum AppThreadSpeculativePlacement { static func place( _ window: AppThreadCreatedWindow, speculate: Bool, assistiveTechnology: AssistiveTechnology?, read: (@Sendable (AppThreadCreatedWindow) -> CGRect?)?, write: (CGRect) throws -> CGRect ) throws -> AppThreadCreatedWindow { guard speculate, let target = try target(for: window, assistiveTechnology: assistiveTechnology, read: read) else { return window } var placed = AppThreadCreatedWindow( windowID: window.windowID, facts: window.facts, frame: try write(target), isOnScreen: window.isOnScreen, parentWindowID: window.parentWindowID) placed.placementInitialFrame = window.frame placed.placementTarget = target return placed }
static func target( for window: AppThreadCreatedWindow, assistiveTechnology: AssistiveTechnology?, read: (@Sendable (AppThreadCreatedWindow) -> CGRect?)? ) throws -> CGRect? { guard window.isOnScreen, assistiveTechnology != nil, let target = read?(window) else { return nil } guard [target.origin.x, target.origin.y, target.size.width, target.size.height].allSatisfy(\.isFinite), target.size.width > 0, target.size.height > 0 else { throw AXPlatformError.unexpectedValue("Speculative window target") } return target }}
private enum AppThreadCallbackTrace { private static let enabled = ProcessInfo.processInfo.environment["PARCEL_TRACE"] == "1" private static let signposter = OSSignposter(subsystem: "com.parcel", category: .pointsOfInterest)
static func begin(notification: String) -> OSSignpostIntervalState? { guard enabled else { return nil } return signposter.beginInterval( "appthread.callback", id: signposter.makeSignpostID(), "notification=\(notification, privacy: .public)") }
static func end(_ interval: OSSignpostIntervalState?) { if let interval { signposter.endInterval("appthread.callback", interval) } }
static func beginSpeculativeWrite(windowID: CGWindowID) -> OSSignpostIntervalState? { guard enabled else { return nil } return signposter.beginInterval( "appthread.speculativeWrite", id: signposter.makeSignpostID(), "window=\(windowID)") }
static func endSpeculativeWrite(_ interval: OSSignpostIntervalState?) { if let interval { signposter.endInterval("appthread.speculativeWrite", interval) } }}
struct AppThreadRegistrationTracker { private var completed: [CGWindowID?: Set<String>] = [:]
func needs(_ notification: String, windowID: CGWindowID?) -> Bool { !(completed[windowID]?.contains(notification) ?? false) }
mutating func record(_ result: AXError, notification: String, windowID: CGWindowID?) { if result == .success || result == .notificationAlreadyRegistered || result == .notificationUnsupported { completed[windowID, default: []].insert(notification) } }
mutating func remove(windowID: CGWindowID) { completed.removeValue(forKey: windowID) }}
struct AppThreadFrameWriteTracker { enum Axis { case position, size } static let maximumAgeNanoseconds: UInt64 = 500_000_000 private struct Candidate { let id: UUID let frame: CGRect let createdAt: UInt64 var position: Bool var size: Bool } private var candidates: [CGWindowID: Candidate] = [:]
mutating func record( windowID: CGWindowID, writeID: UUID, before: CGRect?, actual: CGRect, attempted: CGRect? = nil, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) { let attemptedWrite = attempted.map { $0 != before } ?? false let position = before?.origin != actual.origin || attemptedWrite let size = before?.size != actual.size || attemptedWrite candidates[windowID] = position || size ? Candidate(id: writeID, frame: actual, createdAt: now, position: position, size: size) : nil }
mutating func clear(windowID: CGWindowID) { candidates.removeValue(forKey: windowID) }
mutating func hasCandidate( windowID: CGWindowID, axis: Axis, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> Bool { guard let candidate = candidates[windowID] else { return false } guard now >= candidate.createdAt && now - candidate.createdAt < Self.maximumAgeNanoseconds else { clear(windowID: windowID) return false } switch axis { case .position: return candidate.position case .size: return candidate.size } }
mutating func origin( windowID: CGWindowID, axis: Axis, pointerIsDown: Bool, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> AppThreadEventOrigin { if pointerIsDown { clear(windowID: windowID) return .unattributed } guard hasCandidate(windowID: windowID, axis: axis, now: now), let candidate = candidates[windowID] else { return .unattributed } return .possiblySelfGenerated(candidate.id) }
mutating func match( windowID: CGWindowID, axis: Axis, frame: CGRect, now: UInt64 = DispatchTime.now().uptimeNanoseconds ) -> AppThreadEventOrigin { guard hasCandidate(windowID: windowID, axis: axis, now: now), let candidateValue = candidates[windowID] else { return .unattributed } guard candidateValue.frame == frame else { clear(windowID: windowID) return .unattributed } return .possiblySelfGenerated(candidateValue.id) }}
struct AppThreadTimeoutTracker { private let threshold: Int private var count = 0 private var wedged = false
init(threshold: Int) { precondition(threshold > 0) self.threshold = threshold }
mutating func timedOut() -> Bool { if count < threshold { count += 1 } guard count == threshold && !wedged else { return false } wedged = true return true }
mutating func succeeded() -> Bool { count = 0 let wasWedged = wedged wedged = false return wasWedged }
mutating func otherFailure() { count = 0 }
mutating func observe(_ activity: AXCallActivity) -> [AppThreadEvent] { var events: [AppThreadEvent] = [] for result in activity.results { switch result { case nil: if succeeded() { events.append(.responsive) } case .timedOut: if timedOut() { events.append(.unresponsive) } case .some: otherFailure() } } return events }}
// The waiter can finish before AX returns. Expired queued jobs must never start.final class AppThreadBoundedJob<Value: Sendable>: Sendable { private struct State { var result: Result<Value, any Error>? var continuation: CheckedContinuation<Value, any Error>? var timer: AXWatchdogDeadline? } private let state = Mutex(State()) private let onAbort: @Sendable () -> Void
init(onAbort: @escaping @Sendable () -> Void) { self.onAbort = onAbort }
var isPending: Bool { state.withLock { $0.result == nil } }
func wait(timeout: Double) async throws -> Value { precondition(timeout.isFinite && timeout > 0) return try await withTaskCancellationHandler { try await withCheckedThrowingContinuation { continuation in let result = state.withLock { state -> Result<Value, any Error>? in if let result = state.result { return result } state.continuation = continuation return nil } if let result { continuation.resume(with: result) return } let timer = AXWatchdogDeadline(deadline: timeout, queue: .global(qos: .utility)) { [weak self] in self?.finish(.failure(AXPlatformError.timedOut), abort: true) } let installed = state.withLock { state in guard state.result == nil else { return false } state.timer = timer return true } if !installed { timer.cancel() } } } onCancel: { self.finish(.failure(CancellationError()), abort: true) } }
func finish(_ result: Result<Value, any Error>, abort: Bool = false) { let completed = state.withLock { state -> (CheckedContinuation<Value, any Error>?, AXWatchdogDeadline?)? in guard state.result == nil else { return nil } state.result = result let completed = (state.continuation, state.timer) state.continuation = nil state.timer = nil return completed } guard let completed else { return } if abort { onAbort() } completed.1?.cancel() completed.0?.resume(with: result) }}
extension AppThreadExecutor { func performBounded<Value: Sendable>( timeout: Double, onAbort: @escaping @Sendable () -> Void = {}, _ operation: @escaping @Sendable () throws -> Value ) async throws -> Value { let job = AppThreadBoundedJob<Value>(onAbort: onAbort) return try await withTaskCancellationHandler { try Task.checkCancellation() submit( run: { guard job.isPending else { return } do { job.finish(.success(try operation())) } catch { job.finish(.failure(error)) } }, cancel: { job.finish(.failure(AppThreadFailure.stopped), abort: true) }) return try await job.wait(timeout: timeout) } onCancel: { job.finish(.failure(CancellationError()), abort: true) } }}
// The lock protects the queue and run-loop handles; jobs themselves only run on the owner thread.final class AppThreadExecutor: @unchecked Sendable { private struct Job: Sendable { let run: @Sendable () -> Void let cancel: @Sendable () -> Void } private let lock = NSLock() private var jobs: [Job] = [] private var stopping = false private var runLoop: CFRunLoop? private var source: CFRunLoopSource? private let start: @Sendable () -> Void private let stop: @Sendable () -> Void private let failure: @Sendable () -> Void
init( start: @escaping @Sendable () -> Void, stop: @escaping @Sendable () -> Void, failure: @escaping @Sendable () -> Void = {} ) { self.start = start self.stop = stop self.failure = failure Thread { [self] in threadMain() }.start() }
func submit(run: @escaping @Sendable () -> Void, cancel: @escaping @Sendable () -> Void) { lock.lock() guard !stopping else { lock.unlock() cancel() return } jobs.append(Job(run: run, cancel: cancel)) signalLocked() lock.unlock() }
func shutdown() { lock.lock() guard !stopping else { lock.unlock() return } stopping = true let cancelled = jobs jobs.removeAll() signalLocked() lock.unlock() for job in cancelled { job.cancel() } }
private func signalLocked() { if let source { CFRunLoopSourceSignal(source) } if let runLoop { CFRunLoopWakeUp(runLoop) } }
private func threadMain() { guard let runLoop = CFRunLoopGetCurrent() else { failure() shutdown() stop() return } var context = CFRunLoopSourceContext( version: 0, info: Unmanaged.passUnretained(self).toOpaque(), retain: nil, release: nil, copyDescription: nil, equal: nil, hash: nil, schedule: nil, cancel: nil, perform: { info in guard let info else { return } Unmanaged<AppThreadExecutor>.fromOpaque(info).takeUnretainedValue().drain() } ) guard let source = CFRunLoopSourceCreate(nil, 0, &context) else { failure() shutdown() stop() return } CFRunLoopAddSource(runLoop, source, .defaultMode) lock.lock() self.runLoop = runLoop self.source = source signalLocked() lock.unlock() start() CFRunLoopRun() lock.lock() let unexpectedExit = !stopping lock.unlock() if unexpectedExit { failure() } shutdown() stop() CFRunLoopRemoveSource(runLoop, source, .defaultMode) lock.lock() self.source = nil self.runLoop = nil lock.unlock() }
private func drain() { lock.lock() if stopping { lock.unlock() CFRunLoopStop(CFRunLoopGetCurrent()) return } guard !jobs.isEmpty else { lock.unlock() return } let job = jobs.removeFirst() if !jobs.isEmpty { signalLocked() } lock.unlock() job.run() }}