25 KiB
01 — Core Application Architecture & Lifecycle
Audit scope: the app entry point,
App.swift(NSApplicationDelegate), andsrc/macos/(permissions, accessibility, login item, AX scheduling). This is the spine the rest of the paywall-removal audit hangs on. Read-only audit — no source was modified.
All file:line references are against the tree as audited (branch master, commit 9fadf36b).
1. Entry point & process bootstrap
The app has no @main / @NSApplicationMain. It uses a top-level main.swift
(src/main.swift) as the executable entry, per the AGENTS.md "pure Swift, no Interface Builder"
constraint.
Boot order in src/main.swift:
src/main.swift:4-6— CLI fast-path. If launched with a recognized CLI command (CliClient.detectCommand()), it forwards the command to the already-running instance via a Mach message port and the process exits early (never becomes the GUI app).src/main.swift:11-15— installs POSIX signal handlers forSIGTERM/SIGTRAPthat callemergencyExit(...).src/main.swift:19-21— installsNSSetUncaughtExceptionHandler(Obj-C exceptions) → alsoemergencyExit(...).src/main.swift:23—App.shared.run()enters the AppKit run loop.
emergencyExit (src/main.swift:33-39) re-enables the native ⌘-Tab
(setNativeCommandTabEnabled(true)), prints a stack trace, drains in-flight screen captures
(makeSureAllCapturesAreFinished(), src/main.swift:41-51, which sets App.isTerminating = true
and spins up to 5 s waiting on ActiveWindowCaptures.value()), then exit(0).
Paywall touchpoint in entry path: none. main.swift is clean.
2. The App class
App (src/App.swift:7) subclasses AppCenterApplication (a Microsoft AppCenter NSApplication
subclass, used for crash reporting) and sets itself as its own delegate
(src/App.swift:41-44, delegate = self). It conforms to NSApplicationDelegate in the extension
at src/App.swift:434-507.
It is a hybrid singleton: instance methods satisfy the NSApplicationDelegate protocol, but the
bulk of the app's coordination logic lives in static methods/properties on App (e.g.
App.showUi, App.hideUi, App.refreshUi, App.continueAppLaunchAfterPermissionsAreGranted).
App.shared (src/App.swift:24) downcasts NSApplication.shared.
Notable static state:
App.isTerminating(src/App.swift:28) — read by the capture-drain loop.App.activity(src/App.swift:9-10) — aProcessInfo.beginActivitytoken preventing App Nap.App.sparkleDelegate/App.updaterController(src/App.swift:35-36) — Sparkle auto-update.- Selectors
supportProjectAction/upgradeToProAction/openAccountAction(src/App.swift:25-27) — wired into the menubar (see §7).
3. Startup sequence (the two-phase launch)
Launch is deliberately two-phase, gated on macOS permissions. This split is structurally important for the removal plan because the paywall is initialized in phase A and the rest of the app only boots in phase B after permissions pass.
Phase A — applicationDidFinishLaunching (src/App.swift:435-463)
Runs immediately on launch, before any permission is confirmed:
:436AppCenterCrash()— crash reporting.:437disableRelaunchOnLogin().:438-439Logger.initialize()+ version log.:444(release only)MoveToApplicationsFolder.promptIfNeeded().:446AXUIElement.setGlobalTimeout()— sets the global 1 s AX messaging timeout.:447Preferences.initialize()— loadsUserDefaults, runs migrations.:448-460License/Pro wiring (PAYWALL). Wires threeLicenseManager.sharedcallbacks and callsLicenseManager.shared.initialize(). Detailed in §6.:461BackgroundWork.preStart()— creates the minimal early queues needed for permission polling (permissionsCheckOnTimerQueue,permissionsSystemCallsQueue,screenshotsQueue;src/util/BackgroundWork.swift:23-30).:462SystemPermissions.ensurePermissionsAreGranted()— starts the permission timer (see §5).
Phase A does not create the switcher panel, menubar, or any event taps. If permissions are missing, the app sits in the permission-window loop and never proceeds to phase B.
Phase B — App.continueAppLaunchAfterPermissionsAreGranted (src/App.swift:383-431)
Called once, from SystemPermissions.checkPermissionsPreStartup()
(src/macos/SystemPermissions.swift:77), the moment both Accessibility and Screen-Recording
permissions are confirmed. This is the real subsystem-wiring sequence:
| Line | Call | Subsystem |
|---|---|---|
:385 |
BackgroundWork.start() |
full set of background threads/queues (§4) |
:386 |
NSScreen.updatePreferred() |
display state |
:387 |
Appearance.update() |
switcher theming |
:388-389 |
TilesPanel.updateMaxPossible…Size() |
layout precompute |
:390 |
Menubar.initialize() |
menubar status item (touches license, §7) |
:391 |
MainMenu.create() |
app main menu |
:392-393 |
TilesPanel() / PreviewPanel() |
switcher windows |
:394-395 |
Spaces.refresh() / Screens.refresh() |
spaces & displays state |
:396-405 |
*.observe() for Spaces, Screens, SystemAppearance, SystemScrollerStyle, InputSource, Cursor, Trackpad, Cli; plus Applications.initialDiscovery(); KeyboardEvents.addEventHandlers() |
event observers / taps (§8) |
:406-413 |
SparkleDelegate() + SPUStandardUpdaterController, updater started 30 s later |
auto-update |
:414 |
PreferencesEvents.initialize() |
applies side-effects of every preference |
:415 |
BenchmarkRunner.startIfNeeded() |
dev benchmark |
:416-420 |
first-launch Settings window (showSettingsWindowOnFirstLaunchIfNeeded) |
UI (license-aware, §6) |
:421-426 |
#if DEBUG QA menu / debug graph |
dev-only |
:427 |
UsageStats.prune() |
usage telemetry |
:428-429 |
ProTransitionManager.shared.onAction = … + onAppLaunchComplete() |
PAYWALL (§6) |
Applications.initialDiscovery() (src/App.swift:401) is also where the NSWorkspace
running-applications observer gets installed: it calls RunningApplicationsEvents.observe()
internally (src/switcher/state/Applications.swift:20).
4. Background threading model (BackgroundWork)
src/util/BackgroundWork.swift. The app is heavily multithreaded because most macOS hooks
(CGEvent taps, AX observers, Mach ports) require their own run loops, and AX calls can block for the
1 s timeout.
- Dedicated run-loop threads (
BackgroundThreadWithRunLoop,:106-137):accessibilityEventsThread,keyboardAndMouseAndTrackpadEventsThread,missionControlThread,cliEventsThread. Each runs aCFRunLoopRun()with a dummy source to stay alive (:131-136). Created instart()(:43-49). - Operation queues (
LabeledOperationQueue,:140-160):repeatingKeyQueue,screenshotsQueue,accessibilityCommandsQueue,focusOrderQueue,crashReportsQueue,permissionsCheckOnTimerQueue,permissionsSystemCallsQueue. preStart()(:23-30) creates only the three queues needed before permissions;start()(:32-50) creates the rest in phase B.- Thread budget is policed:
addPotentialThreadCountasserts the total stays ≤ 45 against the ~64-thread process limit (:59-63).
The separate AXCallScheduler (src/macos/AXCallScheduler.swift) owns three more bounded pools
for outgoing AX queries (axQueryFirstTryQueue 10, axQueryScanQueue 6, axQueryRetryQueue 8;
:43-45). It is a per-key serializing executor with retry/backoff for unresponsive apps
(schedule(...), :51-71; attemptBlock, :113-169). It does no throttling/coalescing —
that is the caller's job. No paywall coupling.
Paywall touchpoint in threading: none. BackgroundWork and AXCallScheduler are clean.
5. How permissions are requested (src/macos/SystemPermissions.swift)
SystemPermissions drives a DispatchSourceTimer on permissionsCheckOnTimerQueue.
ensurePermissionsAreGranted()(:22-27) creates the timer with handlercheckPermissionsOnTimerand fires it immediately.- Pre-startup (
checkPermissionsPreStartup,:70-84): if bothAccessibilityPermission.statusandScreenRecordingPermission.statusare not-.notGranted, it flipspreStartupPermissionsPassed = true, closes the permission window, switches to the infrequent timer, starts the distributed-notification revoke listener, and callsApp.continueAppLaunchAfterPermissionsAreGranted()(:77). Otherwise it shows the permissions window (:81). - Post-startup (
checkPermissionsPostStartup,:86-91): if Accessibility is revoked while running, it restarts the app (App.restart()). - Revoke detection (
startListeningForDistributedRevoke,:29-43): observes the undocumentedcom.apple.accessibility.apidistributed notification; on revoke →App.restart(). A sparse 60 s backstop timer covers cases where the notification doesn't fire (setInfrequentTimer,:96-103). - Accessibility detection (
AccessibilityPermission,:116-128):AXIsProcessTrustedWithOptionswithkAXTrustedCheckOptionPrompt: false. - Screen-recording detection (
ScreenRecordingPermission,:130-217): viaSCShareableContent.getExcludingDesktopWindows(macOS 12.3+) orCGDisplayStreamprobing, each wrapped in a 6 s timeout (runWithTimeout,:202-217). HonorsPreferences.screenRecordingPermissionSkipped(:141).
The permission UI window (PermissionsWindow) lives outside this scope
(src/secondary-windows/permission-window/).
Paywall touchpoint in permissions: none. SystemPermissions.swift is clean.
6. PAYWALL — every place the spine touches License / Pro
This section is the deliverable's core. Below is every reference in the spine (App.swift,
Menubar.swift, main.swift, src/macos/) to LicenseManager, ProTransitionManager,
ProPromptHost, checkout, and UpgradeTab.
6.1 App.swift — license wiring & callbacks
file:line |
Code | Purpose |
|---|---|---|
src/App.swift:26 |
static var upgradeToProAction: Selector { #selector(App.upgradeToPro) } |
selector exposed to menubar "Get Pro" |
src/App.swift:27 |
static var openAccountAction: Selector { #selector(App.openAccount) } |
selector for menubar "My Account" |
src/App.swift:78 |
ProTransitionManager.shared.onSwitcherDismissed() |
inside hideUi() — ends free-pass session, queues post-dismiss upsell windows |
src/App.swift:115-117 |
@objc static func upgradeToPro() { ProTransitionManager.openCheckout() } |
opens checkout URL |
src/App.swift:119-121 |
@objc static func openAccount() { UpgradeTab.openAccountPage() } |
opens account page |
src/App.swift:206-207 |
if case .pro = LicenseManager.shared.state { return false } / return !ProTransitionManager.shared.hasSeenWelcome |
willShowDay1WelcomeOnAppLaunch() — defers first-launch Settings if the Day-1 welcome nag will show |
src/App.swift:328 |
ProTransitionManager.shared.onSwitcherShown() |
inside showUiOrCycleSelection() — decides Day-4 tour or post-expiration free-pass |
src/App.swift:428 |
ProTransitionManager.shared.onAction = { ProPromptHost.shared.dispatch($0) } |
binds the prompt-action emitter to the Day-X UI host |
src/App.swift:429 |
ProTransitionManager.shared.onAppLaunchComplete() |
starts the trial-nag scheduler |
src/App.swift:448 |
LicenseManager.shared.onBeforeProUnlock = { ProTransitionManager.shared.onProUnlocked() } |
restore Pro prefs on activation |
src/App.swift:449-459 |
LicenseManager.shared.onStateChanged = { state in … } |
the big state-change fan-out (see below) |
src/App.swift:460 |
LicenseManager.shared.initialize() |
computes initial license/trial state; first thing that touches Keychain/UserDefaults trial bookkeeping |
src/App.swift:480 |
UpgradeTab.showAutoActivating(licenseKey) |
custom-URL alttab://activate handler |
src/App.swift:481-489 |
LicenseManager.shared.activate(licenseKey) { … } (+ UpgradeTab.showAutoActivation{Success,Failed}) |
license activation via custom URL |
The onStateChanged closure (src/App.swift:449-459) does six things on every license-state
transition:
Menubar.refreshLicenseMenuItems()(:450)syncLicenseCookie(state:)(:451) — defined insrc/pro/license/LicenseCookie.swift:5, writes a Sparkle HTTP cookie so the appcast can serve license-aware updates.ProTransitionManager.shared.onLicenseStateChanged()(:452)UpgradeTab.refreshStatus()(:453)SettingsWindow.shared?.refreshUpgradeButton()(:454)App.resetPreferencesDependentComponents()ifTilesPanel.shared != nil(:455), then postsProTransitionManager.proLockStateDidChangeNotification(:458).
6.2 App.swift custom-URL scheme — license activation
application(_:open:) (src/App.swift:465-471) routes alttab:// URLs to handleCustomUrl
(:473-490), which handles only host == "activate" with a license_key query item, calling
LicenseManager.shared.activate(...). The entire custom-URL handler exists solely for license
activation — there is no other URL scheme use in the spine.
6.3 Menubar.swift — license-driven menu items & badge
Menubar is the other spine file with deep paywall coupling (it's created in phase B at
src/App.swift:390):
file:line |
Purpose |
|---|---|
src/Menubar.swift:46-47 |
builds the "Get Pro" item with a custom UpgradeMenuItemView |
src/Menubar.swift:48 |
"My Account" item (App.openAccountAction) |
src/Menubar.swift:49 |
"Support this project" item |
src/Menubar.swift:50 |
calls refreshLicenseMenuItems() during build |
src/Menubar.swift:84-107 |
refreshLicenseMenuItems() — switches visibility of Get-Pro/Account/Support items on LicenseManager.shared.state |
src/Menubar.swift:109-118 |
toggleUpgradeMenuItem() — inserts/removes the Get-Pro item |
src/Menubar.swift:156-158 |
comment referencing LicenseManager.initialize() ordering vs statusItem nil |
src/Menubar.swift:202-227 |
updateBadgeDotOverlay() — gated on ProTransitionManager.shared.shouldShowBadgeDot (orange nag dot on the menubar icon) |
src/Menubar.swift:235-390 |
UpgradeMenuItemView — the entire gradient/shine "Get Pro" menu cell, uses ProGradient.makeLayer() and App.upgradeToPro(); updateContent(_ state: LicenseState) renders trial-days-remaining |
src/Menubar.swift:392-399 |
MenubarMenuDelegate.menuWillOpen → LicenseManager.shared.refreshState() |
6.4 src/macos/ — license touchpoints
None. SystemPermissions.swift, BackgroundWork.swift, AXCallScheduler.swift,
LoginItem.swift contain no License/Pro references (verified by grep). The src/macos/ layer is
paywall-free.
6.5 The contract the spine depends on (for the removal plan)
App.swift depends on this public surface of the Pro module:
LicenseManager.shared(singleton,src/pro/license/LicenseManager.swift:7-15), with:.state: LicenseState(:51),.initialize()(:91),.refreshState()(:99),.activate(_:completion:)(:104),.onStateChanged(:38),.onBeforeProUnlock(:49),.isProLocked(:67),.isProAvailable(:62),.daysSinceTrialStart(:79),.customerEmail(:55).LicenseStateenum (src/pro/license/LicenseState.swift:1-5):.trial(daysRemaining:),.pro,.proExpired,.trialExpired.ProTransitionManager.shared(src/pro/scheduling/ProTransitionManager.swift:105), with the lifecycle hooksonSwitcherShown/Dismissed,onAppLaunchComplete,onLicenseStateChanged,onProUnlocked,onAction,hasSeenWelcome,shouldShowBadgeDot, the staticopenCheckout()(:307) andproLockStateDidChangeNotification(:110).ProPromptHost.shared.dispatch(_:)(src/pro/ui/ProPromptHost.swift:9-11).UpgradeTabstatic methods (src/preferences/settings-window/tabs/UpgradeTab.swift).syncLicenseCookie(state:)(src/pro/license/LicenseCookie.swift:5).
The runtime feature gate itself is ProFeature.attemptUse()
(src/pro/ProFeature.swift:74-83): returns true if isProAvailable, else if a free-pass
session is active, else routes hard-gated features through
ProTransitionManager.shared.attemptHardGatedFeature(...). Call sites for the gate live outside
this scope (TilesView, ShortcutAction, SearchModeResolver) — see §9.
7. App-menu / window plumbing (license-adjacent)
App exposes several @objc window/show helpers wired into the menubar and main menu:
showSettingsWindow (:137), showAboutWindow (:151), showFeedbackPanel (:123),
showDebugWindow (:132), showPermissionsWindow (:235), checkForUpdatesNow (:103),
checkPermissions (:107), supportProject (:111). Of these, only supportProject,
upgradeToPro, openAccount are paywall-adjacent.
First-launch Settings logic (showSettingsWindowOnFirstLaunchIfNeeded, :189-233) is
entangled with the Day-1 welcome nag: it checks willShowDay1WelcomeOnAppLaunch()
(:205-208, reads LicenseManager.shared.state and ProTransitionManager.shared.hasSeenWelcome)
and, if the welcome window will appear, defers showing Settings until a Day1WelcomeLetterWindow
willCloseNotification fires (:210-220).
8. How AltTab hooks into macOS (event taps, AX observers, NSWorkspace)
The hooks are installed in phase B and live mostly under src/events/. Summary of the kernel of
macOS integration the rest of the audit will reference:
- CGEvent tap (keyboard) —
KeyboardEvents.addCgEventTap()(src/events/KeyboardEvents.swift:132-152): a.cghidEventTap/.headInsertEventTap/.defaultTaptap for.flagsChanged+.keyDown, added toBackgroundWork.keyboardAndMouseAndTrackpadEventsThread's run loop. IftapCreatereturns nil (permission lost) →App.restart()(:150). Also a localNSEventmonitor (:123-130). The tap's.keyDownbranch only absorbs Esc, and only when a shortcut binds it and the switcher is active (issue #5585 workaround,:33-44). - Carbon hotkeys —
RegisterEventHotKeyfor the global switcher shortcuts (registerHotKeyIfNeeded,:104-120; handlers installed inaddGlobalHandlerIfNeeded,:154-173).toggleGlobalShortcuts(:64-75) registers/unregisters them when an app exception disables AltTab. - Accessibility (AX) observers —
AccessibilityEvents.axObserverCallback(src/events/AccessibilityEvents.swift:6-21). Subscriptions bake(pid, wid)into therefcon(subscriptionRefcon,:25-28). Focus/activation use an IPC-free fast lane (updateFocusOrderFastLane,:38-56) onBackgroundWork.focusOrderQueue; everything else is scheduled throughAXCallScheduler.sharedand dispatched tohandleEventApp/handleEventWindow. These feed the window inventory (Windows,Applications) and driveApp.refreshOpenUiAfterExternalEvent/App.checkIfShortcutsShouldBeDisabled. - NSWorkspace —
RunningApplicationsEvents.observe()(src/events/RunningApplicationsEvents.swift:6-10): KVO onNSWorkspace.shared.runningApplications(not the launch/terminate notifications, which miss non-GUI apps), feedingApplications.addRunningApplications/removeRunningApplications. - Other observers wired at
src/App.swift:396-405: Spaces, Screens, system appearance, scroller style, input source, cursor, trackpad, CLI (Mach message port). - Login item —
src/macos/LoginItem.swiftwrites/removes a launchdLaunchAgentsplist keyed byApp.bundleIdentifier; reconciled fromPreferences.startAtLoginviaPreferencesEvents.
None of the macOS hook installation is paywall-coupled. The only license interaction at runtime
is via ProFeature.attemptUse() invoked from feature call sites (§9), not from the tap/observer
plumbing itself.
9. Runtime feature gates reachable from the spine (out-of-scope files, noted for the plan)
The spine wires the managers; the actual gating happens when features run. For continuity with
later audit sections, the ProFeature.attemptUse() (src/pro/ProFeature.swift:74) call sites are:
src/switcher/main-window/TilesView.swift:79(lockSearchInSwitcher),:92(searchInSwitcher)src/switcher/ShortcutAction.swift:56(extraShortcut(index:))- preference read interception:
src/preferences/PreferenceDefinition.swift:34-35(isProLocked+isFreePassSessionActiveswap stored Pro values for Free)
And the broader (non-spine) paywall coupling surface — settings UI badges, upgrade tab, and the
preference setter that bounces to the Upgrade tab — is concentrated in src/preferences/...,
src/Menubar.swift, src/events/PreferencesEvents.swift:62-63, and src/debug/QAMenu.swift
(DEBUG-only). These are covered by later audit sections; they are listed here only so the spine's
fan-out is traceable.
10. Removal-plan notes (spine only)
Goal: every ProFeature.attemptUse() should behave as if isProAvailable == true, and all
trial-nag / upsell windows and license activation should be gone, without breaking the two-phase
launch.
App.continueAppLaunchAfterPermissionsAreGrantedmust keep its non-Pro work. Onlysrc/App.swift:428-429(theonActionbinding +onAppLaunchComplete) is Pro. Removing those two lines stops the trial-nag scheduler. Everything else in this method (queues, panels, observers, Sparkle, first-launch Settings) must stay.applicationDidFinishLaunchinglicense block (src/App.swift:448-460) is the cleanest cut point. If the Pro module is deleted wholesale, all 13 lines (:448-459callback wiring +:460initialize()) go. Risk:LicenseManager.shared.initialize()is currently the place that seedstrialStartDate(src/pro/license/LicenseManager.swift:193-194); removing it is fine for a free build (nothing reads trial state once gating is unconditional), but any leftover reader ofLicenseManager.shared.statewill crash if the singleton is deleted.onStateChangedfan-out (src/App.swift:449-459) has one non-Pro side effect worth noting:App.resetPreferencesDependentComponents()(:455) and theproLockStateDidChangeNotificationpost (:458). Both become dead once Pro is removed, butresetPreferencesDependentComponents()itself (src/App.swift:51-53) is a legitimate function used elsewhere — keep the function, drop this caller.hideUi/showUiOrCycleSelectioneach have exactly one Pro line (src/App.swift:78and:328). Remove theProTransitionManager.shared.onSwitcher*calls; the surrounding session logic is independent.upgradeToPro/openAccount/supportProject(src/App.swift:111-121) and their selectors (:25-27) are only referenced by the menubar. Removing the correspondingMenubaritems (src/Menubar.swift:46-50, the entireUpgradeMenuItemView:235-390,refreshLicenseMenuItems:84-118, badge dot:202-227, and theMenubarMenuDelegate.menuWillOpenlicense refresh:392-399) lets these selectors be deleted.supportProject(Endpoints.supportUrl) is a donation link, not a paywall — keep or drop per the owner's call.- Custom-URL handler (
src/App.swift:465-490). The entireapplication(_:open:)+handleCustomUrlexists only for license activation. It can be removed entirely (and thealttab://URL scheme dropped fromInfo.plist— out of this scope but flagged). - First-launch welcome entanglement (
src/App.swift:189-233).willShowDay1WelcomeOnAppLaunch(:205-208) and the deferral observer (:210-220) reference Pro. With the welcome nag gone, simplifyshowSettingsWindowOnFirstLaunchIfNeededto always callshowAndCenterSettingsWindowOnFirstLaunch()directly. Risk: if you deleteDay1WelcomeLetterWindowbut leave thewillCloseNotificationobserver, the observer never fires and Settings never shows on first launch — remove the observer path together with the nag. - Keychain / signing invariant (from AGENTS.md). A free build that keeps
LicenseManageralive (e.g. to avoid touching many call sites) must preserveApp.bundleIdentifier, TeamID, and Developer ID, becauseLicenseManager.keychainServiceis"\(App.bundleIdentifier).license"(src/pro/license/LicenseManager.swift:4). A clean free build that deletes the Pro module entirely removes all Keychain usage and sidesteps this — preferred. Either way, do not rotate bundle ID without the migration AGENTS.md describes. src/macos/is safe. No file undersrc/macos/references the paywall; the permission loop, AX scheduler, and login item need no changes. The phase-A→phase-B handoff (SystemPermissions.swift:77→App.continueAppLaunchAfterPermissionsAreGranted) is the critical path and is paywall-free.
Appendix — files read for this section
src/main.swift, src/App.swift, src/Menubar.swift, src/macos/SystemPermissions.swift,
src/macos/AXCallScheduler.swift, src/macos/LoginItem.swift, src/util/BackgroundWork.swift,
src/events/KeyboardEvents.swift, src/events/AccessibilityEvents.swift,
src/events/RunningApplicationsEvents.swift, src/switcher/SwitcherSession.swift,
src/pro/scheduling/ProTransitionManager.swift, src/pro/license/LicenseManager.swift,
src/pro/license/LicenseState.swift, src/pro/ProFeature.swift,
src/pro/ui/ProPromptHost.swift (surface only), src/pro/license/LicenseCookie.swift (ref only).