docs(readme): document Quick Look registration troubleshooting - #203
Merged
Conversation
The v0.31.1 sandbox fix ships correctly, but macOS does not always auto-register the Quick Look extension after install (for example when the app is still quarantined at first launch), so pressing Space renders no preview. Add a troubleshooting tip that registers the appex with pluginkit and refreshes the Quick Look cache. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documents a macOS Quick Look troubleshooting path for cases where the Quick Look extension isn’t registered after installation (e.g., quarantined first launch), even though the extension bundle/entitlements are correct.
Changes:
- Adds a README troubleshooting TIP under Installation for “Quick Look preview not showing?”
- Documents manual Quick Look extension registration via
pluginkitand cache refresh viaqlmanage.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The v0.31.1 sandbox fix (#202) reaches users' disks correctly — the embedded
ArtoQuickLook.appexcarries thenetwork.cliententitlement and non-persistentdata store. But the preview can still fail to appear because macOS does not always
register the Quick Look extension after install: when the app is still
quarantined at first launch (unsigned/ad-hoc build), PluginKit lists no match and
Space renders no preview — indistinguishable from the old "doesn't load" symptom.
Removing the quarantine alone does not register the extension; the app must be
launched, or the extension registered explicitly.
What
Add a
> [!TIP]troubleshooting note under Installation showing the manualrecovery steps (verified on macOS 26.5):
pluginkit -a /Applications/Arto.app/Contents/PlugIns/ArtoQuickLook.appex qlmanage -r && qlmanage -r cacheFramed as troubleshooting, not a required step — normal launch auto-registers it.
🤖 Generated with Claude Code