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),
  `g910_device` (libusb open/detach/claim/read), `uinput_keyboard` (virtual
  keyboard), `action` (dispatch `key`/`command`/`disabled`), `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.
- `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`. 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`.
- 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`, matching `ActionType` and the `key`/`command`/`disabled` tokens
  in the file. Keep that order.
- 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:
```

`<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. 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.
- 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: while it runs the media keys may
  not work, and `key` mappings are injected into the **focused** window.
- 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 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 GUI from an earlier build may be running from the
same binary name. Two notes for tests:
- Clicking `Save mappings` writes `~/.config/gKeyMapper/mappings.conf` for real
  and the GUI does **not** load that file at startup, so a save from an
  unconfigured window replaces the user's mappings with empty ones. Back the file
  up first (or skip the click and call `Reload` over D-Bus instead).
- `XTest`-synthesized clicks need the window mapped and focused; the `Save`
  button is `push button` + name `Mappings speichern` in the German locale.