feat: client-selectable compositor (protocol → host → client → C ABI → mgmt → web)

A client can now request which compositor backend the host drives its virtual
output on (gamescope/KWin/Mutter/wlroots). The host honors the request if that
backend is available, else falls back to auto-detect and reports the resolved
choice back — wire-compatible both directions (no ABI bump).

Protocol (punktfunk-core):
- New CompositorPref (config.rs): Auto|Kwin|Wlroots|Mutter|Gamescope with
  u8/name mappings. Appended as one optional byte to Hello (client preference)
  and Welcome (host's resolved choice). Both decoders already tolerate trailing
  bytes, so old↔new interop is preserved — ABI_VERSION stays 2. Round-trip +
  back-compat (truncated-message) tests.
- C ABI: punktfunk_connect_ex(compositor) + PUNKTFUNK_COMPOSITOR_* constants;
  punktfunk_connect delegates with AUTO, so the existing symbol is unchanged.
  NativeClient::connect / worker_main thread the preference through.

Host:
- vdisplay::available() enumerates usable backends via cheap, side-effect-free
  probes (KWin zkde global, gamescope binary+version, GNOME/Sway env), plus
  Compositor id/label/as_pref/from_pref/all helpers.
- m3 handshake resolves the preference to a concrete backend during the
  handshake (pick_compositor pure + resolved logging), reports it in Welcome,
  and threads it into virtual_stream (replacing the unconditional detect()).
- mgmt GET /v1/compositors lists every backend with availability + the
  auto-detected default (OpenAPI regenerated).

Client:
- punktfunk-client-rs --compositor NAME; logs the host's resolved choice from
  the Welcome ("session offer … compositor=…").

Web console:
- Host page gains a Compositors card (availability + default badges) via the
  codegen'd useListCompositors hook; en/de strings added.

Also fixes a pre-existing, env-dependent test-isolation bug:
mgmt::tests::paired_clients_list_and_unpair seeded the real
~/.config/punktfunk/paired.json (AppState::new loads it), so a real
GameStream-paired client leaked into body[0] on a dev box — now cleared first.

Live-validated against headless KWin: --compositor kwin honored, --compositor
mutter falls back to kwin (available=[kwin, gamescope]), resolved choice
round-trips to the client. Tests: +6 (wire/back-compat, resolution precedence,
endpoint); workspace green, clippy/fmt clean, C ABI harness PASS at abi_version=2,
web typecheck + build clean.

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

crates/punktfunk-client-rs/src/main.rs

@@ -17,15 +17,19 @@
 //! Host→client datagrams (Opus audio, rumble) are counted and reported with the stream
 //! stats — decode/playback is the platform clients' job.
 //!
+//! `--compositor NAME` requests a host compositor backend (`auto`|`kwin`|`wlroots`|`mutter`|
+//! `gamescope`); the host honors it if available, else auto-detects and reports the resolved
+//! choice in its Welcome (logged as `session offer … compositor=…`).
+//!
 //! Usage: `punktfunk-client-rs [--connect HOST:PORT] [--mode WxHxFPS] [--out FILE] [--input-test]
-//!         [--pin HEX]` (M4 adds VAAPI decode + wgpu present on this same skeleton.)
+//!         [--pin HEX] [--compositor NAME]` (M4 adds VAAPI decode + wgpu present on this skeleton.)
 
 use anyhow::{anyhow, Context, Result};
 use punktfunk_core::config::Role;
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::quic::{endpoint, io, Hello, Reconfigure, Reconfigured, Start, Welcome};
 use punktfunk_core::transport::UdpTransport;
-use punktfunk_core::{Mode, PunktfunkError, Session};
+use punktfunk_core::{CompositorPref, Mode, PunktfunkError, Session};
 use std::io::Write;
 
 struct Args {
@@ -40,6 +44,8 @@ struct Args {
     pair: Option<String>,
     /// `--name LABEL` — how the host labels this client when pairing.
     name: String,
+    /// `--compositor NAME` — request a host compositor backend (auto|kwin|wlroots|mutter|gamescope).
+    compositor: CompositorPref,
 }
 
 fn parse_mode(m: &str) -> Option<Mode> {
@@ -115,6 +121,17 @@ fn parse_args() -> Args {
             }
         }
     };
+    // A present-but-unrecognized --compositor must abort rather than silently auto-detect.
+    let compositor = match get("--compositor") {
+        None => CompositorPref::Auto,
+        Some(s) => match CompositorPref::from_name(s) {
+            Some(c) => c,
+            None => {
+                eprintln!("--compositor must be one of: auto, kwin, wlroots, mutter, gamescope");
+                std::process::exit(2);
+            }
+        },
+    };
     Args {
         connect: get("--connect").unwrap_or("127.0.0.1:9777").to_string(),
         mode,
@@ -124,6 +141,7 @@ fn parse_args() -> Args {
         remode,
         pair: get("--pair").map(String::from),
         name: get("--name").unwrap_or("punktfunk-client-rs").to_string(),
+        compositor,
     }
 }
 
@@ -207,6 +225,7 @@ async fn session(args: Args) -> Result<()> {
         &Hello {
             abi_version: punktfunk_core::ABI_VERSION,
             mode: args.mode,
+            compositor: args.compositor,
         }
         .encode(),
     )
@@ -218,6 +237,7 @@ async fn session(args: Args) -> Result<()> {
         fec = ?welcome.fec,
         encrypt = welcome.encrypt,
         frames = welcome.frames,
+        compositor = welcome.compositor.as_str(),
         "session offer"
     );