hyprduma-config/docs/PYWAL-SETUP.md

# Pywal Integration Guide

Dynamic color theming based on your wallpaper, applied system-wide to Hyprland, Caelestia, Kitty, GTK apps, Firefox, and more.

## Prerequisites

- `python-pywal` installed (`sudo pacman -S python-pywal`)
- Hyprland window manager
- Caelestia shell (optional, for full integration)

## Setup

If you used the auto-installer (`install.py`), pywal is already configured. For manual setup:

### 1. Install Templates

```bash
mkdir -p ~/.config/wal/templates
cp -r wal/templates/* ~/.config/wal/templates/

# Verify
ls ~/.config/wal/templates/
# Should show: hyprland-colors.conf, caelestia-scheme.json
```

### 2. Install Scripts

```bash
cp pywal.sh ~/.config/hypr/scripts/
chmod +x ~/.config/hypr/scripts/pywal.sh
```

### 3. Configure Kitty Terminal

```bash
mkdir -p ~/.config/kitty
cp kitty/kitty.conf ~/.config/kitty/

# Verify correct filename reference
grep "colors-kitty" ~/.config/kitty/kitty.conf
# Should show: include ~/.cache/wal/colors-kitty.conf
```

### 4. Configure Shell

Add to `~/.bashrc` (or `~/.zshrc`):

```bash
# Import pywal colorscheme from cache
(cat ~/.cache/wal/sequences &)

# To add support for TTYs (optional)
source ~/.cache/wal/colors-tty.sh 2>/dev/null
```

### 5. Generate Initial Colors

```bash
wal -i wallpapers/sakura.jpg && pywal
source ~/.bashrc
```

## Usage

### Using Waypaper GUI (Recommended)

Press `Super+W` to open waypaper. Select a wallpaper and colors auto-apply via the waypaper hook.

### Command Line

```bash
# Dark theme (default)
pywal ~/Pictures/wallpaper.jpg

# Light theme
pywal ~/Pictures/wallpaper.jpg light

# Switch mode (keep current wallpaper)
pywal "" light
pywal "" dark

# Refresh current theme
~/pywal.sh
```

### One-Liner

```bash
wal -i /path/to/wallpaper.png && pywal
```

## Light/Dark Theme

### Light Theme

Works best with bright wallpapers:

```bash
wal -i /path/to/bright-wallpaper.png -l && pywal
```

### Dark Theme (Default)

```bash
wal -i /path/to/dark-wallpaper.png && pywal
```

### Backend Options

Different backends generate different color palettes:

```bash
wal -i /path/to/wallpaper.png --backend colorz      # More vibrant
wal -i /path/to/wallpaper.png --backend colorthief   # Alternative palette
wal -i /path/to/wallpaper.png --backend haishoku     # Another option
```

## What Gets Themed

| Component | What changes |
|-----------|-------------|
| **Hyprland** | Window borders (active gradient, inactive) |
| **Caelestia Shell** | Material Design 3 color scheme, all UI elements |
| **Kitty Terminal** | Background, foreground, all 16 colors |
| **Bash/Zsh Shell** | Terminal color palette via sequences |
| **GTK Apps** | Via `wal-gtk` (if installed) |
| **Firefox** | Via `pywalfox` (if installed) |
| **System** | Dark/light mode preference via gsettings |

## Optional Enhancements

### GTK Theme Support

```bash
yay -S wal-gtk-theme-git
# pywal.sh will automatically generate GTK themes
```

### Firefox Theme Support

```bash
yay -S python-pywalfox
pywalfox install
# Then install the Pywalfox extension from Firefox Add-ons
```

### Qt Application Support

```bash
yay -S qt5ct qt6ct kvantum
echo "QT_QPA_PLATFORMTHEME=qt5ct" >> ~/.config/environment.d/qt.conf
echo "QT_STYLE_OVERRIDE=kvantum" >> ~/.config/environment.d/qt.conf
```

## Customization

### Border Colors

Edit `~/.config/wal/templates/hyprland-colors.conf`:

```conf
general {
    col.active_border = rgba({color4.strip}ee) rgba({color6.strip}ee) 45deg
    col.inactive_border = rgba({color8.strip}aa)
}
```

Available variables: `{color0}` through `{color15}`, `{background}`, `{foreground}`, `{cursor}`

After editing, regenerate with `wal -R`.

### Caelestia Colors

Edit `~/.config/wal/templates/caelestia-scheme.json` to adjust Material Design 3 color mappings.

## How It Works

1. `wal -i wallpaper.png` generates colors and processes templates in `~/.config/wal/templates/`
2. Generated files land in `~/.cache/wal/`
3. `hyprland.conf` sources `~/.cache/wal/hyprland-colors.conf` for border colors
4. `pywal.sh` copies the Caelestia scheme, reloads Hyprland, restarts Caelestia, reloads Kitty, and sets GTK/Firefox themes
5. The waypaper hook (`waypaper-hook.sh`) runs this entire chain automatically on wallpaper change

## Files

```
~/.config/wal/templates/
├── hyprland-colors.conf     # Template for Hyprland border colors
└── caelestia-scheme.json    # Template for Caelestia color scheme

~/.cache/wal/                # Generated by pywal
├── hyprland-colors.conf     # Sourced by hyprland.conf
├── colors-kitty.conf        # Included by kitty.conf
├── caelestia-scheme.json    # Copied to Caelestia state dir
├── sequences                # Loaded by bashrc
└── colors.json              # Full color palette
```

## Troubleshooting

### Colors not applying to terminals

1. Check bashrc has pywal lines: `grep pywal ~/.bashrc`
2. Check cache exists: `ls ~/.cache/wal/sequences`
3. Open a **new** terminal (existing ones need `source ~/.bashrc`)

### Kitty colors wrong

```bash
# Must reference colors-kitty.conf (not kitty-colors.conf)
grep "wal" ~/.config/kitty/kitty.conf

# Fix if wrong
sed -i 's/kitty-colors.conf/colors-kitty.conf/g' ~/.config/kitty/kitty.conf
killall -SIGUSR1 kitty
```

### Caelestia not updating

```bash
pkill caelestia && sleep 0.5 && caelestia shell -d &
```

### Hyprland fails to start (source file not found)

Run `wal -i /path/to/wallpaper.png` once to generate initial colors before starting Hyprland.

### Complete Reset

```bash
rm -rf ~/.cache/wal
mkdir -p ~/.config/wal/templates
cp ~/.config/hypr/wal/templates/* ~/.config/wal/templates/
wal -i /path/to/wallpaper.png && pywal
source ~/.bashrc
```

### Kitty Opacity for Light Themes

If light theme is too transparent, adjust in `~/.config/kitty/kitty.conf`:

```conf
background_opacity 0.95
```

Reload: `killall -SIGUSR1 kitty`