diff --git a/README.md b/README.md index 3e3fb41..85de6b0 100644 --- a/README.md +++ b/README.md @@ -197,6 +197,10 @@ Screenshots show whatever was on screen, so look over a hand-off before sharing ## Get started +On first launch, choose **Check Access**, follow macOS's Screen Recording permission prompts, and relaunch if macOS asks. + +> **Screen Recording enabled but capture still denied:** follow the [step-by-step Screen Recording recovery guide](docs/troubleshooting.md#screen-recording-enabled-but-capture-still-fails). + 1. Open the app you’re working on, such as a local dev server in your browser. 2. In ContextLens, press ⌘N, choose that window under **Which window?**, and click **Start Capture**. 3. Use your app as usual: open the menu, reproduce the bug, walk through the flow. Click **Stop Capture** when you’re done. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 9a4a9eb..c63932b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -12,9 +12,41 @@ macOS blocks the first launch of these unnotarized builds. If you trust the down ## Permissions and capture -Grant Screen Recording in System Settings → Privacy & Security → Screen & System Audio Recording (named Screen Recording on older macOS). Approve the installed copy and relaunch when macOS asks. Optional Accessibility permission enables clicked-control labels; capture works without those labels. ContextLens does not request typed text, password values or audio. +### First-time Screen Recording setup -If Settings shows access enabled but no windows appear, confirm which app path is running and use **Check Access**. A changed development signature or a transition to Developer ID distribution can require fresh consent. Follow [permissions](permissions.md) for targeted manual recovery. No permission database is reset by a build or installation. +First-time users normally follow the standard macOS permission grant flow: + +1. Open your installed copy of ContextLens, normally `/Applications/ContextLens.app`. +2. In ContextLens's Capture panel, choose **Check Access** and respond to the macOS permission prompt. +3. Open **System Settings → Privacy & Security → Screen & System Audio Recording** (called **Screen Recording** on older macOS). Enable ContextLens in the **upper Screen & System Audio Recording list**. If it is missing, use **+ beneath that list** to add your installed app. +4. Follow any macOS **Quit & Reopen** request. Reopen the same installed copy and choose **Check Access** again, then select a window to capture. + +On macOS 26, the separate lower **System Audio Recording Only** list grants audio-only access. Enabling ContextLens there does not authorize window capture. Use the upper list for Screen Recording, even though ContextLens itself does not record audio. Optional Accessibility permission enables clicked-control labels; capture works without those labels, and ContextLens does not read typed text or password values. + +Normally, first-time setup ends after the standard grant and relaunch. Use the recovery procedure below only if access remains denied despite an enabled entry. + +### Screen Recording enabled but capture still fails + +This procedure successfully restored access in an observed macOS 26 case where ScreenCaptureKit returned permission denial **`-3801`** even though ContextLens was enabled in Settings. + +An ad-hoc-signed app update can change the identity that macOS previously approved, leaving an enabled entry that no longer authorizes the updated app. **This can happen even with only one ContextLens installation.** Multiple copies can make identifying the approved app harder, but are not required for this failure. The [technical permission and signing explanation](permissions.md#signing-and-upgrades) describes why. + +Reconnect the installed app manually: + +1. **Save your work and quit ContextLens fully** with **ContextLens → Quit ContextLens** or ⌘Q. Closing its window alone does not quit the app. If other ContextLens copies are open, quit those too. +2. Open **System Settings → Privacy & Security → Screen & System Audio Recording**. +3. In the **upper Screen & System Audio Recording list**, select **ContextLens** and click **−** to remove its entry. If ContextLens is absent from that list, continue to step 4. Remove **only ContextLens**; leave other apps and the separate **System Audio Recording Only** list unchanged. +4. Click **+ beneath the upper list**. In the file chooser, press ⌘⇧G, enter `/Applications`, and press Return. Select **ContextLens.app** and click **Open** to add `/Applications/ContextLens.app` again. +5. Confirm ContextLens is back in the **upper list** and turn its switch **on**. +6. Follow any macOS **Quit & Reopen** request. Otherwise, reopen `/Applications/ContextLens.app` from Finder. Use that same installed copy throughout the procedure. +7. Open ContextLens's Capture panel and choose **Check Access**. Access should be verified through ScreenCaptureKit. If the window list is empty after verification, open an application window and refresh. +8. Select a test window and start a short capture. Make a visible change, then stop and confirm a state appears in **Review**. + +The expected result is verified access and a working window capture; the Settings switch alone is not proof. Other API errors can have different causes. + +If access still fails, confirm the running app's path. Recent builds show **Running copy**, **Copy and signing details**, and **Show This Copy in Finder** beside the error. Note the app version/build, macOS version and exact error for a [bug report](https://github.com/Brendan-Lim/ContextLens/issues), keeping private logs and screen content local. See [permission diagnostics](permissions.md#interpret-the-apps-result) for the meanings of unverified, denied and failed checks. This procedure changes only ContextLens's permission entry; keep macOS security protections enabled. + +### Other capture issues If the selected window closes or becomes unavailable, start a new capture and explicitly choose a target. The recorder must not substitute a different window or the whole display.