public import CoreGraphics public import Foundation import Synchronization import os enum AppThreadWriteTrace { static let enabled = ProcessInfo.processInfo.environment["PARCEL_TRACE"] == "1" private static let signposter = OSSignposter(subsystem: "com.parcel", category: .pointsOfInterest) static func begin() -> OSSignpostIntervalState? { guard enabled else { return nil } return signposter.beginInterval("ax.write", id: signposter.makeSignpostID()) } static func end(_ interval: OSSignpostIntervalState?, calls: Int, duration: Double, windows: Int, final: Bool) { guard let interval else { return } let perWindowMilliseconds = duration * 1_000 / Double(max(1, windows)) signposter.endInterval( "ax.write", interval, "calls=\(calls) perWindowMs=\(perWindowMilliseconds) final=\(final)") } static func frameRead(window: CGWindowID, reason: String) { guard enabled else { return } signposter.emitEvent("ax.read.frame", "window=\(window) reason=\(reason, privacy: .public)") } private static let logger = Logger(subsystem: "com.parcel", category: "ax.sizeCorrection") static func sizeCorrection(window: CGWindowID, requested: CGSize, actual: CGRect, attempt: Int) { guard enabled else { return } logger.notice( "window=\(window) attempt=\(attempt) requested=\(Double(requested.width))x\(Double(requested.height)) AX=(\(Double(actual.minX)),\(Double(actual.minY)),\(Double(actual.width)),\(Double(actual.height)))" ) do { let rows = try WindowServer().windows(options: .optionIncludingWindow, relativeTo: window) guard let frame = rows.first(where: { $0.number == window })?.bounds else { logger.error("window=\(window) attempt=\(attempt) CG readback missing") return } logger.notice( "window=\(window) attempt=\(attempt) CG=(\(Double(frame.minX)),\(Double(frame.minY)),\(Double(frame.width)),\(Double(frame.height)))" ) } catch { logger.error( "window=\(window) attempt=\(attempt) CG readback failed: \(String(describing: error), privacy: .public)" ) } } static func setterLimit(window: CGWindowID) { logger.notice("window=\(window) final frame reached the 8-setter AX frame budget; returning readback") } static func toggled(_ value: Bool) { guard enabled else { return } signposter.emitEvent("ax.enhancedUI.toggle", "enabled=\(value)") } } public enum AppThreadFrameWritePhase: Sendable, Equatable { case ongoing case final } public struct AppThreadFrameWrite: Sendable { public let windowID: CGWindowID public let target: CGRect public let writeID: UUID public let generation: UInt64 public let phase: AppThreadFrameWritePhase public let resetsSizeFit: Bool package var preservesSize = false package var setterLimit = AppThreadFrameWriteDiagnostics.maximumSetters public init( windowID: CGWindowID, target: CGRect, writeID: UUID = UUID(), generation: UInt64, phase: AppThreadFrameWritePhase, resetsSizeFit: Bool = false ) { self.windowID = windowID self.target = target self.writeID = writeID self.generation = generation self.phase = phase self.resetsSizeFit = resetsSizeFit } } public struct AppThreadFrameWriteDiagnostics: Codable, Sendable, Equatable { public static let currentVersion = 1 public static let maximumSetters = 8 public struct Axis: Codable, Sendable, Equatable { public enum Kind: String, Codable, Sendable { case grid, plateau, maximum } public let kind: Kind public let anchor: CGFloat public let requestAnchor: CGFloat public let step: CGFloat? public let lowerRequest: CGFloat? } public let schemaVersion: Int public let setterCount: Int public let setterLimit: Int public let limitReached: Bool public let width: Axis? public let height: Axis? init(budget: FrameWriteBudget, fit: FrameSizeFit) { schemaVersion = Self.currentVersion setterCount = budget.count setterLimit = Self.maximumSetters limitReached = budget.limitReached width = fit.width height = fit.height } package func adding(_ other: Self) -> Self { precondition(setterCount + other.setterCount <= Self.maximumSetters) return Self( setterCount: setterCount + other.setterCount, limitReached: limitReached || other.limitReached || setterCount + other.setterCount == Self.maximumSetters, width: width, height: height) } private init(setterCount: Int, limitReached: Bool, width: Axis?, height: Axis?) { schemaVersion = Self.currentVersion self.setterCount = setterCount setterLimit = Self.maximumSetters self.limitReached = limitReached self.width = width self.height = height } } public struct AppThreadFrameWriteReceipt: Sendable { public let windowID: CGWindowID public let writeID: UUID public let generation: UInt64 public let phase: AppThreadFrameWritePhase public let before: CGRect? public let actual: CGRect? public let error: (any Error)? public let diagnostics: AppThreadFrameWriteDiagnostics? init( _ request: AppThreadFrameWrite, before: CGRect?, actual: CGRect?, error: (any Error)?, diagnostics: AppThreadFrameWriteDiagnostics? = nil ) { windowID = request.windowID writeID = request.writeID generation = request.generation phase = request.phase self.before = before self.actual = actual self.error = error self.diagnostics = diagnostics } } public struct AppThreadWriteBatchReceipt: Sendable { public let windows: [AppThreadFrameWriteReceipt] public let duration: Double public let cleanupErrors: [any Error] public let axCallCount: Int } public struct AppThreadWriteBatchFailure: Error, Sendable { public let errors: [any Error] } public enum AppThreadFrameWriteError: Error, Sendable, Equatable { case staleGeneration(CGWindowID, UInt64) case duplicateWindow(CGWindowID) } final class AppThreadShutdownResult: Sendable { private struct State { var result: Result? var waiters: [CheckedContinuation] = [] } private let state = Mutex(State()) func wait() async throws { try await withCheckedThrowingContinuation { continuation in let result = state.withLock { state -> Result? in if let result = state.result { return result } state.waiters.append(continuation) return nil } if let result { continuation.resume(with: result) } } } func complete(_ error: (any Error)?) { let result: Result = error.map { .failure($0) } ?? .success(()) let waiters = state.withLock { state in precondition(state.result == nil, "App thread shutdown completed twice") state.result = result let waiters = state.waiters state.waiters.removeAll() return waiters } for waiter in waiters { waiter.resume(with: result) } } } final class AppThreadWriteCancellation: Sendable { private let cancelled = Mutex(false) var isCancelled: Bool { cancelled.withLock { $0 } } func cancel() { cancelled.withLock { $0 = true } } } // Kept on the owning app thread, including cancellation and notification handling. final class AppThreadFrameWriter { private struct Motion { let frame: CGRect } private struct Generation { let value: UInt64 var closed: Bool } private var active: [CGWindowID: Motion] = [:] private var generations: [CGWindowID: Generation] = [:] private var sizeFits: [CGWindowID: FrameSizeFit] = [:] private var enhancedUI: EnhancedUIBurstGuard init(onEnhancedUIDisableUnsupported: @escaping (AXPlatformError) -> Void = EnhancedUIBurstGuard.reportUnsupported) { enhancedUI = EnhancedUIBurstGuard(onUnsupported: onEnhancedUIDisableUnsupported) } func generationForStandaloneWrite(for windowID: CGWindowID) -> UInt64 { guard let previous = generations[windowID] else { return 0 } guard previous.closed else { return previous.value } precondition(previous.value < .max, "Frame write generation exhausted") return previous.value + 1 } func suppressesFrameNotification(windowID: CGWindowID, pointerIsDown: Bool) -> Bool { active[windowID] != nil && !pointerIsDown } func refreshAssistiveTechnology( _ technology: AssistiveTechnology, application: Application ) throws { if technology.voiceOver || technology.switchControl { try enhancedUI.restore(application: application) } } @discardableResult func cancel( windowIDs: Set? = nil, throughGeneration: UInt64? = nil, application: Application ) throws -> Set { let ids = windowIDs ?? Set(generations.keys) var cancelled: Set = [] for id in ids { if let generation = generations[id], let throughGeneration, generation.value > throughGeneration { continue } guard let watermark = throughGeneration ?? generations[id]?.value else { continue } active.removeValue(forKey: id) generations[id] = Generation(value: watermark, closed: true) cancelled.insert(id) } if active.isEmpty { try enhancedUI.restore(application: application) } return cancelled } func resetSizeFits(windowIDs: Set? = nil) { if let windowIDs { for id in windowIDs { sizeFits[id] = nil } } else { sizeFits.removeAll() } } func forget(_ id: CGWindowID, application: Application) throws { // A queued old write must not acquire a recycled window ID. sizeFits[id] = nil try cancel(windowIDs: [id], application: application) } func write( _ requests: [AppThreadFrameWrite], application: Application, assistiveTechnology: () -> AssistiveTechnology, resolve: (CGWindowID) throws -> Window, isCancelled: @escaping () -> Bool = { false } ) -> (windows: [AppThreadFrameWriteReceipt], cleanupErrors: [any Error]) { var receipts: [AppThreadFrameWriteReceipt] = [] var cleanupErrors: [any Error] = [] var failed = false for request in requests { if let previous = generations[request.windowID], request.generation < previous.value || (request.generation == previous.value && previous.closed) { receipts.append( AppThreadFrameWriteReceipt( request, before: nil, actual: nil, error: AppThreadFrameWriteError.staleGeneration(request.windowID, request.generation))) continue } if request.resetsSizeFit { resetSizeFits(windowIDs: [request.windowID]) } let budget = FrameWriteBudget(limit: request.setterLimit, isCancelled: isCancelled) var fit = sizeFits[request.windowID] ?? FrameSizeFit() var before: CGRect? var actual: CGRect? var resolved: Window? var attemptedWrite = false do { if isCancelled() { throw CancellationError() } let window = try resolve(request.windowID) resolved = window let current: CGRect if let motion = active[request.windowID] { current = motion.frame } else { AppThreadWriteTrace.frameRead(window: request.windowID, reason: "initial") current = try window.frame before = current } if isCancelled() { throw CancellationError() } generations[request.windowID] = Generation(value: request.generation, closed: false) let changes = request.preservesSize ? current.origin != request.target.origin : current != request.target if changes { try enhancedUI.prepare(application: application, assistiveTechnology: assistiveTechnology()) } else { try refreshAssistiveTechnology(assistiveTechnology(), application: application) } if isCancelled() { throw CancellationError() } if request.phase == .final && before == request.target { actual = before } else { attemptedWrite = true if request.phase == .final { AppThreadWriteTrace.frameRead(window: request.windowID, reason: "final") } actual = try executeMotionFrameWrite( request.target, window: window, current: current, final: request.phase == .final, preservingSize: request.preservesSize, fit: &fit, budget: budget) sizeFits[request.windowID] = fit } if request.phase == .ongoing { active[request.windowID] = Motion( frame: CGRect( origin: request.target.origin, size: request.preservesSize ? current.size : request.target.size)) } else { active.removeValue(forKey: request.windowID) } let diagnostics = AppThreadFrameWriteDiagnostics(budget: budget, fit: fit) if diagnostics.limitReached { AppThreadWriteTrace.setterLimit(window: request.windowID) } receipts.append( AppThreadFrameWriteReceipt( request, before: before, actual: actual, error: nil, diagnostics: request.phase == .final ? diagnostics : nil)) } catch { sizeFits[request.windowID] = nil fit = FrameSizeFit() if attemptedWrite, let resolved { do { actual = try resolved.frame } catch let readError { cleanupErrors.append(readError) } } let cancelled = error is CancellationError if !cancelled { failed = true } active.removeValue(forKey: request.windowID) generations[request.windowID] = Generation(value: request.generation, closed: cancelled) receipts.append( AppThreadFrameWriteReceipt( request, before: before, actual: actual, error: error, diagnostics: request.phase == .final ? AppThreadFrameWriteDiagnostics(budget: budget, fit: fit) : nil)) } } do { if failed { active.removeAll() try enhancedUI.restore(application: application) } else if isCancelled() { for request in requests { try cancel( windowIDs: [request.windowID], throughGeneration: request.generation, application: application) } } else if active.isEmpty { try enhancedUI.restore(application: application) } else { try refreshAssistiveTechnology(assistiveTechnology(), application: application) } } catch { cleanupErrors.append(error) } return (receipts, cleanupErrors) } } struct EnhancedUIBurstGuard { private static let logger = Logger(subsystem: "com.parcel", category: "ax.enhancedUI") private let onUnsupported: (AXPlatformError) -> Void private var reportedUnsupported = false private var inspected = false private var restorationRequired = false init(onUnsupported: @escaping (AXPlatformError) -> Void = Self.reportUnsupported) { self.onUnsupported = onUnsupported } static func reportUnsupported(_ error: AXPlatformError) { logger.notice( "AXEnhancedUserInterface could not be disabled for this app session; optional setter unsupported: \(String(describing: error), privacy: .public). Frame readback remains required." ) } mutating func prepare( application: Application, assistiveTechnology: AssistiveTechnology ) throws { if assistiveTechnology.voiceOver || assistiveTechnology.switchControl { try restore(application: application) return } guard !inspected else { return } let enabled: Bool do { enabled = try application.enhancedUI } catch AXPlatformError.attributeUnsupported { // Absence permits this write, but does not prove the next window's guard is disabled. return } if enabled { // A failed set can still have changed the remote app. restorationRequired = true do { try application.setEnhancedUI(false) } catch let error as AXPlatformError where Self.isOptionalSetterUnsupported(error) { // Only a successful readback establishes whether the failed setter changed the app. if try application.enhancedUI { restorationRequired = false if !reportedUnsupported { reportedUnsupported = true onUnsupported(error) } // A read-only value is not a disabled guard; each sibling must attempt its own disable. return } } } inspected = true } mutating func restore(application: Application) throws { inspected = false if restorationRequired { do { try application.setEnhancedUI(true) } catch let error as AXPlatformError where Self.isOptionalSetterUnsupported(error) { guard try application.enhancedUI else { throw error } } restorationRequired = false } } private static func isOptionalSetterUnsupported(_ error: AXPlatformError) -> Bool { error == .attributeUnsupported || error == .other(-25208) } } func executeMotionFrameWrite( _ target: CGRect, window: Window, current: CGRect, final: Bool, preservingSize: Bool = false ) throws -> CGRect? { var fit = FrameSizeFit() return try executeMotionFrameWrite( target, window: window, current: current, final: final, preservingSize: preservingSize, fit: &fit, budget: FrameWriteBudget()) } extension AppThreadFrameWriteDiagnostics.Axis { func prediction(_ limit: CGFloat) -> (request: CGFloat, actual: CGFloat)? { switch kind { case .maximum: return limit > anchor ? (limit, anchor) : nil case .plateau: guard let lowerRequest, limit >= lowerRequest, limit <= anchor else { return nil } return (limit, anchor) case .grid: guard let step else { return nil } let size = anchor + ((limit - anchor) / step).rounded(.down) * step let request = requestAnchor + size - anchor return size > 0 && request > 1 ? (request, size) : nil } } } struct FrameSizeFit { typealias Axis = AppThreadFrameWriteDiagnostics.Axis var width: Axis? var height: Axis? func matches(_ actual: CGSize, target: CGSize) -> Bool { let w = width?.prediction(target.width) let h = height?.prediction(target.height) return (w == nil || w?.actual == actual.width) && (h == nil || h?.actual == actual.height) } func accepts(_ actual: CGSize, target: CGSize) -> Bool { matches(actual, target: target) && (actual.width <= target.width || width?.prediction(target.width)?.actual == actual.width) && (actual.height <= target.height || height?.prediction(target.height)?.actual == actual.height) } func prediction(_ size: CGSize) -> (request: CGSize, actual: CGSize) { let w = width?.prediction(size.width) let h = height?.prediction(size.height) return ( CGSize(width: w?.request ?? size.width, height: h?.request ?? size.height), CGSize(width: w?.actual ?? size.width, height: h?.actual ?? size.height) ) } } private func executeMotionFrameWrite( _ target: CGRect, window: Window, current: CGRect, final: Bool, preservingSize: Bool, fit: inout FrameSizeFit, budget: FrameWriteBudget ) throws -> CGRect? { let bounded = BudgetedFrameWriteAccess(window: window, budget: budget) do { return try executeBoundedMotionFrameWrite( target, window: bounded, current: current, final: final, preservingSize: preservingSize, fit: &fit, budget: budget) } catch is FrameWriteBudgetExhausted { // Exhaustion is an explicit receipt state, not evidence that the requested frame succeeded. return final ? try window.frame : nil } } private func executeBoundedMotionFrameWrite( _ target: CGRect, window: Window, current: CGRect, final: Bool, preservingSize: Bool, fit: inout FrameSizeFit, budget: FrameWriteBudget ) throws -> CGRect? { let prediction = fit.prediction(target.size) var requested = final && !preservingSize ? prediction.request : target.size let resized = !preservingSize && current.size != requested if resized { try window.setSize(requested) } if resized || current.origin != target.origin { try window.setPosition(target.origin) } if final { var actual = try window.frame let confirmUnchangedProbe = !resized || actual.size == current.size if preservingSize { if actual.origin != target.origin { try window.setPosition(target.origin) actual = try window.frame } return actual } if actual.size != prediction.actual { actual = try readAfterSizeWrite(requested, origin: target.origin, window: window) } // An unchanged smaller reply can be lag, not a contained resize result. if actual.size == current.size, prediction.actual.width > current.width || prediction.actual.height > current.height { for _ in 0..<2 { actual = try readAfterSizeWrite(requested, origin: target.origin, window: window) if actual.size != current.size { break } } } if !fit.matches(actual.size, target: target.size) { fit = FrameSizeFit() requested = target.size actual = try readAfterSizeWrite(requested, origin: target.origin, window: window) } // The motion cache records requests, not what the app accepted. if actual.origin != target.origin { try window.setPosition(target.origin) actual = try window.frame if actual.size != target.size { requested = target.size actual = try readAfterSizeWrite(requested, origin: target.origin, window: window) } } if !fit.matches(actual.size, target: target.size) { fit = FrameSizeFit() } if actual.size == current.size { if requested.width > actual.width, prediction.actual.width > actual.width { fit.width = FrameSizeFit.Axis( kind: .maximum, anchor: actual.width, requestAnchor: requested.width, step: nil, lowerRequest: nil) } if requested.height > actual.height, prediction.actual.height > actual.height { fit.height = FrameSizeFit.Axis( kind: .maximum, anchor: actual.height, requestAnchor: requested.height, step: nil, lowerRequest: nil ) } } if fit.accepts(actual.size, target: target.size), fit.width != nil || fit.height != nil { return actual } // Settle a large stale reply before using its overshoot to choose any probe. if actual.size == current.size, actual.width - target.width > 32 || actual.height - target.height > 32 { requested = target.size for _ in 0..<2 { let next = try readAfterSizeWrite(requested, origin: target.origin, window: window) if next.size == target.size { return next } actual = next } if actual.size == current.size { if actual.width > target.width { fit.width = FrameSizeFit.Axis( kind: .plateau, anchor: actual.width, requestAnchor: requested.width, step: nil, lowerRequest: requested.width) } if actual.height > target.height { fit.height = FrameSizeFit.Axis( kind: .plateau, anchor: actual.height, requestAnchor: requested.height, step: nil, lowerRequest: requested.height) } return actual } } return try fitFinalFrame( target, requested: requested, actual: actual, window: window, fit: &fit, budget: budget, confirmUnchanged: confirmUnchangedProbe) } if resized, try window.size != target.size { try window.setSize(target.size) } return nil } private func readAfterSizeWrite( _ size: CGSize, origin: CGPoint, window: Window ) throws -> CGRect { try window.setSize(size) let actual = try window.frame guard actual.origin != origin else { return actual } try window.setPosition(origin) return try window.frame } private func fitFinalFrame( _ target: CGRect, requested: CGSize, actual: CGRect, window: Window, fit: inout FrameSizeFit, budget: FrameWriteBudget, confirmUnchanged: Bool ) throws -> CGRect { guard actual.width > target.width || actual.height > target.height else { return actual } var width = FrameSizeFitSearch(limit: target.width, request: requested.width, actual: actual.width) var height = FrameSizeFitSearch(limit: target.height, request: requested.height, actual: actual.height) var actual = actual for attempt in 0..<8 { let nextWidth = width.next let nextHeight = height.next guard nextWidth != nil || nextHeight != nil else { break } // Refinement already has a contained fallback; an unexplored axis also needs confirmation room. let refiningContained = (nextWidth == nil || width.hasContained) && (nextHeight == nil || height.hasContained) guard budget.remaining >= (confirmUnchanged && !refiningContained ? 3 : 2) else { budget.stopFitting() break } let size = CGSize(width: nextWidth ?? width.best, height: nextHeight ?? height.best) actual = try sizeCorrection( size, previous: actual.size, origin: target.origin, window: window, attempt: attempt, confirmUnchanged: confirmUnchanged) width.observe(request: size.width, actual: actual.width) height.observe(request: size.height, actual: actual.height) } let best = CGSize(width: width.best, height: height.best) fit.width = width.learned ?? fit.width fit.height = height.learned ?? fit.height if width.needsRestore || height.needsRestore { actual = try sizeCorrection( best, previous: actual.size, origin: target.origin, window: window, attempt: 8, confirmUnchanged: confirmUnchanged) } return actual } private func sizeCorrection( _ size: CGSize, previous: CGSize, origin: CGPoint, window: Window, attempt: Int, confirmUnchanged: Bool ) throws -> CGRect { let first = try readAfterSizeWrite(size, origin: origin, window: window) window.recordSizeCorrection(size, actual: first, attempt: attempt * 2) guard first.size == previous else { return first } // A session that already returned a stale frame needs another setter, not just another stale read. let confirmed = confirmUnchanged ? try readAfterSizeWrite(size, origin: origin, window: window) : try window.frame window.recordSizeCorrection(size, actual: confirmed, attempt: attempt * 2 + 1) return confirmed } private struct FrameSizeFitSearch { let limit: CGFloat private var contained: CGFloat? private var containedActual: CGFloat? private var rejected: CGFloat private var rejectedActual: CGFloat private var step: CGFloat = 2 private var lastRequest: CGFloat private var plateauLowerRequest: CGFloat? private var plateauActual: CGFloat? private var refinements = 0 private let lowerRequest: CGFloat init(limit: CGFloat, request: CGFloat, actual: CGFloat) { self.limit = limit contained = actual <= limit ? request : nil containedActual = actual <= limit ? actual : nil rejected = actual > limit ? request : limit rejectedActual = actual lastRequest = request // Unknown capabilities never justify collapsing a live window to find a global minimum. lowerRequest = max(2, limit / 2, limit - 64) } var best: CGFloat { contained ?? limit } var hasContained: Bool { contained != nil } var needsRestore: Bool { lastRequest != best } var learned: FrameSizeFit.Axis? { if let contained, let containedActual, rejectedActual > limit, rejectedActual > containedActual { return FrameSizeFit.Axis( kind: .grid, anchor: containedActual, requestAnchor: contained, step: rejectedActual - containedActual, lowerRequest: nil) } guard let plateauLowerRequest, let plateauActual else { return nil } return FrameSizeFit.Axis( kind: .plateau, anchor: plateauActual, requestAnchor: limit, step: nil, lowerRequest: plateauLowerRequest) } var next: CGFloat? { if let contained, let containedActual { let nearby = contained + limit - containedActual return refinements == 0 && nearby > contained && nearby < rejected ? nearby : nil } let nearby = max(lowerRequest, rejected - max(step, rejectedActual - limit)) return nearby > 1 && nearby < rejected ? nearby : nil } mutating func observe(request: CGFloat, actual: CGFloat) { lastRequest = request if actual <= limit { if contained != nil { refinements += 1 } if actual >= (containedActual ?? -.infinity) { contained = request containedActual = actual } plateauLowerRequest = nil plateauActual = nil } else { if actual == rejectedActual { plateauLowerRequest = request plateauActual = actual } else { plateauLowerRequest = nil plateauActual = nil } rejected = request rejectedActual = actual step *= 2 } } } struct AppThreadWindowCache { private var windows: [CGWindowID: Window] = [:] subscript(id: CGWindowID) -> Window? { get { windows[id] } set { windows[id] = newValue } } mutating func removeAll() { windows.removeAll() } func resolve(_ id: CGWindowID, onMiss: () throws -> Window) rethrows -> Window { if let window = windows[id] { return window } return try onMiss() } }