Something went wrong. Try again.
An auto tiler for macOS
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538public import AppKitimport Dispatchimport Observationpublic import ParcelConfigpublic import ParcelCoreimport ParcelPlatformimport SwiftUI
@MainActor@Observablepublic 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<Void, Never>? @ObservationIgnored private var presentationTask: Task<Void, Never>? private var presentationGeneration = UUID() @ObservationIgnored private var refreshTask: Task<Void, Never>? @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) } }}
@MainActorfinal 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() }}