GNOME ASUS Keyboard RGB - Structure du Projet
==============================================

gnome-asus-kbd-rgb/
│
├── README.md                    # Documentation principale du projet
├── CLAUDE.md                    # Guide pour Claude Code
├── CHANGELOG.md                 # Historique des modifications
├── gnome_asus_kbd_rgb_claude_prompt.md  # Consignes initiales
│
├── extension/                   # Code source de l'extension GNOME Shell
│   ├── extension.js            # Point d'entrée (lifecycle: init/enable/disable)
│   ├── ui.js                   # Interface utilisateur (popover, sliders, presets)
│   ├── backend.js              # Interface sysfs et logique métier
│   ├── metadata.json           # Métadonnées (UUID, version, shell-version)
│   ├── stylesheet.css          # Styles CSS personnalisés
│   └── schemas/
│       └── org.gnome.shell.extensions.asuskbdrgb.gschema.xml
│                               # Schéma GSettings (persistance)
│
├── docs/                        # Documentation complète
│   ├── INSTALL.md              # Guide d'installation détaillé
│   ├── TROUBLESHOOTING.md      # Résolution des problèmes
│   ├── TESTING.md              # Checklist de tests (120+ items)
│   └── UI_SCHEMA.md            # Schémas de l'interface (Mermaid, ASCII)
│
└── tools/                       # Scripts utilitaires
    └── install-local.sh        # Script d'installation automatique


Modules Principaux
==================

1. backend.js (Interface Système)
   - checkHardwareSupport()     : Vérifie la présence du matériel
   - checkPermissions()         : Vérifie les droits d'accès
   - getMaxBrightness()         : Lit la valeur max
   - readBrightness()           : Lit la brightness actuelle
   - writeBrightness(level)     : Écrit la brightness (0-3)
   - writeRGB(r, g, b, master)  : Écrit RGB avec master gain
   - writeRGBDebounced()        : Écrit RGB avec debouncing (75ms)
   - parsePreset(string)        : Parse "R,G,B" en objet
   - rgbToHex(r, g, b)          : Convertit RGB en #RRGGBB
   - cleanup()                  : Nettoie les ressources

2. ui.js (Interface Utilisateur)
   - KeyboardRGBIndicator       : Classe principale (extends PanelMenu.Button)
   - _buildUI()                 : Construit l'interface complète
   - _buildBrightnessButtons()  : Crée les 4 boutons d'intensité
   - _buildRGBSliders()         : Crée les sliders RGB + Master
   - _buildInfoLine()           : Crée la ligne d'information
   - _buildPresets()            : Crée les 6 boutons preset
   - _buildErrorUI()            : Affiche les messages d'erreur
   - _onBrightnessButtonClicked() : Gère les clics sur boutons
   - _onRGBChanged()            : Applique les changements RGB
   - _onPresetClicked()         : Applique un preset
   - _applyCurrentState()       : Restaure l'état au démarrage

3. extension.js (Lifecycle)
   - AsusKeyboardRGBExtension   : Classe principale (extends Extension)
   - enable()                   : Active l'extension
   - disable()                  : Désactive l'extension


Fichiers sysfs
==============

/sys/class/leds/asus::kbd_backlight/
├── brightness           # Intensité (0..max_brightness)
├── max_brightness       # Valeur maximale (lecture seule)
└── kbd_rgb_mode         # Couleur RGB (format: "1 0 R G B 0")


Configuration GSettings
=======================

Schéma: org.gnome.shell.extensions.asuskbdrgb

Clés disponibles:
- red (int)              : Composante rouge (0-255)
- green (int)            : Composante verte (0-255)
- blue (int)             : Composante bleue (0-255)
- brightness-level (int) : Niveau d'intensité (0-3)
- master-gain (int)      : Gain master (0-100)
- rgb-step (int)         : Pas d'ajustement (défaut: 5)
- preset-1..6 (string)   : Presets couleur (format "R,G,B")
- master-mode (string)   : Mode du master slider (défaut: "gain")


Installation
============

1. Configuration permissions (obligatoire):
   sudo tee /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 requis !

2. Installation extension:
   ./tools/install-local.sh

3. Rechargement GNOME Shell:
   - X11: Alt+F2, "r", Enter
   - Wayland: Logout/Login


Dépendances
===========

Runtime:
- GNOME Shell 48
- GLib/GIO (pour sysfs)
- GSettings (pour persistance)
- Module kernel: asus-nb-wmi

Build:
- glib-compile-schemas


Prochaines Améliorations (Post-MVP)
====================================

- [ ] Page de préférences (prefs.js) pour modifier les presets
- [ ] Support de modes RGB animés (breathing, wave, etc.)
- [ ] Support multi-zones (si matériel compatible)
- [ ] Export/Import de configurations
- [ ] Profils par application
- [ ] Raccourcis clavier globaux
- [ ] Indicateur de synchronisation avec le matériel
- [ ] Support d'autres modes master (offset, HSV)