Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,9 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the component breakdown and

## Getting started

deckd needs Python 3.11+ and Node 22+ (CI and the flox environment use Node 24 LTS). CI tests the 3.11 floor and the 3.12 interpreter the Nix package ships. In brief:
**On a Mac, without a toolchain:** download the DMG from the [releases](https://github.com/jonocodes/deckd/releases) and follow [macOS app: install](docs/GUIDE.md#macos-app-bundle-experimental-165). It needs **Accessibility** and **Automation → System Events** granted to `deckd.app` (otherwise the trackpad, scrolling, and shortcut buttons silently do nothing), and the grants need redoing after each upgrade until [#194](https://github.com/jonocodes/deckd/issues/194) lands.

**From a checkout:** deckd needs Python 3.11+ and Node 22+ (CI and the flox environment use Node 24 LTS). CI tests the 3.11 floor and the 3.12 interpreter the Nix package ships. In brief:

```sh
uv venv --python 3.11
Expand Down
72 changes: 58 additions & 14 deletions docs/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ endpoints see [REFERENCE.md](REFERENCE.md); for the system architecture see

- [Repository layout](#repository-layout)
- [Web-app decks](#web-app-decks)
- [Running deckd](#running-deckd) — install, macOS, KDE Plasma Wayland, phone/tablet testing
- [Running deckd](#running-deckd) — install, macOS ([app + permissions](#macos-app-bundle-experimental-165)), KDE Plasma Wayland, phone/tablet testing
- [Design tooling](#design-tooling-no-daemon-required), [hosted demo](#hosted-demo-github-pages), [PWA install](#pwa-install-over-https-tailscale)
- Client features — [chrome](#client-chrome), [manual control](#manual-control-mode), [deck editor](#deck-editor), [app badge](#chrome-app-badge), [app icons](#app-icons-source-desktop), [tuning](#client-tuning), [accessibility](#accessibility)
- [uinput permissions](#uinput-permissions), [live reload](#live-reload), [focus watcher](#focus-watcher), [dev UX](#dev-ux-auto-ignore--deck-override), [smoke test](#smoke-test), [CLI](#cli)
Expand Down Expand Up @@ -139,7 +139,7 @@ Machine-verified on hardware 2026-08-06 (macOS 15.6.1, Apple Silicon) by driving

**TCC permissions are per-process-tree, and that bites.** macOS attributes a grant to the *responsible* process — the terminal (or launchd agent) that started the daemon — not to `python` itself. Consequences worth knowing before you debug the wrong layer:

- **Accessibility** gates Quartz `CGEventPost` *and* the `AXRaise` half of raise. Without it, pointer/click/drag/scroll are **silently dropped** (no error, no log line) and `raise_window` fails with `kAXErrorAPIDisabled` (-25211) after the app has already been activated — so the app comes forward but the specific window doesn't rise.
- **Accessibility** gates Quartz `CGEventPost` *and* the `AXRaise` half of raise. Without it, pointer/click/drag/scroll are **silently dropped** (no per-event error; the daemon only logs one `Accessibility is not granted …` warning at startup) and `raise_window` fails with `kAXErrorAPIDisabled` (-25211) after the app has already been activated — so the app comes forward but the specific window doesn't rise.
- **System Events** (the focus + `keystroke` path) is a *separate* grant, which is why focus detection and key injection can work fine while every Quartz path is dead.
- Run the daemon from a *different* terminal (or under an editor/agent harness) and you inherit that tree's grants, not the ones you clicked through earlier.
- **Screen Recording** gates `kCGWindowName`. Without it every enumerated window's `title` is `None`, so the running-windows list is labelled by app name alone. deckd works either way — the label falls back — but title-based deck matching (`title:` tokens) can't see enumerated windows.
Expand Down Expand Up @@ -675,31 +675,75 @@ tail -f deckd.log # follow logs (written in the checkout)

### macOS app bundle (experimental, [#165](https://github.com/jonocodes/deckd/issues/165))

Beyond the source-checkout + LaunchAgent path above, deckd can be built as a self-contained `deckd.app`: a private Python runtime, the built client, and the decks in one bundle, driven by a menu-bar UI. The target Mac needs no Python, Node, or Homebrew. Build it **on a Mac** (a `.app` needs Apple tooling):
Beyond the source-checkout + LaunchAgent path above, deckd ships as a self-contained `deckd.app`: a private Python runtime, the built client, and the decks in one bundle, driven by a menu-bar UI. The target Mac needs no Python, Node, or Homebrew. Apple Silicon only for now.

#### Install

1. Download `deckd-<version>.dmg` from the [GitHub releases](https://github.com/jonocodes/deckd/releases) and drag **deckd** into **Applications**.
2. The bundle is **ad-hoc signed, not notarized** (no paid Apple Developer Program; see [#194](https://github.com/jonocodes/deckd/issues/194)), so Gatekeeper blocks the first launch of a browser download. Right-click → **Open**, or:

```sh
xattr -dr com.apple.quarantine /Applications/deckd.app
```

3. Launch it. deckd runs as a menu-bar app (no Dock icon), seeds decks into `~/Library/Application Support/deckd/decks`, logs to `~/Library/Logs/deckd.log`, and serves the surface on `http://127.0.0.1:8765`. The password for the surface is in `~/.config/deckd/password`.
4. **Grant permissions** (next section). Without them deckd *looks* half-working, with no error on the phone. Missing Accessibility is the sneaky one: decks still follow the focused app, but the trackpad, scroll strip, and every keyboard-shortcut button silently do nothing.
5. **Allow LAN access** to use it from a phone or tablet (below).

#### Grant permissions

Grants belong to `deckd.app` itself, in System Settings → **Privacy & Security**:

| permission | what breaks without it | how to grant |
| --- | --- | --- |
| **Accessibility** | trackpad pointer, click, drag, scroll strip, keyboard-shortcut buttons (System Events refuses to type for an app without it), raising a specific window | Not prompted. Open **Accessibility**, click **+** under the list, pick `/Applications/deckd.app`, make sure its toggle is on. **Then restart deckd** (menu → Restart server, or quit and relaunch): it checks the grant at startup. |
| **Automation → System Events** | following the focused app (decks don't switch), keyboard-shortcut buttons (e.g. Firefox **New window** sends ⌘N) | Prompted shortly after launch, the first time deckd checks which app is focused: *"deckd wants access to control System Events"* → **Allow**. If you clicked Don't Allow, turn it on under **Automation → deckd → System Events**. |
| **Screen Recording** *(optional)* | window titles in the running-windows list (labels fall back to the app name) and `title:` deck matching on enumerated windows | Open **Screen Recording**, add `deckd.app`. |

To check, look for these lines in `~/Library/Logs/deckd.log` after a restart. A clean start has none of them:

- `Accessibility is not granted to deckd.app` → Accessibility missing (or granted to a previous build, see *Upgrading*).
- `osascript is not allowed to send keystrokes (1002)` → Accessibility missing.
- `Not authorized to send Apple events to System Events. (-1743)` → Automation missing.

The client doesn't show these yet; that's [#195](https://github.com/jonocodes/deckd/issues/195).

#### LAN access

The app is localhost-only until you enable **Allow LAN access** in its menu; it then listens on all interfaces and the surface is at `http://<your-mac>.local:8765` (or the Mac's hostname / IP). The choice is remembered across quits, reboots, and upgrades. You can also set it without the menu bar, which helps if macOS isn't showing the icon ([#200](https://github.com/jonocodes/deckd/issues/200)):

```sh
just build-macos-app # -> dist/deckd.app
just build-macos-dmg # -> dist/deckd-<version>.dmg
defaults write com.deckd.daemon AllowLAN -bool true # LAN on (false or `defaults delete com.deckd.daemon AllowLAN` for localhost-only)
osascript -e 'quit app id "com.deckd.daemon"'; open -a deckd # relaunch to apply
```

The bundle is **ad-hoc signed, not notarized** (no paid Apple Developer Program). A DMG downloaded through a browser is quarantined by Gatekeeper, so the first launch needs either right-click → Open, or:
The menu offers Open surface / Open decks folder / Restart server / Allow LAN access / Quit. Opening deckd.app again while it's already running (Finder, Spotlight, `open -a deckd`) opens the surface in your browser, so the app stays reachable even with no menu-bar icon. Without the menu, restart it with the `osascript … quit` / `open -a deckd` pair above.

#### Upgrading

Because the bundle is ad-hoc signed, macOS identifies it by its content hash: **every new build looks like a different app, and the old Accessibility / Automation grants stop applying**, without any prompt ([#194](https://github.com/jonocodes/deckd/issues/194)). The symptom after an upgrade is the same as never granting, typically decks still switching while the trackpad, scroll strip, and shortcut buttons do nothing. The toggle in System Settings may still show *on*, for the old build.

Clear deckd's stale entries (this only touches deckd's grants), then grant again as above and restart deckd:

```sh
xattr -dr com.apple.quarantine /Applications/deckd.app
tccutil reset Accessibility com.deckd.daemon
tccutil reset AppleEvents com.deckd.daemon
```

Then grant the TCC permissions as for the source build (see [macOS](#macos) above): Accessibility, System Events, and — for window titles — Screen Recording. The app seeds decks into `~/Library/Application Support/deckd/decks` on first run and logs to `~/Library/Logs/deckd.log`. The menu offers Open surface / Open decks folder / Restart server / Allow LAN access / Quit; it stays localhost-only until you enable LAN access. The **Allow LAN access** choice is remembered across quits, reboots, and upgrades. You can also set it without the menu bar, which helps if macOS isn't showing the icon:
(In System Settings you can instead select the `deckd` row by its name, not its toggle, and press **−** under the list.) Decks, the password, and the LAN setting survive an upgrade.

#### Building it yourself

Build **on a Mac** (a `.app` needs Apple tooling):

```sh
defaults write com.deckd.daemon AllowLAN -bool true # LAN on (false or `defaults delete com.deckd.daemon AllowLAN` for localhost-only)
osascript -e 'quit app id "com.deckd.daemon"'; open -a deckd # relaunch to apply
just build-macos-app # -> dist/deckd.app
just build-macos-dmg # -> dist/deckd-<version>.dmg
```

Opening deckd.app again while it's already running (Finder, Spotlight, `open -a deckd`) opens the surface in your browser, so the app stays reachable even with no menu-bar icon.

Because the bundle is ad-hoc signed, its code identity is its content hash: **every rebuild changes it, so macOS may ask you to re-grant Accessibility / System Events after an upgrade.** Remove the stale `deckd` entry from System Settings → Privacy & Security and re-add the app if a grant stops working.
A local build is a new identity too, so running it means granting permissions to `dist/deckd.app` (and again after every rebuild).

Verified so far (macOS 26.6.2, Apple Silicon): the bundle builds, launches as a menu-bar app, seeds decks, and serves the surface on `127.0.0.1:8765` with logs in `~/Library/Logs/deckd.log`. The injected-input features still depend on the three TCC grants, which need a human on the target Mac to confirm — the same caveat as the source build.
Verified on hardware (macOS 26.6.2, Apple Silicon, 2026-11-18): installed from the release DMG and driven from a phone over LAN, focus-following deck switching, the trackpad, the scroll strip, and keyboard-shortcut buttons all worked once Accessibility and Automation were granted to `deckd.app`, and none of them (except deck switching) did before.

#### Releasing a DMG

Expand Down
2 changes: 2 additions & 0 deletions site/shared/content.js
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,8 @@ const FAQ = [
"With the editor in the app: pick widgets, set icons and colours, drag to reorder, save. Every screen updates as you go. Decks are plain text files too, if you'd rather."],
["What can a button do?",
"Press a key combination, run a command, open a URL, start a terminal, call D-Bus — or chain several into a macro."],
["On my Mac the decks switch, but buttons and the trackpad do nothing. Why?",
`deckd is missing the Accessibility permission, or still has it from an older version: macOS treats every upgrade as a new app until deckd is properly signed (<a href="${GH}/issues/194">#194</a>). Re-add deckd under System Settings → Privacy &amp; Security → Accessibility and reopen it. The <a href="${GH}/blob/main/docs/GUIDE.md#grant-permissions">guide</a> has the steps.`],
];
function faq(root) {
root.append(el(`<div class="dk-faq">${FAQ.map(([q, a]) => `<details><summary>${q}</summary><p>${a}</p></details>`).join("")}</div>`));
Expand Down
7 changes: 4 additions & 3 deletions site/shared/scenes.js
Original file line number Diff line number Diff line change
Expand Up @@ -267,9 +267,10 @@ const INSTALL = {
macOS: `<ol>
<li><a class="dl" href="${REL}">Download the DMG</a><span class="note">Apple Silicon</span></li>
<li>Drag deckd to Applications. It isn't notarized yet, so open it the first time with right-click → Open.</li>
<li>Allow Accessibility when asked, then pick <b>Allow LAN access</b> from the menu-bar icon.</li>
<li>Open the address on your phone.</li></ol>
<p class="note">Now playing and D-Bus actions are Linux-only for now.</p>`,
<li>When macOS asks if deckd may control <b>System Events</b>, click Allow. That's how it sees the focused app and sends shortcuts.</li>
<li>macOS won't ask for this one: in System Settings → Privacy &amp; Security → <b>Accessibility</b>, add deckd with <b>+</b>, then quit and reopen it. Without it the decks switch, but the trackpad, scrolling and shortcuts do nothing.</li>
<li>Pick <b>Allow LAN access</b> from the menu-bar icon and open <code>http://&lt;your-mac&gt;.local:8765</code> on your phone. The password is in <code>~/.config/deckd/password</code>.</li></ol>
<p class="note">After an upgrade, macOS treats deckd as a new app, so grant Accessibility again (<a href="https://github.com/jonocodes/deckd/blob/main/docs/GUIDE.md#upgrading">how</a>). Now playing and D-Bus actions are Linux-only for now.</p>`,
"From source": `<pre>git clone https://github.com/jonocodes/deckd && cd deckd
uv venv --python 3.11 && uv pip install -e ".[uinput,dbus]"
(cd client && npm install) && just build-client
Expand Down
Loading