Merge pull request #47 from saphid/linux-vr-streaming

docs: repeat Frame streaming client feasibility under test lock

.gitattributes

@@ -6,3 +6,8 @@
 *.json text eol=lf
 *.md text eol=lf
 *.bat text eol=crlf
+# Test fixtures are byte-exact (hashes, signatures): never convert line endings.
+tests/fixtures/** -text
+*.apk binary
+*.jar binary
+*.obb binary

.github/workflows/pc-host.yml

@@ -1,53 +0,0 @@
-name: PC host libraries
-on:
-  pull_request:
-    paths: ["desktop/**", "ui/**", "tests/**", "mac/frame-mac-view/**", "scripts/macview-bench.py", ".github/workflows/pc-host.yml"]
-  workflow_dispatch:
-jobs:
-  linux:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, ubuntu-24.04-arm]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Native libraries
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libglib2.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-pipewire libpipewire-0.3-modules libspa-0.2-modules
-          python3 desktop/build.py
-      - name: Tests (real x264, fake capture consent/input)
-        env:
-          FRAME_PC_REQUIRE_NATIVE: "1"
-        run: python3 -m unittest discover -s tests -p 'test_pc*.py' -v
-      - uses: actions/upload-artifact@v4
-        with:
-          name: pc-host-${{ matrix.os }}
-          path: desktop/bundle
-  windows:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: msys2/setup-msys2@v2
-        with:
-          msystem: UCRT64
-          update: true
-          install: >-
-            mingw-w64-ucrt-x86_64-gcc
-            mingw-w64-ucrt-x86_64-pkgconf
-            mingw-w64-ucrt-x86_64-python
-            mingw-w64-ucrt-x86_64-gstreamer
-            mingw-w64-ucrt-x86_64-gst-plugins-base
-            mingw-w64-ucrt-x86_64-gst-plugins-good
-            mingw-w64-ucrt-x86_64-gst-plugins-bad
-            mingw-w64-ucrt-x86_64-gst-plugins-ugly
-      - name: Native build and tests (x264; WGC and MF need a desktop/GPU)
-        shell: msys2 {0}
-        run: |
-          python desktop/build.py
-          FRAME_PC_REQUIRE_NATIVE=1 python -m unittest discover -s tests -p 'test_pc*.py' -v
-      - uses: actions/upload-artifact@v4
-        with:
-          name: pc-host-windows
-          path: desktop/bundle

.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
   push:
     tags: ["v*"]
   pull_request:
-    paths: ["app/**", "ui/**", "desktop/**", "mac/**", "scripts/**", "frame/**", "apk-catalog/**", ".github/workflows/release.yml"]
+    paths: ["app/**", "ui/**", "scripts/**", "frame/**", "apk-catalog/**", ".github/workflows/release.yml"]
   workflow_dispatch:
 
 permissions:
@@ -28,62 +28,18 @@ jobs:
           - os: ubuntu-latest
             script: dist:linux
             files: app/dist/*.AppImage app/dist/*.deb
-          - os: ubuntu-24.04-arm
-            script: dist:linux:arm64
-            files: app/dist/*.AppImage app/dist/*.deb
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "24"
-      - name: Linux streaming libraries
-        if: runner.os == 'Linux'
-        shell: bash
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libglib2.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-pipewire libpipewire-0.3-modules libspa-0.2-modules
-          arch=x64; if [ "$(uname -m)" = aarch64 ]; then arch=arm64; fi
-          python3 desktop/build.py --out "app/build/desktop/linux-$arch"
-      - uses: msys2/setup-msys2@v2
-        if: runner.os == 'Windows'
-        with:
-          msystem: UCRT64
-          update: true
-          install: >-
-            mingw-w64-ucrt-x86_64-gcc
-            mingw-w64-ucrt-x86_64-pkgconf
-            mingw-w64-ucrt-x86_64-python
-            mingw-w64-ucrt-x86_64-gstreamer
-            mingw-w64-ucrt-x86_64-gst-plugins-base
-            mingw-w64-ucrt-x86_64-gst-plugins-good
-            mingw-w64-ucrt-x86_64-gst-plugins-bad
-            mingw-w64-ucrt-x86_64-gst-plugins-ugly
-      - name: Windows streaming libraries
-        if: runner.os == 'Windows'
-        shell: msys2 {0}
-        run: python desktop/build.py --out app/build/desktop/win-x64
       - name: Build
         working-directory: app
         shell: bash
         run: npm ci && npm run ${{ matrix.script }}
         env:
           CSC_IDENTITY_AUTO_DISCOVERY: "false"
-      - name: Test the bundled Python with the native PC libraries
-        if: runner.os != 'macOS'
-        shell: bash
-        run: |
-          if [ "$RUNNER_OS" = Windows ]; then
-            platform=win; arch=x64
-            python="$PWD/app/build/deps/win-x64/python/python.exe"
-            native="$(cygpath -w "$PWD/app/build/desktop/win-x64")"
-          else
-            platform=linux; arch=x64
-            if [ "$(uname -m)" = aarch64 ]; then arch=arm64; fi
-            python="$PWD/app/build/deps/linux-$arch/python/bin/python3"
-            native="$PWD/app/build/desktop/linux-$arch"
-          fi
-          FRAME_PC_NATIVE="$native" FRAME_PC_REQUIRE_NATIVE=1 "$python" -m unittest discover -s tests -p 'test_pc*.py' -v
       - name: Upload to the release
         if: startsWith(github.ref, 'refs/tags/')
         shell: bash

.gitignore

@@ -7,15 +7,5 @@ compat-db/.lakebed/
 tests/smoke/results/
 mac/bin/
 
-# Shared desktop streaming controller build products
-desktop/controller.dll
-desktop/controller.dylib
-desktop/controller.so
-desktop/*.obj
-desktop/*.lib
-desktop/*.exp
-desktop/bundle/
-app/build/desktop/
-
 # Downloaded at build time (frame/kdeconnect/fetch.py, app/build/fetch-deps.js)
 frame/kdeconnect/packages/

README.md

@@ -35,8 +35,8 @@ See what the headset sees, install games and Android apps, move files and text a
 <tr>
 <td width="50%" valign="top">
 
-**👓 Headset view**<br>
-Live video of what the lenses show (about 30 fps), or a still of both eyes. Zoom, pan, full screen, save as PNG.
+**👓 Headset view and Desktop**<br>
+Live video of what the lenses show, or of the app panel in use, flat and still however the wearer looks around. Turn on Control and tap or click right on it to use the Frame from your phone or computer.
 
 </td>
 <td width="50%" valign="top">
@@ -93,9 +93,15 @@ SSH, SFTP, Steam Link, remote desktop, volume, sleep, restart and shut down.
 </tr>
 </table>
 
-Nothing is installed on the Frame for any of this: the app uses what SteamOS
+The optional [Family and comfort](docs/family-comfort.md) card adds session
+limits, breaks, local alerts and one-click casting. A session copies a small
+Frame Control worker into your headset user account.
+
+For the other features, nothing is installed on the Frame: the app uses what SteamOS
 already ships (sideloading a game copies Valve's own devkit scripts to
-`~/devkit-utils`, as Valve's Devkit Client does). [How each feature works](docs/frame-control.md).
+`~/devkit-utils`, as Valve's Devkit Client does). The optional
+[performance HUD](docs/vr-utilities.md) copies our own Python helpers into
+`~/.local/share/frame-control/vr/`. [How each feature works](docs/frame-control.md).
 
 ## Install
 
@@ -209,8 +215,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Android apps (Lepton)](docs/apks.md) | Sideloading, the rated F-Droid catalogue, per-app instances |
 | [Sideloading Linux and Windows games](docs/sideloading.md) | A .zip, folder or .exe as a Steam Devkit Game, runtime detection |
 | [Install links for websites](docs/web-install.md) | `frame-control://install` links and manifests, the rules, a button to paste |
-| [Steam games](docs/steam-games.md) · [VR video](docs/vr-video.md) · [WebXR in Chromium](docs/webxr-chromium.md) | Installing and buying, watching VR180/360, the Chromium build |
-| [PC in the headset](docs/pc-in-headset.md) | Windows and Linux host implementation and test coverage |
+| [VR comfort and HUD](docs/vr-utilities.md) · [Steam games](docs/steam-games.md) · [VR video](docs/vr-video.md) · [WebXR in Chromium](docs/webxr-chromium.md) | Installing and buying, watching VR180/360, the Chromium build |
 | [Mac in the headset](docs/mac-in-headset.md) | Mac windows and screens as panels in the Frame, with laser and keyboard input |
 | [VR mods and custom songs](docs/mods.md) | Per-game feasibility, real-Frame results and blockers; no installer yet |
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |

app/main.js

@@ -1,7 +1,7 @@
 // Frame Control as a desktop app (macOS, Windows, Linux): starts ui/server.py on
 // a free loopback port and shows it in a native window. The server does all the
 // work over the `frame` SSH alias; this file only hosts it.
-const { app, BrowserWindow, Menu, clipboard, dialog, ipcMain, shell } = require("electron");
+const { app, BrowserWindow, Menu, Notification, clipboard, dialog, ipcMain, shell } = require("electron");
 const { execFile, spawn } = require("child_process");
 const { promisify } = require("util");
 const fs = require("fs");
@@ -159,10 +159,16 @@ async function startServer() {
 
 // Closing stdin lets server.py close its SSH connections and exit (the only clean
 // way on Windows); SIGTERM does the same elsewhere.
+// Resolves once it has exited (or after 20 s), so a replacement can take the server
+// lock: server.py allows one per user.
 function endServer(child) {
+  const gone = child.exitCode !== null || child.signalCode !== null ? Promise.resolve()
+    : new Promise((resolve) => child.once("exit", resolve));
   try { child.stdin.end(); } catch {}
   if (!IS_WIN) child.kill("SIGTERM");
-  setTimeout(() => { if (child.exitCode === null && child.signalCode === null) child.kill(); }, 5000).unref();
+  // server.py ignores a second SIGTERM while it shuts down, so the fallback is a hard kill.
+  setTimeout(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL"); }, 12000).unref();
+  return Promise.race([gone, new Promise((resolve) => setTimeout(resolve, 20000).unref())]);
 }
 
 function stopServer() {
@@ -183,27 +189,37 @@ function serverDied(why) {
   if (win) win.loadURL(errorPage(`The server stopped unexpectedly (${why}). See ${LOG}.`));
 }
 
-async function restartServer() {
-  const old = server;
-  server = null;
-  url = null;
-  if (old) endServer(old);
-  await load();
+// Restarts that overlap share one: two could each start a server, and the one
+// that lost the lock would leave the app pointing at nothing.
+let restarting = null;
+function restartServer() {
+  if (!restarting) {
+    restarting = (async () => {
+      const old = server;
+      server = null;
+      url = null;
+      if (old) await endServer(old);
+      if (starting) await starting.catch(() => {});  // a start it cut short: then start afresh
+      await load();
+    })().finally(() => { restarting = null; });
+  }
+  return restarting;
 }
 
 // On macOS the page's sticky header becomes the title bar, clear of the traffic lights.
 const CHROME_CSS = IS_MAC && `
   header { padding-left: 92px !important; -webkit-app-region: drag; user-select: none; }
-  header a, header button, header input, header .chip { -webkit-app-region: no-drag; }
+  header a, header button, header input, header select, header .chip { -webkit-app-region: no-drag; }
 `;
 
 // Restart Server can start a new load while an older one is still waiting for
 // its server; only the newest load may touch the window.
 let loadGen = 0;
+let starting = null;  // loads that overlap share one server start
 async function load() {
   const gen = ++loadGen;
   try {
-    if (!url) await startServer();
+    if (!url) await (starting ||= startServer().finally(() => { starting = null; }));
     if (gen === loadGen && win) { await win.loadURL(url); firstRunCheck(); }
   } catch (e) {
     if (gen === loadGen && win) await win.loadURL(errorPage(e.message));
@@ -254,6 +270,61 @@ ipcMain.handle("update:get", (e) => fromUi(e) ? publicUpdate() : null);
 ipcMain.handle("update:check", (e) => fromUi(e) ? checkForUpdate({ manual: true }).then(publicUpdate) : null);
 ipcMain.handle("update:install", (e) => { if (fromUi(e)) installUpdate(); });
 
+// The page reports the headsets it knows (the server's Devices tab), so the Frame
+// menu can switch between them. Only plain names and ids go into the menu.
+const ALIAS_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+let devices = [];
+ipcMain.on("devices:changed", (e, list) => {
+  if (!fromUi(e) || !Array.isArray(list)) return;
+  const next = list.slice(0, 20).filter(d => d && typeof d.id === "string" && ALIAS_RE.test(d.alias || ""))
+    .map(d => ({ id: d.id.slice(0, 80), name: String(d.name || d.alias).slice(0, 60), alias: d.alias, active: !!d.active }));
+  if (JSON.stringify(next) === JSON.stringify(devices)) return;
+  devices = next;
+  buildMenu();
+});
+const activeAlias = () => (devices.find(d => d.active) || {}).alias || FRAME;
+
+// SSH through the server, so it goes to the headset and address the app is using
+// (with its own pinned identity), and refuses when there's none.
+function openSsh() {
+  if (!url) return dialog.showErrorBox("Couldn't open SSH", "Frame Control's server isn't running.");
+  const body = JSON.stringify({ what: "terminal" });
+  const req = http.request(new URL("/api/open", url), {
+    method: "POST", timeout: 15000,
+    headers: { "Content-Type": "application/json", "X-Frame-UI": "1", "Content-Length": Buffer.byteLength(body) },
+  }, (res) => {
+    let data = "";
+    res.on("data", (c) => { data += c; });
+    res.on("end", () => {
+      if (res.statusCode === 200) return;
+      let why = `HTTP ${res.statusCode}`;
+      try { why = JSON.parse(data).error || why; } catch {}
+      dialog.showErrorBox("Couldn't open SSH", why);
+    });
+  });
+  req.on("error", (e) => dialog.showErrorBox("Couldn't open SSH", e.message));
+  req.on("timeout", () => req.destroy(new Error("the server didn't answer")));
+  req.end(body);
+}
+function showDevices() {
+  if (win && url) win.webContents.executeJavaScript('location.hash = "devices"').catch(() => {});
+}
+
+ipcMain.handle("comfort:notify", (e, message) => {
+  if (!fromUi(e) || typeof message !== "string" || message.length > 500) throw new Error("Invalid notification");
+  if (!Notification.isSupported()) throw new Error("System notifications are unavailable");
+  return new Promise((resolve, reject) => {
+    const notification = new Notification({title: "Frame Control", body: message});
+    const timer = setTimeout(() => reject(new Error("Notification delivery was not confirmed. Check system notification settings.")), 5000);
+    notification.once("show", () => { clearTimeout(timer); resolve(true); });
+    notification.once("failed", (_event, error) => {
+      clearTimeout(timer);
+      reject(new Error("Notification delivery failed. Check system notification settings: " + error));
+    });
+    notification.show();
+  });
+});
+
 // frame-control://install links from websites (docs/web-install.md). They can
 // arrive before the window or server exists (macOS open-url on a cold launch),
 // so they wait here until the page asks for them. The page checks the link with
@@ -376,7 +447,7 @@ function createWindow() {
     title: "Frame Control", backgroundColor: BG, show: false,
     ...(IS_MAC ? { titleBarStyle: "hiddenInset", trafficLightPosition: { x: 18, y: 26 } }
                : { icon: path.join(__dirname, "build", "icon.png") }),
-    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true,
+    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true, backgroundThrottling: false,
                       preload: path.join(__dirname, "preload.js") },
   });
   win.once("ready-to-show", () => win.show());
@@ -410,13 +481,14 @@ async function runInTerminal(argv) {
   }
 }
 
-async function setUpConnection() {
-  const alias = `FRAME_ALIAS=${FRAME}`;
+// Set Up Connection for the headset in use (or another alias, from the Devices tab).
+async function setUpConnection(name = activeAlias()) {
+  if (!ALIAS_RE.test(name)) return;
+  const alias = `FRAME_ALIAS=${name}`;
   if (IS_MAC) return runInTerminal(["env", alias, "zsh", path.join(SCRIPTS, "connect.sh")]);
   const py = python || await findPython({ ...process.env, PATH: await loginPath() });
-  const setup = [py || "python3", ...PY_FLAGS, path.join(ROOT, "ui", "frame_connect.py")];
-  // A new console inherits our environment on Windows; Linux terminals may not.
-  runInTerminal(IS_WIN ? setup : ["env", alias, ...setup]);
+  // --alias, since a new console on Windows (and some Linux terminals) doesn't get our environment.
+  runInTerminal([py || "python3", ...PY_FLAGS, path.join(ROOT, "ui", "frame_connect.py"), "--alias", name]);
 }
 
 function buildMenu() {
@@ -431,8 +503,15 @@ function buildMenu() {
     {
       label: "Frame",
       submenu: [
-        { label: "Set Up Connection…", click: setUpConnection },
-        { label: IS_MAC ? "Open SSH in Terminal" : "Open SSH in a Terminal", click: () => runInTerminal(["ssh", FRAME]) },
+        { label: "Set Up Connection…", click: () => setUpConnection() },
+        { label: IS_MAC ? "Open SSH in Terminal" : "Open SSH in a Terminal", click: openSsh },
+        { type: "separator" },
+        ...(devices.length > 1 ? [{
+          label: "Headset",
+          submenu: devices.map(d => ({ label: d.name, type: "radio", checked: d.active,
+                                       click: () => { if (win) win.webContents.send("use-device", d.id); } })),
+        }] : []),
+        { label: "Devices…", accelerator: "CmdOrCtrl+5", click: showDevices },
         { type: "separator" },
         { label: "Open in Browser", click: () => url && shell.openExternal(url) },
         { label: "Restart Server", click: () => win ? restartServer() : createWindow() },

app/package.json

@@ -11,9 +11,8 @@
     "icon": "env -u ELECTRON_RUN_AS_NODE electron build/make-icon.js",
     "dist": "sh ../mac/frame-mac-view/build.sh && node build/fetch-deps.js mac arm64 && electron-builder --mac --arm64 --publish never",
     "dist:dir": "sh ../mac/frame-mac-view/build.sh && node build/fetch-deps.js mac arm64 && electron-builder --mac --arm64 --dir",
-    "dist:linux": "node build/fetch-deps.js linux x64 && electron-builder --linux --x64 --publish never",
-    "dist:win": "node build/fetch-deps.js win x64 && electron-builder --win --x64 --publish never",
-    "dist:linux:arm64": "node build/fetch-deps.js linux arm64 && electron-builder --linux --arm64 --publish never"
+    "dist:linux": "node build/fetch-deps.js linux x64 arm64 && electron-builder --linux --x64 --arm64 --publish never",
+    "dist:win": "node build/fetch-deps.js win x64 && electron-builder --win --x64 --publish never"
   },
   "devDependencies": {
     "electron": "^44.4.5",
@@ -49,9 +48,18 @@
         "filter": [
           "*.py",
           "*.html",
+          "*.js",
           "telemetry.json"
         ]
       },
+      {
+        "from": "../ui/apk_sources",
+        "to": "ui/apk_sources",
+        "filter": [
+          "*.py",
+          "*.json"
+        ]
+      },
       {
         "from": "../scripts",
         "to": "scripts",
@@ -64,7 +72,8 @@
         "to": "frame/android",
         "filter": [
           "*.sh",
-          "*.py"
+          "*.py",
+          "*.js"
         ]
       },
       {
@@ -172,16 +181,7 @@
         "entry": {
           "StartupWMClass": "frame-control"
         }
-      },
-      "extraResources": [
-        {
-          "from": "build/desktop/${os}-${arch}",
-          "to": "desktop/bundle",
-          "filter": [
-            "**/*"
-          ]
-        }
-      ]
+      }
     },
     "deb": {
       "depends": [
@@ -194,16 +194,7 @@
         "zip"
       ],
       "icon": "build/icon.png",
-      "artifactName": "Frame-Control-win-${arch}.${ext}",
-      "extraResources": [
-        {
-          "from": "build/desktop/${os}-${arch}",
-          "to": "desktop/bundle",
-          "filter": [
-            "**/*"
-          ]
-        }
-      ]
+      "artifactName": "Frame-Control-win-${arch}.${ext}"
     },
     "nsis": {
       "oneClick": false,

app/preload.js

@@ -2,15 +2,23 @@
 // to the Frame needs no pbpaste, PowerShell, xclip or wl-clipboard. Also tells
 // the page where a dropped file or folder lives, so a folder can be sideloaded
 // as a title without zipping it (the local server reads it from there).
-// It can open Set Up Connection when the headset can't be reached.
+// It can open Set Up Connection when the headset can't be reached, and keeps the
+// Frame menu's list of headsets up to date.
 // It also receives frame-control://install links (docs/web-install.md): only
 // what the link asked for, never an install; the page asks the user first.
 // And it passes update state both ways: see app/updater.js.
 const { contextBridge, ipcRenderer, webUtils } = require("electron");
 
 contextBridge.exposeInMainWorld("frameApp", {
+  notify: (message, request) => ipcRenderer.invoke("comfort:notify", message, request),
   readClipboard: () => ipcRenderer.invoke("clipboard:read"),
   setUpConnection: () => ipcRenderer.invoke("connection:setup"),
+  // The Frame menu's headset switcher: the page tells it the headsets, and hears picks.
+  devicesChanged: (list) => ipcRenderer.send("devices:changed", list),
+  onUseDevice: (cb) => {
+    ipcRenderer.removeAllListeners("use-device");
+    ipcRenderer.on("use-device", (_e, id) => cb(String(id)));
+  },
   // While the keyboard-and-trackpad panel holds the keyboard, ⌘W, ⌘R and the rest go to the Frame.
   captureKeys: (on) => ipcRenderer.send("keys:capture", !!on),
   pathForFile: (file) => { try { return webUtils.getPathForFile(file) || ""; } catch { return ""; } },

bench/results/2026-09-28-c5fc552-dirty-pc-agent-frame-arm64-hairpin.json

@@ -1,311 +0,0 @@
-{
- "label": "pc-agent-frame-arm64-hairpin",
- "date": "2026-09-28T22:36:19",
- "commit": "c5fc552+dirty",
- "config": {
-  "quality": "balanced",
-  "mode": "separate",
-  "net": "none",
-  "delay_ms": 0,
-  "buffer_ms": 250,
-  "host": "frame",
-  "usb": false,
-  "ssh_opts": [],
-  "encoder": "",
-  "duration_s": 10.0,
-  "browser_flags": []
- },
- "frame_build": "20260925.6191901",
- "mac": "26.5.2",
- "host_platform": "Linux aarch64, SteamOS Frame, BUILD_ID 20260925.6191901 (synthetic host only)",
- "source": "",
- "pc_host": true,
- "headset": "0:03.056203 [Info] - 1 - leaving standby",
- "scenarios": [
-  {
-   "scenario": "test",
-   "frames_sent": 351,
-   "frames_drawn": 351,
-   "frames_shown": 324,
-   "duration_s": 10.1,
-   "stages_ms": {
-    "capture": {
-     "p50": 0.1,
-     "p95": 0.2,
-     "p99": 0.5,
-     "n": 351
-    },
-    "queue": {
-     "p50": 0.1,
-     "p95": 0.3,
-     "p99": 0.4,
-     "n": 351
-    },
-    "encode": {
-     "p50": 2.0,
-     "p95": 2.9,
-     "p99": 3.5,
-     "n": 351
-    },
-    "socket": {
-     "p50": 0.1,
-     "p95": 0.4,
-     "p99": 0.6,
-     "n": 351
-    },
-    "network": {
-     "p50": 11.6,
-     "p95": 75.7,
-     "p99": 130.1,
-     "n": 351
-    },
-    "decode": {
-     "p50": 0.7,
-     "p95": 2.1,
-     "p99": 4.1,
-     "n": 351
-    },
-    "draw": {
-     "p50": 0.4,
-     "p95": 0.8,
-     "p99": 1.1,
-     "n": 351
-    },
-    "present": {
-     "p50": 0.8,
-     "p95": 18.1,
-     "p99": 24.9,
-     "n": 324
-    },
-    "content": {
-     "p50": 15.1,
-     "p95": 80.3,
-     "p99": 134.2,
-     "n": 351
-    },
-    "content_shown": {
-     "p50": 21.0,
-     "p95": 71.8,
-     "p99": 146.3,
-     "n": 324
-    }
-   },
-   "fps": 34.8,
-   "fps_shown": 32.0,
-   "late_pct": 53.41,
-   "stall_max": 226.8,
-   "stalls_over_100ms": 7,
-   "mbps": 0.26,
-   "keyframes": 6,
-   "size": "1280x720",
-   "captured": 607,
-   "viewer_never_drawn": 0,
-   "input_ms": {
-    "p50": 43.3,
-    "p95": 98.4,
-    "p99": 110.1,
-    "n": 18
-   },
-   "input_shown_ms": {
-    "p50": 54.7,
-    "p95": 98.9,
-    "p99": 114.0,
-    "n": 18
-   },
-   "input_parts_ms": {
-    "uplink": {
-     "p50": 17.1,
-     "p95": 48.3,
-     "p99": 53.1,
-     "n": 18
-    },
-    "mac": {
-     "p50": 12.5,
-     "p95": 32.9,
-     "p99": 35.7,
-     "n": 18
-    },
-    "back": {
-     "p50": 16.8,
-     "p95": 50.0,
-     "p99": 55.9,
-     "n": 18
-    }
-   },
-   "inputs": {
-    "asked": 18,
-    "sent": 18,
-    "seen": 18
-   },
-   "timeline": [
-    {
-     "t": 0,
-     "fps": 38,
-     "mbps": 0.3,
-     "content_p50": 14.8,
-     "content_p95": 25.3,
-     "bitrate": 2764800,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 1,
-     "fps": 33,
-     "mbps": 0.24,
-     "content_p50": 15.6,
-     "content_p95": 103.5,
-     "bitrate": 3845448,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 2,
-     "fps": 39,
-     "mbps": 0.28,
-     "content_p50": 15.6,
-     "content_p95": 29.9,
-     "bitrate": 5283790,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 3,
-     "fps": 25,
-     "mbps": 0.21,
-     "content_p50": 17.8,
-     "content_p95": 175.9,
-     "bitrate": 2764800,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 4,
-     "fps": 34,
-     "mbps": 0.22,
-     "content_p50": 15.4,
-     "content_p95": 69.8,
-     "bitrate": 2764800,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 5,
-     "fps": 38,
-     "mbps": 0.29,
-     "content_p50": 17.7,
-     "content_p95": 68.7,
-     "bitrate": 2764800,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 6,
-     "fps": 38,
-     "mbps": 0.26,
-     "content_p50": 15.0,
-     "content_p95": 18.2,
-     "bitrate": 3091280,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 7,
-     "fps": 30,
-     "mbps": 0.22,
-     "content_p50": 19.2,
-     "content_p95": 111.0,
-     "bitrate": 1725204,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 8,
-     "fps": 35,
-     "mbps": 0.26,
-     "content_p50": 13.4,
-     "content_p95": 102.6,
-     "bitrate": 1725204,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 9,
-     "fps": 38,
-     "mbps": 0.28,
-     "content_p50": 12.3,
-     "content_p95": 20.9,
-     "bitrate": 1725204,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 10,
-     "fps": 3,
-     "mbps": 0.02,
-     "content_p50": 20.9,
-     "content_p95": 24.7,
-     "bitrate": 1725204,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    }
-   ],
-   "adapt": [],
-   "content_p50": 15.1,
-   "content_p95": 80.3,
-   "input_p50": 43.3,
-   "input_p95": 98.4,
-   "grades": {
-    "input_replies": "local",
-    "content_p50": "local",
-    "content_p95": "acceptable",
-    "input_p50": "local",
-    "input_p95": "acceptable",
-    "fps": "bad",
-    "late_pct": "bad",
-    "stall_max": "acceptable"
-   },
-   "controller": {
-    "target": 3442081,
-    "ceiling": 5529600,
-    "tier": 0,
-    "fps": 60,
-    "scale": 1.0,
-    "baseRtt": 13.334,
-    "inFlight": 1,
-    "slack": 71.738,
-    "adapt": true
-   },
-   "events": [
-    {
-     "t": 3.77,
-     "e": "target 2764800 bit/s; tier 0"
-    },
-    {
-     "t": 7.42,
-     "e": "target 1725204 bit/s; tier 0"
-    }
-   ],
-   "source_fps": 60.1,
-   "cpu": {
-    "host": "not sampled"
-   },
-   "viewer": "h264 software; ANGLE (Mesa, zink Vulkan 1.4(Turnip Adreno (TM) 750 (MESA_TURNIP)), OpenGL 4.6); raf 71 Hz",
-   "show_s": 1.88,
-   "panel": "valve.steam.desktopgame.2001932457",
-   "src": "test",
-   "route": "network"
-  }
- ],
- "proof": "Synthetic x264 PC agent runs on the Frame itself, forwarded via Mac and back. Not Windows/Linux desktop capture or laser input."
-}

bench/results/2026-09-28-cd20243-pc-agent-frame-arm64-final.json

@@ -1,302 +0,0 @@
-{
- "label": "pc-agent-frame-arm64-final",
- "date": "2026-09-28T22:55:27",
- "commit": "cd20243",
- "config": {
-  "quality": "balanced",
-  "mode": "native",
-  "net": "none",
-  "delay_ms": 0,
-  "buffer_ms": 250,
-  "host": "frame",
-  "usb": false,
-  "ssh_opts": [],
-  "encoder": "",
-  "duration_s": 10.0,
-  "browser_flags": []
- },
- "frame_build": "20260925.6191901",
- "mac": "26.5.2",
- "host_platform": "Linux aarch64, SteamOS Frame, BUILD_ID 20260925.6191901 (synthetic host only)",
- "source": "",
- "pc_host": true,
- "headset": "0:03.056203 [Info] - 1 - leaving standby",
- "scenarios": [
-  {
-   "scenario": "test",
-   "frames_sent": 400,
-   "frames_drawn": 400,
-   "frames_shown": 339,
-   "duration_s": 10.2,
-   "stages_ms": {
-    "capture": {
-     "p50": 0.1,
-     "p95": 0.1,
-     "p99": 0.2,
-     "n": 400
-    },
-    "queue": {
-     "p50": 0.1,
-     "p95": 0.2,
-     "p99": 0.4,
-     "n": 400
-    },
-    "encode": {
-     "p50": 2.0,
-     "p95": 2.7,
-     "p99": 3.1,
-     "n": 400
-    },
-    "socket": {
-     "p50": 0.1,
-     "p95": 0.3,
-     "p99": 0.4,
-     "n": 400
-    },
-    "network": {
-     "p50": 11.8,
-     "p95": 25.2,
-     "p99": 37.8,
-     "n": 400
-    },
-    "decode": {
-     "p50": 0.7,
-     "p95": 1.5,
-     "p99": 2.0,
-     "n": 400
-    },
-    "draw": {
-     "p50": 0.3,
-     "p95": 0.7,
-     "p99": 1.0,
-     "n": 400
-    },
-    "present": {
-     "p50": 0.8,
-     "p95": 19.3,
-     "p99": 26.8,
-     "n": 339
-    },
-    "content": {
-     "p50": 15.1,
-     "p95": 28.6,
-     "p99": 41.3,
-     "n": 400
-    },
-    "content_shown": {
-     "p50": 17.6,
-     "p95": 39.0,
-     "p99": 47.2,
-     "n": 339
-    }
-   },
-   "fps": 39.3,
-   "fps_shown": 33.4,
-   "late_pct": 50.25,
-   "stall_max": 69.3,
-   "stalls_over_100ms": 0,
-   "mbps": 0.35,
-   "keyframes": 6,
-   "size": "1280x720",
-   "captured": 612,
-   "viewer_never_drawn": 0,
-   "input_ms": {
-    "p50": 76.6,
-    "p95": 98.2,
-    "p99": 127.8,
-    "n": 19
-   },
-   "input_shown_ms": {
-    "p50": 80.5,
-    "p95": 107.8,
-    "p99": 128.1,
-    "n": 16
-   },
-   "input_parts_ms": {
-    "uplink": {
-     "p50": 36.5,
-     "p95": 57.6,
-     "p99": 83.2,
-     "n": 19
-    },
-    "mac": {
-     "p50": 14.6,
-     "p95": 31.3,
-     "p99": 31.7,
-     "n": 19
-    },
-    "back": {
-     "p50": 15.1,
-     "p95": 32.8,
-     "p99": 36.2,
-     "n": 19
-    }
-   },
-   "inputs": {
-    "asked": 19,
-    "sent": 19,
-    "seen": 19
-   },
-   "timeline": [
-    {
-     "t": 0,
-     "fps": 40,
-     "mbps": 0.34,
-     "content_p50": 11.7,
-     "content_p95": 27.4,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 1,
-     "fps": 39,
-     "mbps": 0.37,
-     "content_p50": 11.9,
-     "content_p95": 28.2,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 2,
-     "fps": 41,
-     "mbps": 0.35,
-     "content_p50": 11.4,
-     "content_p95": 16.6,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 3,
-     "fps": 39,
-     "mbps": 0.37,
-     "content_p50": 12.7,
-     "content_p95": 28.0,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 4,
-     "fps": 38,
-     "mbps": 0.33,
-     "content_p50": 15.3,
-     "content_p95": 30.0,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 5,
-     "fps": 39,
-     "mbps": 0.37,
-     "content_p50": 16.7,
-     "content_p95": 28.5,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 6,
-     "fps": 41,
-     "mbps": 0.38,
-     "content_p50": 15.9,
-     "content_p95": 29.4,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 7,
-     "fps": 41,
-     "mbps": 0.31,
-     "content_p50": 15.6,
-     "content_p95": 28.2,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 8,
-     "fps": 38,
-     "mbps": 0.38,
-     "content_p50": 15.5,
-     "content_p95": 25.9,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 9,
-     "fps": 38,
-     "mbps": 0.29,
-     "content_p50": 16.7,
-     "content_p95": 28.8,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    },
-    {
-     "t": 10,
-     "fps": 6,
-     "mbps": 0.03,
-     "content_p50": 17.6,
-     "content_p95": 23.1,
-     "bitrate": 5529600,
-     "tier": 0,
-     "w": 1280,
-     "net": null
-    }
-   ],
-   "adapt": [],
-   "content_p50": 15.1,
-   "content_p95": 28.6,
-   "input_p50": 76.6,
-   "input_p95": 98.2,
-   "grades": {
-    "input_replies": "local",
-    "content_p50": "local",
-    "content_p95": "local",
-    "input_p50": "acceptable",
-    "input_p95": "acceptable",
-    "fps": "bad",
-    "late_pct": "bad",
-    "stall_max": "local"
-   },
-   "controller": {
-    "target": 5529600,
-    "ceiling": 5529600,
-    "tier": 0,
-    "fps": 60,
-    "scale": 1.0,
-    "baseRtt": 12.332,
-    "inFlight": 0,
-    "slack": 74.12,
-    "adapt": true
-   },
-   "events": [],
-   "source_fps": 60.0,
-   "cpu": {
-    "host": "not sampled"
-   },
-   "viewer": "h264 software; ANGLE (Mesa, zink Vulkan 1.4(Turnip Adreno (TM) 750 (MESA_TURNIP)), OpenGL 4.6); raf 72 Hz",
-   "show_s": 1.75,
-   "panel": "valve.steam.desktopgame.2001932457",
-   "src": "test",
-   "route": "network"
-  }
- ],
- "proof": "Synthetic x264 PC agent runs on the Frame itself, forwarded via Mac and back. Not Windows/Linux desktop capture or laser input."
-}

desktop/build-controller.py

@@ -1,16 +0,0 @@
-#!/usr/bin/env python3
-"""Build the common controller for the Python PC host (a C11 compiler needed)."""
-import os
-from pathlib import Path
-import subprocess
-import sys
-
-root = Path(__file__).resolve().parent
-suffix = '.dll' if sys.platform == 'win32' else '.dylib' if sys.platform == 'darwin' else '.so'
-out = root / ('controller' + suffix)
-if sys.platform == 'win32' and os.environ.get('CC', 'cl') == 'cl':
-    cmd = ['cl', '/nologo', '/O2', '/LD', '/std:c11', str(root / 'controller.c'), '/link', '/OUT:' + str(out)]
-else:
-    cmd = [os.environ.get('CC', 'cc'), '-O2', '-std=c11', '-shared', '-fPIC', str(root / 'controller.c'), '-o', str(out)]
-subprocess.run(cmd, cwd=root, check=True)
-print(out)

desktop/build.py

@@ -1,118 +0,0 @@
-#!/usr/bin/env python3
-"""Build our native PC adapter and bundle its ordinary shared libraries.
-
-Run on the target architecture after installing GStreamer development packages.
-No GStreamer executable or desktop streaming application is shipped or invoked.
-Linux libc, display/GPU drivers and the portal service remain platform pieces.
-"""
-import argparse
-import json
-import os
-from pathlib import Path
-import re
-import shutil
-import subprocess
-import sys
-
-ROOT = Path(__file__).resolve().parent
-
-
-def output(*args):
-    return subprocess.check_output(args, text=True).strip()
-
-
-def build(destination):
-    win = sys.platform == 'win32'
-    destination.mkdir(parents=True, exist_ok=True)
-    modules = ['gstreamer-1.0', 'gstreamer-app-1.0', 'gstreamer-video-1.0']
-    if not win:
-        modules += ['gio-unix-2.0']
-    import shlex
-    flags = shlex.split(output('pkg-config', '--cflags', '--libs', *modules))
-    lib = destination / ('pc-host.dll' if win else 'pc-host.so')
-    cmd = [os.environ.get('CC', 'gcc' if win else 'cc'), '-std=c11', '-O2', '-shared', '-Wall', '-Wextra']
-    if not win:
-        cmd += ['-fPIC', '-Wl,-rpath,$ORIGIN/lib']
-    subprocess.run(cmd + [str(ROOT / f) for f in ('controller.c', 'capture.c', 'portal.c')] + flags + ['-o', str(lib)], check=True)
-    prefix = Path(output('pkg-config', '--variable=prefix', 'gstreamer-1.0'))
-    plugin_dir = Path(output('pkg-config', '--variable=pluginsdir', 'gstreamer-1.0'))
-    plugins_out, libs_out = destination / 'lib' / 'gstreamer-1.0', destination / ('bin' if win else 'lib')
-    plugins_out.mkdir(parents=True, exist_ok=True)
-    libs_out.mkdir(parents=True, exist_ok=True)
-    names = ['coreelements', 'videotestsrc', 'videoconvertscale', 'app', 'jpeg', 'videoparsersbad', 'x264']
-    names += ['d3d11', 'mediafoundation'] if win else ['pipewire', 'va']
-    pending = [lib]
-    for name in names:
-        matches = list(plugin_dir.glob('*gst' + name + ('.dll' if win else '.so')))
-        if not matches:
-            raise SystemExit('Missing GStreamer library: ' + name)
-        for source in matches:
-            target = plugins_out / source.name
-            shutil.copy2(source, target)
-            pending.append(source)
-    if not win:
-        # PipeWire dynamically loads support and protocol modules. ldd cannot
-        # discover those; bundle them with a private client-only config instead
-        # of accidentally loading a different distro's client modules/config.
-        libdir = plugin_dir.parent
-        for relative in ('pipewire-0.3/libpipewire-module-protocol-native.so',
-                         'pipewire-0.3/libpipewire-module-client-node.so',
-                         'pipewire-0.3/libpipewire-module-adapter.so',
-                         'spa-0.2/support/libspa-support.so',
-                         'spa-0.2/support/libspa-dbus.so',
-                         'spa-0.2/videoconvert/libspa-videoconvert.so'):
-            source = libdir / relative
-            if not source.is_file():
-                raise SystemExit('Missing PipeWire runtime library: ' + str(source))
-            target = destination / 'lib' / relative
-            target.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(source, target)
-            pending.append(source)
-        config = destination / 'share' / 'pipewire'
-        config.mkdir(parents=True, exist_ok=True)
-        (config / 'client.conf').write_text(
-            'context.spa-libs = { support.* = support/libspa-support video.* = videoconvert/libspa-videoconvert }\n'
-            'context.modules = [\n'
-            '  { name = libpipewire-module-protocol-native }\n'
-            '  { name = libpipewire-module-client-node }\n'
-            '  { name = libpipewire-module-adapter }\n'
-            ']\n')
-    copied = set()
-    while pending:
-        binary = pending.pop()
-        if win:
-            imported = re.findall(r'DLL Name:\s*(\S+)', output('objdump', '-p', str(binary)))
-            dependencies = [prefix / 'bin' / name for name in imported]
-        else:
-            dependencies = [Path(p) for p in re.findall(r'=>\s+(/\S+)', output('ldd', str(binary)))]
-        for dep in dependencies:
-            if not dep.is_file() or dep.name in copied:
-                continue
-            if not win and re.match(r'lib(c|m|dl|rt|pthread|resolv)\.so', dep.name):
-                continue
-            shutil.copy2(dep, libs_out / dep.name)
-            copied.add(dep.name)
-            pending.append(dep)
-    # License texts and package provenance accompany the dynamically linked
-    # libraries. Distribution builders keep the upstream package/source URLs.
-    licenses = destination / 'licenses'
-    licenses.mkdir(exist_ok=True)
-    if win:
-        source = prefix / 'share' / 'licenses'
-        if source.exists():
-            shutil.copytree(source, licenses, dirs_exist_ok=True)
-        packages = output('pacman', '-Q') if shutil.which('pacman') else 'See MSYS2 build log'
-    else:
-        packages = output('dpkg-query', '-W', '-f=${Package} ${Version}\n') if shutil.which('dpkg-query') else ''
-        # Debian copyright files contain licenses and source homepage details.
-        for path in Path('/usr/share/doc').glob('*/copyright'):
-            shutil.copy2(path, licenses / (path.parent.name + '.copyright'))
-    (destination / 'libraries.json').write_text(json.dumps(dict(gstreamer=output('pkg-config', '--modversion', 'gstreamer-1.0'),
-        libraries=sorted(copied), packages=packages), indent=2))
-    print(lib)
-
-
-if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--out', type=Path, default=ROOT / 'bundle')
-    build(parser.parse_args().out.resolve())

desktop/capture.c

@@ -1,125 +0,0 @@
-/* Frame Control's capture/encode adapter. GStreamer is a bundled library;
- * capture uses WGC on Windows and the consented PipeWire fd on Linux. */
-#include "controller.h"
-#include <gst/gst.h>
-#include <gst/app/gstappsink.h>
-#include <gst/video/video-event.h>
-#include <string.h>
-
-typedef int (*Gate)(int stage, int64_t pts, int64_t capture, int64_t arrived);
-typedef struct {
-    GstElement *pipeline, *encoder, *sink, *raw_queue;
-    Gate gate;
-    GstSample *sample;
-    GstMapInfo map;
-    int mapped;
-    char error[512];
-} Capture;
-typedef struct { const unsigned char *data; int size, key, width, height; int64_t pts; } Encoded;
-FC_API int64_t fc_now(void) {return g_get_monotonic_time();}
-FC_API void fc_gst_init(void) {gst_init(NULL,NULL);}
-FC_API int fc_has_element(const char *name) {
-    GstElementFactory *f=gst_element_factory_find(name);
-    if(!f)return 0;gst_object_unref(f);return 1;
-}
-static GstPadProbeReturn probe(GstPad *pad,GstPadProbeInfo *info,gpointer data) {
-    Capture *c=data; GstBuffer *b=GST_PAD_PROBE_INFO_BUFFER(info);
-    if(!b)return GST_PAD_PROBE_OK;
-    int64_t now=fc_now(), cap=now;
-    GstClock *clock=gst_element_get_clock(c->pipeline);
-    if(clock && GST_BUFFER_PTS_IS_VALID(b)) {
-        GstClockTime current=gst_clock_get_time(clock),origin=gst_element_get_base_time(c->pipeline);
-        if(current>=origin && current-origin>=GST_BUFFER_PTS(b))
-            cap-= (int64_t)((current-origin-GST_BUFFER_PTS(b))/1000);
-    }
-    if(clock)gst_object_unref(clock);
-    int stage=GPOINTER_TO_INT(g_object_get_data(G_OBJECT(pad),"stage"));
-    if(stage==1) return c->gate(stage,(int64_t)GST_BUFFER_PTS(b),cap,now)>0 ? GST_PAD_PROBE_OK : GST_PAD_PROBE_DROP;
-    int phase=0;
-    for(;;) {
-        /* While congested, prefer a newer raw picture queued upstream. If
-         * nothing changed, retain this last picture until the gate opens;
-         * an idle window must not stay stale after a dropped final update. */
-        guint queued=0;
-        if(phase && c->raw_queue)g_object_get(c->raw_queue,"current-level-buffers",&queued,NULL);
-        if(queued)return GST_PAD_PROBE_DROP;
-        int decision=c->gate(phase,(int64_t)GST_BUFFER_PTS(b),cap,now);
-        if(decision)return decision>0 ? GST_PAD_PROBE_OK : GST_PAD_PROBE_DROP;
-        phase=2;g_usleep(2000);
-    }
-}
-FC_API Capture *fc_capture_open(const char *pipeline,Gate gate,char *error,int capacity) {
-    GError *e=NULL;Capture *c=g_new0(Capture,1);c->gate=gate;
-    c->pipeline=gst_parse_launch(pipeline,&e);
-    if(e || !c->pipeline) {
-        g_strlcpy(error,e?e->message:"No pipeline",capacity);
-        if(e)g_error_free(e);if(c->pipeline)gst_object_unref(c->pipeline);g_free(c);return NULL;
-    }
-    c->encoder=gst_bin_get_by_name(GST_BIN(c->pipeline),"enc");
-    c->sink=gst_bin_get_by_name(GST_BIN(c->pipeline),"out");
-    GstElement *raw=gst_bin_get_by_name(GST_BIN(c->pipeline),"gate");
-    if(!c->encoder || !c->sink || !raw) {
-        g_strlcpy(error,"Pipeline is missing enc, out or gate",capacity);
-        if(raw)gst_object_unref(raw);if(c->encoder)gst_object_unref(c->encoder);
-        if(c->sink)gst_object_unref(c->sink);gst_object_unref(c->pipeline);g_free(c);return NULL;
-    }
-    c->raw_queue=gst_bin_get_by_name(GST_BIN(c->pipeline),"raw_queue");
-    GstPad *p=gst_element_get_static_pad(raw,"src");
-    g_object_set_data(G_OBJECT(p),"stage",GINT_TO_POINTER(0));
-    gst_pad_add_probe(p,GST_PAD_PROBE_TYPE_BUFFER,probe,c,NULL);gst_object_unref(p);gst_object_unref(raw);
-    p=gst_element_get_static_pad(c->encoder,"sink");
-    g_object_set_data(G_OBJECT(p),"stage",GINT_TO_POINTER(1));
-    gst_pad_add_probe(p,GST_PAD_PROBE_TYPE_BUFFER,probe,c,NULL);gst_object_unref(p);
-    gst_element_set_state(c->pipeline,GST_STATE_PLAYING);
-    return c;
-}
-FC_API int fc_capture_pull(Capture *c,Encoded *out) {
-    if(c->mapped) {gst_buffer_unmap(gst_sample_get_buffer(c->sample),&c->map);c->mapped=0;}
-    if(c->sample){gst_sample_unref(c->sample);c->sample=NULL;}
-    GstBus *bus=gst_element_get_bus(c->pipeline);
-    GstMessage *m=gst_bus_pop_filtered(bus,GST_MESSAGE_ERROR);gst_object_unref(bus);
-    if(m) {
-        if(GST_MESSAGE_TYPE(m)==GST_MESSAGE_ERROR) {
-            GError *e=NULL;char *debug=NULL;gst_message_parse_error(m,&e,&debug);
-            g_strlcpy(c->error,e->message,sizeof(c->error));g_error_free(e);g_free(debug);
-        } else g_strlcpy(c->error,"The capture source closed",sizeof(c->error));
-        gst_message_unref(m);return -1;
-    }
-    c->sample=gst_app_sink_try_pull_sample(GST_APP_SINK(c->sink),100*GST_MSECOND);
-    if(!c->sample) {
-        if(gst_app_sink_is_eos(GST_APP_SINK(c->sink))) {
-            g_strlcpy(c->error,"The capture source closed",sizeof(c->error));return -1;
-        }
-        return 0;
-    }
-    GstBuffer *b=gst_sample_get_buffer(c->sample);
-    if(!gst_buffer_map(b,&c->map,GST_MAP_READ))return 0;
-    c->mapped=1;out->data=c->map.data;out->size=(int)c->map.size;
-    out->key=!GST_BUFFER_FLAG_IS_SET(b,GST_BUFFER_FLAG_DELTA_UNIT);out->pts=(int64_t)GST_BUFFER_PTS(b);
-    const GstStructure *s=gst_caps_get_structure(gst_sample_get_caps(c->sample),0);
-    gst_structure_get_int(s,"width",&out->width);gst_structure_get_int(s,"height",&out->height);return 1;
-}
-FC_API const char *fc_capture_error(Capture *c) {return c->error;}
-FC_API void fc_capture_bitrate(Capture *c,int bps) {
-    g_object_set(c->encoder,"bitrate",(guint)MAX(1,bps/1000),NULL);
-}
-FC_API void fc_capture_test(Capture *c,uint32_t input) {
-    GstElement *source=gst_bin_get_by_name(GST_BIN(c->pipeline),"source");
-    if(source) {
-        /* Each benchmark click visibly changes the ball, before injection is
-         * timestamped. This is a response, not merely a protocol input echo. */
-        guint color=0xff000000u | ((input*2654435761u)&0x00ffffffu);
-        g_object_set(source,"foreground-color",color,NULL);gst_object_unref(source);
-    }
-}
-FC_API void fc_capture_key(Capture *c) {
-    GstPad *p=gst_element_get_static_pad(c->encoder,"src");
-    gst_pad_send_event(p,gst_video_event_new_upstream_force_key_unit(GST_CLOCK_TIME_NONE,TRUE,0));gst_object_unref(p);
-}
-FC_API void fc_capture_close(Capture *c) {
-    gst_element_set_state(c->pipeline,GST_STATE_NULL);
-    if(c->mapped)gst_buffer_unmap(gst_sample_get_buffer(c->sample),&c->map);
-    if(c->sample)gst_sample_unref(c->sample);
-    if(c->raw_queue)gst_object_unref(c->raw_queue);
-    gst_object_unref(c->sink);gst_object_unref(c->encoder);gst_object_unref(c->pipeline);g_free(c);
-}

desktop/controller.c

@@ -1,127 +0,0 @@
-/* Extracted from the Mac agent's RateController. Same gate, demand protection,
- * bitrate recovery and tier hysteresis for every host. Bounded sample buffers. */
-#include "controller.h"
-#include <stdlib.h>
-#include <string.h>
-#define CAP 1024
-#define MIN(a,b) ((a)<(b)?(a):(b))
-#define MAX(a,b) ((a)>(b)?(a):(b))
-typedef struct { int64_t t, v; uint32_t seq; } Sample;
-typedef struct { Sample a[CAP]; int n; } Samples;
-struct FCController {
-    int max_fps, enabled, ceiling, target, tier, frame_bytes, held, signal, saw_ack;
-    int64_t decrease, increase, below, above, slack;
-    Samples flight, rtts, acked, sent, captures;
-};
-static const int fps[] = {60,45,30,30,30}, scale[] = {100,100,100,75,50};
-static const double floors[] = {.45,.28,.16,.08,0};
-static void remove_first(Samples *s, int n) {
-    s->n -= n; memmove(s->a, s->a+n, (size_t)s->n*sizeof(Sample));
-}
-static void add(Samples *s, Sample v, int cap) {
-    if (s->n >= cap) remove_first(s, 1);
-    s->a[s->n++] = v;
-}
-static void expire(Samples *s, int64_t oldest) {
-    int n=0; while(n<s->n && s->a[n].t<oldest) n++;
-    remove_first(s,n);
-}
-static int64_t base(FCController *c) {
-    int64_t v=0;
-    for(int i=0;i<c->rtts.n;i++) if(!i || c->rtts.a[i].v<v) v=c->rtts.a[i].v;
-    return v;
-}
-static int compare(const void *a, const void *b) {
-    int64_t x=*(const int64_t*)a, y=*(const int64_t*)b;
-    return (x>y)-(x<y);
-}
-static int64_t quantile(Samples *s,int64_t since,int numerator,int denominator) {
-    int64_t a[CAP]; int n=0;
-    for(int i=0;i<s->n;i++) if(s->a[i].t>since) a[n++]=s->a[i].v;
-    if(!n) return 0;
-    qsort(a,(size_t)n,sizeof(int64_t),compare);
-    return a[n*numerator/denominator];
-}
-static int rate(Samples *s) {
-    int64_t total=0; for(int i=0;i<s->n;i++) total+=s->a[i].v;
-    return (int)MIN(total*16,2147483647);
-}
-FCController *fc_new(int max_fps,int enabled) {
-    FCController *c=calloc(1,sizeof(*c));
-    if(c) {c->max_fps=MAX(1,max_fps);c->enabled=enabled;c->slack=40000;}
-    return c;
-}
-void fc_free(FCController *c) {free(c);}
-void fc_ceiling(FCController *c,int bps) {
-    if(!c->target || c->target>bps) c->target=bps;
-    c->ceiling=bps;
-}
-int fc_gate(FCController *c,int64_t now,int counts) {
-    if(!c->enabled || !c->saw_ack) return 1;
-    expire(&c->flight,now-2000000);
-    if(!c->flight.n) return 1;
-    int64_t interval=1000000/MIN(c->max_fps,fps[c->tier]);
-    int window=MAX(3,(int)((base(c)+c->slack)/interval)+1);
-    if(c->flight.n<window && now-c->flight.a[0].t<=base(c)+c->slack) return 1;
-    if(counts) c->held++;
-    return 0;
-}
-void fc_capture(FCController *c,int64_t now) {add(&c->captures,(Sample){now,0,0},256);}
-void fc_sent(FCController *c,uint32_t seq,int bytes,int64_t now) {
-    Sample s={now,bytes,seq};add(&c->flight,s,512);add(&c->sent,s,CAP);
-}
-int fc_ack(FCController *c,uint32_t seq,int64_t now) {
-    c->saw_ack=1;
-    for(int i=0;i<c->flight.n;i++) if(c->flight.a[i].seq==seq) {
-        Sample s=c->flight.a[i];remove_first(&c->flight,i+1);
-        add(&c->rtts,(Sample){now,now-s.t,0},CAP);
-        add(&c->acked,(Sample){now,s.v,0},CAP);return 1;
-    }
-    return 0;
-}
-int fc_update(FCController *c,int64_t now) {
-    expire(&c->rtts,now-10000000);expire(&c->acked,now-500000);
-    expire(&c->sent,now-500000);expire(&c->flight,now-2000000);
-    expire(&c->captures,now-1000000);
-    if(!c->enabled || c->ceiling<=0) return 0;
-    int64_t baseline=base(c), spread=quantile(&c->rtts,now-2000000,9,10);
-    int64_t jitter=spread ? spread-baseline : 0;
-    c->slack=1000000/MIN(c->max_fps,fps[c->tier])+MIN(MAX(jitter*3/2,25000),80000);
-    int64_t recent=quantile(&c->rtts,now-300000,1,2);
-    int64_t queue=recent ? recent-baseline : 0;
-    int64_t age=c->flight.n ? now-c->flight.a[0].t : 0;
-    int delivered=rate(&c->acked),sending=rate(&c->sent);
-    if(c->sent.n) c->frame_bytes=sending/16/c->sent.n;
-    int demand=(int)MIN((int64_t)MIN(c->captures.n,MIN(c->max_fps,fps[c->tier]))*c->frame_bytes*8,2147483647);
-    int signal=(sending>=c->target/2 && queue>40000)||c->held>=3||age>baseline+100000;
-    int congested=signal && c->signal;c->signal=signal;c->held=0;
-    if(congested && now-c->decrease>300000) {
-        int next=MAX(300000,MIN((int64_t)c->target*4/5,MAX((int64_t)delivered*9/10,c->target/2)));
-        if(demand>0 && (int64_t)demand*2<=(int64_t)c->target*5/4) next=MAX(next,MIN(c->target,(int64_t)demand*2));
-        c->target=next;c->decrease=now;
-    } else if(!congested && now-c->decrease>1000000 && now-c->increase>250000 && c->target<c->ceiling &&
-              (sending>(int64_t)c->target*6/10 || now-c->decrease>3000000)) {
-        c->target=MIN(c->ceiling,(int64_t)(c->target*1.1)+50000);c->increase=now;
-    }
-    double share=(double)c->target/MAX(c->ceiling,1);
-    if(c->tier<4 && share<floors[c->tier] && sending>=(int64_t)c->target*7/10) {
-        if(!c->below)c->below=now;
-        if(now-c->below>500000) {
-            for(c->tier=0;c->tier<4 && share<floors[c->tier];c->tier++) {}
-            c->below=0;
-        }
-    } else c->below=0;
-    if(c->tier>0 && share>floors[c->tier-1]*1.25) {
-        if(!c->above)c->above=now;
-        if(now-c->above>2000000) {c->tier--;c->above=0;}
-    } else c->above=0;
-    return c->target;
-}
-int64_t fc_value(FCController *c,int field) {
-    switch(field) {
-    case 0:return c->target;case 1:return c->ceiling;case 2:return c->tier;
-    case 3:return MIN(c->max_fps,fps[c->tier]);case 4:return scale[c->tier];
-    case 5:return base(c);case 6:return c->flight.n;case 7:return c->slack;
-    default:return 0;
-    }
-}

desktop/controller.h

@@ -1,29 +0,0 @@
-/* Shared latency controller. Times are monotonic host microseconds.
- * Callers serialize access. Capture is gated BEFORE encoding: dropping an
- * encoded inter frame would break the decoder's reference chain. */
-#ifndef FRAME_CONTROLLER_H
-#define FRAME_CONTROLLER_H
-#include <stdint.h>
-#ifdef _WIN32
-#define FC_API __declspec(dllexport)
-#else
-#define FC_API
-#endif
-#ifdef __cplusplus
-extern "C" {
-#endif
-typedef struct FCController FCController;
-FC_API FCController *fc_new(int fps, int enabled);
-FC_API void fc_free(FCController *c);
-FC_API void fc_ceiling(FCController *c, int bps);
-FC_API int fc_gate(FCController *c, int64_t now, int counts);
-FC_API void fc_capture(FCController *c, int64_t now);
-FC_API void fc_sent(FCController *c, uint32_t seq, int bytes, int64_t now);
-FC_API int fc_ack(FCController *c, uint32_t seq, int64_t now);
-FC_API int fc_update(FCController *c, int64_t now);
-/* target, ceiling, tier, fps, scale percent, baseline us, in flight, slack us */
-FC_API int64_t fc_value(FCController *c, int field);
-#ifdef __cplusplus
-}
-#endif
-#endif

desktop/portal.c

@@ -1,147 +0,0 @@
-/* xdg-desktop-portal RemoteDesktop + ScreenCast, one consented session per
- * panel. PipeWire receives the portal fd, never the unrestricted daemon fd.
- * Input uses only the devices granted in Start's response. */
-#ifndef _WIN32
-#include "controller.h"
-#include <gio/gio.h>
-#include <gio/gunixfdlist.h>
-#include <unistd.h>
-#include <string.h>
-#define BUS "org.freedesktop.portal.Desktop"
-#define PATH "/org/freedesktop/portal/desktop"
-#define RD "org.freedesktop.portal.RemoteDesktop"
-#define SC "org.freedesktop.portal.ScreenCast"
-typedef struct {
-    GDBusConnection *bus;
-    GMainContext *context;
-    char *session;
-    int fd;
-    unsigned node, devices;
-    int width,height;
-} Portal;
-typedef struct {GVariant *result;int done;unsigned code;} Response;
-static void response(GDBusConnection *c,const char *sender,const char *path,const char *iface,
-                     const char *signal,GVariant *params,gpointer data) {
-    (void)c;(void)sender;(void)path;(void)iface;(void)signal;
-    Response *r=data;g_variant_get(params,"(u@a{sv})",&r->code,&r->result);r->done=1;
-}
-static void option(GVariantBuilder *b,const char *key,GVariant *v) {g_variant_builder_add(b,"{sv}",key,v);}
-static GVariant *request(Portal *p,const char *iface,const char *method,GVariant *args,
-                         const char *token,char *error,int capacity) {
-    char *sender=g_strdup(g_dbus_connection_get_unique_name(p->bus)+1);
-    for(char *c=sender;*c;c++)if(*c=='.')*c='_';
-    char *path=g_strdup_printf(PATH "/request/%s/%s",sender,token);g_free(sender);
-    Response r={0};GError *e=NULL;
-    guint sub=g_dbus_connection_signal_subscribe(p->bus,BUS,"org.freedesktop.portal.Request","Response",
-                                                 path,NULL,G_DBUS_SIGNAL_FLAGS_NONE,response,&r,NULL);
-    GVariant *reply=g_dbus_connection_call_sync(p->bus,BUS,PATH,iface,method,args,G_VARIANT_TYPE("(o)"),
-                                               G_DBUS_CALL_FLAGS_NONE,10000,NULL,&e);
-    if(reply)g_variant_unref(reply);
-    int64_t deadline=g_get_monotonic_time()+120000000;
-    while(!e && !r.done && g_get_monotonic_time()<deadline) {
-        while(g_main_context_iteration(p->context,FALSE)) {}
-        g_usleep(10000);
-    }
-    if(!r.done) {
-        GVariant *closed=g_dbus_connection_call_sync(p->bus,BUS,path,"org.freedesktop.portal.Request","Close",
-                                NULL,NULL,G_DBUS_CALL_FLAGS_NONE,2000,NULL,NULL);
-        if(closed)g_variant_unref(closed);
-    }
-    g_dbus_connection_signal_unsubscribe(p->bus,sub);g_free(path);
-    if(e || !r.done || r.code) {
-        g_strlcpy(error,e?e->message:!r.done?"Screen sharing request timed out":"Screen sharing was cancelled or refused",capacity);
-        if(e)g_error_free(e);if(r.result)g_variant_unref(r.result);return NULL;
-    }
-    return r.result;
-}
-FC_API void fc_portal_close(Portal *p) {
-    if(!p)return;
-    if(p->session && p->bus) {
-        GVariant *r=g_dbus_connection_call_sync(p->bus,BUS,p->session,"org.freedesktop.portal.Session","Close",
-                                                NULL,NULL,G_DBUS_CALL_FLAGS_NONE,2000,NULL,NULL);
-        if(r)g_variant_unref(r);
-    }
-    if(p->fd>=0){close(p->fd);p->fd=-1;}
-    g_free(p->session);if(p->bus)g_object_unref(p->bus);
-    if(p->context)g_main_context_unref(p->context);g_free(p);
-}
-/* Each pipeline gets a fresh restricted PipeWire connection. A dup of a
- * previously consumed protocol socket is not a new connection.
- * Ownership: the Portal owns p->fd for its whole life and is its only closer.
- * pipewiresrc never takes the fd it is given: its core connects with
- * pw_context_connect_fd(ctx, fcntl(fd, F_DUPFD_CLOEXEC, 3), ...) and that
- * duplicate is what PipeWire closes on teardown (src/gst/gstpipewirecore.c,
- * unchanged from 0.3.19 through 1.x). So closing p->fd here is not a double
- * close; not closing it would leak one socket per pipeline reopen. The
- * caller closes the previous pipeline before asking for a new fd. */
-FC_API int fc_portal_refresh(Portal *p,char *error,int capacity) {
-    GVariantBuilder b;g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    GUnixFDList *fds=NULL;GError *e=NULL;
-    GVariant *r=g_dbus_connection_call_with_unix_fd_list_sync(p->bus,BUS,PATH,SC,"OpenPipeWireRemote",
-         g_variant_new("(oa{sv})",p->session,&b),G_VARIANT_TYPE("(h)"),G_DBUS_CALL_FLAGS_NONE,10000,NULL,&fds,NULL,&e);
-    if(!r){g_strlcpy(error,e->message,capacity);g_error_free(e);return -1;}
-    int handle;g_variant_get(r,"(h)",&handle);g_variant_unref(r);
-    int fd=g_unix_fd_list_get(fds,handle,&e);g_object_unref(fds);
-    if(fd<0){g_strlcpy(error,e->message,capacity);g_error_free(e);return -1;}
-    if(p->fd>=0)close(p->fd);
-    p->fd=fd;return fd;
-}
-FC_API Portal *fc_portal_select(char *error,int capacity) {
-    Portal *p=g_new0(Portal,1);p->fd=-1;p->context=g_main_context_new();
-    g_main_context_push_thread_default(p->context);
-    GError *e=NULL;GVariant *r=NULL;
-    p->bus=g_bus_get_sync(G_BUS_TYPE_SESSION,NULL,&e);
-    if(!p->bus) {g_strlcpy(error,e->message,capacity);g_error_free(e);goto fail;}
-    GVariantBuilder b;char token[64],session[64];
-    g_snprintf(session,sizeof(session),"fc_%u",g_random_int());
-    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());
-    g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    option(&b,"handle_token",g_variant_new_string(token));option(&b,"session_handle_token",g_variant_new_string(session));
-    r=request(p,RD,"CreateSession",g_variant_new("(a{sv})",&b),token,error,capacity);if(!r)goto fail;
-    g_variant_lookup(r,"session_handle","s",&p->session);g_variant_unref(r);r=NULL;
-    if(!p->session){g_strlcpy(error,"Portal did not return a session",capacity);goto fail;}
-    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    option(&b,"handle_token",g_variant_new_string(token));option(&b,"types",g_variant_new_uint32(3));
-    r=request(p,RD,"SelectDevices",g_variant_new("(oa{sv})",p->session,&b),token,error,capacity);if(!r)goto fail;g_variant_unref(r);
-    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    option(&b,"handle_token",g_variant_new_string(token));option(&b,"types",g_variant_new_uint32(3));
-    option(&b,"multiple",g_variant_new_boolean(FALSE));option(&b,"cursor_mode",g_variant_new_uint32(2));
-    r=request(p,SC,"SelectSources",g_variant_new("(oa{sv})",p->session,&b),token,error,capacity);if(!r)goto fail;g_variant_unref(r);
-    g_snprintf(token,sizeof(token),"fc_%u",g_random_int());g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    option(&b,"handle_token",g_variant_new_string(token));
-    r=request(p,RD,"Start",g_variant_new("(osa{sv})",p->session,"",&b),token,error,capacity);if(!r)goto fail;
-    g_variant_lookup(r,"devices","u",&p->devices);
-    GVariant *streams=g_variant_lookup_value(r,"streams",G_VARIANT_TYPE("a(ua{sv})"));
-    if(streams && g_variant_n_children(streams)>0) {
-        GVariant *entry=g_variant_get_child_value(streams,0),*props=NULL;
-        g_variant_get(entry,"(u@a{sv})",&p->node,&props);
-        g_variant_lookup(props,"size","(ii)",&p->width,&p->height);
-        g_variant_unref(props);g_variant_unref(entry);
-    }
-    if(streams)g_variant_unref(streams);g_variant_unref(r);r=NULL;
-    if(!p->node || p->width<=0 || p->height<=0) {g_strlcpy(error,"Portal returned no stream size",capacity);goto fail;}
-    if(fc_portal_refresh(p,error,capacity)<0)goto fail;
-    g_main_context_pop_thread_default(p->context);return p;
-fail:
-    g_main_context_pop_thread_default(p->context);fc_portal_close(p);return NULL;
-}
-FC_API int fc_portal_value(Portal *p,int field) {
-    switch(field){case 0:return p->fd;case 1:return (int)p->node;case 2:return p->width;
-                 case 3:return p->height;case 4:return (int)p->devices;default:return 0;}
-}
-FC_API int fc_portal_input(Portal *p,int type,double x,double y,int code,int down) {
-    const char *method=NULL;GVariant *args=NULL;GVariantBuilder b;g_variant_builder_init(&b,G_VARIANT_TYPE_VARDICT);
-    if(type==0 && (p->devices&2)) {
-        method="NotifyPointerMotionAbsolute";args=g_variant_new("(oa{sv}udd)",p->session,&b,p->node,x,y);
-    } else if(type==1 && (p->devices&2)) {
-        method="NotifyPointerButton";args=g_variant_new("(oa{sv}iu)",p->session,&b,code,(guint)down);
-    } else if(type==2 && (p->devices&2)) {
-        method="NotifyPointerAxis";args=g_variant_new("(oa{sv}dd)",p->session,&b,x,y);
-    } else if(type==3 && (p->devices&1)) {
-        method="NotifyKeyboardKeysym";args=g_variant_new("(oa{sv}iu)",p->session,&b,code,(guint)down);
-    } else return 0;
-    GError *e=NULL;GVariant *r=g_dbus_connection_call_sync(p->bus,BUS,PATH,RD,method,args,NULL,
-                                                       G_DBUS_CALL_FLAGS_NONE,2000,NULL,&e);
-    if(e)g_error_free(e);if(r)g_variant_unref(r);return r!=NULL;
-}
-#endif

docs/agents.md

@@ -168,6 +168,43 @@ on this branch (run 36421345682).
 **Verified on the same Frame/build:** both Ctrl-C and SIGTERM close the dedicated
 browser profile and SSH tunnel and remove the profile and panel log.
 
+**Verified end to end on the same Frame/build (2026-09-29), with mutations:**
+a stdio MCP client started `ui/frame_mcp.py` in its default mode (private
+backend, no API key, no prestarted server) and a human approved or rejected
+each change in the approval page in a real Chrome window:
+
+| Tool | Result on the Frame |
+|---|---|
+| `send_file` | Approved; the file arrived in `~/Downloads` with identical contents |
+| `install` | Approved; `io.github.fizzyizzy05.binary` job finished in about 35 s |
+| `panel` | Approved; gamescope listed a new panel window, and `computer_state` reported the same window ID and PID. The app rendered in that window (below) |
+| `launch` | Approved; Keep Talking and Nobody Explodes (341800) started under Proton and `computer_state` reported it as the focused app |
+| `uninstall` | Approved; app and locale removed |
+| `power` | Rejected in the page. Unapproved retries, the same token used for `uninstall`, and a retry after rejection were all refused. Nothing was powered off |
+| `send_text` | Approved, then refused because the Plasma desktop was not open (documented requirement) |
+| `keep_awake` | `status` reports the script unavailable until PR #16 lands |
+
+A separate Claude Code CLI session, with only this server configured, read
+status, `computer_state` and a headset capture, and requested an install. It
+received an approval URL and did not execute anything.
+
+The assistant opened as a Frame panel through `scripts/assistant-on-frame.py`.
+Against a loopback stub model, a send without consent made zero requests. With
+consent it made exactly one, carrying the text and a fresh Frame screenshot.
+Consent unticked itself after sending. SIGTERM removed the panel, profile, log
+and tunnel.
+
+**Not verified while unworn:** every headset capture was a uniform dark frame,
+so SteamVR's rendered view of panels and the game could not be checked; window
+captures (`xwd`) were used instead. MCP can launch a game or panel but has no
+tool to stop one: the tester stopped them over SSH. Removing an app leaves any
+runtime it pulled in; Flatpak may also remove related extensions when that
+runtime is removed by hand.
+
+![Approval page showing the exact install action](img/mcp-approval-install.png)
+
+![The installed Flatpak rendering in its own gamescope panel window](img/mcp-panel-binary.png)
+
 ![Assistant in Frame Chromium, after an opted-in request to the local test endpoint](img/assistant-panel.png)
 
 ## Computer-use coverage

docs/apk-repos.md

@@ -0,0 +1,144 @@
+# APK repositories
+
+Frame Control supports **F-Droid-format repositories**, including F-Droid,
+F-Droid archive, IzzyOnDroid and user-provided HTTPS repositories. Repository
+indexes are authenticated before their apps appear. Search lists builds with
+Android API ≤30 and arm64-v8a or no native libraries, using the same streaming
+reducer as the existing catalogue. This does not guarantee an app works in Lepton.
+
+## Formats considered
+
+| Format | Users and purpose | Support in this source |
+|---|---|---|
+| F-Droid v2 | F-Droid, IzzyOnDroid, self-hosted fdroidserver repositories; consumed by F-Droid clients including Droid-ify and Neo Store | Preferred: signed `entry.jar` authenticates `entry.json`; its SHA-256 authenticates `index-v2.json`, which supplies APK SHA-256 hashes |
+| F-Droid v1 | Older F-Droid servers and clients | Fallback: verify `index-v1.jar`, then read its signed `index-v1.json` |
+| Obtainium configurations / exports | Obtainium users share app URLs plus source-specific filters and update settings; exports can contain a list of app configuration objects | Not imported here: configurations describe how to find releases, not one signed repository index |
+| SideQuest listings / custom feeds | SideQuest's own app discovery and installation service | No interoperable signed custom-repository specification was established from the public project documentation examined; SideQuest needs its own adapter |
+| GitHub release lists | Developers publish APK assets on release pages; community lists link to projects | Not a repository standard: asset naming, build selection and publisher verification vary; handled separately from this F-Droid source |
+| Minimal JSON list | A private list could contain package, title, APK URL and SHA-256 | Deliberately not introduced: unsigned hashes downloaded alongside files do not authenticate their publisher; another bespoke signing/update protocol would duplicate F-Droid |
+
+Research references (checked 2026-09-28):
+
+- [F-Droid APIs](https://f-droid.org/docs/All_our_APIs/) and
+  [repository setup](https://f-droid.org/docs/Setup_an_F-Droid_App_Repo/).
+- [F-Droid signing keys](https://f-droid.org/docs/Release_Channels_and_Signing_Keys/)
+  and [IzzyOnDroid's repository page and fingerprint](https://apt.izzysoft.de/fdroid/).
+- [Droid-ify](https://github.com/Droid-ify/client) and
+  [Neo Store](https://github.com/NeoApplications/Neo-Store).
+- [Obtainium](https://github.com/ImranR98/Obtainium), its
+  [configuration/deep-link format](https://wiki.obtainium.imranr.dev/deep_links/),
+  and [community app configurations](https://apps.obtainium.imranr.dev/).
+- [SideQuest's public client](https://github.com/SideQuestVR/SideQuest).
+  The absence of a specification in these materials is not proof that no
+  historical or private custom-feed format exists.
+
+## Add a repository in Frame Control
+
+From the Frame Control checkout, use its source-management CLI:
+
+```sh
+python3 ui/apk_sources/fdroid.py add 'https://example.org/fdroid/repo?fingerprint=YOUR_64_HEX_CERTIFICATE_FINGERPRINT' --name 'My apps'
+python3 ui/apk_sources/fdroid.py list
+python3 ui/apk_sources/fdroid.py search SOURCE_ID 'music'
+python3 ui/apk_sources/fdroid.py download SOURCE_ID org.example.app
+python3 ui/apk_sources/fdroid.py remove SOURCE_ID
+```
+
+Replace `SOURCE_ID` with the `id` printed by `add` or `list`. `--fingerprint`
+can also supply the pin. `fdroidrepos://example.org/fdroid/repo?fingerprint=…`
+links are accepted and converted to HTTPS. Conflicting fingerprints are refused.
+A URL must identify the repository directory, not its website or an index file.
+
+Adding fetches and validates the complete index **before saving** the source.
+Without a fingerprint, Frame Control verifies the JAR signature and remembers
+its signer: trust on first use (TOFU). This establishes continuity with the
+first server response, not independent publisher identity. Obtain the published
+fingerprint through a trusted channel when possible; the store's Add a source
+form shows the pinned one ("Trusted on first use: …") so you can compare it.
+Re-adding an existing URL preserves its pin; changing it requires deliberately
+removing and re-adding it.
+
+The API for the search/server integration is in `ui/apk_sources/fdroid.py`:
+`add_repo(url, fingerprint=None, name=None)`, `remove_repo(source_id)`,
+`set_enabled(source_id, enabled)`, and `user_repos()`. The module also exposes
+`sources`, `search`, `details`, and `download` from the shared source contract.
+This change supplies the CLI and API; the integrated source-management UI is
+separate work. Built-in sources can be disabled but cannot be removed.
+
+Settings and pins live in `frame_host.data_dir('apk-repos.json')`
+(`~/Library/Application Support/Frame Control/apk-repos.json` on macOS).
+Authenticated reduced indexes and APKs live under
+`frame_host.cache_dir('apk-sources')`; indexes refresh after 24 hours. An
+expired index is still served (marked stale in the store) while it refreshes in
+the background; a failed refresh is retried after 10 minutes.
+Only the running Frame Control app prunes cached APKs (at start and after store
+downloads); the command-line tools never do.
+The existing catalogue's unverified index cache is never treated as authenticated.
+
+Rollback protection: each repository's newest accepted signed index timestamp
+is kept in `apk-repo-state.json` next to the settings, and an older index is
+refused. Once a repository has served a v2 `entry.jar`, a missing `entry.jar`
+is an error rather than a reason to fall back to `index-v1.jar`. `entry.jar`
+must be signed with SHA-2 (SHA-1 is still accepted for legacy `index-v1.jar`).
+Removing a repository clears its state.
+
+## Publish your own repository
+
+Only publish free APKs you own or have the developer's permission to distribute.
+Do not publish paid app mirrors or bypass store licences. Check distribution
+terms before adding someone else's repository; this module does not infer legal
+permission from a signature or automatically audit a repository's terms.
+
+Install a current [fdroidserver](https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools/)
+and its documented Android/Java dependencies on the publishing machine, then:
+
+```sh
+mkdir my-fdroid
+cd my-fdroid
+fdroid init
+# Set repo_url in config.yml to https://example.org/fdroid/repo
+# Also set repo_name and repo_description; keep the generated signing key safe.
+cp /path/to/your-free-app.apk repo/
+fdroid update --create-metadata
+# Review the generated metadata (name, summary, licence, source and website).
+fdroid update
+```
+
+Serve the generated **repo directory** at that HTTPS URL, including APKs,
+icons, `entry.jar`, `index-v2.json` and `index-v1.jar`. Do not publish the
+private signing keystore or configuration passwords. Configure fdroidserver's
+`serverwebroot` and run `fdroid deploy` for managed publication, or copy the
+public directory with your existing deployment tool. Publish the SHA-256
+repository certificate fingerprint displayed by fdroidserver in a link such as
+`https://example.org/fdroid/repo?fingerprint=…`.
+
+Keep the repository signing key backed up: changing it breaks existing pins.
+For updates, add the new APK, edit metadata as needed, run `fdroid update` and
+publish again. Test the published URL with Frame Control's `add`, `search` and
+`download` commands. The above publisher setup is documented from fdroidserver;
+it was not executed as part of this implementation.
+
+## Verification and limits
+
+The stdlib verifier supports one RSA PKCS#1 v1.5 JAR/CMS signer with a key of
+2048–8192 bits; SHA-256/384/512 and legacy SHA-1 digest encodings are
+recognized. It checks the signer certificate pin, the signature over `.SF`,
+the whole-manifest digest, and the manifest's digest of the JSON member.
+ECDSA, DSA, RSA-PSS, multiple signers and section-only `.SF` manifests are
+rejected. Certificates are pinned identities, not validated as Web PKI chains.
+HTTPS certificates are separately checked by Python's normal TLS validation.
+
+v1 fallback occurs only when `entry.jar` returns HTTP 404 or 410. Signature,
+fingerprint, index hash, TLS and server errors never trigger an unsigned
+fallback. APKs are cached by SHA-256 and checked again before reuse. Here,
+`verified: true` means the bytes match the signed repository's APK hash; it
+is not an independent APK publisher-signature or runtime compatibility verdict.
+There is no repository timestamp rollback/expiry policy or automated signing-key
+rotation yet. An old correctly signed index can still validate.
+
+Offline fixtures exercise v2, v1, TOFU, pin changes, disabled sources, cache
+reuse, URL rejection and corruption of every signature/hash layer. On the Mac,
+the real IzzyOnDroid repository was added with its published pin, searched for
+Tiny Music Player, and its 16,520-byte APK downloaded with SHA-256
+`d7bcb24d101b04beb3394b695b24be4e2c3d6ed702f1d0e06bc4dd707f64d86a`.
+No headset connection or installation was performed.

docs/apk-sources.md

@@ -0,0 +1,103 @@
+# Developer-consented APK sources
+
+Surveyed 2026-09-28. Free access is not proof of redistribution permission or
+Frame compatibility. These adapters fetch only public publisher releases or
+link to publisher pages. They do not acquire store entitlements, defeat access
+checks, install anything, or rehost APKs. See [VR compatibility](vr-apks.md).
+
+| Source | Developer consent and automated-access position | API/feed; VR coverage | Decision |
+|---|---|---|---|
+| [itch.io](https://itch.io/docs/legal/terms) | Publishers warrant distribution rights (§4). Users may access content through the service; this is not blanket scraping permission. Main robots excludes `/game/download/`; author subdomains exclude `/*/download/`. No challenge bypass. | Public free Android RSS for `openxr` and `oculus-quest`; substantial indie VR. Server API is mostly authenticated publisher/account functionality, not a general anonymous store-download API. | Implement RSS search, artwork and page links; `downloadable: False`. The supplied free-download script follows keyed download pages excluded by robots, so it is not shipped. |
+| [GitHub releases](https://docs.github.com/en/rest/releases/releases) | Maintainers publish assets; curated repositories below establish provenance. Public hosting or an open-source topic alone does not establish rights to every uploaded binary. Use supported REST API under [API terms](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#h-api-terms), not HTML crawling. | Releases API includes APK assets and sometimes SHA-256. Topic search finds OpenXR/Quest projects. 60 unauthenticated requests/hour; authenticated user limits are generally 5,000/hour, with separate search/secondary limits. | Implement curated downloads and explicit topic discovery. Unreviewed topic results are page-only. |
+| [Uptodown](https://www.uptodown.com/aboutus) | Developer distribution program exists, but that does not prove publisher authorization for every catalog item. [Privacy policy](https://www.uptodown.com/aboutus/privacy) explicitly describes protection against automated access. General automation permission was not established. | Broad Android catalog, limited VR focus; no supported public consumer-download API established in this survey. | Page links only; no downloader. Do not infer consent from an unchanged APK signature. |
+| [APKPure](https://apkpure.com/terms) | Third-party APK catalog; individual publisher consent and automation rights were not established. Terms request returned HTTP 403; no bypass attempted. | Broad Android coverage, incidental VR; internal endpoints are not permission to automate. | Exclude automatic indexing/downloading; user may open site. |
+| [APKMirror](https://www.apkmirror.com/faq/) | Publisher-signed files and a free-app policy are not a blanket developer-consent or automation grant. FAQ request returned HTTP 403, so current terms could not be confirmed. | General Android/version archive; APK bundles often need another installer; little VR focus. No supported consumer-download API established. | Page links only, no scraping or bundle conversion. |
+| [Aptoide](https://en.aptoide.com/company/legal) | Terms define an app supplier as developer, owner or authorized distributor; user stores still require per-item provenance. API availability alone does not settle third-party access rights. | API ecosystem and general Android catalog; weak VR focus. | Defer until a publisher-owned store and its API terms can be approved. No blanket community-store downloader. |
+| [Amazon Appstore](https://developer.amazon.com/docs/app-submission/understanding-submission.html) | Official developer submissions; store account, device and license rules apply. Publisher submission APIs do not authorize public binary extraction. | Fire-device distribution; Android-device Appstore support ended in 2025; little Quest relevance. | Official product links only; no account or entitlement extraction. |
+| [PICO / ByteDance store](https://developer.picoxr.com/document/distribute) | Official publisher channel with store/device entitlements. No public unauthenticated binary-download grant established; documentation request encountered a redirect error. | Strong standalone VR; PICO builds may depend on PICO services/extensions. | Store links only. A developer's independently published GitHub/itch build can qualify separately. |
+| [Meta Horizon Store / former App Lab](https://www.meta.com/experiences/) | Official developer submissions. A free store entitlement is still an entitlement; no license bypass or authenticated store extraction. App Lab was folded into the main store in 2024. | Strongest Quest coverage; no supported anonymous APK-download API established. | Store links only; independently distributed free builds use their publisher source. |
+| [Khronos samples](https://github.com/KhronosGroup/OpenXR-SDK-Source) | Official upstream, Apache-2.0 sample; developer-published release APKs. GitHub API terms apply. | `hello_xr` Vulkan/OpenGL ES APKs; excellent OpenXR diagnostics. | Included in GitHub curated list, Vulkan variant selected. |
+| [Meta OpenXR samples](https://github.com/meta-quest/Meta-OpenXR-SDK) | Official upstream; check each sample's license. Source availability does not imply a published APK, and some samples require Meta extensions/services. | Source/build examples, inconsistent ready-made APK releases. | Link to upstream; add specific free APKs only after release/provenance review. |
+| [Godot XR demos](https://github.com/GodotVR/godot-xr-tools) | Official project source and publisher demo pages; licenses and dependencies vary by demo. | OpenXR examples on GitHub/itch. Older Godot builds can fail on Lepton's missing clipboard service. | Covered by source discovery; no compatibility promise from an OpenXR tag. |
+
+The table distinguishes observed restrictions from unknown permission. An
+unverified policy is a reason to defer automation, not a claim that a site is
+unlawful. Only the two implemented source kinds are registered by their own
+`sources()` functions; the other rows are recommendations, not new UI entries.
+
+## Adapters
+
+`ui/apk_sources/github.py` uses `github_curated.json`: Khronos `hello_xr`,
+[Open Brush](https://github.com/icosa-foundation/open-brush), and
+[SuperTux 3D](https://github.com/SgtBilko76/SuperTux-3D). These have official
+OpenXR project/release evidence, not a blanket claim of headset compatibility.
+Open Brush's compatibility evidence is recorded in [vr-apks.md](vr-apks.md).
+Open Brush and SuperTux publish the selected builds as prereleases; curated
+opt-ins preserve that label in version records. Exact APK filename patterns
+avoid downloading desktop archives or alternate non-Quest builds.
+[OpenSaberPlus](https://github.com/arpruss/OpenSaberPlus) was examined but not
+curated: GitHub reports its license as `NOASSERTION`, and current OpenXR APK
+provenance was not established in this pass.
+
+Default GitHub search is offline against this small list. Queries
+`topic:openxr`, `topic:oculus-quest`, and `topic:quest` explicitly call repository
+search. Results outside the curated list stay page-only, even if a repository
+claims an open-source license. This prevents an arbitrary tagged mirror from
+becoming a trusted downloader. Extend the curated JSON after provenance review.
+
+Set optional `FRAME_GITHUB_TOKEN` in the process environment for a higher API
+quota. Tokens are sent only to `api.github.com`, never written to the cache,
+never sent to asset hosts, and removed on redirects. The adapter does not
+read `gh` credentials automatically. Metadata is cached for one hour under
+`frame_host.cache_dir('apk-sources', 'publisher')`. A cold details request
+fetches at most ten releases. Rate-limit errors are surfaced without retry
+loops. Asset IDs and release tags are not Android version codes: metadata
+leaves the latter unknown and rejects a requested `version_code` rather than
+silently fetching a different build.
+
+`itch.py` exposes separate OpenXR and Quest feed sources, so one feed's failure
+does not suppress the other at the aggregator level. Queries filter the current
+feed window locally: this is not an exhaustive historical itch search. Only
+explicit zero-price Android entries are returned. Covers are exposed in
+`images`; absent screenshots, APK version, ABI and minimum SDK stay unknown.
+Curated GitHub entries include publisher artwork and plain-language summaries.
+Repository image URLs are pinned to inspected commits. Open Brush screenshots
+come from its README-linked Steam listing; SuperTux uses the upstream gameplay
+preview embedded in the port's README (not a headset capture). The hello_xr
+sample has a launcher icon and GitHub social banner; no published screenshot
+was found in the inspected repository/README, so its screenshot list is empty.
+Uncurated topic results use the owner's avatar and GitHub's repository social
+preview. These are repository placeholders, not app screenshots. Itch's recorded
+RSS includes only covers, so screenshot lists remain empty without page scraping. VR is
+based on curated evidence or a VR-specific feed/topic, not a compatibility claim.
+
+Downloads stream to unique temporary files, require an APK manifest entry,
+restrict HTTPS origins and redirects, and enforce a 2 GiB ceiling. `verified`
+means the downloaded SHA-256 matches GitHub's published digest. Without such a
+digest, the computed SHA-256 is returned with `verified: False`; neither value
+claims publisher-signature validation. Installation must inspect the APK as
+usual. OBBs, split APKs, paid assets and external release-body download links
+are unsupported.
+
+## Evidence and limits
+
+On this Mac, Python 3.9 downloaded the real Khronos Vulkan 1.1.63 APK through
+the GitHub adapter, matched its published SHA-256
+`f24bbe8ba6f6339fca658628868ba8189cbc33390d6ac508f69d76fb67b5fa34`, and
+`python3 ui/frame_android.py info <apk>` exited 0: package
+`org.khronos.openxr.hello_xr.vulkan`, version code 1063, minimum API 24,
+arm64-v8a present, OpenXR detected. No Frame connection or installation occurred.
+
+The itch OpenXR RSS was fetched successfully and recorded as a fixture.
+Subsequent live adapter search encountered HTTP 429; it is not claimed as a
+successful live end-to-end search. Fixture search finds Off Nominal and parses
+nine Android entries from the ten-item feed (one has only an HTML platform).
+A real itch download and APK inspection were deliberately not performed:
+robots restrictions take precedence over that requested proof. No current
+policy text is claimed verified where the table records failed access.
+
+Tests use recorded, reduced API/RSS fixtures with network access blocked in
+the new test class. They cover selection, prereleases, unknown topic results,
+paid/non-Android exclusion, URL restrictions, redirect credential removal,
+caching, rate limits, checksum mismatch, non-APK rejection and partial-file
+cleanup. See `.claude/NOTES-more-sources.md` for commands and local evidence.

docs/apks.md

@@ -331,3 +331,11 @@ because gamescope scales Lepton's surface to fit the same panel. Also unverified
 whether the settings survive the app or its Lepton instance relaunching.
 Lepton Development rebuilds its Android data on exit, so there they probably
 don't.
+
+## Expansion files and save backups
+
+SideQuest-inspired CLI helpers install local OBB files into an already-running
+app instance and back up/restore a stopped instance's private app data. See
+[SideQuest features and limits](sidequest.md) for commands, archive scope and
+verification status. These paths have offline coverage; real Frame storage and
+permissions remain unverified. They do not change APK install or launch behavior.

docs/devices.md

@@ -0,0 +1,180 @@
+# Headsets, addresses and the connection
+
+Frame Control can manage more than one Steam Frame, and each headset can be
+reached at more than one address: a LAN IP at home, another at the office, its
+mDNS name (`frame.local`), its Tailscale IP or MagicDNS name. The **Devices**
+tab (key 5) lists them, and the connection pill in the header shows what the
+app is doing to reach the one in use, step by step, as it happens.
+
+The code is in three modules, all stdlib-only Python on your computer:
+
+| Module | What it does |
+|---|---|
+| `ui/frame_devices.py` | The registry: headsets, their addresses, networks; importing and updating `~/.ssh/config`; pinned host keys |
+| `ui/frame_network.py` | Which network this computer is on, and Tailscale's state |
+| `ui/frame_link.py` | The connector: finds the headset, keeps the SSH connection, publishes each stage; the Devices API |
+
+## Headsets
+
+Each headset keeps its own SSH alias, as Set Up Connection has always written
+it: the first is `frame`, the next `frame-2`, and so on. Terminal's
+`ssh frame-2` and the helper scripts (`FRAME_ALIAS=frame-2 scripts/push.sh …`)
+work for each one.
+
+- **Nothing to migrate by hand.** On first start, the app imports every
+  `# >>> steam-frame (ALIAS) >>>` block in `~/.ssh/config` as a headset, with
+  the block's HostName as its first address. It also copies the host key your
+  `known_hosts` already trusts for that address into the headset's own
+  known_hosts file, `~/.ssh/frame-control-hosts/<id>`, so nobody is asked to trust it again.
+- **Add a headset** runs Set Up Connection (`scripts/connect.sh` on macOS,
+  `ui/frame_connect.py --alias NAME` elsewhere) in a terminal with a new alias.
+  When it writes its block, the app picks the headset up by itself. If Set Up
+  Connection runs again and finds a headset somewhere new, that address is added
+  at the top of its list.
+- **Use this headset** (or the switcher in the header, or the app's
+  **Frame → Headset** menu) moves the whole app to another headset; every panel
+  reloads from it. From that moment no command goes to the previous headset, even
+  if the new one never answers. It waits while an install is running, since an
+  install reads the SSH settings step by step.
+- **Remove** forgets a headset. Its `~/.ssh/config` block stays unless you tick
+  the box; either way it isn't imported again unless Set Up Connection changes it.
+- A plain `FRAME_ALIAS` that Set Up Connection never configured still works: the
+  app shows it as not set up and lets ssh's own config decide where it goes.
+
+## Addresses
+
+Each address has a kind (LAN, mDNS, Tailscale or Other, guessed from the address
+and changeable), an optional label, the networks it has worked on, and when it
+last worked with its round-trip time.
+
+When connecting, the app **tries all addresses at once** (TCP to the SSH port)
+and ranks them:
+
+1. addresses that worked on the network this computer is on now;
+2. mDNS names;
+3. Tailscale addresses, if Tailscale is running here;
+4. addresses not tried on this network yet;
+5. addresses that only ever worked on other networks;
+6. Tailscale addresses while Tailscale is off.
+
+Your order on the Devices tab breaks ties. The best-ranked address that answers
+wins; one that answers first waits up to 0.35 s for a better-ranked one that is
+still trying. If SSH to the winner fails in a way another address could fix
+(a different device answered there, or the link dropped), the next one that
+answered is tried. Every success records the network on that address, so next
+time on that network it's tried first.
+
+**Test now** probes every address and tries SSH on each one that answers, without
+disturbing the connection in use: "SSH works", "answered as a different
+headset", "refused this computer's key", or why it didn't answer. **Find on
+Tailscale** lists your tailnet's devices (likely headsets first, from `tailscale
+status --json`, including the Mac app's own CLI) with buttons to add their
+MagicDNS name or IP. **Find on this network** asks mDNS for SteamOS devkit
+services and checks `ALIAS.local` and `frame.local`.
+
+## Networks
+
+A network is told apart by its default gateway: the router's IP address plus its
+hardware (MAC) address, read with `route`/`arp` (macOS), `ip route`/`ip neigh`
+(Linux) or `route print`/`arp -a` (Windows). That works on wired networks, and
+on macOS 14 and later, which hides the Wi-Fi name from apps without Location
+permission. Where the system does share the Wi-Fi name, it's shown, and you can
+name any network yourself ("Home Wi-Fi") on the Devices tab.
+
+The app rereads the gateway every 5 seconds and Tailscale's state every
+30 seconds. Changing networks reconnects.
+
+## The connection, stage by stage
+
+The connector runs in the server (`frame_link.Link`) and moves through:
+
+1. **Checking this computer's network**: gateway, Wi-Fi, this computer's IP, Tailscale.
+2. **Finding the headset**: each address resolving, trying, answered in N ms,
+   no answer, refused, or can't be found.
+3. **Opening SSH** to the address that answered.
+4. **Checking the headset's identity**: the host key must match the one pinned
+   for this headset.
+5. **Logging in** as the headset's user.
+6. **Connected** via network N, address A, round trip T; or **failed** at a stage
+   with the reason in plain words and a countdown to the next try (5, 10, 20,
+   then every 30 seconds). Retry now skips the wait.
+
+Stages 3 to 5 come from following `ssh -v` as it runs. On macOS and Linux the
+connection is an SSH ControlMaster that every command shares; when it dies (the
+headset slept or left the network) the connector notices and starts again. On
+Windows, where OpenSSH can't share a connection, the same handshake runs once
+and each command then connects on its own; a command that can't reach the
+headset makes the connector start again.
+
+Once connected, every `ssh`, `scp` and `rsync` the app runs gets
+`-o HostName=<address> -o HostKeyAlias=frame-control-<id>
+-o UserKnownHostsFile=~/.ssh/frame-control-hosts/<id> -o HashKnownHosts=no -o User=… -o Port=…`. The
+alias's block in `~/.ssh/config` is also updated to the last address that
+worked (and to the user and port you set), so Terminal's `ssh frame` and the
+scripts follow. Edits to `~/.ssh/config` take a lock file
+(`~/.ssh/config.frame-control.lock`) that Set Up Connection takes too, and never
+write over a change someone else made since the app last read the file.
+
+**Host keys are pinned per headset, not per address.** Your own `known_hosts`
+is keyed by address, so a different device answering at a remembered IP (a DHCP
+lease that moved) would look like a new host there. The app keeps one known_hosts
+file per headset instead, so saving or forgetting one headset's key never touches
+another's: a different device answering at one of its
+addresses is refused, and the pill says so. A headset's first connection trusts
+the key it shows, as Set Up Connection does. After reinstalling SteamOS the
+headset has a new key; **Forget identity** on the Devices tab lets the next
+connection save the new one.
+
+## One server at a time
+
+Only one Frame Control server runs per user (a lock file, `server.lock`, in the app's
+data folder). Two would each connect, reconnect and edit the headsets on their own, and
+one could move the other's install to a different headset. A second one, say
+`scripts/frame-ui.sh` while the app is open, exits with "Frame Control is already
+running". `FRAME_CONTROL_DATA_DIR` gives a separate one, with its own headsets.
+
+## API
+
+All under the usual `/api/` guards (loopback `Host`, `X-Frame-UI` header).
+
+| Request | Returns |
+|---|---|
+| `GET /api/connection` | The connection state: `phase` (connecting, connected, failed), `device`, `network`, `stages`, `probes`, `via`, `error`, `retry_at`, `tests`, `version` |
+| `GET /api/connection/events` | The same as server-sent events, one each time it changes (the page reads it with `fetch`, since `EventSource` can't send the header) |
+| `GET /api/devices` | Headsets, the current network, known networks, the next free alias |
+| `GET /api/devices/tailscale?id=` | Tailscale peers, likely headsets first |
+| `GET /api/devices/mdns?id=` | Headsets found on this network |
+| `POST /api/devices` | `{"action": ...}`: `use`, `update` (name, user, port), `remove`, `address-add`, `address-update`, `address-remove`, `address-move`, `test`, `forget-identity`, `name-network`, `setup` (alias, optional host), `retry` |
+
+Every host, alias and user is checked against strict patterns before it's
+stored, because they end up in ssh arguments and `~/.ssh/config`; nothing goes
+through a shell.
+
+## The registry file
+
+`devices.json` in the app's data folder (`~/Library/Application Support/Frame
+Control` on macOS, `%APPDATA%\Frame Control` on Windows,
+`~/.local/share/frame-control` on Linux). It's plain JSON so the iPhone app can
+share the format later (it still connects to one host; see
+[iphone.md](iphone.md)):
+
+```json
+{"version": 1, "active": "f67f8b7e",
+ "devices": [{"id": "f67f8b7e", "name": "Steam Frame", "alias": "frame", "user": "steamos", "port": 22,
+              "identity_files": ["~/.ssh/id_ed25519_frame"],
+              "addresses": [{"host": "frame.local", "kind": "mdns", "label": "",
+                             "networks": ["n-e0998baa61"], "last_ok": 1790593550.4, "last_rtt_ms": 0.9}]}],
+ "networks": {"n-e0998baa61": {"name": "Home Wi-Fi", "ssid": null, "gateway": "192.168.1.1",
+                               "gateway_mac": "b4:fb:e4:b5:67:55", "wifi": true, "last_seen": 1790593550.0}}}
+```
+
+A network id is `n-` and the first 10 hex digits of SHA-1 of `gateway|mac`.
+
+## Tests
+
+`tests/test_devices.py`, `tests/test_network.py` and `tests/test_link.py` run
+with the other unit tests. They use a stand-in `ssh` (`tests/fakessh/ssh`) that
+prints what `ssh -v` prints and plays a ControlMaster, real sockets on this
+computer for the addresses, and temporary folders for `~/.ssh`
+(`FRAME_CONTROL_SSH_DIR`) and the app data (`FRAME_CONTROL_DATA_DIR`), so they
+never touch yours.

docs/evidence/linux-vr/2026-09-29.txt

@@ -0,0 +1,29 @@
+Locked real-Frame repeat, 2026-09-29
+SteamOS 0.4.1, BUILD_ID 20260925.6191901; aarch64.
+mkdir /tmp/frame-test.lock succeeded before installs/launches; rmdir issued after cleanup.
+Preflight battery 44%, charging; before WiVRn 46%, before ALVR 47%, cleanup 47%.
+Original Steam PID 49823 and vrserver PID 49571 present after cleanup.
+Same unmodified upstream release APKs and SHA-256s as 2026-09-28.txt.
+Installer functions loaded from a613735 before checkout was fast-forwarded to current main.
+No compatibility layer injected. Per-app immersive Lepton instances, Steam shortcut launches.
+Headset unworn. No Linux gaming host. No pairing or streaming session reached.
+
+WIVRN: selected journal lines (local +1000 prefix, Android timestamps UTC).
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.202  1153  1181 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.210  1153  1181 I WiVRn   : [2026-09-29 01:03:15.210] [WiVRn] [info] Failed to create OpenXR instance version 1.1.58: XR_ERROR_EXTENSION_NOT_PRESENT
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.248  1153  1181 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.256  1153  1181 I WiVRn   : [2026-09-29 01:03:15.256] [WiVRn] [info] Failed to create OpenXR instance version 1.0.58: XR_ERROR_EXTENSION_NOT_PRESENT
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.257  1153  1181 E WiVRn   : [2026-09-29 01:03:15.257] [WiVRn] [error] Error during initialization: Failed to create OpenXR instance: XR_ERROR_EXTENSION_NOT_PRESENT
+Screenshot API exit 0; 1920x1080 uniformly dark image; no client scene visible.
+
+ALVR: selected journal lines (local +1000 prefix, Android timestamps UTC).
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.553  1139  1167 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.553  1139  1165 I RustStdoutStderr: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.611  1139  1167 E [ALVR NATIVE-RUST]: panicked at alvr/client_openxr/src/lib.rs:220:10:
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.611  1139  1167 E [ALVR NATIVE-RUST]: called `Result::unwrap()` on an `Err` value: ERROR_EXTENSION_NOT_PRESENT
+Screenshot API exit 0; 1920x1080 uniformly dark image; no client scene visible.
+
+Cleanup: both test app directories, compatdata, shadercache, containers and shortcuts absent.
+Capture output directory removed. No global settings changed; Steam/SteamVR not stopped.
+The shared lock was subsequently acquired by another thread (new directory timestamp 11:03:49 +1000).
+Native clients and Valve host streaming not exercised: no native build or Linux gaming host available.

docs/evidence/vr-utilities/device.json

@@ -0,0 +1,53 @@
+{
+  "date": "2026-09-28",
+  "os": {
+    "version": "0.4.1",
+    "build": "20260925.6191901",
+    "variant": "vr"
+  },
+  "performance": {
+    "compositorFps": 72.0,
+    "frameMs": 13.89,
+    "appFps": null,
+    "gpuMs": 3.07,
+    "compositorCpuMs": 0.61,
+    "cpuPercent": 40.6,
+    "gpuMHz": 903.0
+  },
+  "batteryPercent": 16,
+  "maxTempC": 73.5,
+  "ownership": [
+    {
+      "id": 1009850,
+      "owned": false,
+      "installed": false,
+      "frame": 0
+    },
+    {
+      "id": 1173510,
+      "owned": false,
+      "installed": false,
+      "frame": 0
+    },
+    {
+      "id": 1068820,
+      "owned": false,
+      "installed": false,
+      "frame": 0
+    },
+    {
+      "id": 908520,
+      "owned": false,
+      "installed": false,
+      "frame": 0
+    },
+    {
+      "id": 1494460,
+      "owned": false,
+      "installed": false,
+      "frame": 0
+    }
+  ],
+  "hudLifecycle": "open, duplicate-open, close passed before control-test pause; overlay probe removal verified",
+  "comfort": "Initial 1cm seated probe restored exactly. Later commits/readback disagreed while Frame in use; Alex paused control tests. No controls shipped."
+}

docs/evidence/vr-utilities/review.md

@@ -0,0 +1,58 @@
+# Independent review attempts — 2026-09-28
+
+Target: the implementation and evidence in
+[3fb541d](https://github.com/saphid/frame-control/commit/3fb541d) and
+[6a63a5a](https://github.com/saphid/frame-control/commit/6a63a5a), supplied as a
+frozen diff before those commits were made. No executable code changed after
+the final review snapshot.
+
+Requested model: **SWE-2 Max**, explicitly selected with `--model swe-2-max`.
+No completed verdict or model self-identification was returned. This is not a
+passed review, and there is no "no actionable findings" claim.
+
+## First attempt
+
+Launcher:
+
+```sh
+devin -p --model swe-2-max --permission-mode auto --respect-workspace-trust false --prompt-file /tmp/frame-vr-review-prompt.txt
+```
+
+The prompt required read-only review, no delegation, no edits and no Frame
+access. The reviewer inspected surrounding code, then stopped while checking
+the public OpenVR header. The tool runner reported:
+
+> warning: rejected a tool call that requires confirmation. Running in non-interactive mode.
+
+The real launcher exit status was **0**, but no verdict was returned. A zero
+process status here is not evidence that the review completed.
+
+## Tool-free retry
+
+Launcher:
+
+```sh
+devin -p --model swe-2-max --permission-mode auto --respect-workspace-trust false --prompt-file /tmp/frame-vr-review-final-prompt.txt
+```
+
+The self-contained prompt supplied the complete frozen changes, surrounding
+code, standards and locally fetched authoritative OpenVR header excerpts. It
+explicitly prohibited tools, edits, delegation and device access. This avoided
+the first attempt's permission boundary without escalating permissions.
+
+No output or verdict arrived within the fifteen-minute review window. The
+process was sent SIGTERM at 918 seconds; the shell recorded real exit status
+**143**. Findings are unavailable. Review must be completed before considering
+this partial draft ready; playspace feasibility is also still paused.
+
+## Other validation
+
+- 166 Python unit tests passed locally.
+- 8 website tests and UI JavaScript syntax passed locally.
+- Desktop and phone-width attached-preview checks passed using live telemetry;
+  paid optional install buttons were disabled, and unavailable metrics cleared.
+- [Fake-Frame CI](https://github.com/saphid/frame-control/actions/runs/36423548487/job/108931878908)
+  passed, as did Windows/Linux server tests and the main checks job. Docker was
+  unavailable locally. macOS/iOS jobs were still queued at this handoff.
+- Real-device evidence and the paused-control limitation are in
+  [VR utilities](../../vr-utilities.md).

docs/family-comfort.md

@@ -0,0 +1,122 @@
+# Family and comfort
+
+Frame Control's Home tab has a **Family and comfort** card, on desktop and
+on iPhone. No third-party notification or parental-control app is needed.
+This is Frame Control code using Python, Steam and SteamVR already on the Frame.
+
+![Family and comfort controls in the desktop app](img/comfort-desktop.png)
+
+## Sessions
+
+Set a limit of 1–240 minutes, optional break and check-in intervals, then
+**Start session**. Break and check-in intervals of 0 turn those reminders off.
+**Cancel session** cancels the timer and monitoring without changing the game.
+Cancel before starting a session with different settings.
+
+The Frame shows a one-minute warning, then opens Steam Home in its dashboard.
+**Games stay running**: save and pause before the limit. Some games pause when
+the dashboard opens; others do not. There is no kill, power-off, Steam restart,
+account restriction or parental lock. The wearer can return to the game.
+
+**Documented implementation:** the timer is a single, opt-in Python worker in
+the Frame user's account. Desktop and iPhone share its state. It keeps going
+when the companion disconnects, closes or is suspended. It exits after
+completion or cancellation (normally within five seconds). Cancellation waits
+for any in-flight SteamVR action to finish within its timeout; it is not a boot
+service. A Frame reboot invalidates the session. Suspend counts toward the
+limit, using Linux's boot-time clock. If a warning was delayed by suspend or a
+SteamVR failure, Home waits until at least a full minute after a successful
+warning. A failed Home transition remains active and retries, with an error
+shown in the companion. A stale worker is reported as unverified enforcement.
+
+## Alerts and breaks
+
+During a session, battery, overheating and check-in alerts go to connected
+companions. Break reminders and session warnings also appear on the headset.
+
+- **Low battery:** 15% or below while discharging. One alert until charging or
+  recovery to 20%, so values around 15% do not produce repeated notifications.
+- **Overheating:** a thermal zone reaches its own kernel-reported hot/critical
+  trip, or the battery reports `Overheat`. Missing sensors mean unknown, not
+  safe. These are status alerts, not medical advice or an extra thermal governor.
+- **Check in:** an alert after the chosen number of active minutes.
+- **Breaks:** a SteamVR reminder and companion notification at the chosen interval.
+
+**Inferred:** SteamVR activity levels 1 and 2 are a useful proxy for use, not
+proof someone is wearing the headset. Inactive readings reset continuous use;
+missing readings add no time. Long gaps count at most 30 seconds. Breaks and
+check-ins are distinct from the elapsed-time session limit.
+
+Click **Enable / test notifications** on each companion. iOS asks for permission;
+macOS, Windows and Linux follow their notification settings. The page also shows
+recent events and errors. Keep Frame Control open and connected for companion
+alerts. **Phone alerts are local, not push notifications:** iOS suspension,
+force-quit or a lost SSH connection prevents live delivery. Old alerts are not
+replayed as a notification burst on reconnect. Headset warnings and the session
+limit continue without the phone. A physical iPhone's background delivery has
+not been verified and is not guaranteed.
+
+## Casting
+
+**Cast headset view** starts the existing headset Live view and requests full
+screen where supported. Show that screen to people in the room, or use the
+computer/phone's own screen mirroring. It creates no new stream transport,
+public URL or LAN server. iPhone uses the inline viewer if full screen is not
+available. The image includes private content visible to the wearer.
+
+## What is installed
+
+The shared authenticated `/api/comfort` endpoint copies three bundled Python
+files to `~/.cache/frame-control/comfort/<content-hash>/`. Session state and
+locks live in `~/.local/state/frame-control/comfort/`, with a private directory
+and 0600 state file. There is no network listener or system service. Cancel a
+session before removing these directories. The iPhone's normal server still
+exits on disconnect; the explicitly started comfort worker is the exception.
+
+## Verification
+
+**Verified 2026-09-28**, SteamOS 0.4.1, build `20260925.6191901`: shipped
+`/opt/steamvr/bin/linuxarm64/vrcmd --notify TEXT` reported success for a custom
+reminder. Steam's CDP `SteamUIStore.Navigate('/library/home')` and
+`SteamClient.OpenVR.VROverlay.ShowDashboard('valve.steam.gamepadui.main')`
+opened Home while the running app ID stayed unchanged. Prior page and dashboard
+visibility were restored. Kernel hot/critical trips and SteamVR activity were
+read from the real device. No temperature or battery fault was induced.
+
+**Verified locally:** deterministic fake-Frame tests cover late warnings,
+failed warnings/Home actions, cancellation, activity gaps, thresholds, duplicate
+suppression, reboot invalidation, shared session state and the exact Home
+JavaScript. `python3 -m unittest discover -s tests` runs them. The iOS Simulator
+build tests notification content and bounds. Physical iPhone delivery and
+wearer-perceived headset notification visibility remain unverified.
+
+**Verified end to end on the same Frame:** a two-minute session with no companion
+connection for 135 seconds emitted its warning, break and check-in, then opened
+Home. The running app ID was unchanged; the test restored the previous page and
+dashboard visibility and confirmed the worker exited. Casting through the Home
+shortcut decoded the existing headset stream at 30 fps.
+
+**Verified on the iOS 26.5 Simulator:** connected to the real Frame, approved the
+notification prompt, and saw the native Frame Control test banner. Seven iOS
+tests passed.
+
+![Native test notification in the iOS Simulator](img/comfort-notification-ios.png)
+
+Desktop and 390-pixel phone layouts had no horizontal overflow.
+On macOS the development Electron app's real notification attempt was denied
+(`UNErrorDomain` 1); the bridge now returns that failure instead of reporting
+success. Successful macOS/Windows/Linux notification display remains unverified.
+
+**Verified on the real Frame:** its naturally discharging 15% battery produced
+one low-battery event during a short session; the test then cancelled the
+session. Overheating alerts use fake sensor samples in tests: the shared
+headset was not deliberately overheated.
+
+**Verified 2026-09-29 on the same Frame:** a fresh one-minute session opened
+Home more than 60 seconds after the successful warning. The test restored the
+previous page and dashboard visibility. Local regression coverage now includes
+slow notification delivery, a total Home-action timeout, failed worker startup,
+unreadable saved state, malformed activity samples and notification UX: 173
+Python tests passed. Desktop and 390-pixel layouts were checked again; system
+notification-denial guidance stayed visible across polls. Initial event history
+did not replay notifications, and only the latest new event was announced.

docs/frame-control.md

@@ -17,13 +17,16 @@ python3 ui/server.py         # anywhere: then open http://127.0.0.1:47810
 
 ## Features
 
-The window has four tabs: **Home** (headset view, status, screenshots),
+The window has five tabs: **Home** (headset view, status, screenshots),
 **Games** (installed games, sideloaded titles, getting games), **Android** (apps,
-the catalogue, display settings, reports) and **Tools** (sending files and text,
-Flatpaks, remote and power). Keys 1–4 switch between them. Files can be dropped
-anywhere in the window. When the Frame can't be reached, one banner says why in
-plain words and the app retries every few seconds, filling everything in once it
-answers. Flatpak and Android installs run in the background; the bottom bar
+the catalogue, display settings, reports), **Tools** (sending files and text,
+Flatpaks, remote and power) and **Devices** (your headsets and their addresses).
+Keys 1–5 switch between them. Files can be dropped anywhere in the window. A
+connection pill in the header always shows which headset, which network this
+computer is on, the address in use or being tried, and each step of connecting
+as it happens; click it for the whole timeline. When the Frame can't be
+reached, a banner says why in plain words, what was tried, and counts down to
+the next try, filling everything in once it answers. Flatpak and Android installs run in the background; the bottom bar
 counts them while they run.
 
 - **Headset view**: what the lenses show, as SteamVR composites it (the room,
@@ -78,6 +81,11 @@ counts them while they run.
   an SSH tunnel; see [mac-in-headset.md](mac-in-headset.md).
 - **Flatpaks**: install and remove them (quick picks: Moonlight, Firefox, VLC,
   Remmina).
+- **Devices**: several headsets, each with several addresses (LAN IPs per
+  network, its `.local` mDNS name, its Tailscale IP or MagicDNS name). The app
+  tries them all at once and learns which worked on which network. Add, edit,
+  reorder and test addresses, find a headset on Tailscale or on this network,
+  name your networks, and switch headsets. See [devices.md](devices.md).
 - **One-click tools**: SSH or SFTP in a terminal window, Steam Link, and remote
   desktop (Windows App on macOS, Remote Desktop on Windows, Remmina or FreeRDP on
   Linux). Sleep, restart and shut down open a terminal window because SteamOS
@@ -101,7 +109,9 @@ Frame for the keyboard and trackpad.
 The server is Python stdlib only and listens on 127.0.0.1. It rejects requests
 with a non-local `Host` header, and any `/api/` request without a custom
 header, so other websites can't drive it or read captures. Everything reaches
-the headset through the `frame` SSH alias. On macOS and Linux it keeps one
+the headset through its SSH alias (`frame` for the first one), pointed at the
+address that answered with `-o HostName=` (`ui/frame_link.py`, described in
+[devices.md](devices.md)). On macOS and Linux it keeps one
 multiplexed SSH connection open, so status and each capture take about 0.3 s.
 Windows' OpenSSH can't share a connection, so there each request connects on
 its own and the app is a little slower. What differs between the three

docs/how-the-frame-works.md

@@ -40,6 +40,8 @@ Lepton (Android 11, podman container "lepton-dev") ← its own panel, app 305600
 | Present: `rsync`, `flatpak`, `python3`, `git`, `qdbus6`, `xrdp`, `xprop`, `xwininfo`, `xterm`, `konsole`, `dolphin`, `gamescopectl`. Missing: `wl-copy`, `xclip`, `xsel`, `kdeconnect-cli`, `tailscale` (installable in `~`, see below), `krfb`, `wayvnc`. | Script design |
 | **SteamOS updates arrive on their own.** The Frame went from 0.3.0 (build 20260922.6101926) to **0.4.1, build 20260925.6191901**, between 2026-09-27 and 2026-09-28 with no action from us; `~` (keys, user Flatpaks, `~/.local/share`) survived. **Verified 2026-09-28.** | Keep changes in `~` |
 | **Valve's package repository has more than the image.** `pacman -Si` / `pacman -Sp` work as `steamos` without root and list Valve's own builds, such as `kdeconnect` 24.02.2 and `python-evdev` 1.7.0 in `extra`. Unpacking those packages into `~` runs them without touching the read-only root. The repository URLs say not to share them, so never write them down; Valve also publishes each build's source package there (`sources/packages/`), which is how Frame Control got the complete source for the KDE Connect it ships. **Verified 2026-09-28**, SteamOS 0.4.1. | [streaming.md](streaming.md#input-type-and-point-in-the-frame-from-the-mac-or-iphone) |
+| **gamescope has its own input injection.** An EIS socket at `/run/user/1000/gamescope-0-ei` (libei 1.4.1 is on the image) offers "Gamescope Virtual Input": relative and absolute pointer, buttons, scroll, keyboard. It drives the panel that has focus in the headset, on either X display. Focus moves only with the controller's laser (or to a new panel when none has it); `gamescopectl focus_info` prints the focus state to the journal. **Verified 2026-09-29.** | [streaming.md](streaming.md#live-view-and-control-watch-a-panel-and-tap-on-it) |
+| **A panel's own pixels:** `ffmpeg -f x11grab -window_id <window> -i :<display>` captures one window (x11grab of the root is black under gamescope). Panels live on `:0` (Steam's UI, windows tagged by `panel-on-frame.sh`) or `:1` (apps Steam starts). **Verified 2026-09-29.** | Frame Control's Desktop view |
 | **gamescope runs two Xwayland displays.** `:0` holds Steam's VR bar and menus (`valve.steam.gamepadui.*`) and ignores XTest pointer motion; `:1` holds apps such as Chromium and takes it. There's also a libei socket, `/run/user/1000/gamescope-0-ei`. **Verified 2026-09-28**, SteamOS 0.4.1. | Keyboard and trackpad |
 | Flathub is a **system** remote. `--user` installs over SSH work and show up in the desktop menu. | `install-apps.sh` |
 | `/` is 10 GB and read-only. `/home` is 929 GB. | Where to put things |

docs/iphone.md

@@ -26,7 +26,10 @@ as its transport too), so the desktop and phone share one code path. Android
 display settings use `podman exec` into each Lepton container instead of adb,
 which the Frame doesn't have.
 
-Nothing is left running on the Frame after the phone disconnects; the copied
+The app server stops after the phone disconnects. An explicitly started
+[comfort session](family-comfort.md) keeps its timer and headset reminders running
+until the session ends or is cancelled; phone notifications require the app to
+remain connected and running. The copied
 files stay in `~/.cache/frame-control` (delete it any time).
 
 ## Pairing
@@ -108,3 +111,11 @@ running), a real sleep/restart/shut down on the Frame, and a physical iPhone.
 Debug builds have Simulator test hooks (`FRAME_TEST_HOST`, `FRAME_TEST_PAGE`,
 `FRAME_TEST_JS`, and the tunnel URL in the app's Caches folder); release builds
 don't.
+
+## Family and comfort
+
+The shared Home card sets session limits, breaks and check-ins, and offers
+**Cast headset view**. **Enable / test notifications** requests iOS notification
+permission and sends a local test. These are local notifications, not APNs push;
+iOS background suspension can interrupt phone alerts. The headset timer still
+runs. See [the behavior and verification limits](family-comfort.md).

docs/linux-vr-streaming.md

@@ -38,6 +38,33 @@ after its container exited. No headset was worn and no host was connected.
 All test app files, compatdata, shortcuts and containers were removed afterwards.
 SteamVR's original process remained running. No global settings changed.
 
+### Locked repeat, 2026-09-29 (verified)
+
+Acquired `/tmp/frame-test.lock` before installing or launching anything and
+released it after cleanup. Battery was 44% and charging at preflight, 46–47%
+during the launches, and 47% at cleanup. The SteamOS version/build was unchanged.
+
+Reinstalled and launched both original APKs in immersive Lepton instances.
+WiVRn again failed at OpenXR 1.1 and 1.0 with the missing timespec extension;
+ALVR again panicked on `ERROR_EXTENSION_NOT_PRESENT`. This repeats the
+unmodified-client test, not the newer installer's automatic compatibility-layer
+path. Neither reached a session that could be paired or exercised further.
+Fresh [journal excerpts and cleanup evidence](evidence/linux-vr/2026-09-29.txt)
+record the failures.
+
+SteamVR's screenshot API returned a 1920×1080 headset capture after each
+launch. Both are uniformly dark: [WiVRn](evidence/linux-vr/2026-09-29-wivrn.png)
+and [ALVR](evidence/linux-vr/2026-09-29-alvr.png). These images do **not** prove
+rendering or a working client. The headset was unworn; visibility, controllers,
+frame rate and motion-to-photon latency could not be judged. The explicit
+OpenXR errors, rather than the dark captures, establish the client blocker.
+
+Both test installs, app data, shader caches, shortcuts, containers and temporary
+capture files were removed. The original Steam and SteamVR process IDs were
+unchanged. No reboot, power action or global setting change was used. Native
+clients remain untested, and no Linux gaming host was available for Valve's
+streaming path. The recommendation below is unchanged.
+
 ### Relation to the VR APK branch
 
 **Documented from source:** [PR #20](https://github.com/saphid/frame-control/pull/20)

docs/mac-in-headset.md

@@ -468,3 +468,18 @@ versus on, medians of the runs, ms):
   window to the front first.
 - Ctrl stays Ctrl. On the Mac, copy is ⌘C, so use Meta+C on a keyboard paired
   with the Frame.
+
+## Switching panels and workspace limits
+
+**Tools → Panel switcher** lists open SteamVR panels, including Mac viewers.
+Use **Show** to request focus or **Open in headset** for Frame Control's own
+switcher panel. It uses SteamVR/gamescope and Chromium, with no third-party
+overlay app. [Device checks and limits](panels.md#frame-controls-panel-switcher)
+include the difference between a panel surviving a scene launch and staying
+visible over it.
+
+Saved spatial layouts are blocked on this build: the public OpenVR transform
+setter denies access to gamescope-owned panels. Reconnecting an existing viewer
+is supported; restoring its room position after a reboot is not. We do not
+save short-lived Mac window IDs or viewer access keys as if they were a durable
+workspace. See [the feasibility evidence](panels.md#saved-spatial-layouts-blocked-on-the-current-panel-route).

docs/panels.md

@@ -121,8 +121,165 @@ a limit on the number of floating panels.
   script needed.
 - **Inside the desktop panel**: KWin tiling (Meta+arrow keys with a Bluetooth
   keyboard) or virtual desktops arrange windows within the 1280×800 rectangle.
-- **Windows-only overlay tools** (Desktop+, OVR Toolkit, OVRdrop) do this for a
-  PC's desktop in SteamVR. They don't run on the Frame's standalone Linux.
+- **Optional overlay tools:** Desktop+, OVR Toolkit and similar software are
+  separate from Frame Control. Public reports describe some Proton support;
+  Windows-only does not by itself prove a Frame app cannot run. Local status
+  and sources are in [VR utilities](vr-utilities.md).
+- **Our performance HUD:** Home → VR comfort and performance → Open HUD in
+  headset creates its own gamescope panel using built-in tools. It needs no
+  third-party overlay app. [Metrics and verification](vr-utilities.md).
+
+## Frame Control's panel switcher
+
+**Verified 2026-09-28**, SteamOS 0.4.1, BUILD_ID `20260925.6191901`,
+SteamVR 2.18.1: **Tools → Panel switcher** lists SteamVR's open main panels,
+including panels that are currently hidden. **Show** asks SteamVR to bring one
+forward. **Open in headset** opens the same switcher as its own panel; choose
+it again from Steam's dashboard after switching away. Refresh updates the list.
+This is a list, not thumbnail Exposé.
+
+![Frame Control's switcher rendered on the Frame](img/panel-switcher.png)
+
+This is our own Python/HTML implementation (`ui/frame_panels.py`), using the
+Frame's shipped `vrcmd` OpenVR client and gamescope. The headset page uses
+Chromium (Chromium XR when present, then system Chromium, then the existing
+Chromium Flatpak). No XSOverlay, OVR Toolkit, WayVR or other overlay application
+is needed. This dependency boundary also applies to future layout and panel
+persistence work: platform APIs and bundled libraries are fine; another app
+must not implement the feature for us.
+
+The companion runs the helper over SSH. Opening it in the headset installs a
+copy under `~/.local/share/frame-control/panels/` and starts a loopback HTTP
+server and an isolated Chromium profile. There is no startup service or global
+setting change. Close the switcher to stop its server and browser. Other
+Chromium profiles, Steam and SteamVR are left alone. If the window or runtime
+closes, use **Open in headset** again.
+
+The page carries a random, per-process access key in its URL fragment, removes
+it from the address bar, keeps it in tab session storage for page reloads, and
+sends it in a header. Panel lists and actions need
+that key; Host and Origin checks reject other sites. The key permits only
+listing panels, requesting focus and closing this switcher. Like Mac viewer
+launch tickets, it is initially readable by another process running as the
+same Frame user. Panel titles are rendered as text, never HTML. The companion
+retains its existing request guards. No Mac capture credentials cross this API.
+
+**Verified:** the real headset page rendered its panel list (image above), its
+HTTP focus request changed `GAMESCOPE_FOCUSED_APP` to `2000999030`, a request
+without the key returned HTTP 403, and Close stopped the helper and its browser.
+Opening an already running switcher requests its focus rather than creating a
+second one. The companion uses the same list/focus helper. **Unverified:** laser
+selection while wearing the headset, physical placement, and non-XR Chromium.
+The API reports that focus was *requested*: another action can take focus before
+we observe the result. Closed panels are rejected after re-enumeration.
+
+### Shared-device recheck, 2026-09-29
+
+**Verified:** the follow-up's atomic `mkdir /tmp/frame-test.lock` attempts
+failed because another thread held the lock. The existing lock was left alone;
+no applications were installed, launched or stopped in this follow-up. The last
+read-only battery check showed 62%, charging. The 180 Python and 8 website tests
+passed again locally.
+
+**Unverified in this follow-up:** the prepared browser-button test (Refresh,
+selection, reload and Close) and repeated OpenXR transition could not run under
+the shared lock. The device results elsewhere in this page are the earlier
+2026-09-28 observations, not results from this blocked recheck. In particular,
+HTTP focus is not evidence of worn-headset laser input. Follow the
+[shared-device test procedure](testing.md#headset-smoke-test) for the next run.
+
+## Saved spatial layouts: blocked on the current panel route
+
+**Verified 2026-09-28**, same build, using a temporary xterm panel with
+`STEAM_GAME=2000999031` and `FnTable:IVROverlay_028` from
+`/opt/steamvr/bin/linuxarm64/libopenvr_api.so`:
+
+| OpenVR call | Result |
+|---|---|
+| `FindOverlay("valve.steam.desktopgame.2000999031")` | Success |
+| `GetOverlayWidthInMeters` | Success, 2.67 m |
+| `SetOverlayWidthInMeters` (same width) | Success |
+| `GetOverlayTransformType` | Success, type 5 (`VROverlayTransform_DashboardTab`) |
+| `GetOverlayTransformAbsolute` | 18 (`WrongTransformType`) |
+| `SetOverlayTransformAbsolute` (identity rotation, 1.2 m up, 1.5 m forward) | 12 (`PermissionDenied`); type remained 5 |
+
+The public interface names type 5 **DashboardTab**; SteamVR's dashboard code
+places these panels through its scene graph. It owns the frame/docking
+transforms. A successful width setter does not grant permission to restore the
+position. `vrcmd --dock-overlay world <key>` dispatched a docking request but
+the dashboard logged `Failed to get SGTransform in setInitialTransformForLocation.
+Invalid transform ID`. This does not establish working world placement.
+
+**Inferred:** saving X11 pixel rectangles or Mac window IDs would not restore
+this spatial arrangement. Mac window IDs also change when an application
+reopens; viewer tickets and reconnect keys must not go into a layout file.
+The base Mac stream reconnects after a network break, but that is different
+from recreating windows and their room positions after a reboot.
+
+There is consequently no Save/Restore control yet. A durable layout needs a
+working transform restore path, stable source identity, and a fresh capture
+permission/ticket flow. The tested gamescope-owned overlay route denies that
+transform operation. A future Frame Control-owned overlay renderer, or a
+supported platform API for dashboard frame transforms, needs its own device
+proof before building layout UI. This is a blocker for the current approach,
+not a claim that all possible implementations are impossible. Reboot recovery
+was not tested: the shared headset was not rebooted.
+
+## Panels during an immersive session
+
+**Verified 2026-09-28**, same build: our Chromium switcher panel remained in
+OpenVR's overlay list before, during and after the Frame's shipped `helloxr -g
+Vulkan` sample. During the test `vrcmd --stats` identified
+`system.generated.openxr.helloxr.helloxr`, with 242 frame submissions. The test
+ended only its own sample process; no SteamVR, Steam, power or global settings
+were changed. The switcher was still selectable afterwards.
+
+This proves survival of that panel across an OpenXR scene session, **not** that
+it stayed visibly composited over the scene: OpenVR reported it `not_visible`
+before, during and after. **Verified:** calling `ShowOverlay` on our
+*gamescope-owned* switcher overlay returns 12 (`PermissionDenied`). A helper
+cannot force that panel visible using the public overlay call. Use the
+switcher/dashboard to request access to it; we do not fight the runtime with a
+repeated force-focus loop.
+
+**Verified in a second controlled run:** a live H.264 test-pattern stream from
+this checkout's Mac helper, through its own SSH tunnel and a temporary Chromium
+profile, survived the same OpenXR sample (257 scene-frame submissions). Its
+panel `2000999032` changed from `visible` before launch to `not_visible` during
+and after the scene. The Mac helper still reported the same `test` stream;
+captured frames increased from 35 to 232, with 29.5 decoded/drawn fps afterwards.
+The test did not capture personal Mac windows or inject Mac input. The sample,
+viewer, temporary profile, tunnel and Mac helper were cleaned up. This proves
+stream survival, and also shows why it must not be advertised as always visible.
+
+**Unverified:** persistent visible placement while playing a Steam-launched VR
+game, Plasma desktop and real Mac-window behavior during that launch, and worn
+headset input. Other threads were launching games and changing the runtime on
+the shared device, so those transitions were not treated as controlled evidence.
+A runtime/X-server restart can destroy the viewer windows; a network reconnect
+cannot recreate them. No “always visible during games” guarantee is shipped.
+
+## Keyboard passthrough feasibility
+
+**Verified 2026-09-28**, same build, using `FnTable:IVRTrackedCamera_006`:
+`HasCamera(0)` returned success and true. `GetCameraFrameSize` returned 100
+(`OperationFailed`), with zero dimensions, for all three public frame types
+(distorted, undistorted and maximum-undistorted), including after acquiring the
+video service. Acquisition returned success and a handle; release returned 101
+(`InvalidHandle`). The probe shut down its OpenVR client afterwards. No camera
+frames were captured and no camera settings were changed.
+
+**Documented:** the public OpenVR camera interface provides camera frame sizes,
+intrinsics, projections and streaming handles; these are prerequisites for a
+spatially aligned camera cutout. See Valve's
+[OpenVR C API](https://github.com/ValveSoftware/openvr/blob/master/headers/openvr_capi.h).
+
+**Inferred:** camera presence alone does not establish access to camera pixels.
+The failed frame-size path blocks a keyboard cutout in our current panel
+implementation. We have not established a keyboard detector or a calibrated
+camera-to-panel mapping. Built-in full-room passthrough is not proof of a
+public, selectively masked camera stream. No keyboard cutout is offered, and
+no third-party camera/overlay app is substituted for it.
 
 ## Frame Control's media theatre
 

docs/pc-in-headset.md

@@ -1,199 +0,0 @@
-# PC in the headset
-
-Windows and Linux hosts use **Tools → PC in the headset**. The host shares a
-window or screen, and the existing Frame viewer makes it a SteamVR panel.
-Move it with the dashboard's Float in World, Move and Size controls.
-
-**Inferred / not yet verified on a desktop host:** the Windows and Linux
-capture and input paths below. This work was developed on a Mac with no
-Windows or Linux desktop VM. A native build or test-pattern test in CI does
-not establish that desktop capture, a permission dialog, hardware encoding
-or laser input works. Keep this feature in the draft/testing stage until
-those paths have been tried on real hosts.
-
-## Own implementation, platform APIs and bundled libraries
-
-Frame Control owns the host agent, input routing, authentication, streaming
-protocol, panel launcher and adaptation. It does not launch or require
-Sunshine, OBS or another desktop-streaming app. GStreamer and its codec
-plugins are ordinary libraries bundled with the Windows and Linux app;
-users do not install a GStreamer application. The shared library build keeps
-license texts and package provenance alongside the libraries. Linux also
-bundles the PipeWire client’s dynamically loaded SPA/protocol modules and a
-private client configuration; it does not change the desktop’s configuration.
-
-First-party alternatives considered (**documented**): Valve Remote Play
-streams a game/desktop, rather than providing this per-window panel protocol;
-Windows Remote Desktop opens a remote session; Linux's desktop portal is the
-consent mechanism for sharing the current desktop. The chosen paths are:
-
-| Host | Capture | Encoding | Input |
-|---|---|---|---|
-| Windows | Windows.Graphics.Capture, through `d3d11screencapturesrc capture-api=wgc`; HWND or HMONITOR | Hardware Media Foundation (`mfh264enc`), low latency, no B-frames | `SendInput`, with source bounds and per-monitor DPI awareness |
-| Linux | RemoteDesktop + ScreenCast portal, then the returned PipeWire fd/node | VA-API (`vah264enc`) where registered; x264 otherwise | RemoteDesktop portal notifications, using only granted pointer/keyboard devices |
-
-API choices are **documented**, not device verification:
-[Windows capture](https://learn.microsoft.com/en-us/windows/uwp/audio-video-camera/screen-capture),
-[GStreamer WGC](https://gstreamer.freedesktop.org/documentation/d3d11/d3d11screencapturesrc.html),
-[Media Foundation encoder](https://gstreamer.freedesktop.org/documentation/mediafoundation/mfh264enc.html),
-[ScreenCast portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.ScreenCast.html),
-[RemoteDesktop portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.RemoteDesktop.html).
-
-Windows needs a WGC-capable Windows 10/11 desktop and an available hardware
-Media Foundation H.264 encoder. Elevated windows and the secure desktop
-cannot be driven by an ordinary Frame Control process. If Windows refuses
-to focus a selected window, input is refused rather than sent to the app
-covering it; bring the selected window forward, then Stop and Show again. Minimized/closed
-windows may stop producing frames. Protected content is not supported.
-
-On Linux, press **Choose a window or screen…** and approve the desktop's
-sharing dialog. Choose another source to add another panel. Stop releases
-that source's portal session; sharing it again asks for consent again.
-A desktop must implement both ScreenCast and RemoteDesktop for this path;
-a ScreenCast-only compositor cannot provide laser input through this API.
-Cancelling or denying a dialog is reported on the card. No portal permission
-is bypassed, and Frame Control does not open `/dev/uinput` or the unrestricted
-PipeWire daemon on the host.
-
-The host's own keyboard still works. Input from the viewer uses normalized
-picture coordinates, maps through the selected source's bounds, and releases
-held buttons/keys on blur, disconnect and Stop. Linux requires the pointer
-and keyboard grants. **Untested:** desktop-specific consent, mixed-DPI
-Windows input alignment, multi-monitor layouts, hardware encoder behavior,
-window resize/minimize, and non-US keyboard layouts.
-
-## Shared pieces
-
-- `ui/frame_macview.py` owns the SSH tunnel, reconnect supervision, quality
-  presets and panel launch for all hosts. `ui/frame_pcview.py` selects the PC
-  helper; `/api/macview` remains the compatible endpoint.
-- `ui/mac-view.html` is the one viewer. The 17-byte big-endian frame header,
-  Annex-B H.264/JPEG payloads, `hello`/`ack` reconnect handshake, clock sync,
-  `rx`/`fd` timing reports and input messages are unchanged.
-- `desktop/controller.c` is the rate controller shared by the Mac Swift
-  binding and the PC Python binding. Capture is gated **before** encoding;
-  encoded reference frames are never discarded. A bounded raw-frame queue
-  keeps the newest picture, including the last update of an idle window,
-  until the gate opens. A native one-frame-source test covers that case.
-  It keeps the Mac's bitrate demand protection and tier hysteresis.
-- PC records use the existing `Stats.swift` JSON schema, with bounded
-  4096-frame/512-input storage in `ui/frame_stream_stats.py`. The benchmark's
-  analysis, targets and network shaping are shared, not reimplemented.
-  Capture timestamps describe the native pipeline's source time; they do
-  not prove the time at which the host compositor displayed the pixels.
-- Mac virtual-display separation remains Mac-only. Windows WGC and the
-  Linux portal share the selected window directly.
-
-PC capture follows the shared frame-rate and resolution tiers. x264 updates
-bitrate while running. Hardware encoders are drained and reopened when the
-budget changes materially, at most once a second, because their live property
-support varies. Reopening starts a new keyframe and retains the consented
-portal session. **Untested:** hardware reconfiguration latency and whether a
-particular desktop permits reconnecting its PipeWire stream this way.
-
-## Build and measure
-
-Packaged Windows/Linux builds include `desktop/bundle/pc-host` and its shared
-libraries. Source checkouts build them with `python3 desktop/build.py` after
-installing GStreamer development packages (see the `PC host libraries` CI
-workflow). The feature reports a missing bundle; it does not download or
-install a streaming app on first use.
-
-The existing benchmark now accepts a PC host:
-
-```sh
-python3 scripts/macview-bench.py run --pc --scenario test --label pc-test
-# Linux: select a real source in the desktop's sharing dialog
-python3 scripts/macview-bench.py run --pc --scenario capture --source choose --label linux-window
-# Windows: use the HWND/monitor source ID shown by the host's /windows or /displays
-python3 scripts/macview-bench.py run --pc --scenario capture --source window:12345 --label windows-window
-```
-
-The synthetic PC pattern uses bundled x264 so headless CI can verify the
-wire protocol without claiming that a GPU was exercised. The `capture`
-scenario measures the selected real source without injecting input or
-assuming that it animates at 60 fps. Mac-only Chrome/virtual-display typing
-and scrolling automation is not run on PC hosts. Results retain the same
-latency stages and record `host_platform`, `pc_host` and `source`. CPU sampling
-on PC hosts is explicitly unavailable. `--net` and `--delay` still use the
-same bounded shaping relay, without administrator privileges.
-
-## Evidence
-
-- **Verified, Mac, 2026-09-28:** the final full unit/integration suite ran
-  183 tests successfully, including the real Mac helper's H.264, ticket, timing
-  and input-echo tests. The native PC test class was skipped locally because
-  its libraries were absent; the PC adapter and shared-controller tests passed.
-- **Verified, real Frame, 2026-09-28, BUILD_ID 20260925.6191901:** the base
-  helper's synthetic source created panel `valve.steam.desktopgame.2001639889`,
-  and the shared Chromium viewer decoded H.264. It recorded 286 frames over
-  the short probe, with a two-second summary of 19.5 fps shown and total
-  latency p50/p95 83/156.5 ms. This establishes the existing viewer/transport
-  route, not Windows/Linux capture, input or a latency target. The probe's
-  helper, tunnel and viewer were stopped afterward.
-- **Verified in CI:** native library builds and real x264 protocol tests passed
-  on Windows, Ubuntu x64 and Ubuntu ARM64 in
-  [run 36422214445](https://github.com/saphid/frame-control/actions/runs/36422214445).
-  All four installer builds passed in
-  [run 36422214425](https://github.com/saphid/frame-control/actions/runs/36422214425).
-  These are build/synthetic tests, not desktop-host verification. No VM was used.
-- **Verified, real Frame, same build/date:** the ARM64 PC agent and its
-  bundled libraries ran from a temporary user directory, using x264's moving
-  test pattern. Traffic travelled Frame → Mac SSH relay → Frame viewer.
-  The shared bench recorded 351 drawn frames, content p50/p95 15.1/80.3 ms,
-  and 34.8 fps. The frame-rate and late-frame targets failed. This checks the
-  new agent and real viewer together; it is not a representative PC link.
-  The helper exited 0, its viewer/tunnels stopped, and its directory was removed.
-  [Raw benchmark result](../bench/results/2026-09-28-c5fc552-dirty-pc-agent-frame-arm64-hairpin.json).
-  This first probe's input echo measured message receipt to the next capture,
-  not a visible pattern response; later builds make test clicks change its color.
-- **Verified, Mac:** all 600 states in a 60-second congestion/recovery trace
-  matched the original Swift controller. `tests/test_pc_controller.py` retains
-  the original trace digest as a regression check.
-- **Verified, real Frame, agent at `cd20243`:** the repeated synthetic
-  probe drew 400 frames at 39.3 fps, content p50/p95 15.1/28.6 ms, and synthetic
-  input-to-drawn p50 76.6 ms. Test clicks now change the pattern color before
-  injection is timestamped. The frame-rate/late-frame targets still failed;
-  this remains a Frame-hosted x264 test through a Mac relay, not a desktop or
-  physical-laser measurement. Helper exit 0 and cleanup succeeded.
-  [Latest device probe result](../bench/results/2026-09-28-cd20243-pc-agent-frame-arm64-final.json).
-- **Untested:** real Windows WGC → Media Foundation → Frame; real Linux
-  portal → PipeWire → VA-API/x264 → Frame; physical laser input on either.
-  No benchmark numbers for those desktop paths are claimed.
-
-## Independent review availability
-
-A direct read-only review was attempted with
-`devin -p --model swe-2-max --permission-mode auto --prompt-file …`. The first
-attempt exited 0 after rejecting a tool that needed interactive permission;
-it did not inspect the diff. A full inline-diff attempt returned no output
-for 15 minutes and was terminated (shell exit 143). A smaller inline native
-code review returned no output within 300 seconds (process exit -15).
-SWE-2 Max was requested; no completed review or findings were received, so
-independent review is **unverified**, not a passed check. The PR remains draft.
-
-## Device follow-up, 2026-09-29
-
-**Verified, read-only, SteamOS BUILD_ID 20260925.6191901:** the Frame was
-reachable, charging (44% initially, 63% at the end), and SteamVR reported
-activity level 3 (standby). No Plasma desktop was running. Introspection of
-the active `org.freedesktop.portal.Desktop` service exposed ScreenCast with
-source types 3, but no RemoteDesktop interface. **Inferred:** this gamescope
-session cannot provide this feature's required consented input path; a
-ScreenCast-only session is insufficient.
-
-**Blocked, not a device execution result:** the shared `/tmp/frame-test.lock`
-was held by another thread. Ten lock-acquisition attempts over five minutes
-all failed, after earlier preparation-time attempts also found it occupied.
-The current `a992f6d` ARM64 CI bundle was downloaded to the Mac, but nothing
-was installed, launched or stopped on the Frame. No new screenshots or
-current-revision device timings were obtained. The lock was not removed and
-no global settings were changed. The earlier synthetic results above remain
-valid only for their named revisions; standby visibility, physical laser
-input and worn-headset performance remain unverified.
-
-**Verified, Mac:** a fresh full suite ran 309 tests successfully, with one
-native-PC class skipped. Current-revision CI passed
-[native hosts](https://github.com/saphid/frame-control/actions/runs/36504546909),
-[installers](https://github.com/saphid/frame-control/actions/runs/36504546800)
-and [general checks](https://github.com/saphid/frame-control/actions/runs/36504546887).

docs/sidequest.md

@@ -0,0 +1,142 @@
+# SideQuest and Frame Control
+
+Researched 2026-09-28. SideQuest is both a Quest discovery website and a desktop
+sideloading/device-management app. Its Quest labels are **not** evidence that a
+game works on Lepton: inspect the APK for arm64/OpenXR, Android API requirements,
+VrApi and Meta services (see [VR APKs](vr-apks.md)).
+
+## Features worth borrowing
+
+Desktop evidence is the public [SideQuest source at af2ac70](https://github.com/SideQuestVR/SideQuest/tree/af2ac7043db122bca3c8db18f2b58f1660e9befb),
+especially [ADB operations](https://github.com/SideQuestVR/SideQuest/blob/af2ac7043db122bca3c8db18f2b58f1660e9befb/desktop-app/src/app/adb-client.service.ts),
+[drag and drop](https://github.com/SideQuestVR/SideQuest/blob/af2ac7043db122bca3c8db18f2b58f1660e9befb/desktop-app/src/app/drag-and-drop.service.ts),
+and the [legacy repository index](https://github.com/SideQuestVR/SideQuest/blob/af2ac7043db122bca3c8db18f2b58f1660e9befb/desktop-app/src/app/packages/package.service.ts).
+Website evidence: [SideQuest](https://sidequestvr.com/) and its public Angular
+bundle `main-4MMXZRXL.js`, inspected locally without browser automation.
+No SideQuest implementation code was copied.
+
+| SideQuest feature | Frame Control before this change | Borrow? / effort |
+|---|---|---|
+| Store descriptions, screenshots, banners, trailers, ratings | F-Droid names, icons, compatibility verdicts and reports; no equivalent rich VR store | Yes, from authorised sources; medium. Search and library workers own presentation/artwork. |
+| OBB expansion-file install | APK-only install | **Implemented helper and CLI**, medium. Essential for games whose assets are separate from the APK. |
+| App-data backup/restore | Persistent instances and optional keep-data uninstall, no portable save archive | **Implemented private-data helper and CLI**, medium. Back up before updates or experiments. |
+| File manager (list, upload, download, remove) | General Send to Frame, no Android file browser | Useful later, medium; requires clear instance selection and scoped paths. |
+| Installed-app management (launch, uninstall, backup) | List, launch, stop, remove, probe | Already mostly covered. Backup added here. |
+| Update notices / account library | Compatible-version lookup; no source-aware installed update notices | Useful later, medium; needs original version code and source identity recorded on install. |
+| Custom repositories | Built-in F-Droid catalogue and compatible-version indexes | Separate user-repos worker. Legacy SideQuest source has a fixed SideQuestRepos index; arbitrary current custom-repo support was not verified. |
+| Drag-and-drop APK/OBB install | APK drag-and-drop already works | OBB backend added here; future UI can call it. UI drop wiring is not included. |
+| Tags, price, headset filters, reviews | Text search and Lepton verdicts, not Quest headset metadata | Useful, medium; search worker owns filters. Keep source headset claims distinct from tested Frame compatibility. |
+| Screenshot/video capture and streaming | Frame screenshots/VR capture already present | Reuse existing tools; do not port Quest capture commands. |
+| Device settings and ADB utilities | Frame/Android display settings, SSH and own-instance tools | Borrow selectively; Quest CPU/GPU presets and wireless-ADB setup do not map directly to Lepton. |
+
+Priority: expansion files, then save backup/restore. Rich discovery and update
+notices follow once a permitted metadata source and source/version persistence
+are available. This patch deliberately exposes CLI/backend operations, leaving
+shared UI, install(), Steam artwork and launch behavior to sibling work.
+
+## SideQuest as a source: page-only
+
+[Terms](https://sidequestvr.com/terms), “Prohibited Activities”, (i) prohibits
+copying/distributing/disclosing the Service including automated or non-automated
+“scraping”; (xi) prohibits content access through means other than those provided
+or authorised by the Service; (xii) prohibits bypassing access restrictions.
+The terms describe downloading developer-posted games through the Service, but
+do not establish permission for this third-party API integration.
+
+[robots.txt](https://sidequestvr.com/robots.txt) requests a three-second crawl
+delay and disallows `/search/`, `/user/*` and `/sideload/*`. Robots permission
+would not override the terms. The API host's robots request returned HTTP 403;
+a request for the first shared website JS chunk also returned 403. No bypass,
+account token, cookies, browser session or private endpoint was used.
+
+The homepage publishes `https://api.sidequestvr.com` and
+`https://cdn.sidequestvr.com`. The website bundle calls `searchApps(...)` and
+`getApp(id, null)`; their actual HTTP search/detail routes could not be established
+from the retrieved bundle. Do not invent endpoints. The open-source desktop
+[install flow](https://github.com/SideQuestVR/SideQuest/blob/af2ac7043db122bca3c8db18f2b58f1660e9befb/electron/app.ts)
+POSTs `{token: ...}` to `/install-from-key`. It consumes
+`data.apps[].urls[]`, with `provider` values including `APK`, `OBB`,
+`Github Release` and `Mod`, and `link_url`. This is a website-issued install-key
+flow, not evidence of an anonymous download API. It is not implemented here.
+
+`ui/apk_sources/sidequest.py` implements the shared interface conservatively:
+
+- `sources()` marks SideQuest `page_only` and explains why.
+- `search()` raises a user-readable `SourceError` with the browse URL (zero
+  limit returns no rows). It does not invent app results or report a false
+  “no matching games”. The aggregate search UI should surface this source error.
+- `details()` accepts a numeric listing id and returns its canonical page link,
+  `downloadable: False`, empty versions/tags/headsets and the `images` shape
+  `{icon: None, banner: None, screenshots: []}`. Name is explicitly a listing id;
+  unknown facts, including free/VR status, stay `None`.
+- `download()` refuses with that page link. Paid/external listings cannot be
+  downloaded by this adapter either. No downloads means no verification claim.
+
+The JSON fixture records policy evidence, **not a purported live app response**.
+No listing metadata, artwork URLs, or OBB download URLs were scraped.
+The requested real SideQuest → OpenXR APK → `frame_android.py info` test is
+**blocked by the terms**, and was not performed. No alternate source is silently
+substituted. A future integration needs SideQuest's permission or an expressly
+supported third-party API, plus recorded search/detail/download fixtures,
+free/direct-download classification, and size/hash verification. A calculated
+local SHA-256 alone must not be called publisher verification.
+
+## OBB files
+
+```sh
+python3 ui/frame_android.py install-obb org.example.game main.42.org.example.game.obb
+python3 ui/frame_android.py install-obb org.example.game main.42.org.example.game.obb patch.42.org.example.game.obb
+```
+
+Install the APK first. The named instance must already be running; the helper
+never launches an app or uses Lepton Development. It requires standard
+`main|patch.<versionCode>.<package>.obb` filenames and nonempty files, validates
+the entire batch before transfer, streams each file through SSH into that
+instance, checks its SHA-256 **inside Android**, then renames it into
+`/sdcard/Android/obb/<package>/`. `verified: True` here means transfer integrity
+against the local input, not publisher authentication. Publication is atomic per
+file, not for the whole batch; retry after a partial batch failure. Existing OBBs
+with different version codes remain. The filename version must match the game;
+the current install metadata does not expose its version code for comparison.
+Restart the game yourself after the transfer if it cached missing expansion data.
+
+Both read-only SSH attempts to the Frame timed out. Therefore the exact
+host-side `/sdcard` mapping and persistence of expansion data were **not verified**.
+`compatdata/<instance>/internal/<package>` is documented as `/data/data/<package>`;
+it must not be mistaken for `/sdcard`. Using Android's path avoids guessing a
+host layout, but device verification across restart/update is still required.
+No OBB file was installed on the Frame during this work.
+
+## Private app-data backups
+
+```sh
+python3 ui/frame_android.py stop org.example.game
+python3 ui/frame_android.py backup-data org.example.game ./game-save.tar.gz
+python3 ui/frame_android.py restore-data org.example.game ./game-save.tar.gz
+```
+
+Keep the instance stopped throughout either operation; do not launch it from
+Steam concurrently. The remote guard fails if Podman cannot enumerate containers
+or reports that instance running. The helpers use `podman unshare` to read/write
+Android's mapped ownership without changing the live data's permissions.
+
+The archive covers **only** `compatdata/<instance>/internal/<package>`, not the
+APK, external `/sdcard/Android/data`, OBBs, keystore, or the full Android snapshot.
+It contains a package/instance manifest and regular files/directories. Backups
+are private (0600), validated before publication, and never overwrite an existing
+backup. Keep them safe: app data can contain credentials and is not encrypted.
+
+Restore checks the package and instance, rejects absolute/traversing/duplicate
+paths, links and devices, caps files at 100,000 and content at 20 GiB, and validates
+again on the Frame. It extracts into a separate directory, preserves numeric
+ownership, ordinary modes and timestamps, then swaps the private-data directory.
+Setuid/setgid bits are not restored. The previous directory remains beside it as
+`.<package>.before-restore-<timestamp>`; the returned `previous` path identifies
+it. This is an additional recovery copy, not an automatic deletion policy.
+
+Locally verified: archive round trip including recovery copy, malformed archive
+rejection, transfer command construction and failure handling. Not verified:
+real Frame UID mappings/permissions, Android app-level recovery, live FUSE OBB
+writes or persistence. Backups reject symlinks/special files; an app requiring
+those needs a separately designed backup format. These CLI features still need
+a real-device acceptance pass before being exposed as a polished UI workflow.

docs/steam-games.md

@@ -110,3 +110,11 @@ returns nothing without `cc`, so Frame Control takes the country from
 - Installing when there's more than one library folder, such as a microSD card.
 - Uninstalling. `steam://uninstall/<appid>` should open a confirmation in the
   headset.
+
+## Optional VR software
+
+The [VR utilities list](vr-utilities.md#optional-software) is separate from our
+controls and HUD. It checks software ownership as well as games; paid utilities
+are installable only when already in the loaded Frame account library. No
+purchase flow is added. Public reports, local results and ownership are shown
+separately, and untested tools remain untested.

docs/streaming.md

@@ -8,6 +8,7 @@ This covers three directions, plus input:
 - **PC VR from Linux**: [feasibility and options](linux-vr-streaming.md),
   including Valve's streaming and USB support. No Linux host tested yet.
 - **Input**: type and point in the Frame from the Mac or iPhone.
+- **Live view and Control**: watch a panel flat and tap on it to use it.
 
 The confidence labels are the same as in [ssh.md](ssh.md).
 
@@ -184,13 +185,72 @@ on the Frame, which talks KDE Connect's own LAN protocol to the Frame's
   and ignores injected pointer motion; `:1` holds apps such as Chromium and
   takes it. KDE Connect runs on `:1`, so it reaches apps, not Steam's own menus.
   There's also a `gamescope-0-ei` (libei) socket.
-- **Not yet tested:** typing and clicking as seen in the headset, and whether
-  it reaches the KDE desktop panel (Plasma is its own session).
+- Typing through KDE Connect lands in a Chromium panel on `:1` (seen in the
+  panel's own capture, 2026-09-29). It **can't reach panels on `:0`** (Frame
+  Control's own panels, Steam's UI) and, since XTest positions are clamped to
+  `:1`'s 1280×720 root, can't reach beyond that in a bigger window. Control on
+  the live view (below) has neither limit.
+- **Not yet tested:** whether it reaches the KDE desktop panel (Plasma is its
+  own session).
 - **Known limit:** keys and clicks typed while the link is reconnecting wait
   and are sent once it's back, but anything sent in the moment the Wi-Fi
   drops, before SSH notices, can be lost. Confirming every event would add a
   round trip to each pointer move.
 
+## Live view and Control: watch a panel and tap on it
+
+**Built: Home → Desktop / Headset view → Control.** The live view has two
+sources:
+
+- **Headset view**: what the lenses show (SteamVR's mirror, `/dev/video99`). It
+  moves with the wearer's head, so Control makes the view a trackpad: drag to
+  move the pointer, tap to click, press and hold to right-click, two fingers to
+  scroll. With a mouse, moving over the view moves the pointer.
+- **Desktop**: the app panel in use in the headset, from its own window, so it
+  stays still however the wearer looks around. Control makes taps and clicks
+  land exactly where you put them. Dragging is a mouse drag, press and hold is a
+  right-click, two fingers scroll, and on a computer the mouse, wheel and
+  keyboard work directly on it (⌘ is sent as Ctrl on a Mac). A picker shows any
+  other panel, view only.
+
+Below the view, a text field and key buttons type on the Frame from a phone.
+
+How (**verified 2026-09-29**, SteamOS 0.4.1, build 20260925.6191901):
+
+- **Input goes through gamescope's own injection.** gamescope serves an EIS
+  socket (`/run/user/1000/gamescope-0-ei`; Steam feeds Remote Play input through
+  it), and `libei` 1.4.1 is on the image. [`ui/frame_touch.py`](../ui/frame_touch.py)
+  talks to it with `ctypes`: nothing to install. gamescope offers one device,
+  "Gamescope Virtual Input", with relative and absolute pointer, buttons,
+  scroll and keyboard (Linux key codes; no text capability, so the text field
+  types printable ASCII on a US layout). Its absolute region is unbounded; the
+  pointer uses the focused panel's display coordinates, and gamescope fits each
+  window to its display, so a 1920×1080 window on the 1280×720 `:1` takes
+  positions at two thirds scale. Taps on a 1280×720 page landed on the exact
+  pixel.
+- **It reaches the panel that has focus** (`GAMESCOPE_FOCUSED_WINDOW` on `:0`'s
+  root), on either X display. In the OpenVR backend focus moves only on SteamVR
+  overlay events (the controller's laser entering or clicking a panel), or to a
+  new panel when none holds it (read from gamescope's `OpenVRBackend.cpp`, seen
+  with `gamescopectl focus_info`, which writes to the journal). Neither
+  `GAMESCOPECTRL_BASELAYER_WINDOW`/`_APPID` nor X focus moves it, and no
+  gamescope command does. So Control follows the wearer: whatever they last
+  used is what your taps reach. A window without a Steam app id (`STEAM_GAME`)
+  gets a connector of its own and doesn't hold focus.
+- **Keys in a burst can arrive out of order**, so the helper paces them (8 ms
+  apart).
+- **Known limit:** if focus moves to another panel in the middle of a drag, the
+  release goes to the panel that has focus then. Whether gamescope hands it to
+  the window that got the press isn't known yet. When the session ends, the
+  helper lets go of every button and key it still holds.
+- **The Desktop picture is the window's own pixels**: `ffmpeg -f x11grab
+  -window_id <window> -i :<display>` works on gamescope's redirected windows,
+  while grabbing the root gives black. It streams as H.264 like the headset view
+  (about 30 fps at 720p).
+- Tested from the iPhone app (Simulator): a tap on the Desktop view focused a
+  text box in the panel and the text field typed into it; a trackpad move went
+  exactly (+40, +25).
+
 Our own `uinput` keyboard and mouse would also work (`steamos` is in the
 `input` group and `/dev/uinput` is group-writable, verified 2026-09-27), and
 remains the fallback if the bundled KDE Connect ever stops working on a new SteamOS.

docs/testing.md

@@ -104,6 +104,20 @@ switch while SSH is down:
 
 ## Headset smoke test
 
+**Documented shared-device procedure:** before a test installs, launches or
+stops an application, acquire `ssh frame 'mkdir /tmp/frame-test.lock'`. If it
+fails, leave that lock alone and continue offline work. Only the thread that
+acquired it releases it with `ssh frame 'rmdir /tmp/frame-test.lock'`, after
+cleanup. Keep each device session to a few minutes.
+
+Check battery capacity and charging state under `/sys/class/power_supply`
+before and after; keep capacity above 20%. Stop only processes started by the
+test, remove temporary installs and profiles, and restore the prior dashboard
+state. Leave Steam and SteamVR running. Do not reboot or change global settings.
+Record the build, actual interaction results, cleanup and any unworn-headset
+limits alongside screenshots or logs. These are caller responsibilities; the
+smoke script below does not acquire this shared lock itself.
+
 ```sh
 scripts/frame-smoke.sh           # needs `ssh frame` to work without a password
 scripts/frame-smoke.sh --pair    # also pairs a throwaway key: approve it in the headset
@@ -149,17 +163,6 @@ refuses ids with a hyphen (`missing/invalid arguments`), which the fake had
 accepted. The fake now refuses them the same way, and Frame Control makes ids
 Steam accepts.
 
-## PC panel host tests
-
-`tests/test_pcview.py` checks source-bound tickets, reconnect/Stop revocation,
-input release, source-coordinate mapping and use of the existing panel
-launcher. The `PC host libraries` workflow builds the bundled native adapter
-on Windows, Ubuntu x64 and Ubuntu ARM64, then runs a real x264 synthetic
-stream through the HTTP/WebSocket agent. `FRAME_PC_REQUIRE_NATIVE=1` makes a
-missing native bundle fail CI instead of skipping. These tests do not grant a
-portal dialog, capture a desktop, exercise a hardware encoder or validate
-laser alignment. See [PC host evidence](pc-in-headset.md#evidence).
-
 ## Owned media player
 
 `tests/test_media.py` covers layout evidence and overrides, OU eye ordering,
@@ -181,3 +184,29 @@ assistant against an in-process HTTP endpoint with canned responses (no keys or
 external calls). `tests/e2e/test_agents.py` runs the MCP/HTTP/SSH path against the
 fake Frame for approved installs, clipboard and file transfer. Headset Chromium
 rendering and real screenshots still need a device; see [agent evidence](agents.md#evidence-and-limits).
+
+## Family and comfort
+
+`tests/test_comfort.py` uses an injected clock, fake headset sensor readings and
+actions, plus a Node fake of Steam's Home API. It covers warnings before Home,
+late/suspended sessions, cancellation, failed actions, duplicate alerts, reboot
+invalidation, per-zone thermal trips and shared on-headset state. The server
+guards reject invalid session settings before SSH. See
+[real-device evidence and limits](family-comfort.md#verification).
+
+## Panel switcher
+
+`tests/test_panels.py` supplies fake-Frame `vrcmd --overlays` output, checks
+main-panel filtering (including hidden panels), revalidates closed panels before
+focus, and drives the headset helper's real loopback HTTP server to test access
+keys, Host/Origin guards, malformed requests, offline errors and Close. It runs
+in the normal unit suite without OpenVR or a headset. The fixture format comes
+from SteamVR 2.18.1, BUILD_ID `20260925.6191901`; it does not simulate rendering.
+
+On the Frame, run `python3 -` over SSH with `ui/frame_panels.py` on stdin to
+list panels. `--focus <key>` rechecks the list and requests focus. In Frame
+Control, **Tools → Panel switcher → Open in headset** exercises installation,
+Chromium rendering and the same helper through HTTP. Close the switcher after
+testing. [The recorded device checks](panels.md#frame-controls-panel-switcher)
+cover actual focus, HTTP guards and an OpenXR sample transition, and separately
+identify the unverified Steam-game, spatial layout, reboot and laser behaviors.

docs/vr-apks.md

@@ -84,6 +84,132 @@ not being worn, so it did not reach `FOCUSED`).
 The loader was never the problem: Wolvic's Quest `libopenxr_loader.so` is a
 Khronos-style loader and found SteamVR through `/vendor`.
 
+## In the Steam library
+
+Every successful APK install goes through the same mandatory artwork writer:
+CLI (including `scripts/install-apk.sh`), upload, catalogue, version finder,
+web download and source modules calling `frame_android.install`. Native
+Linux/Windows sideloads also use it, preserving their devkit runtime wiring.
+A new shortcut is rolled back if artwork fails; failure is never reported as
+an installed app with a blank tile.
+
+Artwork preference is **SteamGridDB → source images → generated fallback**.
+Set the optional free key in Frame Control's **Library artwork settings**, or
+`STEAMGRIDDB_API_KEY` (`FRAME_STEAMGRIDDB_API_KEY` also works). Environment
+settings override the saved key. Without a key there are no provider calls or
+warnings. Saved keys stay in host app data, mode 0600 on POSIX, and are never
+returned by the settings API or copied to the headset. Exact title matches
+(including a trailing “VR” variant) use the highest-scored returned static,
+non-NSFW image in each slot. Provider failures use the next source.
+
+Sources pass `install(apk_path, artwork={...})`: keys are `grid`, `wide`,
+`hero`, `logo`, `icon`, `banner`, `feature_graphic`, `screenshot`, or a list
+`screenshots`. Values are PNG/JPEG bytes or HTTP(S) URLs (12 MiB and
+4096×4096 pixels maximum; any PNG depth or interlace, since the Frame's
+Chromium decodes them). URLs must resolve to public addresses, follow at most
+three redirects and share one deadline per install. Any source that fails,
+for any reason, becomes a warning and generated art. Banners and feature graphics supply hero/wide art;
+screenshots are the next fallback. Source images are cached for refresh.
+All images are fitted to 600×900 portrait, 920×430 wide, 3840×1240 hero,
+1280×480 logo and 256×256 icon. Explicit logos retain transparency.
+Photo-based portrait, wide and hero slots are JPEG: Steam takes at most
+12 MiB per slot, and on the Frame (2026-09-28) a noise-heavy 3840×1240 hero
+came to more than 12 MiB as PNG, 3.7 MB as JPEG (2.7 s to render); a
+landscape photo hero 5.6 MB as PNG, 0.76 MB as JPEG (0.75 s). A render that
+still fails is retried once with generated art. Steam keeps a slot's `.png`
+and `.jpg` side by side, so each slot is cleared before it is set.
+
+Generated art uses the APK icon, a dominant-colour gradient, a blurred
+backdrop and large foreground icon with shadow. Steam's Chromium canvas and
+Motiva Sans render real text consistently regardless of the host OS; no
+Pillow, host font installation or bitmap font is needed. The hero has no
+title; the generated logo is a transparent title. APKs with no usable icon
+get a typographic monogram. The desktop package includes the renderer.
+
+Backfill installed Android apps without reinstalling or stopping them:
+
+```sh
+python3 ui/frame_android.py refresh-art org.godotengine.open_saber_plus
+python3 ui/frame_android.py refresh-art --all
+```
+
+Devkit titles installed by Frame Control have the same command,
+`python3 ui/frame_titles.py refresh-art ID|--all`. The settings panel's
+refresh covers both. The API is `POST /api/android` with
+`{"action":"refresh-art","all":true}` (apps and titles) or a `package`, and
+`POST /api/titles` with `{"action":"refresh-art","id":…}`; each returns a
+background job. Batch results retain per-item errors, and the CLIs exit
+nonzero if any failed. Apps and titles without complete artwork show **Add
+artwork** and `list` prints the command. Only entries marked `art_pending` at
+install (a title Steam registered after an install made while it wasn't
+running) are backfilled automatically, when Frame Control lists them with
+Steam running (at most every five minutes), and that backfill only fills
+slots Steam has no art for: names, icons, flags and any art the user set are
+kept. Older installs without the flag are refreshed only on request.
+
+Steam's app overviews carry no `devkit_gameid` (checked 2026-09-28, build
+20260925.6191901, on every non-Steam shortcut). A title's shortcut is found by
+its saved id, or by an executable or start folder inside
+`~/devkit-game/<id>/`, read from `appDetailsStore`; never by display name.
+That the devkit shortcut's exe/start folder sit inside the title folder is
+inferred from `docs/sideloading.md` (`proton waitforexitandrun
+"/home/steamos/devkit-game/<id>/<exe>"`), not yet seen in app details.
+Devkit titles keep the VR flag Steam gave them.
+
+**Verified on build 20260925.6191901, SteamVR 2.18.1 (2026-09-28):** both
+Open Saber Plus and SuperTux were backfilled. Steam's cached portrait, wide,
+hero and logo PNGs have the dimensions above; each shortcut points at its
+256×256 icon. This Frame client mishandles custom-art type 4 (documented as
+Icon), overwriting the wide capsule; the implementation uses custom types
+0–3 and **SetShortcutIcon** separately.
+
+Steam accepts display name, executable/start directory, icon, VR flag and
+sort-as name. Android apps join **Android**, immersive apps also **Android
+VR**; native sideloads join **Sideloaded**. Existing collection members and
+unrelated collections are preserved (both games retained **Played**).
+Dynamic/read-only collection conflicts produce warnings. The native notes
+API supports a managed **Installation details** note (package, version and
+source) while preserving other notes. Notes are keyed by sanitized shortcut
+name, so Steam itself cannot distinguish equal-name shortcut notes. No
+supported shortcut description/store-page, developer/publisher, release
+metadata or custom achievement API was found; these are not fabricated.
+
+The launcher supervises Lepton and handles TERM/INT/HUP and normal exit by
+stopping its own container and child process group. A lock refuses duplicate launches;
+a container still running while the lock is free was orphaned by a killed
+launcher and is stopped before the new launch. Lepton doesn't inherit the
+lock. Orphan recovery only stops the app's own, deterministically named
+container; a Lepton host process whose launcher was killed before it created
+the container may linger briefly. Removing an app or title still deletes its files when Steam isn't
+running; tidying Steam's collections and artwork is best effort. Steam Stop uses `TerminateApp` with the exact
+64-bit game ID string. Frame Control's Stop additionally has a direct-container
+fallback. The stable instance ID and compatdata paths remain unchanged.
+
+Lepton normally forwards the instance `SteamAppId` to Android, causing
+SteamVR to associate the scene with a different, artwork-less app. The
+launcher uses Lepton's supported `LEPTON_ENV_SteamAppId` passthrough to send
+the actual shortcut ID to Android while retaining the stable container ID.
+**Verified:** Open Saber was alive 22 seconds after Steam Play, SteamVR
+identified `steam.app.3346865537`, and its scene appeared in the headset
+capture without the previous blank Resume tile. Steam Stop then removed its
+tracked process and stopped the container. An earlier 32-second session was
+also tracked until Steam Stop. No global standby or dashboard overrides were
+installed; wear detection and other user-opened overlays still apply.
+
+**SuperTux limitation:** Steam launched and tracked it, but SDL crashed during
+activity creation because Lepton lacks `ClipboardManager`. Its container
+cleaned up on exit after about 17 seconds. Consequently sustained SuperTux
+Play/Stop and its VR scene could not be verified. This is an APK/runtime
+compatibility failure, separate from library presentation.
+
+Evidence is under `/tmp/vrlib-evidence/` on the development Mac: final artwork
+preview and three design passes, `steam-cache-final.log`,
+`steam-details-targets.json`, `opensaber-identity-session.log`,
+`opensaber-identity-headset.png`, and `supertux-lepton.log`. The preview is
+rendered artwork, not a Steam UI screenshot; CDP screenshot capture timed
+out. Authenticated SteamGridDB, Windows/Linux packaged builds and the sibling
+source-search endpoint remain unverified (the public install seam is tested).
+
 ## Out of scope
 
 - **Meta entitlement.** Apps that call the Oculus Platform SDK

docs/vr-utilities.md

@@ -0,0 +1,139 @@
+# VR comfort and performance
+
+Frame Control owns its HUD and telemetry. They use SteamVR/OpenVR, gamescope,
+Python and xterm already on the Frame, plus the Frame's sensors. No feature
+requires fpsVR, OVR Advanced Settings, XSOverlay or another third-party app.
+The software list is a separate, optional convenience.
+
+This is **part of [#25](https://github.com/saphid/frame-control/issues/25)**,
+not completion of the issue. Playspace controls remain blocked on the device
+checks below. The PR stays draft.
+
+## Our performance HUD
+
+On **Home → VR comfort and performance**, the app shows a timestamped sample
+with each status refresh (30 seconds, or Refresh). **Open HUD in headset**
+starts our text HUD as a gamescope panel, refreshed every two seconds. In the
+SteamVR dashboard, select **Frame Control HUD**, then Float in World or dock
+it to a controller. **Close HUD**, or closing its terminal, ends it. Opening
+it twice reuses the existing process.
+
+| Value | Meaning and source |
+|---|---|
+| Compositor FPS / period | Differences between two `IVRCompositor_029::GetFrameTiming` frame indices and monotonic compositor timestamps, sampled 200 ms apart. Output cadence, not game FPS or a long-term average. |
+| Application FPS | Reciprocal of OpenVR's client frame interval. Unavailable if there is no positive interval; not inferred from refresh rate. |
+| Render GPU time | OpenVR total render GPU milliseconds, not GPU utilisation. |
+| Compositor CPU | OpenVR compositor render CPU milliseconds, not game CPU time. |
+| System CPU | `/proc/stat` busy-time delta across the sample, with guest time counted once and iowait treated as idle. |
+| GPU clock | `3d00000.gpu/cur_freq`, converted from Hz to MHz; frequency is not load. |
+| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. |
+
+OpenVR uses background application mode, which does not start SteamVR or keep
+it running. This mode also returned live timing in a read-only device probe.
+
+Missing sensors, a stopped or incompatible SteamVR runtime, and non-advancing
+frame indices display **Unavailable**, never invented zero FPS. Failed status
+refreshes clear the HUD card rather than keeping a stale live-looking sample.
+The HUD itself adds CPU/GPU work; it is a diagnostic, not a zero-overhead benchmark.
+
+**Verified 2026-09-28**, SteamOS 0.4.1, build `20260925.6191901`, SteamVR
+2.18.1: the exact OpenVR interface and 192-byte timing layout returned advancing
+frame indices and live GPU/CPU timing. Sensor reads, creation of overlay
+`valve.steam.desktopgame.2000250025`, duplicate-open handling, and closing the
+HUD passed. The temporary probe overlay disappeared after its process closed.
+[Sanitized device sample](evidence/vr-utilities/device.json).
+
+**Unverified:** visual placement while wearing the headset, controller docking,
+and overhead during gameplay. The companion card was checked in the attached
+preview using live Frame data. Creating an overlay does not establish that it
+was visible to the wearer.
+
+The optional HUD copies only `frame_status.py` and `frame_vr.py` into
+`~/.local/share/frame-control/vr/`. It tags only the window whose X11 PID matches
+its own xterm, avoiding other threads' windows. Stop checks both PID and Linux
+process start time before sending SIGTERM. It does not stop Steam or SteamVR,
+edit their settings, install a service, or need sudo.
+
+## Playspace, seated height and recenter: paused
+
+**Verified 2026-09-28:** SteamVR exposes `IVRChaperoneSetup_006` and
+`IVRChaperone_004`. An initial 1 cm seated zero-pose translation committed,
+read back and restored numerically. A later trial, while the shared Frame was
+in use, changed universe IDs after commits and returned transforms that did
+not match the requested write or restore. Journal entries reported
+`CommitWorkingCopy`, `VREvent_ChaperoneUniverseHasChanged` and
+`VREvent_ChaperoneRoomSetupCommitted`. The collision-bound arrays and play-area
+size matched in the saved before/after records, but the origin matrices did not.
+
+Alex confirmed the headset was in use and asked to pause control tests. No
+further playspace writes were made. The exploratory control implementation was
+removed from the shipping API; `recenter`, `adjust` and `restore` are rejected.
+This is an **unresolved feasibility check**, not evidence that OpenVR controls
+cannot work. Concurrent use and the Frame driver's coordinate-system handling
+still need to be separated.
+
+The probe's original and last-read poses remain in the Frame's
+`~/.local/share/frame-control/vr/comfort.json` for investigation. This draft
+neither reads nor applies that baseline. Do not blindly replay it into a room
+that may have changed. No recenter test was reached in the later trial.
+
+Before adding controls, on an idle Frame:
+
+1. Establish current room and tracking state, and inspect the retained probe
+   evidence before considering any restoration.
+2. Prove seated and standing height/move operations in the Frame driver's
+   current coordinates, including delayed readback, coordinate rebasing and
+   recovery. Show that the physical safety boundary stays correct.
+3. Verify recenter independently, and test a full apply/restore cycle plus a
+   concurrent room-change refusal. Add a fake OpenVR test for those contracts.
+4. Check the apparent result in a seated and a standing app before exposing UI.
+
+**Documented:** seated and standing are tracking origins selected by an app;
+changing a seated origin cannot force every game to support seated play.
+
+**Inferred from the installed SteamVR defaults:** there is no generic snap-turn
+or locomotion-vignette setting. `dashboard.verticalOffsetCm_2` and
+`steamvr.panelMaskVignette` affect panels, not the player's height or game
+locomotion. The app gives game-setting hints for snap-turn, teleport movement
+and movement vignette instead of writing these unrelated settings.
+
+## Optional software
+
+**Verified 2026-09-28 (same build):** a read-only query of Steam's loaded
+`appStore.allApps` found none of these five apps on the Frame account. The query
+includes software, which the existing games-only library filter excludes.
+Steam's public app-details API listed only Desktop+ as free. No software was
+purchased, installed or launched during these ownership checks.
+
+| Utility | Local Frame status | Public evidence / optional source |
+|---|---|---|
+| OVR Advanced Settings (1009850) | **Untested**, not owned | Steam edition is paid. Developer's [free source and releases](https://github.com/OpenVR-Advanced-Settings/OpenVR-AdvancedSettings). No verified Frame result in this work. |
+| XSOverlay (1173510) | **Untested**, not owned | Supplied research attributes Proton support with tweaks to [Road to VR](https://www.roadtovr.com/valve-steam-frame-review/). This is a public report, not our verification. |
+| OVR Toolkit (1068820) | **Untested**, not owned | Same [public Frame report](https://www.roadtovr.com/valve-steam-frame-review/); no local verification. |
+| fpsVR (908520) | **Untested**, not owned | [Steam listing](https://store.steampowered.com/app/908520/). No Frame-specific result established in the supplied research. General PC VR reviews do not verify Frame support. |
+| Desktop+ (1494460) | **Untested**, free | [Developer source](https://github.com/elvissteinjr/DesktopPlus). No verified Frame result in this work. |
+
+**Documented (supplied research):** the XSOverlay/OVR Toolkit claims are kept as
+attributed leads. **Verified source check 2026-09-28:** fetching the linked
+review returned HTTP 200 and the expected review title, but neither utility name
+appeared in the fetched HTML or extracted text. The claims could not be
+corroborated from that page; this is not proof of incompatibility. They do not make those apps dependencies or mark them
+locally verified. No paid utility is auto-acquired. A server-side check blocks
+installation through the Steam endpoint if the paid utility is absent from the
+loaded Frame library; an empty/unavailable library fails closed. Desktop+ uses
+the existing free Steam install flow, which may need a license confirmation in
+the headset. None is advertised as known-good without local evidence.
+
+Compatibility reports reuse the existing `compat-db` storage and validation
+with `package: "steam:<appid>"`, rather than colliding with Android package IDs.
+The optional list shows the latest `works`, `issues` or `broken` report with its
+date, build and notes, separately from public sources and ownership. With no
+report the status stays **untested**. No shared database schema change or
+production deployment is needed; no reports were published by this work.
+
+## Validation and review
+
+166 unit tests and 8 website tests passed locally. The new fake-Frame cases
+passed in GitHub CI (Docker was unavailable locally). Desktop and phone-width
+preview checks passed. The two independent review attempts did not produce a
+verdict; [commands, real exit statuses and limitations](evidence/vr-utilities/review.md).

docs/vr-video.md

@@ -75,6 +75,34 @@ All test media were generated by us. No paid content or DRM was involved.
 
 ![Our Gaussian-splat stereo preview on the Frame](img/media-splat-proof.png)
 
+**Verified end to end, 2026-09-29** (same build; headset unworn): uploads
+through the HTTP API, the web UI and `scripts/push-vr-video.sh`, all played by
+the owned player. Our generated test files:
+
+| Case | Result |
+|---|---|
+| H.264 half-SBS 1920×1080 with AAC, theatre | 240/240 frames in 8.09 s; audio stream "Frame Control Media" in PulseAudio |
+| H.265 half-OU 1920×1080 | 180/180 frames in 6.03 s; red left eye, cyan right |
+| H.264 full-SBS 3840×1080, `stereo_mode=left_right` only | Detected from metadata; 150/150 frames in 5.03 s |
+| H.264 1280×720, explicit 2D | 150/150 frames in 5.02 s |
+| SBS PNG, OU JPEG (theatre) | Correct eye in each capture |
+| 3,000-Gaussian `.splat` | Rendered in about 5 s, then held until Stop |
+| 2D file on Auto, `_SBS_OU` file, HEIC, VP9 | Refused with the documented message |
+| Second Play while one runs | Refused: "Stop the current media…" |
+
+Stop always left the unit inactive, and no player process remained.
+
+**Standby (verified):** an unworn Frame turns its displays off a few seconds
+after it wakes. `SetOverlayRaw` then returns `RequestFailed` (23). The
+first run's movie died there. The player now drops frames while the headset
+is in standby, keeps the audio and its clock going, and resumes the picture
+when the headset wakes. The 8 s movie above dropped 40 frames and finished.
+Stills and the theatre surround are re-sent after waking. Five minutes
+without an accepted frame is reported as an error. Headset-view captures
+taken during standby show a flat dark frame, not our screen.
+
+![Media panel in Frame Control while a photo plays on the Frame](img/media-ui-panel.png)
+
 **Verified failed route:** GStreamer 1.24.2's `playbin` selected
 `v4l2h264dec`, delivered the first RGBA sample and then segfaulted (exit 139)
 in the basic appsink probe and the OpenVR probe. We do not ship that route.

frame/android/app-data.py

@@ -0,0 +1,168 @@
+"""Private-data archives, run under podman unshare on the Frame. Stdlib only."""
+import contextlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import sys
+import tarfile
+import tempfile
+import time
+
+MAX_BYTES = 20 * 1024 ** 3
+MAX_FILES = 100000
+MAX_MANIFEST = 1024 * 1024
+
+
+def inspect_archive(path, package, instance):
+    names, total, manifest = set(), 0, None
+    with tarfile.open(path, 'r:gz') as archive:
+        for member in archive:
+            name = member.name
+            parts = PurePosixPath(name).parts
+            if (not parts or name.startswith('/') or '..' in parts or
+                    name != '/'.join(parts) or name in names or '\\' in name):
+                raise ValueError('unsafe or duplicate archive path')
+            if name == 'data' and not member.isdir():
+                raise ValueError('data root must be a directory')
+            names.add(name)
+            if len(names) > MAX_FILES or not (member.isdir() or member.isfile()):
+                raise ValueError('archive has too many files, links or special files')
+            if member.uid < 0 or member.gid < 0 or member.uid > 65535 or member.gid > 65535:
+                raise ValueError('archive owner outside Android user namespace')
+            total += member.size
+            if total > MAX_BYTES:
+                raise ValueError('archive exceeds 20 GiB')
+            if name == 'manifest.json' and member.isfile() and member.size <= MAX_MANIFEST:
+                manifest = json.load(archive.extractfile(member))
+            elif parts[0] != 'data':
+                raise ValueError('unexpected archive member')
+        if (not isinstance(manifest, dict) or manifest.get('format') != 1 or
+                manifest.get('package') != package or manifest.get('instance') != instance or
+                'data' not in names):
+            raise ValueError('backup does not match this package and instance')
+    return {'files': len(names) - 1, 'bytes': total, 'package': package, 'instance': instance,
+            'skipped_links': manifest.get('skipped_link_count', 0)}
+
+
+def backup(root, package, instance, output):
+    import io
+    source = root / package
+    if source.is_symlink() or not source.is_dir():
+        raise ValueError('private app data does not exist or is a symlink')
+    count, total, links, skipped = 0, 0, [], 0
+
+    def checked(member):
+        nonlocal count, total, skipped
+        if member.issym():  # never followed or restored; listed in the manifest instead
+            skipped += 1
+            if len(links) < 1000:
+                links.append({'path': member.name[:512], 'target': member.linkname[:256]})
+            return None
+        if member.islnk():  # a second name for a file already archived: store its content again
+            member.type, member.linkname = tarfile.REGTYPE, ''
+            member.size = os.lstat(str(source / member.name[len('data/'):])).st_size
+        count += 1
+        total += member.size
+        if not (member.isdir() or member.isfile()) or count > MAX_FILES or total > MAX_BYTES:
+            raise ValueError('private data contains special files or exceeds backup limits')
+        return member
+
+    with tarfile.open(fileobj=output, mode='w|gz', dereference=False) as archive:
+        archive.add(str(source), arcname='data', filter=checked)
+        # Written last so that it can list what was skipped.
+        manifest = json.dumps({'format': 1, 'package': package, 'instance': instance,
+                               'skipped_links': links, 'skipped_link_count': skipped}).encode()
+        member = tarfile.TarInfo('manifest.json')
+        member.size, member.mode = len(manifest), 0o600
+        archive.addfile(member, io.BytesIO(manifest))
+
+
+def restore(root, package, instance, input_stream):
+    source = root / package
+    if source.is_symlink() or not source.is_dir():
+        raise ValueError('private app data does not exist or is a symlink')
+    with tempfile.TemporaryDirectory(prefix='.frame-restore-', dir=str(root)) as work:
+        work = Path(work)
+        archive_path = work / 'backup.tar.gz'
+        with archive_path.open('wb') as output:
+            size = 0
+            while True:
+                chunk = input_stream.read(1024 * 1024)
+                if not chunk:
+                    break
+                size += len(chunk)
+                if size > MAX_BYTES:
+                    raise ValueError('compressed backup exceeds 20 GiB')
+                output.write(chunk)
+        result = inspect_archive(archive_path, package, instance)
+        stage = work / 'stage'
+        stage.mkdir(mode=0o700)
+        with tarfile.open(archive_path, 'r:gz') as archive:
+            directories = []
+            for member in archive:
+                if member.name == 'manifest.json':
+                    continue
+                target = stage / member.name
+                if member.isdir():
+                    target.mkdir(parents=True, exist_ok=True)
+                    directories.append((target, member))
+                else:
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    with archive.extractfile(member) as src, target.open('xb') as dst:
+                        shutil.copyfileobj(src, dst, 1024 * 1024)
+                    apply_metadata(target, member)
+            for target, member in reversed(directories):
+                apply_metadata(target, member)
+        with package_lock(root, package):  # another restore of this package must not delete our copy
+            previous = root / ('.' + package + '.before-restore-' + str(time.time_ns()))
+            source.rename(previous)
+            try:
+                (stage / 'data').rename(source)
+            except BaseException:
+                previous.rename(source)
+                raise
+            # Keep only the newest pre-restore copy of this package's data.
+            for old in root.glob('.' + package + '.before-restore-*'):
+                if old != previous and not old.is_symlink():
+                    shutil.rmtree(str(old), ignore_errors=True)
+        result['previous'] = str(previous)
+        return result
+
+
+@contextlib.contextmanager
+def package_lock(root, package):
+    import fcntl
+    fd = os.open(str(root / ('.' + package + '.restore.lock')), os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        os.close(fd)  # releases the lock
+
+
+def apply_metadata(path, member):
+    os.chown(str(path), member.uid, member.gid)
+    os.chmod(str(path), member.mode & 0o777)
+    os.utime(str(path), (member.mtime, member.mtime))
+
+
+def main():
+    action, package, instance = sys.argv[1:]
+    instance = int(instance)
+    root = Path.home() / '.local/share/Steam/steamapps/compatdata' / str(instance) / 'internal'
+    if root.is_symlink() or root.resolve() != root.absolute():
+        raise ValueError('private-data directory traverses a symlink')
+    if action == 'backup':
+        backup(root, package, instance, sys.stdout.buffer)
+    elif action == 'restore':
+        print(json.dumps(restore(root, package, instance, sys.stdin.buffer)))
+    else:
+        raise ValueError('unknown app-data action')
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (OSError, ValueError, tarfile.TarError) as error:
+        sys.exit(str(error))

frame/android/lepton-app.sh

@@ -19,6 +19,25 @@ done
 
 # A number that isn't a real Steam app; it names this app's Lepton context.
 export SteamAppId="$(cat "$DIR/instance.id")"
+[[ "$SteamAppId" =~ ^[0-9]+$ ]] || { echo "invalid instance.id" >&2; exit 1; }
+# Keep the stable Lepton context, but identify the Android VR client as its
+# actual Steam shortcut. Lepton applies LEPTON_ENV_* after its own passthrough.
+if [[ -f "$DIR/shortcut.id" ]]; then
+  shortcut="$(cat "$DIR/shortcut.id")"
+  [[ "$shortcut" =~ ^[0-9]+$ ]] || { echo "invalid shortcut.id" >&2; exit 1; }
+  export LEPTON_ENV_SteamAppId="$shortcut"
+fi
+exec 9>"$DIR/launch.lock"
+flock -n 9 || { echo "Android app is already running" >&2; exit 1; }
+CONTAINER="lepton-steamlaunch-$SteamAppId"
+# Holding the lock means no launcher owns a running container: it was orphaned
+# (this script SIGKILLed), so stop it rather than refuse every later Play. The
+# name is this app's alone. A Lepton host process whose launcher was killed
+# before it made the container may linger briefly; nothing else is killed.
+if [[ "$(podman inspect --format '{{.State.Running}}' "$CONTAINER" 2>/dev/null || true)" == true ]]; then
+  echo "Stopping orphaned $CONTAINER" >&2
+  podman stop -t 5 "$CONTAINER" >/dev/null 2>&1 || true
+fi
 export STEAM_COMPAT_INSTALL_PATH="$DIR"
 # Must be under ~/.local/share/Steam: only that tree is mounted in the container.
 export STEAM_COMPAT_DATA_PATH="$HOME/.local/share/Steam/steamapps/compatdata/$SteamAppId"
@@ -29,4 +48,29 @@ mkdir -p "$STEAM_COMPAT_DATA_PATH" "$STEAM_FOSSILIZE_DUMP_PATH"
 # Lepton's setpgid --foreground re-exec needs a terminal that Steam shortcuts
 # and SSH don't have; give it its own session instead.
 export IS_PARENT=true
-exec setsid --wait "$LEPTON" waitforexitandrun -- "$DIR/app.apk"
+# Keep this shell in Steam's process tree; setsid alone has no container cleanup.
+child=""
+cleanup() {
+  trap '' TERM INT HUP
+  if [[ -n "$child" ]]; then
+    kill -TERM -- "-$child" 2>/dev/null || true
+    kill -TERM "$child" 2>/dev/null || true
+  fi
+  podman stop -t 5 "$CONTAINER" >/dev/null 2>&1 || true
+  if [[ -n "$child" ]]; then
+    kill -KILL -- "-$child" 2>/dev/null || true
+    kill -KILL "$child" 2>/dev/null || true
+    wait "$child" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+trap 'exit 143' TERM
+trap 'exit 130' INT
+trap 'exit 129' HUP
+# 9>&-: the lock is this launcher's alone; Lepton's tree mustn't keep it held.
+setsid --wait "$LEPTON" waitforexitandrun -- "$DIR/app.apk" 9>&- &
+child=$!
+rc=0
+wait "$child" || rc=$?
+child=""
+exit "$rc"

frame/android/library_artwork.js

@@ -0,0 +1,146 @@
+// Runs in Steam's Chromium context: identical fonts/rendering from every host OS.
+async function renderLibraryArtwork(input) {
+  const sizes = {grid:[600,900], wide:[920,430], hero:[3840,1240], logo:[1280,480], icon:[256,256]};
+  const label = String(input.label || 'Untitled').trim().slice(0,180);
+  const font = '"Motiva Sans", "Noto Sans", Arial, sans-serif';
+  await document.fonts.load(`800 120px ${font}`, label);
+  const images = {}, warnings = [];
+  for (const [slot, item] of Object.entries(input.images || {})) {
+    try {
+      const img = new Image();
+      img.src = `data:image/${item[0]};base64,${item[1]}`;
+      await img.decode();
+      if (!img.width || !img.height || img.width*img.height > 16777216) throw Error('dimensions');
+      images[slot] = img;
+    } catch (_) { warnings.push(`${slot} could not be decoded; generated art used`); }
+  }
+  let icon = images.icon;
+  if (icon) {
+    // Remove only a near-black matte connected to the outside of an opaque icon.
+    const cut=document.createElement('canvas');cut.width=icon.width;cut.height=icon.height;
+    const c=cut.getContext('2d');c.drawImage(icon,0,0);
+    const pixels=c.getImageData(0,0,cut.width,cut.height), d=pixels.data, w=cut.width,h=cut.height;
+    const corners=[0,w-1,(h-1)*w,h*w-1];
+    if(corners.every(i=>d[i*4+3]>250 && Math.max(d[i*4],d[i*4+1],d[i*4+2])<24)) {
+      const seen=new Uint8Array(w*h), queue=corners.slice();
+      for(let q=0;q<queue.length;q++) {
+        const i=queue[q];if(seen[i])continue;seen[i]=1;
+        if(Math.max(d[i*4],d[i*4+1],d[i*4+2])>24)continue;
+        d[i*4+3]=0;
+        if(i%w)queue.push(i-1);if(i%w<w-1)queue.push(i+1);
+        if(i>=w)queue.push(i-w);if(i<w*(h-1))queue.push(i+w);
+      }
+      c.putImageData(pixels,0,0);icon=cut;
+    }
+  }
+  // Quantized, saturated dominant colors avoid white/black icon margins.
+  let colors = [[48,91,137], [24,36,63]];
+  if (icon) {
+    const sample = document.createElement('canvas'); sample.width=48; sample.height=48;
+    const s=sample.getContext('2d'); s.drawImage(icon,0,0,48,48);
+    const data=s.getImageData(0,0,48,48).data, bins=new Map();
+    for (let i=0;i<data.length;i+=4) {
+      const rgb=[data[i],data[i+1],data[i+2]], hi=Math.max(...rgb), lo=Math.min(...rgb);
+      if (data[i+3]<150 || hi<45 || lo>220 || hi-lo<25) continue;
+      const key=rgb.map(v=>Math.round(v/32)*32).join(',');
+      bins.set(key,(bins.get(key)||0)+1);
+    }
+    const ranked=[...bins].sort((a,b)=>b[1]-a[1]);
+    if (ranked.length) {
+      colors[0]=ranked[0][0].split(',').map(Number);
+      colors[1]=(ranked.find(([key])=>key.split(',').reduce((n,v,i)=>n+Math.abs(Number(v)-colors[0][i]),0)>170)||ranked[0])[0].split(',').map(Number);
+    }
+  }
+  // Preserve hue while lifting muted icon colors into a richer background palette.
+  colors=colors.map(c=>{const low=Math.min(...c),range=Math.max(...c)-low||1;
+    return c.map(v=>45+(v-low)/range*165);});
+  const rgb=(c,a=1)=>`rgba(${c.map(v=>Math.min(255,Math.round(v))).join(',')},${a})`;
+  function image(ctx,img,x,y,w,h,cover=false) {
+    const scale=cover?Math.max(w/img.width,h/img.height):Math.min(w/img.width,h/img.height);
+    const dw=img.width*scale,dh=img.height*scale;
+    ctx.save(); ctx.beginPath(); ctx.rect(x,y,w,h); ctx.clip();
+    ctx.drawImage(img,x+(w-dw)/2,y+(h-dh)/2,dw,dh); ctx.restore();
+  }
+  function title(ctx,w,h,top,bottom,maxSize) {
+    let lines=[],size=maxSize;
+    const maxWidth=w*.84;
+    for (;size>=18;size-=2) {
+      ctx.font=`800 ${size}px ${font}`;
+      lines=[]; let line='';
+      for (const word of label.split(/\s+/)) {
+        const next=line?line+' '+word:word;
+        if (line && ctx.measureText(next).width>maxWidth) {lines.push(line);line=word;} else line=next;
+      }
+      lines.push(line);
+      if (lines.length*size*1.08<=bottom-top && lines.every(l=>ctx.measureText(l).width<=maxWidth)) break;
+    }
+    if(lines.length===2) {
+      const words=lines[0].split(' ');
+      if(words.length>1) {
+        const first=words.slice(0,-1).join(' '), second=words.slice(-1)[0]+' '+lines[1];
+        if(ctx.measureText(second).width<=maxWidth &&
+           Math.abs(ctx.measureText(first).width-ctx.measureText(second).width)<
+           Math.abs(ctx.measureText(lines[0]).width-ctx.measureText(lines[1]).width)) lines=[first,second];
+      }
+    }
+    // A long unbroken label is still fitted, including scripts without spaces.
+    ctx.textAlign='center'; ctx.textBaseline='middle'; ctx.fillStyle='#fff';
+    ctx.shadowColor='rgba(0,0,0,.45)'; ctx.shadowBlur=size*.28; ctx.shadowOffsetY=size*.06;
+    let y=top+(bottom-top-lines.length*size*1.08)/2+size*.54;
+    for (const line of lines) {ctx.fillText(line,w/2,y,maxWidth); y+=size*1.08;}
+    ctx.shadowBlur=0; ctx.shadowOffsetY=0;
+  }
+  const result={};
+  for (const [slot,[w,h]] of Object.entries(sizes)) {
+    const canvas=document.createElement('canvas'); canvas.width=w; canvas.height=h;
+    const ctx=canvas.getContext('2d'); ctx.imageSmoothingQuality='high';
+    const direct=images[slot];
+    const feature=images.feature_graphic||images.banner;
+    const scene=direct || ((slot==='hero'||slot==='wide') && (feature||images.screenshot));
+    if (scene) {
+      if (slot==='logo'||slot==='icon') image(ctx,scene,0,0,w,h);
+      else image(ctx,scene,0,0,w,h,true);
+    } else if (slot==='logo') {
+      title(ctx,w,h,h*.08,h*.92,150);
+    } else {
+      const gradient=ctx.createLinearGradient(0,0,w,h);
+      gradient.addColorStop(0,rgb(colors[0].map(v=>v*.68)));
+      gradient.addColorStop(.6,rgb(colors[1].map(v=>v*.32)));
+      gradient.addColorStop(1,'#080c16'); ctx.fillStyle=gradient;ctx.fillRect(0,0,w,h);
+      if (icon) {
+        ctx.save();ctx.globalAlpha=.16;ctx.filter=`blur(${Math.round(w*.055)}px) saturate(1.4)`;
+        image(ctx,icon,-w*.15,-h*.15,w*1.3,h*1.3,true);ctx.restore();
+      }
+      const glow=ctx.createRadialGradient(w*.5,h*.32,0,w*.5,h*.32,w*.8);
+      glow.addColorStop(0,rgb(colors[0],.27));glow.addColorStop(1,rgb(colors[1],0));
+      ctx.fillStyle=glow;ctx.fillRect(0,0,w,h);
+      const vignette=ctx.createLinearGradient(0,h*.25,0,h);
+      vignette.addColorStop(0,'rgba(0,0,0,0)');vignette.addColorStop(1,'rgba(0,0,0,.56)');
+      ctx.fillStyle=vignette;ctx.fillRect(0,0,w,h);
+      const box=slot==='grid'?[w*.12,h*.14,w*.76,w*.76]:
+                slot==='wide'?[w*.36,h*.06,w*.28,h*.59]:
+                slot==='hero'?[w*.365,h*.12,w*.27,h*.78]:[w*.08,h*.08,w*.84,h*.84];
+      if (icon) {
+        ctx.save();ctx.shadowColor='rgba(0,0,0,.65)';ctx.shadowBlur=Math.min(w,h)*.055;
+        ctx.shadowOffsetY=Math.min(w,h)*.022;
+        // Opaque square icons read as deliberate app tiles, not pasted rectangles.
+        const [x,y,bw,bh]=box, side=Math.min(bw,bh);
+        if(slot!=='hero' && icon===images.icon) {
+          ctx.beginPath();ctx.roundRect(x+(bw-side)/2,y+(bh-side)/2,side,side,side*.14);ctx.clip();
+        }
+        image(ctx,icon,...box);ctx.restore();
+      } else if (slot !== 'hero') {
+        // A typographic monogram when the APK contains no usable image.
+        ctx.font=`800 ${Math.min(w,h)*.48}px ${font}`;ctx.fillStyle='rgba(255,255,255,.94)';
+        ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText([...label][0]||'A',w/2,h*.38);
+      }
+      if (slot==='grid') title(ctx,w,h,h*.7,h*.93,66);
+      if (slot==='wide') title(ctx,w,h,h*.69,h*.92,52);
+      // Hero intentionally has no title: Steam overlays the transparent logo.
+    }
+    // Photos as PNG can pass Steam's 12 MiB limit at hero size; the logo keeps its transparency.
+    const jpeg=scene && slot!=='logo' && slot!=='icon';
+    result[slot]=[jpeg?'jpg':'png', canvas.toDataURL(jpeg?'image/jpeg':'image/png',.9).split(',')[1]];
+  }
+  return {images:result,warnings,font};
+}

frame/android/steam_shortcuts.py

@@ -5,9 +5,11 @@ Python stdlib only; the Mac runs it with `ssh frame python3 - <args> < this`.
 
   steam_shortcuts.py add NAME EXE START_DIR [ICON]  -> prints the shortcut app id
   steam_shortcuts.py list                           -> JSON [{appid, name, exe}]
+  steam_shortcuts.py configure APPID NAME EXE START_DIR ICON VR ARTWORK_JSON
+  steam_shortcuts.py stop APPID
   steam_shortcuts.py remove APPID
 """
-import base64, json, os, socket, struct, sys, urllib.request
+import base64, glob, json, os, re, socket, struct, sys, urllib.request
 
 DEVTOOLS = 'http://127.0.0.1:8080/json'
 
@@ -22,10 +24,10 @@ def target_ws():
 class WS:
     """Just enough RFC 6455 for one CDP request/response on loopback."""
 
-    def __init__(self, url):
+    def __init__(self, url, timeout=20):
         host_port, path = url[len('ws://'):].split('/', 1)
         host, port = host_port.split(':')
-        self.s = socket.create_connection((host, int(port)), timeout=20)
+        self.s = socket.create_connection((host, int(port)), timeout=timeout)
         key = base64.b64encode(os.urandom(16)).decode()
         self.s.sendall((f'GET /{path} HTTP/1.1\r\nHost: {host_port}\r\nUpgrade: websocket\r\n'
                         f'Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\n'
@@ -69,8 +71,8 @@ class WS:
                 return msg.decode()
 
 
-def evaluate(js):
-    ws = WS(target_ws())
+def evaluate(js, timeout=20):
+    ws = WS(target_ws(), timeout)
     ws.send(json.dumps({'id': 1, 'method': 'Runtime.evaluate', 'params': {
         'expression': js, 'awaitPromise': True, 'returnByValue': True}}))
     while True:
@@ -83,6 +85,206 @@ def evaluate(js):
     return res.get('result', {}).get('value')
 
 
+# Steam's ELibraryAssetType (Capsule, Hero, Logo, Header, Icon).
+ASSETS = {'grid': 0, 'hero': 1, 'logo': 2, 'wide': 3, 'icon': 4}
+
+
+def collections_js(appid, wanted=()):
+    wanted = list(wanted)
+    return f'''async function syncCollections() {{
+      const wanted = {json.dumps(wanted)};
+      if (typeof collectionStore === "undefined" ||
+          typeof collectionStore.GetUserCollectionsByName !== "function" ||
+          typeof collectionStore.NewUnsavedCollection !== "function" ||
+          typeof collectionStore.SaveCollection !== "function")
+        return ["Steam collections API unavailable"];
+      const app = {{appid: {appid}}};
+      const warnings = [];
+      for (const name of ["Android", "Android VR", "Sideloaded"]) {{
+        const matches = collectionStore.GetUserCollectionsByName(name);
+        let collection = matches.find(c => !c.bIsDynamic && c.bAllowsDragAndDrop);
+        if (wanted.includes(name)) {{
+          if (!collection && matches.length) {{
+            warnings.push(name + " is an existing dynamic or read-only collection");
+            continue;
+          }}
+          if (!collection) {{
+            collection = collectionStore.NewUnsavedCollection(name, undefined, [app]);
+          }} else {{
+            collection.AsDragDropCollection().AddApps([app]);
+          }}
+          await collectionStore.SaveCollection(collection);
+        }} else if (collection) {{
+          collection.AsDragDropCollection().RemoveApps([app]);
+          await collectionStore.SaveCollection(collection);
+        }}
+      }}
+      return warnings;
+    }}'''
+
+
+
+def notes_js(name, details):
+    filename = 'notes_shortcut_' + re.sub(r'[!-/:-@ \[\\\]\^`]', '_', name.strip())
+    content = '\n'.join(str(details[k]) for k in ('package', 'version', 'source') if details.get(k))
+    return f'''if (SteamClient.GameNotes && typeof SteamClient.GameNotes.GetNotes === "function" &&
+                   typeof SteamClient.GameNotes.SaveNotes === "function") {{
+      try {{
+        const file = {json.dumps(filename)};
+        const previous = await SteamClient.GameNotes.GetNotes(file, file + "_images/");
+        if (previous.result !== 1 && previous.result !== 9) throw Error("read " + previous.result);
+        const data = previous.result === 1 ? JSON.parse(previous.notes) : {{notes: [], shortcut_name: {json.dumps(name)}}};
+        if (!Array.isArray(data.notes)) throw Error("unexpected notes format");
+        const id = "frame-control-library", now = Math.floor(Date.now()/1000);
+        const old = data.notes.find(n => n.id === id);
+        const note = {{id, shortcut_name: {json.dumps(name)}, title: "Installation details",
+                      content: {json.dumps(content)}, ordinal: old ? old.ordinal : data.notes.length,
+                      time_created: old ? old.time_created : now, time_modified: now}};
+        data.notes = data.notes.filter(n => n.id !== id).concat([note]);
+        const result = await SteamClient.GameNotes.SaveNotes(file, JSON.stringify(data));
+        if (result !== 1) throw Error("save " + result);
+      }} catch (e) {{ warnings.push("Steam notes: " + String(e)); }}
+    }}'''
+
+
+MAX_ART = 12 * 1024 * 1024  # Steam's custom artwork limit per slot
+
+
+def render(plan):
+    with open(plan) as f:
+        source = json.load(f)
+    images = {}
+    for slot, path in source['images'].items():
+        ext = os.path.splitext(path)[1][1:]
+        with open(path, 'rb') as f:
+            data = f.read(MAX_ART + 1)
+        if len(data) > MAX_ART:
+            raise ValueError('source artwork too large')
+        images[slot] = [ext, base64.b64encode(data).decode()]
+    renderer = globals().get('ART_RENDERER')
+    if renderer is None:
+        with open(os.path.join(os.path.dirname(__file__), 'library_artwork.js')) as f:
+            renderer = f.read()
+    try:
+        return _render(plan, renderer, source['label'], images)
+    except (ValueError, OSError, EOFError, SystemExit) as e:
+        # Generated art from the icon alone always fits; a photo that didn't must not fail the install.
+        result = _render(plan, renderer, source['label'], {k: v for k, v in images.items() if k == 'icon'})
+        result['warnings'].insert(0, 'Source artwork could not be rendered (' + str(e)[:120] + '); generated art used')
+        return result
+
+
+def _render(plan, renderer, label, images):
+    # A 4K photo takes seconds to decode and encode on the Frame; allow well beyond that.
+    result = evaluate(renderer + '\nrenderLibraryArtwork(' + json.dumps({'label': label, 'images': images}) + ')',
+                      timeout=75)
+    if not isinstance(result, dict) or set(result.get('images', {})) != set(ASSETS):
+        raise ValueError('incomplete artwork render')
+    paths = {}
+    for slot, (ext, encoded) in result['images'].items():
+        data = base64.b64decode(encoded, validate=True)
+        signature = {'png': b'\x89PNG\r\n\x1a\n', 'jpg': b'\xff\xd8\xff'}.get(ext)
+        if not signature or not data.startswith(signature) or len(data) > MAX_ART:
+            raise ValueError(slot + ' render is ' + str(len(data)) + ' bytes of ' + str(ext))
+        paths[slot] = os.path.join(os.path.dirname(plan), slot + '.' + ext)
+        with open(paths[slot] + '.tmp', 'wb') as f:
+            f.write(data)
+    for slot, path in paths.items():
+        os.replace(path + '.tmp', path)
+        for stale in ('png', 'jpg'):
+            other = os.path.join(os.path.dirname(plan), slot + '.' + stale)
+            if other != path and os.path.exists(other):
+                os.remove(other)
+    return {'paths': paths, 'warnings': list(result.get('warnings', []))}
+
+
+# Steam's own file for each custom-art type in userdata/*/config/grid/.
+GRID_FILES = {0: 'p', 1: '_hero', 2: '_logo', 3: ''}
+
+
+def custom_art(appid):
+    """The custom-art types this shortcut already has in Steam, for any local user."""
+    found = set()
+    for kind, suffix in GRID_FILES.items():
+        pattern = os.path.expanduser(f'~/.local/share/Steam/userdata/*/config/grid/{int(appid)}{suffix}.*')
+        if any(os.path.splitext(p)[1].lower() in ('.png', '.jpg', '.jpeg') for p in glob.glob(pattern)):
+            found.add(kind)
+    return found
+
+
+def configure(appid, name, exe, start_dir, icon, vr, artwork, options=None):
+    """options: category, details, fill_only (only empty slots and a missing icon; name and flags untouched)."""
+    options = options or {}
+    category = options.get('category', 'Android')
+    fill = bool(options.get('fill_only'))
+    existing = custom_art(appid) if fill else set()
+    if set(artwork) != set(ASSETS):
+        raise ValueError('all five Steam artwork slots are required')
+    images = []
+    for slot, path in artwork.items():
+        if slot not in ASSETS:
+            raise ValueError('unknown artwork slot')
+        ext = os.path.splitext(path)[1][1:]
+        if ext not in ('png', 'jpg'):
+            raise ValueError('artwork must be PNG or JPEG')
+        with open(path, 'rb') as f:
+            data = f.read(MAX_ART + 1)
+        if len(data) > MAX_ART:
+            raise ValueError('artwork is too large')
+        # Frame's custom-art API maps type 4 to Header; use SetShortcutIcon.
+        if slot != 'icon' and ASSETS[slot] not in existing:
+            images.append([ASSETS[slot], ext, base64.b64encode(data).decode()])
+    return evaluate(f'''(async () => {{
+      const id = {int(appid)}, warnings = [], fill = {json.dumps(fill)};
+      const overview = appStore.GetAppOverviewByAppID(id);
+      if (!fill) {{
+        SteamClient.Apps.SetShortcutName(id, {json.dumps(name)});
+        if ({json.dumps(exe)}) SteamClient.Apps.SetShortcutExe(id, {json.dumps(exe)});
+        if ({json.dumps(start_dir)}) SteamClient.Apps.SetShortcutStartDir(id, {json.dumps(start_dir)});
+        if (typeof SteamClient.Apps.SetShortcutSortAs === "function")
+          SteamClient.Apps.SetShortcutSortAs(id, {json.dumps(name)});
+      }}
+      if (!fill || !(overview && overview.icon_data)) SteamClient.Apps.SetShortcutIcon(id, {json.dumps(icon)});
+      // null (devkit titles) or filling gaps: leave the VR flag as Steam has it.
+      if ({json.dumps(vr)} !== null && !fill) {{
+        if (typeof SteamClient.Apps.SetShortcutIsVR === "function")
+          SteamClient.Apps.SetShortcutIsVR(id, {json.dumps(vr)});
+        else warnings.push("Steam VR shortcut flag API unavailable");
+      }}
+      if (typeof SteamClient.Apps.SetCustomArtworkForApp === "function") {{
+        for (const [type, ext, data] of {json.dumps(images)}) {{
+          // Steam keeps a slot's PNG and JPEG side by side; clear it so a stale one can't win.
+          if (!fill && typeof SteamClient.Apps.ClearCustomArtworkForApp === "function")
+            try {{ await SteamClient.Apps.ClearCustomArtworkForApp(id, type); }} catch (e) {{}}
+          await SteamClient.Apps.SetCustomArtworkForApp(id, data, ext, type);
+        }}
+      }} else throw new Error("Steam artwork API unavailable; installation is incomplete");
+      {collections_js(int(appid), [category] + (['Android VR'] if vr and category == 'Android' else []))}
+      try {{ warnings.push(...await syncCollections()); }}
+      catch (e) {{ warnings.push("Steam collections: " + String(e)); }}
+      {notes_js(name, options.get('details', {}))}
+      return {{warnings}};
+    }})()''', timeout=60)
+
+
+def remove(appid):
+    # Collections and artwork are tidy-up: only a missing RemoveShortcut may fail the removal.
+    return evaluate(f'''(async () => {{
+      const id = {int(appid)}, warnings = [];
+      {collections_js(int(appid))}
+      try {{ warnings.push(...await syncCollections()); }}
+      catch (e) {{ warnings.push("Steam collections: " + String(e)); }}
+      if (typeof SteamClient.Apps.ClearCustomArtworkForApp === "function") {{
+        for (const type of [0, 1, 2, 3]) {{
+          try {{ await SteamClient.Apps.ClearCustomArtworkForApp(id, type); }}
+          catch (e) {{ warnings.push("Steam artwork " + type + ": " + String(e)); }}
+        }}
+      }} else warnings.push("Steam artwork removal API unavailable");
+      SteamClient.Apps.RemoveShortcut(id);
+      return {{warnings}};
+    }})()''')
+
+
 def main():
     cmd, args = sys.argv[1], sys.argv[2:]
     if cmd == 'add':
@@ -97,12 +299,30 @@ def main():
         }})()'''
         print(evaluate(js))
     elif cmd == 'list':
-        js = '''(() => appStore.allApps.filter(a => a.app_type === 1073741824)
-                  .map(a => ({appid: a.appid, name: a.display_name})))()'''
+        # Overviews carry no exe or devkit id (checked 2026-09-28); app details do, once registered.
+        js = '''(async () => Promise.all(appStore.allApps.filter(a => a.app_type === 1073741824).map(async a => {
+          let d = typeof appDetailsStore !== "undefined" && appDetailsStore.GetAppDetails(a.appid);
+          if (!d && typeof SteamClient.Apps.RegisterForAppDetails === "function") d = await new Promise(ok => {
+            let reg;
+            const timer = setTimeout(() => { if (reg) reg.unregister(); ok(null); }, 3000);
+            reg = SteamClient.Apps.RegisterForAppDetails(a.appid, x => {
+              clearTimeout(timer); setTimeout(() => reg && reg.unregister()); ok(x); });
+          });
+          return {appid: a.appid, name: a.display_name, devkit_gameid: a.devkit_gameid,
+                  exe: d ? d.strShortcutExe || "" : "", start_dir: d ? d.strShortcutStartDir || "" : ""};
+        })))()'''
         print(json.dumps(evaluate(js)))
+    elif cmd == 'render':
+        print(json.dumps(render(args[0])))
+    elif cmd == 'configure':
+        vr = {'1': True, '0': False}.get(args[5])  # '' leaves Steam's VR flag alone
+        print(json.dumps(configure(int(args[0]), *args[1:5], vr, json.loads(args[6]),
+                                   json.loads(args[7]) if len(args) > 7 else None)))
+    elif cmd == 'stop':
+        evaluate(f'SteamClient.Apps.TerminateApp({json.dumps(str((int(args[0]) << 32) | 0x02000000))}, false)')
+        print('stopping')
     elif cmd == 'remove':
-        evaluate(f'SteamClient.Apps.RemoveShortcut({int(args[0])})')
-        print('removed')
+        print(json.dumps(remove(int(args[0]))))
     else:
         sys.exit(__doc__)
 

ios/FrameControl.xcodeproj/project.pbxproj

@@ -17,6 +17,7 @@
 		78427FC66780623F31E7501E /* FrameControlApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 93C8E0D7C3F4F628941B3D5A /* FrameControlApp.swift */; };
 		84423CB45629465420180A64 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 8F2CB550FC81C01E6BDD5A71 /* Assets.xcassets */; };
 		9657F7BC23E3352E5AB30777 /* SetupView.swift in Sources */ = {isa = PBXBuildFile; fileRef = DB544223FC60A59CC3E8EF5F /* SetupView.swift */; };
+		A0C5B00E257230A38DBD9E54 /* ComfortNotificationTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E81218B75FEEE47B8D8BAE20 /* ComfortNotificationTests.swift */; };
 		A8C7AED25A6280682FCE45DC /* Citadel in Frameworks */ = {isa = PBXBuildFile; productRef = 6BA549B6CC0A0CB847126456 /* Citadel */; };
 		DC043FB74BE2D23F3A5826BF /* FrameControlTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1740B691F9C25E5FB6F9EFC3 /* FrameControlTests.swift */; };
 		E6898C714A92D3979F73B6E1 /* FrameFinder.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2F288DF6636A417F0CA3A6CD /* FrameFinder.swift */; };
@@ -48,6 +49,7 @@
 		BF0FCA7117DA3ABA449B4EE0 /* InstallLink.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = InstallLink.swift; sourceTree = "<group>"; };
 		D6C4E6C28315CA8729FCAAEA /* WebShell.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WebShell.swift; sourceTree = "<group>"; };
 		DB544223FC60A59CC3E8EF5F /* SetupView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SetupView.swift; sourceTree = "<group>"; };
+		E81218B75FEEE47B8D8BAE20 /* ComfortNotificationTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ComfortNotificationTests.swift; sourceTree = "<group>"; };
 		EDC7BA8014DBC302D08FD397 /* HeadsetServer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = HeadsetServer.swift; sourceTree = "<group>"; };
 		F3E2F5607DD877272483D64E /* FrameControl.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = FrameControl.app; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
@@ -107,6 +109,7 @@
 		75A17B1C79C8C3C60FEABBA6 /* FrameControlTests */ = {
 			isa = PBXGroup;
 			children = (
+				E81218B75FEEE47B8D8BAE20 /* ComfortNotificationTests.swift */,
 				1740B691F9C25E5FB6F9EFC3 /* FrameControlTests.swift */,
 			);
 			path = FrameControlTests;
@@ -274,6 +277,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				A0C5B00E257230A38DBD9E54 /* ComfortNotificationTests.swift in Sources */,
 				DC043FB74BE2D23F3A5826BF /* FrameControlTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;

ios/FrameControl/Web/WebShell.swift

@@ -1,6 +1,7 @@
 import SwiftUI
 import UIKit
 import WebKit
+import UserNotifications
 
 /// The Frame Control page, served by the server on the headset, in a web view.
 /// window.frameApp (the same bridge the desktop app's preload.js provides) lets
@@ -48,6 +49,7 @@ struct WebShell: UIViewRepresentable {
       let installCb = null;
       window.frameApp = {
         platform: "ios",
+        notify: (message, request) => call("notify", { message, request }),
         readClipboard: () => call("readClipboard"),
         setUpConnection: () => call("setUpConnection"),
         open: (what) => call("open", what),
@@ -58,13 +60,31 @@ struct WebShell: UIViewRepresentable {
     })();
     """
 
-    final class Coordinator: NSObject, WKScriptMessageHandlerWithReply, WKNavigationDelegate, WKUIDelegate {
+    final class Coordinator: NSObject, WKScriptMessageHandlerWithReply, WKNavigationDelegate, WKUIDelegate, UNUserNotificationCenterDelegate {
         let model: AppModel
         weak var web: WKWebView?
         var loaded: URL?
         private var installReady = false
 
-        init(model: AppModel) { self.model = model }
+        init(model: AppModel) {
+            self.model = model
+            super.init()
+            UNUserNotificationCenter.current().delegate = self
+        }
+
+        func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification,
+                                    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
+            completionHandler([.banner, .sound, .list])
+        }
+
+        static func notificationContent(_ message: String) -> UNMutableNotificationContent? {
+            guard !message.isEmpty, message.count <= 500 else { return nil }
+            let content = UNMutableNotificationContent()
+            content.title = "Frame Control"
+            content.body = message
+            content.sound = .default
+            return content
+        }
 
         // MARK: bridge
 
@@ -76,6 +96,28 @@ struct WebShell: UIViewRepresentable {
             }
             let arg = body["arg"]
             switch name {
+            case "notify":
+                guard message.frameInfo.isMainFrame,
+                      message.frameInfo.securityOrigin.host == "127.0.0.1",
+                      let args = arg as? [String: Any], let text = args["message"] as? String,
+                      let content = Self.notificationContent(text) else {
+                    return replyHandler(nil, "Invalid notification")
+                }
+                let center = UNUserNotificationCenter.current()
+                let send: (Bool, Error?) -> Void = { allowed, error in
+                    guard allowed else {
+                        return replyHandler(nil, error?.localizedDescription ?? "Notifications are off. Enable them in iOS Settings.")
+                    }
+                    let request = UNNotificationRequest(identifier: UUID().uuidString, content: content, trigger: nil)
+                    center.add(request) { error in replyHandler(error == nil, error?.localizedDescription) }
+                }
+                if args["request"] as? Bool == true {
+                    center.requestAuthorization(options: [.alert, .sound], completionHandler: send)
+                } else {
+                    center.getNotificationSettings { settings in
+                        send(settings.authorizationStatus == .authorized || settings.authorizationStatus == .provisional, nil)
+                    }
+                }
             case "readClipboard":
                 replyHandler(UIPasteboard.general.string ?? "", nil)
             case "setUpConnection":

ios/FrameControlTests/ComfortNotificationTests.swift

@@ -0,0 +1,14 @@
+import XCTest
+import UserNotifications
+@testable import Frame_Control
+
+final class ComfortNotificationTests: XCTestCase {
+    func testNotificationContentAndBounds() {
+        let content = WebShell.Coordinator.notificationContent("Time for a break")
+        XCTAssertEqual(content?.title, "Frame Control")
+        XCTAssertEqual(content?.body, "Time for a break")
+        XCTAssertNotNil(content?.sound)
+        XCTAssertNil(WebShell.Coordinator.notificationContent(""))
+        XCTAssertNil(WebShell.Coordinator.notificationContent(String(repeating: "x", count: 501)))
+    }
+}

mac/frame-mac-view/Sources/CGVirtualDisplay.h

@@ -26,5 +26,3 @@
 - (instancetype)initWithDescriptor:(CGVirtualDisplayDescriptor *)descriptor;
 - (BOOL)applySettings:(CGVirtualDisplaySettings *)settings;
 @end
-
-#include "../../../desktop/controller.h"

mac/frame-mac-view/Sources/Controller.swift

@@ -1,45 +1,234 @@
-// Thin, serialized binding to the same controller used by the PC host.
-// Algorithm and bounded state live in desktop/controller.c.
+// Adapts each stream to its network, latency first. The viewer acknowledges
+// every frame as it arrives ("rx"); from those acks the controller knows how
+// long frames take to get through and how fast the link delivers them.
+//
+// - The gate: a new frame is sent only while the oldest unacknowledged one is
+//   younger than the path's usual round trip plus a little slack. So frames
+//   never queue up in SSH, TCP or the Wi-Fi driver; while the link is stuck
+//   the newest picture waits and goes out as soon as it moves again.
+// - The bitrate: when frames start queueing (the round trip grows) or the
+//   gate has to hold frames back, it drops to a bit under what the link
+//   actually delivered; once things are clear it probes up again slowly, never
+//   above the quality setting's bitrate (the ceiling).
+// - The tier: as the bitrate falls, fewer frames per second (60, 45, 30), then
+//   a smaller picture (75%, then 50% of the panel's pixels).
+// See docs/mac-in-headset.md ("Adapting to the network"). Thread-safe.
 import Foundation
 
 final class RateController {
+    struct Tier: Equatable {
+        let fps: Int
+        let scale: Double  // of the picture's long side
+    }
+
+    static let tiers = [Tier(fps: 60, scale: 1), Tier(fps: 45, scale: 1), Tier(fps: 30, scale: 1),
+                        Tier(fps: 30, scale: 0.75), Tier(fps: 30, scale: 0.5)]
+    /// A tier is used while the target bitrate is at least this share of the ceiling.
+    static let floors = [0.45, 0.28, 0.16, 0.08, 0]
     static let enabled = ProcessInfo.processInfo.environment["FRAME_MAC_VIEW_ADAPT"] != "0"
+
     let maxFps: Int
     private let lock = NSLock()
-    private let core: OpaquePointer
-    private var events: [[String: Any]] = []
-    init(maxFps: Int) {
-        self.maxFps = maxFps
-        core = fc_new(Int32(maxFps), Self.enabled ? 1 : 0)!
-    }
-    deinit { fc_free(core) }
+    private var ceiling = 0  // bits/s at full size and frame rate
+    private(set) var target = 0
+    private(set) var tier = 0
+    private var unacked: [(seq: UInt32, sent: Int64, bytes: Int)] = []
+    /// Round trips (send -> ack arrives here), for the baseline: the lowest
+    /// in the last 10 s is the path without any queue.
+    private var rtts: [(t: Int64, v: Int64)] = []
+    private var acked: [(t: Int64, bytes: Int)] = []  // the last second
+    private var sentLog: [(t: Int64, bytes: Int)] = []
+    private var captures: [Int64] = []  // the last second
+    private var frameBytes = 0  // average recent frame, kept while the gate holds everything back
+    private var held = 0  // frames the gate held back since the last update
+    private var lastSignal = false
+    private var sawAck = false
+    private var lastDecrease: Int64 = 0
+    private var lastIncrease: Int64 = 0
+    private var belowSince: Int64 = 0, aboveSince: Int64 = 0
+    /// What changed, for the timeline: (time, event).
+    private(set) var events: [(Int64, String)] = []
+
+    init(maxFps: Int) { self.maxFps = maxFps }
+
     private func locked<T>(_ f: () -> T) -> T { lock.lock(); defer { lock.unlock() }; return f() }
-    private func value(_ field: Int32) -> Int { Int(fc_value(core, field)) }
-    var target: Int { locked { value(0) } }
-    var tier: Int { locked { value(2) } }
-    var fps: Int { locked { value(3) } }
-    var scale: Double { locked { Double(value(4)) / 100 } }
-    var baseRtt: Int64 { locked { fc_value(core, 5) } }
-    func setCeiling(_ bps: Int) { locked { fc_ceiling(core, Int32(bps)) } }
-    func maySend(now: Int64, counts: Bool = true) -> Bool { locked { fc_gate(core, now, counts ? 1 : 0) != 0 } }
-    func captured(at t: Int64) { locked { fc_capture(core, t) } }
-    func sent(seq: UInt32, bytes: Int, at t: Int64) { locked { fc_sent(core, seq, Int32(bytes), t) } }
-    func acked(seq: UInt32, at t: Int64) -> Bool { locked { fc_ack(core, seq, t) != 0 } }
-    func update(now: Int64) -> Int? {
+
+    /// The quality setting's bitrate at full size; the first call also starts there.
+    func setCeiling(_ bps: Int) {
         locked {
-            let old = value(0), tier = value(2)
-            let result = Int(fc_update(core, now))
-            if value(0) < old || value(2) != tier {
-                events.append(["t": now, "e": "target \(value(0)) bit/s; tier \(value(2))"])
-                if events.count > 200 { events.removeFirst() }
-            }
-            return result == 0 ? nil : result
+            if target == 0 || target > bps { target = bps }
+            ceiling = bps
         }
     }
-    func state() -> [String: Any] {
-        locked { ["target": value(0), "ceiling": value(1), "tier": value(2), "fps": value(3),
-                  "scale": Double(value(4)) / 100, "baseRtt": Double(value(5)) / 1000,
-                  "inFlight": value(6), "slack": Double(value(7)) / 1000, "adapt": Self.enabled] }
+
+    var fps: Int { locked { fpsLocked } }
+    private var fpsLocked: Int { min(maxFps, RateController.tiers[tier].fps) }
+    var scale: Double { locked { RateController.tiers[tier].scale } }
+    var baseRtt: Int64 { locked { baseline() } }
+
+    private func baseline() -> Int64 { rtts.map(\.v).min() ?? 0 }
+
+    /// How late a frame may be before the gate holds the next one: one frame
+    /// interval, plus room for the jitter this link normally has (1.5 times
+    /// its recent spread), so ordinary Wi-Fi jitter doesn't cost frames but a
+    /// real queue does. Updated in update().
+    private var slack: Int64 = 40_000
+
+    /// Whether a frame may be sent now without queueing behind earlier ones.
+    /// `counts`: a held frame is a sign of congestion (not when merely
+    /// re-checking whether a held frame can go yet).
+    func maySend(now: Int64, counts: Bool = true) -> Bool {
+        locked {
+            guard RateController.enabled, sawAck else { return true }  // not heard from the viewer yet
+            // Unacknowledged for 2 s: gone with a reconnection, not in a queue.
+            unacked.removeAll { now - $0.sent > 2_000_000 }
+            guard let oldest = unacked.first else { return true }
+            // Age is what bounds latency. The count only stops a burst, and it
+            // allows a full round trip of frames, so a long but clear path
+            // (100 ms away) still gets every frame.
+            let interval = Int64(1_000_000 / max(1, fpsLocked))
+            let window = max(3, Int((baseline() + slack) / interval) + 1)
+            if unacked.count < window, now - oldest.sent <= baseline() + slack { return true }
+            if counts { held += 1 }
+            return false
+        }
     }
-    func eventList() -> [[String: Any]] { locked { events } }
+
+    /// A picture was captured (sent or not): with the frame sizes, what this
+    /// stream would send if the link allowed.
+    func captured(at t: Int64) {
+        locked {
+            captures.append(t)
+            if captures.count > 256 { captures.removeFirst(captures.count - 256) }
+        }
+    }
+
+    func sent(seq: UInt32, bytes: Int, at t: Int64) {
+        locked {
+            // Bounded even if the viewer never acknowledges (an old viewer, or
+            // the controller is off).
+            unacked.append((seq, t, bytes))
+            if unacked.count > 512 { unacked.removeFirst(unacked.count - 512) }
+            sentLog.append((t, bytes))
+            if sentLog.count > 1024 { sentLog.removeFirst(sentLog.count - 1024) }
+        }
+    }
+
+    /// The viewer has frame `seq`. Returns true if that may let a held frame go.
+    func acked(seq: UInt32, at now: Int64) -> Bool {
+        locked {
+            sawAck = true
+            guard let i = unacked.firstIndex(where: { $0.seq == seq }) else { return false }
+            let f = unacked[i]
+            unacked.removeSubrange(0...i)  // TCP delivers in order: earlier ones arrived too
+            rtts.append((now, now - f.sent))
+            acked.append((now, f.bytes))
+            return true
+        }
+    }
+
+    /// Called every 100 ms. Returns the new bitrate target, or nil if the
+    /// controller is off.
+    func update(now: Int64) -> Int? {
+        locked {
+            rtts.removeAll { now - $0.t > 10_000_000 }
+            acked.removeAll { now - $0.t > 500_000 }
+            sentLog.removeAll { now - $0.t > 500_000 }
+            unacked.removeAll { now - $0.sent > 2_000_000 }
+            captures.removeAll { now - $0 > 1_000_000 }
+            guard RateController.enabled, ceiling > 0 else { return nil }
+            let base = baseline()
+            let spread = rtts.filter { now - $0.t < 2_000_000 }.map(\.v).sorted()
+            let jitter = spread.isEmpty ? 0 : spread[spread.count * 9 / 10] - base
+            let interval = Int64(1_000_000 / max(1, fpsLocked))
+            slack = interval + min(max(jitter * 3 / 2, 25_000), 80_000)
+            let recent = rtts.filter { now - $0.t < 300_000 }.map(\.v).sorted()
+            let queueing = recent.isEmpty ? 0 : recent[recent.count / 2] - base
+            let oldestAge = unacked.first.map { now - $0.sent } ?? 0
+            let stuck = oldestAge > base + 100_000
+            let delivered = acked.reduce(0) { $0 + $1.bytes } * 16  // bits/s over the last half second
+            let sending = sentLog.reduce(0) { $0 + $1.bytes } * 16
+            // Demand: captures per second (up to the tier's rate) times the
+            // average frame. A test card or a mostly still window wants far
+            // less than its budget; when the link hiccups, cutting its bitrate
+            // can't help, and it would only look link-limited afterwards.
+            if !sentLog.isEmpty { frameBytes = sentLog.reduce(0) { $0 + $1.bytes } / sentLog.count }
+            let demand = min(captures.count, fpsLocked) * frameBytes * 8
+            // Delay alone isn't our queue: Wi-Fi jitters by itself. It only
+            // counts while this stream uses a good part of its budget (so its
+            // own data could be what's queueing). Frames the gate had to hold,
+            // or one stuck in flight, show demand the link isn't carrying
+            // whatever was sent (the gate itself keeps what's sent low).
+            let busy = sending >= target / 2
+            // Twice in a row (200 ms), so one late ack doesn't count.
+            let signal = (busy && queueing > 40_000) || held >= 3 || stuck
+            let congested = signal && lastSignal
+            lastSignal = signal
+            let heldNow = held
+            held = 0
+            let floorBps = 300_000
+            if congested, now - lastDecrease > 300_000 {
+                // Down to a bit under what got through: at least a fifth off, at
+                // most half (a stall delivers nothing, but the link is still there).
+                let measured = Int(Double(delivered) * 0.9)
+                var next = max(floorBps, min(target * 4 / 5, max(measured, target / 2)))
+                // App-limited (it wants about half its budget or less): never
+                // below twice what it wants, however many cuts in a row. The
+                // extra quarter is hysteresis, so frame sizes wobbling at the
+                // floor don't switch the protection off.
+                if demand > 0, demand * 2 <= target * 5 / 4 { next = max(next, min(target, demand * 2)) }
+                target = next
+                lastDecrease = now
+                events.append((now, "down to \(target / 1000) kbit/s: queue \(queueing / 1000) ms, held \(heldNow), "
+                                    + "oldest \(oldestAge / 1000) ms, base \(base / 1000) ms, sent \(sending / 1000) got \(delivered / 1000) "
+                                    + "wants \(demand / 1000)"))
+            } else if !congested, now - lastDecrease > 1_000_000, now - lastIncrease > 250_000, target < ceiling,
+                      sending > target * 6 / 10 || now - lastDecrease > 3_000_000 {
+                // Clear for a second and using what it has: probe up.
+                target = min(ceiling, Int(Double(target) * 1.1) + 50_000)
+                lastIncrease = now
+            }
+            // Fewer frames or pixels only help a stream that fills its budget;
+            // a small one (a still window, a test card) keeps its tier.
+            retier(now: now, linkLimited: sending >= target * 7 / 10)
+            if events.count > 200 { events.removeFirst(events.count - 200) }
+            return target
+        }
+    }
+
+    /// Steps down quickly, straight to the tier the bitrate supports, and back
+    /// up one tier at a time only when there's clearly room (hysteresis).
+    private func retier(now: Int64, linkLimited: Bool) {
+        let share = Double(target) / Double(max(ceiling, 1))
+        if tier < RateController.tiers.count - 1, share < RateController.floors[tier], linkLimited {
+            if belowSince == 0 { belowSince = now }
+            if now - belowSince > 500_000 {
+                tier = RateController.floors.firstIndex { share >= $0 } ?? RateController.tiers.count - 1
+                belowSince = 0
+                events.append((now, "tier \(tier)"))
+            }
+        } else {
+            belowSince = 0
+        }
+        if tier > 0, share > RateController.floors[tier - 1] * 1.25 {
+            if aboveSince == 0 { aboveSince = now }
+            if now - aboveSince > 2_000_000 {
+                tier -= 1
+                aboveSince = 0
+                events.append((now, "tier \(tier)"))
+            }
+        } else {
+            aboveSince = 0
+        }
+    }
+
+    func state() -> [String: Any] {
+        locked {
+            ["target": target, "ceiling": ceiling, "tier": tier, "fps": min(maxFps, RateController.tiers[tier].fps),
+             "scale": RateController.tiers[tier].scale, "baseRtt": Double(baseline()) / 1000,
+             "inFlight": unacked.count, "slack": Double(slack) / 1000, "adapt": RateController.enabled]
+        }
+    }
+
+    func eventList() -> [[String: Any]] { locked { events.map { ["t": $0.0, "e": $0.1] } } }
 }

mac/frame-mac-view/build.sh

@@ -5,10 +5,7 @@ set -eu
 here=$(cd "$(dirname "$0")" && pwd)
 out=${1:-$here/../bin/frame-mac-view}
 mkdir -p "$(dirname "$out")"
-obj=$(mktemp /tmp/frame-controller.XXXXXX)
-trap 'rm -f "$obj"' EXIT
-xcrun clang -O2 -target arm64-apple-macos14.0 -c "$here/../../desktop/controller.c" -o "$obj"
 xcrun swiftc -O -swift-version 5 -target arm64-apple-macos14.0 \
   -import-objc-header "$here/Sources/CGVirtualDisplay.h" \
-  -o "$out" "$here"/Sources/*.swift "$obj"
+  -o "$out" "$here"/Sources/*.swift
 echo "built $out"

scripts/connect.sh

@@ -101,10 +101,22 @@ make_key() {  # path type comment [extra ssh-keygen args]
   fi
 }
 
-# Checks each step itself: pair_with_devkit calls this from an `elif`, where set -e is off.
+# Takes the lock Frame Control uses to edit ~/.ssh/config (ui/frame_devices.py), so a
+# running app and this script never write over each other's change.
 write_config() {
+  local lockfd="" rc
+  zmodload zsh/system 2>/dev/null
+  touch "$CONFIG.frame-control.lock" 2>/dev/null
+  zsystem flock -t 30 -f lockfd "$CONFIG.frame-control.lock" 2>/dev/null || lockfd=""
+  write_config_locked; rc=$?
+  [[ -n "$lockfd" ]] && zsystem flock -u "$lockfd"
+  return $rc
+}
+
+# Checks each step itself: pair_with_devkit calls this from an `elif`, where set -e is off.
+write_config_locked() {
   touch "$CONFIG" && chmod 600 "$CONFIG" || return 1
-  local tmp
+  local tmp new="$CONFIG.frame-control.$$"
   tmp=$(mktemp) || return 1
   # Drop any previous managed block, then PREPEND a fresh one: ssh uses the first
   # value it sees per option, so this block must precede any other "Host frame"
@@ -126,7 +138,8 @@ write_config() {
     print -r -- "Host *"
     print -r -- "$END_MARK"
     cat "$tmp"
-  } > "$CONFIG" || { print -u2 "!! Writing $CONFIG failed; its previous contents are in $tmp"; return 1; }
+  } > "$new" && chmod 600 "$new" && mv -f "$new" "$CONFIG" \
+    || { rm -f "$new"; print -u2 "!! Writing $CONFIG failed; its previous contents are in $tmp"; return 1; }
   rm -f "$tmp"
 }
 

scripts/keep-awake.sh

@@ -15,11 +15,13 @@
 set -euo pipefail
 
 FRAME_ALIAS=${FRAME_ALIAS:-frame}
+# Frame Control passes the headset it has chosen: its address and pinned identity.
+ssh_opts=(${(Q)${(z)FRAME_SSH_OPTS:-}})
 HERE=${0:A:h}
 cmd=${1:-status}
 case $cmd in on|off|status) ;; *) echo "usage: keep-awake.sh on|off|status" >&2; exit 2 ;; esac
 
-ssh -o ConnectTimeout=8 "$FRAME_ALIAS" \
+ssh "${ssh_opts[@]}" -o ConnectTimeout=8 "$FRAME_ALIAS" \
   'mkdir -p ~/.cache/frame-control && cat > ~/.cache/frame-control/frame_steam.py' < "$HERE/../ui/frame_steam.py"
 
 # Runs on the Frame. Verified 2026-09-28 (BUILD_ID 20260925.6191901): the
@@ -27,7 +29,7 @@ ssh -o ConnectTimeout=8 "$FRAME_ALIAS" \
 # written the way Steam's settings page does (steamui module exporting the
 # SetSetting wrapper). logind refuses an inhibitor from an SSH session
 # ("Interactive authentication required") but allows one from a user unit.
-ssh "$FRAME_ALIAS" python3 - "$cmd" <<'EOF'
+ssh "${ssh_opts[@]}" "$FRAME_ALIAS" python3 - "$cmd" <<'EOF'
 import json, os, subprocess, sys
 sys.path.insert(0, os.path.expanduser("~/.cache/frame-control"))
 from frame_steam import Page

scripts/macview-bench.py

@@ -55,7 +55,6 @@ from urllib.parse import quote, urlencode  # %20, not +: the agent's URLComponen
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT / "ui"))
 import frame_macview  # noqa: E402
-import frame_pcview  # noqa: E402
 
 RESULTS = ROOT / "bench" / "results"
 PAGES = ROOT / "bench" / "pages"
@@ -255,10 +254,7 @@ class LabView(frame_macview.MacView):
 
 def ssh_runner(base):
     def run(remote, stdin=None, timeout=30):
-        r = subprocess.run([*base, remote], input=stdin.encode("utf-8") if stdin is not None else None,
-                           capture_output=True, timeout=timeout)
-        r.stdout = r.stdout.decode("utf-8", errors="replace")
-        r.stderr = r.stderr.decode("utf-8", errors="replace")
+        r = subprocess.run([*base, remote], input=stdin, capture_output=True, text=True, timeout=timeout)
         if r.returncode:
             e = RuntimeError((r.stderr or r.stdout).strip())
             e.stdout = r.stdout
@@ -385,11 +381,7 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
     if args.browser_flag is not None:
         mv.browser_flags = [f for f in args.browser_flag if f]
     chrome = None
-    src = args.source or "test"
-    cpu = None
-    if args.pc:
-        mv.host = "windows" if sys.platform == "win32" else "linux"
-        mv.viewer_profile = "pc-view"
+    src = "test"
     try:
         if scenario in ("scroll", "type"):
             chrome = chrome_window(f"{scenario}.html")
@@ -413,10 +405,9 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         since = max([f["s"] for f in first["frames"]] or [0])
         captured_before = first["captured"]
         start_mac_us = mv.call("/stats", id=stream["id"])["now"]
-        if not args.pc:
-            agent_pid = int(subprocess.run(["pgrep", "-f", "Frame Mac View Lab.app/Contents/MacOS/frame-mac-view"],
-                                           capture_output=True, text=True).stdout.split()[0])
-            cpu = CpuSampler(frame_ssh, agent_pid)
+        agent_pid = int(subprocess.run(["pgrep", "-f", "Frame Mac View Lab.app/Contents/MacOS/frame-mac-view"],
+                                       capture_output=True, text=True).stdout.split()[0])
+        cpu = CpuSampler(frame_ssh, agent_pid)
         if relay:
             relay.begin()
         expected = 0  # input events the harness asked the viewer for
@@ -452,8 +443,7 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         if not streams:
             raise SystemExit(f"{scenario}: the stream ended during the run (did the Frame go to sleep?)")
         data = streams[0]
-        if cpu:
-            cpu.stop()
+        cpu.stop()
         if args.raw:
             Path(f"{args.raw}-{scenario}.json").write_text(json.dumps(data))
         result = summarize(scenario, data, start_mac_us, end_mac_us, args, relay, schedule, expected)
@@ -462,7 +452,7 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
                             for e in data.get("events", []) if e["t"] >= start_mac_us]
         result["captured"] = (captured_end if captured_end is not None else data["captured"]) - captured_before
         result["source_fps"] = round(result["captured"] / max(result["duration_s"], 1), 1)
-        result["cpu"] = cpu.summary() if cpu else {"host": "not sampled"}
+        result["cpu"] = cpu.summary()
         result["viewer"] = data["summary"].get("decoder", "")
         result["show_s"] = show_s
         result["panel"] = shown.get("panel")
@@ -470,8 +460,6 @@ def run_scenario(args, scenario, agent_port, token, frame_ssh):
         result["route"] = mv.route
         return result
     finally:
-        if cpu:
-            cpu.stop()
         try:
             mv.stop(src)
         except Exception:  # noqa: BLE001 - best effort
@@ -682,8 +670,6 @@ def fmt(v):
 
 def add_run_args(r):
     r.add_argument("--scenario", default="test,scroll,type")
-    r.add_argument("--pc", action="store_true", help="run the bundled PC host; use --scenario test or capture")
-    r.add_argument("--source", default="", help="PC source: window:ID, display:ID, or choose (Linux portal)")
     r.add_argument("--duration", type=float, default=20)
     r.add_argument("--warmup", type=float, default=3)
     r.add_argument("--quality", default="balanced", choices=list(frame_macview.QUALITY))
@@ -731,7 +717,7 @@ def frame_ssh_for(args):
 
 
 def run_suite(args, frame_ssh, quiet=False):
-    agent_port, token = (args.pc_view.port, args.pc_view.token) if args.pc else lab_agent()
+    agent_port, token = lab_agent()
     results = []
     for sc in args.scenario.split(","):
         if not quiet:
@@ -758,12 +744,11 @@ def document(args, frame_ssh, results, **extra):
     commit = git("rev-parse", "--short", "HEAD") + ("+dirty" if git("status", "--porcelain", "--", "mac", "ui") else "")
     return {
         "label": args.label or args.cmd, "date": datetime.datetime.now().isoformat(timespec="seconds"), "commit": commit,
-        "config": {"quality": args.quality, "mode": "native" if args.pc else args.mode, "net": args.net or "none", "delay_ms": args.delay,
+        "config": {"quality": args.quality, "mode": args.mode, "net": args.net or "none", "delay_ms": args.delay,
                    "buffer_ms": args.buffer, "host": args.host or args.frame, "usb": args.usb, "ssh_opts": args.ssh_opt,
                    "encoder": os.environ.get("FRAME_MAC_VIEW_ENCODER", ""), "duration_s": args.duration,
                    "browser_flags": args.browser_flag if args.browser_flag is not None else frame_macview.BROWSER_FLAGS},
-        "frame_build": build.strip().partition("=")[2], "mac": platform.mac_ver()[0],
-        "host_platform": platform.platform(), "source": args.source, "pc_host": args.pc, "headset": standby[-40:],
+        "frame_build": build.strip().partition("=")[2], "mac": platform.mac_ver()[0], "headset": standby[-40:],
         "scenarios": results, **extra,
     }
 
@@ -834,46 +819,19 @@ def main():
             print("\nworse:\n  " + "\n  ".join(regs))
         sys.exit(1 if regs else 0)
 
-    if args.pc and (args.cmd == "ab" or args.scenario not in ("test", "capture")):
-        p.error("PC runs use --scenario test or --scenario capture; Mac automation is not portable")
-    if args.pc and args.scenario == "capture" and not args.source:
-        p.error("capture needs --source window:ID, display:ID, or choose")
-    if not args.pc:
-        lab_agent()
+    lab_agent()
     frame_ssh = frame_ssh_for(args)
     # Keep the Mac's screen awake: virtual displays aren't removed while it sleeps.
     runs = 1 if args.cmd == "run" else args.repeat * len(args.arm)
-    awake = subprocess.Popen(["caffeinate", "-d", "-u", "-t", str(int(runs * (args.duration * 4 + 60) + 120))]) if sys.platform == "darwin" else None
-    args.pc_view = None
+    awake = subprocess.Popen(["caffeinate", "-d", "-u", "-t", str(int(runs * (args.duration * 4 + 60) + 120))])
     try:
-        if args.pc:
-            args.pc_view = frame_pcview.PCView(frame_ssh[:-1], ssh_runner(frame_ssh), frame_ssh[-1])
-            args.pc_view.ensure_agent()
-            if args.source == "choose":
-                args.pc_view.call("/permissions", method="POST")
-                print("Choose a window or screen in your desktop's sharing dialog.", flush=True)
-                deadline = time.monotonic()+125
-                while time.monotonic() < deadline:
-                    state = args.pc_view.call("/status")
-                    if not state.get("selecting"):
-                        sources = args.pc_view.call("/windows")["windows"]
-                        if not sources:
-                            raise SystemExit(state.get("selectionError") or "Nothing was shared")
-                        args.source = sources[-1]["src"]
-                        break
-                    time.sleep(.5)
-                else:
-                    raise SystemExit("Sharing dialog timed out")
         if args.cmd == "ab":
             arm_runs, table = ab(args, frame_ssh)
             write(document(args, frame_ssh, [], arms=args.arm, runs=arm_runs, table=table), args)
             return
         results = run_suite(args, frame_ssh)
     finally:
-        if args.pc_view:
-            args.pc_view.shutdown()
-        if awake:
-            awake.terminate()
+        awake.terminate()
     doc = document(args, frame_ssh, results)
     write(doc, args)
     bad = [f"{r['scenario']} {k}" for r in results for k, v in r["grades"].items() if v in ("bad", "missing")]

scripts/panel-on-frame.sh

@@ -21,6 +21,8 @@
 set -euo pipefail
 
 FRAME_ALIAS=${FRAME_ALIAS:-frame}
+# Frame Control passes the headset it has chosen: its address and pinned identity.
+ssh_opts=(${(Q)${(z)FRAME_SSH_OPTS:-}})
 REMMINA_PROFILE="~/.var/app/org.remmina.Remmina/data/remmina/mac-screen-sharing.remmina"
 id="" name=""
 
@@ -109,4 +111,4 @@ EOF
 )
 b64=$(print -rn -- "$remote" | base64)
 
-ssh "$FRAME_ALIAS" "bash -c \"\$(echo $b64 | base64 -d)\" panel-on-frame $id ${(j: :)${(@q)cmd}}"
+ssh "${ssh_opts[@]}" "$FRAME_ALIAS" "bash -c \"\$(echo $b64 | base64 -d)\" panel-on-frame $id ${(j: :)${(@q)cmd}}"

tests/e2e/test_android.py

@@ -33,8 +33,8 @@ class AndroidApps(harness.FrameTestCase):
         self.assertEqual(shortcut['name'], 'App label')
         self.assertEqual(shortcut['exe'], f'{APP_DIR}/launch.sh')
         self.assertEqual(shortcut['start_dir'], APP_DIR)
-        self.assertEqual(shortcut['icon'], f'{APP_DIR}/icon.png')
-        for f in ('app.apk', 'launch.sh', 'instance.id', 'meta.json', 'icon.png', 'lepton-show-flatscreen'):
+        self.assertEqual(shortcut['icon'], f'{APP_DIR}/artwork/icon.png')
+        for f in ('app.apk', 'launch.sh', 'instance.id', 'meta.json', 'artwork/icon.png', 'lepton-show-flatscreen'):
             self.assertTrue(exists(f'{APP_DIR}/{f}'), f)
         self.assertEqual(meta['game_id'], (meta['shortcut'] << 32) | 0x02000000)
 

tests/e2e/test_device.py

@@ -83,5 +83,27 @@ class Device(harness.FrameTestCase):
         self.assertEqual(state()['steam']['pages'][0]['title'], 'Hades on Steam')
 
 
+class VRUtilities(harness.FrameTestCase):
+    def test_missing_vr_runtime_is_unavailable_not_zero_fps(self):
+        data = ok('GET', '/api/status')
+        self.assertIsNone(data['performance']['compositorFps'])
+        self.assertIsNone(data['performance']['appFps'])
+        self.assertEqual(data['temp'], 41.5)
+        self.assertEqual(data['battery']['percent'], 76)
+
+    def test_optional_paid_utilities_are_not_installed(self):
+        # The fake library contains games but none of these paid software titles.
+        for appid in (1009850, 1173510, 1068820, 908520):
+            code, body, _ = api('POST', '/api/steam', {'action': 'install', 'appid': appid})
+            self.assertEqual(code, 502, body)
+            self.assertIn('not owned', body['error'])
+        self.assertEqual(launches('install'), [])
+
+    def test_unverified_controls_are_not_exposed(self):
+        for action in ('recenter', 'adjust', 'restore'):
+            code, body, _ = api('POST', '/api/vr', {'action': action, 'origin': 'seated', 'y': .1})
+            self.assertEqual(code, 400, body)
+
+
 if __name__ == '__main__':
     unittest.main()

tests/fakeframe/rootfs/usr/local/bin/podman

@@ -25,6 +25,10 @@ containers = {n: c for n, c in fs.read()['lepton'].items() if alive(c)}
 if cmd == 'ps':
     for name, c in sorted(containers.items()):
         print(f"{name} {c['port']}")
+elif cmd == 'inspect':
+    if args[-1] not in containers:
+        sys.exit(1)
+    print('true')
 elif cmd == 'stop':
     name = args[-1]
     c = containers.get(name)

tests/fakeframe/rootfs/usr/local/lib/fakeframe/canvas_stub.js

@@ -0,0 +1,33 @@
+// Synthetic canvas for API-path tests only. It emits transparent PNGs, not visual proof.
+const zlib = require('zlib');
+function crc(data) {
+  let c=0xffffffff;
+  for(const b of data) {c^=b;for(let i=0;i<8;i++)c=(c>>>1)^((c&1)?0xedb88320:0);}
+  return (c^0xffffffff)>>>0;
+}
+function chunk(name,data) {
+  const body=Buffer.concat([Buffer.from(name),data]), n=Buffer.alloc(4), sum=Buffer.alloc(4);
+  n.writeUInt32BE(data.length);sum.writeUInt32BE(crc(body));return Buffer.concat([n,body,sum]);
+}
+function png(w,h) {
+  const header=Buffer.alloc(13);header.writeUInt32BE(w);header.writeUInt32BE(h,4);header[8]=8;header[9]=6;
+  return Buffer.concat([Buffer.from('89504e470d0a1a0a','hex'),chunk('IHDR',header),
+    chunk('IDAT',zlib.deflateSync(Buffer.alloc((w*4+1)*h))),chunk('IEND',Buffer.alloc(0))]).toString('base64');
+}
+function surface() {
+  const canvases=[];
+  const document={fonts:{load:async()=>[]},createElement(tag) {
+    if(tag!=='canvas')throw Error('unexpected element');
+    const canvas={width:1,height:1,text:[],draws:0};
+    const ctx={measureText:t=>({width:String(t).length*30}),fillText(t){canvas.text.push(t);},
+      drawImage(){canvas.draws++;},getImageData:()=>({data:new Uint8ClampedArray(canvas.width*canvas.height*4)}),
+      createLinearGradient:()=>({addColorStop(){}}),createRadialGradient:()=>({addColorStop(){}})};
+    for(const method of ['save','restore','beginPath','rect','roundRect','clip','fillRect','putImageData','arc','fill','stroke'])ctx[method]=()=>{};
+    canvas.getContext=()=>ctx;canvas.toDataURL=type=>type==='image/jpeg'?'data:image/jpeg;base64,'+Buffer.from('ffd8ffe000104a464946','hex').toString('base64'):
+      'data:image/png;base64,'+png(canvas.width,canvas.height);
+    canvases.push(canvas);return canvas;
+  }};
+  class Image {constructor(){this.width=2;this.height=2;} async decode(){if(this.src.includes('YmFk'))throw Error('bad image');}}
+  return {document,Image,canvases};
+}
+module.exports={surface};

tests/fakeframe/rootfs/usr/local/lib/fakeframe/cef_shim.js

@@ -27,7 +27,7 @@ function newShortcutId(steam) {
 function build(steam) {
   const findShortcut = id => steam.shortcuts.find(s => s.appid === Number(id));
   const gameOverview = a => ({
-    appid: a.appid, display_name: a.display_name, sort_as: a.display_name, app_type: 1,
+    appid: a.appid, display_name: a.display_name, sort_as: a.display_name, app_type: a.app_type ?? 1,
     steam_hw_compat_category_packed: a.packed || 0, vr_supported: !!a.vr, vr_only: !!a.vr_only,
     size_on_disk: String(a.installed ? a.size : 0), minutes_playtime_forever: a.minutes || 0,
     rt_last_time_played: a.last_played || 0,
@@ -37,7 +37,8 @@ function build(steam) {
     },
   });
   const shortcutOverview = s => ({
-    appid: s.appid, display_name: s.name, sort_as: s.name, app_type: SHORTCUT_TYPE,
+    appid: s.appid, display_name: s.name, sort_as: s.name, app_type: SHORTCUT_TYPE, devkit_gameid: s.devkit_gameid,
+    icon_data: s.icon ? 'fake-icon' : undefined,
     local_per_client_data: { installed: true, display_status: 1, status_percentage: 0 },
   });
   const allApps = () => [...steam.apps.map(gameOverview), ...steam.shortcuts.map(shortcutOverview)];
@@ -54,7 +55,30 @@ function build(steam) {
     }
   };
 
+  // Library API shapes from SteamTracking / decky-frontend-lib (2026-09-28).
+  // Not yet verified on this Frame build: Steam was unavailable during testing.
+  steam.collections ||= [];
+  const collection = value => ({
+    ...value, displayName: value.name, bIsDynamic: !!value.dynamic, bAllowsDragAndDrop: true,
+    AsDragDropCollection() { return this; },
+    AddApps(apps) { value.apps = [...new Set([...value.apps, ...apps.map(a => a.appid)])]; },
+    RemoveApps(apps) { value.apps = value.apps.filter(id => !apps.some(a => a.appid === id)); },
+    value,
+  });
   return {
+    ...require('./canvas_stub').surface(),
+    collectionStore: {
+      GetUserCollectionsByName(name) { return steam.collections.filter(c => c.name === name).map(collection); },
+      NewUnsavedCollection(name, filter, apps) { return collection({name, apps: apps.map(a => a.appid)}); },
+      async SaveCollection(c) { if (!steam.collections.includes(c.value)) steam.collections.push(c.value); },
+    },
+    // Shortcut exe/start folder live in app details, not overviews (Frame, 2026-09-28).
+    appDetailsStore: {
+      GetAppDetails(id) {
+        const s = findShortcut(id);
+        return s ? { strShortcutExe: s.exe, strShortcutStartDir: s.start_dir, bShortcutIsVR: !!s.vr } : null;
+      },
+    },
     appStore: {
       get allApps() { return allApps(); },
       GetAppOverviewByAppID(id) { return allApps().find(a => a.appid === Number(id)) || null; },
@@ -75,6 +99,17 @@ function build(steam) {
         SetShortcutStartDir(id, dir) { const s = findShortcut(id); if (s) s.start_dir = String(dir); },
         SetShortcutIcon(id, icon) { const s = findShortcut(id); if (s) s.icon = String(icon); },
         SetShortcutExe(id, exe) { const s = findShortcut(id); if (s) s.exe = String(exe); },
+        SetShortcutIsVR(id, vr) { const s = findShortcut(id); if (s) s.vr = vr; },
+        async SetCustomArtworkForApp(id, data, ext, type) {
+          const s = findShortcut(id);
+          if (s) { s.artwork ||= {}; s.artwork[type] = {data, ext}; }
+        },
+        async ClearCustomArtworkForApp(id, type) {
+          const s = findShortcut(id);
+          if (s?.artwork) delete s.artwork[type];
+        },
+        // Container fallback in frame_android.stop performs the simulated stop.
+        TerminateApp(gameid) { steam.last_terminate = gameid; },
         RemoveShortcut(id) {
           steam.shortcuts = steam.shortcuts.filter(s => s.appid !== Number(id));
           delete steam.compat_tools[String(id)];

tests/fakessh/ssh

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""A stand-in for OpenSSH's ssh, for tests/test_link.py: prints what `ssh -v` prints at
+each step of a connection, and plays a ControlMaster. What each HostName does comes
+from $FAKESSH_HOSTS (JSON: host -> "ok", "wrong" (a different host key), "denied" or
+"slow" (hangs after connecting);
+every call is appended to $FAKESSH_LOG as a JSON line. POSIX only."""
+import json
+import os
+import signal
+import sys
+import time
+
+args = sys.argv[1:]
+with open(os.environ["FAKESSH_LOG"], "a") as f:
+    f.write(json.dumps(args) + "\n")
+hosts = json.loads(os.environ.get("FAKESSH_HOSTS", "{}"))
+opts = {}
+i = 0
+while i < len(args) and args[i].startswith("-"):
+    if args[i] in ("-o", "-O", "-p", "-l"):
+        key = args[i]
+        val = args[i + 1]
+        if key == "-o":
+            k, _, v = val.partition("=")
+            opts[k.lower()] = v
+        else:
+            opts[key] = val
+        i += 2
+    else:
+        opts[args[i]] = True
+        i += 1
+alias = args[i] if i < len(args) else ""
+host = opts.get("hostname", alias).replace("%%", "%")
+marker = os.path.join(os.environ["FAKESSH_DIR"], "master-" + host.replace("/", "_"))
+say = lambda s: (sys.stderr.write(s + "\n"), sys.stderr.flush())
+
+if "-G" in opts:
+    print(f"hostname {alias}\nport 22\nuser tester")
+    sys.exit(0)
+if opts.get("-O") == "check":
+    sys.exit(0 if os.path.exists(marker) else 255)
+if opts.get("-O") == "exit":
+    if os.path.exists(marker):
+        os.unlink(marker)
+    sys.exit(0)
+
+what = hosts.get(host)
+if what is None:
+    say(f"ssh: Could not resolve hostname {host}: nodename nor servname provided, or not known")
+    sys.exit(255)
+say(f"debug1: Connecting to {host} [127.0.0.1] port {opts.get('port', 22)}.")
+say("debug1: Connection established.")
+if what == "slow":
+    time.sleep(30)
+say(f"debug1: Authenticating to {host}:22 as '{opts.get('user', 'tester')}'")
+say("debug1: Server host key: ssh-ed25519 SHA256:fakefakefakefakefakefakefakefakefakefakefak")
+if what == "wrong":
+    say("@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@")
+    say("@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @")
+    say("Host key verification failed.")
+    sys.exit(255)
+say(f"debug1: Host '{opts.get('hostkeyalias', host)}' is known and matches the ED25519 host key.")
+say("debug1: Next authentication method: publickey")
+if what == "denied":
+    say(f"tester@{host}: Permission denied (publickey).")
+    sys.exit(255)
+say(f'Authenticated to {host} ([127.0.0.1]:22) using "publickey".')
+if opts.get("controlmaster") == "yes":
+    open(marker, "w").close()
+    def bye(*_):
+        if os.path.exists(marker):
+            os.unlink(marker)
+        sys.exit(0)
+    signal.signal(signal.SIGTERM, bye)
+    while True:
+        time.sleep(0.2)
+        if not os.path.exists(marker):
+            sys.exit(0)
+sys.exit(0)

tests/fixtures/apk-search/artwork/README.md

@@ -0,0 +1,19 @@
+# Store preview artwork
+
+Recorded public artwork for offline UI verification, fetched 2026-09-28.
+`urls.json` records each original URL. No unit test downloads these files.
+
+- Open Brush banner, icon and screenshots: Icosa Foundation's public
+  `icosa-foundation/openbrush.app` website assets. Artwork remains credited to
+  its creators; used here to preview the Open Brush listing.
+- Mindustry, AntennaPod and NewPipe icons/screenshots: their public F-Droid
+  listings. Corresponding projects use GPL licences; these images represent
+  those same apps in the store preview.
+- Luanti, SuperTuxKart and other social previews: public GitHub-generated
+  repository preview images. Project names/logos belong to their owners.
+
+`../store.json` contains illustrative listing metadata, including mock package
+names, popularity, dates, version/size and compatibility fields. It is not a
+catalogue or evidence that a particular release works on the Frame. `_demo.py`
+is opt-in and cannot download APKs. `tests/search_preview.py` preloads these
+recordings into the image cache and simulates installation without a headset.

tests/fixtures/apk-search/artwork/urls.json

@@ -0,0 +1,16 @@
+{
+  "brush-banner.jpg": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/bg.jpg",
+  "brush-icon.png": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/icon.png",
+  "brush-shot1.png": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/1.png",
+  "brush-shot2.webp": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/2.webp",
+  "brush-shot3.webp": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/3.webp",
+  "luanti.png": "https://opengraph.githubassets.com/1/luanti-org/luanti",
+  "kart.png": "https://opengraph.githubassets.com/1/supertuxkart/stk-code",
+  "luanti-icon.png": "https://raw.githubusercontent.com/luanti-org/luanti/master/textures/base/pack/logo.png",
+  "pod-icon.png": "https://f-droid.org/repo/de.danoeh.antennapod/en-US/icon_w44b41PyuNt3pI7Gh8zYHJrWgu__3HT7YSWZtttfenk=.png",
+  "mindustry-icon.png": "https://f-droid.org/repo/io.anuke.mindustry/en-US/icon_Eno3XvqCZUcHRm3eMjiUleAxgzLopPe6-hkI7BHx1lU=.png",
+  "mindustry-shot.png": "https://f-droid.org/repo/io.anuke.mindustry/en-US/phoneScreenshots/1.png",
+  "pod-shot.png": "https://f-droid.org/repo/de.danoeh.antennapod/en-US/phoneScreenshots/00.png",
+  "newpipe-icon.png": "https://f-droid.org/repo/org.schabi.newpipe/en-US/icon_OHy4y1W-fJCNhHHOBCM9V_cxZNJJgbcNkB-x7UDTY9Q=.png",
+  "newpipe-shot.png": "https://f-droid.org/repo/org.schabi.newpipe/en-US/phoneScreenshots/00.png"
+}

tests/fixtures/apk-search/entries.json

@@ -0,0 +1,7 @@
+[
+ {"source":"one","id":"brush","package":"org.brush","name":"Open Brush","free":true,"downloadable":true,"verified":true,"version":"1","version_code":1,"min_sdk":29,"abis":["arm64-v8a"],"vr":true,"updated":"2025-01-01"},
+ {"source":"two","id":"brush2","package":"org.brush","name":"Open Brush","free":true,"downloadable":true,"verified":false,"version":"2","version_code":2,"min_sdk":29,"abis":["arm64-v8a"],"vr":true,"updated":"2026-01-01"},
+ {"source":"one","id":"other","package":"org.other","name":"Open Brush","free":true,"downloadable":true,"min_sdk":31,"abis":["arm64-v8a"],"vr":true},
+ {"source":"one","id":"unknown","package":null,"name":"Pocket Radio!","free":true,"downloadable":false,"vr":false},
+ {"source":"two","id":"unknown2","package":null,"name":"pocket  radio","free":true,"downloadable":false,"vr":false}
+]

tests/fixtures/apk-search/store.json

@@ -0,0 +1,182 @@
+[
+  {
+    "id": "brush",
+    "package": "org.preview.brush",
+    "name": "Open Brush",
+    "summary": "Make the world your canvas. Paint, sculpt and create in a space without limits.",
+    "description": "Your imagination deserves more room. Open Brush turns the space around you into a canvas, with expressive brushes, vivid colors and light you can paint with.\n\nCreate something small, build something extraordinary, or just enjoy making your first mark in VR. This community-led painting app is free and open source.",
+    "developer": "Icosa Foundation",
+    "license": "Apache-2.0",
+    "free": true,
+    "downloadable": true,
+    "version": "2.32.29",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": true,
+    "updated": "2026-09-27",
+    "size": 85000000,
+    "popularity": 100,
+    "images": {
+      "banner": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/bg.jpg",
+      "icon": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/icon.png",
+      "screenshots": [
+        "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/1.png",
+        "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/2.webp",
+        "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/carousel/3.webp"
+      ]
+    },
+    "engine": "Unity OpenXR",
+    "frame_tested": true,
+    "icon": "https://raw.githubusercontent.com/icosa-foundation/openbrush.app/main/assets/icon.png",
+    "page": "https://openbrush.app"
+  },
+  {
+    "id": "mindustry",
+    "package": "org.preview.mindustry",
+    "name": "Mindustry",
+    "summary": "Build a factory. Defend your world.",
+    "description": "Build a factory. Defend your world.",
+    "developer": "Anuken",
+    "license": "GPL-3.0",
+    "free": true,
+    "downloadable": true,
+    "version": "1.2",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": false,
+    "updated": "2026-09-26",
+    "size": 85000000,
+    "popularity": 92,
+    "images": {
+      "banner": "https://f-droid.org/repo/io.anuke.mindustry/en-US/phoneScreenshots/1.png",
+      "icon": "https://f-droid.org/repo/io.anuke.mindustry/en-US/icon_Eno3XvqCZUcHRm3eMjiUleAxgzLopPe6-hkI7BHx1lU=.png",
+      "screenshots": [
+        "https://f-droid.org/repo/io.anuke.mindustry/en-US/phoneScreenshots/1.png"
+      ]
+    },
+    "icon": "https://f-droid.org/repo/io.anuke.mindustry/en-US/icon_Eno3XvqCZUcHRm3eMjiUleAxgzLopPe6-hkI7BHx1lU=.png"
+  },
+  {
+    "id": "luanti",
+    "package": "org.preview.luanti",
+    "name": "Luanti",
+    "summary": "A world of blocks. Endless possibilities.",
+    "description": "A world of blocks. Endless possibilities.",
+    "developer": "Luanti contributors",
+    "license": "LGPL-2.1",
+    "free": true,
+    "downloadable": true,
+    "version": "1.3",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": false,
+    "updated": "2026-09-25",
+    "size": 85000000,
+    "popularity": 84,
+    "images": {
+      "banner": "https://opengraph.githubassets.com/1/luanti-org/luanti",
+      "icon": "https://raw.githubusercontent.com/luanti-org/luanti/master/textures/base/pack/logo.png",
+      "screenshots": [
+        "https://opengraph.githubassets.com/1/luanti-org/luanti"
+      ]
+    },
+    "icon": "https://raw.githubusercontent.com/luanti-org/luanti/master/textures/base/pack/logo.png"
+  },
+  {
+    "id": "pod",
+    "package": "org.preview.pod",
+    "name": "AntennaPod",
+    "summary": "Your favorite stories, wherever you listen.",
+    "description": "Your favorite stories, wherever you listen.",
+    "developer": "AntennaPod contributors",
+    "license": "GPL-3.0",
+    "free": true,
+    "downloadable": true,
+    "version": "1.4",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": false,
+    "updated": "2026-09-24",
+    "size": 85000000,
+    "popularity": 76,
+    "images": {
+      "banner": "https://f-droid.org/repo/de.danoeh.antennapod/en-US/phoneScreenshots/00.png",
+      "icon": "https://f-droid.org/repo/de.danoeh.antennapod/en-US/icon_w44b41PyuNt3pI7Gh8zYHJrWgu__3HT7YSWZtttfenk=.png",
+      "screenshots": [
+        "https://f-droid.org/repo/de.danoeh.antennapod/en-US/phoneScreenshots/00.png"
+      ]
+    },
+    "icon": "https://f-droid.org/repo/de.danoeh.antennapod/en-US/icon_w44b41PyuNt3pI7Gh8zYHJrWgu__3HT7YSWZtttfenk=.png"
+  },
+  {
+    "id": "newpipe",
+    "package": "org.preview.newpipe",
+    "name": "NewPipe",
+    "summary": "Your videos and music, without the distractions.",
+    "description": "Your videos and music, without the distractions.",
+    "developer": "Team NewPipe",
+    "license": "GPL-3.0",
+    "free": true,
+    "downloadable": true,
+    "version": "1.5",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": false,
+    "updated": "2026-09-23",
+    "size": 85000000,
+    "popularity": 68,
+    "images": {
+      "banner": "https://f-droid.org/repo/org.schabi.newpipe/en-US/phoneScreenshots/00.png",
+      "icon": "https://f-droid.org/repo/org.schabi.newpipe/en-US/icon_OHy4y1W-fJCNhHHOBCM9V_cxZNJJgbcNkB-x7UDTY9Q=.png",
+      "screenshots": [
+        "https://f-droid.org/repo/org.schabi.newpipe/en-US/phoneScreenshots/00.png"
+      ]
+    },
+    "icon": "https://f-droid.org/repo/org.schabi.newpipe/en-US/icon_OHy4y1W-fJCNhHHOBCM9V_cxZNJJgbcNkB-x7UDTY9Q=.png"
+  },
+  {
+    "id": "kart",
+    "package": "org.preview.kart",
+    "name": "SuperTuxKart",
+    "summary": "A little friendly competition. A lot of colorful chaos.",
+    "description": "A little friendly competition. A lot of colorful chaos.",
+    "developer": "SuperTuxKart Team",
+    "license": "GPL-3.0",
+    "free": true,
+    "downloadable": false,
+    "version": "1.6",
+    "version_code": 1,
+    "min_sdk": 26,
+    "abis": [
+      "arm64-v8a"
+    ],
+    "vr": false,
+    "updated": "2026-09-22",
+    "size": 85000000,
+    "popularity": 60,
+    "images": {
+      "banner": "https://opengraph.githubassets.com/1/supertuxkart/stk-code",
+      "icon": null,
+      "screenshots": [
+        "https://opengraph.githubassets.com/1/supertuxkart/stk-code"
+      ]
+    },
+    "icon": null,
+    "page": "https://supertuxkart.net"
+  }
+]

tests/fixtures/fdroid/README.md

@@ -0,0 +1,21 @@
+# F-Droid verification fixtures
+
+`entry.jar` and `index-v1.jar` are synthetic RSA-2048/SHA-256 signed JARs,
+including CMS signed attributes. `fingerprint.txt` identifies their throwaway
+certificate. Their JSON describes org.example.app; `example.apk` is deliberately
+plain test data, not an installable app. The v2 index includes incompatible
+Android-31 and x86-only versions to exercise the shared reducer.
+
+`izzy-entry.jar` was recorded from
+https://apt.izzysoft.de/fdroid/repo/entry.jar on 2026-09-28. Its certificate
+fingerprint matches the operator's published fingerprint:
+3BF0D6ABFEAE2F401707B6D966BE743BF0EEE49C2561B9BA39073711F628937A.
+It exercises an independent production JAR/CMS encoder without network access.
+The index it references is not needed by this signature-only fixture test.
+
+`artwork-v1.json` and `artwork-v2.json` are unsigned metadata/reducer fixtures
+based on the synthetic indexes above. They exercise en-US preference, per-field
+locale fallback, v1 artwork paths, phone/tablet ordering, the six-image cap,
+author names and HTML/multiline summaries. The signed integrity fixtures remain
+unchanged; artwork tests feed these JSON files directly through the reducer and
+then round-trip the resulting entries through the source cache.

tests/fixtures/fdroid/artwork-v1.json

@@ -0,0 +1,54 @@
+{
+  "apps": [
+    {
+      "packageName": "org.example.app",
+      "name": "Example",
+      "license": "MIT",
+      "authorName": "Example Developer",
+      "summary": "Fallback summary",
+      "localized": {
+        "de": {
+          "name": "Beispiel",
+          "summary": "Deutsch",
+          "icon": "german.png",
+          "phoneScreenshots": [
+            "german.png"
+          ]
+        },
+        "en-US": {
+          "name": "Example",
+          "summary": "Offline <b>fixture</b> &amp; music.\n One\t line.",
+          "icon": "icon.png",
+          "phoneScreenshots": [
+            "1.png",
+            "2.png",
+            "3.png",
+            "4.png"
+          ]
+        },
+        "fr": {
+          "featureGraphic": "featureGraphic.png",
+          "sevenInchScreenshots": [
+            "1.png",
+            "2.png",
+            "3.png",
+            "4.png"
+          ]
+        }
+      }
+    }
+  ],
+  "packages": {
+    "org.example.app": [
+      {
+        "versionName": "1",
+        "versionCode": 1,
+        "apkName": "example1.apk",
+        "hash": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79",
+        "hashType": "sha256",
+        "size": 51,
+        "minSdkVersion": 21
+      }
+    ]
+  }
+}

tests/fixtures/fdroid/artwork-v2.json

@@ -0,0 +1,143 @@
+{
+  "repo": {
+    "name": {
+      "en-US": "Fixture"
+    }
+  },
+  "packages": {
+    "org.example.app": {
+      "metadata": {
+        "name": {
+          "en-US": "Example"
+        },
+        "summary": {
+          "en-US": "<p>Offline <b>fixture</b> &amp; music.</p>\n<p>One\t line.</p><script>hidden()</script>"
+        },
+        "license": "MIT",
+        "authorName": "Example Developer",
+        "icon": {
+          "de": {
+            "name": "/org.example.app/de/icon.png"
+          },
+          "en-US": {
+            "name": "/org.example.app/en-US/icon.png"
+          }
+        },
+        "featureGraphic": {
+          "fr": {
+            "name": "/org.example.app/fr/featureGraphic.png"
+          }
+        },
+        "screenshots": {
+          "phone": {
+            "de": [
+              {
+                "name": "/org.example.app/de/phoneScreenshots/1.png"
+              }
+            ],
+            "en-US": [
+              {
+                "name": "/org.example.app/en-US/phoneScreenshots/1.png"
+              },
+              {
+                "name": "/org.example.app/en-US/phoneScreenshots/2.png"
+              },
+              {
+                "name": "/org.example.app/en-US/phoneScreenshots/3.png"
+              },
+              {
+                "name": "/org.example.app/en-US/phoneScreenshots/4.png"
+              }
+            ]
+          },
+          "sevenInch": {
+            "fr": [
+              {
+                "name": "/org.example.app/fr/sevenInchScreenshots/1.png"
+              },
+              {
+                "name": "/org.example.app/fr/sevenInchScreenshots/2.png"
+              },
+              {
+                "name": "/org.example.app/fr/sevenInchScreenshots/3.png"
+              },
+              {
+                "name": "/org.example.app/fr/sevenInchScreenshots/4.png"
+              }
+            ]
+          }
+        }
+      },
+      "versions": {
+        "1": {
+          "manifest": {
+            "versionName": "1",
+            "versionCode": 1,
+            "usesSdk": {
+              "minSdkVersion": 21
+            },
+            "nativecode": []
+          },
+          "file": {
+            "name": "/example1.apk",
+            "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79",
+            "size": 51
+          },
+          "added": 1700000000000
+        },
+        "2": {
+          "manifest": {
+            "versionName": "2",
+            "versionCode": 2,
+            "usesSdk": {
+              "minSdkVersion": 30
+            },
+            "nativecode": [
+              "arm64-v8a"
+            ]
+          },
+          "file": {
+            "name": "/example2.apk",
+            "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79",
+            "size": 51
+          },
+          "added": 1700000000000
+        },
+        "3": {
+          "manifest": {
+            "versionName": "3",
+            "versionCode": 3,
+            "usesSdk": {
+              "minSdkVersion": 31
+            },
+            "nativecode": []
+          },
+          "file": {
+            "name": "/example3.apk",
+            "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79",
+            "size": 51
+          },
+          "added": 1700000000000
+        },
+        "4": {
+          "manifest": {
+            "versionName": "4",
+            "versionCode": 4,
+            "usesSdk": {
+              "minSdkVersion": 21
+            },
+            "nativecode": [
+              "x86_64"
+            ]
+          },
+          "file": {
+            "name": "/example4.apk",
+            "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79",
+            "size": 51
+          },
+          "added": 1700000000000
+        }
+      }
+    }
+  }
+}

tests/fixtures/fdroid/example.apk

@@ -0,0 +1 @@
+Fixture APK payload, deliberately not installable.

tests/fixtures/fdroid/fingerprint.txt

@@ -0,0 +1 @@
+0e87b227cd414d7093fb150fda81f1754900f3abc810e6785d8e0767c6eb798a

tests/fixtures/fdroid/index-v2.json

@@ -0,0 +1 @@
+{"repo": {"name": {"en-US": "Fixture"}}, "packages": {"org.example.app": {"metadata": {"name": {"en-US": "Example"}, "summary": {"en-US": "Offline fixture"}, "license": "MIT"}, "versions": {"1": {"manifest": {"versionName": "1", "versionCode": 1, "usesSdk": {"minSdkVersion": 21}, "nativecode": []}, "file": {"name": "/example1.apk", "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79", "size": 51}, "added": 1700000000000}, "2": {"manifest": {"versionName": "2", "versionCode": 2, "usesSdk": {"minSdkVersion": 30}, "nativecode": ["arm64-v8a"]}, "file": {"name": "/example2.apk", "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79", "size": 51}, "added": 1700000000000}, "3": {"manifest": {"versionName": "3", "versionCode": 3, "usesSdk": {"minSdkVersion": 31}, "nativecode": []}, "file": {"name": "/example3.apk", "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79", "size": 51}, "added": 1700000000000}, "4": {"manifest": {"versionName": "4", "versionCode": 4, "usesSdk": {"minSdkVersion": 21}, "nativecode": ["x86_64"]}, "file": {"name": "/example4.apk", "sha256": "3e1e2658aef79aaf21aeb8d6705dbc5b251e51627bfdfc53650da50ed2c38c79", "size": 51}, "added": 1700000000000}}}}}

tests/fixtures/library/README.md

@@ -0,0 +1,17 @@
+# Library fixtures
+
+`icon.png` is a synthetic 2×2 RGBA fixture with opaque, half-transparent and
+transparent pixels. `steam-responses.json` includes the Open Saber Plus
+shortcut ID/name and home path read from the Frame's existing metadata on
+2026-09-28; the `configure` response is synthetic, matching our helper's
+contract. Tests never contact the network.
+
+The existing fakeframe CEF shim models artwork and collection methods from
+SteamTracking's `ClientExtracted/steamui/chunk~2dcc5aaf7.js` and
+SteamDeckHomebrew/decky-frontend-lib's `src/globals/steam-client/App.ts`, read
+2026-09-28. These methods were not captured from this headset: Steam's client
+was unavailable. The Node-based test runs the actual generated JavaScript
+against that fixture; it is skipped when Node is absent.
+
+`icon.jpg` is the same synthetic icon converted with macOS `sips` to exercise
+JPEG SOF parsing. `sips` is not used by the product or tests.

tests/fixtures/library/check-renderer.js

@@ -0,0 +1,21 @@
+const fs=require('fs'),vm=require('vm'),assert=require('assert');
+const stub=require(process.cwd()+'/tests/fakeframe/rootfs/usr/local/lib/fakeframe/canvas_stub');
+(async()=>{
+ const surface=stub.surface(),ctx=vm.createContext(surface);
+ vm.runInContext(fs.readFileSync('frame/android/library_artwork.js','utf8'),ctx);
+ const result=await ctx.renderLibraryArtwork({label:'Example Game',images:{icon:['png','fixture']}});
+ assert.deepEqual(Object.keys(result.images),['grid','wide','hero','logo','icon']);
+ for(const [slot,size] of Object.entries({grid:[600,900],wide:[920,430],hero:[3840,1240],logo:[1280,480],icon:[256,256]})) {
+  assert.equal(result.images[slot][0],'png');
+  const b=Buffer.from(result.images[slot][1],'base64');assert.equal(b.readUInt32BE(16),size[0]);assert.equal(b.readUInt32BE(20),size[1]);
+ }
+ // A photo scene is JPEG (Steam's 12 MiB limit at hero size); the logo stays transparent PNG.
+ const photo=await ctx.renderLibraryArtwork({label:'Photo',images:{hero:['jpg','fixture'],banner:['jpg','fixture']}});
+ for(const slot of ['wide','hero'])assert.equal(photo.images[slot][0],'jpg');
+ for(const slot of ['grid','logo','icon'])assert.equal(photo.images[slot][0],'png');
+ const hero=surface.canvases.find(c=>c.width===3840);assert.equal(hero.text.length,0);
+ const logo=surface.canvases.find(c=>c.width===1280);assert(logo.text.length);assert.equal(logo.draws,0);
+ const before=surface.canvases.length;await ctx.renderLibraryArtwork({label:'No Icon',images:{}});
+ assert.equal(surface.canvases.slice(before).find(c=>c.width===3840).text.length,0);
+ console.log('five dimensions, textless hero, title logo: OK');
+})().catch(e=>{console.error(e);process.exit(1)});

tests/fixtures/library/steam-responses.json

@@ -0,0 +1,12 @@
+{
+  "home": "/home/steamos",
+  "shortcuts": [
+    {
+      "appid": 3346865537,
+      "name": "Open Saber Plus"
+    }
+  ],
+  "configure": {
+    "warnings": []
+  }
+}