public import AppKit import Dispatch import Observation public import ParcelConfig public import ParcelCore import ParcelPlatform import SwiftUI @MainActor @Observable public final class WindowLearningController { public private(set) var tour: GuidedTour public let setup: TourSetupController public func beginSetup(_ track: TourTrack) { present() } package var visibleSetupWindow: NSWindow? { guard setup.isPresented, let panel, panel.isVisible else { return nil } return panel } public var setupDisplay: DisplayID? { guard let screen = panel?.screen else { return nil } do { return try DisplayNaming.id(for: screen) } catch { failure(error); return nil } } public var onTourPresented: (@MainActor () -> Void)? public var onTourResolved: (@MainActor () -> Void)? public func completeTour(hide: Bool = true) { guard setup.result?.completed == true, !setup.isBusy else { return } if hide { setup.dismiss(); hideSetup() } } public func closeSetup() { if setup.isBusy { setup.cancelStartup(); return } if setup.result?.completed == true { completeTour(); return } runSetup { try await self.setup.deferSetup() } } public func openTourShortcuts() { changeSetup { try setup.openShortcuts() } } func retrySetup() { guard !setup.isBusy, setup.result?.permitsRetry == true else { return } onTourPresented?() runSetup { try await self.setup.retryStartup() } } public func retryTourProgress() { let expected = setup.sessionID runSetup { let saved = try self.progressStore.migrate() guard let actions = self.setup.actions else { throw TourSetupFailure.unavailable } try await actions.preparePresentation() guard self.setup.isPresented, self.setup.sessionID == expected, !Task.isCancelled else { return } self.setup.begin(progress: saved) try await self.setup.checkCurrentStep() } } public func announceTourPermission() { guard setup.permission != lastAnnouncedPermission else { return } lastAnnouncedPermission = setup.permission if setup.permission == .granted { announce(TourText.text("Accessibility is on.")) } else if setup.permission == .missing { announce(TourText.text("Accessibility is off.")) } } private func hideSetup() { stopSetupObservations() panel?.orderOut(nil) onTourResolved?() if let previousApplication, previousApplication.processIdentifier != ProcessInfo.processInfo.processIdentifier, !previousApplication.isTerminated, let current = NSRunningApplication(processIdentifier: previousApplication.processIdentifier), current.launchDate == previousApplication.launchDate, current.bundleIdentifier == previousApplication.bundleIdentifier, let previousWindow, frontWindow(for: current.processIdentifier) == previousWindow { _ = previousApplication.activate(options: []) } previousApplication = nil previousWindow = nil } private func frontWindow(for pid: pid_t) -> UInt32? { do { return try WindowServer().windows(options: .optionOnScreenOnly) .first { $0.pid == pid && $0.layer == 0 && $0.isOnscreen }?.number } catch { failure(error); return nil } } func reportSetupFailure(_ error: any Error) { failure(error) } func runSetup(_ operation: @escaping @MainActor () async throws -> Void) { guard !setup.isBusy else { return } setupTask?.cancel() let expected = setup.sessionID setupTask = Task { @MainActor in do { try await operation() try Task.checkCancellation() if !setup.isPresented { hideSetup() } } catch is CancellationError { return } catch { guard setup.isPresented, setup.sessionID == expected else { return } setup.report(error); failure(error) } } } func changeSetup(_ operation: () throws -> Void) { do { try operation() } catch { setup.report(error); failure(error) } } public var hoverPreferences: HoverBarConfiguration { hoverSettings?.configuration.hoverBar ?? configuration.hoverBar } private var hoverSettings: SettingsModel? public func bindHoverPreferences(to settings: SettingsModel) { hoverSettings = settings } public var onHoverPreferencesChanged: (@MainActor (HoverBarConfiguration) -> Void)? public private(set) var state = ParcelCore.State() public private(set) var configuration = ParcelConfiguration.defaults public private(set) var active = false private let defaults: UserDefaults let navigationShortcuts: TourNavigationShortcuts private let progressStore: TourSetupProgressStore private var previousApplication: NSRunningApplication? private var previousWindow: UInt32? private var lastAnnouncedPermission = PermissionStatus.checking private let failure: @MainActor (any Error) -> Void private let requestKeyboardFocus: @MainActor (NSPanel) -> Void @ObservationIgnored private var panel: LearningPanel? private(set) var setupContentSize: CGSize? @ObservationIgnored private var setupTask: Task? @ObservationIgnored private var presentationTask: Task? private var presentationGeneration = UUID() @ObservationIgnored private var refreshTask: Task? @ObservationIgnored private var refreshGeneration: UUID? @ObservationIgnored private var pendingFullRefresh = false @ObservationIgnored private var pendingPermissionRefresh = false @ObservationIgnored private var trustObservation: AccessibilityTrustObservation? @ObservationIgnored private var voiceOverObservation: VoiceOverObservation? @ObservationIgnored private var activationObservation: (any NSObjectProtocol)? @ObservationIgnored private var workspaceObservations: [any NSObjectProtocol] = [] public convenience init( defaults: UserDefaults = .standard, onFailure: @escaping @MainActor (any Error) -> Void ) throws { try self.init( defaults: defaults, onFailure: onFailure, requestKeyboardFocus: { $0.makeKeyAndOrderFront(nil) }) } init( defaults: UserDefaults, onFailure: @escaping @MainActor (any Error) -> Void, requestKeyboardFocus: @escaping @MainActor (NSPanel) -> Void ) throws { self.requestKeyboardFocus = requestKeyboardFocus self.defaults = defaults navigationShortcuts = try TourNavigationShortcuts(defaults: defaults) failure = onFailure let store = TourSetupProgressStore(defaults: defaults) progressStore = store setup = TourSetupController( loginDefaultApplied: defaults.bool(forKey: "guidedTour.v2.loginDefaultApplied"), onLoginDefaultApplied: { defaults.set(true, forKey: "guidedTour.v2.loginDefaultApplied") }, saveProgress: { try store.save($0) }) let progress: TourProgress if let stored = defaults.object(forKey: "guidedTour.v1") { guard let data = stored as? Data else { throw LearningPreferenceError.invalidTour } progress = try JSONDecoder().decode(TourProgress.self, from: data) guard progress.isValid else { throw LearningPreferenceError.invalidTour } } else { progress = TourProgress() } tour = GuidedTour(progress: progress) } public var instruction: TourInstruction { TourInstruction(tour: tour, state: state, configuration: configuration, active: active) } public func update(state: ParcelCore.State, configuration: ParcelConfiguration, active: Bool) { let configChanged = self.configuration != configuration self.state = state self.configuration = configuration self.active = active if configChanged { tour.rebase(state, configuration: configuration) } if active { receiveTourState() } else { tour.rebase(state, configuration: configuration) } } public func present(afterOnboarding: Bool = false, defaultOpenAtLogin: Bool = false) { if setup.isPresented { NSApplication.shared.activate(ignoringOtherApps: true) panel?.makeKeyAndOrderFront(nil) return } guard !setup.isBusy else { return } guard presentationTask == nil else { return } let generation = UUID() presentationGeneration = generation let saved: TourSetupProgress let progressError: String? do { saved = try progressStore.migrate() progressError = nil } catch { saved = TourSetupProgress(recovery: .recoveryRequired) progressError = error.localizedDescription failure(error) } if afterOnboarding, progressError == nil, !saved.shouldPresentAtLaunch { return } let selectedIntent = setup.actions?.currentIntent() ?? saved.intent if !setup.isPresented { previousApplication = NSWorkspace.shared.frontmostApplication previousWindow = previousApplication.flatMap { frontWindow(for: $0.processIdentifier) } } onTourPresented?() tour.pause() var held = saved var entryError = progressError if progressError == nil { if defaultOpenAtLogin && !defaults.bool(forKey: "guidedTour.v2.loginDefaultApplied") && held.loginDesired == nil { held.loginDesired = true } held.disposition = .inProgress if !afterOnboarding && saved.completed { held.step = .welcome held.intent = selectedIntent if held.recovery == .none { held.recovery = .interrupted } } do { try progressStore.save(held) } catch { entryError = error.localizedDescription; failure(error) } } let checkpoint = held let savedEntryError = entryError presentationTask = Task { @MainActor [weak self] in guard let self else { return } var presentationError = savedEntryError var prepared = false do { if let actions = setup.actions { try await actions.preparePresentation() } else { throw TourSetupFailure.unavailable } try Task.checkCancellation() prepared = true } catch is CancellationError { return } catch { presentationError = error.localizedDescription; failure(error) } guard generation == presentationGeneration, !Task.isCancelled else { return } var currentProgress = checkpoint var progressIsValid = progressError == nil if progressIsValid { do { guard let latest = try progressStore.load() else { throw TourProgressFailure.invalid } currentProgress = latest } catch { progressIsValid = false presentationError = error.localizedDescription failure(error) } } setup.begin( progress: currentProgress, replay: !afterOnboarding && saved.completed, currentIntent: selectedIntent, defaultOpenAtLogin: defaultOpenAtLogin, progressError: presentationError, wasInterrupted: saved.recovery != .none, progressIsValid: progressIsValid, presentationPrepared: prepared) lastAnnouncedPermission = .checking observeSetupChanges() showSetupPanel() runSetup { try await self.setup.checkCurrentStep() } presentationTask = nil } } private func showSetupPanel() { if panel == nil { let panel = LearningPanel(title: UIStrings.text("Guided Tour"), interactive: true, setupWindow: true) let host = NSHostingView(rootView: TourView(controller: self)) host.sizingOptions = [] panel.contentMinSize = CGSize(width: TourSetupView.windowSize.width, height: 1) panel.contentMaxSize = CGSize(width: TourSetupView.windowSize.width, height: .greatestFiniteMagnitude) panel.setContentSize(setupContentSize ?? TourSetupView.windowSize) panel.onSetupClose = { [weak self] in self?.closeSetup() } host.wantsLayer = true self.panel = panel panel.contentView = host host.layoutSubtreeIfNeeded() panel.isMovableByWindowBackground = true panel.center() } resizePanel() positionPanel() // A resumed tour may open from a background launch without an activation yield. NSApplication.shared.activate(ignoringOtherApps: true) panel?.makeKeyAndOrderFront(nil) } func setupScreenChanged() { announce(TourText.text(setup.step.title)) } func resizeSetupPanel(to measured: CGSize) { guard setup.isPresented else { return } let size = TourWindowGeometry.fittingSize(measured) setupContentSize = size guard let panel else { return } panel.contentMinSize = size panel.contentMaxSize = size let frameSize = panel.frameRect(forContentRect: CGRect(origin: .zero, size: size)).size guard panel.frame.size != frameSize else { return } let frame = TourWindowGeometry.frame(resizing: panel.frame, to: frameSize) LearningMotion.resize(panel, to: frame, configuration: configuration.motion) } func resizePanel() { guard !setup.isPresented, let content = panel?.contentView else { return } content.layoutSubtreeIfNeeded() resizePanel(to: content.fittingSize) } func resizePanel(to size: CGSize) { guard !setup.isPresented, let panel, size.width > 0, size.height > 0 else { return } let frameSize = panel.frameRect(forContentRect: CGRect(origin: .zero, size: size)).size guard panel.frame.size != frameSize else { return } let frame = CGRect( x: panel.frame.midX - frameSize.width / 2, y: panel.frame.maxY - frameSize.height, width: frameSize.width, height: frameSize.height) LearningMotion.resize(panel, to: frame, configuration: configuration.motion) } private func observeSetupChanges() { guard activationObservation == nil else { return } setup.updateVoiceOver(VoiceOverStatus.isRunning) trustObservation = AccessibilityTrustObserver.shared.observe { [weak self] in self?.refreshSetup(permissionOnly: true) } voiceOverObservation = VoiceOverStatus.observeChanges { [weak self] in guard let self, self.setup.isPresented else { return } self.setup.updateVoiceOver(VoiceOverStatus.isRunning) self.refreshSetup(permissionOnly: false) } activationObservation = NotificationCenter.default.addObserver( forName: NSApplication.didBecomeActiveNotification, object: nil, queue: .main ) { [weak self] _ in MainActor.assumeIsolated { guard let self, self.setup.isPresented else { return } self.panel?.makeKey() self.refreshSetup(permissionOnly: false) } } for name in [NSWorkspace.didWakeNotification, NSWorkspace.sessionDidBecomeActiveNotification] { workspaceObservations.append( NSWorkspace.shared.notificationCenter.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in MainActor.assumeIsolated { self?.refreshSetup(permissionOnly: false) } }) } } private func refreshSetup(permissionOnly: Bool) { if permissionOnly { pendingPermissionRefresh = true } else { pendingFullRefresh = true } guard refreshTask == nil else { return } let generation = UUID() refreshGeneration = generation refreshTask = Task { @MainActor [weak self] in guard let self else { return } defer { if refreshGeneration == generation { refreshTask = nil } } while !Task.isCancelled && setup.isPresented && (pendingFullRefresh || pendingPermissionRefresh) { let fullRefresh = pendingFullRefresh pendingFullRefresh = false pendingPermissionRefresh = false do { if fullRefresh { try await setup.refreshAllowChecks() } else { try await setup.refreshPermission() } try Task.checkCancellation() resizePanel() } catch is CancellationError { return } catch { failure(error) } } } } private func stopSetupObservations() { refreshTask?.cancel() refreshTask = nil refreshGeneration = nil pendingFullRefresh = false pendingPermissionRefresh = false trustObservation?.cancel() trustObservation = nil voiceOverObservation?.cancel() voiceOverObservation = nil if let activationObservation { NotificationCenter.default.removeObserver(activationObservation) } activationObservation = nil for observer in workspaceObservations { NSWorkspace.shared.notificationCenter.removeObserver(observer) } workspaceObservations.removeAll() } private func positionPanel() { guard let panel else { return } guard let workspace = state.activeWorkspace, let display = state.displays[workspace.display], display.hasUsableGeometry else { panel.center() return } panel.place( CGRect( x: CGFloat(display.frame.minX + display.frame.size.width / 2) - panel.frame.width / 2, y: CGFloat(display.frame.minY + display.frame.size.height / 2) - panel.frame.height / 2, width: panel.frame.width, height: panel.frame.height)) } public func begin(_ track: TourTrack) { guard active else { return } tour.start(track: track, state: state, configuration: configuration) persist() } public func performed(_ input: TourInput) { tour.performed(input) } public func confirmFocus(_ window: WindowID) { guard active else { return } tour.confirmFocus(window) receiveTourState() } private func receiveTourState() { if tour.receive(state, configuration: configuration) { persist() if tour.progress.track == .keyboard, let panel { requestKeyboardFocus(panel) } announce(UIStrings.text("Nicely done.")) } } public func skip() { tour.skip(state: state, configuration: configuration) persist() } public func next() { tour.continueAfterWin(state: state, configuration: configuration) persist() } public func pause() { presentationGeneration = UUID() presentationTask?.cancel() presentationTask = nil setup.cancelStartup() setupTask?.cancel() setupTask = nil stopSetupObservations() tour.pause() persist() panel?.orderOut(nil) } public func setHoverPreferences(_ preferences: HoverBarConfiguration) { guard preferences.isValid else { failure(LearningPreferenceError.invalidHover) return } guard let onHoverPreferencesChanged else { failure(LearningPreferenceError.hoverWriterUnavailable) return } onHoverPreferencesChanged(preferences) } public func stop() { pause() setup.dismiss() panel?.contentView = nil panel?.close() panel = nil active = false state = ParcelCore.State() } private func persist() { do { defaults.set(try JSONEncoder().encode(tour.progress), forKey: "guidedTour.v1") } catch { failure(error) } } private func announce(_ text: String) { guard let panel else { return } NSAccessibility.post( element: panel, notification: .announcementRequested, userInfo: [.announcement: text, .priority: NSAccessibilityPriorityLevel.medium.rawValue]) } } private enum LearningPreferenceError: LocalizedError { case invalidTour, invalidHover, hoverWriterUnavailable var errorDescription: String? { switch self { case .invalidTour: UIStrings.text( "Your saved tour couldn't be read. Reset guidedTour.v1 in Parcel's preferences to start fresh.") case .hoverWriterUnavailable: String( localized: "Hover bar settings could not be saved. Open Settings and try again.", table: "Settings", bundle: .module) case .invalidHover: String(localized: "Hover delay must be between 0.1 and 3 seconds.", table: "Settings", bundle: .module) } } } @MainActor final class TourMenuItem: NSMenuItem { private let invoke: @MainActor () -> Void init(invoke: @escaping @MainActor () -> Void) { self.invoke = invoke let title = UIStrings.text("Guided Tour…") super.init(title: title, action: #selector(openTour), keyEquivalent: "") target = self setAccessibilityLabel(title) } required init(coder: NSCoder) { fatalError("init(coder:) is unavailable") } @objc private func openTour() { invoke() } }