# Firefox + NVIDIA + Wayland Performance Debugging

## Symptom

General page lag in Firefox on an Arch/CachyOS desktop with NVIDIA GPU running KDE Wayland. Not just video — scrolling, page loads, UI interactions all sluggish.

## Root Cause Triad

Firefox falling back to **software rendering** (llvmpipe) due to incompatible prefs + NVIDIA driver version mismatch on Wayland. The smoking gun: Firefox shows **0 MiB** in `nvidia-smi`.

## Trigger Timeline

A batch upgrade that simultaneously bumps NVIDIA driver (595→610), Firefox (150→151), and KWin causes the regression. The 610 series changed Wayland compositing in ways that conflict with Firefox's `layers.acceleration.force-enabled` pref.

## Diagnostic Steps (in order)

### 1. Check GPU usage by Firefox

```bash
nvidia-smi | grep -i firefox
```

If Firefox is **absent** from the process list (0 MiB GPU memory), it's running on software fallback. A healthy Firefox with WebRender should show 200-500 MiB.

### 2. Check display server

```bash
cat /proc/<firefox-pid>/environ | tr '\0' '\n' | grep -E "^DISPLAY|^WAYLAND|^MOZ_ENABLE"
```

- `WAYLAND_DISPLAY=wayland-0` → native Wayland (good)
- `DISPLAY=:0` + no `WAYLAND_DISPLAY` → running under XWayland (adds overhead)

### 3. Check Firefox prefs

Look in `~/.config/mozilla/firefox/<profile>/prefs.js` and `user.js`:

| Problematic pref | Why | Fix |
|-----------------|-----|-----|
| `layers.acceleration.force-enabled=true` | Marked `do_not_use_directly` in Mozilla source. Overrides Firefox's hardware detection and backfires on NVIDIA 610+Wayland, causing full software fallback. **This is the #1 culprit.** | `user_pref("layers.acceleration.force-enabled", false);` in user.js |
| `gfx.webrender.all=true` | Forces all WebRender optimizations through path that may conflict with NVIDIA 610. Less harmful than force-enabled, but can cause issues. | Remove or leave — overridden by force-enabled=false |
| Missing `media.ffmpeg.vaapi.enabled` | Disables hardware video decoding — YouTube content decodes on CPU | `= true` |

### 4. Check actual renderer

Open `about:support` → look for:
- **Compositing:** should say `WebRender` (not `Basic` or `Software`)
- **GPU #1:** should be `NVIDIA` (not `llvmpipe` or `Mesa`)
- **Asynchronous Pan/Zoom:** `true`
- **VAAPI:** `true`

### 5. Verify pref defaults from Mozilla source (when docs are behind bot blockers)

When Arch Wiki or Mozilla support pages are behind CAPTCHAs/bot blockers, check the actual Mozilla source:

```bash
curl -sL 'https://raw.githubusercontent.com/mozilla/gecko-dev/master/modules/libpref/init/StaticPrefList.yaml' | grep -A5 -B2 "<pref-name-here>"
```

This reveals:
- Default value
- Platform guards (`#ifdef XP_WIN` — pref is Windows-only)
- Deprecation/usage notes (`do_not_use_directly: true`)

## Fix

### Environment: Force native Wayland

**For systemd services** → `~/.config/environment.d/moz-fix.conf`:

```
MOZ_ENABLE_WAYLAND=1
```

**For GUI-launched apps** (KDE panel, desktop shortcuts) → `~/.config/plasma-workspace/env/moz-wayland.sh`:

```bash
#!/bin/bash
export MOZ_ENABLE_WAYLAND=1
```
Make executable: `chmod +x ~/.config/plasma-workspace/env/moz-wayland.sh`

The `environment.d` path ONLY affects systemd user services. Plasma GUI apps read `plasma-workspace/env/*.sh`. Both are needed for full coverage. Need to log out/in for either to take effect.

### Firefox user.js

```javascript
// === Fix: disable force-enabled override (causes software fallback on NVIDIA Wayland) ===
user_pref("layers.acceleration.force-enabled", false);

// === NVIDIA VA-API hardware video decoding (YouTube etc.) ===
user_pref("media.ffmpeg.vaapi.enabled", true);
user_pref("media.rdd-ffmpeg.enabled", true);
user_pref("media.ffmpeg.vaapi-drm-display.enabled", true);

// === WebGL stability ===
user_pref("webgl.out-of-process", true);
```

**Do NOT set** these on Linux (they are Windows-only or ineffective):
- `gfx.webrender.force-angle` — wrapped in `#ifdef XP_WIN` in Mozilla source, does nothing on Linux
- `gfx.webrender.enabled` — already enabled by `gfx.webrender.all=true` if that's set

### Verify fix

1. Restart Firefox (after logging back in if env scripts were added)
2. `nvidia-smi | grep firefox` should now show GPU memory (200-500 MiB typical for WebRender)
3. `about:support` → Compositing: `WebRender`, GPU: `NVIDIA`, VAAPI: `true`
4. Open YouTube 1080p60 → video decoder in `nvidia-smi` should show >0%

## Quick rollback if worse

If performance degrades after changes, the most common causes are:
- **`MOZ_ENABLE_WAYLAND=1` on a very old NVIDIA driver (< 545)** — causes crashes; revert by removing the env scripts
- **Switch to X11 session** at SDDM login (Plasma X11) as a cross-check — eliminates all Wayland compositor issues in one test