From deb9c1b6d76fff44c707507552aca67ec9c1ef84 Mon Sep 17 00:00:00 2001
From: iris-ai <4+iris-ai@noreply.localhost>
Date: Mon, 14 Sep 2026 00:36:19 -0400
Subject: [PATCH] Detect the rig's binaries, and take the machine out of its
 comments

The comments described the machine the rig was written on -- "this
machine has no display", "there is a real GPU here", an Android
emulator's GLX quirk -- which says nothing to anyone reading it from a
different checkout. What the reader needs is what the script supplies
and why, which is now all they get.

`sway`, `swaymsg` and, when `--shot` is passed, `grim` are checked up
front and named in the failure, rather than surfacing as a compositor
that would not start.

The `# shellcheck disable=SC2086 -- prose` directive did not parse, so
the suppression was not in effect; the prose moves to its own line.
Clean under shellcheck now.
---
 scripts/headless.conf   | 14 +++++++-------
 scripts/run-headless.sh | 23 ++++++++++++++++-------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/scripts/headless.conf b/scripts/headless.conf
index 71abd5a..ea95646 100644
--- a/scripts/headless.conf
+++ b/scripts/headless.conf
@@ -1,13 +1,13 @@
-# The compositor `scripts/run-headless.sh` starts, because this machine has no
-# display. Nothing here is meant to be looked at directly; `grim` is.
+# The compositor `scripts/run-headless.sh` starts, so that an example has a
+# surface where there is no display. Nothing here is meant to be looked at
+# directly; `grim` is.
 #
-# No Xwayland: winit talks Wayland natively, and starting an X server is a
-# second thing to go wrong for no gain. (`emu`'s config forces it because the
-# Android emulator's renderer speaks GLX.)
+# No Xwayland: winit talks Wayland natively, so an X server is a second thing
+# to go wrong for no gain.
 xwayland disable
 
-# A desktop-shaped output, since this is the desktop half of the port. Larger
-# than the window an example opens, so nothing is scaled or clipped.
+# The default output, overridden per run by `--mode`. Larger than the window
+# an example opens, so nothing is scaled or clipped.
 output HEADLESS-1 mode 1920x1200@60Hz
 
 default_border none
diff --git a/scripts/run-headless.sh b/scripts/run-headless.sh
index 429ce84..838a6d9 100755
--- a/scripts/run-headless.sh
+++ b/scripts/run-headless.sh
@@ -23,13 +23,21 @@
 # `--shot` it also writes `<shot>-before.png` from just before the gesture,
 # since "it moved" is a claim about two pictures.
 #
-# There is a real GPU here and no display, so what is missing is only a
-# compositor to give winit a surface: a headless sway, and `grim` to see the
-# result. It has its own socket and runtime directory rather than joining
-# whatever else is running, because sway tiles -- adding a window to someone
-# else's compositor resizes theirs.
+# What it supplies is a compositor for winit to open a surface on: a headless
+# sway, and `grim` to screenshot it. Sway gets its own socket and runtime
+# directory rather than joining whatever else is running, because it tiles --
+# adding a window to someone else's compositor resizes theirs.
 set -eu
 
+need() {
+    command -v "$1" >/dev/null 2>&1 || {
+        echo "run-headless: $1 is not installed ($2)" >&2
+        exit 127
+    }
+}
+need sway "the compositor an example opens its window on"
+need swaymsg "sway's control socket"
+
 scripts=$(cd "$(dirname "$0")" && pwd)
 root=$(cd "$scripts/.." && pwd)
 workdir="$root"
@@ -57,6 +65,7 @@ while [ $# -gt 0 ]; do
 done
 [ -n "$example" ] || { echo "usage: $0 NAME [--bin] [--dir DIR] [--mode WxH@Hz] [--replay TOUCH] [--shot PNG] [--seconds N] [-- cargo args]" >&2; exit 2; }
 [ -z "$replay" ] || [ -f "$replay" ] || { echo "run-headless: no touch script at $replay" >&2; exit 2; }
+[ -z "$shot" ] || need grim "the screenshot --shot writes"
 
 mkdir -p "$run"
 export SWAYSOCK="$run/sway.sock"
@@ -110,8 +119,8 @@ else
     bin="$workdir/target/debug/examples/$example"
 fi
 
-# shellcheck disable=SC2086 -- deliberately word-split: this is the
-# binary's own argv, not a single path.
+# Deliberately word-split: this is the binary's own argv, not a single path.
+# shellcheck disable=SC2086
 "$bin" ${RUN_HEADLESS_ARGS:-} >"$run/$example.log" 2>&1 &
 pid=$!
 trap 'kill "$pid" 2>/dev/null || true' EXIT INT TERM