gnome-asus-kbd-rgb/gnome_asus_kbd_rgb_claude_prompt.md

Consignes de développement — Extension GNOME Shell (GNOME 48) : contrôle RGB clavier ASUS (asus-nb-wmi)

1) Contexte et objectif

Machine cible : ASUS TUF Gaming A16 FA608UH sous Debian GNU/Linux 13 (trixie), GNOME 48 (capture fournie). Le rétroéclairage clavier est pilotable via l’interface noyau asus-nb-wmi :

• Intensité : /sys/class/leds/asus::kbd_backlight/brightness (0..max)
• Couleur (statique) : /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode
  Format : cmd mode R G B speed (ex : 1 0 255 165 0 0)

But : créer une extension GNOME Shell qui ajoute un icône dans la barre du haut, et au clic affiche un popover permettant :

• 4 boutons d’intensité (Off/Faible/Moyen/Fort)
• 3 sliders R, G, B
• 1 slider Master (offset global sur R/G/B, ou gain global — à préciser)
• 6 couleurs prédéfinies (cases cliquables)
• Application en direct sur l’aperçu + sur le clavier

Le tout doit être user-friendly et robuste, avec gestion claire des droits.

2) Décision technique recommandée (à appliquer)

Langage / framework

• GJS / JavaScript (langage standard des extensions GNOME Shell)
• UI via PanelMenu.Button, PopupMenu, St (et éventuellement Slider de GNOME Shell)
• Compatible GNOME Shell 48

Architecture recommandée

Séparer en 3 blocs :

1. ui.js : construction du menu (widgets, layout, events)
2. backend.js : lecture/écriture sysfs + logique (clamp, master slider, presets)
3. prefs/ : page de préférences (optionnel au MVP), + stockage presets (GSettings)

Stockage (persistant)

• GSettings (schema dédié) : RGB courant, intensité, 6 presets, step RGB, mode “master”
• Appliquer au démarrage de session (extension enable) : relire settings et appliquer.

3) Gestion des droits — approche “propre” (prioritaire)

L’extension tourne en user-space (non root). Écrire dans /sys/... nécessite des droits.

Approche recommandée (simple + stable) :

• créer une règle udev qui donne accès en écriture à un groupe dédié (ex kbdled)
• ajouter l’utilisateur au groupe kbdled
• l’extension teste l’accès en écriture et affiche un message si absent

Exemple (à documenter dans README) :

• /etc/udev/rules.d/99-asus-kbd.rules SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", GROUP="kbdled", MODE="0660"
• sudo groupadd -f kbdled
• sudo usermod -aG kbdled $USER
• sudo udevadm control --reload-rules && sudo udevadm trigger
• logout/login

Alternative (non MVP, mais “enterprise grade”) :

• service systemd root + D-Bus + polkit. À proposer uniquement si l’utilisateur refuse udev.

4) Spécification UI (MVP)

Icône

• Icône type “keyboard backlight” (symbolic) dans le top bar.

Menu déroulant (popover)

• Ligne 1 : 4 boutons intensité alignés (Off, 1, 2, 3)
  (style : toggle buttons, celui actif surligné)
• Section sliders :
  • R slider 0..255
  • G slider 0..255
  • B slider 0..255
  • Master slider (définir le comportement exact, voir Questions)
• Ligne info (en bas) :
  • RGB=(r,g,b) + HEX=#RRGGBB + Intensity=n/max
• Section presets :
  • 6 cases couleur cliquables (carrés), appliquent RGB instantanément
  • Un clic long (optionnel) ouvre un mini-dialog pour “enregistrer” la couleur courante dans ce preset

UX exigée

• Application immédiate lors des changements sliders (avec debouncing 50–100ms pour éviter spam sysfs)
• Clamp et sécurité : jamais écrire hors 0..255 / 0..max_brightness
• Si brightness=0, on peut conserver RGB en mémoire mais ne pas écrire kbd_rgb_mode (optionnel)

5) Logique “Master slider”

Implémenter l’une des options suivantes (à trancher via Questions) :

• Option A (offset) : master ajoute un delta (-128..+127) à R,G,B en même temps (clamp).
• Option B (gain) : master agit comme “brightness RGB” 0..100% (multiplie R,G,B).
• Option C (HSV value) : convert RGB->HSV, master modifie V, puis reconvertit.

MVP : Option B (gain) est la plus intuitive pour un “tout monter/descendre”.

6) Implémentation backend (sysfs)

Écriture

• utiliser Gio.File.new_for_path(path).replace_contents(...) (sync ou async)
• écrire :
  • brightness: entier (0..max)
  • kbd_rgb_mode: string 1 0 R G B 0\n
• lecture :
  • max_brightness
  • brightness
  • (si dispo) kbd_rgb_state pour init, sinon utiliser GSettings

Debounce

• sur sliders, ne pas écrire à chaque pixel : buffer + GLib.timeout_add().

Robustesse

• si fichiers absents : afficher “Matériel non supporté”
• si permission refusée : afficher un bloc “Fix permissions” avec étapes udev

7) Repo / Outillage (Gitea + VS Code)

Repo

Créer un repo Gitea (nom suggéré) : gnome-asus-kbd-rgb Arborescence :

• extension/
  • metadata.json
  • extension.js
  • ui.js
  • backend.js
  • stylesheet.css (optionnel)
  • schemas/org.gnome.shell.extensions.asuskbdrgb.gschema.xml
• prefs/ (optionnel MVP)
• README.md
• INSTALL.md (permissions udev + installation)
• tools/ (scripts de dev, lint, packaging)

Dev loop

• activer en local via ~/.local/share/gnome-shell/extensions/<uuid>/
• recharger GNOME Shell :
  • X11 : Alt+F2, r, Enter
  • Wayland : logout/login
• logs :
  • journalctl -f -o cat /usr/bin/gnome-shell

8) UUID et metadata

UUID conseillé : asus-kbd-rgb@gilles (metadata.json doit déclarer shell-version: ["48"])

9) Définition des presets (6)

Par défaut (modifiable) :

1. Orange (255,165,0)
2. Rouge (255,0,0)
3. Vert (0,255,0)
4. Bleu (0,0,255)
5. Blanc (255,255,255)
6. Cyan (0,255,255)

Stocker en GSettings sous forme a{sv} ou simples clés preset1_r, etc.

10) Tests fonctionnels à livrer

• Intensité change correctement (0..max)
• Sliders RGB appliquent instantanément
• Master slider influence R/G/B conformément au mode choisi
• Presets appliquent la couleur
• Redémarrage session : la dernière config est restaurée
• Cas “no permission” : message et guide udev affichés
• Cas “hardware absent” : message clair

11) Livrables attendus de Claude Code

1. Code complet extension GNOME Shell 48 (MVP)
2. README.md (usage) + INSTALL.md (permissions + installation)
3. gschema.xml + compilation instructions (glib-compile-schemas)
4. Un script tools/install-local.sh (copie dans ~/.local/share/gnome-shell/extensions)
5. Optionnel : page Prefs GNOME (prefs.js) pour gérer presets et mode master

12) Questions à trancher AVANT de coder (si ambigu)

Claude doit demander au début, puis implémenter par défaut si pas de réponse :

1. Master slider : offset ou gain ? (par défaut : gain 0..100%)
2. Pas (step) RGB : 1, 5, 10 ? (par défaut : 5, avec option prefs)
3. Au démarrage : lire sysfs si possible, sinon GSettings ? (par défaut : GSettings)
4. Sur brightness=0 : garder couleur mémorisée sans l’écrire, ou écrire quand même ? (par défaut : mémoriser, n’écrire que si >0)
5. Presets : simple clic applique ; long-press pour enregistrer ? (par défaut : clic applique, bouton “Save to preset” option prefs)

13) Prompt d’exécution pour Claude Code

Tu es Claude Code (mode dev). Tu dois produire un projet complet dans un repo Git. Contraintes :

• tes reponse seront en francais
• commentaires en francais
• GNOME Shell 48 (GJS)
• Pas de dépendances externes
• Code lisible, modulaire, commenté
• Robustesse permissions + erreurs
• UX immédiate et fluide
• choix des icones parmis des elemnt gratuit, libre ou opensource
• les fichiers de documentation seront dans un dossier 'docs'
• maintien a jours un changelog qui sera utilise pour reprendre le devellopement de l'app

Plan de travail exigé : 0.0 Analyse complete du projet 0.1 Popose un schema webui (format ascii draw, mermaid, excalidraw, ....) 0.2 Creation d'un ToDO evolutif que tu mettra jours ( a faire, terminer, a tester, annulé, amelioration, ...) 0.3 Creation d'un changelog a mettre ajours frequement ( tu me posera la question) . les element qui y seront inscrit seront pertinent pour une reprise du devellopement

1. Générer l’arborescence complète
2. Implémenter backend sysfs + debounce
3. Implémenter UI popover (table + sliders + presets)
4. Implémenter GSettings + valeurs par défaut
5. Documenter installation + règle udev + troubleshooting
6. Tester et fournir checklist

Fin.