# Installing TransparentLock (Tester Build)

Thanks for testing TransparentLock — a transparent lock-screen replacement
for macOS that blocks all keyboard/mouse input but keeps the screen visible
so you can watch long-running processes.

This is an unsigned beta build, so macOS will warn you the first time you
open it. The steps below are the standard install flow for unsigned Mac
apps; you've probably done it before for other indie tools.

**Requirements:** macOS 14 (Sonoma) or later, Apple Silicon recommended.

---

## 1. Install the app

1. Download the `TransparentLock-*.zip` you were sent.
2. Double-click the zip to unpack it. You'll get `TransparentLock.app`.
3. Drag `TransparentLock.app` into your **Applications** folder.

## 2. First launch (one-time Gatekeeper approval)

Double-click `TransparentLock.app` in `/Applications`.

macOS will show a dialog:

> **"TransparentLock" cannot be opened because Apple cannot check it for
> malicious software.**

This is expected for any app that hasn't gone through Apple's paid
notarisation process. Click **Done** to dismiss it.

Then:

1. Open **System Settings** (⌘+space → "System Settings").
2. Go to **Privacy & Security**.
3. Scroll down to the **Security** section.
4. You'll see: *"TransparentLock was blocked from use because it is not
   from an identified developer."*
5. Click **Open Anyway**.
6. A confirmation dialog appears — click **Open**.
7. You may be asked for your Mac password to confirm.

The app is now trusted. From here on, you can just double-click it like
any other app.

## 3. Approve the helper as a Login Item

TransparentLock uses a small helper process to install the input-blocking
event tap. macOS will show a notification:

> **Background Item Added** — "TransparentLock" added an item that can
> run in the background.

To approve it:

1. Open **System Settings → General → Login Items & Extensions**.
2. Scroll to **"Allow in the Background"**.
3. Find **TransparentLock** in the list and toggle it **on**.

The TransparentLock menu-bar icon (a lock symbol) should now show a green
"Helper running" indicator when you click it.

## 4. Grant Accessibility & Input Monitoring (one-time)

To block input, the helper needs two macOS permissions. The app will tell
you which ones are missing via banners in the menu-bar popover.

**Important quirk:** the permissions are granted to the *helper* binary,
not the app itself. The macOS Privacy picker sometimes won't let you
select it from a file browser. TransparentLock works around this with a
**"Reveal Helper in Finder"** button:

1. Click the TransparentLock menu-bar icon.
2. If you see an orange banner like *"Helper needs Accessibility access"*,
   click **Reveal Helper in Finder**.
3. A Finder window opens, with a file named
   `com.molaga.TransparentLock.helper` highlighted.
4. Open **System Settings → Privacy & Security → Accessibility**.
5. Drag the highlighted file from Finder directly into the Accessibility
   list, then toggle it **on**.
6. Repeat the same drag for **Privacy & Security → Input Monitoring** if
   the app also prompts for that.

## 5. Use it

- **⌃⌘L** (Control+Command+L): lock the screen.
- While locked: type your Mac password or use Touch ID to unlock.
- **⌃⌘U** (Control+Command+U): unlock manually if needed.
- Click the menu-bar icon for **Lock Now**, settings, and helper status.

---

## What to report

If something doesn't work, please send back:

1. macOS version (Apple menu → About This Mac).
2. The exact step that failed.
3. The contents of the menu-bar popover (screenshot is great).
4. Helper logs, if you're comfortable with Terminal:
   ```
   log show --last 5m --predicate 'process == "com.molaga.TransparentLock.helper"' --info
   ```

Thanks!