feat(gamepad): controller discovery + client-negotiated pad type + rich DualSense end to end

The Apple client grows full gamepad support and punktfunk/1 learns to negotiate the virtual pad type: - Protocol: Hello carries a GamepadPref byte (offset 21, the same trailing-byte back-compat pattern as the compositor; echoed resolved in Welcome at 54). Host precedence: explicit client choice > PUNKTFUNK_GAMEPAD env > Xbox 360, DualSense (UHID) only where available. ABI: punktfunk_connect_ex2 + punktfunk_connection_gamepad (connect_ex delegates; ABI_VERSION stays 2 — the trailing byte IS the compat mechanism). punktfunk-client-rs gets --gamepad. - Swift client: GamepadManager (app-lifetime discovery + selection — Settings lists every controller with capabilities/battery/"In use"; exactly ONE pad forwards as pad 0, auto = most recently connected, or pinned), GamepadCapture (snapshot-diff button/axis events, DualSense touchpad + ~250 Hz motion on the rich-input plane, held state released on switch/deactivate/stop), GamepadFeedback (rumble → CoreHaptics per-handle engines; lightbar → GCDeviceLight; player LEDs → playerIndex; adaptive-trigger blocks → the table-driven DualSenseTriggerEffect parser → GCDualSenseAdaptiveTrigger, exact for the 10-zone positional modes). The pad type auto-resolves from the physical controller at connect time, user-overridable in Settings. - Host DualSense fixes surfaced by adversarial review against hid-playstation / SDL / Nielk1 ground truth: input-report sensor/touch offsets were off by one (the kernel read garbage motion + phantom touches), the L2/R2 trigger blocks were swapped (the report is right-trigger-first), feedback now gates on the report's valid-flags (a plain rumble write no longer blanks lightbar/ triggers), and the touchpad rescale clamps to the advertised ABS_MT extents. - Tests: Hello/Welcome trailing-byte back-compat, pick_gamepad precedence, byte-exact input-report layout, valid-flag gating, per-mode trigger-parser table (incl. packed 3-bit zones), wire conversions, and a scripted loopback feedback burst (PUNKTFUNK_TEST_FEEDBACK=1) asserted through the xcframework on the rumble + HID-output planes. Validated: cargo test/clippy/fmt green on macOS + Linux (61 host tests), swift build/test green, test-loopback.sh green, tvOS/iOS targets compile. DualSense motion sign/scale is derived from the calibration blob, not yet live-verified (constants isolated in GamepadWire). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 16:28:33 +02:00
parent d86896da16
commit 1d605fb781
24 changed files with 2321 additions and 142 deletions
@@ -621,6 +621,19 @@ pub const PUNKTFUNK_COMPOSITOR_MUTTER: u32 = 3;
 /// gamescope (spawned nested).
 pub const PUNKTFUNK_COMPOSITOR_GAMESCOPE: u32 = 4;

+/// Gamepad-backend preference for [`punktfunk_connect_ex2`] (`gamepad` arg): which virtual pad
+/// the host creates for this session's controllers. Precedence host-side: an explicit client
+/// choice > the host's `PUNKTFUNK_GAMEPAD` env var > X-Box 360. `AUTO` (or any unrecognized
+/// value) = host decides. The resolved choice is echoed over the protocol (`Welcome`) and
+/// readable via [`punktfunk_connection_gamepad`].
+pub const PUNKTFUNK_GAMEPAD_AUTO: u32 = 0;
+/// uinput X-Box 360 pad (the universal default — every game speaks XInput).
+pub const PUNKTFUNK_GAMEPAD_XBOX360: u32 = 1;
+/// UHID DualSense (kernel `hid-playstation`): adaptive triggers, lightbar, touchpad, motion —
+/// feedback arrives on the HID-output plane ([`punktfunk_connection_next_hidout`]). Honored
+/// only where available (Linux hosts); otherwise the host falls back to X-Box 360.
+pub const PUNKTFUNK_GAMEPAD_DUALSENSE: u32 = 2;
+
 /// 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. Equivalent to
 /// [`punktfunk_connect_ex`] with `compositor = PUNKTFUNK_COMPOSITOR_AUTO`.
@@ -674,6 +687,7 @@ pub unsafe extern "C" fn punktfunk_connect(
 /// 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.
+/// Equivalent to [`punktfunk_connect_ex2`] with `gamepad = PUNKTFUNK_GAMEPAD_AUTO`.
 ///
 /// # Safety
 /// Same as [`punktfunk_connect`].
@@ -691,6 +705,49 @@ pub unsafe extern "C" fn punktfunk_connect_ex(
    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_ex2(
+            host,
+            port,
+            width,
+            height,
+            refresh_hz,
+            compositor,
+            PUNKTFUNK_GAMEPAD_AUTO,
+            pin_sha256,
+            observed_sha256_out,
+            client_cert_pem,
+            client_key_pem,
+            timeout_ms,
+        )
+    }
+}
+
+/// Like [`punktfunk_connect_ex`], but additionally requests which virtual `gamepad` backend the
+/// host creates for this session's pads (one of the `PUNKTFUNK_GAMEPAD_*` values).
+/// `PUNKTFUNK_GAMEPAD_AUTO` (or any unrecognized value) lets the host decide (its
+/// `PUNKTFUNK_GAMEPAD` env var, else X-Box 360); a concrete value is honored only if that
+/// backend is available on the host. The resolved choice is readable via
+/// [`punktfunk_connection_gamepad`] — only a DualSense session emits HID-output feedback.
+///
+/// # Safety
+/// Same as [`punktfunk_connect`].
+#[cfg(feature = "quic")]
+#[no_mangle]
+pub unsafe extern "C" fn punktfunk_connect_ex2(
+    host: *const std::os::raw::c_char,
+    port: u16,
+    width: u32,
+    height: u32,
+    refresh_hz: u32,
+    compositor: u32,
+    gamepad: 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() {
@@ -705,7 +762,14 @@ pub unsafe extern "C" fn punktfunk_connect_ex(
            height,
            refresh_hz,
        };
-        let pref = crate::config::CompositorPref::from_u8(compositor as u8);
+        // "Any unrecognized value = Auto" must hold for the FULL u32 domain — `as u8`
+        // would wrap 0x101 into a concrete choice before from_u8's fallback could apply.
+        let pref = u8::try_from(compositor)
+            .map(crate::config::CompositorPref::from_u8)
+            .unwrap_or_default();
+        let gamepad = u8::try_from(gamepad)
+            .map(crate::config::GamepadPref::from_u8)
+            .unwrap_or_default();
        let pin = if pin_sha256.is_null() {
            None
        } else {
@@ -725,6 +789,7 @@ pub unsafe extern "C" fn punktfunk_connect_ex(
            port,
            mode,
            pref,
+            gamepad,
            pin,
            identity,
            std::time::Duration::from_millis(timeout_ms as u64),
@@ -1153,6 +1218,33 @@ pub unsafe extern "C" fn punktfunk_connection_mode(
    })
 }

+/// The virtual gamepad backend the host actually resolved for this session (one of the
+/// `PUNKTFUNK_GAMEPAD_*` values; the `Welcome`'s echo of the [`punktfunk_connect_ex2`]
+/// preference). `PUNKTFUNK_GAMEPAD_AUTO` = an older host that didn't say — assume X-Box 360,
+/// no HID-output feedback. Safe any time after connect.
+///
+/// # Safety
+/// `c` is a valid connection handle; `gamepad` is writable (NULL is skipped).
+#[cfg(feature = "quic")]
+#[no_mangle]
+pub unsafe extern "C" fn punktfunk_connection_gamepad(
+    c: *const PunktfunkConnection,
+    gamepad: *mut u32,
+) -> PunktfunkStatus {
+    guard(|| {
+        let c = match unsafe { c.as_ref() } {
+            Some(c) => c,
+            None => return PunktfunkStatus::NullPointer,
+        };
+        unsafe {
+            if !gamepad.is_null() {
+                *gamepad = c.inner.resolved_gamepad.to_u8() as u32;
+            }
+        }
+        PunktfunkStatus::Ok
+    })
+}
+
 /// Ask the host to switch the live session to `width`x`height`@`refresh_hz` without
 /// reconnecting (window resized, refresh changed). Non-blocking enqueue: on acceptance the
 /// stream continues at the new mode — the first new-mode access unit is an IDR with
@@ -11,7 +11,7 @@
 //! invariant) plus a blocking data-plane pump; frames cross to the embedder over a bounded
 //! channel. All methods are safe to call from any single embedder thread.

-use crate::config::{CompositorPref, Mode, Role};
+use crate::config::{CompositorPref, GamepadPref, Mode, Role};
 use crate::error::{PunktfunkError, Result};
 use crate::input::InputEvent;
 use crate::quic::{
@@ -71,6 +71,9 @@ pub struct NativeClient {
    /// SHA-256 fingerprint of the certificate the host actually presented. A TOFU caller
    /// (`pin = None`) persists this and passes it as the pin from then on.
    pub host_fingerprint: [u8; 32],
+    /// The virtual gamepad backend the host actually resolved ([`Welcome::gamepad`]).
+    /// `Auto` = an older host that didn't say (assume X-Box 360, no DualSense feedback).
+    pub resolved_gamepad: GamepadPref,
 }

 impl NativeClient {
@@ -84,11 +87,13 @@ impl NativeClient {
    /// `identity`: this client's persistent self-signed identity (PEM cert + PKCS#8 key,
    /// see [`endpoint::generate_identity`]), presented via TLS client auth so a host can
    /// recognize a paired client. `None` = anonymous (rejected by hosts requiring pairing).
+    #[allow(clippy::too_many_arguments)]
    pub fn connect(
        host: &str,
        port: u16,
        mode: Mode,
        compositor: CompositorPref,
+        gamepad: GamepadPref,
        pin: Option<[u8; 32]>,
        identity: Option<(String, String)>,
        timeout: Duration,
@@ -101,7 +106,8 @@ impl NativeClient {
        let (mic_tx, mic_rx) = tokio::sync::mpsc::unbounded_channel::<(u32, u64, Vec<u8>)>();
        let (rich_input_tx, rich_input_rx) = tokio::sync::mpsc::unbounded_channel::<RichInput>();
        let (reconfig_tx, reconfig_rx) = tokio::sync::mpsc::unbounded_channel::<Mode>();
-        let (ready_tx, ready_rx) = std::sync::mpsc::channel::<Result<(Mode, [u8; 32])>>();
+        let (ready_tx, ready_rx) =
+            std::sync::mpsc::channel::<Result<(Mode, GamepadPref, [u8; 32])>>();
        let shutdown = Arc::new(AtomicBool::new(false));
        let mode_slot = Arc::new(std::sync::Mutex::new(mode));

@@ -127,6 +133,7 @@ impl NativeClient {
                    port,
                    mode,
                    compositor,
+                    gamepad,
                    pin,
                    identity,
                    frame_tx,
@@ -144,7 +151,7 @@ impl NativeClient {
            })
            .map_err(PunktfunkError::Io)?;

-        let (negotiated, fingerprint) = match ready_rx.recv_timeout(timeout) {
+        let (negotiated, resolved_gamepad, fingerprint) = match ready_rx.recv_timeout(timeout) {
            Ok(Ok(t)) => t,
            Ok(Err(e)) => return Err(e),
            Err(_) => {
@@ -166,6 +173,7 @@ impl NativeClient {
            worker: Some(worker),
            mode: mode_slot,
            host_fingerprint: fingerprint,
+            resolved_gamepad,
        })
    }

@@ -364,6 +372,7 @@ struct WorkerArgs {
    port: u16,
    mode: Mode,
    compositor: CompositorPref,
+    gamepad: GamepadPref,
    pin: Option<[u8; 32]>,
    identity: Option<(String, String)>,
    frame_tx: SyncSender<Frame>,
@@ -374,7 +383,7 @@ struct WorkerArgs {
    mic_rx: tokio::sync::mpsc::UnboundedReceiver<(u32, u64, Vec<u8>)>,
    rich_input_rx: tokio::sync::mpsc::UnboundedReceiver<RichInput>,
    reconfig_rx: tokio::sync::mpsc::UnboundedReceiver<Mode>,
-    ready_tx: std::sync::mpsc::Sender<Result<(Mode, [u8; 32])>>,
+    ready_tx: std::sync::mpsc::Sender<Result<(Mode, GamepadPref, [u8; 32])>>,
    shutdown: Arc<AtomicBool>,
    mode_slot: Arc<std::sync::Mutex<Mode>>,
 }
@@ -387,6 +396,7 @@ async fn worker_main(args: WorkerArgs) {
        port,
        mode,
        compositor,
+        gamepad,
        pin,
        identity,
        frame_tx,
@@ -437,6 +447,7 @@ async fn worker_main(args: WorkerArgs) {
                abi_version: crate::ABI_VERSION,
                mode,
                compositor,
+                gamepad,
            }
            .encode(),
        )
@@ -448,6 +459,12 @@ async fn worker_main(args: WorkerArgs) {
                "host resolved compositor"
            );
        }
+        if welcome.gamepad != GamepadPref::Auto {
+            tracing::info!(
+                gamepad = welcome.gamepad.as_str(),
+                "host resolved gamepad backend"
+            );
+        }

        // Reserve our data-plane port, then start the host.
        let probe = std::net::UdpSocket::bind("0.0.0.0:0")?;
@@ -466,18 +483,33 @@ async fn worker_main(args: WorkerArgs) {
        let transport =
            UdpTransport::connect(&format!("0.0.0.0:{udp_port}"), &host_udp.to_string())?;
        let session = Session::new(welcome.session_config(Role::Client), Box::new(transport))?;
-        Ok::<_, PunktfunkError>((conn, session, send, recv, welcome.mode, fingerprint))
+        Ok::<_, PunktfunkError>((
+            conn,
+            session,
+            send,
+            recv,
+            welcome.mode,
+            welcome.gamepad,
+            fingerprint,
+        ))
    };

-    let (conn, mut session, mut ctrl_send, mut ctrl_recv, negotiated, fingerprint) =
-        match setup.await {
-            Ok(t) => t,
-            Err(e) => {
-                let _ = ready_tx.send(Err(e));
-                return;
-            }
-        };
-    let _ = ready_tx.send(Ok((negotiated, fingerprint)));
+    let (
+        conn,
+        mut session,
+        mut ctrl_send,
+        mut ctrl_recv,
+        negotiated,
+        resolved_gamepad,
+        fingerprint,
+    ) = match setup.await {
+        Ok(t) => t,
+        Err(e) => {
+            let _ = ready_tx.send(Err(e));
+            return;
+        }
+    };
+    let _ = ready_tx.send(Ok((negotiated, resolved_gamepad, fingerprint)));

    // Input task: embedder events → QUIC datagrams.
    let input_conn = conn.clone();
@@ -130,6 +130,67 @@ impl CompositorPref {
    }
 }

+/// Which virtual gamepad the host should create for a client's pads.
+///
+/// Sent in [`Hello`](crate::quic::Hello) as a *preference* and echoed back — resolved to the
+/// backend actually chosen — in [`Welcome`](crate::quic::Welcome). `Auto` (the default) lets the
+/// host decide (its `PUNKTFUNK_GAMEPAD` env var, else X-Box 360). A concrete preference is
+/// honored only if that backend is available on the host (DualSense needs Linux UHID); otherwise
+/// the host falls back and reports the real choice in `Welcome`. The wire form is a single byte
+/// (`0 = Auto`, `1 = Xbox360`, `2 = DualSense`), appended to `Hello`/`Welcome` — older peers
+/// simply omit/ignore it.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
+pub enum GamepadPref {
+    /// Let the host pick (its `PUNKTFUNK_GAMEPAD` env var, else X-Box 360).
+    #[default]
+    Auto,
+    /// uinput X-Box 360 pad (the universal default — every game speaks XInput).
+    Xbox360,
+    /// UHID DualSense (kernel `hid-playstation`) — adaptive triggers, lightbar, touchpad, motion.
+    DualSense,
+}
+
+impl GamepadPref {
+    /// Wire byte. `0 = Auto`, `1 = Xbox360`, `2 = DualSense`.
+    pub fn to_u8(self) -> u8 {
+        match self {
+            GamepadPref::Auto => 0,
+            GamepadPref::Xbox360 => 1,
+            GamepadPref::DualSense => 2,
+        }
+    }
+
+    /// Inverse of [`to_u8`](Self::to_u8). An unknown byte decodes to `Auto` — forward-compatible:
+    /// a future concrete value a peer doesn't recognize degrades to "let the host decide".
+    pub fn from_u8(v: u8) -> Self {
+        match v {
+            1 => GamepadPref::Xbox360,
+            2 => GamepadPref::DualSense,
+            _ => GamepadPref::Auto,
+        }
+    }
+
+    /// Parse a CLI/config name (case-insensitive, with the usual aliases). `None` for an
+    /// unrecognized name, so callers can error rather than silently defaulting to `Auto`.
+    pub fn from_name(s: &str) -> Option<Self> {
+        Some(match s.trim().to_ascii_lowercase().as_str() {
+            "auto" | "default" => GamepadPref::Auto,
+            "xbox" | "xbox360" | "x360" | "uinput" => GamepadPref::Xbox360,
+            "dualsense" | "ds" | "ps5" => GamepadPref::DualSense,
+            _ => return None,
+        })
+    }
+
+    /// Canonical lowercase identifier (`"auto"`, `"xbox360"`, `"dualsense"`).
+    pub fn as_str(self) -> &'static str {
+        match self {
+            GamepadPref::Auto => "auto",
+            GamepadPref::Xbox360 => "xbox360",
+            GamepadPref::DualSense => "dualsense",
+        }
+    }
+}
+
 /// Per-block FEC parameters. Recovery count is derived from `fec_percent` exactly as
 /// GameStream does: `m = ceil(k * fec_percent / 100)`.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -63,6 +63,10 @@ pub mod gamepad {
    pub const BTN_B: u32 = 0x2000;
    pub const BTN_X: u32 = 0x4000;
    pub const BTN_Y: u32 = 0x8000;
+    /// DualSense touchpad click. Moonlight's extended-button position (`buttonFlags2`
+    /// merges in at `<< 16`, see `gamestream/gamepad.rs`), so GameStream clients land on
+    /// the same bit. Only the DualSense backend renders it; the xpad has no such button.
+    pub const BTN_TOUCHPAD: u32 = 0x10_0000;

    /// Axis ids for `InputKind::GamepadAxis`.
    pub const AXIS_LS_X: u32 = 0;
@@ -22,7 +22,9 @@
 //! reported back for persisting). The data plane adds AES-GCM on top.
 //! All integers little-endian; every message is `u16 length || payload`.

-use crate::config::{CompositorPref, Config, FecConfig, FecScheme, Mode, ProtocolPhase, Role};
+use crate::config::{
+    CompositorPref, Config, FecConfig, FecScheme, GamepadPref, Mode, ProtocolPhase, Role,
+};
 use crate::error::{PunktfunkError, Result};

 /// Protocol magic + version, first bytes of the positional handshake (Hello/Welcome/Start).
@@ -45,6 +47,11 @@ pub struct Hello {
    /// choice in [`Welcome::compositor`]. Appended to the wire form — omitted by older clients
    /// (decodes to `Auto`).
    pub compositor: CompositorPref,
+    /// Which virtual gamepad the host should create for this session's pads (`Auto` = host
+    /// decides: its `PUNKTFUNK_GAMEPAD` env var, else X-Box 360). Resolved choice echoed in
+    /// [`Welcome::gamepad`]. Appended to the wire form — omitted by older clients (decodes
+    /// to `Auto`).
+    pub gamepad: GamepadPref,
 }

 /// `host → client`: the complete session offer.
@@ -65,6 +72,11 @@ pub struct Welcome {
    /// [`Hello::compositor`] preference if available, else the host's auto-detected choice).
    /// Appended to the wire form — `Auto` when an older host omitted it (i.e. "unknown").
    pub compositor: CompositorPref,
+    /// The virtual gamepad backend the host actually resolved (the client's [`Hello::gamepad`]
+    /// preference if available, else env var / X-Box 360). A client uses this to know whether
+    /// DualSense feedback (0xCD) can arrive at all. Appended to the wire form — `Auto` when an
+    /// older host omitted it (i.e. "unknown, assume X-Box 360").
+    pub gamepad: GamepadPref,
 }

 /// `client → host`: data plane is bound, begin streaming.
@@ -359,13 +371,14 @@ pub mod pake {

 impl Hello {
    pub fn encode(&self) -> Vec<u8> {
-        let mut b = Vec::with_capacity(21);
+        let mut b = Vec::with_capacity(22);
        b.extend_from_slice(MAGIC);
        b.extend_from_slice(&self.abi_version.to_le_bytes());
        b.extend_from_slice(&self.mode.width.to_le_bytes());
        b.extend_from_slice(&self.mode.height.to_le_bytes());
        b.extend_from_slice(&self.mode.refresh_hz.to_le_bytes());
        b.push(self.compositor.to_u8()); // appended at offset 20 — older hosts read [0..20] and skip it
+        b.push(self.gamepad.to_u8()); // appended at offset 21 — same back-compat discipline
        b
    }

@@ -381,11 +394,15 @@ impl Hello {
                height: u32at(12),
                refresh_hz: u32at(16),
            },
-            // Optional trailing byte — an older client that omits it requests `Auto`.
+            // Optional trailing bytes — an older client that omits them requests `Auto`.
            compositor: b
                .get(20)
                .map(|&v| CompositorPref::from_u8(v))
                .unwrap_or_default(),
+            gamepad: b
+                .get(21)
+                .map(|&v| GamepadPref::from_u8(v))
+                .unwrap_or_default(),
        })
    }
 }
@@ -411,13 +428,14 @@ impl Welcome {
        b.extend_from_slice(&self.salt);
        b.extend_from_slice(&self.frames.to_le_bytes());
        b.push(self.compositor.to_u8()); // appended at offset 53 — older clients read [0..53] and skip it
+        b.push(self.gamepad.to_u8()); // appended at offset 54 — same back-compat discipline
        b
    }

    pub fn decode(b: &[u8]) -> Result<Welcome> {
        // Layout (LE): magic[0..4] abi[4..8] port[8..10] w[10..14] h[14..18] hz[18..22]
        // scheme[22] pct[23] max_data[24..26] shard[26..28] encrypt[28] key[29..45]
-        // salt[45..49] frames[49..53] compositor[53] (optional trailing byte).
+        // salt[45..49] frames[49..53] compositor[53] gamepad[54] (optional trailing bytes).
        if b.len() < 53 || &b[0..4] != MAGIC {
            return Err(PunktfunkError::InvalidArg("bad Welcome"));
        }
@@ -449,12 +467,16 @@ impl Welcome {
            key,
            salt,
            frames: u32at(49),
-            // Optional trailing byte — an older host that omits it leaves the resolved
-            // compositor unknown (`Auto`).
+            // Optional trailing bytes — an older host that omits them leaves the resolved
+            // compositor / gamepad backend unknown (`Auto`).
            compositor: b
                .get(53)
                .map(|&v| CompositorPref::from_u8(v))
                .unwrap_or_default(),
+            gamepad: b
+                .get(54)
+                .map(|&v| GamepadPref::from_u8(v))
+                .unwrap_or_default(),
        })
    }

@@ -1126,6 +1148,7 @@ mod tests {
            salt: [1, 2, 3, 4],
            frames: 600,
            compositor: CompositorPref::Gamescope,
+            gamepad: GamepadPref::DualSense,
        };
        assert_eq!(Welcome::decode(&w.encode()).unwrap(), w);
    }
@@ -1140,6 +1163,7 @@ mod tests {
                refresh_hz: 120,
            },
            compositor: CompositorPref::Kwin,
+            gamepad: GamepadPref::DualSense,
        };
        assert_eq!(Hello::decode(&h.encode()).unwrap(), h);
        let s = Start {
@@ -1171,11 +1195,29 @@ mod tests {
        assert_eq!(CompositorPref::from_u8(200), CompositorPref::Auto);
    }

+    #[test]
+    fn gamepad_pref_wire_and_names() {
+        for p in [
+            GamepadPref::Auto,
+            GamepadPref::Xbox360,
+            GamepadPref::DualSense,
+        ] {
+            assert_eq!(GamepadPref::from_u8(p.to_u8()), p);
+            assert_eq!(GamepadPref::from_name(p.as_str()), Some(p));
+        }
+        // Aliases + unknowns.
+        assert_eq!(GamepadPref::from_name("PS5"), Some(GamepadPref::DualSense));
+        assert_eq!(GamepadPref::from_name("x360"), Some(GamepadPref::Xbox360));
+        assert_eq!(GamepadPref::from_name("nope"), None);
+        // Unknown wire byte degrades to Auto (forward-compatible).
+        assert_eq!(GamepadPref::from_u8(200), GamepadPref::Auto);
+    }
+
    #[test]
    fn hello_welcome_compositor_back_compat() {
-        // A new client/host appends one byte; the field is optional on decode, so a legacy
-        // peer's shorter message still decodes (compositor = Auto), and a legacy peer reading a
-        // new message ignores the trailing byte. Simulate both directions by truncation.
+        // Trailing optional bytes (compositor at 20/53, gamepad at 21/54): a legacy peer's
+        // shorter message still decodes (missing fields = Auto), and a legacy peer reading a
+        // new message ignores the trailing bytes. Simulate both directions by truncation.
        let h = Hello {
            abi_version: 2,
            mode: Mode {
@@ -1184,13 +1226,19 @@ mod tests {
                refresh_hz: 60,
            },
            compositor: CompositorPref::Mutter,
+            gamepad: GamepadPref::DualSense,
        };
        let enc = h.encode();
-        assert_eq!(enc.len(), 21);
-        // Legacy (20-byte) Hello → Auto, mode intact.
+        assert_eq!(enc.len(), 22);
+        // Legacy (20-byte) Hello → both Auto, mode intact.
        let legacy = Hello::decode(&enc[..20]).unwrap();
        assert_eq!(legacy.compositor, CompositorPref::Auto);
+        assert_eq!(legacy.gamepad, GamepadPref::Auto);
        assert_eq!(legacy.mode, h.mode);
+        // Compositor-era (21-byte) Hello → compositor intact, gamepad Auto.
+        let mid = Hello::decode(&enc[..21]).unwrap();
+        assert_eq!(mid.compositor, CompositorPref::Mutter);
+        assert_eq!(mid.gamepad, GamepadPref::Auto);

        let w = Welcome {
            abi_version: 2,
@@ -1207,13 +1255,18 @@ mod tests {
            salt: [9, 8, 7, 6],
            frames: 0,
            compositor: CompositorPref::Kwin,
+            gamepad: GamepadPref::Xbox360,
        };
        let wenc = w.encode();
-        assert_eq!(wenc.len(), 54);
+        assert_eq!(wenc.len(), 55);
        let legacy_w = Welcome::decode(&wenc[..53]).unwrap();
        assert_eq!(legacy_w.compositor, CompositorPref::Auto);
+        assert_eq!(legacy_w.gamepad, GamepadPref::Auto);
        assert_eq!(legacy_w.frames, 0);
        assert_eq!(legacy_w.key, w.key);
+        let mid_w = Welcome::decode(&wenc[..54]).unwrap();
+        assert_eq!(mid_w.compositor, CompositorPref::Kwin);
+        assert_eq!(mid_w.gamepad, GamepadPref::Auto);
    }

    #[test]
@@ -1257,6 +1310,7 @@ mod tests {
                    refresh_hz: 60,
                },
                compositor: CompositorPref::Auto,
+                gamepad: GamepadPref::Auto,
            }
            .encode();
            assert!(PairRequest::decode(&h).is_err(), "abi {abi} parsed as pair");