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-host/src/mgmt.rs

@@ -120,6 +120,7 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
             OpenApiRouter::new()
                 .routes(routes!(get_health))
                 .routes(routes!(get_host_info))
+                .routes(routes!(list_compositors))
                 .routes(routes!(get_status))
                 .routes(routes!(list_paired_clients))
                 .routes(routes!(unpair_client))
@@ -446,6 +447,52 @@ async fn get_host_info(State(st): State<Arc<MgmtState>>) -> Json<HostInfo> {
     })
 }
 
+/// A compositor backend the host can drive a virtual output on, and whether it's usable now.
+#[derive(Serialize, ToSchema)]
+struct AvailableCompositor {
+    /// Stable identifier (`"kwin"` | `"wlroots"` | `"mutter"` | `"gamescope"`) — pass this to a
+    /// client's `--compositor` flag.
+    id: String,
+    /// Human-readable label for UIs.
+    label: String,
+    /// Usable on this host right now: the live session's own compositor, or gamescope wherever
+    /// its binary is installed.
+    available: bool,
+    /// True for the backend an `Auto` (unspecified) request resolves to right now.
+    default: bool,
+}
+
+/// Available compositor backends
+///
+/// Lists every backend the host knows how to drive, flags which are usable right now, and marks
+/// the one an unspecified (`Auto`) client request resolves to. Clients pass an `id` to their
+/// `--compositor` flag (or `PUNKTFUNK_COMPOSITOR_*` over the C ABI) to request it.
+#[utoipa::path(
+    get,
+    path = "/compositors",
+    tag = "host",
+    operation_id = "listCompositors",
+    responses(
+        (status = OK, description = "Compositor backends with availability + the auto-detected default", body = [AvailableCompositor]),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+async fn list_compositors() -> Json<Vec<AvailableCompositor>> {
+    let available = crate::vdisplay::available();
+    let default = crate::vdisplay::detect().ok();
+    Json(
+        crate::vdisplay::Compositor::all()
+            .into_iter()
+            .map(|c| AvailableCompositor {
+                id: c.id().into(),
+                label: c.label().into(),
+                available: available.contains(&c),
+                default: default == Some(c),
+            })
+            .collect(),
+    )
+}
+
 /// Live host status
 #[utoipa::path(
     get,
@@ -771,6 +818,24 @@ mod tests {
         assert_eq!(body["codecs"], serde_json::json!(["h264", "h265", "av1"]));
     }
 
+    #[tokio::test]
+    async fn compositors_lists_all_backends_with_flags() {
+        let app = test_app(test_state(), None);
+        let (status, body) = send(&app, get_req("/api/v1/compositors")).await;
+        assert_eq!(status, StatusCode::OK);
+        let arr = body.as_array().expect("array");
+        // Every backend the host knows, in stable order.
+        let ids: Vec<&str> = arr.iter().map(|c| c["id"].as_str().unwrap()).collect();
+        assert_eq!(ids, ["kwin", "gamescope", "mutter", "wlroots"]);
+        for c in arr {
+            assert!(c["available"].is_boolean());
+            assert!(c["default"].is_boolean());
+            assert!(c["label"].as_str().is_some_and(|s| !s.is_empty()));
+        }
+        // At most one backend is the auto-detect default (none, if the test env has no desktop).
+        assert!(arr.iter().filter(|c| c["default"] == true).count() <= 1);
+    }
+
     #[tokio::test]
     async fn status_reflects_runtime_state() {
         let state = test_state();
@@ -808,7 +873,14 @@ mod tests {
             x509_parser::pem::parse_x509_pem(state.identity.cert_pem.as_bytes()).unwrap();
         let der = pem.contents.clone();
         let fingerprint = hex::encode(Sha256::digest(&der));
-        state.paired.lock().unwrap().push(der);
+        // Isolate from any real paired store on the dev box: AppState::new loads
+        // ~/.config/punktfunk/paired.json, so clear it before seeding our stand-in — otherwise
+        // a real GameStream-paired client lands at body[0] and this assertion sees its hash.
+        {
+            let mut p = state.paired.lock().unwrap();
+            p.clear();
+            p.push(der);
+        }
 
         let (status, body) = send(&app, get_req("/api/v1/clients")).await;
         assert_eq!(status, StatusCode::OK);