feat(decky): pinned-games library + self-update robustness; fix gamepad tab-nav

Decky client batch:
- Pinned games / library picker: per-host game grid (GamePickerModal),
  pin/unpin, one-tap streams surfaced on the Hosts tab and QAM
  (usePins/streamPin/resolvePinHost, new src/library.tsx).
- Self-update + client-update plumbing (main.py check_update, hooks.ts
  applyUpdate) with a CA-bundle-resolving SSL context and per-channel
  manifest polling; steam.ts / punktfunkrun.sh launch tweaks.
- scripts/test-backend.py harness for the backend RPCs; README refresh.

Fix: the fullscreen page wrapped <Tabs> in an overflow-visible box, so
Valve's L1/R1 tab slide + autoFocusContents scrollIntoView panned
#GamepadUI itself — the whole Steam UI slid left until a tab was clicked.
Clip the Tabs wrapper (overflow:hidden), matching Valve's own Tabs
containers. (On-glass verification pending — Deck offline this session.)

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

clients/decky/src/backend.ts

@@ -9,6 +9,43 @@ export interface Host {
   fp: string; // host cert SHA-256 fingerprint (lowercase hex) from the mDNS advert
   proto: string; // advertised protocol, e.g. "punktfunk/1"
   paired: boolean; // whether THIS device has already PIN-paired this host (by fingerprint)
+  id: string; // the host's stable instance id (mDNS TXT `id`; "" when not advertised)
+  mgmt: number; // management-API port (mDNS TXT `mgmt`; 0 = not advertised → default 47990)
+}
+
+// One title from a host's game library (the flatpak client's --library TSV, parsed by the
+// backend). `id` is store-qualified (steam:<appid> / custom:<id>) and doubles as the
+// launch handle (PF_LAUNCH → the session Hello).
+export interface GameEntry {
+  id: string;
+  store: string; // "steam" | "custom" | "heroic" | "lutris" | …
+  title: string;
+}
+
+export interface LibraryResult {
+  ok: boolean;
+  games?: GameEntry[];
+  // "flatpak-not-found" | "timeout" | "not-paired" | "pin-mismatch" | "unreachable" |
+  // "http" | "client-outdated" | "client-error"
+  error?: string;
+  detail?: string; // the client's own one-line reason, for the generic error copy
+}
+
+// A pinned game — a one-tap stream row in the QAM. The host is identified primarily by
+// cert fingerprint (survives IP changes; pairing is fp-keyed too), with the stored
+// address as the launch fallback when the host isn't currently advertising.
+export interface PinnedGame {
+  game_id: string;
+  title: string;
+  store: string;
+  host_fp: string;
+  host_id: string;
+  host_name: string;
+  host: string;
+  port: number;
+  mgmt: number;
+  added_at: number; // unix seconds
+  paired?: boolean; // annotated by get_pins from the client's known-hosts store
 }
 
 export interface PairResult {
@@ -68,6 +105,16 @@ export const pair = callable<
   [host: string, port: number, pin: string, name: string],
   PairResult
 >("pair");
+// Fetch a paired host's game library (headless flatpak --library; can take seconds on a
+// cold client start — show a spinner). Pass fp whenever known so the pin can't degrade.
+export const library = callable<
+  [host: string, mgmt_port: number, fp: string],
+  LibraryResult
+>("library");
+export const getPins = callable<[], { pins: PinnedGame[] }>("get_pins");
+export const setPins = callable<[pins: PinnedGame[]], { ok: boolean; error?: string }>(
+  "set_pins",
+);
 export const runnerInfo = callable<[], RunnerInfo>("runner_info");
 export const shortcutArt = callable<[], ShortcutArt>("shortcut_art");
 export const getSettings = callable<[], StreamSettings>("get_settings");

clients/decky/src/hooks.ts

@@ -2,8 +2,18 @@
 import { toaster } from "@decky/api";
 import { Navigation } from "@decky/ui";
 import { useCallback, useEffect, useState } from "react";
-import { checkUpdate, discover, Host, updateClient, UpdateInfo } from "./backend";
-import { launchStream } from "./steam";
+import {
+  checkUpdate,
+  discover,
+  GameEntry,
+  getPins,
+  Host,
+  PinnedGame,
+  setPins as setPinsBackend,
+  updateClient,
+  UpdateInfo,
+} from "./backend";
+import { LaunchOpts, launchStream } from "./steam";
 
 export const DOCS_URL = "https://docs.punktfunk.unom.io/docs/steam-deck";
 
@@ -169,12 +179,153 @@ export async function applyUpdate(
 // ----------------------------------------------------------------------------------------
 // Stream launch — via the hidden Steam shortcut (see steam.ts for why).
 // ----------------------------------------------------------------------------------------
-export async function startStream(h: Host): Promise<void> {
+export async function startStream(
+  h: Host,
+  opts: LaunchOpts = {},
+  label?: string,
+): Promise<void> {
   try {
-    await launchStream(h.host, h.port);
+    await launchStream(h.host, h.port, opts);
     Navigation.CloseSideMenus();
-    toaster.toast({ title: "Punktfunk", body: `Starting stream — ${h.name}` });
+    toaster.toast({ title: "Punktfunk", body: `Starting ${label ?? "stream"} — ${h.name}` });
   } catch (e) {
     toaster.toast({ title: "Punktfunk", body: `Launch failed: ${e}` });
   }
 }
+
+/** Open the GTK client's gamepad library launcher for a host (`--browse` via PF_BROWSE). */
+export async function startBrowse(h: Host): Promise<void> {
+  try {
+    await launchStream(h.host, h.port, { browse: true, mgmt: h.mgmt });
+    Navigation.CloseSideMenus();
+    toaster.toast({ title: "Punktfunk", body: `Opening library — ${h.name}` });
+  } catch (e) {
+    toaster.toast({ title: "Punktfunk", body: `Launch failed: ${e}` });
+  }
+}
+
+// ----------------------------------------------------------------------------------------
+// Pinned games — the QAM's one-tap game rows, persisted by the backend next to the
+// client's config (survives plugin reinstalls).
+// ----------------------------------------------------------------------------------------
+export interface PinsApi {
+  pins: PinnedGame[];
+  addPin: (h: Host, g: GameEntry) => void;
+  removePin: (hostFp: string, gameId: string) => void;
+  isPinned: (hostFp: string, gameId: string) => boolean;
+  /** Refresh a pin's stored address from a live advert (hosts change IPs). */
+  updatePinHost: (pin: PinnedGame, h: Host) => void;
+  refresh: () => Promise<void>;
+}
+
+export function usePins(): PinsApi {
+  const [pins, setPins] = useState<PinnedGame[]>([]);
+
+  const refresh = useCallback(async () => {
+    try {
+      setPins((await getPins()).pins);
+    } catch {
+      /* backend unavailable — keep the current view */
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  // Optimistic local state; the backend validates/dedups and is re-read on failure.
+  const save = useCallback(
+    (next: PinnedGame[]) => {
+      setPins(next);
+      setPinsBackend(next).catch(() => void refresh());
+    },
+    [refresh],
+  );
+
+  const addPin = useCallback(
+    (h: Host, g: GameEntry) => {
+      const pin: PinnedGame = {
+        game_id: g.id,
+        title: g.title,
+        store: g.store,
+        host_fp: h.fp,
+        host_id: h.id,
+        host_name: h.name,
+        host: h.host,
+        port: h.port,
+        mgmt: h.mgmt,
+        added_at: Math.floor(Date.now() / 1000),
+        paired: h.paired,
+      };
+      save([
+        ...pins.filter((p) => !(p.host_fp === pin.host_fp && p.game_id === pin.game_id)),
+        pin,
+      ]);
+    },
+    [pins, save],
+  );
+
+  const removePin = useCallback(
+    (hostFp: string, gameId: string) => {
+      save(pins.filter((p) => !(p.host_fp === hostFp && p.game_id === gameId)));
+    },
+    [pins, save],
+  );
+
+  const isPinned = useCallback(
+    (hostFp: string, gameId: string) =>
+      pins.some((p) => p.host_fp === hostFp && p.game_id === gameId),
+    [pins],
+  );
+
+  const updatePinHost = useCallback(
+    (pin: PinnedGame, h: Host) => {
+      if (pin.host === h.host && pin.port === h.port && pin.mgmt === h.mgmt) {
+        return;
+      }
+      save(
+        pins.map((p) =>
+          p.host_fp === pin.host_fp && p.game_id === pin.game_id
+            ? { ...p, host: h.host, port: h.port, mgmt: h.mgmt, host_name: h.name }
+            : p,
+        ),
+      );
+    },
+    [pins, save],
+  );
+
+  return { pins, addPin, removePin, isPinned, updatePinHost, refresh };
+}
+
+/**
+ * The host a pin should launch against right now: match the live mDNS scan by cert
+ * fingerprint first (pairing is fp-keyed, survives IP changes), then by the host's stable
+ * id, else fall back to the stored address (host offline or scan flaky — still launch).
+ */
+export function resolvePinHost(
+  pin: PinnedGame,
+  live: Host[],
+): { host: Host; online: boolean } {
+  const fp = pin.host_fp.toLowerCase();
+  const match =
+    (fp && live.find((h) => h.fp && h.fp.toLowerCase() === fp)) ||
+    (pin.host_id && live.find((h) => h.id && h.id === pin.host_id)) ||
+    undefined;
+  if (match) {
+    return { host: match, online: true };
+  }
+  return {
+    host: {
+      name: pin.host_name || pin.host,
+      host: pin.host,
+      port: pin.port,
+      pair: pin.paired ? "optional" : "required",
+      fp: pin.host_fp,
+      proto: "",
+      paired: !!pin.paired,
+      id: pin.host_id,
+      mgmt: pin.mgmt,
+    },
+    online: false,
+  };
+}

clients/decky/src/index.tsx

@@ -12,18 +12,30 @@ import {
 } from "@decky/ui";
 import { definePlugin, routerHook } from "@decky/api";
 import { FC } from "react";
-import { FaDownload, FaLock, FaLockOpen, FaSyncAlt, FaTv } from "react-icons/fa";
+import { FaDownload, FaLock, FaLockOpen, FaPlay, FaSyncAlt, FaTv } from "react-icons/fa";
 import { PluginErrorBoundary } from "./boundary";
-import { applyUpdate, checkForUpdatesNow, hasUpdate, startStream, useHosts, useUpdate } from "./hooks";
+import {
+  applyUpdate,
+  checkForUpdatesNow,
+  hasUpdate,
+  resolvePinHost,
+  startStream,
+  useHosts,
+  usePins,
+  useUpdate,
+} from "./hooks";
+import { streamPin } from "./library";
 import { PunktfunkRoute, ROUTE } from "./page";
 import { PairModal } from "./pair";
 
 // ----------------------------------------------------------------------------------------
-// QAM panel — quick status + entry into the full page + one-tap stream for known hosts.
+// QAM panel — quick status + entry into the full page + one-tap stream for known hosts
+// and pinned games.
 // ----------------------------------------------------------------------------------------
 const QamPanel: FC = () => {
   const { hosts, scanning, refresh } = useHosts();
   const { info: update, checking, check } = useUpdate();
+  const pins = usePins();
 
   return (
     <>
@@ -65,6 +77,31 @@ const QamPanel: FC = () => {
         </PanelSectionRow>
       </PanelSection>
 
+      {/* Pinned games — the "jump straight into Playnite" rows. Pin games from a host's
+          picker (fullscreen page → host row → games button). */}
+      {pins.pins.length > 0 && (
+        <PanelSection title="Games">
+          {pins.pins.map((pin) => {
+            const { online } = resolvePinHost(pin, hosts);
+            return (
+              <PanelSectionRow key={`${pin.host_fp}:${pin.game_id}`}>
+                <ButtonItem
+                  layout="below"
+                  onClick={() => streamPin(pin, hosts, pins)}
+                  label={pin.title}
+                  description={`${pin.host_name}${online ? "" : " · offline?"}${
+                    pin.paired ? "" : " · pairing required"
+                  }`}
+                >
+                  <FaPlay style={{ marginRight: "0.5em" }} />
+                  Stream
+                </ButtonItem>
+              </PanelSectionRow>
+            );
+          })}
+        </PanelSection>
+      )}
+
       <PanelSection title="Hosts">
         <PanelSectionRow>
           <ButtonItem layout="below" onClick={refresh} disabled={scanning}>

clients/decky/src/library.tsx

@@ -0,0 +1,219 @@
+// The per-host game picker + pinned-game launch helper. The picker fetches a paired
+// host's library through the backend (headless flatpak --library — a cold client start
+// can take seconds, hence the explicit spinner copy) and pins titles as one-tap rows in
+// the QAM's Games section; its header also launches the GTK client's on-screen gamepad
+// library (`--browse`).
+import { DialogButton, Field, Focusable, ModalRoot, Spinner, showModal } from "@decky/ui";
+import { CSSProperties, FC, useEffect, useState } from "react";
+import { FaThLarge, FaTv } from "react-icons/fa";
+import { GameEntry, Host, library, LibraryResult, PinnedGame } from "./backend";
+import { PinsApi, resolvePinHost, startBrowse, startStream } from "./hooks";
+import { isSafeLaunchId } from "./steam";
+import { PairModal } from "./pair";
+
+/** Human store tag (mirrors the GTK client's `store_label`). */
+export function storeLabel(store: string): string {
+  switch (store) {
+    case "steam":
+      return "Steam";
+    case "custom":
+      return "Custom";
+    case "heroic":
+      return "Heroic";
+    case "lutris":
+      return "Lutris";
+    case "epic":
+      return "Epic";
+    case "gog":
+      return "GOG";
+    case "xbox":
+      return "Xbox";
+    default:
+      return "Game";
+  }
+}
+
+/**
+ * Stream a pinned game: resolve the host from the live scan (fp → id → stored address),
+ * opportunistically refresh a drifted stored address, and route through pairing first if
+ * this device is no longer paired with the host.
+ */
+export function streamPin(pin: PinnedGame, live: Host[], pins: PinsApi): void {
+  const { host, online } = resolvePinHost(pin, live);
+  if (online) {
+    pins.updatePinHost(pin, host); // no-op unless the address actually drifted
+  }
+  if (!pin.paired) {
+    showModal(
+      <PairModal
+        host={host}
+        onPaired={() => {
+          void pins.refresh(); // pick up the now-paired annotation
+          void startStream(host, { launchId: pin.game_id }, pin.title);
+        }}
+      />,
+    );
+    return;
+  }
+  void startStream(host, { launchId: pin.game_id }, pin.title);
+}
+
+const pickButton: CSSProperties = {
+  width: "fit-content",
+  minWidth: "5em",
+  flexShrink: 0,
+};
+
+// Copy per backend error code (LibraryResult.error); `detail` covers the generic case.
+function errorCopy(res: LibraryResult): string {
+  switch (res.error) {
+    case "not-paired":
+      return "This Deck isn't paired with the host — pair first, then browse its library.";
+    case "pin-mismatch":
+      return "The host's identity changed — re-pair to re-establish trust.";
+    case "unreachable":
+      return "Couldn't reach the host's management API. Is the host online and up to date?";
+    case "timeout":
+      return "Timed out talking to the host — try again.";
+    case "flatpak-not-found":
+      return "The Punktfunk client isn't installed (flatpak io.unom.Punktfunk).";
+    case "client-outdated":
+      return "The installed client is too old for library browsing — update it from the About tab.";
+    default:
+      return res.detail || "Couldn't fetch the library.";
+  }
+}
+
+// ----------------------------------------------------------------------------------------
+// The picker modal: "open on screen" + a pin-toggle list of the host's games.
+// ----------------------------------------------------------------------------------------
+export const GamePickerModal: FC<{
+  host: Host;
+  pins: PinsApi;
+  clientUpdatePending?: boolean;
+  closeModal?: () => void;
+}> = ({ host, pins, clientUpdatePending, closeModal }) => {
+  const [result, setResult] = useState<LibraryResult | null>(null);
+  const [attempt, setAttempt] = useState(0); // bump to refetch (retry / after pairing)
+
+  useEffect(() => {
+    let stale = false;
+    setResult(null);
+    library(host.host, host.mgmt, host.fp)
+      .then((res) => {
+        if (!stale) setResult(res);
+      })
+      .catch((e) => {
+        if (!stale) setResult({ ok: false, error: "client-error", detail: String(e) });
+      });
+    return () => {
+      stale = true;
+    };
+  }, [host.host, host.mgmt, host.fp, attempt]);
+
+  const games = (result?.ok && result.games) || [];
+  const sorted = [...games].sort((a, b) => a.title.localeCompare(b.title));
+
+  return (
+    <ModalRoot closeModal={closeModal}>
+      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.4em" }}>
+        {host.name} — Games
+      </div>
+
+      <Field
+        label="Open library on screen"
+        description="Browse this host's games with the controller, full screen"
+        childrenContainerWidth="max"
+      >
+        <DialogButton
+          style={pickButton}
+          onClick={() => {
+            closeModal?.();
+            void startBrowse(host);
+          }}
+        >
+          <FaTv style={{ marginRight: "0.4em" }} />
+          Open
+        </DialogButton>
+      </Field>
+
+      {clientUpdatePending && (
+        <Field
+          focusable={false}
+          description="A client update is available — direct game launch and on-screen browsing need the latest client."
+        />
+      )}
+
+      {result === null && (
+        <Field
+          focusable={false}
+          label={
+            <span style={{ display: "inline-flex", alignItems: "center", gap: "0.6em" }}>
+              <Spinner style={{ height: "1em" }} />
+              Fetching the library…
+            </span>
+          }
+          description="This starts the client headlessly — a cold start can take a few seconds."
+        />
+      )}
+
+      {result !== null && !result.ok && (
+        <Field label="Couldn't fetch the library" description={errorCopy(result)} childrenContainerWidth="max">
+          <Focusable style={{ display: "flex", gap: "0.5em", justifyContent: "flex-end" }}>
+            {result.error === "not-paired" && (
+              <DialogButton
+                style={pickButton}
+                onClick={() =>
+                  showModal(<PairModal host={host} onPaired={() => setAttempt((n) => n + 1)} />)
+                }
+              >
+                Pair
+              </DialogButton>
+            )}
+            <DialogButton style={pickButton} onClick={() => setAttempt((n) => n + 1)}>
+              Retry
+            </DialogButton>
+          </Focusable>
+        </Field>
+      )}
+
+      {result?.ok && sorted.length === 0 && (
+        <Field
+          focusable={false}
+          label="No games found"
+          description="Install Steam titles or add custom entries in the host's web console."
+        />
+      )}
+
+      {sorted.length > 0 && (
+        <div style={{ maxHeight: "55vh", overflowY: "auto" }}>
+          {sorted.map((g: GameEntry) => {
+            const pinned = pins.isPinned(host.fp, g.id);
+            const safe = isSafeLaunchId(g.id);
+            return (
+              <Field
+                key={g.id}
+                label={g.title}
+                description={
+                  storeLabel(g.store) + (safe ? "" : " · unsupported id — can't be pinned")
+                }
+                childrenContainerWidth="max"
+              >
+                <DialogButton
+                  style={pickButton}
+                  disabled={!safe}
+                  onClick={() =>
+                    pinned ? pins.removePin(host.fp, g.id) : pins.addPin(host, g)
+                  }
+                >
+                  <FaThLarge style={{ marginRight: "0.4em" }} />
+                  {pinned ? "Unpin" : "Pin"}
+                </DialogButton>
+              </Field>
+            );
+          })}
+        </div>
+      )}
+    </ModalRoot>
+  );
+};

clients/decky/src/page.tsx

@@ -21,18 +21,23 @@ import {
   FaLockOpen,
   FaPlay,
   FaSyncAlt,
+  FaThLarge,
 } from "react-icons/fa";
 import { Host, UpdateInfo, killStream } from "./backend";
 import { PluginErrorBoundary } from "./boundary";
 import {
   DOCS_URL,
+  PinsApi,
   applyUpdate,
   checkForUpdatesNow,
   hasUpdate,
+  resolvePinHost,
   startStream,
   useHosts,
+  usePins,
   useUpdate,
 } from "./hooks";
+import { GamePickerModal, storeLabel, streamPin } from "./library";
 import { PairModal } from "./pair";
 import { SettingsSection } from "./settings";
 import { stopStream } from "./steam";
@@ -118,7 +123,11 @@ const HostDetailsModal: FC<{ host: Host; closeModal?: () => void }> = ({
 // ----------------------------------------------------------------------------------------
 // One host row: status icon + address, details / pair / stream actions.
 // ----------------------------------------------------------------------------------------
-const HostRow: FC<{ host: Host; onPaired: () => void }> = ({ host, onPaired }) => {
+const HostRow: FC<{ host: Host; onPaired: () => void; onGames: () => void }> = ({
+  host,
+  onPaired,
+  onGames,
+}) => {
   // The host's policy is `pair=required`, but if THIS device is already paired we don't need to
   // pair again — show it as trusted and go straight to Stream.
   const needsPair = host.pair === "required" && !host.paired;
@@ -142,6 +151,9 @@ const HostRow: FC<{ host: Host; onPaired: () => void }> = ({ host, onPaired }) =
         >
           <FaInfoCircle />
         </DialogButton>
+        <DialogButton style={iconButton} onClick={onGames}>
+          <FaThLarge />
+        </DialogButton>
         {needsPair && (
           <DialogButton
             style={{ ...actionButton, minWidth: "5em" }}
@@ -163,7 +175,9 @@ const HostsTab: FC<{
   hosts: Host[];
   scanning: boolean;
   refresh: () => void;
-}> = ({ hosts, scanning, refresh }) => (
+  pins: PinsApi;
+  clientUpdatePending: boolean;
+}> = ({ hosts, scanning, refresh, pins, clientUpdatePending }) => (
   <div style={tabScroll}>
     <Field
       label="Discover"
@@ -193,8 +207,55 @@ const HostsTab: FC<{
       />
     )}
     {hosts.map((h) => (
-      <HostRow key={h.fp || `${h.host}:${h.port}`} host={h} onPaired={refresh} />
+      <HostRow
+        key={h.fp || `${h.host}:${h.port}`}
+        host={h}
+        onPaired={refresh}
+        onGames={() =>
+          showModal(
+            <GamePickerModal host={h} pins={pins} clientUpdatePending={clientUpdatePending} />,
+          )
+        }
+      />
     ))}
+
+    {/* Pinned games — also the cleanup surface for pins whose host is gone from the scan. */}
+    {pins.pins.length > 0 && (
+      <>
+        <Field
+          focusable={false}
+          label="Pinned games"
+          description="One-tap streams — they also live in the quick-access menu"
+          bottomSeparator="standard"
+        />
+        {pins.pins.map((pin) => {
+          const { online } = resolvePinHost(pin, hosts);
+          return (
+            <Field
+              key={`${pin.host_fp}:${pin.game_id}`}
+              label={pin.title}
+              description={`${storeLabel(pin.store)} · ${pin.host_name}${
+                online ? "" : " · offline?"
+              }${pin.paired ? "" : " · pairing required"}`}
+              childrenContainerWidth="max"
+            >
+              <Focusable style={{ display: "flex", gap: "0.5em", justifyContent: "flex-end" }}>
+                <DialogButton style={actionButton} onClick={() => streamPin(pin, hosts, pins)}>
+                  <FaPlay style={{ marginRight: "0.4em" }} />
+                  Play
+                </DialogButton>
+                <DialogButton
+                  style={{ ...actionButton, minWidth: "5em" }}
+                  onClick={() => pins.removePin(pin.host_fp, pin.game_id)}
+                >
+                  Remove
+                </DialogButton>
+              </Focusable>
+            </Field>
+          );
+        })}
+      </>
+    )}
   </div>
 );
 
@@ -295,6 +356,7 @@ const AboutTab: FC<{
 const PunktfunkPage: FC = () => {
   const { hosts, scanning, refresh } = useHosts();
   const { info: update, checking, check } = useUpdate();
+  const pins = usePins();
   const [tab, setTab] = useState("hosts");
 
   return (
@@ -325,7 +387,12 @@ const PunktfunkPage: FC = () => {
         </div>
       </Focusable>
 
-      <div style={{ flex: 1, minHeight: 0 }}>
+      {/* overflow:hidden is load-bearing: Valve's Tabs slides the incoming panel in from the
+          right on L1/R1, and with autoFocusContents it scrollIntoViews a control inside that
+          still-offscreen panel. Without a clip here the scroll pans #GamepadUI itself — the whole
+          Steam UI (top bar included) slides left until you click a tab. Valve's own Tabs always
+          live in a clipped flex box; match that. */}
+      <div style={{ flex: 1, minHeight: 0, overflow: "hidden" }}>
         <Tabs
           activeTab={tab}
           onShowTab={(id: string) => setTab(id)}
@@ -334,7 +401,15 @@ const PunktfunkPage: FC = () => {
             {
               id: "hosts",
               title: "Hosts",
-              content: <HostsTab hosts={hosts} scanning={scanning} refresh={refresh} />,
+              content: (
+                <HostsTab
+                  hosts={hosts}
+                  scanning={scanning}
+                  refresh={refresh}
+                  pins={pins}
+                  clientUpdatePending={!!update?.client_update_available}
+                />
+              ),
             },
             {
               id: "settings",

clients/decky/src/steam.ts

@@ -184,19 +184,62 @@ function disableSteamInputForShortcut(appId: number): void {
   }
 }
 
+/** Per-launch extras beyond the host target (all optional — {} is the plain stream). */
+export interface LaunchOpts {
+  /** Library id to launch on connect (a pinned game) — rides PF_LAUNCH → `--launch`. */
+  launchId?: string;
+  /** Open the gamepad library launcher instead of streaming (PF_BROWSE → `--browse`). */
+  browse?: boolean;
+  /** Management-API port for the launcher's library fetch (PF_MGMT; 0/absent = default). */
+  mgmt?: number;
+}
+
+// Launch ids ride Steam launch options as an env-prefix token (`PF_LAUNCH=<id>`), so they
+// must be space/quote-free — Steam's tokenizer and the wrapper's env both break otherwise.
+// Real ids are `steam:<digits>` / `custom:<slug>`, so this rejects nothing in practice;
+// it's VALIDATION, never encoding (the host must match the opaque token verbatim).
+const UNSAFE_LAUNCH_ID = /["'\\$`\s]/;
+export function isSafeLaunchId(id: string): boolean {
+  return (
+    id.length > 0 &&
+    id.length <= 128 &&
+    UNSAFE_LAUNCH_ID.exec(id) === null &&
+    /^[\x21-\x7e]+$/.test(id)
+  );
+}
+
 /**
- * Launch a stream to `host:port` fullscreen in Gaming Mode. Encodes the target into the
- * shortcut's launch options (so one generic shortcut serves every host), then RunGame.
+ * Launch a stream to `host:port` fullscreen in Gaming Mode (optionally straight into a
+ * library title, or into the gamepad library launcher). Encodes the target into the
+ * shortcut's launch options (so one generic shortcut serves every host and every pinned
+ * game), then RunGame.
  */
-export async function launchStream(host: string, port: number): Promise<void> {
+export async function launchStream(
+  host: string,
+  port: number,
+  opts: LaunchOpts = {},
+): Promise<void> {
   const { appId, runner } = await ensureShortcut();
   // Best-effort so the Deck's rich controls reach the client; no-op if the API is absent (the user
   // disables Steam Input manually — see the Settings instruction).
   disableSteamInputForShortcut(appId);
   const target = port && port !== 9777 ? `${host}:${port}` : host;
+  const env = [`PF_HOST=${target}`];
+  if (opts.browse) {
+    env.push("PF_BROWSE=1");
+    if (opts.mgmt) {
+      env.push(`PF_MGMT=${Math.floor(opts.mgmt)}`);
+    }
+  } else if (opts.launchId) {
+    if (!isSafeLaunchId(opts.launchId)) {
+      // Enforced at pin time too (the picker disables Pin) — this is the backstop.
+      throw new Error(`unsupported launch id: ${opts.launchId}`);
+    }
+    env.push(`PF_LAUNCH=${opts.launchId}`);
+  }
   // KEY=value ... %command% args — %command% expands to the shortcut exe (/bin/sh); the wrapper
-  // script rides behind it as an argument and reads PF_HOST from the environment.
-  SteamClient.Apps.SetAppLaunchOptions(appId, `PF_HOST=${target} %command% "${runner}"`);
+  // script rides behind it as an argument and reads PF_* from the environment.
+  SteamClient.Apps.SetAppLaunchOptions(appId, `${env.join(" ")} %command% "${runner}"`);
   SteamClient.Apps.RunGame(gameIdFromAppId(appId), "", -1, 100);
 }