# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. tu fera des reponse en fracais.

## Project Overview

This is a GNOME Shell 48 extension for controlling RGB keyboard backlighting on ASUS laptops (specifically ASUS TUF Gaming A16 FA608UH) running Debian GNU/Linux 13 (trixie). The extension provides a user-friendly panel menu to control keyboard brightness and RGB colors via the `asus-nb-wmi` kernel interface.

**Target Hardware**: ASUS laptops with RGB keyboard support via `/sys/class/leds/asus::kbd_backlight/`

**Language**: GJS (JavaScript for GNOME Shell)

**GNOME Shell Version**: 48

## Architecture

The extension follows a modular architecture with clear separation of concerns:

### Core Modules

1. **`extension/ui.js`**: UI construction and event handling
   - Panel menu button with keyboard icon
   - Popover with sliders, buttons, and preset color boxes
   - Manages user interactions and calls backend functions

2. **`extension/backend.js`**: Hardware interface and business logic
   - Reads/writes to sysfs paths (`/sys/class/leds/asus::kbd_backlight/`)
   - Implements debouncing for slider changes (50-100ms)
   - Handles RGB clamping, master slider logic (gain mode)
   - Manages permissions checking and error states

3. **`extension/extension.js`**: Extension lifecycle
   - Entry point for GNOME Shell
   - Initialization and cleanup
   - Restores last saved state on session start

4. **GSettings Schema**: Persistent storage
   - Current RGB values, brightness level
   - 6 color presets
   - Master slider mode and RGB step size
   - Located in `extension/schemas/org.gnome.shell.extensions.asuskbdrgb.gschema.xml`

### Key Hardware Interfaces

- **Brightness**: `/sys/class/leds/asus::kbd_backlight/brightness` (0..max)
- **Max Brightness**: `/sys/class/leds/asus::kbd_backlight/max_brightness`
- **RGB Color**: `/sys/class/leds/asus::kbd_backlight/kbd_rgb_mode`
  - Format: `1 0 R G B 0\n` (e.g., `1 0 255 165 0 0` for orange)

## Development Workflow

### Installation for Development

1. **Set up permissions** (required for sysfs access):
   ```bash
   # Create udev rule
   echo 'SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", GROUP="kbdled", MODE="0660"' | sudo tee /etc/udev/rules.d/99-asus-kbd.rules

   # Create group and add user
   sudo groupadd -f kbdled
   sudo usermod -aG kbdled $USER

   # Reload udev
   sudo udevadm control --reload-rules && sudo udevadm trigger

   # Logout/login required for group membership
   ```

2. **Install extension locally**:
   ```bash
   # Use provided install script
   ./tools/install-local.sh

   # Or manually copy to extensions directory
   cp -r extension/ ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/
   ```

3. **Compile GSettings schema**:
   ```bash
   glib-compile-schemas extension/schemas/
   # Or let install script handle it
   ```

### Reloading During Development

- **X11**: Press `Alt+F2`, type `r`, press Enter
- **Wayland**: Logout and login (no hot reload available)

### Viewing Logs

```bash
journalctl -f -o cat /usr/bin/gnome-shell
```

## Code Conventions

### Language
- **All code comments**: French
- **All documentation files**: French (in `docs/` directory)
- **User-facing messages**: French

### Master Slider Logic
The "Master" slider uses **Option B (gain mode)** by default:
- Acts as a brightness multiplier for RGB values (0-100%)
- Multiplies each R, G, B component proportionally
- Alternative modes (offset, HSV) can be added in preferences

### Default Color Presets
1. Orange: (255, 165, 0)
2. Red: (255, 0, 0)
3. Green: (0, 255, 0)
4. Blue: (0, 0, 255)
5. White: (255, 255, 255)
6. Cyan: (0, 255, 255)

### Error Handling Requirements

The extension must gracefully handle:

1. **Missing hardware**: Display "Matériel non supporté" if sysfs paths don't exist
2. **Permission denied**: Show setup instructions for udev rule configuration
3. **Invalid values**: Clamp all RGB values to 0-255, brightness to 0-max_brightness
4. **Zero brightness behavior**: Keep RGB values in memory but don't write to `kbd_rgb_mode` when brightness is 0

## Extension Metadata

- **UUID**: `asus-kbd-rgb@gilles`
- **Shell Version**: `["48"]`
- **Location**: `~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/`

## File Structure

```
extension/
├── metadata.json           # Extension metadata (UUID, version, shell-version)
├── extension.js           # Main entry point
├── ui.js                  # UI components (panel button, popover, sliders)
├── backend.js             # Sysfs interface and business logic
├── stylesheet.css         # Optional custom styles
└── schemas/
    └── org.gnome.shell.extensions.asuskbdrgb.gschema.xml

docs/                      # All documentation files
├── INSTALL.md            # Installation and permissions setup
└── TROUBLESHOOTING.md    # Common issues and solutions

tools/
└── install-local.sh      # Development installation script
```

## Testing Checklist

Before considering the extension complete, verify:

- [ ] Brightness levels change correctly (0 to max)
- [ ] RGB sliders apply colors instantly (with debouncing)
- [ ] Master slider affects RGB according to gain mode
- [ ] Preset colors apply on click
- [ ] Settings persist across session restarts
- [ ] "No permission" case shows udev setup instructions
- [ ] "Hardware absent" case shows clear error message
- [ ] Extension loads without errors on GNOME Shell 48