feat(clients/decky): SteamOS Gaming-Mode launcher plugin (spike)

A Decky Loader plugin so a Steam Deck / SteamOS box can launch the punktfunk
client from Gaming Mode using REAL Steam UI components (it runs inside Steam's
CEF, so the panel is built from @decky/ui — the literal Big Picture primitives,
not a replica).

- Frontend (src/index.tsx, @decky/api + @decky/ui): a Quick Access Menu panel —
  Refresh → discover hosts, a native list (name, ip:port, pairing flag), tap to
  connect with a status toast, Disconnect.
- Backend (main.py): discover() shells `avahi-browse -rpt _punktfunk._udp` and
  parses the host's advertised TXT keys (proto/fp/pair/id from discovery.rs),
  dedup by id preferring IPv4; connect() resolves + spawns
  `punktfunk-client --connect host:port` (gamescope composites its video like a
  game), tracking the child; disconnect() terminates it.
- Mirrors the current official Decky template (the API moved to @decky/ui +
  @decky/api). Frontend builds clean (pnpm build → dist/index.js); main.py
  py_compiles. dist/ + node_modules gitignored — build on the Deck per README.

Spike scope: launcher only, runtime untested (no Deck here). Next on this track:
the in-stream Quick-Access overlay (volume/disconnect/stats over the running
stream) and a fuller real-components UI. Client decode on the AMD Deck is the
existing VAAPI path; the host-encode VAAPI gap is separate (NVIDIA host = NVENC).

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

clients/decky/main.py

@@ -0,0 +1,271 @@
+"""
+punktfunk Decky plugin — backend.
+
+Bridges the Gaming-Mode Quick Access panel (``src/index.tsx``) to two host-side
+operations:
+
+* **discover()** — browse the LAN over mDNS for punktfunk/1 hosts advertising the
+  ``_punktfunk._udp`` service, returning name / ip:port / pairing-requirement / cert
+  fingerprint for each. Implemented by shelling out to ``avahi-browse`` (SteamOS, Bazzite
+  and most Linux distros ship ``avahi-daemon``); see :func:`Plugin.discover`.
+* **connect(host, port)** / **disconnect()** — launch / kill the native GTK4 client
+  (``punktfunk-client --connect host:port``). The child PID is tracked so a later
+  :func:`Plugin.disconnect` (or plugin unload) can terminate it.
+
+The TXT-record keys parsed here (``proto`` / ``fp`` / ``pair`` / ``id``) are defined by the
+host advert in ``crates/punktfunk-host/src/discovery.rs``.
+"""
+
+import asyncio
+import shutil
+from pathlib import Path
+
+import decky
+
+# The native punktfunk/1 client binary (the GTK4/libadwaita Linux client, crate
+# ``punktfunk-client-linux``). It is resolved at runtime from PATH and a handful of common
+# install locations (see :func:`_resolve_client`). If none exist we fall back to this bare
+# name and let the spawn fail loudly — install the client on the Deck (.deb / RPM / flatpak)
+# or symlink it into ~/.local/bin.
+#
+# TODO: once a Steam Deck / SteamOS install path for punktfunk-client is settled (likely a
+# flatpak, since SteamOS is image-based and /usr is read-only), pin the canonical path here.
+CLIENT_BINARY = "punktfunk-client"
+
+# Service type advertised by punktfunk/1 hosts (matches NATIVE_SERVICE in the Rust host).
+SERVICE_TYPE = "_punktfunk._udp"
+
+# Candidate locations probed (in order) when the binary is not on PATH. ``$HOME`` is the
+# effective user's home as provided by decky.
+_CLIENT_CANDIDATES = [
+    "/usr/bin/punktfunk-client",
+    "/usr/local/bin/punktfunk-client",
+    str(Path(decky.HOME) / ".local" / "bin" / "punktfunk-client"),
+    # Flatpak: launched via `flatpak run` rather than a path — handled in _resolve_client.
+]
+
+
+def _resolve_client() -> list[str]:
+    """Return the argv prefix used to launch the native client.
+
+    Resolution order: PATH → well-known absolute paths → flatpak (if the app id is
+    installed) → bare binary name (so the eventual spawn fails with a clear error).
+    """
+    on_path = shutil.which(CLIENT_BINARY)
+    if on_path:
+        return [on_path]
+
+    for candidate in _CLIENT_CANDIDATES:
+        if Path(candidate).exists():
+            return [candidate]
+
+    # Flatpak fallback. The app id is a guess until a flatpak is actually published;
+    # `flatpak run <id>` is a no-op-ish failure if it is not installed, which surfaces as a
+    # spawn error the user can act on.
+    flatpak = shutil.which("flatpak")
+    if flatpak:
+        return [flatpak, "run", "earth.buehler.punktfunk.Client"]
+
+    decky.logger.warning(
+        "punktfunk-client not found on PATH or in %s; falling back to bare name",
+        _CLIENT_CANDIDATES,
+    )
+    return [CLIENT_BINARY]
+
+
+def _parse_avahi_browse(stdout: str) -> list[dict]:
+    """Parse ``avahi-browse -rpt`` output into a list of host dicts.
+
+    ``avahi-browse -r`` resolves services; ``-p`` makes the output parseable (one record
+    per line, semicolon-separated, fields escaped with ``\\``); ``-t`` terminates after the
+    initial cache dump instead of running forever.
+
+    Resolved records start with ``=`` and have the columns::
+
+        =;iface;protocol;name;type;domain;hostname;address;port;txt
+
+    where ``txt`` is a space-separated list of ``"key=value"`` tokens, each already wrapped
+    in double quotes by avahi, e.g. ``"proto=punktfunk/1" "fp=ab12..." "pair=required"``.
+
+    We dedup on the host advert ``id`` TXT key (a host re-advertises across interfaces /
+    IPv4+IPv6, producing several ``=`` lines for one logical host); when ``id`` is absent we
+    fall back to ``host:port``.
+    """
+    out: dict[str, dict] = {}
+    for raw in stdout.splitlines():
+        line = raw.strip()
+        if not line.startswith("="):
+            continue
+        # Split on unescaped ';'. avahi escapes literal ';' inside fields as '\;', so a
+        # simple replace-guard split is adequate for the fixed 10-column layout.
+        parts = line.replace("\\;", "\x00").split(";")
+        parts = [p.replace("\x00", ";") for p in parts]
+        if len(parts) < 9:
+            continue
+
+        name = parts[3]
+        # parts[4] is the service type, parts[5] the domain.
+        address = parts[7]
+        port_str = parts[8]
+        txt = parts[9] if len(parts) > 9 else ""
+
+        try:
+            port = int(port_str)
+        except ValueError:
+            port = 0
+
+        # Parse TXT tokens: each is a quoted "key=value".
+        props: dict[str, str] = {}
+        for token in _split_txt(txt):
+            if "=" in token:
+                k, v = token.split("=", 1)
+                props[k] = v
+
+        # Only surface actual punktfunk/1 adverts.
+        if props.get("proto") and not props["proto"].startswith("punktfunk/"):
+            continue
+
+        entry = {
+            "name": name,
+            "host": address,
+            "port": port,
+            "pair": props.get("pair", "optional"),
+            "fp": props.get("fp", ""),
+            "proto": props.get("proto", ""),
+        }
+        key = props.get("id") or f"{address}:{port}"
+        # Prefer an IPv4 record over IPv6 for the user-facing host string when both exist.
+        existing = out.get(key)
+        if existing is None or (":" in existing["host"] and ":" not in address):
+            out[key] = entry
+
+    return list(out.values())
+
+
+def _split_txt(txt: str) -> list[str]:
+    """Split an avahi TXT column into tokens, honouring the ``"key=value"`` quoting.
+
+    avahi prints each TXT item wrapped in double quotes and space-separated, e.g.::
+
+        "proto=punktfunk/1" "fp=ab12cd" "pair=required" "id=host-1"
+
+    A value can legitimately contain spaces, so we split on the quote boundaries rather
+    than on whitespace.
+    """
+    tokens: list[str] = []
+    cur: list[str] = []
+    in_quote = False
+    for ch in txt:
+        if ch == '"':
+            if in_quote:
+                tokens.append("".join(cur))
+                cur = []
+            in_quote = not in_quote
+        elif in_quote:
+            cur.append(ch)
+    if cur:
+        tokens.append("".join(cur))
+    return tokens
+
+
+class Plugin:
+    # Tracks the launched native client so disconnect()/_unload can terminate it.
+    _client: asyncio.subprocess.Process | None = None
+    _connected_host: str | None = None
+
+    async def discover(self) -> list[dict]:
+        """Browse the LAN for punktfunk/1 hosts. Returns ``[{name, host, port, pair, fp}]``."""
+        avahi = shutil.which("avahi-browse")
+        if not avahi:
+            decky.logger.error("avahi-browse not found; install avahi for host discovery")
+            return []
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                avahi,
+                "-rpt",
+                SERVICE_TYPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=8.0)
+            except asyncio.TimeoutError:
+                proc.kill()
+                decky.logger.warning("avahi-browse timed out")
+                return []
+        except Exception:  # noqa: BLE001 - surface any spawn failure as "no hosts"
+            decky.logger.exception("avahi-browse failed")
+            return []
+
+        if stderr:
+            decky.logger.debug("avahi-browse stderr: %s", stderr.decode(errors="replace"))
+
+        hosts = _parse_avahi_browse(stdout.decode(errors="replace"))
+        decky.logger.info("discovered %d punktfunk host(s)", len(hosts))
+        return hosts
+
+    async def connect(self, host: str, port: int) -> dict:
+        """Launch the native client against ``host:port``. Returns ``{ok, host, error?}``."""
+        # Tear down any prior session first.
+        await self.disconnect()
+
+        argv = _resolve_client() + ["--connect", f"{host}:{port}"]
+        decky.logger.info("launching client: %s", " ".join(argv))
+        try:
+            self._client = await asyncio.create_subprocess_exec(
+                *argv,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+        except FileNotFoundError:
+            decky.logger.error("client binary not found: %s", argv[0])
+            return {"ok": False, "host": f"{host}:{port}", "error": "client-not-found"}
+        except Exception as exc:  # noqa: BLE001
+            decky.logger.exception("failed to launch client")
+            return {"ok": False, "host": f"{host}:{port}", "error": str(exc)}
+
+        self._connected_host = f"{host}:{port}"
+        decky.logger.info("client launched (pid %s) -> %s", self._client.pid, self._connected_host)
+        return {"ok": True, "host": self._connected_host}
+
+    async def disconnect(self) -> dict:
+        """Terminate the launched native client, if any."""
+        proc = self._client
+        self._client = None
+        host = self._connected_host
+        self._connected_host = None
+        if proc is None or proc.returncode is not None:
+            return {"ok": True, "host": None}
+
+        decky.logger.info("disconnecting client (pid %s)", proc.pid)
+        try:
+            proc.terminate()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                decky.logger.warning("client did not exit; killing (pid %s)", proc.pid)
+                proc.kill()
+                await proc.wait()
+        except ProcessLookupError:
+            pass
+        except Exception:  # noqa: BLE001
+            decky.logger.exception("error terminating client")
+        return {"ok": True, "host": host}
+
+    async def status(self) -> dict:
+        """Return the current connection status for UI refresh on panel open."""
+        connected = self._client is not None and self._client.returncode is None
+        return {"connected": connected, "host": self._connected_host if connected else None}
+
+    # ---- Decky lifecycle ----
+
+    async def _main(self):
+        decky.logger.info("punktfunk plugin loaded")
+
+    async def _unload(self):
+        decky.logger.info("punktfunk plugin unloading; tearing down client")
+        await self.disconnect()
+
+    async def _uninstall(self):
+        decky.logger.info("punktfunk plugin uninstalled")