public import Foundation public import ParcelAnimation public import ParcelConfig public import ParcelCore public import ParcelPlatform public enum FrameChangeOrigin: Sendable, Equatable { case user case engine(UInt64) case reconciled case unknown } public enum SystemWindowConflict: Equatable, Sendable { case stageManager case nativeTiling case both case unverified } public enum EnginePlatformEvent: Sendable { indirect case detected(EnginePlatformEvent, traces: [DetectionTrace]) case observed(Event) case placementReadBack(initial: Rect, target: Rect, final: Rect) case pointerButton(isDown: Bool) case frameChanged(WindowID, frame: Rect, resized: Bool, origin: FrameChangeOrigin) case appLaunched(AppID, at: Double) case appExited(AppID) case appAvailable(AppID) case appResponsivenessChanged(AppID, isResponsive: Bool) case suspendedDisplaysChanged(Set) case displaySuspensionsChanged([DisplaySuspension], provisionalDisplays: Set = []) case systemWindowConflictChanged(SystemWindowConflict?) case failure(EnginePlatformFailure) } extension EnginePlatformEvent { public var untraced: EnginePlatformEvent { if case .detected(let event, _) = self { return event.untraced } return self } public func dropDetectionTracing() { if case .detected(let event, let traces) = self { for trace in traces { trace.dropIfUnowned() } event.dropDetectionTracing() } } } public enum EngineOperationFailure: Error, Sendable, Equatable { case activationRefused(AppID) case focusUnchanged(WindowID) case displayLinkUnavailable(DisplayID) case pointerMonitorUnavailable case missingSpace(WindowID, display: DisplayID?) case missingApplicationNotification } public struct EngineUnexpectedFailure: Error, Sendable, Equatable { public let cause: any Error private let identity = UUID() public init(cause: any Error) { self.cause = cause } public static func == (lhs: Self, rhs: Self) -> Bool { lhs.identity == rhs.identity } } public enum EnginePlatformFailure: Error, Sendable, Equatable { case appUnavailable(AppID) case accessibility(AppID, window: WindowID?, cause: AXPlatformError) case appThread(AppID, cause: AppThreadFailure) case operation(EngineOperationFailure) case unexpected(EngineUnexpectedFailure) case timedOut(AppID) case vanished(WindowID) case permissionLost case correctiveWriteLimit(WindowID, limit: Int) } extension EnginePlatformFailure { var vanishedWindow: WindowID? { switch self { case .vanished(let window), .accessibility(_, .some(let window), .elementInvalid): window case .appThread(_, .windowNotFound(let raw)): WindowID(rawValue: raw) default: nil } } var isTimeout: Bool { switch self { case .timedOut, .accessibility(_, _, .timedOut), .appThread(_, .operationOverdue): true case .unexpected(let failure): Self.contains(failure.cause, accessibility: .timedOut) default: false } } var isPermissionLoss: Bool { switch self { case .permissionLost, .accessibility(_, _, .notPermitted): true case .unexpected(let failure): Self.contains(failure.cause, accessibility: .notPermitted) default: false } } private static func contains(_ error: any Error, accessibility cause: AXPlatformError) -> Bool { if let error = error as? AXPlatformError { return error == cause } if let error = error as? FrameWriteFailure { return contains(error.writeError, accessibility: cause) || contains(error.restoreError, accessibility: cause) } if let error = error as? AppThreadWriteBatchFailure { return error.errors.contains { contains($0, accessibility: cause) } } return false } } public struct EngineFrameWrite: Sendable, Equatable { public let window: WindowID public let frame: Rect public let transaction: UInt64 public let generation: UInt64 public let isFinal: Bool public let capturesInitialFrame: Bool public let resetsSizeFit: Bool public init( window: WindowID, frame: Rect, transaction: UInt64, generation: UInt64 = 0, isFinal: Bool = true, capturesInitialFrame: Bool = false, resetsSizeFit: Bool = false ) { self.window = window self.frame = frame self.transaction = transaction self.generation = generation self.isFinal = isFinal self.capturesInitialFrame = capturesInitialFrame self.resetsSizeFit = resetsSizeFit } } public struct EngineWriteReceipt: Sendable { /// Fresh window-server frames captured before the first tracked write. public let initialFrames: [WindowFrame] public let frames: [WindowFrame] public let failures: [EnginePlatformFailure] public let duration: Double public let writtenWindowCount: Int? public let frameWriteDiagnostics: [WindowID: AppThreadFrameWriteDiagnostics] public init( frames: [WindowFrame], failures: [EnginePlatformFailure] = [], duration: Double, writtenWindowCount: Int? = nil, initialFrames: [WindowFrame] = [], frameWriteDiagnostics: [WindowID: AppThreadFrameWriteDiagnostics] = [:] ) { precondition(writtenWindowCount == nil || writtenWindowCount.map { $0 > 0 } == true) self.initialFrames = initialFrames self.frames = frames self.failures = failures self.duration = duration self.writtenWindowCount = writtenWindowCount self.frameWriteDiagnostics = frameWriteDiagnostics } } @MainActor public protocol EngineWindowWorld: AnyObject { var accessibilityPermissionGranted: Bool? { get } func start(receive: @escaping @MainActor (EnginePlatformEvent) -> Void) throws func setDetectionTracing(_ source: (any DetectionTraceSource)?) func stop() func write( _ frames: [EngineFrameWrite], for app: AppID, completion: @escaping @MainActor (EngineWriteReceipt) -> Void ) func focus(_ window: WindowID, completion: @escaping @MainActor (EnginePlatformFailure?) -> Void) func raise(_ window: WindowID, completion: @escaping @MainActor (EnginePlatformFailure?) -> Void) func close(_ window: WindowID) async throws func toggleFullscreen(_ window: WindowID) async throws func reconcile(_ apps: Set) func updatePlacementState(_ state: State, classifier: WindowClassifier?, allowsSpeculation: Bool) func reconcileFrames(_ apps: Set) func cancelFrameWrites(_ window: WindowID, for app: AppID, throughGeneration: UInt64) func stopRestoringFrameWrites() async -> [EnginePlatformFailure] } extension EngineWindowWorld { public var accessibilityPermissionGranted: Bool? { nil } public func setDetectionTracing(_ source: (any DetectionTraceSource)?) {} public func updatePlacementState(_ state: State, classifier: WindowClassifier?, allowsSpeculation: Bool) {} public func reconcileFrames(_ apps: Set) { reconcile(apps) } public func cancelFrameWrites(_ window: WindowID, for app: AppID, throughGeneration: UInt64) {} public func stopRestoringFrameWrites() async -> [EnginePlatformFailure] { stop() return [] } } @MainActor public protocol EngineCommandWindowProviding: AnyObject { func focusedCommandWindow() async throws -> ManagedWindow? } public enum EngineWindowCommandError: Error, Sendable, Equatable, LocalizedError { case busy(WindowID) case fullscreenUnchanged(WindowID) case noFocusedWindow public var errorDescription: String? { switch self { case .busy: String(localized: "Another window command is still finishing. Try again in a moment.", bundle: .module) case .fullscreenUnchanged: String( localized: "macOS did not confirm the fullscreen change. Try again after the window settles.", bundle: .module) case .noFocusedWindow: String(localized: "The focused window is unavailable. Focus a window and try again.", bundle: .module) } } } @MainActor public protocol EngineClock: AnyObject { var now: Double { get } } @MainActor public protocol EngineCancellation: AnyObject { func cancel() } @MainActor public protocol EngineScheduler: AnyObject { func schedule(after delay: Double, _ action: @escaping @MainActor () -> Void) -> any EngineCancellation } @MainActor public protocol EngineDisplayLink: AnyObject { var isRunning: Bool { get } var frameRate: Double { get } func start(tick: @escaping @MainActor (Double) -> Void) func stop() } @MainActor public protocol EngineConfigurationSource: AnyObject { func start(changed: @escaping @MainActor (ConfigSnapshot) -> Void) async throws -> ParcelConfiguration func stop() async } @MainActor public protocol EngineAnnouncer: AnyObject { func announce(_ announcement: Announcement) } public struct EngineFrameAdjustment: Codable, Sendable, Equatable { public static let currentVersion = 1 public let schemaVersion: Int public let requested: Rect public let accepted: Rect public let frameWrite: AppThreadFrameWriteDiagnostics? public init(requested: Rect, accepted: Rect, frameWrite: AppThreadFrameWriteDiagnostics? = nil) { schemaVersion = Self.currentVersion self.requested = requested self.accepted = accepted self.frameWrite = frameWrite } } public enum EngineDiagnostic: Sendable { case internalFailure(any Error) case workspaceStorage(any Error) case frameAdjusted(WindowID, EngineFrameAdjustment) case core(Report) case platform(EnginePlatformFailure) case motion(MotionError) case config([ConfigDiagnostic]) case configuration(String) } @MainActor public protocol EngineLogSink: AnyObject { func record(_ diagnostic: EngineDiagnostic) func flush() func forgetFailures(for app: AppID) } extension EngineLogSink { public func flush() {} public func forgetFailures(for app: AppID) {} } public enum EngineTraceStage: String, Sendable { case eventToFirstWrite, eventToSettled, detect, apply, layout, diff, reduce, plan, write, settle } @MainActor public protocol EngineEventRecorder: AnyObject { func record(_ events: [Event]) } @MainActor public protocol EngineTraceSink: AnyObject { var isEnabled: Bool { get } nonisolated var detectionSource: (any DetectionTraceSource)? { get } var emissionSink: (any ParcelTraceSink)? { get } func begin(_ stage: EngineTraceStage, transaction: UInt64) func end(_ stage: EngineTraceStage, transaction: UInt64) } extension EngineTraceSink { public var isEnabled: Bool { true } public nonisolated var detectionSource: (any DetectionTraceSource)? { nil } public var emissionSink: (any ParcelTraceSink)? { nil } } public struct EngineCommandResult: Sendable, Equatable { public let revision: UInt64 public let reports: [Report] public let isAccepted: Bool } public struct EngineSnapshot: Sendable, Equatable { public let revision: UInt64 public let state: State public var readbackFrames: [WindowID: Rect] = [:] public var focusedMotionPlan: EngineFocusMotionPlan? = nil public var displaySuspensions: [DisplaySuspension] = [] public var layouts: [DisplayID: Layout] { Dictionary( uniqueKeysWithValues: state.workspaces.keys.sorted().filter(state.isActive).compactMap { key in state.workspaces[key].map { (key.display, $0.layout) } }) } public var tiles: [WindowFrame] { state.visibleWindows.compactMap { window in state.frames[window].map { WindowFrame(window: window, frame: $0) } } } public var focusedWindow: WindowID? { state.focusedWindow } }