# Black Screen Diagnostic Workflow

When Sunshine, x11vnc, or any display capture tool shows a black screen, use this
workflow to determine whether it's a capture/encoding problem or the GPU is
genuinely outputting black pixels.

## Step 1: Take a hardware screenshot

```bash
DISPLAY=:0 xwd -root -out /tmp/screen.xwd
convert /tmp/screen.xwd /tmp/screen.png
ls -la /tmp/screen.png
```

If the PNG is tiny (~1.3KB regardless of resolution), the framebuffer is all
black. Verify with Python:

```python
from PIL import Image
img = Image.open('/tmp/screen.png')
samples = [img.getpixel((x, y)) for y in range(0, img.height, 200)
           for x in range(0, img.width, 200)]
unique = set(samples)
# {0} means completely black — GPU is not rendering
```

## Step 2: If framebuffer is black, check DRM connector state

```bash
for c in /sys/class/drm/card*-HDMI-*/; do
    echo "$(basename $c): status=$(cat $c/status) enabled=$(cat $c/enabled) dpms=$(cat $c/dpms)"
done
```

Normal output:
```
card1-HDMI-A-1: status=connected enabled=enabled dpms=On
```

Problem output (DPMS lockup):
```
card1-HDMI-A-1: status=connected enabled=disabled dpms=Off
```

## Step 3: Cross-check with nvidia-settings

```bash
nvidia-settings -q EnabledDisplays -q ConnectedDisplays
```

Healthy: `EnabledDisplays` matches `ConnectedDisplays` bitmask.
Locked: `EnabledDisplays = 0x00000000` while `ConnectedDisplays` shows the port.

## Step 4: Cross-check X11 state

```bash
DISPLAY=:0 xrandr | grep "HDMI-0"
DISPLAY=:0 xset q | grep -i "monitor\|dpms"
```

X11 may report "Monitor is On" and show modes available even when the kernel
connector is disabled. This is a driver-level mismatch — X11's DPMS state
doesn't reflect the kernel's actual state.

## Resolution

If `enabled=disabled` and `dpms=Off` at the kernel level:
- `xset dpms force on` and `xrandr --output HDMI-0 --auto` will NOT fix it
- Writing to `/sys/class/drm/card*-HDMI-*/dpms` returns Permission denied even
  as root (NVIDIA driver read-only)
- The GPU display controller needs a full power cycle
- Only a reboot reliably fixes this

After reboot, X11 authorization is broken (LightDM's Xauthority is invalid for
the user). See the main SKILL.md DPMS lockup pitfall for the Xauth merge fix.

## If framebuffer is NOT black (screenshot shows desktop)

The problem is in the capture/streaming layer:
- Sunshine: check `output_name`, `capture` method, `hw_cursor`
- x11vnc: add `-noxdamage`, use `novnc_proxy` launcher
- noVNC: check UFW allows the port, browser console for WebSocket errors