gnome-asus-kbd-rgb/CHANGELOG.md

# CHANGELOG - Extension GNOME Shell ASUS RGB Keyboard

Ce fichier documente l'évolution du développement de l'extension pour faciliter la reprise du travail.

## [Non publié] - En cours de développement

### 📅 2025-12-23

#### 🆕 Nouvelles Améliorations (Session 4 - suite)

**Amélioration 9: Changement automatique de fond d'écran** ✅
- **Fonctionnalité**: L'extension change automatiquement le fond d'écran GNOME selon la couleur sélectionnée
- **Système de nommage**: 9 wallpapers nommés `ec_v_<couleur>.jpg` (ex: `ec_v_blue.jpg`, `ec_v_orange.jpg`)
- **Implémentation**:
  - Nouvelle fonction `_changeWallpaper(accentColor)` dans ui.js
  - Intégration dans `_syncGnomeTheme()` pour changement automatique
  - Vérification d'existence du fichier avant application
  - Support mode clair ET mode sombre (picture-uri + picture-uri-dark)
- **Installation**:
  - Dossier `wallpapers/` créé dans le projet
  - Script `install-local.sh` modifié pour copier automatiquement les wallpapers
  - Comptage et affichage du nombre de wallpapers installés
- **Documentation**: docs/WALLPAPERS.md avec guide complet
- **Fichiers modifiés**:
  - ui.js ligne 558-587 : Fonction _changeWallpaper()
  - ui.js ligne 619 : Intégration dans _syncGnomeTheme()
  - tools/install-local.sh ligne 112-128 : Copie des wallpapers
- **Comportement**:
  - Si wallpaper absent → log informatif (pas d'erreur)
  - Si présent → changement automatique en même temps que couleur thème
- **Résultat**: Synchronisation complète : couleur clavier + thème GNOME + fond d'écran

### 📅 2025-12-21

#### 🆕 Nouvelles Améliorations (Session 4)

**Amélioration 4: Presets GNOME et restauration thème** ✅
- **Demande**: Remplacer les 6 presets personnalisés par les 9 couleurs d'accentuation GNOME
- **Solution implémentée**:
  - Modification du schéma GSettings : ajout de `preset-7`, `preset-8`, `preset-9`
  - Mise à jour de tous les presets avec les couleurs GNOME officielles :
    1. Bleu (53, 132, 228) - couleur par défaut GNOME
    2. Turquoise (51, 209, 122)
    3. Vert (87, 227, 137)
    4. Jaune (246, 211, 45)
    5. Orange (255, 120, 0)
    6. Rouge (237, 51, 59)
    7. Rose (246, 97, 81)
    8. Violet (145, 65, 172)
    9. Gris ardoise (119, 118, 123)
  - Adaptation UI : boucle de 6 → 9 presets, ajustement taille boutons (32px → 28px)
  - Restauration thème : désactiver la synchronisation remet GNOME sur "blue" (défaut)
- **Résultat**: Cohérence totale entre presets clavier et couleurs d'accentuation GNOME

**Amélioration 5: Style presets ronds et surbrillance** ✅
- **Demande**: Presets en forme de ronds avec cercle blanc autour du preset actif
- **Solution implémentée**:
  - Modification style : `border-radius: 50%` pour rendre les presets circulaires
  - Taille ajustée : 26×26px pour des cercles parfaits
  - Fonction `_updatePresetSelection()` : cercle blanc épais (3px) + box-shadow sur le preset actif
  - Stockage des boutons dans `this._presetButtons[]` avec propriétés `_preset` et `_baseStyle`
  - Comparaison RGB avec tolérance de ±10
  - Appel à chaque changement de couleur pour mise à jour en temps réel
- **Résultat**: Feedback visuel clair du preset actuellement sélectionné

**Amélioration 6: Synchronisation thème universelle** ✅
- **Problème**: Synchronisation thème GNOME fonctionnait uniquement depuis la roue chromatique
- **Cause**: `_onPresetClicked()` appelait directement `Backend.writeRGB()` au lieu de `_onRGBChanged()`
- **Solution**: Refactorisation de `_onPresetClicked()` pour utiliser `_onRGBChanged()`
- **Déclenchement synchronisation maintenant actif**:
  - ✅ Depuis la roue chromatique
  - ✅ Depuis les sliders RGB
  - ✅ Depuis les presets
  - ✅ Depuis le slider Master
- **Résultat**: La couleur GNOME se synchronise peu importe le mode de sélection utilisé

**Amélioration 7: Forçage de l'état RGB au démarrage** ✅ **[CRITIQUE]**
- **Problème**: Clavier parfois éteint au redémarrage, impossible à rallumer sous Debian
- **Cause identifiée**:
  - Le firmware ASUS peut réinitialiser le contrôleur RGB au boot
  - L'extension vérifiait `brightness == 0` et ne touchait pas à RGB dans ce cas
  - Le contrôleur restait dans un état indéfini
- **Solution implémentée**:
  - Suppression de la vérification `if (currentBrightness === 0)` dans `writeRGB()`
  - `_applyCurrentState()` force TOUJOURS brightness + RGB au démarrage
  - Logs explicites pour débugger l'initialisation
- **Fichiers modifiés**:
  - backend.js ligne 171-206 : Suppression du skip RGB si brightness = 0
  - ui.js ligne 837-849 : Forçage inconditionnel de l'état
- **Documentation**: docs/ANALYSE_PERSISTANCE.md
- **Résultat**: Le clavier sera toujours réinitialisé dans l'état GSettings au login GNOME

**Amélioration 8: Correction couleurs presets GNOME** ✅
- **Problème**: Les presets ne correspondaient pas aux vraies couleurs d'accentuation GNOME
- **Couleurs corrigées** (RGB hex → RGB décimal):
  1. ✅ Bleu #3584e4 → (53, 132, 228) - déjà correct
  2. ❌ Turquoise #2190a4 → (33, 144, 164) - corrigé (était 51,209,122)
  3. ❌ Vert #3a944a → (58, 148, 74) - corrigé (était 87,227,137)
  4. ❌ Jaune #c88800 → (200, 136, 0) - corrigé (était 246,211,45)
  5. ❌ Orange #ed5b00 → (237, 91, 0) - corrigé (était 255,120,0)
  6. ❌ Rouge #e62d42 → (230, 45, 66) - corrigé (était 237,51,59)
  7. ❌ Rose #d56199 → (213, 97, 153) - corrigé (était 246,97,81)
  8. ✅ Violet #9141ac → (145, 65, 172) - déjà correct
  9. ❌ Ardoise #6f8396 → (111, 131, 150) - corrigé (était 119,118,123)
- **Fichiers modifiés**:
  - schemas/org.gnome.shell.extensions.asuskbdrgb.gschema.xml ligne 45-89
  - ui.js ligne 526-537 : Fonction `_rgbToGnomeAccent()`
- **Résultat**: Synchronisation thème GNOME maintenant exacte avec les 9 couleurs officielles

#### 🆕 Nouvelles Améliorations (Session 2 et 3)

**Amélioration 1: Surbrillance des boutons d'intensité** ✅
- **Problème**: Les boutons OFF/1/2/3 n'affichaient pas de surbrillance du niveau sélectionné
- **Cause**: Classe CSS incorrecte (`'button'` au lieu de `'brightness-button'`)
- **Solution**: Correction de `style_class` dans `_buildBrightnessButtons()`
- **Résultat**: Bouton actif affiché avec fond bleu et texte blanc gras

**Amélioration 2: Surbrillance de la couleur sélectionnée dans la roue** ✅
- **Problème**: Pas de feedback visuel sur la couleur active dans la roue chromatique
- **Solution implémentée**:
  - Stockage des 113 boutons dans `this._wheelButtons[]`
  - Ajout de propriétés `_rgb` et `_baseStyle` sur chaque bouton
  - Nouvelle fonction `_updateWheelSelection()` pour mettre à jour la bordure
  - Bordure blanche épaisse (3px) + box-shadow sur la couleur sélectionnée
  - Comparaison RGB avec tolérance de ±10 pour gérer les approximations HSL
- **Appels**:
  - ✅ À la construction de la roue (affichage initial)
  - ✅ Sur clic dans la roue
  - ✅ Sur clic preset
  - ✅ Sur changement de couleur
- **Résultat**: Indication claire de quelle couleur est actuellement appliquée dès l'ouverture du menu

**Amélioration 3: Synchronisation avec le thème GNOME** ✅
- **Demande**: Appliquer automatiquement la couleur du clavier comme couleur d'accentuation GNOME
- **Solution implémentée**:
  - Ajout clé GSettings `sync-gnome-theme` (booléen, défaut: false)
  - Fonction `_rgbToGnomeAccent()` : mapping RGB → 9 couleurs GNOME (blue, teal, green, yellow, orange, red, pink, purple, slate)
  - Algorithme: distance euclidienne dans l'espace RGB pour trouver la couleur la plus proche
  - Fonction `_syncGnomeTheme()` : applique via `org.gnome.desktop.interface accent-color`
  - UI: `PopupSwitchMenuItem` "Synchroniser thème GNOME" après les presets
- **Déclenchement**:
  - ✅ Activation de la case à cocher (application immédiate)
  - ✅ Lors de chaque changement de couleur clavier (si activé)
- **Résultat**: La couleur d'accentuation GNOME (affichée dans Paramètres → Apparence) change automatiquement pour correspondre au clavier RGB

#### 🔍 Analyse des Problèmes Identifiés (Session 1)

**Problème 1: Roue chromatique non fonctionnelle**
- **Symptôme**: Impossible de sélectionner une couleur en cliquant sur la roue
- **Cause identifiée**:
  - Première tentative avec `St.DrawingArea` non interactive sous GNOME Shell 48
  - Deuxième tentative avec grille 16×16 de boutons (cellSize: 12px) potentiellement trop petits
  - Les boutons sont créés mais les clics ne sont pas détectés
- **Hypothèse**: Boutons trop petits (12px) ou problème de style CSS empêchant l'interaction

**Problème 2: Niveau d'intensité non visuellement sélectionné**
- **Symptôme**: Aucune indication visuelle du bouton d'intensité actif
- **Cause**: Pas de mise à jour du style CSS lors du clic
- **Solution**: Ajouter classe CSS active et mettre à jour dans `_updateBrightnessButtons()`

**Problème 3: Mode par défaut incorrect**
- **Symptôme**: Mode sliders affiché par défaut alors que l'utilisateur préfère la roue
- **Cause**: `this._colorPickerMode = 'sliders'` dans l'initialisation
- **Solution**: Inverser pour `this._colorPickerMode = 'wheel'`

#### 🔧 Correctifs Appliqués

**Correctif 1: Roue chromatique fonctionnelle** ✅
- Augmentation de la taille des cellules: 12px → 18px (+50%)
- Réduction de la grille: 16×16 → 12×12 pour meilleure visibilité
- Ajout de bordure visible `rgba(0,0,0,0.3)` pour feedback visuel
- Ajout de `reactive: true` et `track_hover: true` pour garantir l'interactivité
- Espacement entre cellules: 2px → 3px pour meilleure séparation

**Correctif 2: Surbrillance des boutons d'intensité** ✅
- Classe CSS `.active` déjà implémentée dans stylesheet.css
- Style actif: fond bleu (`rgba(53, 132, 228, 0.8)`), texte blanc, gras
- Fonction `_updateBrightnessButtons()` existante et fonctionnelle

**Correctif 3: Mode roue par défaut** ✅
- Changement de `_colorPickerMode: 'sliders'` → `'wheel'`
- Roue chromatique affichée en premier au démarrage
- Bouton de bascule pour passer en mode sliders

#### 📊 Résumé des Améliorations

**Interface utilisateur:**
- ✅ Roue chromatique 12×12 avec 113 couleurs cliquables
- ✅ Boutons 18×18px, bien visibles et réactifs
- ✅ Mode roue chromatique par défaut (préférence utilisateur)
- ✅ Surbrillance automatique du niveau d'intensité actif
- ✅ Aperçu couleur dans le header avec correction gamma sRGB

**Ergonomie:**
- ✅ Clic sur la roue chromatique → application immédiate au clavier
- ✅ Slider Luminosité (Master) pour contrôle de l'intensité
- ✅ Bascule facile entre roue et sliders RGB
- ✅ Interface compacte et optimisée

### 📅 2025-12-20

#### ✅ Terminé
- **Analyse du projet** : Compréhension complète des spécifications
- **Architecture définie** : Séparation en 3 modules (ui.js, backend.js, extension.js)
- **Schéma UI créé** : Documentation visuelle complète dans `docs/UI_SCHEMA.md`
  - Diagramme Mermaid de l'architecture
  - Layout ASCII du popover
  - Flux de données
  - Gestion des erreurs UI
- **CLAUDE.md créé** : Guide pour futures instances de Claude Code
- **CHANGELOG.md initialisé** : Ce fichier

#### 🔄 En cours
- Prêt pour installation et tests complets

#### ✅ Tests Matériel Réalisés (ASUS TUF Gaming A16 FA608UH)
- ✅ **Contrôle brightness** : Changement de niveaux 0-3 fonctionnel
- ✅ **Contrôle RGB** : Écriture kbd_rgb_mode validée
- ✅ **Permissions udev** : Règle corrigée et fonctionnelle
  - Règle finale : `ACTION=="add"` avec `RUN+="/bin/sh -c 'chgrp kbdled ...'"`
  - Rechargement module : `modprobe -r asus_nb_wmi && modprobe asus_nb_wmi`
  - Permissions validées : `kbdled` groupe appliqué correctement

#### 📋 Terminé (MVP complet)
- ✅ Arborescence complète du projet créée
- ✅ backend.js implémenté (interface sysfs + debouncing)
- ✅ ui.js implémenté (construction du popover complet)
- ✅ extension.js créé (lifecycle GNOME Shell)
- ✅ Schéma GSettings complet avec 6 presets
- ✅ metadata.json créé
- ✅ stylesheet.css créé pour le styling
- ✅ Documentation installation (docs/INSTALL.md)
- ✅ Documentation troubleshooting (docs/TROUBLESHOOTING.md)
- ✅ Documentation tests (docs/TESTING.md)
- ✅ Script d'installation (tools/install-local.sh)
- ✅ README.md complet et détaillé

#### 🎯 Décisions techniques prises
- **Langage**: GJS (JavaScript GNOME Shell)
- **GNOME Shell**: Version 48
- **UUID**: `asus-kbd-rgb@gilles`
- **Master Slider**: Mode "gain" (multiplie R/G/B par 0-100%)
- **Debouncing**: 75ms pour les sliders
- **Permissions**: Règle udev + groupe `kbdled` (approche simple)
- **Step RGB par défaut**: 5
- **Comportement brightness=0**: Mémoriser RGB sans écrire kbd_rgb_mode

#### 📝 Presets couleur par défaut
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)

#### 🔧 Interface matérielle
- Path brightness: `/sys/class/leds/asus::kbd_backlight/brightness`
- Path max: `/sys/class/leds/asus::kbd_backlight/max_brightness`
- Path RGB: `/sys/class/leds/asus::kbd_backlight/kbd_rgb_mode`
- Format RGB: `1 0 R G B 0\n`

---

## Notes pour reprise du développement

### Prochaines étapes recommandées
1. Créer l'arborescence complète des fichiers
2. Implémenter backend.js en premier (base pour tests)
3. Implémenter ui.js (interface)
4. Créer extension.js pour intégrer les modules
5. Tester avec règles udev configurées

### Points d'attention
- **Permissions critiques**: L'extension ne peut pas fonctionner sans les règles udev
- **Debouncing essentiel**: Éviter de spammer sysfs lors des déplacements de sliders
- **Clamping obligatoire**: Toujours valider 0-255 pour RGB, 0-max pour brightness
- **GNOME Shell 48**: Vérifier la compatibilité API (notamment pour Slider)
- **Wayland vs X11**: Différence pour le rechargement en dev

### Dépendances système
- GNOME Shell 48
- GLib/GIO pour sysfs
- GSettings pour la persistance
- udev pour les permissions

### Structure des modules
```
backend.js → Fonctions exportées:
  - checkHardwareSupport()
  - checkPermissions()
  - readBrightness()
  - writeBrightness(value)
  - readRGB()
  - writeRGB(r, g, b, master)
  - applyPreset(presetId)

ui.js → Classe exportée:
  - KeyboardRGBIndicator extends PanelMenu.Button
  - Méthodes: _buildUI(), _onRGBChanged(), _onBrightnessChanged(), etc.

extension.js → Fonctions requises:
  - init()
  - enable()
  - disable()
```

### Tests à effectuer lors de la reprise
- [ ] Extension se charge sans erreur
- [ ] Popover s'affiche au clic
- [ ] Sliders fonctionnent
- [ ] Debouncing actif (vérifier dans les logs)
- [ ] Écriture sysfs réussie (avec permissions)
- [ ] GSettings sauvegarde correctement
- [ ] Restauration au redémarrage de session