import Foundation public import ParcelCore public import ParcelIPC @MainActor public protocol EngineWindowInspectionProviding { func inspectionWindow(_ id: WindowID) -> ManagedWindow? func focusedInspectionWindow(pid: Int32) async throws -> ManagedWindow? } extension EngineIPCHandler { public func why(window rawID: UInt32) async throws -> JSONValue { let id = WindowID(rawValue: rawID) let window = engine.observations[id]?.window ?? (engine.world as? any EngineWindowInspectionProviding)?.inspectionWindow(id) guard let window else { throw IPCError(code: "window_not_found", message: String(localized: "Window not found.", bundle: .module)) } var classification = engine.classifications[id] ?? engine.classify(window) if let managed = engine.snapshot.state.windows[id], managed.managementReason == .whenFull { classification.disposition = managed.isFloating ? .float : .tile classification.reason = .whenFull } let facts = engine.classificationFacts(for: window) let profile = engine.applied.classifier.appProfile(for: facts) let minimum = engine.snapshot.state.windows[id]?.minimum return .object([ "id": .integer(Int64(rawID)), "bundle_id": .string(window.app.bundleID), "disposition": .string(classification.disposition.rawValue), "reason": .string(Self.explanation(classification)), "classification_reason": try Self.encoded(classification.reason), "app_profile": try Self.encoded(profile), "facts": try Self.encoded(facts), "minimum": try Self.encoded(minimum), "frame": try Self.encoded( engine.actualFrames[id] ?? engine.snapshot.readbackFrames[id] ?? engine.snapshot.state.observedFrames[id]), "target_frame": try Self.encoded(engine.snapshot.state.frames[id]), "frame_adjustment": try Self.encoded(engine.frameAdjustments[id]), "frame_write": try Self.encoded( engine.frameWriteDiagnostics[id] ?? engine.frameAdjustments[id]?.frameWrite), "display": classification.display.map { .string($0.rawValue) } ?? .null, "position": classification.position.map { .integer(Int64($0)) } ?? .null, "layout": classification.layout.map { .string($0.rawValue) } ?? .null, "space": classification.space.map { .integer(Int64($0)) } ?? .null, "move_to_space": .bool(classification.moveToSpace), ]) } private static func encoded(_ value: some Encodable) throws -> JSONValue { try JSONDecoder().decode(JSONValue.self, from: JSONEncoder().encode(value)) } private static func explanation(_ classification: WindowClassification) -> String { let cause = localizedCause(classification.reason) let template: String switch classification.disposition { case .tile: template = String(localized: "Tiling because %@.", bundle: .module) case .float: template = String(localized: "Floating because %@.", bundle: .module) case .ignore: template = String(localized: "Ignoring because %@.", bundle: .module) } return String(format: template, cause) } private static func localizedCause(_ reason: ClassificationReason) -> String { switch reason { case .defaultFloatApp(let bundleID): if bundleID == "com.apple.PIPAgent" { return String(localized: "it's picture-in-picture", bundle: .module) } return String(format: String(localized: "%@ is in the default float list", bundle: .module), bundleID) case .nativeTab: return String(localized: "native tabs share one tile", bundle: .module) case .rule(_, let bundleID), .legacyRule(let bundleID): return String(format: String(localized: "your rule matches %@", bundle: .module), bundleID) default: break } let causes: [(ClassificationReason, String)] = [ (.standardWindow, String(localized: "it's a standard window", bundle: .module)), (.fullScreen, String(localized: "it's fullscreen", bundle: .module)), (.minimized, String(localized: "it's minimized", bundle: .module)), (.notWindow, String(localized: "it's not a window", bundle: .module)), (.helper, String(localized: "it's a helper", bundle: .module)), (.dialog, String(localized: "it's a dialog", bundle: .module)), (.sheet, String(localized: "it's a sheet", bundle: .module)), (.panel, String(localized: "it's a panel", bundle: .module)), (.nonResizable, String(localized: "it can't be resized", bundle: .module)), (.fixedSize, String(localized: "it has fixed size bounds", bundle: .module)), (.elevatedLayer, String(localized: "it's on an elevated layer", bundle: .module)), (.tinyWindow, String(localized: "it's a tiny utility window", bundle: .module)), (.pictureInPicture, String(localized: "it's picture-in-picture", bundle: .module)), (.quickTerminal, String(localized: "it's a quick terminal", bundle: .module)), (.launcher, String(localized: "it's a launcher", bundle: .module)), (.quickLook, String(localized: "it's a preview", bundle: .module)), (.splash, String(localized: "it's a splash screen", bundle: .module)), (.manual, String(localized: "you changed it", bundle: .module)), (.whenFull, String(localized: "the workspace is full", bundle: .module)), ] return causes.first { $0.0 == reason }?.1 ?? String(localized: "it's a window", bundle: .module) } }