gKeyMapper/docs/daemon-plan.md

# gKeyMapper daemon — implementation plan

Status: implemented (M0–M4 done, see "Implementation status")
Scope: a native C/C++ background service that detects G1–G9 (and later M1–M3/MR
and media keys) on the Logitech G910 and replays the mappings stored by the GUI.

## Implementation status

- **M0 done** — `shared/mapping.{h,cpp}` (file format + shortcut parsing) and
  `shared/keys.{h,cpp}` (canonical names → Linux codes); the GUI uses them.
  Round-trip and shortcut parsing are covered by a small standalone test.
- **M1 done** — `daemon/` builds (`gkeymapper-daemon`): device discovery,
  kernel-driver detach, F-key binding disable, 64-byte interrupt reads and G1–G9
  decoding. Verified on hardware: all nine keys decode correctly (press and
  release), in order.
- **M2 done** — action execution: `key` shortcuts are replayed through a
  `/dev/uinput` virtual keyboard, `command` runs via fork/exec (with a shell
  fallback so arguments work), `disabled` does nothing. Verified on hardware.
- **M3 done** — config watching and lifecycle: `daemon/config_watch` watches the
  config *directory* with inotify, so a save in the GUI reloads within about
  half a second; `SIGHUP`/`SIGUSR1` stay as the fallback. `Save mappings` now
  writes atomically (temp file + `rename`), so the daemon never reads a
  half-written file. `make install` ships the udev rule, the `modules-load.d`
  fragment and the systemd **user** unit (`data/`).
- **Layout handling (added during M2)** — key names are resolved through the
  active layout (`XKBLAYOUT` from `/etc/default/keyboard`, via xkbcommon). This
  matters because the US-position code `KEY_Z` (44) is `y` on a German keyboard;
  `z` is now correctly resolved to evdev 21.
- **AltGr (added after M2)** — level-3 combinations are representable as
  `altgr+7`; the base (level 0) key is stored plus the `altgr` modifier.
- **M4 done** — D-Bus control channel: `daemon/ipc_dbus` registers
  `dev.rager.gkeymapper.Daemon` on the session bus and serves `Reload`,
  `GetStatus` and `TestMapping`, plus the `KeyPressed`, `ConfigReloaded` and
  `DeviceChanged` signals. `src/daemonclient.{h,cpp}` is the GUI side: the footer
  shows `Daemon: running/not reachable`, the device and the last G key that
  fired, and `Save mappings` calls `Reload()` (the file watch stays the
  backstop). `make install` ships a D-Bus activation file, so the GUI can start
  the daemon on demand; the unit is `Type=dbus` with `BusName=`. A second
  instance refuses to start instead of fighting over the keyboard. Verified with
  `gdbus` (methods, signals, activation) and over AT-SPI (live footer).

## 1. Goals and non-goals

Goals
- Detect G-key presses in C/C++ and execute the configured action.
- Run with a very small, stable resource footprint (idle ≈ 0 % CPU, few MB RSS,
  no interpreter, no polling when nothing happens).
- Reuse the existing `mappings.conf` format as the single source of truth.
- Let the GUI and the daemon run independently; either can start first.
- No Python at runtime.

Non-goals (v1)
- Profiles (M1–M3/MR), per-locale text typing (`typeout`), embedded scripting.
- GUI redesign beyond a status indicator / reload / test button.

## 2. What the Python reference does (and what we keep)

Reference: <https://github.com/JSubelj/g910-gkey-macro-support>

- G-keys are **not** exposed as distinct evdev key codes. The driver therefore
  opens the keyboard's **vendor HID interface (USB interface 1) directly via
  libusb**, detaches the kernel driver from that interface, and reads raw
  interrupt-IN reports.
- On start it sends a control transfer to **disable the firmware F-key→G-key
  binding**, so pressing G1..G9 no longer also emits F1..F9 on the normal
  keyboard interface.
- Raw report byte patterns are looked up in tables
  (`events.macroKeys`, `memoryKeys`, `mediaKeys`, `releaseEvents`) and turned
  into actions.
- A **uinput virtual keyboard** replays `shortcut` (press, later release),
  `typeout` (per-char), `uinput` (direct `KEY_*`); `run` uses `/bin/bash -c`.
- Config is JSON at `~/.config/g910-gkeys/config.json`, reloaded on directory
  change (inotify via `fcntl`), plus `SIGUSR1` reload.
- Ship: a **systemd --user** service and **udev rules** with `TAG+="uaccess"` for
  the device and `/dev/uinput`, so no root is needed.

Relevant USB IDs (from the udev rules): `046d:c335`, `c33f`, `c33e`, `c32b`,
`c24d`, `c22d`. The G910 in this project is `046d:c32b`.

What we keep: libusb raw HID access, disabling the F-key binding, uinput output,
config-dir watching. What we change: JSON→our line format, single-threaded
event-driven loop instead of a Python loop with fixed sleeps, fork/exec reaping,
and a real IPC channel to the GUI.

## 3. Architecture overview

```
+---------------------+        mappings.conf (shared truth)      +----------------------+
|  gkeymapper (GUI)   | <------------ write / inotify ---------> |  gkeymapper-daemon   |
|  GTK4 + GIO/GDBus   |                                          |  libusb + uinput     |
|                     | <===== D-Bus (session bus) ============> |  GDBus + inotify     |
+---------------------+        status / reload / events          +----------+-----------+
                                                                            | raw HID (iface 1)
                                                                            v
                                                                  +----------------------+
                                                                  | Logitech G910        |
                                                                  +----------+-----------+
                                                                             | uinput
                                                                             v
                                                                  +----------------------+
                                                                  | /dev/uinput keyboard |
                                                                  +----------------------+
```

Key property: the **hot path never crosses IPC**. G-key press → decode → uinput
happens entirely inside the daemon. IPC (D-Bus) is only used for control, status
and notifications, so a slow/absent GUI never delays a keypress.

## 4. Daemon design

### 4.1 Process model
- One process, single-threaded, event loop.
- No threads in v1. `run`/`command` actions are launched with `fork()` +
  `execve()`; children are reaped via a `SIGCHLD`/`signalfd` handler so no
  zombies accumulate (the reference leaks a `Popen` per invocation).
- `python` type is intentionally dropped.

### 4.2 Event loop
Use one `poll()`/`epoll()` loop over:
- the **libusb** file descriptor (from `libusb_get_pollfds()`; use libusb's async
  API or `libusb_interrupt_transfer` on a worker, see below),
- an **inotify** fd for the config file/directory,
- a **signalfd** for `SIGTERM`/`SIGINT`/`SIGUSR1`,
- the **D-Bus** connection (GDBus integrates with the same `GMainContext`).

Preferred: drive libusb asynchronously with `libusb_submit_transfer()` and fold
the reported poll fds into the same loop (libusb has an official "poll with
another event loop" pattern). That yields exactly **0 wakeups while idle**
(excluding the kernel's own HID interrupts). If that is too much work for v1,
fall back to a blocking `libusb_interrupt_transfer(..., timeout=1000)` inside a
dedicated thread that posts events into the main loop — still cheap (1 wake/s).

To keep GDBus and the fd loop together, the loop is easiest on the **GLib main
loop** (`GMainLoop`): GDBus, `GFileMonitor` and `GSocket`/`GSource` cover
inotify and signalfd, and libusb poll fds can be wrapped in a custom
`GSource`. GLib is already a dependency of the GUI, so this adds no new library.
If minimal footprint is the priority over convenience, a raw `epoll` loop is the
alternative; decision point in §11.

### 4.3 Device layer (`libusb`)
- Find the device by vendor/product from the supported-device table; pick
  interface 1, endpoint from the same table.
- `libusb_detach_kernel_driver()` on interface 1; remember to
  `libusb_attach_kernel_driver()` on shutdown (reference does this).
- Send the "disable F-key to G-key binding" control transfer
  (`bmRequestType=0x21, bRequest=0x09, wValue=0x0212, wIndex=1`) and consume the
  confirmation reports; ignore the known LED-return patterns
  (`\x11\xff\x0f`, `\x11\xff\x10`, `\x11\xff\xff`).
- Hot-plug / re-plug: on `LIBUSB_ERROR_NO_DEVICE`/`IO` re-run discovery with a
  small backoff (reference re-inits in place).
- Optional (later): `libusb_hotplug_register_callback` to react to device
  add/remove without polling.

The device table in `supported_devices.py` (byte patterns per model) is ported
to a generated C++ header (`constexpr` tables) — keep it a build-time
artifact so the runtime does zero parsing.

### 4.4 Decoding
- The report is a fixed-length byte blob. Build a **compile-time lookup**:
  a sorted array of `{report bytes, action id}` with binary search, or a small
  open-addressed hash keyed on the first 8 bytes. This replaces the Python
  `dict` + `list(...).index()` O(n) scans with O(1)/O(log n) and no allocation.
- Categories: `macro` (G1..G9), `memory` (profiles, later), `media` (later),
  `release` (stops a held shortcut), and ignored/known-noise.

### 4.5 Action layer (uinput)
- Open `/dev/uinput` once; `UI_SET_EVBIT` for `EV_KEY`, register the key set used
  by the mappings, `UI_DEV_CREATE`. Keep the fd for the daemon's lifetime.
- Emit events by `write()`-ing `struct input_event` (from
  `<linux/uinput.h>` / `<linux/input-event-codes.h>` — no libevdev needed).
- `key` mapping = shortcut grammar `ctrl+c,ctrl+v`:
  - single combo: press modifiers+key in order, remember the keys, release them
    when the keyboard's `release` event arrives (mirror the reference's
    `press_release_fifo` stack).
  - comma list: `emit_combo()` each group (press+release).
- `command` mapping: `fork()`; in the child `setsid()`, redirect stdio to
  `/dev/null`, `execve("/bin/sh", "-c", cmd)`. Reap via `SIGCHLD`.
- `disabled`: no-op.
- Give the uinput device a clear name/IDs (e.g. `gkeymapper virtual keyboard`)
  so `libinput`/users can identify it.

### 4.6 Config
- Parse the existing `mappings.conf`:
  `G<n>=<type>:<target>` with `type ∈ {key, command, disabled}`.
- Parse at load and on change only; the runtime holds a small pre-parsed action
  per G-key (enum + fixed target buffer / `std::string`), so no parsing in the
  hot path.
- Watch the config file (and, for atomic-save editors, its directory) with
  inotify/`GFileMonitor`; reload on `IN_CLOSE_WRITE`/`IN_MOVED_TO`. Debounce
  (e.g. 100 ms) to coalesce editor save bursts.
- Also reload on `SIGUSR1` (manual/test) and on `Reload()` D-Bus call.

### 4.7 Privileges and packaging
- udev rule with `TAG+="uaccess"` for the supported USB IDs and for
  `KERNEL=="uinput"` (mirrors the reference's `60-g910-gkeys.rules`).
- `uinput` kernel module must be present; ship `/etc/modules-load.d/` fragment
  or document `modprobe uinput` (here it is built in).
- **systemd --user** unit `gkeymapper-daemon.service`:
  `Type=dbus`, `BusName=dev.rager.gkeymapper.Daemon`,
  `ExecStart=gkeymapper-daemon`, `Restart=on-failure`, `ExecReload=SIGHUP`.
  `Type=dbus` + `BusName` make the unit count as started only once the name is
  owned — the state D-Bus activation and the GUI see. `make install` also ships
  the D-Bus activation file
  (`share/dbus-1/services/dev.rager.gkeymapper.Daemon.service`, with
  `SystemdService=gkeymapper-daemon.service`), so the bus starts the unit when
  the GUI asks for the daemon's status and the daemon runs exactly once either
  way.
- Do **not** require root. Commands run with the user's privileges (the
  reference's "executed as root" note is a wiki artifact, not a design goal).

## 5. GUI ↔ daemon interaction

Three layers, from loosest to tightest:

1. **Shared state = the config file** (`~/.config/gKeyMapper/mappings.conf`).
   The GUI is the writer, the daemon is a watcher/reader. This alone is enough
   for basic operation and is robust: whichever side starts first, the other
   converges. The daemon reloads via inotify; no coupling to the GUI process.
2. **Control/status = D-Bus on the session bus** (GDBus; part of GIO, already
   linked by the GUI). Used for status, explicit reload, and notifications.
3. **Lifecycle**: the daemon is a `systemd --user` service; the GUI can start it
   implicitly by calling a D-Bus method (activation) and can show whether it is
   running.

### 5.1 D-Bus interface (implemented)

- App id: `dev.rager.gkeymapper` (replaces the placeholder `com.example.gkeymapper`);
  it is also the GApplication id.
- Bus name: `dev.rager.gkeymapper.Daemon` — **not** the plain app id.
  `GtkApplication` owns the app id itself, in order to detect a second GUI
  instance; a daemon on the same name would make every GUI start look like a
  duplicate and exit. (The original plan had `<app-id>` here; that clash was
  found while implementing M4.)
- Object path: `/dev/rager/gkeymapper/Daemon`
- Interface: `dev.rager.gkeymapper.Daemon`

Methods
| Method | Signature | Purpose |
|---|---|---|
| `Reload` | `() -> ()` | Re-read `mappings.conf` now (GUI "Save" also calls this). Result via the `ConfigReloaded` signal. |
| `GetStatus` | `() -> (s version, b running, s device, s configPath)` | Status for the GUI footer/indicator. `device` is `""` before the keyboard is open, so the GUI can omit that part. |
| `TestMapping` | `(u index) -> ()` | Fire the mapping of one G key without hardware; same code path as a real press. `index` is **0-based** (`0` = G1 … `8` = G9). Fails with a D-Bus error for an out-of-range index or a `disabled:`/empty row. |

Signals
| Signal | Signature | Purpose |
|---|---|---|
| `KeyPressed` | `(u index, s action)` | A G-key fired (GUI highlight/history; also emitted by `TestMapping`). |
| `ConfigReloaded` | `(b ok)` | Daemon finished reloading. |
| `DeviceChanged` | `(b present, s device)` | Keyboard attached/detached. |

Notes
- All are control-plane calls; none is on the keypress path. `DaemonService::pump()`
  dispatches once per daemon loop iteration, so a reply can take up to one read
  timeout (≤500 ms) — fine for status/reload, and the GUI calls asynchronously.
- `Reload` is best-effort: inotify is the backstop if the call is lost.
- If D-Bus is unavailable, the daemon still works; the GUI degrades to
  "no status" and "save only". Signals `SIGUSR1` (reload) / `SIGTERM` remain for
  scripted use, matching the reference.
- `SetProfile` was dropped: it is reserved for the M-key profiles and would have
  been a no-op today.
- The daemon requests its name with `DO_NOT_QUEUE` and exits (code 0, with a
  message) when another instance owns it, before it touches the device.

### 5.2 Interaction sequences

Save in the GUI:
```
GUI: write mappings.conf (atomic: temp + rename)
GUI: call Daemon.Reload()   [optional, for immediacy]
Daemon: inotify IN_MOVED_TO -> (re)parse -> apply
Daemon: emit ConfigReloaded(ok)
```

Key press:
```
G910 --raw HID--> Daemon -> decode -> uinput emit / fork+exec
Daemon: emit KeyPressed(index, action)   [GUI only, non-blocking]
```

Start-up orders:
- Daemon first, GUI later: GUI reads status via D-Bus; no config write needed.
- GUI first, daemon later: GUI writes config; on daemon start it reads the file.

### 5.3 GUI-side changes (as implemented)
- On "Save mappings": writes the file, then calls `Reload()` best-effort; the
  file watch is the backstop, so a lost call is harmless (a save therefore
  triggers two reloads, both idempotent).
- Footer status line: `Daemon: running/not reachable` + `Device: …` + the last G
  key that fired, fed by `GetStatus`, the `DeviceChanged`/`ConfigReloaded`
  signals and `NameOwnerChanged` (so it follows the daemon starting/stopping).
  The `Device:` part is omitted while the device is not open yet.
- No "Test" button per row: pressing the real key is the better test while the
  hardware is at hand, and `TestMapping` stays available over `gdbus`/`busctl`
  without widening the fixed-width rows.
- The key-name vocabulary matches because the capture dialog already writes
  lowercase GDK key names and the canonical list lives in `shared/keys` (§6).

## 6. Code layout

```
src/                     # GUI (existing)
  daemonclient.{h,cpp}   # D-Bus client (status/reload/signals)
daemon/                  # as implemented (see §6 above)
  ipc_dbus.{h,cpp}       # GDBus service (control plane)
shared/
  mapping.{h,cpp}        # parse/format mappings.conf (used by GUI and daemon)
  keys.{h,cpp}           # canonical names <-> gdk keyval <-> linux KEY_*
  keymap.{h,cpp}         # layout-aware name <-> input code (xkbcommon)
  ipc_ids.h              # app id, version, D-Bus names
data/
  60-gkeymapper.rules    # udev: uaccess for the device and /dev/uinput
  gkeymapper-uinput.conf # modules-load.d fragment (uinput)
  gkeymapper-daemon.service # systemd user unit (@BINDIR@ filled in on install)
  dev.rager.gkeymapper.Daemon.service # D-Bus activation for the same unit
  icons.gresource.xml    # GUI icons compiled into the binary (GResource)
po/                      # shared catalogs (GUI strings)
```

Build: the Makefile gets a second target `gkeymapper-daemon` and install rules
for the unit, udev rule, modules-load fragment and activation file. New build
dependency: `libusb-1.0-0-dev` plus `libglib2.0-dev` (gio-2.0) for the daemon's
D-Bus channel.

## 7. Resource-efficiency measures (summary)

- No Python interpreter; native binary, tables in `.rodata`.
- Event-driven loop, **no idle polling** (libusb async + inotify + signalfd; or a
  1 s blocking USB read in the simple variant).
- O(1)/O(log n) decode via compile-time tables instead of dict/linear scan.
- One `uinput` fd for the process lifetime; fixed-size event writes; no
  per-event heap allocation.
- Config parsed only on load/reload; hot path is table lookups + `write()`.
- `fork`+`exec` for programs, children reaped (no zombies), stdio to `/dev/null`;
  no shell parsing for `key`/`uinput` actions.
- Target footprint: idle 0 % CPU, wakeups only on real HID/DBus/file events,
  RSS in the low single-digit MB.

Measured after M4 (systemd user unit, daemon idle): ~780 KB RSS, 14 ms CPU
since start. The D-Bus control channel adds no wakeups of its own: `pump()`
only dispatches what the loop's read timeout already woke up for.

## 8. Milestones

- **M0 – Shared core.** `shared/mapping` + `shared/keys`; refactor the GUI to use
  them (still file-only). Unit tests for parse/format and key tables.
- **M1 – Device bring-up.** `daemon` opens the G910 via libusb, disables the
  F-key binding, logs `G1..G9` presses. No output yet.
- **M2 – Action layer.** uinput keyboard; `key` (shortcut, incl. release) and
  `command` work end-to-end. `disabled` no-op.
- **M3 – Config & lifecycle (done).** config reload via inotify (`config_watch`,
  directory watch + atomic save) and `SIGHUP`/`SIGUSR1`; systemd --user unit +
  udev rule + modules-load, installed by `make install`.
- **M4 – IPC (done).** GDBus service (`Reload`, `GetStatus`, `TestMapping`,
  signals); GUI status line + Reload-on-save; D-Bus activation file; unit
  `Type=dbus` + `BusName`; single-instance guard.
- **M5 – Polish.** Packaging/install rules, docs, translations, hardening
  (hot-plug, debounce, error reporting to the GUI).

## 9. Testing strategy

- Unit: mapping parser round-trip, key-name tables, decoder against recorded
  byte sequences from the reference tables.
- Device: replay captured reports into the decoder (no hardware needed).
- Integration: `evtest` / `libinput debug-events` to observe the virtual device;
  compare `xev` output for a configured shortcut between reference and daemon.
- D-Bus (M4): `gdbus call` for `GetStatus`/`Reload`/`TestMapping`,
  `gdbus monitor` for the signals, and a `TestMapping` observed with
  `xinput test <keyboard-id>` to confirm the emitted keycodes. The GUI's footer
  line is read back over AT-SPI to check the live status.
- Permission tests: verify the udev rule grants access as a normal user.
- Resource check: `powertop`/`perf` or simple wakeup counting while idle.

## 10. Risks / open points

- **Device table size**: `supported_devices.py` is large; porting/generating the
  byte tables is real work and model-specific.
- **Interface detach** may momentarily disturb the device; must re-attach on
  exit and handle crashes gracefully.
- **Permissions**: relies on `TAG+="uaccess"` + a user service; must never fall
  back to requiring root silently.
- **`command` environment**: `DISPLAY`/`WAYLAND_DISPLAY`/`XAUTHORITY` and
  `PATH` differ between a user service and an interactive shell; decide whether
  to inherit the user manager environment (`systemd --user` import-environment)
  or document `run` snippets setting `DISPLAY=:0` explicitly.
- **Key-name vocabulary drift** between GUI (GDK names) and daemon (Linux KEY_*)
  is the most likely source of silent mismatches — that is why the shared table
  in M0 is mandatory before the daemon consumes the file.
- **uinput device identity**: a second keyboard appears; choose stable
  name/vendor/product so the desktop does not confuse it with the real one.
- **GUI does not load the config at startup** (found while testing M4, GUI-side,
  not a daemon issue): `build_ui()` fills the rows empty and only
  `Import configuration...` reads the file, so pressing `Save mappings` in a
  freshly opened window overwrites the user's mappings with empty ones. Loading
  `~/.config/gKeyMapper/mappings.conf` on start (or refusing to save unchanged
  rows) should be the next GUI fix.

## 11. Decisions to make

1. Bus name / app-id: replace `com.example.gkeymapper` with a real reverse-DNS id
   (suggested `dev.rager.gkeymapper`)? Affects the `.desktop` name too.
2. Event loop: GLib `GMainLoop` (simplest, reuses GIO) vs. raw `epoll` (leanest).
3. IPC: D-Bus (idiomatic, GIO already present) vs. a Unix socket (no bus
   dependency). Recommendation: D-Bus, with signals as a fallback.
4. Scope of v1: keep `key`/`command`/`disabled` only, or also port
   `typeout`/`media`?

### Resolved

- **Bus name / app id (done in M4).** App id (and GApplication id)
  `dev.rager.gkeymapper`; the daemon uses `dev.rager.gkeymapper.Daemon` because
  GtkApplication owns the plain app id to detect a second GUI instance. The
  installed `.desktop` file keeps its name `gkeymapper.desktop` — both old and
  new app id yield the X11 `WM_CLASS` `gkeymapper`, which is what
  `StartupWMClass` matches (verified with `xprop`).
- **IPC (done in M4).** D-Bus with GDBus: libdbus and sd-bus dev files are not
  installed on this machine, GIO is; the daemon links `gio-2.0`.
- **IPC event integration (done in M4).** The daemon keeps its simple blocking
  loop instead of moving to a `GMainLoop`: `DaemonService::pump()` calls
  `g_main_context_iteration(ctx, FALSE)` once per iteration, so D-Bus is serviced
  without a thread and without blocking, at the cost of up to one read timeout of
  latency on the control plane.
- **Status line widget (evaluated).** The daemon status stays a plain
  `GtkLabel` in the window footer. `GtkStatusbar` does exist in GTK4 and is
  themed, but it keeps a message stack (pop/push per context id) and GTK4 exposes
  it over AT-SPI as a generic `filler`, not as a "statusbar" role — so it was
  built, compared side by side and dropped.
- **Event loop (as implemented, deviates from §4.2).** The daemon is
  single-threaded with a blocking `libusb_interrupt_transfer` and a 500 ms
  timeout; the config watch is drained once per iteration. That is ~2 idle
  wakeups/s at 0 % CPU (the "simple variant" of §4.2) rather than the preferred
  async libusb + GMainLoop design. Switching to libusb's async API with its poll
  fds in a `poll()` loop stays open if idle wakeups ever become a concern — the
  config watch would fold into the same set.
- **Layout handling (done in M2).** Key names in the file are layout
  independent; the daemon resolves them through the active layout (`XKBLAYOUT`
  from `/etc/default/keyboard`, via xkbcommon) and only falls back to the US
  positions from `shared/keys`. This closes the vocabulary-drift risk for non-US
  layouts — a German `z` is evdev 21, not the US position 44.
- **Reload without restart (done in M2, completed in M4).** `SIGHUP`/`SIGUSR1`
  re-read the config file; since M4 the GUI's `Save mappings` also calls the
  D-Bus `Reload`, and the inotify watch applies anything else.
- **Config watching (done in M3).** The daemon watches the config **directory**
  with inotify rather than the file, so an atomic save (temp file + `rename`) and
  a recreated file are caught too. The loop iteration (≤ 500 ms) is the
  coalescing window, so one save yields exactly one reload; `SIGHUP`/`SIGUSR1`
  stay as the fallback and there is no extra fd in the loop. `Save mappings` in
  the GUI now writes atomically, so the daemon can never read a partial file. A
  failed reload keeps the previous mappings instead of disabling every key.
- **Lifecycle (done in M3, extended in M4).** A systemd **user** unit (not a
  system service): the daemon needs the session for `/dev/uinput` and for the
  `DISPLAY` a `command` action inherits. Since M4 it is `Type=dbus` with
  `BusName=dev.rager.gkeymapper.Daemon`, and a D-Bus activation file lets the bus
  start it on demand, so enabling the unit is optional. The udev rule and the
  `modules-load.d` fragment live in `data/` and are installed by `make install`
  (under `PREFIX/lib/...`, which udev and systemd both search).
- **Single instance (done in M4).** The daemon requests its bus name with
  `DO_NOT_QUEUE` and exits with a message when it is already taken — two
  instances would detach the kernel driver from each other and create two virtual
  keyboards. The check happens before the device is opened.