Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Swift apple-siliconcustom-formathomebrewiosipaipadipadosiphonemetalnative-portnintendo-switchnxnativeromfsswitch-games
The launcher can preview guided first-run setup
v0lumehi60a699e2eb82
diff --git a/frontend/Onboarding.md b/frontend/Onboarding.mdnew file mode 100644index 00000000..b8541960--- /dev/null+++ b/frontend/Onboarding.md@@ -0,0 +1,67 @@+# First-run UI preview++The guided setup is opt-in. Without a recognized `NSPB_ONBOARDING_DEMO` value, the app opens the existing launcher exactly as before. The preview never instantiates `BuildModel`, detects tools, reads selected files, installs anything or opens the App Store. Its exit screen stands in for opening the library.++From the repository root, enter `frontend`, then run one scenario:++```sh+cd frontend+NSPB_ONBOARDING_DEMO=fresh swift run+NSPB_ONBOARDING_DEMO=xcodeReady swift run+NSPB_ONBOARDING_DEMO=keysInvalid swift run+NSPB_ONBOARDING_DEMO=xcodeFailed swift run+NSPB_ONBOARDING_DEMO=noGames swift run+```++- `fresh`: Start, select a platform, Continue, Get Xcode, wait, Finish setup, confirm the found keys, review the games, Continue, Open library.+- `xcodeReady`: the same path, with Xcode already present; its checks tick through automatically.+- `keysInvalid`: confirming the found file fails validation. Choose or drop another file to exercise recovery. The mock does not read it.+- `xcodeFailed`: setup fails with a plain explanation and expandable diagnostics. Retry, then Finish setup to recover.+- `noGames`: the mock folder scan finds no NSPs and shows a hint. Use Back or Set up later.++Set up later preserves an in-memory snapshot; Resume setup restores it. Persistence across app launches is deliberately left to the real driver.++## Wiring contract++`OnboardingView<Driver: OnboardingDriver>` observes a driver on the main actor. A real `ObservableObject` should publish `OnboardingState` as one value and implement these intents:++```swift+start()+choosePlatform(_ platform: OnboardingPlatform)+getXcode()+finishXcodeSetup()+retry(_ step: OnboardingStep)+chooseKeys(_ url: URL)+confirmKeys()+chooseGames(_ url: URL)+back()+next()+skipForLater()+openLibrary()+```++The driver owns detection, installation, privileges, security-scoped access to selected URLs, validation, decoded cover images, persistence, and navigation. The view owns only presentation, the system chooser, drop URL decoding, disclosure expansion and input handling. No key file contents belong in `OnboardingState`, failure text or diagnostics. Failure messages must already be localized; `details` is diagnostic text supplied by the driver.++Use `OnboardingState.next()` and `.back()` for gated navigation. `canAdvance` requires disk space on Welcome, a platform selection, Xcode plus all background tasks, valid keys, or a nonempty games list respectively. `primary` distinguishes a step action (Get Xcode, Finish setup, confirm keys, Retry) from advancing. `primaryEnabled` also gates completion and dismissed flows. `setupTasks` derives the iOS row from the selected platform.++Automatic advancement belongs in the driver. The mock gives completed Xcode and keys a brief checkmark hold, then advances. Returning to an already completed step stays there so Back remains useful. Games wait for explicit Continue so the player can review what was found. On a return visit, selecting iPhone after completed Mac setup adds the iOS preparation step.++Persist the current step and selections before handling `skipForLater`; inject the restored state on the next launch and revalidate external prerequisites in the real driver. `MockOnboardingDriver(state:)` demonstrates restoration without preferences or file I/O. Its `animated: false` initializer disables scheduled changes for deterministic tests.++## Presentation choices++The flow retains the launcher's dark appearance, palette, Manrope, cream capsule primary button, secondary button style and 1.8:1 cover crop. The app currently forces dark mode, so onboarding does too. The existing app icon is packaged as a SwiftPM resource. Background preparation stays beside Xcode, while a fixed footer keeps the primary action visible at the launcher's 900 × 680 minimum window size. Long content scrolls.++Return activates the primary action, Escape and controller B go back. Every interactive element has an onboarding controller target. Step headings receive VoiceOver focus, and changing status is announced. Reduced Motion replaces slides with fades, shows completed checks immediately, stops indeterminate loops and disables progress interpolation.++## Validation++```sh+swift build -c release+swift test+NX_ONBOARDING_CAPTURE_DIR="$PWD/.build/onboarding-captures" swift test --filter OnboardingTests+```++The last command optionally captures all six screens at minimum window size in English and Simplified Chinese. It only hosts mock SwiftUI views. The normal suite skips that capture unless requested.++Files added: `OnboardingState.swift`, `MockOnboardingDriver.swift`, `OnboardingView.swift`, `Resources/OnboardingIcon.png`, `OnboardingTests.swift`, and this note. Files changed: `NSPortBuilderApp.swift` (demo branch), `Localization.swift` (both languages), and `Package.swift` (icon resource).diff --git a/frontend/Package.swift b/frontend/Package.swiftindex 2eed0a5b..d5c9fd97 100644--- a/frontend/Package.swift+++ b/frontend/Package.swift@@ -5,7 +5,7 @@ let package = Package(name: "NSPortBuilder",platforms: [.macOS(.v13)],targets: [- .executableTarget(name: "NSPortBuilder", path: "Sources/NSPortBuilder"),+ .executableTarget(name: "NSPortBuilder", path: "Sources/NSPortBuilder", resources: [.process("Resources")]),.testTarget(name: "NSPortBuilderTests", dependencies: ["NSPortBuilder"])])diff --git a/frontend/Sources/NSPortBuilder/Localization.swift b/frontend/Sources/NSPortBuilder/Localization.swiftindex ff95392a..c84f6a02 100644--- a/frontend/Sources/NSPortBuilder/Localization.swift+++ b/frontend/Sources/NSPortBuilder/Localization.swift@@ -41,6 +41,97 @@ enum Lang: String {enum L10n {/// key: (Chinese, English)static let table: [String: (zh: String, en: String)] = [+ "onboarding.brand": ("NX2Apple", "NX2Apple"),+ "onboarding.welcome.title": ("\u{51c6}\u{5907}\u{5f00}\u{59cb}\u{6e38}\u{620f}\u{3002}", "Make yourself at home."),+ "onboarding.welcome.note": ("\u{7ea6} 15 \u{5206}\u{949f}\u{ff0c}\u{5373}\u{53ef}\u{5728} Mac \u{4e0a}\u{539f}\u{751f}\u{8fd0}\u{884c}\u{4f60}\u{7684} Switch \u{6e38}\u{620f}\u{3002}", "Play your Switch games natively on your Mac, in about 15 minutes."),+ "onboarding.platform.title": ("\u{4f60}\u{60f3}\u{5728}\u{54ea}\u{91cc}\u{73a9}\u{ff1f}", "Where do you want to play?"),+ "onboarding.platform.note": ("\u{9009}\u{62e9}\u{6e38}\u{73a9}\u{8bbe}\u{5907}\u{ff0c}\u{6211}\u{4eec}\u{4f1a}\u{51c6}\u{5907}\u{6240}\u{9700}\u{7684}\u{5de5}\u{5177}\u{3002}", "Choose where you will play. We will prepare just what you need."),+ "onboarding.xcode.title": ("\u{51c6}\u{5907}\u{597d}\u{4f60}\u{7684} Mac\u{3002}", "Let\u{2019}s get your Mac ready."),+ "onboarding.xcode.note": ("Xcode \u{63d0}\u{4f9b}\u{6784}\u{5efa}\u{6e38}\u{620f}\u{6240}\u{9700}\u{7684} Apple \u{5de5}\u{5177}\u{3002}\u{6211}\u{4eec}\u{5c06}\u{5f15}\u{5bfc}\u{4f60}\u{5b8c}\u{6210}\u{8bbe}\u{7f6e}\u{3002}", "Xcode provides Apple\u{2019}s tools for building your games. We will guide you through the setup."),+ "onboarding.keys.title": ("\u{6dfb}\u{52a0}\u{4f60}\u{7684}\u{5bc6}\u{94a5}\u{3002}", "Bring your own keys."),+ "onboarding.keys.note": ("\u{8bf7}\u{9009}\u{62e9}\u{4ece}\u{4f60}\u{81ea}\u{5df1}\u{7684} Switch \u{5bfc}\u{51fa}\u{7684} prod.keys\u{3002}\u{6211}\u{4eec}\u{4f1a}\u{9a8c}\u{8bc1}\u{6587}\u{4ef6}\u{662f}\u{5426}\u{53ef}\u{7528}\u{3002}", "Choose prod.keys from your own Switch. We will check that the file is ready to use."),+ "onboarding.games.title": ("\u{628a}\u{4f60}\u{7684}\u{6e38}\u{620f}\u{653e}\u{5728}\u{8fd9}\u{91cc}\u{3002}", "Your games, right here."),+ "onboarding.games.note": ("\u{9009}\u{62e9}\u{5b58}\u{653e}\u{4f60}\u{81ea}\u{5df1}\u{5bfc}\u{51fa}\u{7684} NSP \u{6e38}\u{620f}\u{6587}\u{4ef6}\u{7684}\u{6587}\u{4ef6}\u{5939}\u{3002}\u{4e4b}\u{540e}\u{53ef}\u{4ee5}\u{7ee7}\u{7eed}\u{6dfb}\u{52a0}\u{6e38}\u{620f}\u{3002}", "Choose the folder containing your own NSP game dumps. You can add more games later."),+ "onboarding.done.title": ("\u{51c6}\u{5907}\u{5c31}\u{7eea}\u{3002}", "You\u{2019}re ready to play."),+ "onboarding.done.note": ("\u{8bbe}\u{7f6e}\u{5df2}\u{5b8c}\u{6210}\u{ff0c}\u{63a5}\u{4e0b}\u{6765}\u{6253}\u{5f00}\u{6e38}\u{620f}\u{5e93}\u{3002}", "Setup is complete. Your library is the next stop."),+ "onboarding.start": ("\u{5f00}\u{59cb}", "Start"),+ "onboarding.continue": ("\u{7ee7}\u{7eed}", "Continue"),+ "onboarding.getXcode": ("\u{83b7}\u{53d6} Xcode", "Get Xcode"),+ "onboarding.finishSetup": ("\u{5b8c}\u{6210}\u{8bbe}\u{7f6e}", "Finish setup"),+ "onboarding.retry": ("\u{91cd}\u{8bd5}", "Retry"),+ "onboarding.confirmKeys": ("\u{4f7f}\u{7528}\u{6b64}\u{5bc6}\u{94a5}\u{6587}\u{4ef6}", "Use these keys"),+ "onboarding.openLibrary": ("\u{6253}\u{5f00}\u{6e38}\u{620f}\u{5e93}", "Open library"),+ "onboarding.waiting": ("\u{8bf7}\u{7a0d}\u{5019}\u{2026}", "Please wait\u{2026}"),+ "onboarding.back": ("\u{8fd4}\u{56de}", "Back"),+ "onboarding.later": ("\u{7a0d}\u{540e}\u{8bbe}\u{7f6e}", "Set up later"),+ "onboarding.choose": ("\u{9009}\u{62e9}\u{2026}", "Choose\u{2026}"),+ "onboarding.chooseFailed": ("\u{65e0}\u{6cd5}\u{6253}\u{5f00}\u{6240}\u{9009}\u{9879}\u{76ee}\u{ff0c}\u{8bf7}\u{91cd}\u{65b0}\u{9009}\u{62e9}\u{3002}", "The selection could not be opened. Please choose again."),+ "onboarding.stepCount": ("\u{7b2c} %d \u{6b65}\u{ff0c}\u{5171} %d \u{6b65}", "Step %d of %d"),+ "onboarding.footer": ("\u{9009}\u{62e9}\u{7a0d}\u{540e}\u{8bbe}\u{7f6e}\u{65f6}\u{4f1a}\u{4fdd}\u{7559}\u{5f53}\u{524d}\u{8fdb}\u{5ea6}\u{3002}", "Your progress is kept when you set up later."),+ "onboarding.ready": ("\u{5df2}\u{5c31}\u{7eea}", "Ready"),+ "onboarding.queued": ("\u{7b49}\u{5f85}\u{4e2d}", "Waiting"),+ "onboarding.running": ("\u{8fdb}\u{884c}\u{4e2d}", "In progress"),+ "onboarding.failed": ("\u{9700}\u{8981}\u{5904}\u{7406}", "Needs attention"),+ "onboarding.showDetails": ("\u{663e}\u{793a}\u{8be6}\u{60c5}", "Show details"),+ "onboarding.hideDetails": ("\u{9690}\u{85cf}\u{8be6}\u{60c5}", "Hide details"),+ "onboarding.expanded": ("\u{5df2}\u{5c55}\u{5f00}", "Expanded"),+ "onboarding.collapsed": ("\u{5df2}\u{6536}\u{8d77}", "Collapsed"),+ "onboarding.require.mac": ("\u{642d}\u{8f7d} Apple \u{82af}\u{7247}\u{7684} Mac", "A Mac with Apple silicon"),+ "onboarding.require.macNote": ("\u{4f7f}\u{7528}\u{8fd9}\u{53f0} Mac \u{51c6}\u{5907}\u{4f60}\u{7684}\u{6e38}\u{620f}\u{3002}", "The same Mac you will use to prepare your games."),+ "onboarding.require.files": ("\u{4f60}\u{7684}\u{6e38}\u{620f}\u{6587}\u{4ef6}\u{548c} prod.keys", "Your game dumps and prod.keys"),+ "onboarding.require.filesNote": ("\u{4ece}\u{4f60}\u{81ea}\u{5df1}\u{7684} Nintendo Switch \u{5bfc}\u{51fa}\u{3002}", "Exported from your own Nintendo Switch."),+ "onboarding.require.disk": ("\u{8db3}\u{591f}\u{7684}\u{53ef}\u{7528}\u{7a7a}\u{95f4}", "Room to get ready"),+ "onboarding.require.diskNote": ("\u{53ef}\u{7528} %d GB \u{b7} \u{8bbe}\u{7f6e}\u{9700}\u{8981} %d GB", "%d GB free \u{b7} %d GB needed for setup"),+ "onboarding.require.diskWarning": ("\u{8bf7}\u{5148}\u{91ca}\u{653e}\u{4e00}\u{4e9b}\u{7a7a}\u{95f4}\u{ff0c}\u{518d}\u{5f00}\u{59cb}\u{8bbe}\u{7f6e}\u{3002}", "Free up some space before starting setup."),+ "onboarding.platform.mac": ("Mac", "Mac"),+ "onboarding.platform.iphone": ("iPhone", "iPhone"),+ "onboarding.platform.both": ("\u{4e24}\u{8005}\u{90fd}\u{8981}", "Both"),+ "onboarding.platform.macNote": ("\u{5728}\u{8fd9}\u{53f0} Mac \u{4e0a}\u{6e38}\u{73a9}\u{3002}", "Play on this Mac."),+ "onboarding.platform.iosSize": ("\u{5305}\u{542b} iOS \u{5e73}\u{53f0} \u{b7} \u{989d}\u{5916}\u{7ea6} 8 GB", "Includes the iOS platform \u{b7} about 8 GB extra"),+ "onboarding.xcode.checking": ("\u{6b63}\u{5728}\u{68c0}\u{67e5} Xcode\u{2026}", "Checking Xcode\u{2026}"),+ "onboarding.xcode.checkingNote": ("\u{6b63}\u{5728}\u{67e5}\u{627e}\u{6e38}\u{620f}\u{6240}\u{9700}\u{7684}\u{5de5}\u{5177}\u{3002}", "Looking for the tools your games need."),+ "onboarding.xcode.missing": ("\u{5148}\u{83b7}\u{53d6} Xcode\u{3002}", "First, get Xcode."),+ "onboarding.xcode.missingNote": ("\u{4ece} App Store \u{4e0b}\u{8f7d} Xcode\u{3002}\u{8fd9}\u{662f}\u{8bbe}\u{7f6e}\u{4e2d}\u{6700}\u{5927}\u{7684}\u{4e0b}\u{8f7d}\u{9879}\u{76ee}\u{3002}", "Download Xcode from the App Store. This is the largest part of setup."),+ "onboarding.xcode.downloading": ("\u{6b63}\u{5728}\u{7b49}\u{5f85} Xcode\u{2026}", "Waiting for Xcode\u{2026}"),+ "onboarding.xcode.downloadNote": ("\u{8bf7}\u{8ba9} App Store \u{7ee7}\u{7eed}\u{4e0b}\u{8f7d}\u{3002}Xcode \u{5b89}\u{88c5}\u{5b8c}\u{6210}\u{540e}\u{ff0c}\u{6211}\u{4eec}\u{4f1a}\u{81ea}\u{52a8}\u{7ee7}\u{7eed}\u{3002}", "Leave the App Store download running. We will continue automatically when Xcode is installed."),+ "onboarding.xcode.needsSetup": ("\u{5b8c}\u{6210} Xcode \u{7684}\u{6700}\u{540e}\u{4e00}\u{6b65}\u{3002}", "One last step for Xcode."),+ "onboarding.xcode.passwordNote": ("Mac \u{5c06}\u{8bf7}\u{6c42}\u{4e00}\u{6b21}\u{5bc6}\u{7801}\u{ff0c}\u{7528}\u{4e8e}\u{9009}\u{62e9} Xcode\u{3001}\u{63a5}\u{53d7}\u{8bb8}\u{53ef}\u{5e76}\u{5b8c}\u{6210}\u{5de5}\u{5177}\u{51c6}\u{5907}\u{3002}", "Your Mac will ask for your password once to select Xcode, accept its license and finish preparing the tools."),+ "onboarding.xcode.settingUp": ("\u{6b63}\u{5728}\u{5b8c}\u{6210} Xcode \u{8bbe}\u{7f6e}\u{2026}", "Finishing Xcode setup\u{2026}"),+ "onboarding.xcode.ready": ("Xcode \u{5df2}\u{5c31}\u{7eea}\u{3002}", "Xcode is ready."),+ "onboarding.setup.selected": ("\u{9009}\u{62e9} Xcode", "Xcode selected"),+ "onboarding.setup.license": ("\u{63a5}\u{53d7}\u{8bb8}\u{53ef}", "License accepted"),+ "onboarding.setup.firstLaunch": ("\u{9996}\u{6b21}\u{542f}\u{52a8}", "First launch"),+ "onboarding.setup.metal": ("Metal \u{5de5}\u{5177}\u{94fe}", "Metal Toolchain"),+ "onboarding.setup.ios": ("iOS \u{5e73}\u{53f0}", "iOS platform"),+ "onboarding.background.title": ("\u{6b63}\u{5728}\u{540e}\u{53f0}\u{51c6}\u{5907}", "Preparing in the background"),+ "onboarding.background.note": ("\u{8fd9}\u{4e9b}\u{5de5}\u{5177}\u{5c06}\u{5728}\u{8bbe}\u{7f6e} Xcode \u{65f6}\u{51c6}\u{5907}\u{5c31}\u{7eea}\u{3002}", "These tools get ready while you set up Xcode."),+ "onboarding.background.python": ("Python", "Python"),+ "onboarding.background.dotnet": (".NET", ".NET"),+ "onboarding.background.tools": ("\u{6784}\u{5efa}\u{5de5}\u{5177}", "Build tools"),+ "onboarding.keys.searching": ("\u{6b63}\u{5728}\u{67e5}\u{627e} prod.keys\u{2026}", "Looking for prod.keys\u{2026}"),+ "onboarding.keys.found": ("\u{627e}\u{5230}\u{4e86}\u{5bc6}\u{94a5}\u{6587}\u{4ef6}\u{3002}", "We found a keys file."),+ "onboarding.keys.validating": ("\u{6b63}\u{5728}\u{9a8c}\u{8bc1}\u{5bc6}\u{94a5}\u{6587}\u{4ef6}\u{2026}", "Checking your keys file\u{2026}"),+ "onboarding.keys.valid": ("\u{5bc6}\u{94a5}\u{6587}\u{4ef6}\u{5df2}\u{9a8c}\u{8bc1}\u{3002}", "Keys file verified."),+ "onboarding.keys.invalid": ("\u{9700}\u{8981}\u{91cd}\u{65b0}\u{68c0}\u{67e5}\u{6b64}\u{5bc6}\u{94a5}\u{6587}\u{4ef6}\u{3002}", "This keys file needs another look."),+ "onboarding.keys.empty": ("\u{8bf7}\u{9009}\u{62e9} prod.keys \u{6587}\u{4ef6}\u{3002}", "Choose your prod.keys file."),+ "onboarding.keys.privacy": ("\u{4ec5}\u{663e}\u{793a}\u{6587}\u{4ef6}\u{8def}\u{5f84}\u{548c}\u{9a8c}\u{8bc1}\u{7ed3}\u{679c}\u{ff0c}\u{7edd}\u{4e0d}\u{663e}\u{793a}\u{5bc6}\u{94a5}\u{5185}\u{5bb9}\u{3002}", "Only the file path and verification result are shown. Key contents are never displayed."),+ "onboarding.keys.drop": ("\u{5c06} prod.keys \u{62d6}\u{5230}\u{8fd9}\u{91cc}", "Drop prod.keys here"),+ "onboarding.games.drop": ("\u{5c06} NSP \u{6587}\u{4ef6}\u{5939}\u{62d6}\u{5230}\u{8fd9}\u{91cc}", "Drop your NSP folder here"),+ "onboarding.games.scanning": ("\u{6b63}\u{5728}\u{67e5}\u{627e}\u{4f60}\u{7684}\u{6e38}\u{620f}\u{2026}", "Looking for your games\u{2026}"),+ "onboarding.games.count": ("\u{627e}\u{5230} %d \u{4e2a}\u{6e38}\u{620f}", "%d games found"),+ "onboarding.games.version": ("\u{7248}\u{672c} %@", "Version %@"),+ "onboarding.games.none": ("\u{6b64}\u{6587}\u{4ef6}\u{5939}\u{4e2d}\u{6ca1}\u{6709}\u{6e38}\u{620f}\u{3002}", "No games in this folder yet."),+ "onboarding.games.noneHint": ("\u{8bf7}\u{9009}\u{62e9}\u{5b58}\u{653e} NSP \u{6e38}\u{620f}\u{6587}\u{4ef6}\u{7684}\u{6587}\u{4ef6}\u{5939}\u{ff0c}\u{800c}\u{975e}\u{5df2}\u{89e3}\u{5305}\u{7684}\u{6e38}\u{620f}\u{6216}\u{6784}\u{5efa}\u{6587}\u{4ef6}\u{5939}\u{3002}", "Choose a folder containing your NSP dumps, rather than an extracted game or a build folder."),+ "onboarding.done.platform": ("\u{6e38}\u{73a9}\u{8bbe}\u{5907}", "Play on"),+ "onboarding.done.tools": ("\u{6784}\u{5efa}\u{5de5}\u{5177}", "Build tools"),+ "onboarding.done.keys": ("\u{4f60}\u{7684}\u{5bc6}\u{94a5}", "Your keys"),+ "onboarding.demo.mario": ("\u{8d85}\u{7ea7}\u{9a6c}\u{529b}\u{6b27} \u{5965}\u{5fb7}\u{8d5b}", "Super Mario Odyssey"),+ "onboarding.demo.xcodeFailure": ("Metal \u{5de5}\u{5177}\u{672a}\u{80fd}\u{4e0b}\u{8f7d}\u{5b8c}\u{6210}\u{3002}\u{7f51}\u{7edc}\u{8fde}\u{63a5}\u{6062}\u{590d}\u{540e}\u{8bf7}\u{91cd}\u{8bd5}\u{3002}", "The Metal tools could not finish downloading. Try again when your connection is ready."),+ "onboarding.demo.keysFailure": ("\u{6b64}\u{6f14}\u{793a}\u{6587}\u{4ef6}\u{7f3a}\u{5c11}\u{6240}\u{9700}\u{7684}\u{5bc6}\u{94a5}\u{3002}\u{8bf7}\u{9009}\u{62e9}\u{5176}\u{4ed6} prod.keys \u{6587}\u{4ef6}\u{91cd}\u{8bd5}\u{3002}", "This demo file is missing required keys. Choose another prod.keys file to try again."),+ "onboarding.demo.paused": ("\u{8bbe}\u{7f6e}\u{5df2}\u{6682}\u{505c}\u{3002}", "Setup paused."),+ "onboarding.demo.library": ("\u{6e38}\u{620f}\u{5e93}\u{5c06}\u{5728}\u{6b64}\u{6253}\u{5f00}\u{3002}", "Your library would open here."),+ "onboarding.demo.note": ("\u{8fd9}\u{662f}\u{9884}\u{89c8}\u{3002}\u{672a}\u{8bfb}\u{53d6}\u{4efb}\u{4f55}\u{6587}\u{4ef6}\u{ff0c}\u{4e5f}\u{672a}\u{5b89}\u{88c5}\u{4efb}\u{4f55}\u{5de5}\u{5177}\u{3002}", "This is a preview. No files were read and no tools were installed."),+ "onboarding.demo.resume": ("\u{7ee7}\u{7eed}\u{8bbe}\u{7f6e}", "Resume setup"),"library.readyIOS": ("\u{53ef}\u{7528}\u{4e8e} iPhone", "Ready for iPhone"),"library.stopping": ("\u{6b63}\u{5728}\u{505c}\u{6b62}…", "Stopping…"),"build.setup": ("\u{5b8c}\u{6210}\u{8bbe}\u{7f6e}", "Finish setup"),diff --git a/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift b/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swiftnew file mode 100644index 00000000..8a257d62--- /dev/null+++ b/frontend/Sources/NSPortBuilder/MockOnboardingDriver.swift@@ -0,0 +1,202 @@+import Foundation++/// A scripted demo only. No detection, file reads, installs, preferences or subprocesses.+@MainActor final class MockOnboardingDriver: OnboardingDriver {+ enum Scenario: String, CaseIterable { case fresh, xcodeReady, keysInvalid, xcodeFailed, noGames }+ @Published private(set) var state: OnboardingState+ private(set) var resumeSnapshot: OnboardingState?+ let scenario: Scenario+ private let lang: Lang+ private let animated: Bool+ private var jobs: [String: Task<Void, Never>] = [:]+ private var retriedXcode = false+ private var retriedKeys = false++ /// A stored snapshot is injected; persistence belongs to the real driver. `animated: false` is for state tests.+ init(scenario: Scenario = .fresh, state: OnboardingState = .init(), lang: Lang = .initial(), animated: Bool = true) {+ self.scenario = scenario; self.state = state; self.lang = lang; self.animated = animated+ if animated { enterStep() }+ }+ deinit { jobs.values.forEach { $0.cancel() } }++ func start() { guard state.step == .welcome else { return }; next() }+ func choosePlatform(_ platform: OnboardingPlatform) {+ guard state.step == .platform, state.exit == nil else { return }+ let wasIOS = state.selectedPlatform?.includesIOS == true+ state.platform = .selected(platform)+ // Selecting iPhone on a return visit adds work even when Mac setup had already finished.+ if platform.includesIOS && !wasIOS && state.xcode == .ready {+ state.xcode = .needsSetup+ state.setup[.ios] = .queued+ }+ }+ func getXcode() {+ guard state.step == .xcode, state.xcode == .missing, state.exit == nil else { return }+ state.xcode = .downloading+ downloadXcode()+ }+ func finishXcodeSetup() {+ guard state.step == .xcode, state.xcode == .needsSetup, state.exit == nil else { return }+ state.xcode = .settingUp+ setupXcode()+ }+ func retry(_ step: OnboardingStep) {+ guard state.step == step, state.exit == nil else { return }+ switch step {+ case .xcode:+ if case .failed = state.xcode {+ retriedXcode = true+ state.xcode = .needsSetup+ }+ for task in OnboardingBackgroundTask.allCases {+ if case .failed = state.background[task] { state.background[task] = .queued }+ }+ enterStep()+ case .keys: state.keys = .empty+ case .games: state.games = .empty+ default: break+ }+ }+ func chooseKeys(_ url: URL) {+ guard state.step == .keys, state.exit == nil else { return }+ if case .invalid = state.keys { retriedKeys = true }+ validateKeys()+ }+ func confirmKeys() {+ guard state.step == .keys, state.exit == nil, case .found = state.keys else { return }+ validateKeys()+ }+ func chooseGames(_ url: URL) {+ guard state.step == .games, state.exit == nil else { return }+ state.games = .scanning+ run("games", after: 1.1) { driver in+ if driver.scenario == .noGames { driver.state.games = .none }+ else {+ driver.state.games = .found([+ .init(id: "demo.mario", title: driver.t("onboarding.demo.mario"), version: "1.0.0"),+ .init(id: "demo.balatro", title: "Balatro", version: "1.0.0")+ ])+ }+ }+ }+ func back() {+ let old = state.step+ state.back()+ if old != state.step { cancelJobs(); enterStep(allowAutomaticAdvance: false) }+ }+ func next() {+ let old = state.step+ state.next()+ if old != state.step { cancelJobs(); enterStep() }+ }+ func skipForLater() {+ guard state.exit == nil else { return }+ resumeSnapshot = state+ state.exit = .later+ cancelJobs()+ }+ func openLibrary() {+ guard state.step == .done, state.primaryEnabled else { return }+ state.exit = .library+ cancelJobs()+ }+ func resume() {+ guard state.exit == .later, let snapshot = resumeSnapshot else { return }+ state = snapshot+ enterStep()+ }++ private func t(_ key: String) -> String { L10n.string(key, lang) }+ private func cancelJobs() { jobs.values.forEach { $0.cancel() }; jobs.removeAll() }+ private func run(_ name: String, after seconds: Double, _ action: @escaping (MockOnboardingDriver) -> Void) {+ guard animated else { return }+ jobs[name]?.cancel()+ jobs[name] = Task { @MainActor [weak self] in+ do { try await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000)) } catch { return }+ guard !Task.isCancelled, let self, self.state.exit == nil else { return }+ action(self)+ }+ }+ private func enterStep(allowAutomaticAdvance: Bool = true) {+ guard state.exit == nil else { return }+ switch state.step {+ case .xcode:+ prepareBackground()+ switch state.xcode {+ case .checking:+ run("check", after: 0.7) { d in+ d.state.xcode = d.scenario == .xcodeReady ? .settingUp : .missing+ if d.scenario == .xcodeReady { d.setupXcode() }+ }+ case .downloading: downloadXcode()+ case .settingUp: setupXcode()+ case .ready: if allowAutomaticAdvance { advanceWhenReady() }+ default: break+ }+ case .keys:+ switch state.keys {+ case .empty, .searching:+ state.keys = .searching+ run("keys", after: 0.9) { d in d.state.keys = .found(URL(fileURLWithPath: "/Demo/Switch/prod.keys")) }+ case .validating: validateKeys()+ case .valid: if allowAutomaticAdvance { advanceWhenReady() }+ default: break+ }+ case .games:+ // Only this mock synthesizes a selection; the real view still offers Choose and drop.+ if state.games == .empty || state.games == .scanning {+ chooseGames(URL(fileURLWithPath: "/Demo/Switch"))+ }+ case .done:+ if state.done == .celebrating { run("done", after: 0.35) { $0.state.done = .ready } }+ default: break+ }+ }+ private func prepareBackground() {+ for (index, task) in OnboardingBackgroundTask.allCases.enumerated() where state.background[task] != .done {+ if case .failed = state.background[task] { continue }+ state.background[task] = .queued+ run("bg.start.\(task)", after: 0.3 + Double(index) * 0.4) { d in d.state.background[task] = .running(nil) }+ run("bg.progress.\(task)", after: 1.0 + Double(index) * 0.6) { d in d.state.background[task] = .running(0.6) }+ run("bg.done.\(task)", after: 1.8 + Double(index) * 0.7) { d in+ d.state.background[task] = .done+ d.advanceWhenReady()+ }+ }+ }+ private func downloadXcode() {+ run("download", after: 3.2) { d in d.state.xcode = .needsSetup }+ }+ private func setupXcode() {+ let tasks = state.setupTasks+ for (index, task) in tasks.enumerated() {+ state.setup[task] = .queued+ run("setup.start.\(task)", after: 0.2 + Double(index) * 0.65) { d in+ d.state.setup[task] = .running(task == .metal || task == .ios ? 0.35 : nil)+ }+ run("setup.done.\(task)", after: 0.7 + Double(index) * 0.65) { d in d.state.setup[task] = .done }+ }+ run("setup.finish", after: 0.9 + Double(tasks.count) * 0.65) { d in+ if d.scenario == .xcodeFailed && !d.retriedXcode {+ d.state.xcode = .failed(.init(message: d.t("onboarding.demo.xcodeFailure"),+ details: "Demo: MetalToolchain download returned HTTP 503."))+ } else {+ d.state.xcode = .ready+ d.advanceWhenReady()+ }+ }+ }+ private func validateKeys() {+ state.keys = .validating+ run("keys", after: 1) { d in+ if d.scenario == .keysInvalid && !d.retriedKeys {+ d.state.keys = .invalid(d.t("onboarding.demo.keysFailure"))+ } else { d.state.keys = .valid; d.advanceWhenReady() }+ }+ }+ private func advanceWhenReady() {+ guard (state.step == .xcode || state.step == .keys), state.canAdvance else { return }+ let step = state.step+ run("advance", after: 0.7) { d in if d.state.step == step { d.next() } }+ }+}diff --git a/frontend/Sources/NSPortBuilder/NSPortBuilderApp.swift b/frontend/Sources/NSPortBuilder/NSPortBuilderApp.swiftindex ae6e5470..45aac283 100644--- a/frontend/Sources/NSPortBuilder/NSPortBuilderApp.swift+++ b/frontend/Sources/NSPortBuilder/NSPortBuilderApp.swift@@ -5,7 +5,12 @@ struct NSPortBuilderApp: App {@NSApplicationDelegateAdaptor private var delegate: AppDelegatevar body: some Scene {- WindowGroup("NX2Apple") { ContentView() }+ WindowGroup("NX2Apple") {+ if let name = ProcessInfo.processInfo.environment["NSPB_ONBOARDING_DEMO"],+ let scenario = MockOnboardingDriver.Scenario(rawValue: name) {+ OnboardingDemoHost(scenario: scenario)+ } else { ContentView() }+ }.windowStyle(.hiddenTitleBar).defaultSize(width: 1280, height: 900).windowResizability(.automatic)diff --git a/frontend/Sources/NSPortBuilder/OnboardingState.swift b/frontend/Sources/NSPortBuilder/OnboardingState.swiftnew file mode 100644index 00000000..d464d840--- /dev/null+++ b/frontend/Sources/NSPortBuilder/OnboardingState.swift@@ -0,0 +1,189 @@+import AppKit+import Combine++enum OnboardingStep: String, CaseIterable, Codable {+ case welcome, platform, xcode, keys, games, done+ var index: Int { Self.allCases.firstIndex(of: self)! }+ var titleKey: String { "onboarding.\(rawValue).title" }+}++enum OnboardingPlatform: String, CaseIterable {+ case mac, iphone, both+ var includesIOS: Bool { self != .mac }+ var symbol: String { self == .mac ? "desktopcomputer" : (self == .iphone ? "iphone" : "laptopcomputer.and.iphone") }+}++/// The message is already localized by the driver. Details are a diagnostic log, never keys or file contents.+struct OnboardingFailure: Equatable {+ var message: String+ var details: String = ""+}++enum OnboardingTaskState: Equatable {+ case queued, running(Double?), done, failed(OnboardingFailure)+ var isDone: Bool { self == .done }+ var statusKey: String {+ switch self {+ case .queued: return "onboarding.queued"+ case .running: return "onboarding.running"+ case .done: return "onboarding.ready"+ case .failed: return "onboarding.failed"+ }+ }+}++enum OnboardingSetupTask: String, CaseIterable {+ case selected, license, firstLaunch, metal, ios+ var titleKey: String { "onboarding.setup.\(rawValue)" }+}++enum OnboardingBackgroundTask: String, CaseIterable {+ case python, dotnet, tools+ var titleKey: String { "onboarding.background.\(rawValue)" }+}++struct OnboardingGame: Identifiable, Equatable {+ var id: String+ var title: String+ var version: String+ /// Decoded artwork is supplied by the driver. The view never reads or fetches a file.+ var cover: NSImage? = nil+}++struct OnboardingState: Equatable {+ enum Welcome: Equatable {+ case requirements(freeGB: Int, neededGB: Int)+ var hasSpace: Bool {+ switch self { case let .requirements(free, needed): return free >= needed }+ }+ }+ enum Platform: Equatable { case empty, selected(OnboardingPlatform) }+ enum Xcode: Equatable {+ case checking, missing, downloading, needsSetup, settingUp, ready, failed(OnboardingFailure)+ var statusKey: String {+ switch self {+ case .checking: return "onboarding.xcode.checking"+ case .missing: return "onboarding.xcode.missing"+ case .downloading: return "onboarding.xcode.downloading"+ case .needsSetup: return "onboarding.xcode.needsSetup"+ case .settingUp: return "onboarding.xcode.settingUp"+ case .ready: return "onboarding.xcode.ready"+ case .failed: return "onboarding.failed"+ }+ }+ }+ enum Keys: Equatable {+ case searching, found(URL), validating, valid, invalid(String), empty+ var statusKey: String {+ switch self {+ case .searching: return "onboarding.keys.searching"+ case .found: return "onboarding.keys.found"+ case .validating: return "onboarding.keys.validating"+ case .valid: return "onboarding.keys.valid"+ case .invalid: return "onboarding.keys.invalid"+ case .empty: return "onboarding.keys.empty"+ }+ }+ }+ enum Games: Equatable { case empty, scanning, found([OnboardingGame]), none }+ enum Done: Equatable { case celebrating, ready }+ enum Exit: Equatable { case later, library }+ enum Primary: Equatable { case start, next, getXcode, finishXcodeSetup, retry, confirmKeys, openLibrary, waiting }++ var step: OnboardingStep = .welcome+ var welcome: Welcome = .requirements(freeGB: 64, neededGB: 24)+ var platform: Platform = .empty+ var xcode: Xcode = .checking+ var setup: [OnboardingSetupTask: OnboardingTaskState] = [:]+ var background: [OnboardingBackgroundTask: OnboardingTaskState] = [:]+ var keys: Keys = .empty+ var games: Games = .empty+ var done: Done = .celebrating+ var exit: Exit? = nil++ var selectedPlatform: OnboardingPlatform? {+ if case let .selected(value) = platform { return value }+ return nil+ }+ var setupTasks: [OnboardingSetupTask] {+ OnboardingSetupTask.allCases.filter { $0 != .ios || selectedPlatform?.includesIOS == true }+ }+ var backgroundReady: Bool { OnboardingBackgroundTask.allCases.allSatisfy { background[$0] == .done } }+ var backgroundFailed: Bool {+ background.values.contains { if case .failed = $0 { return true }; return false }+ }+ var canAdvance: Bool {+ switch step {+ case .welcome: return welcome.hasSpace+ case .platform: return selectedPlatform != nil+ case .xcode: return xcode == .ready && backgroundReady+ case .keys: return keys == .valid+ case .games: if case let .found(games) = games { return !games.isEmpty }; return false+ case .done: return false+ }+ }+ var primary: Primary {+ switch step {+ case .welcome: return .start+ case .platform, .games: return .next+ case .xcode:+ switch xcode {+ case .missing: return .getXcode+ case .needsSetup: return .finishXcodeSetup+ case .failed: return .retry+ default: return backgroundFailed ? .retry : (canAdvance ? .next : .waiting)+ }+ case .keys: if case .found = keys { return .confirmKeys }; return canAdvance ? .next : .waiting+ case .done: return .openLibrary+ }+ }+ var primaryEnabled: Bool {+ guard exit == nil else { return false }+ switch primary {+ case .start, .next: return canAdvance+ case .waiting: return false+ case .openLibrary: return done == .ready+ default: return true+ }+ }+ var primaryKey: String {+ switch primary {+ case .start: return "onboarding.start"+ case .next: return "onboarding.continue"+ case .getXcode: return "onboarding.getXcode"+ case .finishXcodeSetup: return "onboarding.finishSetup"+ case .retry: return "onboarding.retry"+ case .confirmKeys: return "onboarding.confirmKeys"+ case .openLibrary: return "onboarding.openLibrary"+ case .waiting: return "onboarding.waiting"+ }+ }++ /// Pure navigation, shared by the demo and the future real driver. No step can skip its prerequisite.+ mutating func next() {+ guard exit == nil, canAdvance, step.index + 1 < OnboardingStep.allCases.count else { return }+ step = OnboardingStep.allCases[step.index + 1]+ }+ mutating func back() {+ guard exit == nil, step.index > 0 else { return }+ step = OnboardingStep.allCases[step.index - 1]+ }+}++/// Publish a fresh value when detection or installation changes. Own all work, security-scoped URL access,+/// persistence and automatic advancement in the driver; the generic view only renders and sends intents.+@MainActor protocol OnboardingDriver: ObservableObject {+ var state: OnboardingState { get }+ func start()+ func choosePlatform(_ platform: OnboardingPlatform)+ func getXcode()+ func finishXcodeSetup()+ func retry(_ step: OnboardingStep)+ func chooseKeys(_ url: URL)+ func confirmKeys()+ func chooseGames(_ url: URL)+ func back()+ func next()+ func skipForLater()+ func openLibrary()+}diff --git a/frontend/Sources/NSPortBuilder/OnboardingView.swift b/frontend/Sources/NSPortBuilder/OnboardingView.swiftnew file mode 100644index 00000000..76c5eaf1--- /dev/null+++ b/frontend/Sources/NSPortBuilder/OnboardingView.swift@@ -0,0 +1,581 @@+import SwiftUI+import UniformTypeIdentifiers++@MainActor struct OnboardingView<Driver: OnboardingDriver>: View {+ @ObservedObject var driver: Driver+ var lang: Lang = .initial()+ @Environment(\.accessibilityReduceMotion) private var reduceMotion+ @StateObject private var padFocus = PadFocus()+ @StateObject private var gamepad: LauncherGamepad+ @State private var pickerOpen = false+ @State private var pickingKeys = true+ @State private var detailsOpen = false+ @State private var pickerError: String?+ @State private var backwards = false+ @State private var entered = false+ @AccessibilityFocusState private var headingFocused: Bool++ init(driver: Driver, lang: Lang = .initial(), gamepad: LauncherGamepad? = nil) {+ _driver = ObservedObject(wrappedValue: driver)+ self.lang = lang+ _gamepad = StateObject(wrappedValue: gamepad ?? LauncherGamepad())+ }++ private var state: OnboardingState { driver.state }+ private func t(_ key: String) -> String { L10n.string(key, lang) }+ private var accessibilityStatus: String {+ switch state.step {+ case .xcode: return t(state.xcode.statusKey)+ case .keys: return t(state.keys.statusKey)+ case .games:+ switch state.games {+ case .scanning: return t("onboarding.games.scanning")+ case let .found(games): return String(format: t("onboarding.games.count"), games.count)+ case .none: return t("onboarding.games.none")+ case .empty: return t("onboarding.games.drop")+ }+ default: return ""+ }+ }+ private var transition: AnyTransition {+ reduceMotion ? .opacity : .asymmetric(+ insertion: .move(edge: backwards ? .leading : .trailing).combined(with: .opacity),+ removal: .move(edge: backwards ? .trailing : .leading).combined(with: .opacity))+ }++ var body: some View {+ VStack(spacing: 0) {+ navigation+ .transaction { if reduceMotion { $0.animation = nil; $0.disablesAnimations = true } }+ ScrollView {+ VStack(alignment: .leading, spacing: 28) {+ heading+ stepContent+ }+ .frame(maxWidth: 880, alignment: .leading)+ .padding(.horizontal, 56).padding(.vertical, 28)+ .frame(maxWidth: .infinity)+ .id(state.step)+ .transition(transition)+ }+ .clipped()+ footer+ .transaction { if reduceMotion { $0.animation = nil; $0.disablesAnimations = true } }+ }+ .animation(.easeInOut(duration: reduceMotion ? 0.16 : 0.32), value: state.step)+ .font(.manrope(14))+ .foregroundStyle(.white)+ .background(LauncherPalette.background)+ .background(LauncherWindowChrome())+ .preferredColorScheme(.dark)+ .tint(LauncherPalette.cream)+ .frame(minWidth: 900, idealWidth: 1280, minHeight: 680, idealHeight: 900)+ .padScope("onboarding", padFocus)+ .environmentObject(padFocus)+ .onAppear {+ padFocus.scope = "onboarding"+ gamepad.perform = padAction+ withAnimation(.easeOut(duration: 0.35)) { entered = true }+ headingFocused = true+ }+ .onDisappear { gamepad.perform = { _ in } }+ .onChange(of: state.step) { _ in+ padFocus.focused = nil+ detailsOpen = false+ pickerError = nil+ headingFocused = true+ }+ .onChange(of: accessibilityStatus) { status in+ guard !status.isEmpty else { return }+ NSAccessibility.post(element: NSApplication.shared, notification: .announcementRequested,+ userInfo: [.announcement: status, .priority: NSAccessibilityPriorityLevel.medium.rawValue])+ }+ .onExitCommand { goBack() }+ .fileImporter(isPresented: $pickerOpen, allowedContentTypes: pickingKeys ? [.data] : [.folder]) { result in+ switch result {+ case let .success(url): pickingKeys ? driver.chooseKeys(url) : driver.chooseGames(url)+ case .failure: pickerError = t("onboarding.chooseFailed")+ }+ }+ }++ private var navigation: some View {+ HStack {+ Group {+ if state.step != .welcome {+ Button(action: goBack) { Label(t("onboarding.back"), systemImage: "chevron.left") }+ .buttonStyle(LauncherSecondaryButtonStyle())+ .padTarget("onboarding.back", scope: "onboarding", activate: goBack)+ } else { Color.clear.frame(height: 36) }+ }.frame(width: 130, alignment: .leading)+ Spacer()+ HStack(spacing: 10) {+ ForEach(OnboardingStep.allCases, id: \.self) { step in+ Capsule().fill(step == state.step ? LauncherPalette.cream : (step.index < state.step.index ? LauncherPalette.ready : Color.white.opacity(0.18)))+ .frame(width: step == state.step ? 26 : 7, height: 7)+ }+ }+ .accessibilityElement(children: .ignore)+ .accessibilityLabel(String(format: t("onboarding.stepCount"), state.step.index + 1, OnboardingStep.allCases.count))+ Spacer()+ Button(t("onboarding.later"), action: driver.skipForLater)+ .buttonStyle(.plain).foregroundStyle(.secondary)+ .padTarget("onboarding.later", scope: "onboarding", activate: driver.skipForLater)+ .frame(width: 130, alignment: .trailing)+ }+ .padding(.horizontal, 40).padding(.top, 40).padding(.bottom, 12)+ }++ private var heading: some View {+ VStack(alignment: .leading, spacing: 14) {+ if state.step == .welcome {+ HStack(spacing: 14) {+ if let icon = Bundle.module.image(forResource: "OnboardingIcon") {+ Image(nsImage: icon).resizable().scaledToFit().frame(width: 62, height: 62)+ .accessibilityHidden(true)+ }+ Text(t("onboarding.brand")).font(.manrope(27, .bold)).tracking(-0.8)+ }+ .padding(.bottom, 14)+ .opacity(entered ? 1 : 0)+ .offset(y: reduceMotion || entered ? 0 : 8)+ }+ if state.step == .done {+ OnboardingCheck(lang: lang).frame(width: 64, height: 64).padding(.bottom, 12)+ }+ Text(t(state.step.titleKey)).font(.manrope(44, .bold)).tracking(-1.3)+ .fixedSize(horizontal: false, vertical: true)+ .accessibilityAddTraits(.isHeader)+ .accessibilityValue(accessibilityStatus)+ .accessibilityFocused($headingFocused)+ Text(t("onboarding.\(state.step.rawValue).note"))+ .font(.manrope(17)).foregroundStyle(.secondary)+ .multilineTextAlignment(.leading)+ .fixedSize(horizontal: false, vertical: true)+ .frame(maxWidth: .infinity, alignment: .leading)+ }+ .frame(maxWidth: .infinity, alignment: .leading)+ }++ @ViewBuilder private var stepContent: some View {+ switch state.step {+ case .welcome: welcome+ case .platform: platforms+ case .xcode: xcode+ case .keys: keys+ case .games: games+ case .done:+ VStack(alignment: .leading, spacing: 18) {+ requirement("onboarding.done.platform", value: t("onboarding.platform.\(state.selectedPlatform?.rawValue ?? "mac")"), okay: true)+ requirement("onboarding.done.tools", value: t("onboarding.ready"), okay: true)+ requirement("onboarding.done.keys", value: t("onboarding.keys.valid"), okay: true)+ }.modifier(OnboardingCard())+ }+ }++ private var welcome: some View {+ VStack(alignment: .leading, spacing: 22) {+ requirement("onboarding.require.mac", value: t("onboarding.require.macNote"), okay: true)+ requirement("onboarding.require.files", value: t("onboarding.require.filesNote"), okay: nil)+ if case let .requirements(free, needed) = state.welcome {+ requirement("onboarding.require.disk", value: String(format: t("onboarding.require.diskNote"), free, needed), okay: state.welcome.hasSpace)+ if !state.welcome.hasSpace {+ Text(t("onboarding.require.diskWarning")).foregroundStyle(LauncherPalette.building)+ }+ }+ }.modifier(OnboardingCard())+ }++ private func requirement(_ key: String, value: String, okay: Bool?) -> some View {+ HStack(alignment: .top, spacing: 16) {+ Image(systemName: okay == true ? "checkmark.circle" : (okay == false ? "exclamationmark.triangle" : "folder"))+ .font(.system(size: 22, weight: .light))+ .foregroundStyle(okay == false ? LauncherPalette.building : LauncherPalette.cream)+ .frame(width: 28).accessibilityHidden(true)+ VStack(alignment: .leading, spacing: 5) {+ Text(t(key)).font(.manrope(15, .semibold))+ Text(value).foregroundStyle(.secondary).fixedSize(horizontal: false, vertical: true)+ }+ }.accessibilityElement(children: .combine)+ }++ private var platforms: some View {+ HStack(alignment: .top, spacing: 16) {+ ForEach(OnboardingPlatform.allCases, id: \.self) { platform in+ let selected = state.selectedPlatform == platform+ Button { driver.choosePlatform(platform) } label: {+ VStack(alignment: .leading, spacing: 18) {+ HStack {+ Image(systemName: platform.symbol).font(.system(size: 34, weight: .light))+ Spacer()+ Image(systemName: selected ? "checkmark.circle.fill" : "circle")+ .foregroundStyle(selected ? LauncherPalette.cream : Color.white.opacity(0.2))+ }.accessibilityHidden(true)+ Text(t("onboarding.platform.\(platform.rawValue)")).font(.manrope(22, .bold))+ Text(t(platform.includesIOS ? "onboarding.platform.iosSize" : "onboarding.platform.macNote"))+ .font(.manrope(13)).foregroundStyle(.secondary)+ .fixedSize(horizontal: false, vertical: true)+ Spacer(minLength: 0)+ }+ .padding(24).frame(maxWidth: .infinity, minHeight: 200, alignment: .topLeading)+ .background(selected ? LauncherPalette.cream.opacity(0.07) : LauncherPalette.surface, in: RoundedRectangle(cornerRadius: 14))+ .overlay(RoundedRectangle(cornerRadius: 14).strokeBorder(selected ? LauncherPalette.cream : Color.white.opacity(0.10), lineWidth: selected ? 2 : 1))+ .contentShape(RoundedRectangle(cornerRadius: 14))+ }+ .buttonStyle(.plain)+ .accessibilityAddTraits(selected ? .isSelected : [])+ .padTarget("onboarding.platform.\(platform.rawValue)", scope: "onboarding", radius: 14) { driver.choosePlatform(platform) }+ }+ }+ }++ private var xcode: some View {+ HStack(alignment: .top, spacing: 22) {+ VStack(alignment: .leading, spacing: 20) {+ HStack(spacing: 12) {+ xcodeIcon+ Text(t(state.xcode.statusKey)).font(.manrope(18, .semibold))+ .fixedSize(horizontal: false, vertical: true)+ }.accessibilityElement(children: .combine)+ switch state.xcode {+ case .checking: Text(t("onboarding.xcode.checkingNote")).foregroundStyle(.secondary)+ case .missing: Text(t("onboarding.xcode.missingNote")).foregroundStyle(.secondary)+ case .downloading:+ Text(t("onboarding.xcode.downloadNote")).foregroundStyle(.secondary)+ waitingBar+ case .needsSetup: Text(t("onboarding.xcode.passwordNote")).foregroundStyle(.secondary)+ case .settingUp, .ready:+ ForEach(state.setupTasks, id: \.self) { task in+ taskRow(task.titleKey, status: state.setup[task] ?? (state.xcode == .ready ? .done : .queued))+ }+ case let .failed(failure): failureView(failure)+ }+ }+ .frame(maxWidth: .infinity, alignment: .leading).modifier(OnboardingCard())+ VStack(alignment: .leading, spacing: 20) {+ Text(t("onboarding.background.title")).font(.manrope(14, .semibold))+ ForEach(OnboardingBackgroundTask.allCases, id: \.self) { task in+ taskRow(task.titleKey, status: state.background[task] ?? .queued)+ }+ Text(t("onboarding.background.note")).font(.manrope(12)).foregroundStyle(.secondary)+ .fixedSize(horizontal: false, vertical: true)+ }+ .frame(width: 230, alignment: .leading).modifier(OnboardingCard())+ }+ }++ @ViewBuilder private var xcodeIcon: some View {+ switch state.xcode {+ case .ready: OnboardingCheck(lang: lang).frame(width: 26, height: 26)+ case .checking, .downloading, .settingUp: OnboardingWaiting(label: t("onboarding.running")).frame(width: 24, height: 24)+ default: Image(systemName: "hammer").foregroundStyle(LauncherPalette.cream).accessibilityHidden(true)+ }+ }++ @ViewBuilder private var waitingBar: some View {+ if reduceMotion {+ Capsule().fill(LauncherPalette.cream.opacity(0.2)).frame(height: 6).accessibilityHidden(true)+ } else {+ LauncherProgressBar(value: nil, height: 6, tint: LauncherPalette.cream).accessibilityHidden(true)+ }+ }++ private func taskRow(_ key: String, status: OnboardingTaskState) -> some View {+ VStack(alignment: .leading, spacing: 8) {+ HStack(spacing: 10) {+ Group {+ switch status {+ case .done: OnboardingCheck(lang: lang)+ case .running: OnboardingWaiting(label: t("onboarding.running"))+ case .queued: Image(systemName: "circle").foregroundStyle(LauncherPalette.unbuilt)+ case .failed: Image(systemName: "exclamationmark.circle").foregroundStyle(LauncherPalette.building)+ }+ }.frame(width: 20, height: 20).accessibilityHidden(true)+ Text(t(key)).font(.manrope(13, .medium))+ Spacer(minLength: 0)+ }+ if case let .running(progress) = status, let progress {+ LauncherProgressBar(value: progress, height: 4, tint: LauncherPalette.cream)+ .transaction { if reduceMotion { $0.animation = nil; $0.disablesAnimations = true } }+ .accessibilityHidden(true)+ }+ if case let .failed(failure) = status {+ Text(failure.message).font(.manrope(12)).foregroundStyle(LauncherPalette.building)+ .fixedSize(horizontal: false, vertical: true)+ }+ }+ .accessibilityElement(children: .combine)+ .accessibilityValue(t(status.statusKey) + progressText(status))+ }++ private func progressText(_ status: OnboardingTaskState) -> String {+ if case let .running(progress) = status, let progress { return ", \(Int(progress * 100))%" }+ return ""+ }++ private func failureView(_ failure: OnboardingFailure) -> some View {+ VStack(alignment: .leading, spacing: 14) {+ Text(failure.message).foregroundStyle(LauncherPalette.building).fixedSize(horizontal: false, vertical: true)+ if !failure.details.isEmpty {+ Button { detailsOpen.toggle() } label: {+ Label(t(detailsOpen ? "onboarding.hideDetails" : "onboarding.showDetails"), systemImage: detailsOpen ? "chevron.down" : "chevron.right")+ }+ .buttonStyle(LauncherSecondaryButtonStyle())+ .accessibilityValue(t(detailsOpen ? "onboarding.expanded" : "onboarding.collapsed"))+ .padTarget("onboarding.details", scope: "onboarding") { detailsOpen.toggle() }+ if detailsOpen {+ Text(failure.details).font(.mono(11)).textSelection(.enabled)+ .frame(maxWidth: .infinity, alignment: .leading)+ .padding(12).background(Color.black.opacity(0.25), in: RoundedRectangle(cornerRadius: 8))+ }+ }+ }+ }++ private var keys: some View {+ VStack(alignment: .leading, spacing: 18) {+ HStack(spacing: 12) {+ if state.keys == .valid { OnboardingCheck(lang: lang).frame(width: 26, height: 26) }+ else if state.keys == .searching || state.keys == .validating {+ OnboardingWaiting(label: t(state.keys.statusKey)).frame(width: 24, height: 24)+ } else { Image(systemName: "key").foregroundStyle(LauncherPalette.cream).accessibilityHidden(true) }+ Text(t(state.keys.statusKey)).font(.manrope(17, .semibold))+ }.accessibilityElement(children: .combine)+ if case let .found(url) = state.keys {+ Text(url.path).font(.mono(12)).foregroundStyle(.secondary).textSelection(.enabled)+ .fixedSize(horizontal: false, vertical: true)+ }+ if case let .invalid(reason) = state.keys {+ Text(reason).foregroundStyle(LauncherPalette.building).fixedSize(horizontal: false, vertical: true)+ }+ if state.keys != .valid {+ dropZone(keys: true, enabled: state.keys != .validating)+ }+ Text(t("onboarding.keys.privacy")).font(.manrope(12)).foregroundStyle(.secondary)+ }.modifier(OnboardingCard())+ }++ private var games: some View {+ VStack(alignment: .leading, spacing: 20) {+ switch state.games {+ case .scanning:+ HStack(spacing: 12) {+ OnboardingWaiting(label: t("onboarding.games.scanning")).frame(width: 24, height: 24)+ Text(t("onboarding.games.scanning"))+ }+ case let .found(games) where !games.isEmpty:+ Text(String(format: t("onboarding.games.count"), games.count)).foregroundStyle(LauncherPalette.ready)+ LazyVGrid(columns: [GridItem(.adaptive(minimum: 210, maximum: 290))], alignment: .leading, spacing: 22) {+ ForEach(games) { game in+ VStack(alignment: .leading, spacing: 8) {+ // The collection's 1.8:1 crop, placeholder and radius, with driver-supplied artwork.+ GeometryReader { geometry in+ ZStack {+ if let cover = game.cover { Image(nsImage: cover).resizable().scaledToFill() }+ else {+ LauncherPalette.surface+ Image(systemName: "gamecontroller").font(.system(size: 30, weight: .light)).foregroundStyle(.secondary)+ }+ }+ .frame(width: geometry.size.width, height: geometry.size.height).clipped()+ .clipShape(RoundedRectangle(cornerRadius: 5))+ }.aspectRatio(1.8, contentMode: .fit).accessibilityHidden(true)+ Text(game.title).font(.manrope(16, .semibold)).lineLimit(2)+ Text(String(format: t("onboarding.games.version"), game.version)).font(.manrope(12)).foregroundStyle(.secondary)+ }.accessibilityElement(children: .combine)+ }+ }+ case .none, .found:+ Label(t("onboarding.games.none"), systemImage: "folder.badge.questionmark").foregroundStyle(LauncherPalette.building)+ Text(t("onboarding.games.noneHint")).foregroundStyle(.secondary)+ case .empty: EmptyView()+ }+ dropZone(keys: false, enabled: state.games != .scanning)+ }+ }++ private func dropZone(keys: Bool, enabled: Bool) -> some View {+ OnboardingDropZone(label: t(keys ? "onboarding.keys.drop" : "onboarding.games.drop"),+ chooseLabel: t("onboarding.choose"), id: keys ? "keys" : "games", enabled: enabled,+ choose: { pickingKeys = keys; pickerOpen = true },+ receive: { url in keys ? driver.chooseKeys(url) : driver.chooseGames(url) })+ }++ private var footer: some View {+ VStack(spacing: 0) {+ Divider().opacity(0.3)+ HStack(spacing: 24) {+ VStack(alignment: .leading, spacing: 5) {+ Text(t("onboarding.footer")).font(.manrope(13)).foregroundStyle(.secondary)+ if let pickerError { Text(pickerError).font(.manrope(12)).foregroundStyle(LauncherPalette.building) }+ }+ Spacer()+ Button(action: primaryAction) {+ HStack(spacing: 12) {+ Text(t(state.primaryKey))+ Image(systemName: state.step == .done ? "arrow.up.right" : "arrow.right").accessibilityHidden(true)+ }+ .font(.manrope(16, .semibold)).padding(.horizontal, 28).padding(.vertical, 15)+ .frame(minWidth: 190)+ .foregroundStyle(state.primaryEnabled ? Color.black : Color.white.opacity(0.55))+ .background(state.primaryEnabled ? LauncherPalette.cream : Color.white.opacity(0.08), in: Capsule())+ .contentShape(Capsule())+ }+ .buttonStyle(.plain).disabled(!state.primaryEnabled)+ .keyboardShortcut(.return, modifiers: [])+ .padTarget("onboarding.primary", scope: "onboarding", radius: 28) { if state.primaryEnabled { primaryAction() } }+ }.padding(.horizontal, 56).padding(.vertical, 24)+ }+ }++ private func primaryAction() {+ guard state.primaryEnabled else { return }+ backwards = false+ switch state.primary {+ case .start: driver.start()+ case .next: driver.next()+ case .getXcode: driver.getXcode()+ case .finishXcodeSetup: driver.finishXcodeSetup()+ case .retry: driver.retry(state.step)+ case .confirmKeys: driver.confirmKeys()+ case .openLibrary: driver.openLibrary()+ case .waiting: break+ }+ }+ private func goBack() { backwards = true; driver.back() }+ private func padAction(_ action: LauncherGamepad.Action) {+ guard !pickerOpen else { return }+ if action == .b { goBack(); return }+ if !padFocus.visible {+ padFocus.show(default: "onboarding.primary")+ if [.up, .down, .left, .right].contains(action) { return }+ }+ switch action {+ case .up: padFocus.move(dx: 0, dy: -1)+ case .down: padFocus.move(dx: 0, dy: 1)+ case .left: padFocus.horizontal(-1)+ case .right: padFocus.horizontal(1)+ case .a: padFocus.activate()+ default: break+ }+ }+}++private struct OnboardingCard: ViewModifier {+ func body(content: Content) -> some View {+ content.padding(24).frame(maxWidth: .infinity, alignment: .leading)+ .background(LauncherPalette.surface, in: RoundedRectangle(cornerRadius: 14))+ .overlay(RoundedRectangle(cornerRadius: 14).strokeBorder(Color.white.opacity(0.08)))+ }+}++private struct OnboardingDropZone: View {+ let label: String, chooseLabel: String, id: String+ let enabled: Bool+ let choose: () -> Void+ let receive: (URL) -> Void+ @State private var targeted = false+ var body: some View {+ HStack(spacing: 16) {+ Image(systemName: "square.and.arrow.down").font(.system(size: 26, weight: .light)).accessibilityHidden(true)+ Text(label).font(.manrope(14)).fixedSize(horizontal: false, vertical: true)+ Spacer()+ Button(chooseLabel, action: choose).buttonStyle(LauncherSecondaryButtonStyle())+ .accessibilityLabel(label + ". " + chooseLabel)+ .padTarget("onboarding.choose.\(id)", scope: "onboarding") { if enabled { choose() } }+ }+ .padding(24).frame(minHeight: 112)+ .background(LauncherPalette.cream.opacity(targeted ? 0.10 : 0.025), in: RoundedRectangle(cornerRadius: 12))+ .overlay(RoundedRectangle(cornerRadius: 12).strokeBorder(LauncherPalette.cream.opacity(targeted ? 0.8 : 0.25), style: StrokeStyle(lineWidth: 1, dash: [6, 5])))+ .disabled(!enabled).opacity(enabled ? 1 : 0.5)+ .onDrop(of: [.fileURL], isTargeted: $targeted) { providers in+ guard enabled, let first = providers.first else { return false }+ _ = first.loadDataRepresentation(forTypeIdentifier: UTType.fileURL.identifier) { data, _ in+ guard let data, let url = URL(dataRepresentation: data, relativeTo: nil), url.isFileURL else { return }+ DispatchQueue.main.async { receive(url) }+ }+ return true+ }+ }+}++private struct OnboardingWaiting: View {+ let label: String+ @Environment(\.accessibilityReduceMotion) private var reduceMotion+ var body: some View {+ TimelineView(.animation(paused: reduceMotion)) { context in+ Circle().trim(from: 0.05, to: 0.76).stroke(LauncherPalette.cream, style: StrokeStyle(lineWidth: 2, lineCap: .round))+ .padding(2)+ .rotationEffect(.degrees(reduceMotion ? 0 : context.date.timeIntervalSinceReferenceDate.truncatingRemainder(dividingBy: 1.6) / 1.6 * 360))+ }.accessibilityLabel(label)+ }+}++private struct OnboardingCheck: View {+ let lang: Lang+ @Environment(\.accessibilityReduceMotion) private var reduceMotion+ @State private var drawn = false+ var body: some View {+ ZStack {+ Circle().stroke(LauncherPalette.ready.opacity(0.25), lineWidth: 1)+ CheckStroke().trim(from: 0, to: reduceMotion || drawn ? 1 : 0)+ .stroke(LauncherPalette.ready, style: StrokeStyle(lineWidth: 2, lineCap: .round, lineJoin: .round))+ .padding(5)+ }+ .accessibilityLabel(L10n.string("onboarding.ready", lang))+ .onAppear { withAnimation(.easeOut(duration: 0.3)) { drawn = true } }+ }+ private struct CheckStroke: Shape {+ func path(in rect: CGRect) -> Path {+ Path { path in+ path.move(to: CGPoint(x: rect.minX + rect.width * 0.12, y: rect.midY))+ path.addLine(to: CGPoint(x: rect.minX + rect.width * 0.4, y: rect.minY + rect.height * 0.77))+ path.addLine(to: CGPoint(x: rect.minX + rect.width * 0.9, y: rect.minY + rect.height * 0.22))+ }+ }+ }+}++/// Demo exits stay in the mock shell; opening a demo never starts real launcher detection or work.+@MainActor struct OnboardingDemoHost: View {+ @StateObject private var driver: MockOnboardingDriver+ @StateObject private var padFocus = PadFocus()+ @StateObject private var gamepad = LauncherGamepad()+ private let lang = Lang.initial()+ init(scenario: MockOnboardingDriver.Scenario) {+ _driver = StateObject(wrappedValue: MockOnboardingDriver(scenario: scenario))+ }+ var body: some View {+ Group {+ if driver.state.exit == nil { OnboardingView(driver: driver, lang: lang, gamepad: gamepad) }+ else {+ VStack(spacing: 24) {+ Text(L10n.string(driver.state.exit == .later ? "onboarding.demo.paused" : "onboarding.demo.library", lang)).font(.manrope(32, .bold))+ Text(L10n.string("onboarding.demo.note", lang)).foregroundStyle(.secondary)+ if driver.state.exit == .later {+ Button(L10n.string("onboarding.demo.resume", lang), action: driver.resume)+ .buttonStyle(LauncherSecondaryButtonStyle())+ .keyboardShortcut(.return, modifiers: [])+ .padTarget("onboarding.resume", scope: "onboarding", activate: driver.resume)+ }+ }+ .frame(maxWidth: .infinity, maxHeight: .infinity)+ .padScope("onboarding", padFocus).environmentObject(padFocus)+ .onAppear { [driver, padFocus, gamepad] in+ padFocus.scope = "onboarding"+ // The flow releases its action on disappearance; install the exit screen's action after that.+ DispatchQueue.main.async {+ guard driver.state.exit != nil else { return }+ gamepad.perform = { [weak driver, weak padFocus] action in+ padFocus?.show(default: "onboarding.resume")+ if action == .a { driver?.resume() }+ }+ }+ }+ }+ }+ .frame(minWidth: 900, minHeight: 680)+ .foregroundStyle(.white).background(LauncherPalette.background)+ .background(LauncherWindowChrome()).preferredColorScheme(.dark)+ }+}diff --git a/frontend/Sources/NSPortBuilder/Resources/OnboardingIcon.png b/frontend/Sources/NSPortBuilder/Resources/OnboardingIcon.pngnew file mode 100644index 00000000..a6fa7499Binary files /dev/null and b/frontend/Sources/NSPortBuilder/Resources/OnboardingIcon.png differdiff --git a/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift b/frontend/Tests/NSPortBuilderTests/OnboardingTests.swiftnew file mode 100644index 00000000..f03d9289--- /dev/null+++ b/frontend/Tests/NSPortBuilderTests/OnboardingTests.swift@@ -0,0 +1,198 @@+import XCTest+import SwiftUI+@testable import NSPortBuilder++final class OnboardingTests: XCTestCase {+ func testNextBackAndGates() {+ var s = OnboardingState()+ XCTAssertTrue(s.primaryEnabled)+ s.back(); XCTAssertEqual(s.step, .welcome)+ s.next(); XCTAssertEqual(s.step, .platform)+ XCTAssertFalse(s.primaryEnabled)+ s.next(); XCTAssertEqual(s.step, .platform)+ s.platform = .selected(.mac)+ s.next(); XCTAssertEqual(s.step, .xcode)+ XCTAssertFalse(s.primaryEnabled)+ s.xcode = .ready+ XCTAssertFalse(s.canAdvance, "Xcode alone does not finish background preparation")+ s.background = Dictionary(uniqueKeysWithValues: OnboardingBackgroundTask.allCases.map { ($0, .done) })+ XCTAssertTrue(s.canAdvance)+ s.next(); XCTAssertEqual(s.step, .keys)+ s.keys = .valid+ s.next(); XCTAssertEqual(s.step, .games)+ s.games = .found([])+ XCTAssertFalse(s.primaryEnabled)+ s.games = .found([.init(id: "sample", title: "Sample", version: "1")])+ s.next(); XCTAssertEqual(s.step, .done)+ XCTAssertFalse(s.primaryEnabled)+ s.done = .ready+ XCTAssertTrue(s.primaryEnabled)+ s.next(); XCTAssertEqual(s.step, .done)+ s.back(); XCTAssertEqual(s.step, .games)+ }++ func testDiskSpaceGateAndEveryXcodeAction() {+ var s = OnboardingState()+ s.welcome = .requirements(freeGB: 8, neededGB: 24)+ XCTAssertFalse(s.primaryEnabled)+ s.next(); XCTAssertEqual(s.step, .welcome)+ s.step = .xcode+ for value: OnboardingState.Xcode in [.checking, .downloading, .settingUp] {+ s.xcode = value+ XCTAssertFalse(s.primaryEnabled)+ XCTAssertFalse(s.canAdvance)+ }+ s.xcode = .missing+ XCTAssertEqual(s.primary, .getXcode); XCTAssertTrue(s.primaryEnabled)+ s.xcode = .needsSetup+ XCTAssertEqual(s.primary, .finishXcodeSetup); XCTAssertTrue(s.primaryEnabled)+ s.xcode = .failed(.init(message: "Failure", details: "Diagnostic"))+ XCTAssertEqual(s.primary, .retry); XCTAssertTrue(s.primaryEnabled)+ XCTAssertFalse(s.canAdvance)+ s.xcode = .ready+ s.background[.python] = .failed(.init(message: "Failure"))+ XCTAssertEqual(s.primary, .retry)+ XCTAssertFalse(s.canAdvance)+ }++ func testKeysAndGamesNeverAdvanceBeforeValidation() {+ var s = OnboardingState()+ s.step = .keys+ for value: OnboardingState.Keys in [.empty, .searching, .validating, .invalid("Invalid")] {+ s.keys = value+ XCTAssertFalse(s.primaryEnabled)+ s.next(); XCTAssertEqual(s.step, .keys)+ }+ s.keys = .found(URL(fileURLWithPath: "/Demo/prod.keys"))+ XCTAssertEqual(s.primary, .confirmKeys)+ XCTAssertTrue(s.primaryEnabled)+ XCTAssertFalse(s.canAdvance, "Confirming a found file still needs validation")+ s.step = .games+ for value: OnboardingState.Games in [.empty, .scanning, .none, .found([])] {+ s.games = value+ XCTAssertFalse(s.primaryEnabled)+ s.next(); XCTAssertEqual(s.step, .games)+ }+ }++ func testIOSIsAddedOnlyForIPhoneChoices() {+ var s = OnboardingState()+ for platform in OnboardingPlatform.allCases {+ s.platform = .selected(platform)+ XCTAssertEqual(s.setupTasks.contains(.ios), platform != .mac)+ XCTAssertEqual(s.setupTasks.count, platform == .mac ? 4 : 5)+ }+ }++ func testResumeKeepsStepAndSelectionsWithoutPreferences() async {+ await MainActor.run {+ var snapshot = OnboardingState()+ snapshot.step = .games+ snapshot.platform = .selected(.both)+ snapshot.keys = .valid+ snapshot.games = .found([.init(id: "game", title: "Game", version: "1")])+ snapshot.done = .ready+ let d = MockOnboardingDriver(state: snapshot, animated: false)+ d.skipForLater()+ XCTAssertEqual(d.state.exit, .later)+ XCTAssertEqual(d.resumeSnapshot, snapshot)+ XCTAssertFalse(d.state.primaryEnabled)+ d.next(); d.back()+ XCTAssertEqual(d.state.step, .games)+ let restored = MockOnboardingDriver(state: d.resumeSnapshot!, animated: false)+ XCTAssertEqual(restored.state, snapshot)+ d.resume()+ XCTAssertEqual(d.state, snapshot)+ restored.back(); XCTAssertEqual(restored.state.step, .keys)+ d.next(); d.openLibrary()+ XCTAssertEqual(d.state.exit, .library)+ d.resume()+ XCTAssertEqual(d.state.exit, .library, "A completed flow cannot resume an older paused snapshot")+ }+ }++ func testReturningToPlatformAddsIOSWork() async {+ await MainActor.run {+ var s = OnboardingState()+ s.step = .platform+ s.platform = .selected(.mac)+ s.xcode = .ready+ let d = MockOnboardingDriver(state: s, animated: false)+ d.choosePlatform(.both)+ XCTAssertEqual(d.state.xcode, .needsSetup)+ XCTAssertEqual(d.state.setup[.ios], .queued)+ XCTAssertTrue(d.state.setupTasks.contains(.ios))+ }+ }++ func testDriverIntentsAreGated() async {+ await MainActor.run {+ let d = MockOnboardingDriver(animated: false)+ d.getXcode(); d.finishXcodeSetup(); d.confirmKeys(); d.openLibrary()+ XCTAssertEqual(d.state.step, .welcome)+ XCTAssertEqual(d.state.xcode, .checking)+ XCTAssertNil(d.state.exit)+ d.start(); d.choosePlatform(.iphone); d.next()+ XCTAssertEqual(d.state.step, .xcode)+ XCTAssertEqual(d.state.setupTasks.last, .ios)+ d.next(); XCTAssertEqual(d.state.step, .xcode)+ }+ }++ func testAllOnboardingStringsHaveBothLanguages() {+ let keys = L10n.table.keys.filter { $0.hasPrefix("onboarding.") }+ XCTAssertGreaterThan(keys.count, 80)+ for key in keys {+ XCTAssertFalse(L10n.string(key, .en).isEmpty, key)+ XCTAssertFalse(L10n.string(key, .zh).isEmpty, key)+ XCTAssertNotEqual(L10n.string(key, .en), key)+ XCTAssertNotEqual(L10n.string(key, .zh), key)+ }+ for step in OnboardingStep.allCases {+ XCTAssertNotNil(L10n.table[step.titleKey])+ XCTAssertNotNil(L10n.table["onboarding.\(step.rawValue).note"])+ }+ for task in OnboardingSetupTask.allCases { XCTAssertNotNil(L10n.table[task.titleKey]) }+ for task in OnboardingBackgroundTask.allCases { XCTAssertNotNil(L10n.table[task.titleKey]) }+ XCTAssertTrue(L10n.selfCheck().isEmpty)+ }++ /// The same opt-in native capture path as the launcher's other visual QA tests.+ @MainActor func testRenderOnboardingForVisualQA() throws {+ guard let directory = ProcessInfo.processInfo.environment["NX_ONBOARDING_CAPTURE_DIR"] else {+ throw XCTSkip("Set NX_ONBOARDING_CAPTURE_DIR to capture onboarding")+ }+ let output = URL(fileURLWithPath: directory)+ try FileManager.default.createDirectory(at: output, withIntermediateDirectories: true)+ NSApplication.shared.setActivationPolicy(.accessory)+ XCTAssertNotNil(Bundle.module.image(forResource: "OnboardingIcon"))+ for lang: Lang in [.en, .zh] {+ for step in OnboardingStep.allCases {+ var s = OnboardingState()+ s.step = step+ s.platform = .selected(.both)+ s.xcode = .settingUp+ s.setup = [.selected: .done, .license: .done, .firstLaunch: .done, .metal: .running(0.65), .ios: .queued]+ s.background = [.python: .done, .dotnet: .running(0.5), .tools: .queued]+ s.keys = .found(URL(fileURLWithPath: "/Demo/Switch/prod.keys"))+ s.games = .found([.init(id: "a", title: "Super Mario Odyssey", version: "1.0.0"),+ .init(id: "b", title: "Balatro", version: "1.0.0")])+ s.done = .ready+ let driver = MockOnboardingDriver(state: s, lang: lang, animated: false)+ let view = OnboardingView(driver: driver, lang: lang)+ let host = NSHostingView(rootView: view)+ let window = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 900, height: 680),+ styleMask: [.titled, .closable, .resizable], backing: .buffered, defer: false)+ window.contentView = host+ window.orderFront(nil)+ RunLoop.main.run(until: Date().addingTimeInterval(0.4))+ host.layoutSubtreeIfNeeded()+ let rep = try XCTUnwrap(host.bitmapImageRepForCachingDisplay(in: host.bounds))+ host.cacheDisplay(in: host.bounds, to: rep)+ try XCTUnwrap(rep.representation(using: .png, properties: [:]))+ .write(to: output.appendingPathComponent("\(step.rawValue)-\(lang.rawValue).png"))+ window.orderOut(nil)+ }+ }+ }+}