gKeyMapper/AGENTS.md

# AGENTS.md

## What this is
A pure GTK4 C++ GUI plus a background daemon for remapping the G1–G9 keys of a
Logitech G910. The GUI edits and persists mappings; the daemon reads the G-keys
and replays the configured action. Hardware G-key detection and action execution
live in the daemon, not the GUI. Code is split across `src/` (GUI), `shared/`
(common) and `daemon/`.

## Build / run / verify
- `make` — builds the `gkeymapper` GUI, the `gkeymapper-daemon` and the `.mo`
  catalogs. Needs `g++` (C++17), `make`, `gettext`, `libgtk-4-dev`,
  `libusb-1.0-0-dev`, `libxkbcommon-dev` and `libglib2.0-dev` (see README for
  `apt install` on a fresh machine). `libglib2.0-dev` also provides
  `glib-compile-resources`, which generates the icons embedded into the GUI.
- `make daemon` — builds only `gkeymapper-daemon` (needs libusb, xkbcommon and
  gio-2.0, not GTK).
- `make translations` — only runs `msgfmt` on the existing `.po` files.
- `make run` — builds, then runs with `GKEYMAPPER_LOCALEDIR=$PWD/locale` and
  `GKEYMAPPER_ASSETS_DIR=$PWD/assets` so the working-tree translations are used.
  Plain `./gkeymapper` works too (assets fall back to `./assets`). The window
  icon itself is compiled into the binary, so it never depends on these.
- `make clean` — deletes the binaries and the generated `locale/` and `build/`
  trees.
- No tests and no CI. Verify changes by building and running the app.

## i18n — easy to get wrong
- English is the source language (the `msgid`) **and** also has an explicit
  identity catalog `po/en.po`. Languages: `de`, `en`, `es`, `fr`.
- `make translations` does **not** regenerate the `.pot`. When you add or change
  a UI string, edit `po/gkeymapper.pot` and `po/*.po` by hand, then run
  `make translations`; validate with `msgfmt --check -o /dev/null po/<lang>.po`.
- Never edit the generated `.mo` files under `locale/` (gitignored). Delete any
  `po/*.po~` backups before committing.
- All documentation and source comments are English. German appears only inside
  `po/de.po`.

## Code layout and conventions
- Modules under `src/` (GUI), `shared/` (used by both binaries) and `daemon/`
  (the background service). Shared API lives in `namespace gkeymapper`.
  `shared/mapping` owns the mappings file format, `shared/keys` the canonical
  key-name table (lowercase GDK names -> Linux `KEY_*`), `shared/ipc_ids.h` the
  app id, the version and the D-Bus names both sides use.
- The Makefile globs sources: `make` builds the GUI (`src/*.cpp` + `shared/*.cpp`
  + the generated `build/gresources.c`, see Assets) **and** the daemon
  (`daemon/*.cpp` + `shared/*.cpp`, needs `libusb-1.0-0-dev`,
  `libxkbcommon-dev` and `libglib2.0-dev`). `make daemon` builds only the daemon.
- The daemon is split into: `device_tables` (raw HID report tables per model plus
  `decode_gkey_state`, the report → pressed-bitmap decoder), `g910_device` (libusb
  open/detach/claim/read), `uinput_keyboard` (virtual keyboard), `action`
  (dispatch `key`/`command`/`disabled`/`keyhold`), `config_watch` (inotify auto-reload of
  the mappings file) and `ipc_dbus` (the GDBus service). `shared/keymap` does the
  layout lookups for both sides. The hot path never touches the GUI: D-Bus is
  control plane only and is pumped once per loop.
- G-key decoding is **state-based**, not per-key matching: the macro report holds
  a bitmap (byte 4 = G1–G8, low bit of byte 5 = G9), so the daemon fires a key on
  a 0 → 1 transition. That is what suppresses the repeats of a held key and makes
  a chord fire every key in it. Media/memory keys and command/LED answers are
  rejected by report length and header; keep it that way instead of
  re-introducing exact-report matching.
- `keyhold` uses the **falling** edge too: `run_mapping(..., hold=true)` calls
  `ActionRunner::begin_hold()`, and the 1 → 0 transition of that bit calls
  `end_hold(index)` (a no-op for every other type). The held codes are stored per
  G key in `ActionRunner::held_`, so a code that two G keys hold is released only
  when the *last* one comes up. `release_held()` runs on device loss and on
  shutdown, otherwise a key whose release report never arrived would stay down in
  the whole session. `ActionRunner::run()` (the `TestMapping` path) taps a hold
  mapping, because a D-Bus call cannot wait for a release. Only a single step can
  be held; a sequence is replayed as a tap with a log line, and `keyhold:` on an
  unresolvable name does nothing.
- Auto-repeat of a held key comes from the **X server / compositor**, not from the
  virtual device: it sets no `EV_REP` bits, so the kernel repeats nothing, but X
  does (measured: release+press pairs every ~40 ms after 660 ms). That matches a
  physical key, so do not "fix" it by filtering.
- The daemon runs **without** a keyboard: `open()` failing (or a read error) only
  logs the absence once, reports `DeviceChanged(false)` and the loop retries every
  2 s while D-Bus and the config watch keep running. Never make it exit on a
  missing device — that would drop the bus name and make the GUI look like the
  daemon died. `GKeyDevice::open(quiet)` exists so those retries stay out of the
  journal (libusb-level errors always log).
- `make install` (PREFIX default `/usr/local`) also installs the packaging
  files from `data/`: the udev rule, the `modules-load.d` fragment, the
  systemd **user** unit and the D-Bus activation file. Both contain an
  `@BINDIR@` placeholder that the Makefile substitutes with `$(PREFIX)/bin`.
  Keep it a user service — it needs the session for `/dev/uinput` and
  `DISPLAY`.
- Daemon config reload: `config_watch` watches the config **directory** (so an
  atomic save via `rename` is caught) and reports a change at most once per loop
  iteration, which is the coalescing window. `SIGHUP`/`SIGUSR1` remain as a
  fallback. A failed reload keeps the previous mappings on purpose.
- `main.cpp` keeps the `rows` vector (one `KeyRow` per G key, widget pointers)
  in an anonymous namespace; `src/mappings.cpp` is GUI glue that moves data
  between the widgets and the shared `MappingSet`. `build_ui()` loads
  `default_config_path()` into the rows as soon as they exist (a missing file is
  not an error), so a save from a fresh window rewrites the file instead of
  emptying it. App id:
  `dev.rager.gkeymapper` (`ipc::kAppId`); the About dialog uses `ipc::kVersion`.
- GUI ↔ daemon is D-Bus on the session bus, GDBus (GIO) on both sides:
  `src/daemonclient.{h,cpp}` is the client, `daemon/ipc_dbus.{h,cpp}` the
  service. The daemon owns `dev.rager.gkeymapper.Daemon`, **not** the plain app
  id — `GtkApplication` owns that itself to detect a second GUI instance, so a
  daemon on the same name would make every GUI start look like a duplicate and
  exit. All names live in `shared/ipc_ids.h`.
- Exactly one GUI runs, and it is the one that was just started: `main()` calls
  `replace_running_instance()` (`src/singleinstance.{h,cpp}`) **before** it
  creates the `GtkApplication`. It asks the instance that owns `ipc::kAppId` to
  quit over D-Bus (the `quit` action `GApplication` exports as
  `org.gtk.Actions` at the app-id path, added in `on_activate`) and waits for the
  name; an instance from an older build has no such action, so it is terminated
  with `SIGTERM` after checking that the bus name really belongs to a
  `gkeymapper` process. Only then does the new process become the primary,
  because otherwise `GtkApplication` would hand over to the old process and its
  window — possibly one from an older build — would stay on screen. Row edits
  that were not saved are gone with the replaced window; there is no implicit
  save.
- `on_activate` presents the window that is already there
  (`gtk_application_get_windows()`), it does not build a second one: a remote
  activation — an older build starting next to a new one — would otherwise add a
  second window to the running process.
- Except for that startup takeover, the GUI never does a blocking D-Bus call:
  `DaemonClient` uses async calls and signal subscriptions, which arrive on the
  GTK main loop, and it follows `NameOwnerChanged` so the footer reacts when the
  daemon starts or stops.
- `DaemonService::pump()` dispatches messages once per daemon loop iteration, so
  a control call is answered within one read timeout (≤500 ms) and outgoing
  signals are flushed then too. Keep it off the keypress path.
- The daemon refuses to start when the name is taken (`DO_NOT_QUEUE` + exit 0
  with a message): two instances would fight over the device and create two
  virtual keyboards. That check runs **before** the device is opened.
- The daemon status line is a plain `GtkLabel` in the window footer, updated with
  a single `gtk_label_set_text()`. It is deliberately **not** a `GtkStatusbar`:
  that needs message pop/push bookkeeping per context id, and GTK4 exposes it
  over AT-SPI as a generic `filler`, not as a "statusbar" role, so it buys
  nothing here.
- The Type dropdown index is meaningful everywhere: `0=Key`, `1=Command`,
  `2=Disabled`, `3=Key (hold)`, matching the `key`/`command`/`disabled`/`keyhold`
  tokens in the file. Keep that order (`ActionType` appends new values at the end
  — `Disabled, Key, Command, KeyHold` — so an existing value never changes
  meaning; the GUI maps indices explicitly).
- The capture dialog's `CaptureSession` is heap-allocated and freed only by the
  window's `"destroy"` handler. Always close the dialog with
  `gtk_window_destroy` so the session is released.
- Use GTK4 API only: `gtk_editable_set_text` / `gtk_editable_get_text` (there is
  no `gtk_entry_set_text`), `gtk_window_destroy` (no `gtk_dialog_run`),
  `G_APPLICATION_FLAGS_NONE`.
- The main window is intentionally **non-resizable** and has **no**
  `GtkScrolledWindow` (one collapsed the rows earlier). Keep the fixed widths
  (Type dropdown 150 px, target entry 440 px min, action button 180 px) so rows
  do not jump when the language changes.
- Because it is pure GTK4 it follows the system theme (Mint-Y ships a
  `gtk-4.0` theme). Do **not** add the `suggested-action` CSS class — Mint-Y
  tints it green and it clashes with the rest of the layout.

## Config file format
`Save mappings` writes `~/.config/gKeyMapper/mappings.conf`; Export/Import use
the same format:

```
G1=key:ctrl+c,ctrl+v
G2=command:/usr/bin/firefox
G3=disabled:
G4=keyhold:ctrl+w
```

`<type>:<target>`, one line per key. `key` is a captured sequence (lowercase
`gdk_keyval_name` output; modifiers joined with `+`, steps joined with `,`),
`command` is a program path or command line, `disabled` is inactive, and
`keyhold` presses one step and keeps it down while the G key is held. The
canonical modifier order is `ctrl`, `alt`, `shift`, `super`, `altgr`
(`format_shortcut_step()`; parsing accepts any order).

Key names are **layout independent**: `shared/keymap` resolves a name like `z`
to the key that produces `z` on the active layout (read from
`/etc/default/keyboard`, `XKBLAYOUT`) via xkbcommon — on a German keyboard `z` is
evdev 21, not the US position 44. `shared/keys` maps names to the US positions
and is only the fallback. When you add key names, keep them lowercase GDK keysym
names. `parse_shortcut()` takes an optional resolver for this (the daemon passes
one).

The capture dialog stores the **base (level 0) key**: it uses
`Keymap::base_key_name(keycode)` instead of GDK's shifted keyval, so
`Shift`+ß becomes `shift+ssharp` (not `shift+question`, which would double the
shift). `format_shortcut_step()` — not the dialog — renders a step from a
`ModifierBit` mask, so the order stays in one place.

AltGr (level 3) is recorded as the `altgr` modifier plus the base key
(`AltGr`+7 → `altgr+7`). GTK4 dropped the `GDK_MOD5_MASK` name, so the dialog
tracks `ISO_Level3_Shift` / `Mode_switch` through its own key press/release
(`CaptureSession::altGrHeld`) instead of a state bit. On the replay side
`kModAltGr` maps to `KEY_RIGHTALT`.

## Assets
The icons (`assets/icon.png`, `assets/icon.svg`) are compiled into the GUI:
`data/icons.gresource.xml` is turned into the generated `build/gresources.c` by
`glib-compile-resources` and linked into `gkeymapper`, so the window has its icon
with nothing installed. The resource prefix mirrors the app id
(`/dev/rager/gkeymapper`) and the `icons/` subtree mirrors the hicolor layout, so
`gtk_icon_theme_add_resource_path()` also answers
`gtk_window_set_icon_name("gkeymapper")` from the binary. The daemon embeds no
resource (it has no UI).

`make_icon_image()` and the About dialog take the embedded copy first and fall
back to `find_asset()`, which resolves `$GKEYMAPPER_ASSETS_DIR` → `./assets` →
compiled-in `ASSETS_DIR` (`/usr/local/share/gkeymapper/assets`). Because the
resource is built from `assets/` it cannot go stale, and it deliberately wins
over any installed file; the file lookup remains only as a safety net.

## Driving the daemon for manual checks
- The process name is truncated by the kernel to 15 chars, so `pkill -x
  gkeymapper-daemon` and `pgrep -x gkeymapper-daemon` **never match**. Use
  `pkill -x gkeymapper-daem` / `pgrep -x gkeymapper-daem` (or `pkill -f
  './gkeymapper-daemon'`).
- Run it in the background with `setsid nohup ./gkeymapper-daemon [config]
  > /tmp/daemon.log 2>&1 < /dev/null &`; it survives across shell calls. It
  takes an optional config path as `argv[1]` (default
  `~/.config/gKeyMapper/mappings.conf`).
- `SIGHUP`/`SIGUSR1` reload the mappings
  (`kill -HUP $(pgrep -x gkeymapper-daem)`). Normally you do not need them: the
  config file is watched, so saving in the GUI reloads within about half a
  second. Use `SIGHUP` to check the signal path after touching it.
- If the systemd user service is enabled, **stop it first**
  (`systemctl --user stop gkeymapper-daemon`) before starting the repo build by
  hand: the daemon refuses to run when the bus name is taken (a second instance
  would fight over the device). Restore it afterwards with
  `systemctl --user start gkeymapper-daemon`. Note that the installed unit runs
  `/usr/local/bin/gkeymapper-daemon`, so *that* binary is the old one until the
  next `sudo make install`.
- D-Bus control channel (the daemon owns `dev.rager.gkeymapper.Daemon`):

  ```bash
  D=dev.rager.gkeymapper.Daemon; O=/dev/rager/gkeymapper/Daemon
  gdbus call --session --dest $D --object-path $O --method $D.GetStatus
  gdbus call --session --dest $D --object-path $O --method $D.Reload
  gdbus call --session --dest $D --object-path $O --method $D.TestMapping 0
  gdbus monitor --session --dest $D     # KeyPressed / ConfigReloaded / ...
  ```

  `TestMapping` runs the same path as a real keypress, so it verifies a mapping
  without hardware (index is 0-based, `0` = G1). A `TestMapping` for a
  `disabled:`/empty row fails with `G_n_ has no usable mapping`. `busctl --user`
  also works.
- The config watch is testable without the device: `daemon/config_watch.cpp` has
  a standalone test shape (create a `ConfigWatcher`, `poll_events()` then
  `take_change()` per simulated loop iteration), and `ConfigReloaded` on the
  `gdbus monitor` above reports when a save was applied. A GUI save triggers two
  reloads on purpose — the file watch and the explicit `Reload()` call.
- Decoding and the whole loop are also testable **without** the keyboard, which is
  the fastest way to check hot-plug and the GUI footer states (plan §9):
  - compile `daemon/device_tables.cpp` standalone and feed `decode_gkey_state()`
    synthetic reports: single keys, a chord, a repeated (held) report, the release
    report, and the families that must be rejected (memory keys `11 ff 09` /
    `11 ff 0a`, command `11 ff 08 2e` and LED answers); cover `decode_media_key()`
    with the `02 <bit>` presses, the release, a padded report and the same
    families, which must *not* decode as media keys (see the bit table above);
  - build the daemon with a **fake** `GKeyDevice`: keep the header, script
    `open()`/`read_report()`, link `daemon/*.cpp` **without** `g910_device.cpp`
    and without libusb. That runs the real loop, so it covers "no keyboard at
    start", "device lost" and the reopen, emits real D-Bus signals and never
    claims the real device — nothing touches the keyboard and no key is injected
    into the focused window. Use a config with `command:` mappings only (a helper
    script that dumps its environment is also how you check that a `command`
    action sees `DISPLAY`); with `key:` mappings the fake would inject keys into
    whatever window is focused.
    Two details when the fake has to exercise `key:`/`keyhold:` mappings:
    - **Copy `main.cpp` next to the fake**, e.g. `/tmp/…/fakesrc/main.cpp`, and put
      the fake `g910_device.h` in an include directory. `#include "g910_device.h"`
      searches the *including file's* directory first, so compiling the real
      `daemon/main.cpp` would always pick up the real header (its inline
      `is_open()` needs libusb).
    - **Give the fake its own session bus** (`dbus-daemon --session --address=
      unix:path=/tmp/…/fake_bus --fork --print-pid=1`, then
      `DBUS_SESSION_BUS_ADDRESS=unix:path=…` for the fake). Otherwise it refuses
      to start while the real daemon is running, and stopping the user service for
      a test loses the media keys and the GUI footer.
    - **Read the events back over X**, not from `/dev/input`: the event node of an
      own uinput device has **no ACL** for the user (`/dev/uinput` does, its
      children do not), so `open()` fails with `EACCES`. `xinput test <id>` works
      without root; identify the new device by diffing `xinput list` ids before and
      after (the name is the same as the installed daemon's virtual keyboard). X
      keycodes are evdev + 8, and `xinput test` shows no `EV_SYN`, so
      simultaneity of a chord cannot be read that way — the press/release order
      and the durations can.
    - Use inert keys: `f13`–`f24` are **not** in this layout (`Keymap::key_code`
      returns -1), `pause` and `kp_equal` are. A held Shift for a few 100 ms is
      harmless, a held Ctrl is not.
- D-Bus activation is only testable in a real setup: the installed
  `share/dbus-1/services/dev.rager.gkeymapper.Daemon.service` needs
  `sudo make install`. For a quick check without root, drop a file with
  `Exec=<repo>/gkeymapper-daemon` (no `SystemdService=`) into
  `~/.local/share/dbus-1/services/` — the session bus picks it up without a
  restart — then call a method with no daemon running and watch it appear.
  Remove that file afterwards, or it shadows the installed one.
- `make install DESTDIR=/tmp/stage` stages the packaging files; inspect
  `/tmp/stage/usr/local/lib/...` and
  `/tmp/stage/usr/local/share/dbus-1/services/...` to verify the `@BINDIR@`
  substitution. `systemd-analyze --user verify <unit>` checks the unit. There is
  no `udevadm verify` on systemd 249, so the udev rule is checked by eye against
  the reference project's rule.
- Starting it detaches the kernel driver from the vendor interface and creates a
  `/dev/uinput` keyboard. Warn the user first: `key` mappings are injected into
  the **focused** window. The media keys are *not* affected: the keyboard reports
  mute/volume/play only on that very interface (`…/input1`, measured — see below),
  so the daemon replays those reports unchanged through its virtual keyboard.
  Deleting that passthrough in `daemon/main.cpp` silently kills the media keys
  while the daemon runs. Note that they are deliberately *not* a mapping and not
  going to become one: making them remappable is decided against (plan §11), so do
  not turn `mediaKeys` into config rows or GUI fields without that decision being
  revisited first.
- Media keys cannot be observed over the keyboard's usual event node: with the
  daemon stopped they appear on `event11` (`Phys …/input1`, created when `usbhid`
  owns the interface), not on `event10` (`…/input0`); *both* nodes advertise the
  consumer usages in their HID descriptors, so the capability bitmap proves
  nothing. The authoritative data is the raw report on the `hidraw` node of
  interface `1.1` (`usb-…-5.4.3/input1`, exists only while `usbhid` owns it):
  `02 <bit>` per press with bit 0 `01` next, `02` previous, `04` stop, `08`
  play/pause, `10` volume up, `20` volume down, `40` mute, and `02 00` for the
  release. Verify the passthrough by reading `/tmp/daemon.log`: a press logs
  `media -> mute` / `media -> volume up` / … and the desktop reacts as usual.
  The bit table lives in `g910MediaKeys()` (`daemon/device_tables.cpp`).
- The keyboard is `046d:c32b` (also handle `046d:c335`); on this machine the USB
  device and `/dev/uinput` already carry ACLs for the user, so no root is needed.
- Verify decoding by pressing G keys and reading `/tmp/daemon.log` (it logs
  `G1 -> key:...` per press). Verify what the virtual keyboard emits at the X
  level with `xinput test <keyboard-id>` (`gKeyMapper virtual keyboard` shows up
  as both a pointer and a keyboard — use the **keyboard** id). X keycodes are
  evdev codes + 8. There is no `xdotool`/`wtype`.

## Driving the GUI for manual checks
There is no `xdotool`/`wtype` on this machine, and the capture-dialog buttons
(`Clear`/`Cancel`/`Done`) expose an empty AT-SPI accessible name — the text is in
a child `label` node, so target the button by its child label. `pyatspi`
(`queryAction().doAction(0)`) plus `Xlib`'s `xtest.fake_input` can click buttons
and inject keys. Warn the user before synthesizing keystrokes or stealing window
focus.

The one-instance behavior needs no hardware: start the GUI twice and check that
one process (`pgrep -x gkeymapper`) and one window (`wmctrl -l`) are left. The
replaced process exits `0` when it was closed through the D-Bus `quit` action, or
`143` (`SIGTERM`) when it came from a build without that action — build such an
instance from an older commit (`git worktree add /tmp/legacy <commit>`), start it
and then start the current build next to it. Starting the GUI twice also covers
the `activate` guard: without it the second start adds a second window to the
running process.

The footer's daemon line is a plain `GtkLabel`, so its text can be read back over
AT-SPI: `<app> → frame → panel → label` whose name starts with the translated
`Daemon:` string. To pick the right window, filter the application whose tree
contains that label. A stale instance is not a problem any more: starting the
binary under test closes whatever is running (see the single-instance notes
above) before it shows its window, so it is safe to start it while an older GUI
is up. Three notes for tests:
- Clicking `Save mappings` writes `~/.config/gKeyMapper/mappings.conf` for real.
  Since M5 the window loads that file at startup, so the rows show the saved
  mappings and a save rewrites the same content; back the file up anyway (or skip
  the click and call `Reload` over D-Bus instead).
- The `GtkEntry` texts are **not** readable over AT-SPI here (their text interface
  answers with an empty string), so verify what the rows hold with a screenshot:
  `import -window $(wmctrl -l | grep 'gKeyMapper – Logitech' | awk '{print $1}')
  /tmp/gui.png`. The footer label works over AT-SPI (its accessible *name* is the
  text), but a screenshot of the cropped footer is easier and shows what the user
  sees.
- `XTest`-synthesized clicks need the window mapped and focused; the `Save`
  button is `push button` + name `Mappings speichern` in the German locale.