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-core/src/abi.rs

@@ -477,8 +477,23 @@ unsafe fn opt_cstr<'a>(p: *const std::os::raw::c_char) -> std::result::Result<Op
         .map_err(|_| ())
 }
 
+/// Compositor preference for [`punktfunk_connect_ex`] (`compositor` arg). `AUTO` lets the host
+/// pick (auto-detect from its running desktop); a concrete value is honored only if that backend
+/// is available on the host right now, else the host falls back to auto-detect. The resolved
+/// choice is reported back over the protocol (see `punktfunk/1` `Welcome`).
+pub const PUNKTFUNK_COMPOSITOR_AUTO: u32 = 0;
+/// KWin / KDE Plasma.
+pub const PUNKTFUNK_COMPOSITOR_KWIN: u32 = 1;
+/// wlroots (Sway / Hyprland).
+pub const PUNKTFUNK_COMPOSITOR_WLROOTS: u32 = 2;
+/// Mutter / GNOME.
+pub const PUNKTFUNK_COMPOSITOR_MUTTER: u32 = 3;
+/// gamescope (spawned nested).
+pub const PUNKTFUNK_COMPOSITOR_GAMESCOPE: u32 = 4;
+
 /// Connect to a `punktfunk/1` host and start a session at `width`x`height`@`refresh_hz`.
-/// Blocks up to `timeout_ms` for the handshake. Returns NULL on failure.
+/// Blocks up to `timeout_ms` for the handshake. Returns NULL on failure. Equivalent to
+/// [`punktfunk_connect_ex`] with `compositor = PUNKTFUNK_COMPOSITOR_AUTO`.
 ///
 /// Trust: `pin_sha256` (NULL or 32 bytes) is the expected SHA-256 fingerprint of the host's
 /// certificate — a mismatching host is rejected. NULL = trust on first use; persist the
@@ -507,6 +522,45 @@ pub unsafe extern "C" fn punktfunk_connect(
     client_cert_pem: *const std::os::raw::c_char,
     client_key_pem: *const std::os::raw::c_char,
     timeout_ms: u32,
+) -> *mut PunktfunkConnection {
+    unsafe {
+        punktfunk_connect_ex(
+            host,
+            port,
+            width,
+            height,
+            refresh_hz,
+            PUNKTFUNK_COMPOSITOR_AUTO,
+            pin_sha256,
+            observed_sha256_out,
+            client_cert_pem,
+            client_key_pem,
+            timeout_ms,
+        )
+    }
+}
+
+/// Like [`punktfunk_connect`], but requests a specific `compositor` backend on the host (one of
+/// the `PUNKTFUNK_COMPOSITOR_*` values). `PUNKTFUNK_COMPOSITOR_AUTO` (or any unrecognized value)
+/// lets the host decide; a concrete value is honored only if available, else the host falls back
+/// to auto-detect. The resolved choice is logged host-side and returned over the protocol.
+///
+/// # Safety
+/// Same as [`punktfunk_connect`].
+#[cfg(feature = "quic")]
+#[no_mangle]
+pub unsafe extern "C" fn punktfunk_connect_ex(
+    host: *const std::os::raw::c_char,
+    port: u16,
+    width: u32,
+    height: u32,
+    refresh_hz: u32,
+    compositor: u32,
+    pin_sha256: *const u8,
+    observed_sha256_out: *mut u8,
+    client_cert_pem: *const std::os::raw::c_char,
+    client_key_pem: *const std::os::raw::c_char,
+    timeout_ms: u32,
 ) -> *mut PunktfunkConnection {
     let r = std::panic::catch_unwind(AssertUnwindSafe(|| {
         if host.is_null() {
@@ -521,6 +575,7 @@ pub unsafe extern "C" fn punktfunk_connect(
             height,
             refresh_hz,
         };
+        let pref = crate::config::CompositorPref::from_u8(compositor as u8);
         let pin = if pin_sha256.is_null() {
             None
         } else {
@@ -539,6 +594,7 @@ pub unsafe extern "C" fn punktfunk_connect(
             host,
             port,
             mode,
+            pref,
             pin,
             identity,
             std::time::Duration::from_millis(timeout_ms as u64),