feat(keyboard): light the AK820 Pro in the wallpaper accentHEADmaster

udt-keyboard sets an Ajazz AK820 Pro to its "launch" effect in the
current accent through ak820-ctl, and does nothing without it.
udt-accent starts it detached on every run; --watch reapplies the
accent when the USB cable is plugged in, since the keyboard takes no
commands over its dongle or Bluetooth.

The firmware ignores a mode change unless the lights go off first and
settle, so it sends off, waits three seconds, then the mode. A lock
keeps a wallpaper change and a plug-in from interleaving the pairs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

4 files changed, 65 insertions, 4 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 329a20e..55bdf2d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -208,7 +208,12 @@ It writes seven things: `~/.cache/udt/udt-accent.rasi` (rofi),
 read through a root-made `theme.conf.user` symlink), and the accent
 substitution in Sublime's installed `Packages/User/udt.sublime-color-scheme`.
 It then starts `udt-homepage` and `udt-grub` detached, for the two outputs
-that need a root step on another filesystem or host.
+that need a root step on another filesystem or host, and `udt-keyboard`, which
+lights an Ajazz AK820 Pro in the accent through `ak820-ctl` (a no-op without
+it). The keyboard only listens over its USB cable, so `udt-keyboard --watch`,
+started from hypr-theme's autostart, reapplies the accent on every plug-in. Its
+firmware ignores a mode change unless the lights go off first and settle for a
+few seconds, hence the off, sleep 3, mode sequence; one second was not enough.
 
 **Sublime's accent is replaced, not substituted into a placeholder.** Its
 colour scheme cannot cascade, so the accent has to live in the one generated
@@ -252,7 +257,7 @@ those two and pywal's wallpaper-derived colours come back.
 
 Not everything tracks the wallpaper. rofi, quickshell, Hyprland borders,
 hyprlock's border (through `~/.cache/udt/hyprlock-border.conf`), Sublime's
-colour scheme and Firefox do; conky, Qt, GTK, waybar, hyprlock's panel palette
+colour scheme, Firefox and the AK820 Pro keyboard do; conky, Qt, GTK, waybar, hyprlock's panel palette
 (from `templates/hyprlock/hyprlock-palette.conf`) and Sublime's UI chrome sit
 on the scheme's accent, lavender by default, which is also the fallback
 when a wallpaper is too grey to snap. Qt and GTK apps only reread a theme on restart,
diff --git a/bin/udt-accent b/bin/udt-accent
index 31798cc..b0b59b0 100755
--- a/bin/udt-accent
+++ b/bin/udt-accent
@@ -480,7 +480,8 @@ def main(image):
     # an unreachable host would hold the wallpaper change for the scp timeout.
     # GRUB's background is a wallpaper snapshot. Detached for the same reason;
     # it only rebuilds and notifies, since the copy into /boot needs root.
-    for helper in ("udt-homepage", "udt-grub"):
+    # The keyboard takes seconds per colour change, and is often not there.
+    for helper in ("udt-homepage", "udt-grub", "udt-keyboard"):
         subprocess.Popen([Path(__file__).resolve().parent / helper],
                          stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
                          stderr=subprocess.DEVNULL, start_new_session=True)
diff --git a/bin/udt-keyboard b/bin/udt-keyboard
new file mode 100755
index 0000000..e6dc395
--- /dev/null
+++ b/bin/udt-keyboard
@@ -0,0 +1,55 @@
+#!/bin/bash
+# udt-keyboard: light the Ajazz AK820 Pro in the wallpaper accent.
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+# Licensed under the GNU General Public License v2 only.
+#
+# Usage: udt-keyboard           set the keyboard to the current accent
+#        udt-keyboard --watch   do that again every time it is plugged in
+#
+# The colour is the one udt-accent wrote for rofi, so the keyboard follows the
+# wallpaper like the window borders do. udt-accent starts this detached on
+# every run; the watcher is started from hypr-theme's autostart, because the
+# keyboard only takes commands over the USB cable and may be plugged in long
+# after the last wallpaper change.
+#
+# Talks to the keyboard through ak820-ctl, which the udev rule shipped with it
+# lets the logged-in user drive without root. Without ak820-ctl, or with the
+# keyboard on the 2.4G dongle or Bluetooth, this does nothing.
+
+command -v ak820-ctl >/dev/null || exit 0
+
+# "launch": dark until a key is pressed, which lights outward along its row.
+MODE=launch
+
+apply() {
+    local accent
+    accent="$(grep -o 'accent: #[0-9a-fA-F]\{6\}' "$HOME/.cache/udt/udt-accent.rasi" 2>/dev/null)"
+    [ -n "$accent" ] || return 0
+
+    # A wallpaper change and a plug-in can land together, and two interleaved
+    # off/mode pairs leave the keyboard on whichever off came last.
+    exec 9>"${XDG_RUNTIME_DIR:-/tmp}/udt-keyboard.lock"
+    flock 9
+
+    # This firmware ignores a mode change unless the lights were turned off
+    # first and given time to settle; one second was not enough, three is.
+    ak820-ctl light off >/dev/null 2>&1 || return 0
+    sleep 3
+    ak820-ctl light "$MODE" -c "${accent#accent: #}" >/dev/null 2>&1
+}
+
+if [ "$1" != --watch ]; then
+    apply
+    exit
+fi
+
+# One usb_device event per plug-in; its interfaces and hidraw nodes would each
+# fire again. udevadm prints an event once its rules have run, so the uaccess
+# ACL is already in place, but the keyboard needs a moment to boot.
+/sbin/udevadm monitor --udev --subsystem-match=usb/usb_device --property |
+while read -r line; do
+    case "$line" in
+        ACTION=*) action="${line#ACTION=}" ;;
+        PRODUCT=c45/8009/*) [ "$action" = add ] && { sleep 2; apply; } & ;;
+    esac
+done
diff --git a/install.sh b/install.sh
index 95d3325..7a78f80 100755
--- a/install.sh
+++ b/install.sh
@@ -125,7 +125,7 @@ ln -sfn "$HOME/.cache/udt/colors.json" "$HOME/.cache/wal/colors.json"
 
 # The rofi menus are bound by name in hypr-theme's keybindings, so they keep
 # the names they had when they lived loose in ~/bin.
-for f in udt-accent udt-grub udt-steps udt-palette udt-machine-name udt-powermenu.sh udt-launcher.sh qar-scrotmenu.sh; do
+for f in udt-accent udt-grub udt-keyboard udt-steps udt-palette udt-machine-name udt-powermenu.sh udt-launcher.sh qar-scrotmenu.sh; do
     ln -sfn "$repo/bin/$f" "$HOME/bin/$f"
 done