Merge pull request #555 from insidegui/catalog-mobile-device-instructions

insidegui · web-flow · commit 4c00a4a07d4e · 2025-06-25T13:31:45.000-03:00
Make device support update requirement more prominent, improve instructions
diff --git a/VirtualBuddy/CommandLine/vctool/Core/Helpers.swift b/VirtualBuddy/CommandLine/vctool/Core/Helpers.swift
@@ -114,9 +114,9 @@ extension ResolvedFeatureStatus {
         switch self {
         case .supported:
             return "✅ Supported"
-        case .warning(let message):
+        case .warning(_, let message):
             return "⚠️ Warning: \(message)"
-        case .unsupported(let message):
+        case .unsupported(_, let message):
             return "🛑 Not Supported: \(message)"
         }
     }
diff --git a/VirtualBuddy/CommandLine/vctool/MigrateCommand.swift b/VirtualBuddy/CommandLine/vctool/MigrateCommand.swift
@@ -52,7 +52,7 @@ extension CatalogCommand {
             } else {
                 fputs("Creating empty version 2 catalog for migration\n", stderr)
 
-                catalog = SoftwareCatalog(apiVersion: 2, minAppVersion: .init(string: "2.0.0")!, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [])
+                catalog = SoftwareCatalog(apiVersion: 2, minAppVersion: .init(string: "2.0.0")!, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [], deviceSupportVersions: [])
             }
 
             for legacyChannel in legacyCatalog.channels {
diff --git a/VirtualCore/Source/VirtualCatalog/ResolvedCatalog.swift b/VirtualCore/Source/VirtualCatalog/ResolvedCatalog.swift
@@ -35,6 +35,7 @@ public struct ResolvedRestoreImage: ResolvedCatalogModel, DownloadableCatalogCon
     public var channel: CatalogChannel
     public var features: [ResolvedVirtualizationFeature]
     public var requirements: ResolvedRequirementSet
+    public var deviceSupportVersion: CatalogDeviceSupportVersion?
     public var status: ResolvedFeatureStatus
     public var localFileURL: URL?
 
@@ -46,13 +47,14 @@ public struct ResolvedRestoreImage: ResolvedCatalogModel, DownloadableCatalogCon
     public var downloadSize: Int64 { Int64(image.downloadSize ?? 0) }
     public var isDownloaded: Bool { localFileURL != nil }
 
-    public init(image: RestoreImage, channel: CatalogChannel, features: [ResolvedVirtualizationFeature], requirements: ResolvedRequirementSet, status: ResolvedFeatureStatus, localFileURL: URL?) {
+    public init(image: RestoreImage, channel: CatalogChannel, features: [ResolvedVirtualizationFeature], requirements: ResolvedRequirementSet, status: ResolvedFeatureStatus, localFileURL: URL?, deviceSupportVersion: CatalogDeviceSupportVersion?) {
         self.image = image
         self.channel = channel
         self.features = features
         self.requirements = requirements
         self.status = status
         self.localFileURL = localFileURL
+        self.deviceSupportVersion = deviceSupportVersion
     }
 }
 
@@ -61,14 +63,21 @@ public enum ResolvedFeatureStatus: Hashable, Sendable {
     /// The feature is fully supported.
     case supported
     /// The feature is partially supported.
-    case warning(message: String)
+    case warning(title: String?, message: String)
     /// The feature is not supported.
-    case unsupported(message: String)
+    case unsupported(title: String?, message: String)
+
+    var title: String? {
+        switch self {
+        case .supported: return nil
+        case .warning(let title, _), .unsupported(let title, _): return title
+        }
+    }
 
     var message: String? {
         switch self {
         case .supported: return nil
-        case .warning(let message), .unsupported(let message): return message
+        case .warning(_, let message), .unsupported(_, let message): return message
         }
     }
 }
@@ -207,7 +216,8 @@ public extension ResolvedRestoreImage {
             features: catalog.features.map { ResolvedVirtualizationFeature(feature: $0, status: .supported, platform: environment.guestPlatform) },
             requirements: ResolvedRequirementSet(requirements: catalog.requirementSet(with: image.requirements), status: .supported),
             status: .supported,
-            localFileURL: environment.downloadsProvider?.localFileURL(for: image)
+            localFileURL: environment.downloadsProvider?.localFileURL(for: image),
+            deviceSupportVersion: catalog.deviceSupportVersion(for: image)
         )
 
         update(with: environment)
@@ -219,7 +229,11 @@ public extension ResolvedRestoreImage {
 
         /// Mobile device requirement is isolated from min host/app requirements.
         if versionedEnvironment.mobileDeviceVersion < image.mobileDeviceMinVersion {
-            self.status = .mobileDeviceOutdated
+            if let deviceSupportVersion {
+                self.status = .unsupported(title: deviceSupportVersion.title, message: deviceSupportVersion.instructions)
+            } else {
+                self.status = .mobileDeviceOutdated
+            }
         }
 
         features = features.map { $0.updated(with: versionedEnvironment) }
@@ -233,6 +247,16 @@ public extension ResolvedRestoreImage {
     }
 }
 
+extension SoftwareCatalog {
+    func deviceSupportVersion(for image: RestoreImage) -> CatalogDeviceSupportVersion? {
+        deviceSupportVersions.first(where: {
+            $0.mobileDeviceMinVersion == image.mobileDeviceMinVersion
+            || ($0.osVersion.major == image.version.major && $0.osVersion.minor == image.version.minor)
+            || $0.osVersion.major == image.version.major
+        })
+    }
+}
+
 public extension ResolvedVirtualizationFeature {
     mutating func update(with environment: CatalogResolutionEnvironment) {
         guard !feature.unsupportedPlatform else {
@@ -286,7 +310,7 @@ public extension ResolvedRequirementSet {
 
 extension ResolvedFeatureStatus {
     static func unsupported(_ message: String?...) -> Self {
-        .unsupported(message: message.compactMap({ $0 }).joined(separator: "\n"))
+        .unsupported(title: nil, message: message.compactMap({ $0 }).joined(separator: "\n"))
     }
 
     static func unsupportedHostAndGuestAligned(_ feature: VirtualizationFeature) -> Self {
@@ -313,16 +337,19 @@ extension ResolvedFeatureStatus {
         .unsupported("Not supported for \(platform.name) guests.", feature.detail)
     }
 
-
     static var mobileDeviceOutdated: Self {
-        .warning(message: """
-        This version of macOS requires device support files which are not currently installed on your system.
-        
-        It's likely that this is a beta for a major macOS version and your Mac is not running the corresponding macOS beta.
-        
-        Device support files can be obtained by installing the Xcode beta, they are sometimes made available separately in the Apple Developer portal.
-        """)
+        .unsupported(title: Self.defaultDeviceSupportUpdateNeededTitle,  message: Self.defaultDeviceSupportUpdateNeededInstructions)
     }
+
+    static let defaultDeviceSupportUpdateNeededTitle = "Device Support Update Required"
+
+    static let defaultDeviceSupportUpdateNeededInstructions = """
+    This version of macOS requires device support files which are not currently installed on your system.
+    
+    It's likely that this is a beta for a major macOS version and your Mac is not running the corresponding macOS beta.
+    
+    Device support files can be obtained by installing the Xcode beta, they are sometimes made available separately in the Apple Developer portal.
+    """
 }
 
 struct CatalogError: LocalizedError, CustomStringConvertible {
@@ -420,7 +447,7 @@ public extension ResolvedVirtualizationFeature {
             case .linux: "Supported. Requires host on macOS \(minVersionHost.shortDescription) or later."
             default: "Supported."
             }
-        case .warning(let message), .unsupported(let message):
+        case .warning(_, let message), .unsupported(_, let message):
             message
         }
     }
diff --git a/VirtualCore/Source/VirtualCatalog/SoftwareCatalog.swift b/VirtualCore/Source/VirtualCatalog/SoftwareCatalog.swift
@@ -127,6 +127,19 @@ public struct CatalogChannel: CatalogModel {
     }
 }
 
+/// Describes a "device support files" installation and the instructions that should be presented to the user when it's required.
+public struct CatalogDeviceSupportVersion: CatalogModel {
+    public var id: String
+    /// Hint for which MobileDevice version this entry refers to.
+    public var mobileDeviceMinVersion: SoftwareVersion
+    /// OS version this entry refers to. Matching will be attempted by `major.minor` first, then `major` only.
+    public var osVersion: SoftwareVersion
+    /// User-facing title displayed on the list of software images.
+    public var title: String
+    /// User-facing instructions displayed in interstitial or when user clicks the warning. May contain markdown.
+    public var instructions: String
+}
+
 /// Adopted by both ``RestoreImage`` and ``ResolvedRestoreImage`` to make download lookup more convenient to implement.
 public protocol DownloadableCatalogContent: Identifiable, Hashable, Sendable {
     var build: String { get }
@@ -188,18 +201,21 @@ public struct SoftwareCatalog: Codable, Sendable {
     public var features: [VirtualizationFeature]
     /// Requirement set definitions.
     public var requirementSets: [RequirementSet]
+    /// Device support files definitions.
+    public var deviceSupportVersions: [CatalogDeviceSupportVersion]
 
-    public init(apiVersion: Int, minAppVersion: SoftwareVersion, channels: [CatalogChannel], groups: [CatalogGroup], restoreImages: [RestoreImage], features: [VirtualizationFeature], requirementSets: [RequirementSet]) {
+    public init(apiVersion: Int, minAppVersion: SoftwareVersion, channels: [CatalogChannel], groups: [CatalogGroup], restoreImages: [RestoreImage], features: [VirtualizationFeature], requirementSets: [RequirementSet], deviceSupportVersions: [CatalogDeviceSupportVersion]) {
         self.apiVersion = apiVersion
         self.minAppVersion = minAppVersion
         self.channels = channels
         self.groups = groups
         self.restoreImages = restoreImages
         self.features = features
         self.requirementSets = requirementSets
+        self.deviceSupportVersions = deviceSupportVersions
     }
 
-    public static let empty = SoftwareCatalog(apiVersion: 0, minAppVersion: .empty, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [])
+    public static let empty = SoftwareCatalog(apiVersion: 0, minAppVersion: .empty, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [], deviceSupportVersions: [])
 }
 
 public extension SoftwareCatalog {
diff --git a/VirtualUI/Source/Installer/Steps/Restore Image Selection/Components/RestoreImageBrowser.swift b/VirtualUI/Source/Installer/Steps/Restore Image Selection/Components/RestoreImageBrowser.swift
@@ -148,16 +148,37 @@ private struct RestoreImageButton: View {
         .buttonStyle(RestoreImageButtonStyle(isSelected: isSelected))
     }
 
+    @State private var showingSupportDetail = false
+
     @ViewBuilder
     var label: some View {
-        HStack {
-            downloadState
+        VStack(alignment: .leading, spacing: 6) {
+            HStack {
+                downloadState
 
-            Spacer()
+                Spacer()
 
-            details
+                details
 
-            supportState
+                supportState
+            }
+
+            if case .unsupported(let title, _) = image.status, let title {
+                Button {
+                    showingSupportDetail.toggle()
+                } label: {
+                    Text(title)
+                        .multilineTextAlignment(.trailing)
+                        .frame(maxWidth: .infinity, alignment: .trailing)
+                        .font(.subheadline)
+                }
+                .buttonStyle(.borderless)
+                .foregroundStyle(Color.red)
+                .blendMode(.plusLighter)
+                .popover(isPresented: $showingSupportDetail) {
+                    RestoreImageFeatureDetailView(image: image)
+                }
+            }
         }
         .monospacedDigit()
         .contextMenu {
@@ -225,8 +246,8 @@ struct RestoreImageFeatureStatusButton: View {
     var helpText: String {
         switch status {
         case .supported: "This version is supported on your Mac. Click for details about supported features."
-        case .warning(let message): message
-        case .unsupported(let message): message
+        case .warning(let title, let message): title ?? message
+        case .unsupported(let title, let message): title ?? message
         }
     }
 
@@ -280,18 +301,28 @@ struct RestoreImageFeatureDetailView: View {
         switch image.status {
         case .supported:
             EmptyView()
-        case .warning(let message), .unsupported(let message):
+        case .warning(let title, let message), .unsupported(let title, let message):
             VStack(alignment: .leading, spacing: 12) {
                 HStack {
                     FeatureStatusLabel(status: image.status)
 
-                    Text("This Version May Not Work")
+                    if let title {
+                        Text(title)
+                    } else {
+                        Text("This Version May Not Work")
+                    }
                 }
                     .imageScale(.large)
                     .font(.headline)
 
-                Text(message)
-                    .fixedSize(horizontal: false, vertical: true)
+                Group {
+                    if let attributedMessage = try? AttributedString(markdown: message, options: .init(allowsExtendedAttributes: true, interpretedSyntax: .inlineOnlyPreservingWhitespace, failurePolicy: .returnPartiallyParsedIfPossible, languageCode: nil)) {
+                        Text(attributedMessage)
+                    } else {
+                        Text(message)
+                    }
+                }
+                .fixedSize(horizontal: false, vertical: true)
             }
             .frame(maxWidth: .infinity, alignment: .leading)
             .padding()
diff --git a/VirtualUI/Source/Installer/Steps/Restore Image Selection/Components/SoftwareCatalog+Placeholder.swift b/VirtualUI/Source/Installer/Steps/Restore Image Selection/Components/SoftwareCatalog+Placeholder.swift
@@ -68,9 +68,9 @@ extension ResolvedRequirementSet {
 }
 
 extension SoftwareCatalog {
-    static let placeholder = SoftwareCatalog(apiVersion: 1, minAppVersion: "1.0", channels: [.placeholder], groups: [.placeholder], restoreImages: [.placeholder], features: [], requirementSets: [.placeholder])
+    static let placeholder = SoftwareCatalog(apiVersion: 1, minAppVersion: "1.0", channels: [.placeholder], groups: [.placeholder], restoreImages: [.placeholder], features: [], requirementSets: [.placeholder], deviceSupportVersions: [])
 }
 
 extension ResolvedRestoreImage {
-    static let placeholder = ResolvedRestoreImage(image: .placeholder, channel: .placeholder, features: [], requirements: .placeholder, status: .supported, localFileURL: nil)
+    static let placeholder = ResolvedRestoreImage(image: .placeholder, channel: .placeholder, features: [], requirements: .placeholder, status: .supported, localFileURL: nil, deviceSupportVersion: nil)
 }
diff --git a/data/ipsws_v2.json b/data/ipsws_v2.json
@@ -208,6 +208,15 @@
       "minVersionHost" : "13.0.0"
     }
   ],
+    "deviceSupportVersions": [
+        {
+            "id": "device_support_macOS26_beta",
+            "mobileDeviceMinVersion": "1810.0.0",
+            "osVersion": "26.0.0",
+            "title": "Device Support Update Required",
+            "instructions": "Your Mac needs an update to install virtual machines that use this version of macOS.\n\nHere’s how you can install the update:\n\n1. Head over to the [Apple Developer downloads page](https://developer.apple.com/download/).\n2. Under “Operating Systems”, find “Device Support for macOS 26”.\n3. Click the link below that item.\n4. Double-click the downloaded DMG and open the installer. Follow the instructions.\n5. Quit and relaunch VirtualBuddy. Then, try again.\n\nInstalling the latest Xcode beta will also install the required update."
+        }
+    ],
   "restoreImages" : [
     {
       "build" : "25A5295e",

Original file line number	Diff line number	Diff line change
`@@ -114,9 +114,9 @@ extension ResolvedFeatureStatus {`
`114`	`114`	`switch self {`
`115`	`115`	`case .supported:`
`116`	`116`	`return "✅ Supported"`
`117`		`- case .warning(let message):`
	`117`	`+ case .warning(_, let message):`
`118`	`118`	`return "⚠️ Warning: \(message)"`
`119`		`- case .unsupported(let message):`
	`119`	`+ case .unsupported(_, let message):`
`120`	`120`	`return "🛑 Not Supported: \(message)"`
`121`	`121`	`}`
`122`	`122`	`}`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ extension CatalogCommand {`
`52`	`52`	`} else {`
`53`	`53`	`fputs("Creating empty version 2 catalog for migration\n", stderr)`
`54`	`54`
`55`		`- catalog = SoftwareCatalog(apiVersion: 2, minAppVersion: .init(string: "2.0.0")!, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [])`
	`55`	`+ catalog = SoftwareCatalog(apiVersion: 2, minAppVersion: .init(string: "2.0.0")!, channels: [], groups: [], restoreImages: [], features: [], requirementSets: [], deviceSupportVersions: [])`
`56`	`56`	`}`
`57`	`57`
`58`	`58`	`for legacyChannel in legacyCatalog.channels {`
Original file line number	Diff line number	Diff line change
`@@ -68,9 +68,9 @@ extension ResolvedRequirementSet {`
`68`	`68`	`}`
`69`	`69`
`70`	`70`	`extension SoftwareCatalog {`
`71`		`- static let placeholder = SoftwareCatalog(apiVersion: 1, minAppVersion: "1.0", channels: [.placeholder], groups: [.placeholder], restoreImages: [.placeholder], features: [], requirementSets: [.placeholder])`
	`71`	`+ static let placeholder = SoftwareCatalog(apiVersion: 1, minAppVersion: "1.0", channels: [.placeholder], groups: [.placeholder], restoreImages: [.placeholder], features: [], requirementSets: [.placeholder], deviceSupportVersions: [])`
`72`	`72`	`}`
`73`	`73`
`74`	`74`	`extension ResolvedRestoreImage {`
`75`		`- static let placeholder = ResolvedRestoreImage(image: .placeholder, channel: .placeholder, features: [], requirements: .placeholder, status: .supported, localFileURL: nil)`
	`75`	`+ static let placeholder = ResolvedRestoreImage(image: .placeholder, channel: .placeholder, features: [], requirements: .placeholder, status: .supported, localFileURL: nil, deviceSupportVersion: nil)`
`76`	`76`	`}`