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` and `libxkbcommon-dev` (see README for `apt install` on a
  fresh machine).
- `make daemon` — builds only `gkeymapper-daemon` (needs libusb + xkbcommon,
  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 and
  assets are used. Plain `./gkeymapper` works too (assets fall back to
  `./assets`).
- `make clean` — deletes the binary and the generated `locale/` tree.
- 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_*`).
- The Makefile globs sources: `make` builds the GUI (`src/*.cpp` + `shared/*.cpp`)
  **and** the daemon (`daemon/*.cpp` + `shared/*.cpp`, needs `libusb-1.0-0-dev`
  and `libxkbcommon-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`) and `config_watch`
  (inotify auto-reload of the mappings file). `shared/keymap` does the layout
  lookups for both sides. The hot path never touches the GUI.
- `make install` (PREFIX default `/usr/local`) also installs the packaging
  files from `data/`: the udev rule, the `modules-load.d` fragment and the
  systemd **user** unit. The unit contains 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:
  `com.example.gkeymapper`.
- 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
`find_asset()` resolves in order: `$GKEYMAPPER_ASSETS_DIR` → `./assets` →
compiled-in `ASSETS_DIR` (`/usr/local/share/gkeymapper/assets`). The icon
(`assets/icon.png`) is used in the header bar and the About dialog.

## 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.
- Test the auto-reload without hardware: write the config through the shared
  save path (atomic temp+rename, as the GUI does) and watch `/tmp/daemon.log`
  for a second `loaded ...` line. `daemon/config_watch.cpp` also has a
  standalone test shape: create a `ConfigWatcher`, `poll_events()` then
  `take_change()` per simulated loop iteration.
- `make install DESTDIR=/tmp/stage` stages the packaging files; inspect
  `/tmp/stage/usr/local/lib/...` to verify the unit's `ExecStart` 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.