Add reproducible headless desktop for the X11/NVENC capture path

A Moonlight client connecting to the x11-backend host got a black screen
even though pairing, NVENC, and input injection all worked: the headless
Xorg on :0 had no window manager rendering on it, so capture=x11 grabbed
an empty black root window. (The wlr/kms backends don't hit this — their
capture source renders for itself.)

This was a hand-built path with nothing in the repo to reproduce the
desktop piece. Now:

- files/headless-desktop.service: Openbox session on :0, bound to
  xorg-headless.service, enabled via default.target for lingering boots,
  with a best-effort xsetroot so the desktop is visibly non-black.
- lib/headless.sh: capture_backend_is_x11 + install_headless_desktop
  (idempotent; pulls openbox/xsetroot via the distro dispatch).
- install.sh: installs the desktop unit when capture=x11 is detected.
- status.sh: x11 branch now FAILs if no window manager is on :0 instead
  of only checking the X server answers — the gap that hid this failure.
- docs: TROUBLESHOOTING §13 black-screen lesson; FOLLOWUPS P3 updated.

Part of the P3 x11-backend work; --backend flag, config.sh x11 variant,
and xorg-headless templates remain outstanding.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/FOLLOWUPS.md

@@ -247,6 +247,14 @@ TROUBLESHOOTING.md §13.
 - Debian/Ubuntu package install path (`apt` + the `.deb`), since `yay`/AUR
   don't exist there. This is a larger lift than the flag itself.
 
+**Done so far**: the *desktop* piece of the x11 backend is now reproducible.
+`install.sh` detects `capture = x11` (via `capture_backend_is_x11`) and installs
++ enables `files/headless-desktop.service` (Openbox on `:0`) so the headless
+Xorg has a window manager to render — without it, capture is a black screen.
+`status.sh` gained a matching check (FAIL if no WM on `:0`). Still outstanding:
+the `--backend x11|wlr` flag/auto-detect, the `config.sh` x11 conf variant, and
+shipping the `xorg-headless.service` + `xorg-headless.conf` templates.
+
 **Complexity**: medium-high. The capture-backend split is moderate; full
 Debian packaging support is the bulk of the work.
 

docs/TROUBLESHOOTING.md

@@ -478,6 +478,29 @@ systemctl --user show $UNIT -p Environment -p Requires -p After
 # should show DISPLAY=:0 + XDG_SESSION_TYPE=x11, xorg-headless.service, no wayland/sway
 ```
 
+**Gotcha: black screen in Moonlight even though everything "works".** Pairing
+succeeds, NVENC loads, mouse/keyboard input reaches the host — but the client
+sees only black. Cause: the headless Xorg on `:0` is up, but **nothing is
+rendering on it**. Unlike the wlr path (where the compositor *is* the desktop),
+a bare Xorg server draws nothing on its own, so `capture = x11` grabs an empty
+black root window. Confirm with:
+
+```bash
+DISPLAY=:0 xlsclients                              # only 'sunshine' = no WM/desktop
+DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK    # 'not found' = no window manager
+```
+
+Fix: run a window manager on `:0`. The installer ships a `headless-desktop.service`
+(Openbox) for exactly this and enables it whenever it detects `capture = x11`:
+
+```bash
+systemctl --user enable --now headless-desktop.service
+DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK    # now reports a 'window id'
+```
+
+`status.sh` checks for this directly: with `capture = x11` it now FAILs if no
+window manager is present on `:0`, instead of only verifying the X server answers.
+
 ---
 
 ## Custom keybinding to escape Moonlight (Mac)

files/headless-desktop.service

@@ -0,0 +1,27 @@
+[Unit]
+Description=Openbox session on the headless Xorg (gives Sunshine something to capture)
+# Without a window manager/desktop running on :0, Sunshine's x11 capture grabs
+# an empty black X root window — pairing, NVENC, and input all work but the
+# client sees only black. This unit renders a session onto :0 so the stream
+# shows an actual desktop. Only relevant to the X11/NVENC capture backend
+# (capture = x11); the wlr backend's compositor renders for itself.
+Requires=xorg-headless.service
+After=xorg-headless.service
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+Environment=DISPLAY=:0
+# Wait for the X server to accept connections before launching the WM.
+ExecStartPre=/bin/sh -c 'for i in $(seq 1 20); do xset -display :0 -q >/dev/null 2>&1 && exit 0; sleep 0.5; done; exit 1'
+ExecStart=/usr/bin/openbox-session
+# Paint a solid root so a connecting client sees an obvious (non-black) desktop.
+# Leading '-' = best-effort; a missing xsetroot must not fail the unit.
+ExecStartPost=-/usr/bin/xsetroot -display :0 -solid "#2e3440"
+Restart=on-failure
+RestartSec=2s
+
+[Install]
+# Lingering user manager reaches default.target without a graphical login,
+# matching the headless-boot drop-in pattern used for Sunshine.
+WantedBy=default.target

install.sh

@@ -187,6 +187,16 @@ main() {
       step "Installing headless prep-cmd hooks"
       install_headless_hooks
     fi
+
+    # X11/NVENC headless backend (capture = x11): the headless Xorg on :0 has
+    # no compositor of its own, so it needs a window manager rendering on it or
+    # Sunshine captures a black screen. Detected from the existing sunshine.conf
+    # (this backend is hand-configured; see FOLLOWUPS.md P3). Harmless no-op on
+    # the wlr/kms backends, whose capture source renders for itself.
+    if capture_backend_is_x11; then
+      step "Installing headless desktop (Openbox on :0 for the X11 capture path)"
+      install_headless_desktop
+    fi
     # NOTE: the headless prestart drop-in needs the sunshine unit to already
     # exist; install it after service-unit detection in enable_sunshine_service.
 

lib/headless.sh

@@ -34,6 +34,61 @@ _headless_hook_sources() {
   esac
 }
 
+# The X11/NVENC headless backend (capture = x11, headless Xorg on :0) isn't
+# selected by --headless/--mirror — those pick the *Wayland* capture method.
+# It's identified by an existing `capture = x11` in sunshine.conf, the
+# hand-built path documented in FOLLOWUPS.md P3. When that backend is in play,
+# the headless Xorg needs a window manager rendering on :0 or Sunshine
+# captures a black screen.
+capture_backend_is_x11() {
+  local conf="$HOME/.config/sunshine/sunshine.conf"
+  [[ -f "$conf" ]] || return 1
+  grep -qE '^[[:space:]]*capture[[:space:]]*=[[:space:]]*x11' "$conf"
+}
+
+HEADLESS_DESKTOP_UNIT="headless-desktop.service"
+
+# Pull the lightweight WM (Openbox) we drive on :0, plus xsetroot for the
+# solid-background touch. Idempotent — pkg_install skips what's present.
+ensure_headless_desktop_packages() {
+  command -v openbox-session >/dev/null 2>&1 || pkg_install openbox
+  if ! command -v xsetroot >/dev/null 2>&1; then
+    case "$DISTRO" in
+      debian) pkg_install x11-xserver-utils ;;
+      arch)   pkg_install xorg-xsetroot ;;
+    esac
+  fi
+}
+
+# Install + enable the Openbox session that renders onto the headless Xorg
+# display (:0), so the X11/NVENC capture path has something to show instead of
+# a black root window. Idempotent: safe to re-run. Bound to xorg-headless.service
+# and to default.target (the lingering-user manager reaches it without a login).
+install_headless_desktop() {
+  local src="$SCRIPT_DIR/files/headless-desktop.service"
+  if [[ ! -f "$src" ]]; then
+    err "Desktop unit source missing: $src"
+    return 1
+  fi
+
+  ensure_headless_desktop_packages
+
+  local unit_dir="$HOME/.config/systemd/user"
+  mkdir -p "$unit_dir"
+  install -m 0644 "$src" "$unit_dir/$HEADLESS_DESKTOP_UNIT"
+  systemctl --user daemon-reload
+
+  # enable --now starts it immediately when a user manager is live; on a fresh
+  # headless box with no session yet, fall back to enable-only so it comes up
+  # on next boot via default.target.
+  if systemctl --user enable --now "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1; then
+    ok "Enabled $HEADLESS_DESKTOP_UNIT (Openbox session on :0)"
+  else
+    systemctl --user enable "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1 || true
+    warn "Installed $HEADLESS_DESKTOP_UNIT but couldn't start it now — it will start on next login/boot."
+  fi
+}
+
 install_headless_hooks() {
   mkdir -p "$HEADLESS_BIN_DIR"
   mapfile -t srcs < <(_headless_hook_sources)

status.sh

@@ -182,6 +182,20 @@ case "${CAP:-}" in
         fail "DISPLAY=:0 not reachable (X server not answering)" "Check xorg-headless.service logs."
       fi
     fi
+    # Is a window manager actually rendering on :0? X can be up and reachable
+    # yet have no WM/desktop drawing anything — Sunshine then captures an empty
+    # black root window (pairing/NVENC/input all work; client sees only black).
+    if command -v xprop >/dev/null 2>&1; then
+      wm_check=$( (if [[ $EUID -eq 0 && "$SUSER" != "$(id -un)" ]]; then sudo -u "$SUSER" DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK; else DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK; fi) 2>/dev/null)
+      if grep -q 'window id' <<<"$wm_check"; then
+        pass "a window manager is running on :0 (something to capture)"
+      else
+        fail "no window manager on :0 — capture will be a black screen" \
+             "Start a desktop on the headless Xorg: 'systemctl --user enable --now headless-desktop.service' (install.sh installs it for the x11 backend). See TROUBLESHOOTING.md §13."
+      fi
+    else
+      note "xprop not installed — skipping window-manager-on-:0 check (install x11-utils to enable it)"
+    fi
     # wlr env leaking into an x11 unit (stale sway drop-in — TROUBLESHOOTING §13)
     if [[ -n $UNIT ]]; then
       env_dump=$(uctl show "$UNIT" -p Environment 2>/dev/null)