feat(decky): full-featured Gaming-Mode client — fullscreen page, pairing, focus-correct launch

The plugin was a QAM launcher whose stream never appeared, with no
pairing. Three fixes, plus a headless --pair mode on the GTK client:

- Stream actually starts (MoonDeck's proven mechanism): gamescope only
  focuses the process tree Steam launched via reaper, so a flatpak
  spawned from the (root) backend is invisible. The frontend now
  registers ONE hidden non-Steam shortcut pointing at bin/punktfunkrun.sh,
  passes the host as the shortcut's Steam launch options, and starts it
  with SteamClient.Apps.RunGame — gamescope then fullscreen-focuses it.
  The wrapper execs `flatpak run io.unom.Punktfunk --connect <host>`.
- Fullscreen page: routerHook.addRoute("/punktfunk") — host list,
  per-host Pair/Stream, and a settings section (resolution/refresh/
  bitrate/gamepad/mic, written to client-gtk-settings.json).
- Pairing: a gamepad-navigable PIN keypad. The host shows the PIN; the
  backend runs the SPAKE2 ceremony headlessly via the client's new
  `--pair <PIN> --connect host` CLI mode (app.rs), persisting the host
  as paired so the stream then connects silently. Same flatpak =>
  shared identity store, verified live (ceremony against a real host).
- Backend (main.py): discover / pair / runner_info / get_settings /
  set_settings / kill_stream; uses DECKY_USER_HOME so paths resolve to
  the deck user's flatpak install regardless of the plugin's root flag.

CI (decky.yml) and the sideload packager now ship bin/punktfunkrun.sh.
The Steam-shortcut launch and headless-pairing env follow MoonDeck
exactly but need a Deck in Gaming Mode to fully confirm.

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

clients/decky/src/backend.ts

@@ -0,0 +1,45 @@
+// Bridge to the Python backend (main.py) + shared types.
+import { callable } from "@decky/api";
+
+export interface Host {
+  name: string;
+  host: string;
+  port: number;
+  pair: string; // "required" | "optional"
+  fp: string;
+}
+
+export interface PairResult {
+  ok: boolean;
+  fp?: string;
+  error?: string;
+}
+
+export interface RunnerInfo {
+  runner: string; // absolute path to bin/punktfunkrun.sh
+  app_id: string; // flatpak app id
+  exists: boolean;
+}
+
+export interface StreamSettings {
+  width: number; // 0 = native
+  height: number; // 0 = native
+  refresh_hz: number; // 0 = native
+  bitrate_kbps: number; // 0 = host default
+  gamepad: string; // "auto" | "xbox360" | "dualsense"
+  compositor: string; // "auto" | "kwin" | "wlroots" | "mutter" | "gamescope"
+  inhibit_shortcuts: boolean;
+  mic_enabled: boolean;
+}
+
+export const discover = callable<[], Host[]>("discover");
+export const pair = callable<
+  [host: string, port: number, pin: string, name: string],
+  PairResult
+>("pair");
+export const runnerInfo = callable<[], RunnerInfo>("runner_info");
+export const getSettings = callable<[], StreamSettings>("get_settings");
+export const setSettings = callable<[settings: StreamSettings], { ok: boolean }>(
+  "set_settings",
+);
+export const killStream = callable<[], { ok: boolean }>("kill_stream");

clients/decky/src/index.tsx

@@ -1,131 +1,364 @@
 import {
   ButtonItem,
+  Dropdown,
   Field,
+  Focusable,
+  DialogButton,
+  ModalRoot,
+  Navigation,
   PanelSection,
   PanelSectionRow,
+  SliderField,
   Spinner,
+  ToggleField,
+  showModal,
+  staticClasses,
 } from "@decky/ui";
+import { definePlugin, routerHook, toaster } from "@decky/api";
+import { FC, useCallback, useEffect, useState } from "react";
 import {
-  callable,
-  definePlugin,
-  toaster,
-} from "@decky/api";
-import { useEffect, useState } from "react";
-import { FaTv, FaSyncAlt, FaStop, FaLock, FaLockOpen } from "react-icons/fa";
+  FaTv,
+  FaSyncAlt,
+  FaLock,
+  FaLockOpen,
+  FaPlay,
+  FaArrowLeft,
+} from "react-icons/fa";
+import {
+  discover,
+  getSettings,
+  pair,
+  setSettings,
+  Host,
+  StreamSettings,
+} from "./backend";
+import { launchStream } from "./steam";
 
-// ---- Backend bridge (see main.py) ----
+const ROUTE = "/punktfunk";
 
-interface Host {
-  name: string;
-  host: string;
-  port: number;
-  pair: string; // "required" | "optional"
-  fp: string;
-}
-
-interface ConnectResult {
-  ok: boolean;
-  host: string | null;
-  error?: string;
-}
-
-interface Status {
-  connected: boolean;
-  host: string | null;
-}
-
-const discover = callable<[], Host[]>("discover");
-const connect = callable<[host: string, port: number], ConnectResult>("connect");
-const disconnect = callable<[], { ok: boolean; host: string | null }>("disconnect");
-const getStatus = callable<[], Status>("status");
-
-function Content() {
+// ----------------------------------------------------------------------------------------
+// Discovery hook — shared by the QAM panel and the full page.
+// ----------------------------------------------------------------------------------------
+function useHosts() {
   const [hosts, setHosts] = useState<Host[]>([]);
   const [scanning, setScanning] = useState(false);
-  const [busyHost, setBusyHost] = useState<string | null>(null);
-  const [connectedHost, setConnectedHost] = useState<string | null>(null);
 
-  const refresh = async () => {
+  const refresh = useCallback(async () => {
     setScanning(true);
     try {
-      const found = await discover();
-      setHosts(found);
-      toaster.toast({
-        title: "punktfunk",
-        body:
-          found.length === 0
-            ? "No hosts found on the LAN"
-            : `Found ${found.length} host${found.length === 1 ? "" : "s"}`,
-      });
+      setHosts(await discover());
     } catch (e) {
       toaster.toast({ title: "punktfunk", body: `Discovery failed: ${e}` });
     } finally {
       setScanning(false);
     }
-  };
+  }, []);
 
-  const onConnect = async (h: Host) => {
-    const target = `${h.host}:${h.port}`;
-    setBusyHost(target);
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return { hosts, scanning, refresh };
+}
+
+async function startStream(h: Host) {
+  try {
+    await launchStream(h.host, h.port);
+    Navigation.CloseSideMenus();
+    toaster.toast({ title: "punktfunk", body: `Starting stream — ${h.name}` });
+  } catch (e) {
+    toaster.toast({ title: "punktfunk", body: `Launch failed: ${e}` });
+  }
+}
+
+// ----------------------------------------------------------------------------------------
+// PIN pairing modal — a gamepad-navigable digit grid (the OSK is unreliable in Gaming Mode).
+// The host displays the PIN after the operator arms pairing; the user enters it here.
+// ----------------------------------------------------------------------------------------
+const PairModal: FC<{
+  host: Host;
+  closeModal?: () => void;
+  onPaired: () => void;
+}> = ({ host, closeModal, onPaired }) => {
+  const [pin, setPin] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const press = (d: string) => setPin((p) => (p.length >= 4 ? p : p + d));
+  const back = () => setPin((p) => p.slice(0, -1));
+
+  const submit = async () => {
+    setBusy(true);
+    setError(null);
     try {
-      const res = await connect(h.host, h.port);
+      const res = await pair(host.host, host.port, pin, "Steam Deck");
       if (res.ok) {
-        setConnectedHost(res.host);
-        toaster.toast({ title: "punktfunk", body: `Connecting to ${h.name}` });
+        toaster.toast({ title: "punktfunk", body: `Paired with ${host.name}` });
+        onPaired();
+        closeModal?.();
       } else {
-        toaster.toast({
-          title: "punktfunk",
-          body:
-            res.error === "client-not-found"
-              ? "punktfunk-client is not installed"
-              : `Connect failed: ${res.error ?? "unknown"}`,
-        });
+        setError(res.error ?? "pairing failed");
+        setPin("");
       }
     } catch (e) {
-      toaster.toast({ title: "punktfunk", body: `Connect failed: ${e}` });
+      setError(String(e));
     } finally {
-      setBusyHost(null);
+      setBusy(false);
     }
   };
 
-  const onDisconnect = async () => {
-    try {
-      await disconnect();
-      setConnectedHost(null);
-      toaster.toast({ title: "punktfunk", body: "Disconnected" });
-    } catch (e) {
-      toaster.toast({ title: "punktfunk", body: `Disconnect failed: ${e}` });
-    }
-  };
+  return (
+    <ModalRoot closeModal={closeModal}>
+      <div style={{ fontWeight: "bold", fontSize: "1.3em", marginBottom: "0.3em" }}>
+        Pair with {host.name}
+      </div>
+      <div style={{ opacity: 0.8, marginBottom: "1em" }}>
+        Arm pairing on the host (its console or web UI), then enter the 4-digit PIN it shows.
+      </div>
+
+      <div
+        style={{
+          fontSize: "2.2em",
+          letterSpacing: "0.4em",
+          textAlign: "center",
+          fontFamily: "monospace",
+          minHeight: "1.4em",
+          marginBottom: "0.6em",
+        }}
+      >
+        {pin.padEnd(4, "•")}
+      </div>
+      {error && (
+        <div style={{ color: "#ff6b6b", textAlign: "center", marginBottom: "0.6em" }}>
+          {error}
+        </div>
+      )}
+
+      <Focusable
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(3, 1fr)",
+          gap: "0.5em",
+        }}
+      >
+        {["1", "2", "3", "4", "5", "6", "7", "8", "9"].map((d) => (
+          <DialogButton key={d} disabled={busy} onClick={() => press(d)}>
+            {d}
+          </DialogButton>
+        ))}
+        <DialogButton disabled={busy} onClick={back}>
+          ⌫
+        </DialogButton>
+        <DialogButton disabled={busy} onClick={() => press("0")}>
+          0
+        </DialogButton>
+        <DialogButton
+          disabled={busy || pin.length !== 4}
+          onClick={submit}
+        >
+          {busy ? <Spinner style={{ height: "1em" }} /> : "Pair"}
+        </DialogButton>
+      </Focusable>
+    </ModalRoot>
+  );
+};
+
+// ----------------------------------------------------------------------------------------
+// Settings section — resolution / refresh / bitrate / gamepad, written to the client's JSON.
+// ----------------------------------------------------------------------------------------
+const RESOLUTIONS: [number, number, string][] = [
+  [0, 0, "Native display"],
+  [1280, 720, "1280 × 720"],
+  [1920, 1080, "1920 × 1080"],
+  [2560, 1440, "2560 × 1440"],
+];
+const REFRESH = [0, 30, 60, 90, 120];
+const GAMEPADS = ["auto", "xbox360", "dualsense"];
+
+const SettingsSection: FC = () => {
+  const [s, setS] = useState<StreamSettings | null>(null);
 
-  // On panel open: sync the current connection status and do an initial scan.
   useEffect(() => {
-    getStatus()
-      .then((s) => setConnectedHost(s.connected ? s.host : null))
-      .catch(() => {});
-    void refresh();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    void getSettings().then(setS);
   }, []);
 
+  const patch = (p: Partial<StreamSettings>) => {
+    setS((cur) => {
+      if (!cur) return cur;
+      const next = { ...cur, ...p };
+      void setSettings(next);
+      return next;
+    });
+  };
+
+  if (!s) return <Spinner style={{ height: "1.5em" }} />;
+
+  const resIdx = Math.max(
+    0,
+    RESOLUTIONS.findIndex(([w, h]) => w === s.width && h === s.height),
+  );
+
   return (
     <>
-      <PanelSection title="Status">
-        <PanelSectionRow>
-          <Field label="State" focusable={false}>
-            {connectedHost ? `Connected — ${connectedHost}` : "Idle"}
-          </Field>
-        </PanelSectionRow>
-        {connectedHost && (
-          <PanelSectionRow>
-            <ButtonItem layout="below" onClick={onDisconnect}>
-              <FaStop style={{ marginRight: "0.5em" }} />
-              Disconnect
-            </ButtonItem>
-          </PanelSectionRow>
-        )}
-      </PanelSection>
+      <Field
+        label="Resolution"
+        description="The host creates a virtual output at exactly this size"
+        childrenContainerWidth="max"
+      >
+        <Dropdown
+          rgOptions={RESOLUTIONS.map(([, , label], i) => ({ data: i, label }))}
+          selectedOption={resIdx}
+          onChange={(o) => {
+            const [w, h] = RESOLUTIONS[o.data as number];
+            patch({ width: w, height: h });
+          }}
+        />
+      </Field>
+      <Field label="Refresh rate" childrenContainerWidth="max">
+        <Dropdown
+          rgOptions={REFRESH.map((r) => ({ data: r, label: r === 0 ? "Native" : `${r} Hz` }))}
+          selectedOption={s.refresh_hz}
+          onChange={(o) => patch({ refresh_hz: o.data as number })}
+        />
+      </Field>
+      <SliderField
+        label="Bitrate"
+        description="Mbit/s · 0 = host default"
+        value={Math.round(s.bitrate_kbps / 1000)}
+        min={0}
+        max={150}
+        step={5}
+        showValue
+        valueSuffix=" Mbit/s"
+        onChange={(v) => patch({ bitrate_kbps: v * 1000 })}
+      />
+      <Field label="Gamepad type" childrenContainerWidth="max">
+        <Dropdown
+          rgOptions={GAMEPADS.map((g) => ({
+            data: g,
+            label: g === "auto" ? "Automatic" : g === "xbox360" ? "Xbox 360" : "DualSense",
+          }))}
+          selectedOption={s.gamepad}
+          onChange={(o) => patch({ gamepad: o.data as string })}
+        />
+      </Field>
+      <ToggleField
+        label="Stream microphone"
+        checked={s.mic_enabled}
+        onChange={(v) => patch({ mic_enabled: v })}
+      />
+    </>
+  );
+};
 
-      <PanelSection title="Hosts">
+// ----------------------------------------------------------------------------------------
+// One host row on the full page.
+// ----------------------------------------------------------------------------------------
+const HostRow: FC<{ host: Host }> = ({ host }) => {
+  const pairRequired = host.pair === "required";
+  return (
+    <Field
+      label={
+        <span style={{ display: "inline-flex", alignItems: "center", gap: "0.4em" }}>
+          {pairRequired ? <FaLock /> : <FaLockOpen />}
+          {host.name}
+        </span>
+      }
+      description={`${host.host}:${host.port}${pairRequired ? " · pairing required" : ""}`}
+      childrenContainerWidth="max"
+    >
+      <Focusable style={{ display: "flex", gap: "0.5em" }}>
+        {pairRequired && (
+          <DialogButton
+            style={{ minWidth: "5em" }}
+            onClick={() =>
+              showModal(<PairModal host={host} onPaired={() => {}} />)
+            }
+          >
+            Pair
+          </DialogButton>
+        )}
+        <DialogButton style={{ minWidth: "6em" }} onClick={() => startStream(host)}>
+          <FaPlay style={{ marginRight: "0.4em" }} />
+          Stream
+        </DialogButton>
+      </Focusable>
+    </Field>
+  );
+};
+
+// ----------------------------------------------------------------------------------------
+// The fullscreen page (registered as the /punktfunk route).
+// ----------------------------------------------------------------------------------------
+const PunktfunkPage: FC = () => {
+  const { hosts, scanning, refresh } = useHosts();
+
+  return (
+    <div
+      style={{
+        marginTop: "40px",
+        height: "calc(100% - 40px)",
+        overflowY: "auto",
+        padding: "0 2.5em 2.5em",
+      }}
+    >
+      <Focusable style={{ display: "flex", alignItems: "center", gap: "1em", marginBottom: "1em" }}>
+        <DialogButton
+          style={{ width: "3em", minWidth: "3em" }}
+          onClick={() => Navigation.NavigateBack()}
+        >
+          <FaArrowLeft />
+        </DialogButton>
+        <div className={staticClasses.Title} style={{ flex: 1 }}>
+          punktfunk
+        </div>
+        <DialogButton style={{ width: "10em" }} disabled={scanning} onClick={refresh}>
+          {scanning ? (
+            <Spinner style={{ height: "1em", marginRight: "0.5em" }} />
+          ) : (
+            <FaSyncAlt style={{ marginRight: "0.5em" }} />
+          )}
+          {scanning ? "Scanning…" : "Refresh"}
+        </DialogButton>
+      </Focusable>
+
+      <div style={{ fontSize: "1.1em", fontWeight: "bold", margin: "0.5em 0" }}>Hosts</div>
+      {hosts.length === 0 && !scanning && (
+        <Field focusable={false}>No hosts discovered on the LAN.</Field>
+      )}
+      {hosts.map((h) => (
+        <HostRow key={h.fp || `${h.host}:${h.port}`} host={h} />
+      ))}
+
+      <div style={{ fontSize: "1.1em", fontWeight: "bold", margin: "1.5em 0 0.5em" }}>
+        Stream settings
+      </div>
+      <SettingsSection />
+    </div>
+  );
+};
+
+// ----------------------------------------------------------------------------------------
+// QAM panel — quick status + entry into the full page + one-tap stream for known hosts.
+// ----------------------------------------------------------------------------------------
+const QamPanel: FC = () => {
+  const { hosts, scanning, refresh } = useHosts();
+
+  return (
+    <>
+      <PanelSection title="punktfunk">
+        <PanelSectionRow>
+          <ButtonItem
+            layout="below"
+            onClick={() => {
+              Navigation.Navigate(ROUTE);
+              Navigation.CloseSideMenus();
+            }}
+          >
+            <FaTv style={{ marginRight: "0.5em" }} />
+            Open punktfunk
+          </ButtonItem>
+        </PanelSectionRow>
         <PanelSectionRow>
           <ButtonItem layout="below" onClick={refresh} disabled={scanning}>
             {scanning ? (
@@ -133,39 +366,37 @@ function Content() {
             ) : (
               <FaSyncAlt style={{ marginRight: "0.5em" }} />
             )}
-            {scanning ? "Scanning…" : "Refresh"}
+            {scanning ? "Scanning…" : "Refresh hosts"}
           </ButtonItem>
         </PanelSectionRow>
+      </PanelSection>
 
+      <PanelSection title="Hosts">
         {hosts.length === 0 && !scanning && (
           <PanelSectionRow>
-            <Field focusable={false}>No hosts discovered yet.</Field>
+            <Field focusable={false}>No hosts found.</Field>
           </PanelSectionRow>
         )}
-
         {hosts.map((h) => {
-          const target = `${h.host}:${h.port}`;
-          const isBusy = busyHost === target;
           const pairRequired = h.pair === "required";
           return (
-            <PanelSectionRow key={h.fp || target}>
+            <PanelSectionRow key={h.fp || `${h.host}:${h.port}`}>
               <ButtonItem
                 layout="below"
-                disabled={isBusy}
-                onClick={() => onConnect(h)}
+                onClick={() =>
+                  pairRequired
+                    ? showModal(<PairModal host={h} onPaired={() => startStream(h)} />)
+                    : startStream(h)
+                }
                 label={
-                  <span>
-                    {pairRequired ? (
-                      <FaLock style={{ marginRight: "0.4em" }} />
-                    ) : (
-                      <FaLockOpen style={{ marginRight: "0.4em" }} />
-                    )}
+                  <span style={{ display: "inline-flex", alignItems: "center", gap: "0.4em" }}>
+                    {pairRequired ? <FaLock /> : <FaLockOpen />}
                     {h.name}
                   </span>
                 }
-                description={`${target}${pairRequired ? " · pairing required" : ""}`}
+                description={`${h.host}:${h.port}`}
               >
-                {isBusy ? "Connecting…" : "Connect"}
+                {pairRequired ? "Pair & Stream" : "Stream"}
               </ButtonItem>
             </PanelSectionRow>
           );
@@ -173,16 +404,17 @@ function Content() {
       </PanelSection>
     </>
   );
-}
+};
 
 export default definePlugin(() => {
+  routerHook.addRoute(ROUTE, PunktfunkPage, { exact: true });
   return {
     name: "punktfunk",
-    titleView: <div>punktfunk</div>,
-    content: <Content />,
+    titleView: <div className={staticClasses.Title}>punktfunk</div>,
+    content: <QamPanel />,
     icon: <FaTv />,
     onDismount() {
-      // The backend tears the client down on _unload; nothing frontend-side to clean up.
+      routerHook.removeRoute(ROUTE);
     },
   };
 });

clients/decky/src/steam.ts

@@ -0,0 +1,114 @@
+// Launch the stream as a Steam game so gamescope focuses + fullscreens it.
+//
+// THE LAUNCH MECHANISM (verified against MoonDeck): gamescope only gives focus/fullscreen to
+// the window tree Steam launched via `reaper` (it detects the "current app" by AppID — see
+// gamescope#484). So we cannot launch the flatpak from the plugin backend; we register ONE
+// hidden non-Steam shortcut that points at our wrapper script (bin/punktfunkrun.sh), pass the
+// per-session host as the shortcut's Steam launch options, and start it with RunGame. The
+// wrapper then execs `flatpak run io.unom.Punktfunk --connect <host>` as a reaper descendant.
+
+import { runnerInfo } from "./backend";
+
+// SteamClient is a Steam-internal global injected into the CEF context; it is not fully typed
+// by @decky/ui, so declare the surface we use. Signatures verified against MoonDeck + the
+// decky-frontend-lib SteamClient.Apps typings.
+declare const SteamClient: {
+  Apps: {
+    AddShortcut(
+      name: string,
+      exePath: string,
+      startDir: string,
+      launchOptions: string,
+    ): Promise<number>;
+    SetShortcutName(appId: number, name: string): void;
+    SetShortcutExe(appId: number, exe: string): void;
+    SetShortcutStartDir(appId: number, dir: string): void;
+    SetAppLaunchOptions(appId: number, options: string): void;
+    SetAppHidden(appId: number, hidden: boolean): void;
+    RunGame(gameId: string, _unused: string, _i: number, _j: number): void;
+    TerminateApp(gameId: string, _b: boolean): void;
+  };
+};
+
+const SHORTCUT_NAME = "punktfunk";
+
+// The 64-bit "gameid" RunGame wants, derived from a 32-bit non-Steam shortcut appId: the
+// standard non-Steam-game encoding (appid << 32 | 0x02000000). MoonDeck/decky tools use this.
+function gameIdFromAppId(appId: number): string {
+  return ((BigInt(appId) << 32n) | 0x02000000n).toString();
+}
+
+// Persist our shortcut appId across reloads so we reuse ONE shortcut instead of churning the
+// library (the appId is stable for the life of the shortcut).
+const STORAGE_KEY = "punktfunk:shortcutAppId";
+
+function rememberAppId(appId: number) {
+  try {
+    localStorage.setItem(STORAGE_KEY, String(appId));
+  } catch {
+    /* ignore */
+  }
+}
+function recallAppId(): number | null {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    return v ? Number(v) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure exactly one hidden "punktfunk" shortcut exists pointing at the wrapper script, and
+ * return its appId. Reuses the remembered one when its exe still matches the current runner
+ * path (the plugin dir can change across reinstalls).
+ */
+async function ensureShortcut(): Promise<number> {
+  const info = await runnerInfo();
+  if (!info.exists) {
+    throw new Error(`launch wrapper missing at ${info.runner}`);
+  }
+
+  const remembered = recallAppId();
+  if (remembered != null) {
+    // Re-point the existing shortcut at the current runner path (cheap + idempotent).
+    SteamClient.Apps.SetShortcutExe(remembered, info.runner);
+    SteamClient.Apps.SetShortcutStartDir(
+      remembered,
+      info.runner.replace(/\/[^/]*$/, ""),
+    );
+    return remembered;
+  }
+
+  const appId = await SteamClient.Apps.AddShortcut(
+    SHORTCUT_NAME,
+    info.runner,
+    info.runner.replace(/\/[^/]*$/, ""), // start dir = the bin/ dir
+    "",
+  );
+  SteamClient.Apps.SetShortcutName(appId, SHORTCUT_NAME);
+  // Hide it from the library — it's an implementation detail, launched programmatically.
+  SteamClient.Apps.SetAppHidden(appId, true);
+  rememberAppId(appId);
+  return appId;
+}
+
+/**
+ * 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.
+ */
+export async function launchStream(host: string, port: number): Promise<void> {
+  const appId = await ensureShortcut();
+  const target = port && port !== 9777 ? `${host}:${port}` : host;
+  // KEY=value ... %command% — the wrapper reads PF_HOST from the environment.
+  SteamClient.Apps.SetAppLaunchOptions(appId, `PF_HOST=${target} %command%`);
+  SteamClient.Apps.RunGame(gameIdFromAppId(appId), "", -1, 100);
+}
+
+/** Stop the running stream shortcut (best-effort; the in-stream chord/back also works). */
+export function stopStream(): void {
+  const appId = recallAppId();
+  if (appId != null) {
+    SteamClient.Apps.TerminateApp(gameIdFromAppId(appId), false);
+  }
+}