Add headless streaming mode + Mac client + full docs

Headless mode (new) — for KVM-attached hosts streaming to disconnected clients
- --headless / --mirror flags; default headless on hostname JARVIS, mirror elsewhere
- New lib/headless.sh installs prep-cmd hooks to ~/.local/share/omarchy-moonlight/bin
- bin/sunshine-stream-do.sh creates/resizes a Hyprland HEADLESS-1 output to the
  connecting client's resolution and migrates the active workspace onto it
- bin/sunshine-stream-undo.sh tears down the headless output on disconnect and
  returns the workspace to a non-headless monitor when one is available
- lib/config.sh writes capture=wlr, output_name=HEADLESS-1, and the JSON
  global_prep_cmd entry referencing the installed hook paths
- lib/preflight.sh adds a preflight_headless step that checks hyprctl, jq, and
  a running Hyprland session (warn-only, install can proceed)
- lib/verify.sh adds checks for the hook scripts and the wlr/global_prep_cmd
  config lines

Mac client
- client/install-macos.sh: Darwin guard, Homebrew presence check, brew cask
  install of Moonlight, idempotent
- client/README.md: per-platform install (macOS / Android / iOS / Apple TV /
  Linux + Steam Deck) and the five-step first-pair walkthrough

Other
- jq added to the helper install set in lib/packages.sh (hooks parse Hyprland
  JSON output)
- README.md rewritten to cover both modes, the new flags, the tuned defaults
  per mode + per vendor, the headless internals, and the client pointer

lib/config.sh

@@ -7,6 +7,7 @@ SUNSHINE_CONF="$SUNSHINE_CONF_DIR/sunshine.conf"
 MANAGED_MARKER="# managed-by: omarchy-moonlight"
 
 write_sunshine_config() {
+  local mode="${1:-mirror}"
   mkdir -p "$SUNSHINE_CONF_DIR"
 
   if [[ -f "$SUNSHINE_CONF" ]] && ! grep -qF "$MANAGED_MARKER" "$SUNSHINE_CONF"; then
@@ -31,19 +32,36 @@ write_sunshine_config() {
       ;;
   esac
 
-  info "Writing tuned $SUNSHINE_CONF (GPU: $GPU_VENDOR)"
+  local capture_block
+  case "$mode" in
+    headless)
+      # wlr capture of the Hyprland headless output that prep-cmd hooks create.
+      # global_prep_cmd is parsed as a JSON array by Sunshine, so keep it on one line.
+      capture_block="# Capture: wlr — captures a Hyprland headless output created on stream start.
+capture = wlr
+output_name = HEADLESS-1
+
+# Hooks that create/resize HEADLESS-1 on stream start and remove it on stop.
+global_prep_cmd = [{\"do\":\"${DO_SCRIPT}\",\"undo\":\"${UNDO_SCRIPT}\"}]"
+      ;;
+    mirror|*)
+      capture_block="# Capture: KMS (DRM) — the right choice on Wayland.
+capture = kms"
+      ;;
+  esac
+
+  info "Writing tuned $SUNSHINE_CONF (GPU: $GPU_VENDOR, mode: $mode)"
   cat >"$SUNSHINE_CONF" <<EOF
 $MANAGED_MARKER
 # Generated by omarchy-moonlight install.sh on $(date -Iseconds)
 # Delete this marker line to take ownership; the installer will then leave the file alone.
 #
-# Tuned for low-latency LAN streaming on Hyprland/Wayland with KMS capture.
+# Tuned for low-latency LAN streaming on Hyprland/Wayland.
 # Tune further via the web UI at https://localhost:47990
 
 sunshine_name = ${HOSTNAME_SHORT}
 
-# Capture: KMS (DRM) — the right choice on Wayland.
-capture = kms
+$capture_block
 
 # Encoder tuned for $GPU_VENDOR
 $encoder_block

lib/headless.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Set up headless streaming mode: install prep-cmd hook scripts into a stable
+# location and ensure they're executable. The actual sunshine.conf entries
+# (capture=wlr, output_name=HEADLESS-1, global_prep_cmd=[...]) are written
+# by lib/config.sh.
+
+HEADLESS_BIN_DIR="$HOME/.local/share/omarchy-moonlight/bin"
+
+DO_SCRIPT="$HEADLESS_BIN_DIR/sunshine-stream-do.sh"
+UNDO_SCRIPT="$HEADLESS_BIN_DIR/sunshine-stream-undo.sh"
+export DO_SCRIPT UNDO_SCRIPT
+
+install_headless_hooks() {
+  # Install hook scripts to ~/.local/share so they don't disappear if the
+  # repo gets moved or deleted. Sunshine's config will reference these stable paths.
+  mkdir -p "$HEADLESS_BIN_DIR"
+  install -m 0755 "$SCRIPT_DIR/bin/sunshine-stream-do.sh"   "$DO_SCRIPT"
+  install -m 0755 "$SCRIPT_DIR/bin/sunshine-stream-undo.sh" "$UNDO_SCRIPT"
+  ok "Installed prep-cmd hooks to $HEADLESS_BIN_DIR"
+}

lib/packages.sh

@@ -9,7 +9,7 @@
 
 install_sunshine() {
   # Ensure runtime deps useful for capture/diagnostics across vendors.
-  yay_install pipewire-pulse vulkan-tools libva-utils
+  yay_install pipewire-pulse vulkan-tools libva-utils jq
   yay_install "$SUNSHINE_PKG"
 }
 

lib/preflight.sh

@@ -8,6 +8,7 @@ preflight_all() {
   preflight_gpu
   preflight_kms_modeset
   preflight_audio
+  preflight_headless
 }
 
 preflight_session() {
@@ -96,3 +97,33 @@ preflight_audio() {
     warn "pipewire-pulse is not installed. Audio capture may not work until it is."
   fi
 }
+
+preflight_headless() {
+  # Only relevant in headless mode. Checks are non-fatal: install can proceed
+  # even if Hyprland isn't reachable right now (hooks just won't function until
+  # the user logs into Hyprland on the host).
+  [[ "${STREAM_MODE:-}" == "headless" ]] || return 0
+
+  if command -v hyprctl >/dev/null 2>&1; then
+    ok "hyprctl on PATH"
+  else
+    warn "hyprctl not found. Headless prep-cmd hooks will fail until Hyprland is installed and reachable."
+  fi
+
+  if pkg_installed jq; then
+    ok "jq installed (prep-cmd hooks have their parser)"
+  else
+    info "jq not installed yet — will be installed in the packages step."
+  fi
+
+  if [[ -n "${HYPRLAND_INSTANCE_SIGNATURE:-}" ]]; then
+    ok "Hyprland instance signature present in environment"
+  else
+    local rt="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+    if compgen -G "$rt/hypr/*/" >/dev/null 2>&1; then
+      ok "Hyprland runtime directory found under $rt/hypr/"
+    else
+      warn "Hyprland does not appear to be running. Install will proceed; hooks will only work once you log into Hyprland on the host."
+    fi
+  fi
+}

lib/verify.sh

@@ -67,6 +67,40 @@ verify_install() {
       ;;
   esac
 
+  if [[ "${STREAM_MODE:-}" == "headless" ]]; then
+    local do_script="$HOME/.local/share/omarchy-moonlight/bin/sunshine-stream-do.sh"
+    local undo_script="$HOME/.local/share/omarchy-moonlight/bin/sunshine-stream-undo.sh"
+    local conf="$HOME/.config/sunshine/sunshine.conf"
+
+    if [[ -x "$do_script" ]]; then
+      ok "headless do-hook present and executable"
+    else
+      err "headless do-hook missing or not executable: $do_script"
+      VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
+    fi
+
+    if [[ -x "$undo_script" ]]; then
+      ok "headless undo-hook present and executable"
+    else
+      err "headless undo-hook missing or not executable: $undo_script"
+      VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
+    fi
+
+    if [[ -f "$conf" ]] && grep -q '^capture = wlr' "$conf"; then
+      ok "sunshine.conf has capture = wlr"
+    else
+      err "sunshine.conf missing 'capture = wlr'"
+      VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
+    fi
+
+    if [[ -f "$conf" ]] && grep -q '^global_prep_cmd' "$conf"; then
+      ok "sunshine.conf has global_prep_cmd"
+    else
+      err "sunshine.conf missing 'global_prep_cmd'"
+      VERIFY_FAILURES=$((VERIFY_FAILURES + 1))
+    fi
+  fi
+
   if systemctl --user is-active --quiet sunshine.service; then
     ok "sunshine.service is active"
     if ss -ltn 2>/dev/null | grep -q ':47990 '; then