Skip to content

fix(macos): recover stuck Accessibility onboarding#746

Merged
appergb merged 1 commit into
betafrom
fix/macos-accessibility-onboarding-stuck
Jun 25, 2026
Merged

fix(macos): recover stuck Accessibility onboarding#746
appergb merged 1 commit into
betafrom
fix/macos-accessibility-onboarding-stuck

Conversation

@appergb

@appergb appergb commented Jun 25, 2026

Copy link
Copy Markdown
Collaborator

User description

Summary

  • stop requesting macOS Accessibility during Tauri setup so the first TCC prompt is only triggered from the user-facing onboarding action
  • distinguish first prompt from already-denied TCC state, and avoid opening System Settings when the prompt returns granted
  • add a dedicated stuck-state recovery action that runs a targeted Accessibility TCC reset for com.openless.app, then restarts OpenLess
  • keep the normal updater restart path separate; beta restart still resets TCC for ad-hoc identity refresh
  • mirror the recovery action in Settings > Permissions and update i18n labels

Why

Users reported macOS onboarding staying on the OpenLess authorization page even after granting Accessibility, and manual remove/re-grant could still leave System Settings checked while AXIsProcessTrusted() returned false. That points to a TCC/app identity recovery problem, not just a missing UI refresh.

This PR keeps the prompt aligned with Apple’s expected user-initiated permission flow and gives stuck users an in-app reset path for the current bundle id.

Verification

  • npm run build
  • npx tsc --noEmit --pretty false
  • cargo check --manifest-path openless-all/app/src-tauri/Cargo.toml

Note: cargo fmt --check currently reports existing repository-wide formatting differences unrelated to this PR, so I did not format unrelated files.


PR Type

Bug fix, Enhancement


Description

  • Remove early startup TCC prompt to prevent stuck onboarding

  • Add dedicated Accessibility reset + restart command for stuck state recovery

  • Update UI to distinguish first prompt from denied state

  • Add i18n labels for reset action


Diagram Walkthrough

flowchart LR
    A[App start] --> B[Onboarding page]
    B --> C{Accessibility status}
    C -- notDetermined --> D[Show "Grant" button]
    D --> E[User clicks Grant]
    E --> F{TCC dialog result}
    F -- granted --> G[Continue onboarding]
    F -- denied --> H[Show "Open System Settings"]
    H --> I[User may become stuck]
    C -- denied --> J[Check if prompt already shown?]
    J -- yes --> K[Show "Reset & Restart" button]
    K --> L[Reset TCC and restart app]
Loading

File Walkthrough

Relevant files
Bug fix
2 files
lib.rs
Remove early TCC prompt and add reset+restart command       
+34/-16 
PermissionsSection.tsx
Update permissions section to show reset button when denied
+13/-3   
Enhancement
3 files
Onboarding.tsx
Update onboarding to handle permission states and add restart button
+54/-23 
index.ts
Export new reset method from IPC module                                   
+1/-0     
permissions.ts
Add IPC function for resetting accessibility and restarting
+8/-0     
Documentation
5 files
en.ts
Add English i18n keys for reset action                                     
+2/-0     
ja.ts
Add Japanese i18n keys for reset action                                   
+2/-0     
ko.ts
Add Korean i18n keys for reset action                                       
+2/-0     
zh-CN.ts
Add Simplified Chinese i18n keys for reset action               
+2/-0     
zh-TW.ts
Add Traditional Chinese i18n keys for reset action             
+2/-0     

…ollow-up)

Root cause: permissions::request_accessibility() was called in setup(),
which runs BEFORE the AppKit event loop is live. On some macOS versions,
AXIsProcessTrustedWithOptions depends on the run loop for XPC to tccd.
When the event loop isn't ready, TCC may not show the dialog but still
consumes the one-time prompt. Later calls from the onboarding page's
'grant accessibility' button silently return Denied, trapping users on
the onboarding page. Recovery requires System Settings grant + app
restart, but users had no clear restart action — only a text hint.

Changes:

- lib.rs: Remove setup() TCC prompt. The prompt is now exclusively
  triggered by user action on the onboarding page, aligning with
  Apple HIG (explain why → then prompt).

- Onboarding.tsx:
  * onGrantAccessibility now checks the TCC result: skip
    openSystemSettings when already granted (previously always opened)
  * New tccPromptShown state distinguishes 'never attempted' vs
    'already denied' for correct button labels
  * Denied state now shows a prominent 'Restart OpenLess' button
    calling restartApp()

- PermissionsSection.tsx: Same fix for settings page accessibility
  row — check TCC result, guide to System Settings when denied,
  show 'Restart App' button

- i18n: Add onboarding.actionRestart + settings.permissions.restart
  for zh-CN / zh-TW / en / ja / ko

Closes: macos-onboarding-accessibility-stuck
@github-actions

Copy link
Copy Markdown
Contributor

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ No major issues detected

@appergb appergb merged commit 124a49c into beta Jun 25, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant