feat: keyboard passthrough mode for keyboard-only games (2026.6.15.0-5AB1)

Add a second run-mode USB persona that presents the Pico as a USB HID
boot keyboard instead of an Xbox 360 controller, for console games that
need a keyboard such as Typing of the Dead on the Dreamcast.

- The persona is stored in the flash credential record and chosen at
  boot. Records written before this field default to controller, so
  existing boards keep working without re-provisioning.
- Switch over Wi-Fi with `couchlink keyboard` / `couchlink controller`:
  a new SET_PERSONA datagram persists the choice and reboots the board.
  `couchlink run` reads the persona from the discovery ack and streams
  the matching input type automatically.
- Keyboard input comes from Parsec-injected keystrokes via a low-level
  keyboard hook that forwards only injected events, so the host's own
  typing is ignored, the same way the controller path reads Parsec's
  virtual gamepad.
- Adds KEY_STATE/KEY_HEARTBEAT wire types carrying an 8-byte HID boot
  report, an ack persona flag, persona-aware diagnostics, and tests.

Author: RealWhyKnot

README.md

@@ -4,6 +4,8 @@ Parsec CouchLink lets a remote Parsec player use a real retro console as player
 
 The Windows host reads the Parsec virtual Xbox controller, sends the button state over Wi-Fi, and a Raspberry Pi Pico 2 W or Pico W presents that input as a wired Xbox 360 controller to a USB-to-console adapter such as USB4MAPLE.
 
+For games that need a keyboard instead -- Typing of the Dead on the Dreamcast, for one -- the same Pico can switch to a USB keyboard with `couchlink.exe keyboard` and forward the player's typing. See [Controller Routing](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Controller-Routing) for keyboard mode.
+
 **[Releases](https://github.com/RealWhyKnot/ParsecCouchLink/releases)** | **[Wiki](https://github.com/RealWhyKnot/ParsecCouchLink/wiki)** | **[Quick Start](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Quick-Start)** | **[Troubleshooting](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Troubleshooting)**
 
 ## What You Need
@@ -54,6 +56,8 @@ Useful commands:
 
 ```powershell
 .\couchlink.exe doctor
+.\couchlink.exe keyboard
+.\couchlink.exe controller
 .\couchlink.exe logs --tail
 .\couchlink.exe configure-wifi
 .\couchlink.exe recover

bridge/Cargo.toml

@@ -51,6 +51,8 @@ nusb = "0.1"
 windows = { version = "0.58", features = [
     "Win32_Foundation",
     "Win32_UI_Input_XboxController",
+    "Win32_UI_WindowsAndMessaging",
+    "Win32_System_LibraryLoader",
     "Win32_UI_Shell",
     "Win32_System_Com",
     "Win32_System_Com_StructuredStorage",

bridge/src/cmd_home.rs

@@ -1224,6 +1224,7 @@ mod tests {
                 uptime_seconds: 12,
                 unique_id_short: uid,
             },
+            persona: protocol::Persona::Controller,
         }
     }
 

bridge/src/cmd_persona.rs

@@ -0,0 +1,177 @@
+//! `couchlink keyboard` / `couchlink controller` -- switch a Pico's USB
+//! persona over Wi-Fi and optionally start streaming to it.
+//!
+//! The persona is persisted on the Pico and applied at the next boot, so
+//! switching reboots the board. Because the Pico lives plugged into the
+//! console (not the host), the switch has to happen over UDP -- the same
+//! reason `reboot-to-setup` exists. After the switch we wait for the
+//! board to rejoin Wi-Fi advertising the new persona before handing off
+//! to the streaming loop.
+
+use std::collections::HashSet;
+use std::time::{Duration, Instant};
+
+use anyhow::{bail, Result};
+
+use crate::protocol::Persona;
+use crate::{cmd_run, pico_mode, support};
+
+const DISCOVER: Duration = Duration::from_secs(5);
+const REBOOT_WAIT: Duration = Duration::from_secs(60);
+
+pub async fn run(desired: Persona, selectors: Vec<String>, all: bool, stream: bool) -> Result<()> {
+    let picos = cmd_run::discover_picos_with_auto_recovery(DISCOVER, false).await?;
+    if picos.is_empty() {
+        bail!("{}", support::no_pico_wifi_help(DISCOVER.as_secs()));
+    }
+
+    let targets = select_targets(&picos, &selectors, all)?;
+
+    let mut switched_uids = Vec::new();
+    for t in &targets {
+        if t.persona == desired {
+            println!(
+                "{} is already in {} mode.",
+                t.short_label(),
+                desired.label()
+            );
+            continue;
+        }
+        println!(
+            "Switching {} to {} mode...",
+            t.short_label(),
+            desired.label()
+        );
+        pico_mode::request_set_persona(t, desired).await?;
+        switched_uids.push(t.info.unique_id_short);
+    }
+
+    let final_targets = if switched_uids.is_empty() {
+        targets
+    } else {
+        println!(
+            "Waiting up to {}s for the Pico(s) to reboot into {} mode...",
+            REBOOT_WAIT.as_secs(),
+            desired.label()
+        );
+        let reappeared = wait_for_persona(&switched_uids, desired, REBOOT_WAIT).await?;
+        merge_targets(targets, reappeared, &switched_uids)
+    };
+
+    for t in &final_targets {
+        let mark = if t.persona == desired {
+            "ok"
+        } else {
+            "pending"
+        };
+        println!(
+            "  [{mark}] {} is now in {} mode",
+            t.short_label(),
+            t.persona.label()
+        );
+    }
+    let pending: Vec<_> = final_targets
+        .iter()
+        .filter(|t| t.persona != desired)
+        .map(|t| t.uid_hex())
+        .collect();
+    if !pending.is_empty() {
+        println!(
+            "Note: {} did not confirm {} mode yet. Give it a moment and run `couchlink test discover --all`.",
+            pending.join(", "),
+            desired.label()
+        );
+    }
+
+    if !stream {
+        println!(
+            "Run `couchlink run` to start streaming, or re-run with --stream to switch and stream."
+        );
+        return Ok(());
+    }
+
+    let ready: Vec<_> = final_targets
+        .into_iter()
+        .filter(|t| t.persona == desired)
+        .collect();
+    if ready.is_empty() {
+        bail!(
+            "no Pico is in {} mode yet; nothing to stream",
+            desired.label()
+        );
+    }
+    let routes = cmd_run::auto_routes(ready, Some((0..4).collect()))?;
+    cmd_run::stream_routes(routes, cmd_run::StreamOptions::default()).await
+}
+
+fn select_targets(
+    picos: &[cmd_run::PicoTarget],
+    selectors: &[String],
+    all: bool,
+) -> Result<Vec<cmd_run::PicoTarget>> {
+    if all {
+        return Ok(picos.to_vec());
+    }
+    if !selectors.is_empty() {
+        let mut out: Vec<cmd_run::PicoTarget> = Vec::new();
+        for s in selectors {
+            let p = cmd_run::match_pico_selector(s, picos)?;
+            if !out
+                .iter()
+                .any(|q| q.info.unique_id_short == p.info.unique_id_short)
+            {
+                out.push(p);
+            }
+        }
+        return Ok(out);
+    }
+    match picos {
+        [one] => Ok(vec![one.clone()]),
+        [] => bail!("no Pico found on Wi-Fi"),
+        _ => bail!("more than one Pico found; pass a UID/IP/board selector or --all"),
+    }
+}
+
+async fn wait_for_persona(
+    uids: &[u32],
+    desired: Persona,
+    timeout: Duration,
+) -> Result<Vec<cmd_run::PicoTarget>> {
+    let want: HashSet<u32> = uids.iter().copied().collect();
+    let deadline = Instant::now() + timeout;
+    loop {
+        let picos = cmd_run::discover_picos(Duration::from_secs(2)).await?;
+        let matched: Vec<cmd_run::PicoTarget> = picos
+            .into_iter()
+            .filter(|p| want.contains(&p.info.unique_id_short))
+            .collect();
+        let all_confirmed = want.iter().all(|uid| {
+            matched
+                .iter()
+                .any(|p| p.info.unique_id_short == *uid && p.persona == desired)
+        });
+        if all_confirmed {
+            return Ok(matched);
+        }
+        if Instant::now() >= deadline {
+            return Ok(matched);
+        }
+        tokio::time::sleep(Duration::from_millis(500)).await;
+    }
+}
+
+fn merge_targets(
+    original: Vec<cmd_run::PicoTarget>,
+    reappeared: Vec<cmd_run::PicoTarget>,
+    switched_uids: &[u32],
+) -> Vec<cmd_run::PicoTarget> {
+    let switched: HashSet<u32> = switched_uids.iter().copied().collect();
+    // Keep the originals that weren't switched, then add whatever the
+    // re-discovery turned up for the switched ones.
+    let mut out: Vec<cmd_run::PicoTarget> = original
+        .into_iter()
+        .filter(|p| !switched.contains(&p.info.unique_id_short))
+        .collect();
+    out.extend(reappeared);
+    out
+}