chore: resolve conflicts with main

Queue Android and Quest installs; prepare Frame Control 0.4.7

.github/workflows/pc-host.yml

@@ -0,0 +1,53 @@
+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/**", "scripts/**", "frame/**", "apk-catalog/**", ".github/workflows/release.yml"]
+    paths: ["app/**", "ui/**", "desktop/**", "mac/**", "scripts/**", "frame/**", "apk-catalog/**", ".github/workflows/release.yml"]
   workflow_dispatch:
 
 permissions:
@@ -61,18 +61,62 @@ 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
       # The installer, not just the unpacked build: its 7-Zip payload once dropped
       # the OpenXR layer's arm64 library without any error. Install it silently
       # and compare every installed file with the unpacked build.

.gitignore

@@ -7,5 +7,15 @@ 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

@@ -213,9 +213,12 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Scripts and headset setup](docs/scripts.md) | The command-line helpers, minimum typing, streaming options, floating panels |
 | [How the Frame works](docs/how-the-frame-works.md) | SteamVR → gamescope → Plasma, verified facts, debugging |
 | [Android apps (Lepton)](docs/apks.md) | Sideloading, the rated F-Droid catalogue, per-app instances |
+| [Import from my Quest](docs/quest-import.md) | Copy games you own off your Quest by USB; what runs, and why licence-checked games may not |
+| [My Meta library](docs/meta-library.md) | Experimental: install and test Quest games your Meta account owns, with your own token |
 | [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 |
 | [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 |
+| [PC in the headset](docs/pc-in-headset.md) | Windows and Linux host implementation and test coverage |
 | [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, Notification, clipboard, dialog, ipcMain, nativeImage, shell } = require("electron");
+const { app, BrowserWindow, Menu, Notification, clipboard, dialog, ipcMain, nativeImage, session, shell } = require("electron");
 const { execFile, spawn } = require("child_process");
 const { promisify } = require("util");
 const fs = require("fs");
@@ -11,6 +11,7 @@ const os = require("os");
 const path = require("path");
 const { SCHEME, parseInstallLink, linkFromArgv } = require("./install-link");
 const updater = require("./updater");
+const { createMetaSignIn } = require("./meta-signin");
 
 const run = promisify(execFile);
 
@@ -348,6 +349,47 @@ ipcMain.handle("comfort:notify", (e, message) => {
   });
 });
 
+// ---- Sign in with Meta (app/meta-signin.js, docs/meta-library.md) ----
+// The token goes from the sign-in window's own session straight to the server's
+// connect path; the page asks for it and only hears the server's answer.
+function postApi(apiPath, body) {
+  return new Promise((resolve, reject) => {
+    if (!url) return reject(new Error("Frame Control's server isn't running."));
+    const data = JSON.stringify(body);
+    const req = http.request(new URL(apiPath, url), {
+      method: "POST", timeout: 60000,
+      headers: { "Content-Type": "application/json", "X-Frame-UI": process.env.FRAME_UI_KEY || "1",
+                 "Content-Length": Buffer.byteLength(data) },
+    }, (res) => {
+      let text = "";
+      res.setEncoding("utf8");
+      res.on("data", (c) => { text += c; });
+      res.on("end", () => {
+        let parsed = {};
+        try { parsed = JSON.parse(text); } catch {}
+        resolve({ status: res.statusCode, data: parsed });
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => req.destroy(new Error("the server didn't answer")));
+    req.end(data);
+  });
+}
+
+let metaSignIn = null;
+const meta = () => (metaSignIn ||= createMetaSignIn({
+  BrowserWindow, session, shell, parent: () => win,
+  // The page only offers sign-in after its "I understand" box is ticked (checked again below).
+  connect: (token, attempt) => postApi("/api/meta", { action: "connect", token, acknowledged: true, attempt }),
+  cancel: (attempt) => postApi("/api/meta", { action: "cancel-signin", attempt }),
+}));
+ipcMain.handle("meta:signin", (e, acknowledged) => {
+  if (!fromUi(e)) return null;
+  if (acknowledged !== true) return { ok: false, error: "My Meta library is experimental: tick that you understand the warning first." };
+  return meta().signIn();
+});
+ipcMain.handle("meta:signout", (e) => fromUi(e) ? meta().signOut() : false);
+
 // 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

app/meta-signin.js

@@ -0,0 +1,252 @@
+// "Sign in with Meta" for My Meta library (docs/meta-library.md), the way BSManager's
+// "Log in with Meta" works: Meta's own login page in a Frame Control window, then the
+// access token cookie (oc_ac_at) that page sets is handed to the local server's
+// existing connect path (format check, "who am I" with Meta, 0600 file).
+//
+// The window has its own persistent session (PARTITION), so the cookie is read only
+// from there: never from Frame Control's main window, never from any browser. It has
+// no preload and no Node, and it only navigates within Meta's login sites; anything
+// else opens in the system browser. Nothing here logs the token, and the page only
+// ever gets back the server's answer (connected, display name), never the token.
+// Electron is passed in, so app/test/meta-signin.test.js can run it with fakes.
+const crypto = require("crypto");
+
+const PARTITION = "persist:meta-signin";
+// BSManager's loginUrl (src/main/services/bs-version-download/bs-oculus-downloader.service.ts).
+const LOGIN_URL = "https://secure.oculus.com";
+const COOKIE = "oc_ac_at";
+// Sites the login can go through: the Oculus store web, Meta accounts, Facebook login,
+// and Instagram (Meta's login passes through www.instagram.com: seen live, 2026-10-14).
+const ALLOWED = ["oculus.com", "meta.com", "facebook.com", "instagram.com"];
+const TIMEOUT = 10 * 60 * 1000;  // as BSManager
+
+const underDomain = (host, domains) => {
+  host = String(host || "").replace(/^\./, "").toLowerCase();
+  return domains.some((d) => host === d || host.endsWith("." + d));
+};
+
+// Plain HTTPS on the default port, to one of the login sites.
+function allowedUrl(raw) {
+  let u;
+  try { u = new URL(String(raw)); } catch { return false; }
+  if (u.protocol !== "https:" || u.username || u.password || (u.port && u.port !== "443")) return false;
+  return underDomain(u.hostname, ALLOWED);
+}
+
+// Frames inside the page: any HTTPS address (Meta's login can embed captcha and CDN
+// frames from other sites), or an empty frame; never data:, blob:, javascript:, http:,
+// file: or any other scheme. Frames can't reach the cookie read or IPC (main process only).
+function allowedSubframeUrl(raw) {
+  if (/^about:(?:blank|srcdoc)$/.test(String(raw))) return true;
+  let u;
+  try { u = new URL(String(raw)); } catch { return false; }
+  return u.protocol === "https:" && !u.username && !u.password;
+}
+
+const onOculus = (raw) => { try { return underDomain(new URL(raw).hostname, ["oculus.com"]); } catch { return false; } };
+
+// A cheap first look, so a signed-out or app value is never sent anywhere; the server's
+// check_token (ui/frame_meta.py) has the final word.
+function looksLikeUserToken(v) {
+  return typeof v === "string" && /^(?:OC|FRL)[A-Za-z0-9+/=_-]{18,4093}$/.test(v)
+    && !/^OC\d{15}$/.test(v) && /[a-z]/.test(v);
+}
+
+const fingerprint = (v) => crypto.createHash("sha256").update(v).digest("hex");
+
+// Anything token-shaped out of a message, in case a server error ever carried one.
+function scrub(text, token) {
+  let s = String(text == null ? "" : text);
+  if (token) s = s.split(token).join("<redacted>");
+  return s.replace(/(?:OC|FRL)[A-Za-z0-9+/=_%|:-]{8,}/g, "<redacted>").slice(0, 600);
+}
+
+// deps: { BrowserWindow, session, shell, parent() -> BrowserWindow|null, timeout,
+//         connect(token, attempt) -> Promise<{status, data}>  (the server's connect action),
+//         cancel(attempt) -> Promise  (the server's cancel-signin: never save that attempt) }
+function createMetaSignIn({ BrowserWindow, session, shell, connect, cancel, parent = () => null, timeout = TIMEOUT }) {
+  let active = null;  // { win, promise, finish }
+  const pending = new Set();  // cancels still to reach the server, from flows already finished
+  let signingOut = null;      // the sign-out under way; no sign-in starts while it runs
+  const SIGNING_OUT = "Frame Control is signing out of Meta; try again in a moment.";
+
+  const openOutside = (target) => {
+    if (/^https?:\/\//i.test(String(target))) shell.openExternal(String(target));
+  };
+
+  function signIn() {
+    if (signingOut) return Promise.resolve({ ok: false, error: SIGNING_OUT });
+    if (active) { active.win.focus(); return active.promise; }
+    const ses = session.fromPartition(PARTITION);
+    ses.setPermissionRequestHandler((_wc, _permission, callback) => callback(false));
+    ses.setPermissionCheckHandler(() => false);
+    // Electron adds its own name and the app's to the user agent; send a plain Chrome one.
+    if (ses.getUserAgent && ses.setUserAgent) {
+      ses.setUserAgent(ses.getUserAgent().replace(/\s(?:Electron|frame-control|Frame Control)\/\S+/g, ""));
+    }
+    const p = parent();
+    const win = new BrowserWindow({
+      width: 520, height: 760, title: "Sign in with Meta – Frame Control", autoHideMenuBar: true,
+      ...(p ? { parent: p } : {}),
+      webPreferences: { partition: PARTITION, contextIsolation: true, nodeIntegration: false, sandbox: true,
+                        nodeIntegrationInSubFrames: false, webviewTag: false, safeDialogs: true, devTools: false },
+    });
+    const wc = win.webContents;
+
+    let resolve;
+    const promise = new Promise((r) => { resolve = r; });
+    let done = false, busy = false, again = false, lastError = null, blocked = null;
+    const tried = new Set();  // fingerprints of values already sent, so each goes once
+    // The server refuses to save a connect from an attempt this window gave up on.
+    const attemptId = crypto.randomUUID();
+
+    const onCookie = (_e, cookie, _cause, removed) => {
+      if (!removed && cookie && cookie.name === COOKIE && underDomain(cookie.domain, ["oculus.com"])) attempt();
+    };
+    const timer = setTimeout(() => finish({ ok: false, error: "Sign-in timed out after 10 minutes. Try again." }), timeout);
+    if (timer.unref) timer.unref();
+
+    // Stops cookie intake first, then the window (destroy: a page's beforeunload can't
+    // keep it open), and answers the page. Unless it connected, and if it sent a token, it
+    // then has the server drop this attempt: only once the connect under way has settled,
+    // so the server always sees the cancel after the connect (and deletes the token if
+    // that connect saved it). The returned promise settles when that is done.
+    let finished = null;
+    let inflight = null;  // the last connect sent
+    function finish(result) {
+      if (done) return finished || Promise.resolve();  // destroy() below re-enters through "closed"
+      done = true;
+      ses.cookies.removeListener("changed", onCookie);
+      clearTimeout(timer);
+      if (active && active.win === win) active = null;
+      if (!win.isDestroyed()) win.destroy();
+      resolve(result);
+      if (result.ok || !inflight) return (finished = Promise.resolve());  // nothing sent: nothing to cancel
+      finished = Promise.resolve(inflight).catch(() => {}).then(() => cancel(attemptId)).catch(() => {});
+      pending.add(finished);
+      finished.then(() => pending.delete(finished));
+      return finished;
+    }
+
+    async function attempt() {
+      if (done) return;
+      if (busy) { again = true; return; }
+      busy = true;
+      try {
+        do {
+          again = false;
+          // Only this window's own session, and only Meta's Oculus cookie.
+          const cookies = await ses.cookies.get({ name: COOKIE });
+          const c = cookies.find((k) => underDomain(k.domain, ["oculus.com"]) && looksLikeUserToken(k.value));
+          if (!c || done) continue;
+          const key = fingerprint(c.value);
+          if (tried.has(key)) continue;
+          tried.add(key);
+          let r;
+          try {
+            inflight = connect(c.value, attemptId);
+            r = await inflight;
+          } catch {
+            lastError = "Frame Control's local server didn't answer.";
+            continue;
+          }
+          if (done) return;
+          const d = (r && r.data) || {};
+          if (r && r.status === 200 && d.connected) {
+            finish({ ok: true, connected: true, user: d.user && d.user.name ? { name: scrub(d.user.name, c.value).slice(0, 80) } : null,
+                     message: scrub(d.message || "Connected your Meta account (Experimental)", c.value) });
+            return;
+          }
+          lastError = scrub(d.error || `HTTP ${r && r.status}`, c.value);
+        } while (again && !done);
+      } catch {
+        // The session went away (the window closed); nothing to do.
+      } finally {
+        busy = false;
+      }
+    }
+
+    // Navigation stays on Meta's login sites. A link elsewhere opens in the system
+    // browser; a redirect elsewhere is just stopped (it may carry sign-in data).
+    // Every frame: the window itself stays on the list; frames inside it may load any
+    // HTTPS page (captchas), and one going anywhere else is just stopped.
+    wc.on("will-navigate", (e, target) => { if (!allowedUrl(target)) { e.preventDefault(); openOutside(target); } });
+    // A stopped page change in the window itself says where it went (the host only), so
+    // closing the stuck window explains why instead of "closed before you signed in".
+    const stopped = (to) => {
+      let host = "";
+      try { host = new URL(String(to)).hostname; } catch { /* not an address */ }
+      blocked = `Meta's sign-in went to ${scrub(host || "an address", null).slice(0, 80)}, which Frame Control doesn't allow.`;
+    };
+    wc.on("will-frame-navigate", (e) => {
+      if (e.isMainFrame ? allowedUrl(e.url) : allowedSubframeUrl(e.url)) return;
+      e.preventDefault();
+      if (e.isMainFrame) stopped(e.url);
+    });
+    // Redirects fire for frames too: the same rule per frame (details on the event in
+    // current Electron, positional arguments in older ones; unknown counts as the window).
+    wc.on("will-redirect", (e, target, _inPlace, isMainFrame) => {
+      const to = e && e.url !== undefined ? e.url : target;
+      const main = e && e.isMainFrame !== undefined ? e.isMainFrame : isMainFrame !== false;
+      if (main ? allowedUrl(to) : allowedSubframeUrl(to)) return;
+      e.preventDefault();
+      if (main) stopped(to);
+    });
+    // A page's beforeunload never keeps the window open.
+    wc.on("will-prevent-unload", (e) => e.preventDefault());
+    wc.setWindowOpenHandler(({ url: target }) => {
+      if (allowedUrl(target)) wc.loadURL(target).catch(() => {});
+      else openOutside(target);
+      return { action: "deny" };
+    });
+    // Signed in: the cookie changes, or the window lands back on Meta's store site.
+    ses.cookies.on("changed", onCookie);
+    wc.on("did-navigate", (_e, target) => { blocked = null; if (onOculus(target)) attempt(); });  // it recovered
+    wc.on("did-navigate-in-page", (_e, target) => { if (onOculus(target)) attempt(); });
+    win.on("closed", () => finish({ ok: false, cancelled: true,
+      error: lastError ? `The sign-in window closed before Frame Control could connect. ${lastError}`
+           : blocked ? `The sign-in window was closed before you signed in. ${blocked}`
+                     : "The sign-in window was closed before you signed in." }));
+
+    active = { win, promise, finish };
+    wc.loadURL(LOGIN_URL).catch(() => {});
+    return promise;
+  }
+
+  // Signs out of Meta in Frame Control: stops any sign-in under way (and has the server
+// refuse to save it), destroys the window, then clears everything
+  // the sign-in session stored (cookies, storage, cache), so the next sign-in starts fresh.
+  // One at a time (a second call joins the first), and no sign-in can start meanwhile.
+  // It goes round until no window is open and no connect or cancel is left, so nothing
+  // started before it can set a token after it (or after the Disconnect that follows).
+  function signOut() {
+    if (!signingOut) {
+      signingOut = (async () => {
+        for (;;) {
+          if (active) {
+            const { win, finish } = active;
+            await finish({ ok: false, cancelled: true, error: "Signed out of Meta in Frame Control." });
+            // Clear only once nothing can write to the session again.
+            if (!win.isDestroyed()) throw new Error("The Sign in with Meta window didn't close; try again.");
+          } else if (pending.size) {
+            // A connect under way settles and is cancelled before the caller (Disconnect)
+            // deletes the account, so it can't be saved afterwards.
+            await Promise.all([...pending]);
+          } else {
+            break;
+          }
+        }
+        const ses = session.fromPartition(PARTITION);
+        await ses.clearStorageData();
+        await ses.clearCache();
+        if (ses.clearAuthCache) await ses.clearAuthCache();
+        return true;
+      })().finally(() => { signingOut = null; });
+    }
+    return signingOut;
+  }
+
+  return { signIn, signOut, isOpen: () => !!active, isSigningOut: () => !!signingOut };
+}
+
+module.exports = { createMetaSignIn, allowedUrl, allowedSubframeUrl, looksLikeUserToken, scrub, PARTITION, LOGIN_URL, COOKIE, ALLOWED };

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.6",
+      "version": "0.4.7",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",
@@ -11,8 +11,9 @@
     "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 arm64 && electron-builder --linux --x64 --arm64 --publish never",
-    "dist:win": "node build/fetch-deps.js win x64 && electron-builder --win --x64 --publish never"
+    "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"
   },
   "devDependencies": {
     "electron": "^44.4.5",
@@ -39,6 +40,7 @@
       "preload.js",
       "install-link.js",
       "updater.js",
+      "meta-signin.js",
       "package.json",
       "build/icon.png"
     ],
@@ -183,7 +185,16 @@
         "entry": {
           "StartupWMClass": "frame-control"
         }
-      }
+      },
+      "extraResources": [
+        {
+          "from": "build/desktop/${os}-${arch}",
+          "to": "desktop/bundle",
+          "filter": [
+            "**/*"
+          ]
+        }
+      ]
     },
     "deb": {
       "depends": [
@@ -196,7 +207,16 @@
         "zip"
       ],
       "icon": "build/icon.png",
-      "artifactName": "Frame-Control-win-${arch}.${ext}"
+      "artifactName": "Frame-Control-win-${arch}.${ext}",
+      "extraResources": [
+        {
+          "from": "build/desktop/${os}-${arch}",
+          "to": "desktop/bundle",
+          "filter": [
+            "**/*"
+          ]
+        }
+      ]
     },
     "nsis": {
       "oneClick": false,

app/preload.js

@@ -6,7 +6,8 @@
 // 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.
+// And it passes update state both ways: see app/updater.js. It opens the Sign in
+// with Meta window and signs out of it (app/meta-signin.js).
 const { contextBridge, ipcRenderer, webUtils } = require("electron");
 
 contextBridge.exposeInMainWorld("frameApp", {
@@ -39,6 +40,12 @@ contextBridge.exposeInMainWorld("frameApp", {
     ipcRenderer.removeAllListeners("report:open");
     ipcRenderer.on("report:open", () => cb());
   },
+  // Sign in with Meta (app/meta-signin.js): Meta's login page in its own window. The
+  // answer is the server's (connected, display name), never the token.
+  meta: {
+    signIn: (acknowledged) => ipcRenderer.invoke("meta:signin", acknowledged === true),
+    signOut: () => ipcRenderer.invoke("meta:signout"),
+  },
   onInstallLink: (cb) => {
     ipcRenderer.removeAllListeners("install-link");
     ipcRenderer.on("install-link", (_e, req) => cb({ kind: req.kind, target: req.target }));

app/test/meta-signin.test.js

@@ -0,0 +1,578 @@
+// Run: node --test app/test/
+// "Sign in with Meta" (app/meta-signin.js) with fake Electron windows, sessions and cookies.
+const nodeTest = require("node:test");
+// A broken flow can leave a sign-in waiting forever; fail it instead of hanging.
+const test = (name, fn) => nodeTest(name, { timeout: 5000 }, fn);
+const assert = require("node:assert");
+const { EventEmitter } = require("node:events");
+const { createMetaSignIn, allowedUrl, looksLikeUserToken, scrub, PARTITION, LOGIN_URL, COOKIE } = require("../meta-signin");
+
+const TOKEN = "OCAbcdefghijklmnopQRSTUVwxyz0123456789abcdEFGH";
+const OTHER = "OCzyxwvutsrqponmlkJIHGFEDcba9876543210zyxwVUTS";
+
+class FakeCookies extends EventEmitter {
+  constructor() { super(); this.store = []; this.reads = 0; }
+  async get(filter) {
+    this.reads++;
+    return this.store.filter((c) => !filter.name || c.name === filter.name);
+  }
+  set(cookie) {  // as the page would: store it, then tell listeners
+    this.store = this.store.filter((c) => !(c.name === cookie.name && c.domain === cookie.domain)).concat(cookie);
+    this.emit("changed", {}, cookie, "explicit", false);
+  }
+}
+
+class FakeSession {
+  constructor(name, log) { this.name = name; this.log = log; this.cookies = new FakeCookies(); this.cleared = []; this.permission = null; }
+  setPermissionRequestHandler(fn) { this.permission = fn; }
+  setPermissionCheckHandler(fn) { this.permissionCheck = fn; }
+  getUserAgent() { return "Mozilla/5.0 Chrome/140.0 frame-control/0.4.4 Electron/44.4.5 Safari/537.36"; }
+  setUserAgent(ua) { this.ua = ua; }
+  async clearStorageData(opts) { this.log.push("clear"); this.cleared.push(["storage", opts]); }
+  async clearCache() { this.cleared.push(["cache"]); }
+  async clearAuthCache() { this.cleared.push(["auth"]); }
+}
+
+function fakes({ timeout } = {}) {
+  const log = [];  // the order things happened in
+  const sessions = new Map();
+  const defaultSession = new FakeSession("default", log);
+  const session = {
+    defaultSession,
+    fromPartition(name) {
+      if (!sessions.has(name)) sessions.set(name, new FakeSession(name, log));
+      return sessions.get(name);
+    },
+  };
+  const windows = [];
+  class BrowserWindow extends EventEmitter {
+    constructor(opts) {
+      super();
+      this.opts = opts;
+      this.destroyed = false;
+      this.veto = false;  // a page whose beforeunload keeps the window open on close()
+      this.focused = 0;
+      const wc = new EventEmitter();
+      wc.loaded = [];
+      wc.loadURL = async (u) => { wc.loaded.push(u); };
+      wc.setWindowOpenHandler = (fn) => { wc.openHandler = fn; };
+      // Deliberately a different session: the code must read the partition's, not guess.
+      wc.session = defaultSession;
+      this.webContents = wc;
+      windows.push(this);
+    }
+    isDestroyed() { return this.destroyed; }
+    focus() { this.focused++; }
+    close() { if (this.destroyed || this.veto) return; this.destroy(); }
+    destroy() { if (this.destroyed) return; this.destroyed = true; log.push("destroyed"); this.emit("closed"); }
+  }
+  const opened = [];
+  const shell = { openExternal: (u) => { opened.push(u); } };
+  const calls = [], attempts = [], cancels = [];
+  let answer = () => ({ status: 200, data: { connected: true, user: { name: "Alex" }, message: "Connected your Meta account (Experimental)" } });
+  const connect = async (token, attempt) => { calls.push(token); attempts.push(attempt); log.push("connect"); return answer(token); };
+  const cancel = async (attempt) => {
+    cancels.push(attempt);
+    log.push(`cancel (cookie listeners: ${session.fromPartition(PARTITION).cookies.listenerCount("changed")})`);
+  };
+  const flow = createMetaSignIn({ BrowserWindow, session, shell, connect, cancel, parent: () => null, ...(timeout ? { timeout } : {}) });
+  return { flow, session, sessions, windows, opened, calls, attempts, cancels, log, setAnswer: (fn) => { answer = fn; },
+           meta: () => session.fromPartition(PARTITION) };
+}
+
+const tick = () => new Promise((r) => setImmediate(r));
+async function settle() { for (let i = 0; i < 10; i++) await tick(); }
+
+function navigate(wc, event, target) {
+  let prevented = false;
+  wc.emit(event, { preventDefault: () => { prevented = true; } }, target);
+  return prevented;
+}
+
+test("only plain HTTPS addresses on Meta's login sites are allowed", () => {
+  for (const ok of ["https://secure.oculus.com", "https://secure.oculus.com/my/profile", "https://auth.meta.com/login/",
+                    "https://www.meta.com/", "https://www.facebook.com/login.php", "https://oculus.com:443/",
+                    "https://www.instagram.com/accounts/login/"]) {
+    assert.ok(allowedUrl(ok), ok);
+  }
+  for (const bad of ["http://secure.oculus.com/", "https://oculus.com.evil.example/", "https://evil-oculus.com/",
+                     "https://notmeta.com/", "https://example.com/", "javascript:alert(1)", "file:///etc/passwd",
+                     "https://secure.oculus.com:8443/", "https://user:pw@secure.oculus.com/", "https://evil.example/?u=https://www.meta.com",
+                     "data:text/html,hi", "not a url"]) {
+    assert.ok(!allowedUrl(bad), bad);
+  }
+});
+
+test("the window is isolated: its own partition, no preload, no Node, sandboxed, on Meta's login page", async () => {
+  const f = fakes();
+  f.flow.signIn();
+  const [w] = f.windows;
+  const wp = w.opts.webPreferences;
+  assert.strictEqual(wp.partition, PARTITION);
+  assert.strictEqual(PARTITION, "persist:meta-signin");
+  assert.strictEqual(wp.contextIsolation, true);
+  assert.strictEqual(wp.nodeIntegration, false);
+  assert.strictEqual(wp.sandbox, true);
+  assert.strictEqual(wp.preload, undefined);
+  assert.strictEqual(wp.devTools, false);
+  assert.deepStrictEqual(w.webContents.loaded, [LOGIN_URL]);
+  assert.strictEqual(LOGIN_URL, "https://secure.oculus.com");
+  // Permission prompts (camera, notifications...) are refused.
+  let granted = null;
+  f.meta().permission(null, "media", (v) => { granted = v; });
+  assert.strictEqual(granted, false);
+  assert.strictEqual(f.meta().permissionCheck(null, "notifications", "https://secure.oculus.com"), false);
+  assert.ok(!/Electron|frame-control/.test(f.meta().ua));
+  w.close();
+});
+
+test("navigation stays on Meta's sites; other links open in the system browser", async () => {
+  const f = fakes();
+  f.flow.signIn();
+  const wc = f.windows[0].webContents;
+  assert.strictEqual(navigate(wc, "will-navigate", "https://auth.meta.com/login/"), false);
+  assert.strictEqual(navigate(wc, "will-navigate", "https://www.facebook.com/login.php"), false);
+  assert.strictEqual(navigate(wc, "will-navigate", "https://example.com/help"), true);
+  assert.deepStrictEqual(f.opened, ["https://example.com/help"]);
+  // A redirect elsewhere is stopped and not opened anywhere (it may carry sign-in data).
+  assert.strictEqual(navigate(wc, "will-redirect", "https://evil.example/cb?x=1"), true);
+  assert.strictEqual(navigate(wc, "will-redirect", "https://auth.meta.com/next"), false);
+  assert.deepStrictEqual(f.opened, ["https://example.com/help"]);
+  // New windows: never created. Meta's own load in this window; others go outside; non-web schemes nowhere.
+  assert.deepStrictEqual(wc.openHandler({ url: "https://www.meta.com/legal/terms/" }), { action: "deny" });
+  assert.deepStrictEqual(wc.openHandler({ url: "https://example.org/" }), { action: "deny" });
+  assert.deepStrictEqual(wc.openHandler({ url: "file:///etc/passwd" }), { action: "deny" });
+  await settle();
+  assert.deepStrictEqual(wc.loaded, [LOGIN_URL, "https://www.meta.com/legal/terms/"]);
+  assert.deepStrictEqual(f.opened, ["https://example.com/help", "https://example.org/"]);
+  f.windows[0].close();
+});
+
+test("the cookie is read only from the sign-in partition, only for Meta's Oculus domain", async () => {
+  const f = fakes();
+  // The same cookie elsewhere: the default session and another partition. Never read.
+  f.session.defaultSession.cookies.store.push({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  f.session.fromPartition("persist:other").cookies.store.push({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  const done = f.flow.signIn();
+  const w = f.windows[0];
+  // A cookie with the right name on another site, and a signed-out value: ignored.
+  f.meta().cookies.set({ name: COOKIE, domain: ".evil.example", value: OTHER });
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: "OC123456789012345" });
+  w.webContents.emit("did-navigate", {}, "https://secure.oculus.com/my/profile");
+  await settle();
+  assert.deepStrictEqual(f.calls, []);
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  const r = await done;
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+  assert.strictEqual(r.ok, true);
+  assert.strictEqual(f.session.defaultSession.cookies.reads, 0);
+  assert.strictEqual(f.session.fromPartition("persist:other").cookies.reads, 0);
+  assert.ok(f.sessions.get(PARTITION).cookies.reads > 0);
+});
+
+test("landing on the logged-in page picks up a cookie set earlier", async () => {
+  const f = fakes();
+  const done = f.flow.signIn();
+  f.meta().cookies.store.push({ name: COOKIE, domain: "secure.oculus.com", value: TOKEN });  // no change event
+  f.windows[0].webContents.emit("did-navigate", {}, "https://auth.meta.com/login/");  // not Meta's store site yet
+  await settle();
+  assert.deepStrictEqual(f.calls, []);
+  f.windows[0].webContents.emit("did-navigate", {}, "https://secure.oculus.com/my/profile");
+  assert.strictEqual((await done).ok, true);
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+});
+
+test("after a connect the window closes, and the page gets the answer, never the token", async () => {
+  const f = fakes();
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  const r = await done;
+  assert.ok(f.windows[0].isDestroyed());
+  assert.ok(!f.flow.isOpen());
+  assert.deepStrictEqual(r, { ok: true, connected: true, user: { name: "Alex" }, message: "Connected your Meta account (Experimental)" });
+  assert.ok(!JSON.stringify(r).includes(TOKEN));
+  // The cookie listener is gone: a later change sends nothing.
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  await settle();
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+});
+
+test("a token the server refuses keeps the window open, is sent once, and the next one connects", async () => {
+  const f = fakes();
+  f.setAnswer((t) => t === TOKEN ? { status: 400, data: { error: "Meta didn't accept this token." } }
+                                 : { status: 200, data: { connected: true, user: null } });
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.windows[0].webContents.emit("did-navigate", {}, "https://secure.oculus.com/my/profile");  // same value again
+  await settle();
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+  assert.ok(!f.windows[0].isDestroyed());
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  const r = await done;
+  assert.deepStrictEqual(f.calls, [TOKEN, OTHER]);
+  assert.strictEqual(r.ok, true);
+  assert.strictEqual(r.user, null);
+});
+
+test("the token is never logged, and an error that echoed it is scrubbed", async () => {
+  const seen = [];
+  const names = ["log", "info", "warn", "error", "debug", "trace"];
+  const saved = Object.fromEntries(names.map((n) => [n, console[n]]));
+  const writes = [process.stdout.write, process.stderr.write];
+  for (const n of names) console[n] = (...a) => { seen.push(a.map(String).join(" ")); };
+  process.stdout.write = (c, ...rest) => { seen.push(String(c)); return writes[0].call(process.stdout, c, ...rest); };
+  process.stderr.write = (c, ...rest) => { seen.push(String(c)); return writes[1].call(process.stderr, c, ...rest); };
+  let r;
+  try {
+    const f = fakes();
+    f.setAnswer((t) => ({ status: 500, data: { error: `RuntimeError: bad ${t} and ${t.slice(0, 12)}` } }));
+    const done = f.flow.signIn();
+    f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+    await settle();
+    f.windows[0].close();  // the user gives up
+    r = await done;
+  } finally {
+    for (const n of names) console[n] = saved[n];
+    [process.stdout.write, process.stderr.write] = writes;
+  }
+  assert.strictEqual(r.ok, false);
+  assert.strictEqual(r.cancelled, true);
+  assert.ok(!r.error.includes(TOKEN) && !r.error.includes(TOKEN.slice(0, 12)), r.error);
+  assert.match(r.error, /<redacted>/);
+  assert.ok(!seen.some((s) => s.includes(TOKEN.slice(0, 12))), "token in output");
+  assert.strictEqual(scrub(`x FRL${"a".repeat(30)} y`), "x <redacted> y");
+});
+
+test("closing the window before signing in reports it, and a second click reuses the open window", async () => {
+  const f = fakes();
+  const a = f.flow.signIn();
+  const b = f.flow.signIn();
+  assert.strictEqual(a, b);
+  assert.strictEqual(f.windows.length, 1);
+  assert.strictEqual(f.windows[0].focused, 1);
+  f.windows[0].close();
+  const r = await a;
+  assert.deepStrictEqual(r, { ok: false, cancelled: true, error: "The sign-in window was closed before you signed in." });
+  assert.deepStrictEqual(f.calls, []);
+});
+
+test("disconnect's sign-out closes the window and clears only the sign-in partition", async () => {
+  const f = fakes();
+  f.session.fromPartition("persist:other");
+  const pending = f.flow.signIn();
+  await f.flow.signOut();
+  const r = await pending;
+  assert.strictEqual(r.ok, false);
+  assert.ok(f.windows[0].isDestroyed());
+  assert.deepStrictEqual(f.meta().cleared, [["storage", undefined], ["cache"], ["auth"]]);
+  assert.deepStrictEqual(f.session.defaultSession.cleared, []);
+  assert.deepStrictEqual(f.session.fromPartition("persist:other").cleared, []);
+  // The next sign-in starts with a new window.
+  f.flow.signIn();
+  assert.strictEqual(f.windows.length, 2);
+  f.windows[1].close();
+});
+
+test("the first look at a cookie value matches the server's token rules", () => {
+  assert.ok(looksLikeUserToken(TOKEN));
+  assert.ok(looksLikeUserToken("FRL" + "aB3".repeat(10)));
+  for (const bad of [undefined, "", "OC123456789012345", "OC|123|abc", "OCabc%2Fdef" + "x".repeat(20), "OCshort",
+                     "XY" + "a".repeat(30), "OC" + "A".repeat(30)]) {
+    assert.ok(!looksLikeUserToken(bad), String(bad));
+  }
+});
+
+function frameNav(wc, url, isMainFrame) {
+  let prevented = false;
+  wc.emit("will-frame-navigate", { url, isMainFrame, preventDefault: () => { prevented = true; } });
+  return prevented;
+}
+
+test("the window stays on Meta's sites; frames inside it may load any HTTPS page, nothing else", async () => {
+  const f = fakes();
+  f.flow.signIn();
+  const wc = f.windows[0].webContents;
+  // Frames: captcha and CDN frames from other sites load; other schemes are stopped.
+  for (const ok of ["https://client-api.arkoselabs.com/fc/gc/", "https://newassets.hcaptcha.com/captcha/v1/x",
+                    "https://www.google.com/recaptcha/api2/anchor", "https://static.xx.fbcdn.net/x",
+                    "https://www.facebook.com/plugin", "about:blank", "about:srcdoc"]) {
+    assert.strictEqual(frameNav(wc, ok, false), false, ok);
+  }
+  for (const bad of ["http://www.facebook.com/plugin", "data:text/html,<script>x</script>", "blob:https://evil.example/1",
+                     "javascript:alert(1)", "file:///etc/passwd", "ftp://example.com/", "https://u:p@evil.example/",
+                     "chrome://settings", "not a url"]) {
+    assert.strictEqual(frameNav(wc, bad, false), true, bad);
+  }
+  // The window itself: Meta's sites only.
+  assert.strictEqual(frameNav(wc, "about:blank", true), true);
+  assert.strictEqual(frameNav(wc, "https://evil.example/", true), true);
+  assert.strictEqual(frameNav(wc, "https://client-api.arkoselabs.com/", true), true);
+  assert.strictEqual(frameNav(wc, "https://auth.meta.com/login/", true), false);
+  assert.deepStrictEqual(f.opened, []);  // stopped, never opened outside
+  f.windows[0].destroy();
+});
+
+function redirect(wc, url, isMainFrame, style) {
+  let prevented = false;
+  const e = { preventDefault: () => { prevented = true; } };
+  if (style === "details") wc.emit("will-redirect", Object.assign(e, { url, isMainFrame }));
+  else wc.emit("will-redirect", e, url, false, isMainFrame);
+  return prevented;
+}
+
+test("redirects follow the same rule per frame", async () => {
+  const f = fakes();
+  f.flow.signIn();
+  const wc = f.windows[0].webContents;
+  for (const style of ["details", "positional"]) {
+    // A captcha frame redirected within HTTPS loads; a frame redirected to data: or http: doesn't.
+    assert.strictEqual(redirect(wc, "https://client-api.arkoselabs.com/v2/next", false, style), false, style);
+    assert.strictEqual(redirect(wc, "https://newassets.hcaptcha.com/x", false, style), false, style);
+    assert.strictEqual(redirect(wc, "data:text/html,<b>x</b>", false, style), true, style);
+    assert.strictEqual(redirect(wc, "http://www.facebook.com/x", false, style), true, style);
+    assert.strictEqual(redirect(wc, "javascript:alert(1)", false, style), true, style);
+    // The window: Meta's sites only.
+    assert.strictEqual(redirect(wc, "https://client-api.arkoselabs.com/v2/next", true, style), true, style);
+    assert.strictEqual(redirect(wc, "https://auth.meta.com/next", true, style), false, style);
+  }
+  // Without frame information it is treated as the window.
+  assert.strictEqual(redirect(wc, "https://client-api.arkoselabs.com/", undefined, "positional"), true);
+  assert.deepStrictEqual(f.opened, []);
+  f.windows[0].destroy();
+});
+
+test("a redirect the window stops is named when the window is closed", async () => {
+  const f = fakes();
+  const p = f.flow.signIn();
+  const wc = f.windows[0].webContents;
+  assert.strictEqual(redirect(wc, "https://www.instagram.com/x?next=1", true, "details"), false);  // Meta's login goes here
+  assert.strictEqual(redirect(wc, "https://login.evil.example/cb?code=SECRET", true, "details"), true);
+  f.windows[0].close();
+  const r = await p;
+  assert.strictEqual(r.ok, false);
+  assert.match(r.error, /went to login\.evil\.example, which Frame Control doesn't allow/);
+  assert.doesNotMatch(r.error, /SECRET|code=/);
+});
+
+test("a stopped redirect is forgotten once the window loads a page again", async () => {
+  const f = fakes();
+  const p = f.flow.signIn();
+  const wc = f.windows[0].webContents;
+  assert.strictEqual(redirect(wc, "https://login.evil.example/cb", true, "details"), true);
+  wc.emit("did-navigate", {}, "https://auth.meta.com/login/");  // the user carried on
+  f.windows[0].close();
+  assert.deepStrictEqual(await p, { ok: false, cancelled: true, error: "The sign-in window was closed before you signed in." });
+});
+
+test("a page's beforeunload can't keep the window open", async () => {
+  const f = fakes();
+  const done = f.flow.signIn();
+  const w = f.windows[0];
+  let prevented = false;
+  w.webContents.emit("will-prevent-unload", { preventDefault: () => { prevented = true; } });
+  assert.ok(prevented);
+  // Even if close() would be vetoed, finishing destroys the window.
+  w.veto = true;
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  assert.strictEqual((await done).ok, true);
+  assert.ok(w.isDestroyed());
+});
+
+test("closing during a connect: the cancel goes to the server only after that connect settles", async () => {
+  for (const outcome of ["saved", "refused", "failed"]) {
+    const f = fakes();
+    let release, fail;
+    f.setAnswer(() => new Promise((r, j) => { release = r; fail = j; }));
+    const done = f.flow.signIn();
+    f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+    await settle();
+    assert.deepStrictEqual(f.calls, [TOKEN]);
+    f.windows[0].close();  // the user gives up while the server and Meta are answering
+    const r = await done;  // the page hears at once
+    assert.strictEqual(r.ok, false);
+    await settle();
+    assert.deepStrictEqual(f.cancels, [], outcome);  // not before the connect has settled
+    if (outcome === "saved") release({ status: 200, data: { connected: true } });
+    else if (outcome === "refused") release({ status: 400, data: { error: "no" } });
+    else fail(new Error("socket hang up"));
+    await settle();
+    // The same attempt id the connect carried, after it settled and after cookie intake stopped.
+    assert.deepStrictEqual(f.cancels, [f.attempts[0]], outcome);
+    assert.match(f.cancels[0], /^[A-Za-z0-9-]{8,64}$/);
+    assert.deepStrictEqual(f.log, ["connect", "destroyed", "cancel (cookie listeners: 0)"], outcome);
+    assert.deepStrictEqual(f.calls, [TOKEN]);
+  }
+});
+
+test("closing before any connect needs no cancel", async () => {
+  const f = fakes();
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".evil.example", value: TOKEN });  // nothing usable
+  await settle();
+  f.windows[0].close();
+  assert.strictEqual((await done).ok, false);
+  await f.flow.signOut();
+  await settle();
+  assert.deepStrictEqual(f.calls, []);
+  assert.deepStrictEqual(f.cancels, []);
+});
+
+test("a timeout during a connect cancels after it settles", async () => {
+  const f = fakes({ timeout: 50 });
+  let release;
+  f.setAnswer(() => new Promise((r) => { release = r; }));  // Meta is slow
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  const r = await done;
+  assert.match(r.error, /timed out/);
+  assert.ok(f.windows[0].isDestroyed());
+  assert.deepStrictEqual(f.cancels, []);
+  release({ status: 400, data: { error: "no" } });
+  await settle();
+  assert.deepStrictEqual(f.cancels, [f.attempts[0]]);
+});
+
+test("disconnect during a connect waits for it, cancels it, then clears, before the page deletes the account", async () => {
+  const f = fakes();
+  let release;
+  f.setAnswer(() => new Promise((r) => { release = r; }));
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.log.length = 0;
+  let signedOut = false;
+  const out = f.flow.signOut().then(() => { signedOut = true; });  // the page's Disconnect, step one
+  assert.strictEqual((await done).ok, false);
+  await settle();
+  assert.strictEqual(signedOut, false);  // still waiting for the connect
+  assert.deepStrictEqual(f.cancels, []);
+  release({ status: 200, data: { connected: true } });  // it saved, just now
+  await out;
+  // Only now would the page post its disconnect: the cancel (which deletes what that
+  // connect saved) has reached the server, and the session is cleared.
+  assert.deepStrictEqual(f.log, ["destroyed", "cancel (cookie listeners: 0)", "clear"]);
+  assert.deepStrictEqual(f.cancels, [f.attempts[0]]);
+});
+
+test("a later disconnect still waits for a closed window's connect", async () => {
+  const f = fakes();
+  let release;
+  f.setAnswer(() => new Promise((r) => { release = r; }));
+  const done = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.windows[0].close();
+  await done;
+  let signedOut = false;
+  const out = f.flow.signOut().then(() => { signedOut = true; });
+  await settle();
+  assert.strictEqual(signedOut, false);
+  release({ status: 400, data: { error: "no" } });
+  await out;
+  assert.deepStrictEqual(f.cancels, [f.attempts[0]]);
+});
+
+test("nothing sent means nothing to cancel; sign-out destroys the window, cancels, then clears", async () => {
+  const f = fakes();
+  // Nothing sent: closing cancels nothing.
+  const a = f.flow.signIn();
+  f.windows[0].close();
+  await a;
+  assert.deepStrictEqual(f.cancels, []);
+  // Something sent, then signed out: the attempt is cancelled before the session is cleared.
+  f.setAnswer(() => ({ status: 400, data: { error: "Meta didn't accept this token." } }));
+  const b = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.windows[1].veto = true;  // and its page tries to stay open
+  f.log.length = 0;
+  await f.flow.signOut();
+  assert.strictEqual((await b).ok, false);
+  assert.ok(f.windows[1].isDestroyed());
+  assert.deepStrictEqual(f.log, ["destroyed", "cancel (cookie listeners: 0)", "clear"]);
+  assert.deepStrictEqual(f.cancels, [f.attempts[0]]);
+  // After sign-out a new cookie in the partition sends nothing.
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  await settle();
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+});
+
+test("each sign-in has its own attempt id", async () => {
+  const f = fakes();
+  f.setAnswer(() => ({ status: 400, data: { error: "no" } }));
+  const a = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.windows[0].close();
+  await a;
+  const b = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  await settle();
+  f.windows[1].close();
+  await b;
+  await settle();
+  assert.strictEqual(f.attempts.length, 2);
+  assert.notStrictEqual(f.attempts[0], f.attempts[1]);
+  assert.deepStrictEqual(f.cancels, f.attempts);
+});
+
+test("no sign-in can start while a sign-out waits on an earlier connect", async () => {
+  const f = fakes();
+  let release;
+  f.setAnswer(() => new Promise((r) => { release = r; }));
+  const first = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  const out = f.flow.signOut();  // Disconnect pressed while that connect is under way
+  assert.strictEqual((await first).ok, false);
+  assert.ok(f.flow.isSigningOut());
+  // The page answered, so the user tries again at once: refused, no window, nothing sent.
+  const second = await f.flow.signIn();
+  assert.deepStrictEqual(second, { ok: false, error: "Frame Control is signing out of Meta; try again in a moment." });
+  assert.strictEqual(f.windows.length, 1);
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  await settle();
+  assert.deepStrictEqual(f.calls, [TOKEN]);
+  // A second sign-out joins the first.
+  assert.strictEqual(f.flow.signOut(), out);
+  release({ status: 200, data: { connected: true } });
+  await out;
+  assert.deepStrictEqual(f.cancels, [f.attempts[0]]);
+  assert.strictEqual(f.meta().cleared.filter(([k]) => k === "storage").length, 1);
+  assert.ok(!f.flow.isSigningOut());
+  // Once it is done, signing in works again.
+  f.setAnswer(() => ({ status: 200, data: { connected: true } }));
+  const third = f.flow.signIn();
+  assert.strictEqual(f.windows.length, 2);
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  assert.strictEqual((await third).ok, true);
+});
+
+test("sign-out goes round until no window and no connect or cancel is left", async () => {
+  const f = fakes();
+  let releaseA;
+  f.setAnswer(() => new Promise((r) => { releaseA = r; }));
+  const a = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: TOKEN });
+  await settle();
+  f.windows[0].close();  // window A closed; its cancel waits on its connect
+  await a;
+  // Window B is open, with its own connect under way, when sign-out starts.
+  let releaseB;
+  f.setAnswer(() => new Promise((r) => { releaseB = r; }));
+  const b = f.flow.signIn();
+  f.meta().cookies.set({ name: COOKIE, domain: ".oculus.com", value: OTHER });
+  await settle();
+  let finished = false;
+  const out = f.flow.signOut().then(() => { finished = true; });
+  await b;
+  releaseB({ status: 400, data: { error: "no" } });
+  await settle();
+  assert.strictEqual(finished, false);  // A's connect is still under way
+  releaseA({ status: 200, data: { connected: true } });
+  await out;
+  assert.deepStrictEqual([...f.cancels].sort(), [...f.attempts].sort());
+  assert.strictEqual(f.attempts.length, 2);
+  assert.strictEqual(f.log[f.log.length - 1], "clear");
+});

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

@@ -0,0 +1,311 @@
+{
+ "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

@@ -0,0 +1,302 @@
+{
+ "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

@@ -0,0 +1,16 @@
+#!/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

@@ -0,0 +1,118 @@
+#!/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

@@ -0,0 +1,125 @@
+/* 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

@@ -0,0 +1,127 @@
+/* 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

@@ -0,0 +1,29 @@
+/* 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

@@ -0,0 +1,147 @@
+/* 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/apks.md

@@ -39,6 +39,12 @@ section below), instead of going into Lepton Development:
    run at once alongside Lepton Development, each in its own container
    (`lepton-steamlaunch-<id>`, ADB on 5556, 5557, …).
 
+Split APKs (a base plus `split_*.apk` files) install as one app:
+`python3 ui/frame_android.py install base.apk split1.apk …`. Lepton runs one
+APK, so splits that add native libraries or assets are merged into the base
+and re-signed; density and language splits are refused. See
+[quest-import.md](quest-import.md#split-apks). Not yet tried on a real Frame.
+
 Verified with AntennaPod and Tabletop Tools: installed in about 7 s, launched
 from the shortcut, stopped, and relaunched with their data intact. ADB and
 Lepton Development aren't involved.

docs/meta-library.md

@@ -0,0 +1,371 @@
+# My Meta library (Experimental)
+
+Install Quest games your Meta account owns straight from Meta, test whether
+they run on the Steam Frame, and add the result to the shared compatibility
+reports. It is off until you connect, and it lives in **Android → My Meta
+library**.
+
+**Read this first.** My Meta library uses Meta's undocumented internal API
+with your own Meta access token, as the open-source tools QAVS, DownQuest and
+BSManager do. It may stop working whenever Meta changes things, and using it
+may be against Meta's terms. Your account is your responsibility. Frame
+Control is unofficial and not made or endorsed by Meta or Valve.
+
+What it will and won't do:
+
+- It lists and downloads only games your account owns (its active
+  entitlements). It never downloads anything else.
+- It installs games as Meta ships them. There is **no licence-check bypass**:
+  no patching, no stub libraries, no OVRPort or FramePort. A game that
+  enforces Meta's licence check may quit or hang on the Frame, because that
+  check needs Meta's services, which the Frame doesn't have.
+- Game files go only to a cache folder on your computer and then to your
+  Frame. They are deleted from the cache after each install, and never
+  uploaded or shared. Reports carry results only (below), never files or your
+  token.
+
+## Your token
+
+Frame Control never reads your browser's cookies. There are two ways to give
+it your token.
+
+**Sign in with Meta** (desktop app only; a plain browser doesn't show it).
+Tick **I understand…**, then choose **Sign in with Meta…**. Meta's own login
+page (`https://secure.oculus.com`, the address BSManager's "Log in with Meta"
+opens) appears in a Frame Control window. Sign in there as usual. When Meta's
+site sets its access token cookie (`oc_ac_at`), Frame Control takes it from
+that window, connects with it exactly as if you had pasted it (below), and
+closes the window. The window:
+
+- has its own storage (the Electron session `persist:meta-signin`), separate
+  from Frame Control's main window and from every browser on your computer;
+  the cookie is read only from there, and only for `oculus.com`;
+- runs Meta's page sandboxed, with no access to Frame Control (no preload, no
+  Node, context isolation on, no developer tools) and every permission request
+  or check (camera, notifications…) refused;
+- only goes to `https://` pages on `oculus.com`, `meta.com`, `facebook.com` and
+  `instagram.com` (and their subdomains; Meta's login passes through Instagram).
+  A link anywhere else opens in your system browser; a redirect anywhere else
+  is stopped, and closing the window then says where it went. Pop-ups on those sites open in the same
+  window. Frames inside the page may load any `https://` page (Meta's login
+  can embed captcha and CDN frames from other sites, such as Arkose Labs,
+  hCaptcha, reCAPTCHA or fbcdn) or an empty frame (`about:blank`,
+  `about:srcdoc`); a frame going to any other scheme (`http:`, `data:`,
+  `blob:`, `javascript:`, `file:`…) is just stopped. Redirects follow the same
+  rule for the frame they happen in. Frames can't reach the
+  token: the cookie is read by Frame Control's main process, and the window
+  has no IPC;
+- sends a cookie value on only if it looks like a user token (`OC` or `FRL`,
+  mixed case, no `%`, `|` or `:`), and each value once. If the server refuses
+  it, the window stays open; close it to see why;
+- gives up after 10 minutes, as BSManager does;
+- when it is closed, times out or is signed out of, stops reading cookies
+  first, then is destroyed (a page's "leave this page?" can't keep it open),
+  and, if it had sent a token, tells the server to drop that sign-in: each
+  sign-in has a random attempt id. The cancel is sent only once the connect
+  under way has finished (saved, refused or failed), so the server always
+  gets it after the connect; with nothing sent, there is nothing to cancel.
+  The server lists an attempt only while its
+  connect is being checked: cancelled then, it isn't saved; cancelled just
+  after its token was saved (even before the connect has finished tidying
+  up), that token is deleted (as a disconnect). A cancel
+  never removes an account a later sign-in or a pasted token saved, and one
+  for an unknown attempt changes nothing.
+
+The page never sees the token: the desktop app hands it straight to the local
+server's connect path and tells the page only the answer (connected, and your
+Meta display name). It isn't logged anywhere.
+
+The window keeps you signed in to Meta (in `persist:meta-signin` only) until
+you **Disconnect**, which also signs out of Meta in Frame Control: it clears
+that window's cookies, storage and cache, so the next sign-in starts fresh.
+**Sign out of Meta in Frame Control** next to the sign-in button does just
+that part, for a sign-in that didn't connect.
+
+**Paste a token.** You copy your own token and paste it in. The two ways
+BSManager's guide describes
+([How to obtain your Oculus Token](https://github.com/Zagrios/bs-manager/wiki/How-to-obtain-your-Oculus-Token)):
+
+1. **From the Meta website.** Sign in at `https://secure.oculus.com`. Open the
+   browser's developer tools, then **Application** (Chrome, Edge) or
+   **Storage** (Firefox) → **Cookies** → `https://secure.oculus.com`. Copy the
+   value of `oc_ac_at`. It starts with `OC`.
+2. **From the Meta Quest PC app** (Windows). Press **Ctrl+Shift+I**, open
+   **Network**, press **Ctrl+R**, type `graph` in the filter, open the first
+   request, and copy the access token from its **Payload**. It starts with
+   `FRL`.
+
+Treat it like a password: anyone with it can act as your Meta account. Signing
+out of the Meta website or app usually ends it; then connect again with a new
+one.
+
+Frame Control refuses values that can't be a user token before sending them
+anywhere: anything not starting with `OC` or `FRL`, URL-encoded copies (with
+`%`), app tokens (with `|` or `:`), cut-off values (under 20 characters), and
+anything with characters other than letters, digits and `+ / = - _` (the
+base64 and URL-safe base64 sets), or with no lower-case letter (real tokens are
+mixed case). The public tools only describe tokens made
+of letters and digits; if a real token needs another character, it has to be
+added in one place (`TOKEN_CHARS` in `ui/frame_meta.py`), which also makes
+the redaction look for it.
+
+## Using it
+
+1. Tick **I understand…**, then either choose **Sign in with Meta…** (desktop
+   app) or paste your token and choose **Connect**. Frame Control asks Meta
+   "who am I" with it (a read-only query); only a token Meta accepts is kept.
+2. Your Quest games are listed with their version, size, game data, and the
+   community verdict from the compatibility database when there is one.
+3. **Install** downloads the game and installs it on the Frame, as [Import
+   from my Quest](quest-import.md) does. A game with OBB game data then needs
+   a second **Install** while you have it open on the Frame: Frame Control
+   downloads the data, copies it in and closes the game.
+4. **Install and test** does the same, then starts the game itself (twice if
+   it has game data to add: once to add it, once for the test), watches it for
+   about 30 seconds, and records what happened. **Test again** repeats only
+   the test.
+5. Choose **Install** on as many games as you like: they wait in the
+   **Install queue** and install one after another, with Quest imports and
+   Android store installs. **Remove** takes one out before it starts.
+6. **Disconnect** deletes the token from your computer and, in the desktop
+   app, signs out of Meta in Frame Control (clears the sign-in window's
+   storage). Games already on the Frame stay.
+
+From a terminal (the token is read from standard input, never an argument):
+
+```sh
+python3 ui/frame_meta.py connect --token-stdin      # paste the token, press Enter
+python3 ui/frame_meta.py status
+python3 ui/frame_meta.py list [--refresh]           # owned Quest games, with community verdicts
+python3 ui/frame_meta.py download APP_ID            # into the local install cache (a later download clears it after 6 hours)
+python3 ui/frame_meta.py install APP_ID [--test] [--allow-downgrade]
+python3 ui/frame_meta.py test com.example.game [--wait 30] [--no-report]
+python3 ui/frame_meta.py disconnect
+```
+
+The local API: `GET /api/meta` (connected or not, never the token),
+`GET /api/meta?library=1[&refresh=1]` (the games), and `POST /api/meta` with
+`{"action": "connect", "token": "...", "acknowledged": true}`,
+`{"action": "disconnect"}`, `{"action": "cancel-signin", "attempt": "..."}`, `{"action": "install", "app": "APP_ID", "test": false,
+"allowDowngrade": false}` or `{"action": "test", "package": "..."}`. Install and
+test return a background job (`/api/job`); an install waits its turn in the
+install queue (`/api/queue`, see [Import from my Quest](quest-import.md#using-it)). Sign in with Meta uses the same
+`connect` action: the desktop app's main process (`app/meta-signin.js`) posts
+it with the cookie's value and an `"attempt"` id (8 to 64 letters, digits or
+`-`) once the page's acknowledgement box is ticked. A connect whose attempt
+was cancelled while it was checked answers 409 and saves nothing;
+`cancel-signin` for an attempt whose token is the saved account deletes it.
+
+## What an install does
+
+1. Checks the game is in your library (by its Meta app id), and that there's
+   room on this computer for the APK, a patched copy of it and the game data.
+2. Downloads the APK from Meta's download server, within the size Meta
+   declared (and at most 2 GB), checking its SHA-256 if Meta gives one, and
+   that it is an APK of the package and version Meta said.
+3. Runs Import from my Quest's checks. Refused: 32-bit-only builds (no
+   `arm64-v8a`), and apps that need an Android newer than Lepton's (API 30).
+   Installed with a warning: games that use Meta's licence check
+   (`libovrplatformloader.so`), and VrApi-only games ("may not run").
+4. Installs it with `frame_android.install` (VR detection, the launcher fix,
+   the OpenXR compatibility layer, artwork, a Steam library entry). An older
+   copy never silently replaces a newer one on the Frame unless you tick
+   **Allow replacing a newer version**.
+5. Game data: the app's OBB (saved as Meta names it when that is a standard
+   `main|patch.<version>.<package>.obb` name, otherwise as
+   `main.<version code>.<package>.obb`) and any *required* asset files with
+   standard OBB names, at most 8 GB each. One install downloads at most 16 GB
+   in all, APK included, counted as the bytes arrive (so files whose size Meta
+   doesn't give count too); a file that goes past it is stopped and removed.
+   The data is copied into the
+   running game by the same two-step helper Import from my Quest uses. Other
+   asset files (DLC packs, `.pak` files a game fetches through Meta's
+   Platform SDK) aren't downloaded; the result lists them.
+6. Deletes everything it downloaded, whether the install worked or not.
+   Downloads left by a crash are removed after six hours.
+
+## The test, and the report
+
+The test starts the game, waits for its Lepton instance, then looks every 10
+seconds for 30 seconds: is the game's process alive, and what does its Android
+log (main, system and crash buffers) say. It recognises:
+
+| In the log | Cause given |
+|---|---|
+| "entitlement check failed", "not entitled", `ovr_Entitlement…` or `IsUserEntitledToApplication` reporting a failure (a call that passes doesn't count) | Meta's licence check failed |
+| Platform SDK initialisation errors | Meta's Platform SDK couldn't start |
+| `Failed to launch SystemActivities`, "device not supported" | The game checks it is on a Meta Quest |
+| `vrapi_… was called before…`, VrApi load errors | Legacy VrApi |
+| `XR_ERROR_EXTENSION_NOT_PRESENT` (with the extension's name) | An OpenXR feature the Frame lacks |
+| `XR_ERROR_API_VERSION_UNSUPPORTED`, runtime/initialisation failures | OpenXR version or session problems |
+| `VK_ERROR_DEVICE_LOST`, `zink`, `libgallium_dri.so`, `GL_INVALID_…`, shader failures | Graphics driver errors |
+| `ClipboardManager` | Lepton's missing clipboard service |
+| `NoSuchMethodError`, `UnsatisfiedLinkError`, `dlopen failed` | Android or library features Lepton lacks |
+| `FATAL EXCEPTION`, `Fatal signal`, `SIGSEGV` | A crash |
+| `ANR in …`, "Input dispatching timed out" | Not responding |
+| `XR_SESSION_STATE_SYNCHRONIZED/VISIBLE/FOCUSED`, `xrEndFrame` | The VR scene started |
+
+The outcome is one of **runs** or **runs with issues** (its VR scene
+started), **quits** (closed by itself), **crashes**, **hangs** (Android
+reported it not responding; Frame Control then closes it, and says so if it
+couldn't), **didn't start** (its instance never came up), or **no clear
+result**: it stayed open but its log never showed its VR scene starting. That
+can be a game still loading, or one stuck after a failed check; Frame Control
+can't tell, so it doesn't record it. A game already open is closed first, so
+the test starts clean; if it can't be closed, nothing is tested. If the Frame
+fails while the test reads the game or its log, the test says only that it
+couldn't read the log: a failed command's output can be the game's log, so it
+is never shown. Signatures look at the first 4 KB of each log line and are
+bounded, so a huge or hostile log can't make the test slow. They
+are written for Frame Control from the research in [vr-apks.md](vr-apks.md);
+they are not copied from other tools.
+
+The result goes through the same path as **Test** and **Report**
+(`frame_catalog.add_report`): `via` probe, source `meta-store`, the result
+(`runs`, `crashes` or `instance_failed`, the values the database accepts), and
+notes with the outcome, the cause, the names of the matched signals and the
+version code, all fixed texts. Nothing else: no token, account name, file or
+log text. The page may show a short name from the log next to the cause (an
+OpenXR extension, a library, an exception class or a signal), taken from the
+log line after the token is removed from it, and left out unless it looks like
+a real name (64 characters at most, no long mixed letter-and-digit runs);
+reports never carry it. It is always kept on this
+computer; it reaches the shared database only if **Share compatibility
+results** is on in Privacy settings, as for every report. The panel offers to
+turn that on.
+
+## Your token and privacy
+
+- Kept in `meta-account.json` in Frame Control's per-user data folder
+  (`~/Library/Application Support/Frame Control` on macOS,
+  `%APPDATA%\Frame Control` on Windows, `~/.local/share/frame-control` on
+  Linux), written owner-only (0600) through a temporary file. Never on the
+  Frame.
+- Sent only to `graph.oculus.com` (in the POST body) and
+  `securecdn.oculus.com` (in the download address, which is how that server
+  takes it), over HTTPS. A download that redirects elsewhere (Meta's CDN) is
+  followed only to a plain HTTPS address on port 443 that doesn't carry the
+  token in any form, anywhere (host, path, query or fragment; literal,
+  recased, percent-encoded, or 8+ characters of it), nor an `access_token`
+  parameter. That is checked before any lookup or connection, and a redirect
+  that fails it is refused. API answers that redirect are refused.
+- Every connection goes to an address checked to be public (an allow-list:
+  no private, local, shared, reserved, multicast, NAT64, 6to4 or Teredo
+  addresses), and to exactly that address, with TLS checked for the host
+  name, so a second DNS answer can't swap in another. System proxy settings
+  aren't used. This is the same design as the itch.io purchases branch.
+- Never in logs, error messages, API answers, the page or reports: every
+  message is cleaned first, matching the token (or any start of it of 8+
+  characters) in any letter case, with each character written literally or
+  percent-encoded once or twice (%XX, %25XX) in either case, and any other
+  token-shaped value, before it is shortened.
+- Disconnect deletes the file and the library Frame Control holds in memory,
+  and stops a download under way. A connect still being checked when you
+  disconnect is not saved. In the desktop app, before the token is deleted, it
+  also stops any sign-in under way, destroys the sign-in window, waits for a
+  connect still under way to finish and cancels its attempt (deleting its
+  token if it was just saved), and only then clears the `persist:meta-signin` session
+  (cookies, storage, cache); no other session is touched. Sign in with Meta
+  stays off from the moment you press Disconnect until the token is deleted,
+  and the app refuses a sign-in while it is signing out.
+- With Sign in with Meta, a second copy of your Meta sign-in lives in that
+  session's storage, in Electron's per-user data folder (`Partitions/meta-signin`),
+  until you disconnect or sign out of Meta in Frame Control.
+
+## Where the protocol comes from
+
+Frame Control's code is its own (MIT). These public sources describe the
+protocol; Frame Control takes only facts from them (addresses, query ids,
+field names), not code. QAVS and BSManager are GPL-3.0; OculusGraphQLApiLib,
+DownQuest and Oculus-downgrader state no licence.
+
+| Fact | Source |
+|---|---|
+| GraphQL at `https://graph.oculus.com/graphql`, POST, form fields `access_token`, `doc_id`, `variables`; `OAuthException` / code 190 for a bad token | [OculusGraphQLApiLib `GraphQLClient.cs`](https://github.com/ComputerElite/OculusGraphQLApiLib/blob/866081e2/OculusGraphQLApiLib/GraphQL/GraphQLClient.cs), [DownQuest `DownQuest.js`](https://github.com/ptrpaws/DownQuest/blob/50f5d558/DownQuest.js) |
+| "Who am I": `doc_id` 4149322231793299, `data.viewer.user {id, alias}` | OculusGraphQLApiLib `GraphQLClient.cs` and `Results/User.cs` |
+| Owned apps: `doc_id` 4850747515044496, `data.viewer.user.active_entitlements.nodes[].item` | OculusGraphQLApiLib `GraphQLClient.cs`, `Results/Entitlement.cs`, `Results/Application.cs`; used by [QAVS `GameDownloadManager.cs`](https://github.com/ComputerElite/QuestAppVersionSwitcher/blob/36bebd5a/QuestAppVersionSwitcher/GameDownloadManager.cs) |
+| One binary: `doc_id` 4734929166632773 with `binaryID`; fields `package_name`, `version`, `version_code`, `size`, `obb_binary`, `asset_files` (`file_name`, `size`, `is_required`) | OculusGraphQLApiLib `GraphQLClient.cs`, `Results/OculusBinary.cs`, `Results/AssetFile.cs` |
+| Downloads: `https://securecdn.oculus.com/binaries/download/?id=<id>&access_token=<token>`, the same for the APK, `obb_binary` and asset files; QAVS takes the OBB and required asset files | OculusGraphQLApiLib `Game/GameDownloader.cs`, [QAVS `DownloadManager.cs`](https://github.com/ComputerElite/QuestAppVersionSwitcher/blob/36bebd5a/QuestAppVersionSwitcher/DownloadManager.cs), DownQuest `DownQuest.js` |
+| Token checks (`OC`/`FRL`, no `%`, `|`, `:`, not `OC` + 15 digits) | OculusGraphQLApiLib `GraphQL/TokenTools.cs`, [BSManager `oculus.helpers.ts`](https://github.com/Zagrios/bs-manager/blob/00380c79/src/shared/helpers/oculus.helpers.ts) |
+| How users get a token (`oc_ac_at` cookie, or the PC app's `FRL` token) | [BSManager wiki](https://github.com/Zagrios/bs-manager/wiki/How-to-obtain-your-Oculus-Token) |
+| Sign in with Meta: open `https://secure.oculus.com` in an app window, and once it reaches `https://secure.oculus.com/my/profile` read the `oc_ac_at` cookie from that window's session (checked on `did-navigate`, `did-navigate-in-page`, `did-stop-loading`); 10-minute timeout | [BSManager `bs-oculus-downloader.service.ts`](https://github.com/Zagrios/bs-manager/blob/00380c79/src/main/services/bs-version-download/bs-oculus-downloader.service.ts) (`getUserTokenFromMetaAuth`) |
+
+**Assumed, not seen in those sources:** that the entitlement and binary
+answers carry the fields above in the shapes the libraries' models describe
+(the stored queries are opaque); that the list isn't paginated (none of the
+tools page it); that `ANDROID_6DOF` marks Quest apps; where downloads redirect
+to (the tools let their HTTP client follow redirects; Frame Control follows
+up to five, to any public HTTPS host, and refuses one carrying the token); and
+a `sha256`
+field (none was seen, so in practice only sizes are checked). The log
+signatures for the test are inferred from the compatibility research, not
+from a real Frame.
+
+## Evidence and limits
+
+**Verified locally** with a fake Meta and a fake Frame (`tests/test_meta.py`):
+token checks; storage owner-only through a temporary file; redaction (the
+stored token recased and percent-encoded in either case, starts of it, other
+token-shaped values, and redaction before cutting); HTTPS-only URLs; the
+public-address allow-list, resolving once and connecting only to a checked
+address within one deadline; redirects off Meta's hosts refused when they
+carry the token anywhere, before any lookup; the token never sent to the
+CDN; GraphQL redirects refused; disconnect beating a connect in flight and
+stopping a download; library parsing (Quest apps only, nothing expired or
+inactive, details from the binary query); downloads with an OBB; size, length
+and checksum limits and the whole-install budget with nothing left behind;
+refusing apps not in the
+library; the handoff to Import from my Quest's checks, install and data step;
+the licence-check warning instead of a refusal; test outcomes from log
+fixtures (a passing licence check isn't a failure; no VR scene is no clear
+result, not recorded); closing before a test and saying when a close failed;
+reports carrying only fixed texts, no token, log text or file names. The
+real TLS connection code is the same as the itch.io branch's and is exercised
+here only with a fake connection.
+
+**Sign in with Meta, verified locally** with fake Electron windows, sessions
+and cookies (`app/test/meta-signin.test.js`): the window's options (its own
+partition, sandbox, context isolation, no Node, no preload) and Meta's login
+address, no developer tools; permission requests and checks refused; the
+navigation allow-list (links elsewhere open in the system browser, redirects
+elsewhere are stopped, pop-ups never become windows); frames allowed any
+HTTPS page but no other scheme, the window itself only Meta's sites; a
+page's beforeunload not keeping the window open; the cookie read only from
+`persist:meta-signin` and only for `oculus.com`, even when the default
+session and another partition hold one; signed-out values ignored; a value
+sent once, a refused one keeping the window open; the window closing after a
+connect, with the page getting the answer and never the token; nothing
+logged, and a server error that echoed the token scrubbed; closing the window
+or signing out ending the wait; closing, timing out or signing out during a
+connect cancelling that attempt (with its own id) after cookie intake stops
+and only after that connect settles (saved, refused or failed), and no cancel
+when nothing was sent; sign-out (Disconnect's first step) waiting for a
+connect under way, even from a window closed earlier, before it finishes;
+sign-out destroying the window before clearing only that partition; no
+sign-in starting while a sign-out runs (it is refused: "try again in a
+moment"), a second sign-out joining the first, and a sign-out waiting for
+every window and connect started before it. The
+frame redirects held to the frame rule, the window's to Meta's sites. The
+server side (`tests/test_meta.py`): an attempt cancelled while Meta is
+answering not saved, even after 300 other cancels; a cancel just after the
+save deleting that token; a cancel never removing a later sign-in's or a
+pasted token's account; unknown attempts changing nothing; no attempt left
+listed after a connect, refused or not; attempt ids checked.
+
+**Differences from BSManager:** BSManager uses its app's default session (and
+clears only `.oculus.com` cookies afterwards); Frame Control uses a session of
+its own and clears all of it on disconnect. BSManager waits for
+`/my/profile`; Frame Control also reacts to the cookie changing, and to any
+`oculus.com` page, and lets the server decide whether the value is a
+working token.
+
+**Not verified:** Sign in with Meta against Meta's real login page (no real
+Meta account was used, and nothing was sent to Meta): whether Meta's login
+still goes only through `oculus.com`, `meta.com` and `facebook.com`, whether
+it uses pop-ups (they open in the same window here, which would break a
+pop-up that reports back to its opener), whether `oc_ac_at` is still set on
+`oculus.com` after login, and whether Meta accepts the window (Frame Control
+removes Electron's name from the user agent as a precaution). A real Meta token and Meta's real answers (none was
+available; nothing was sent to Meta), real downloads and their redirects,
+real Quest games installed or tested on a real Frame, and whether the log
+signatures match what real games print in Lepton.

docs/pc-in-headset.md

@@ -0,0 +1,199 @@
+# 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/privacy.md

@@ -90,13 +90,21 @@ SteamOS and Lepton builds. Before sending:
 
 - the notes, app name and version are scrubbed like error messages (see
   below)
-- the APK's source is kept only if it's `F-Droid` or the public host name of
-  a download link (`https://example.com/…`). File names, user names,
+- the APK's source is kept only if it's `F-Droid`, `meta-store` (a test
+  from [My Meta library](meta-library.md)) or the public host name of a
+  download link (`https://example.com/…`). File names, user names,
   passwords, ports, paths, IP addresses and local host names are dropped
 
 When you turn this on, reports you made earlier on this computer are shared
 too.
 
+My Meta library (Experimental) keeps your Meta access token in
+`meta-account.json` in this data folder, owner-only, and sends it only to
+Meta's API and download hosts. It is never in analytics, reports, error
+details or logs; its test reports carry the package, version, version code,
+title, result and the reason, nothing from your account. See
+[meta-library.md](meta-library.md#your-token-and-privacy).
+
 The maintainer's `python3 ui/frame_compat_db.py sync` copies these events
 into the compatibility database, marked `via=community…`. It takes at most
 30 per reporter per day.

docs/quest-import.md

@@ -0,0 +1,219 @@
+# Import from my Quest
+
+Move games you own from your own Meta Quest onto the Steam Frame. Plug the
+Quest into your computer by USB; Frame Control copies the game off it with
+adb, checks it can run in Lepton, and installs it on the Frame like any other
+APK, with its own Lepton instance and Steam library entry
+([apks.md](apks.md), [vr-apks.md](vr-apks.md)).
+
+There is no licence-check bypass, and there won't be. A game that uses Meta's
+licence check installs with a warning: on the Frame that check can't reach
+Meta, so the game may quit, hang, or run without online features. See
+[What won't run](#what-wont-run-and-why) below. To install games you own
+straight from Meta instead, without a Quest, see [My Meta library
+(Experimental)](meta-library.md).
+
+## Before you start: developer mode on the Quest
+
+adb only reaches a Quest with developer mode on:
+
+1. Make a free Meta developer organisation at
+   [developers.meta.com](https://developers.meta.com/horizon/) on a **verified**
+   Meta account (Meta asks for a phone number or payment card to verify).
+2. In the Meta Horizon phone app, open the headset's settings and switch
+   **Developer Mode** on. Restart the Quest.
+3. Plug the Quest into the computer that runs Frame Control with a USB cable
+   that carries data (some charging cables don't).
+4. Put the headset on. Accept **Allow USB debugging**, and tick **Always allow
+   from this computer**.
+
+Frame Control uses the adb it already uses for the Frame (an adb you
+installed, else the one it bundles). On Linux, adb also needs permission to
+open the Quest: add a udev rule for Meta's USB vendor id `2833`, for example
+`SUBSYSTEM=="usb", ATTR{idVendor}=="2833", MODE="0660", GROUP="plugdev"`, and
+be in that group. Then unplug and replug.
+
+The Frame's own adb connections (Frame Control's SSH tunnels to Lepton,
+`127.0.0.1:<port>`) are never touched. Only a device that reports itself as
+Oculus or Meta, or a Quest model, counts as a Quest.
+
+## Using it
+
+In the app: **Android → On your Frame → Import from my Quest**. Choose **Look
+for my Quest**, then **Import** next to a game. Tick **Also copy each game's
+files in Android/data** to bring the game's external files too (some games
+keep saves there). Progress shows in the panel; the result and any reason it
+stopped appear in the message log.
+
+You can choose **Import** on several games at once: they wait in the **Install
+queue** (above the Quest panel) and import one after another, together with
+installs from the Android store and My Meta library. **Remove** takes a game
+out of the queue before it starts. Each queued import runs on the headset that
+was selected when you queued it; if you switch headsets first, it stops with a
+message instead.
+
+A game with game data (an OBB folder, or Android/data when ticked) takes two
+imports, because Android can only take that data while the game's Lepton
+instance is running, and there is no way to start the instance without the
+game. Frame Control never starts the game itself:
+
+1. **Import** installs the game and says it has data to add.
+2. Start the game from the Steam library and leave it on its first screen.
+3. **Import** again. Frame Control sees the game open with the same version,
+   copies the data in, and closes the game. Start it again to play.
+
+A game that quits straight away without its data can't take it this way.
+
+From a terminal:
+
+```sh
+python3 ui/frame_quest.py devices                      # what adb sees, and which is the Quest
+python3 ui/frame_quest.py list                         # apps on the Quest: split or not, OBB and data sizes
+python3 ui/frame_quest.py import com.example.game      # copy one to the Frame
+python3 ui/frame_quest.py import com.example.game --data --serial 1WMHH000XXXXXX
+```
+
+The API is `GET /api/quest` (the Quest, or guidance when there isn't one, and
+its apps) and `POST /api/quest` with
+`{"action": "import", "package": "...", "serial": "...", "data": false}`,
+which returns a background job (`/api/job`) with a stage and percentage. The
+job waits in the install queue first (`"queued": true`, stage `Queued: N
+installs before it`). `GET /api/queue` lists the running install and those
+waiting; `POST /api/queue` with `{"action": "remove", "job": "..."}` removes a
+waiting one (409 once it has started).
+
+## What an import does
+
+1. Finds the Quest (`adb devices -l`, then `ro.product.manufacturer` and
+   `ro.product.model`). If none is ready it says why: nothing connected, not
+   authorised yet (the **Allow USB debugging** prompt), no USB permission
+   (Linux), offline, another Android device, or several Quests.
+2. Lists third-party apps (`pm list packages -3`), each with `pm path` (one
+   line is a single APK, several a split APK) and the size of
+   `/sdcard/Android/obb/<package>` and `/sdcard/Android/data/<package>`.
+   Labels aren't shown before import: reading them means copying the APK.
+3. Checks there is room on the computer (the APKs, a merged and a patched copy
+   of them counted uncompressed, the OBB folder and the Android/data folder
+   once, since that is streamed to the Frame), then copies the APK and its splits
+   into a per-user cache folder (`Frame Control/quest-import` under the
+   system's cache folder).
+4. **Checks the APK before anything else is copied**, refusing:
+   - 32-bit-only builds (native code but no `arm64-v8a`);
+   - apps that need an Android newer than Lepton's (API 30);
+   - split APKs Frame Control can't merge (below).
+   Installed with a warning:
+   - games that use Meta's licence check (Meta's Platform SDK,
+     `libovrplatformloader.so`, in the base or any split): "uses Meta's
+     licence check; it may quit, hang, or run without online features on the
+     Frame. Frame Control won't remove the check." Linking the SDK doesn't
+     mean a game enforces the check: Meta's store requirement for it
+     (VRC.Quest.Security.1) has only been *Recommended* since 2021, and what
+     a game does when the check fails is up to the game;
+   - VrApi-only builds (`libvrapi.so`, no OpenXR loader), flagged as for any
+     APK: the Frame has no VrApi, so they may not run.
+5. If the game isn't open on the Frame: installs it through the normal APK
+   install (`frame_android.install`: VR detection, the launcher fix, the
+   OpenXR compatibility layer, artwork), and says whether it has game data
+   to add. An older Quest copy never replaces a newer version on the Frame
+   (compared by version code, which installs now record; for installs made
+   before that, it is read from the installed APK on the Frame) unless you
+   tick **Allow replacing a newer version** (`--allow-downgrade`,
+   `"allowDowngrade": true`). If the installed version can't be read at all,
+   that permission is needed too.
+6. If the game is open on the Frame (the second import): refuses unless
+   Frame Control's install record is for this package, in this package's own
+   instance, at the Quest's exact version code (an open game is never
+   replaced), otherwise copies the OBB folder (and `Android/data` if ticked)
+   from the Quest, waits for Android to have finished booting, copies standard
+   `main|patch.<version>.<package>.obb` files with the existing OBB helper
+   (checked by SHA-256 inside Android, [sidequest.md](sidequest.md#obb-files))
+   once Android's own `dumpsys package` in that instance shows the same
+   package at the same version code,
+   streams the `Android/data` files in as a tar written straight into the SSH
+   transfer, then closes the game so its next start reads them, and checks
+   its instance has stopped; if it hasn't, or the check itself fails (a
+   failed `podman ps` never reads as "stopped"), the result says so. The game
+   is closed whatever happens during the copy, including a local read error
+   or Ctrl-C, and a failed close is reported without hiding the original
+   error. Everything
+   from the second check of the install record (after the pulls, which can
+   be long) to closing the game holds the same lock as installs and removals.
+   Other files in the OBB folder are listed as not copied.
+7. Deletes the cache folder, whether the import worked or not. A folder left
+   by a crash is removed by a later import after six hours.
+
+Only one import runs at a time. If copying game data fails, the game is
+closed and the message says so; start it and import again.
+
+### Split APKs
+
+Lepton runs one APK per instance, so the shared install path now merges a
+split APK into one (`frame_android.install(base, splits=[...])`, or
+`python3 ui/frame_android.py install base.apk split1.apk ...`). Merging copies
+each split's native libraries and assets into the base, drops the base
+manifest's `isSplitRequired` flag, and re-signs with Frame Control's key, as
+the launcher fix already does. Only splits that hold nothing but
+`lib/<abi>/*.so`, `assets/` and their own signature, manifest and an empty
+resource table are merged. Refused, with the reason, before anything reaches
+the Frame: splits with resources (screen density or language), code
+(`classes*.dex`), any other file, a manifest that declares components or
+libraries (`<service>`, `<uses-library>`...), feature splits, and splits of
+another package. The merged files are held in memory while the APK is
+repacked and signed (as for every patched APK), so a merge adds at most
+512 MB per file and 1 GB in all. Each file is read from its raw bytes and
+checked against both of its ZIP headers: the local header must name the same
+file with the same method, sizes and checksum as the central directory (or a
+data descriptor must carry them; ZIP64 sizes are understood), the data must
+end before the next entry, a stored file must be exactly its declared size, a
+compressed one must end exactly at the end of its data with nothing after it,
+and its checksum must match. So a forged header can't truncate a file or fill
+memory. A resource table counts as empty only
+if it defines nothing at all (styles and other complex entries included). A merged, re-signed APK can't update a
+copy signed by the publisher.
+
+## What won't run, and why
+
+- **Games that enforce their Meta store licence.** Many store games link
+  Meta's Platform SDK (`libovrplatformloader.so`), for the licence check and
+  for user ids, achievements, multiplayer, cloud saves or DLC. On the Frame the
+  SDK can't reach Meta's services, which only exist on Meta headsets. A game
+  that enforces the check then quits or hangs; one that doesn't may run
+  without its online features. Frame Control can't tell which from the APK, so
+  it installs these with a warning and **won't remove or work around the
+  check**, and doesn't bundle, call or link to any tool that does. If yours
+  quits, ask the developer for a build without the check, or get the game from
+  Steam or itch.io. Most SideQuest, itch.io and open-source games don't link
+  the SDK.
+- **32-bit games** (Quest 1 era): the Frame runs 64-bit ARM only. Refused.
+- **VrApi-only games**: the Frame has OpenXR, not Meta's older VrApi. They
+  install with a warning, but may not run.
+- **Anything else that needs Meta**: avatars, Quest-only device checks,
+  passthrough and other `XR_FB_*` features SteamVR lacks
+  ([vr-apks.md](vr-apks.md#what-steamvrs-android-runtime-supports-verified)).
+- **Private app data** (`/data/data/<package>`) can't be read over adb without
+  root, so only saves in `Android/data` come across.
+
+What usually works: OpenXR games without Meta's licence check, for example
+open-source and itch.io builds you sideloaded onto the Quest.
+
+Only import games you own, for your own use.
+
+## Evidence and limits
+
+**Verified locally** with a fake adb (`tests/fakeadb.py`, `tests/test_quest.py`):
+device detection (Quest, the Frame's tunnel, the Frame over USB, other
+Android devices, unauthorised, no permissions, offline, none, several),
+package listing and split detection, the refusals and the licence-check warning, the order of copies
+(APK checked before the OBB is copied), the two-step install then data copy
+(the game is never started by Frame Control, never replaced while open, and
+closed after its data is copied), split merging and signing, the split
+refusals and size limits (including a forged zip bomb), the space estimate,
+and cache clean-up after success and failure.
+
+**Not verified:** a real Quest (none was available), Quest system apps in
+`pm list packages -3`, real split APKs from the Meta Store, OBB and
+`Android/data` writes into a running Lepton instance on a real Frame
+(the OBB helper itself is also unverified there), whether games stay open
+without their OBB long enough for the second import, and the Linux udev rule.
+Large games are copied into memory while being merged or patched, as every
+patched APK already is.

docs/testing.md

@@ -186,6 +186,17 @@ 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,

docs/vr-apks.md

@@ -214,9 +214,16 @@ source-search endpoint remain unverified (the public install seam is tested).
 
 - **Meta entitlement.** Apps that call the Oculus Platform SDK
   (`libovrplatformloader.so`) to check the Quest store licence need Meta's
-  services. Frame Control won't work around that.
+  services. Frame Control won't work around that: no patching, no stub
+  libraries, no OVRPort or FramePort. Linking the SDK doesn't mean an app
+  enforces the check (Meta's VRC.Quest.Security.1 has only been
+  *Recommended* since 2021, and a failed check does nothing by itself; the app
+  decides), so [Import from my Quest](quest-import.md) and [My Meta
+  library](meta-library.md) install these with a warning: they may quit,
+  hang, or run without online features.
 - **VrApi-era apps** (`libvrapi.so`, before OpenXR) need an API translator,
-  not a patch.
+  not a patch. They install with a warning that they may not run: some
+  OpenXR games ship `libvrapi.so` without depending on it.
 
 ## Frame Control does this for you
 

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

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

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

@@ -1,234 +1,45 @@
-// 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.
+// Thin, serialized binding to the same controller used by the PC host.
+// Algorithm and bounded state live in desktop/controller.c.
 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 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 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 func locked<T>(_ f: () -> T) -> T { lock.lock(); defer { lock.unlock() }; return f() }
-
-    /// The quality setting's bitrate at full size; the first call also starts there.
-    func setCeiling(_ bps: Int) {
-        locked {
-            if target == 0 || target > bps { target = bps }
-            ceiling = bps
-        }
-    }
-
-    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
-        }
-    }
-
-    /// 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.
+    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? {
         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
+            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() }
             }
-            // 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
+            return result == 0 ? nil : result
         }
     }
-
-    /// 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]
-        }
+        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] }
     }
-
-    func eventList() -> [[String: Any]] { locked { events.map { ["t": $0.0, "e": $0.1] } } }
+    func eventList() -> [[String: Any]] { locked { events } }
 }

mac/frame-mac-view/build.sh

@@ -5,7 +5,10 @@ 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
+  -o "$out" "$here"/Sources/*.swift "$obj"
 echo "built $out"

scripts/macview-bench.py

@@ -55,6 +55,7 @@ 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"
@@ -254,7 +255,10 @@ class LabView(frame_macview.MacView):
 
 def ssh_runner(base):
     def run(remote, stdin=None, timeout=30):
-        r = subprocess.run([*base, remote], input=stdin, capture_output=True, text=True, timeout=timeout)
+        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")
         if r.returncode:
             e = RuntimeError((r.stderr or r.stdout).strip())
             e.stdout = r.stdout
@@ -381,7 +385,11 @@ 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 = "test"
+    src = args.source or "test"
+    cpu = None
+    if args.pc:
+        mv.host = "windows" if sys.platform == "win32" else "linux"
+        mv.viewer_profile = "pc-view"
     try:
         if scenario in ("scroll", "type"):
             chrome = chrome_window(f"{scenario}.html")
@@ -405,9 +413,10 @@ 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"]
-        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 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)
         if relay:
             relay.begin()
         expected = 0  # input events the harness asked the viewer for
@@ -443,7 +452,8 @@ 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]
-        cpu.stop()
+        if cpu:
+            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)
@@ -452,7 +462,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()
+        result["cpu"] = cpu.summary() if cpu else {"host": "not sampled"}
         result["viewer"] = data["summary"].get("decoder", "")
         result["show_s"] = show_s
         result["panel"] = shown.get("panel")
@@ -460,6 +470,8 @@ 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
@@ -670,6 +682,8 @@ 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))
@@ -717,7 +731,7 @@ def frame_ssh_for(args):
 
 
 def run_suite(args, frame_ssh, quiet=False):
-    agent_port, token = lab_agent()
+    agent_port, token = (args.pc_view.port, args.pc_view.token) if args.pc else lab_agent()
     results = []
     for sc in args.scenario.split(","):
         if not quiet:
@@ -744,11 +758,12 @@ 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": args.mode, "net": args.net or "none", "delay_ms": args.delay,
+        "config": {"quality": args.quality, "mode": "native" if args.pc else 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], "headset": standby[-40:],
+        "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:],
         "scenarios": results, **extra,
     }
 
@@ -819,19 +834,46 @@ def main():
             print("\nworse:\n  " + "\n  ".join(regs))
         sys.exit(1 if regs else 0)
 
-    lab_agent()
+    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()
     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))])
+    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
     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:
-        awake.terminate()
+        if args.pc_view:
+            args.pc_view.shutdown()
+        if awake:
+            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")]

tests/fakeadb.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""A stand-in for Android's adb, for tests/test_quest.py: just enough of `devices -l`,
+`shell`, and `pull` for frame_quest.py, run as a real subprocess.
+
+$FAKEADB_STATE is a JSON file:
+  devices   [{"serial", "state", "extra" (the rest of the `devices -l` line), "props" {getprop name: value}}]
+  root      a folder standing in for each device's file system (remote /x/y is root/x/y)
+  packages  {package: [APK paths, as `pm path` prints them]}
+  fail_pull a remote path whose pull fails
+Every call is appended to $FAKEADB_LOG as a JSON line. Shell commands are the simple
+`; `-separated ones frame_quest sends, each answered here: no real shell runs.
+"""
+import json
+import os
+import shutil
+import sys
+
+args = sys.argv[1:]
+with open(os.environ['FAKEADB_LOG'], 'a') as f:
+    f.write(json.dumps(args) + '\n')
+with open(os.environ['FAKEADB_STATE']) as f:
+    state = json.load(f)
+root = state.get('root', '')
+serial = None
+if args[:1] == ['-s']:
+    serial, args = args[1], args[2:]
+
+
+def fail(message, code=1):
+    sys.stderr.write(message + '\n')
+    sys.exit(code)
+
+
+def local(remote):
+    return os.path.join(root, remote.lstrip('/'))
+
+
+def size_kb(path):
+    total = 0
+    for dirpath, _, files in os.walk(path):
+        total += sum(os.path.getsize(os.path.join(dirpath, n)) for n in files)
+    return max(4, total // 1024)
+
+
+if args == ['devices', '-l']:
+    print('List of devices attached')
+    for d in state.get('devices', []):
+        print(f"{d['serial']:<22} {d['state']} {d.get('extra', '')}".rstrip())
+    sys.exit(0)
+
+device = next((d for d in state.get('devices', []) if d['serial'] == serial), None)
+if serial is None or device is None:
+    fail(f"adb: device '{serial}' not found")
+if device['state'] == 'unauthorized':
+    fail('adb: device unauthorized.\nThis adb server\'s $ADB_VENDOR_KEYS is not set')
+if device['state'] != 'device':
+    fail(f"adb: device {device['state']}")
+
+if args[:1] == ['shell']:
+    out = []
+    for command in ' '.join(args[1:]).split('; '):
+        command = command.replace(' 2>/dev/null', '').strip()
+        words = command.split()
+        if not words or command == 'true':
+            continue
+        if words[0] == 'getprop':
+            out.append(device.get('props', {}).get(words[1], ''))
+        elif words[0] == 'echo':
+            out.append(' '.join(words[1:]))
+        elif command == 'pm list packages -3':
+            out += ['package:' + p for p in state.get('packages', {})]
+        elif words[:2] == ['pm', 'path']:
+            out += ['package:' + p for p in state.get('packages', {}).get(words[2], [])]
+        elif words[:2] == ['du', '-sk']:
+            if os.path.isdir(local(words[2])):
+                out.append(f'{size_kb(local(words[2]))}\t{words[2]}')
+        elif words[:3] == ['stat', '-c', '%s']:
+            out += [str(os.path.getsize(local(p.strip("'")))) for p in words[3:]]
+        else:
+            fail(f'/system/bin/sh: {words[0]}: inaccessible or not found', 127)
+    print('\n'.join(out))
+    sys.exit(0)
+
+if args[:1] == ['pull'] and len(args) == 3:
+    remote, dest = args[1], args[2]
+    if remote == state.get('fail_pull'):
+        fail(f"adb: error: failed to copy '{remote}' to '{dest}': remote Connection reset")
+    src = local(remote)
+    if not os.path.exists(src):
+        fail(f"adb: error: failed to stat remote object '{remote}': No such file or directory")
+    if os.path.isdir(dest):
+        dest = os.path.join(dest, os.path.basename(remote.rstrip('/')))
+    if os.path.isdir(src):
+        shutil.copytree(src, dest)
+    else:
+        shutil.copyfile(src, dest)
+    print(f'{remote}: 1 file pulled.')
+    sys.exit(0)
+
+fail('adb: unknown command ' + ' '.join(args))

tests/page/meta_rows.mjs

@@ -0,0 +1,43 @@
+// The Meta library's rows, run in node against the real functions from ui/index.html.
+// Found in a live test with a real account (2026-10-14): sizes were cut off behind the
+// package name, a required data file Frame Control can't place was not mentioned, and
+// apps and environments were counted as "games".
+import { readFileSync } from "fs";
+const src = readFileSync(new URL("../../ui/index.html", import.meta.url), "utf8");
+const lines = src.split("\n");
+const fail = msg => { console.log("FAIL " + msg); process.exit(1); };
+
+function grab(name) {
+  const start = lines.findIndex(l => new RegExp(`^(?:(?:async )?function ${name}\\(|const ${name} = )`).test(l));
+  if (start < 0) fail(`no top-level ${name} in index.html`);
+  let depth = 0;
+  for (let i = start; i < lines.length; i++) {
+    for (const c of lines[i]) depth += c === "{" ? 1 : c === "}" ? -1 : 0;
+    if (depth <= 0) return lines.slice(start, i + 1).join("\n") + "\n";
+  }
+  fail(`unbalanced ${name}`);
+}
+const els = { metaCount: { textContent: "" }, metaApps: { innerHTML: "" } };
+const metaLib = { connected: true, results: new Map(), apps: [
+  { id: "1", title: "The Climb", package: "com.crytek.climb", version: "666.0", version_code: 666, size: 30639455,
+    data_files: 0, skipped_files: ["main.com.crytek.climb.obb"] },
+  { id: "2", title: "Beat Saber", package: "com.beatgames.beatsaber", problem: "Meta's API said HTTP 500", skipped_files: [] },
+] };
+const render = new Function("$", "metaLib", "androidApps", "installing", "queued",
+  grab("esc") + grab("questSize") + "const META_VERDICT = {};\n" + grab("renderMetaApps") + "renderMetaApps();");
+render(id => els[id], metaLib, [], new Set(["meta:1"]), new Set(["meta:1"]));
+const html = els.metaApps.innerHTML;
+if (els.metaCount.textContent !== "2 apps") fail("count: " + els.metaCount.textContent);
+const climb = html.split('class="item"')[1];
+if (!/<div class="s" title="[^"]*">29 MB · v666\.0 \(666\) · com\.crytek\.climb</.test(climb)) fail("size not first: " + climb);
+if (!/Not installed: 1 required data file \(main\.com\.crytek\.climb\.obb\)/.test(climb)) fail("skipped data not shown: " + climb);
+const saber = html.split('class="item"')[2];
+if (!/<div class="s v-no"[^>]*>Meta&#39;s API said HTTP 500</.test(saber)) fail("problem not on its own line: " + saber);
+if (/Not installed/.test(saber)) fail("warning without skipped files");
+// Waiting in the install queue: marked, and not offered again.
+if (!/<span class="tag">Queued<\/span>/.test(climb) || !/data-meta-install="1" disabled/.test(climb)) fail("queued not shown: " + climb);
+if (/Queued|disabled/.test(saber)) fail("queued on the wrong row: " + saber);
+metaLib.apps = metaLib.apps.slice(0, 1);
+render(id => els[id], metaLib, [], new Set(), new Set());
+if (els.metaCount.textContent !== "1 app") fail("singular count: " + els.metaCount.textContent);
+console.log("ok");

tests/test_install_queue.py

@@ -0,0 +1,127 @@
+"""The install queue (server.queue_job): Android, Quest and Meta installs run one after another."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+from pathlib import Path
+import sys
+import threading
+import time
+import unittest
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'ui'))
+import server  # noqa: E402
+
+
+def wait(job, timeout=5):
+    end = time.time() + timeout
+    while time.time() < end:
+        j = server.job_status(f'id={job}')
+        if j['done']:
+            return j
+        time.sleep(0.01)
+    raise AssertionError(f'job {job} never finished')
+
+
+class InstallQueue(unittest.TestCase):
+    def setUp(self):
+        self.assertEqual(server._queue, [])
+
+    def blocker(self):
+        """A queued install that runs until released."""
+        go, started = threading.Event(), threading.Event()
+
+        def work():
+            started.set()
+            go.wait(5)
+            return {'message': 'first done'}
+        job = server.queue_job('Install first', work)['job']
+        self.assertTrue(started.wait(5))
+        self.addCleanup(go.set)
+        return job, go
+
+    def test_runs_in_order_one_at_a_time(self):
+        order, running = [], []
+
+        def work(name):
+            def run(report):
+                running.append(name)
+                self.assertEqual(len(running), 1, 'two installs ran at once')
+                report('Copying', 50)
+                time.sleep(0.02)
+                order.append(name)
+                running.remove(name)
+                return {'message': f'{name} done'}
+            return run
+        first, go = self.blocker()
+        started = [server.queue_job(f'Install {n}', work(n), progress=True) for n in ('a', 'b', 'c')]
+        self.assertEqual([s['queued'] for s in started], [1, 2, 3])
+        self.assertIn('queued, 3 before it', started[2]['message'])
+        q = server.install_queue()['jobs']
+        self.assertEqual([j['label'] for j in q], ['Install first', 'Install a', 'Install b', 'Install c'])
+        self.assertEqual([j['queued'] for j in q], [False, True, True, True])
+        self.assertEqual(q[1]['stage'], 'Queued: 1 install before it')
+        self.assertEqual(q[3]['stage'], 'Queued: 3 installs before it')
+        go.set()
+        self.assertEqual(wait(first)['message'], 'first done')
+        for s, n in zip(started, 'abc'):
+            j = wait(s['job'])
+            self.assertEqual((j['message'], j['error'], j['queued']), (f'{n} done', None, False))
+        self.assertEqual(order, ['a', 'b', 'c'])
+        self.assertEqual(server.install_queue(), {'jobs': []})
+
+    def test_a_failure_does_not_stop_the_rest(self):
+        def fail():
+            raise server.Failure('no room on the Frame')
+        bad = server.queue_job('Install bad', fail)['job']
+        good = server.queue_job('Install good', lambda: {'message': 'ok'})['job']
+        self.assertEqual(wait(bad)['error'], 'no room on the Frame')
+        self.assertEqual(wait(good)['message'], 'ok')
+
+    def test_a_waiting_install_can_be_removed_but_not_a_running_one(self):
+        ran = []
+        first, go = self.blocker()
+        second = server.queue_job('Install second', lambda: ran.append(2) or {})['job']
+        third = server.queue_job('Install third', lambda: ran.append(3) or {})['job']
+        self.assertIn('Removed Install second', server.queue_action({'action': 'remove', 'job': second})['message'])
+        j = server.job_status(f'id={second}')
+        self.assertTrue(j['done'] and j['cancelled'])
+        self.assertEqual(server.job_status(f'id={third}')['stage'], 'Queued: 1 install before it')
+        for body, status in (({'action': 'remove', 'job': first}, 409), ({'action': 'remove', 'job': second}, 409),
+                             ({'action': 'nope', 'job': third}, 400)):
+            with self.assertRaises(server.Failure) as e:
+                server.queue_action(body)
+            self.assertEqual(e.exception.status, status)
+        go.set()
+        wait(third)
+        self.assertEqual(ran, [3])
+
+    def test_runs_only_on_the_headset_it_was_queued_for(self):
+        class Link:
+            device = 'frame-a'
+
+            def active_device(self):
+                return {'id': self.device}
+        link = Link()
+        with patch.object(server, 'LINK', link):
+            first, go = self.blocker()
+            ran = []
+            later = server.queue_job('Install later', lambda: ran.append(1) or {})['job']
+            link.device = 'frame-b'
+            go.set()
+            self.assertIn('switched headsets', wait(later)['error'])
+        self.assertEqual(ran, [])
+
+    def test_installs_from_each_place_are_queued(self):
+        with patch.object(server, 'ensure_master'), patch.object(server, 'queue_job', return_value={'job': 'j'}) as q:
+            server.quest({'action': 'import', 'package': 'com.example.game'})
+            server.meta({'action': 'install', 'app': '123'})
+            with patch.object(server.frame_catalog, 'app'):
+                server.android({'action': 'install', 'package': 'com.example.game'})
+            server.android({'action': 'install', 'package': 'com.example.game', 'url': 'https://f-droid.org/x.apk'})
+            with patch.object(server.apk_search, 'resolve', return_value=(None, {'enabled': True})):
+                server.source_install({'source': 'fdroid', 'id': 'com.example.game'})
+        self.assertEqual(q.call_count, 5)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_macview.py

@@ -84,7 +84,10 @@ class Helpers(unittest.TestCase):
     @unittest.skipUnless(shutil.which("bash"), "needs bash")
     @unittest.skipIf(os.name == "nt", "Windows' bash.exe is WSL's launcher, and runners have no distribution")
     def test_launch_script_parses(self):
-        r = subprocess.run(["bash", "-n"], input=frame_macview.LAUNCH, text=True, capture_output=True)
+        bash = str(Path(os.environ.get("ProgramFiles", "C:/Program Files")) / "Git/bin/bash.exe") if sys.platform == "win32" else "bash"
+        if sys.platform == "win32" and not Path(bash).exists():
+            self.skipTest("Git Bash is not installed (WSL bash is not a local shell)")
+        r = subprocess.run([bash, "-n"], input=frame_macview.LAUNCH.encode("utf-8"), capture_output=True)
         self.assertEqual(r.returncode, 0, r.stderr)
 
     def test_show_checks_the_source_before_anything_else(self):

tests/test_pc_controller.py

@@ -0,0 +1,64 @@
+"""Frozen regression trace from the original mac-in-headset Swift controller.
+The 600-state reference was produced at 1b90c64, before the C extraction:
+60 seconds with a slow/congested middle, then recovery. No generated behavior
+from the new implementation is used to calculate the expected digest.
+"""
+import ctypes as C
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'ui'))
+from frame_pc_capture import Controller
+
+
+class ControllerTrace(unittest.TestCase):
+    def test_original_mac_congestion_and_recovery(self):
+        cc = shutil.which('cc') or shutil.which('gcc')
+        if not cc:
+            self.skipTest('C compiler not installed; native build jobs cover this trace')
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / ('trace.dll' if sys.platform == 'win32' else 'trace.so')
+            subprocess.run([cc, '-O2', '-shared', '-fPIC', str(ROOT/'desktop/controller.c'), '-o', str(path)], check=True, capture_output=True)
+            lib = C.CDLL(str(path))
+            sig = {'new': (C.c_void_p, [C.c_int, C.c_int]), 'free': (None, [C.c_void_p]),
+                   'ceiling': (None, [C.c_void_p, C.c_int]), 'value': (C.c_int64, [C.c_void_p, C.c_int]),
+                   'capture': (None, [C.c_void_p, C.c_int64]), 'gate': (C.c_int, [C.c_void_p, C.c_int64, C.c_int]),
+                   'sent': (None, [C.c_void_p, C.c_uint32, C.c_int, C.c_int64]),
+                   'ack': (C.c_int, [C.c_void_p, C.c_uint32, C.c_int64]), 'update': (C.c_int, [C.c_void_p, C.c_int64])}
+            for name, (ret, args) in sig.items():
+                fn = getattr(lib, 'fc_'+name)
+                fn.restype, fn.argtypes = ret, args
+            c = Controller(lib, 60, 8000000)
+            due, states, seq = [], [], 0
+            try:
+                for tick in range(6000):
+                    now = 10000000+tick*10000
+                    for t, s in due:
+                        if t <= now:
+                            c.call('ack', s, now)
+                    due = [(t, s) for t, s in due if t > now]
+                    if tick % 2 == 0:
+                        c.call('capture', now)
+                        if c.call('gate', now, 1):
+                            seq += 1
+                            c.call('sent', seq, 8000 if tick < 1000 or tick > 4000 else 22000, now)
+                            due.append((now+(240000 if 1500 < tick < 3500 else 20000), seq))
+                    if tick % 10 == 0:
+                        c.update(now)
+                        x = c.state()
+                        states.append([x[k] for k in ('target', 'ceiling', 'tier', 'fps', 'inFlight')] +
+                                      [round(x['scale']*100), round(x['baseRtt']*1000), round(x['slack']*1000)])
+                digest = hashlib.sha256(json.dumps(states, separators=(',', ':')).encode()).hexdigest()
+                self.assertEqual(digest, '1932f16aafce5c9157bcd2aba5d90719a366f9999422920aaeae78a6cdec08f6')
+            finally:
+                c.close()
+                if sys.platform == 'win32':
+                    import _ctypes
+                    _ctypes.FreeLibrary(lib._handle)

tests/test_pcview.py

@@ -0,0 +1,388 @@
+"""PC adapters: grants, input cleanup, launcher reuse and native codec contract.
+Native tests require the bundled libraries; CI sets REQUIRE_NATIVE so a missing
+bundle is a failure, never a silent skip. No desktop consent or GPU is faked as
+successful real-host capture.
+"""
+import ctypes
+import http.client
+import json
+import os
+from pathlib import Path
+import shutil
+import struct
+import subprocess
+import sys
+import threading
+import time
+import unittest
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / 'ui'))
+import frame_pc_agent as agent
+import frame_pc_capture as capture
+import frame_pcview
+import frame_macview
+from frame_stream_stats import Stats
+from test_macview import WS
+
+
+class GrantsTests(unittest.TestCase):
+    def test_source_bound_retry_ack_and_stop(self):
+        g = agent.Grants('master')
+        ticket = g.ticket('window:1')
+        self.assertIsNone(g.redeem('window:2', {'t': ticket}))
+        key = g.redeem('window:1', {'t': ticket})
+        self.assertEqual(key, g.redeem('window:1', {'t': ticket}))
+        g.ack(key)
+        self.assertIsNone(g.redeem('window:1', {'t': ticket}))
+        self.assertEqual(key, g.redeem('window:1', {'r': key}))
+        self.assertIsNone(g.redeem('window:2', {'r': key}))
+        g.revoke('window:1')
+        self.assertIsNone(g.redeem('window:1', {'r': key}))
+
+    def test_expiry_and_stop_before_redeem(self):
+        g = agent.Grants('master')
+        with mock.patch.object(agent.time, 'monotonic', return_value=1):
+            ticket = g.ticket('test')
+        with mock.patch.object(agent.time, 'monotonic', return_value=62):
+            self.assertIsNone(g.redeem('test', {'t': ticket}))
+        ticket = g.ticket('test')
+        g.revoke()
+        self.assertIsNone(g.redeem('test', {'t': ticket}))
+
+
+class AdapterTests(unittest.TestCase):
+    def test_windows_uses_wgc_and_media_foundation(self):
+        for kind in ('window', 'display'):
+            pipeline = capture.pipeline(dict(src=kind+':42'), 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+            self.assertIn('capture-api=wgc', pipeline)
+            self.assertIn('window-handle=42' if kind == 'window' else 'monitor-handle=42', pipeline)
+            self.assertIn('mfh264enc name=enc low-latency=true bframes=0', pipeline)
+            self.assertNotIn('drop=true', pipeline)
+        with self.assertRaises(ValueError):
+            capture.pipeline(dict(src='window:42 ! fakesink'), 'win32', 'mfh264enc', 640, 360, 30, 1000000)
+
+    def test_linux_uses_only_portal_fd_and_node(self):
+        p = capture.pipeline(dict(src='window:consented', fd=19, node=47), 'linux', 'x264enc', 640, 360, 30, 1000000)
+        self.assertIn('pipewiresrc fd=19 path=47', p)
+        self.assertIn('tune=zerolatency', p)
+        self.assertEqual(capture.dimensions(1920, 1080, 1280), (1280, 720))
+
+    def test_portal_input_clamps_and_releases_held_state(self):
+        native = mock.Mock()
+        native.lib.fc_portal_input.return_value = 1
+        inp = capture.PortalInput(native, dict(portal=123, w=100, h=50))
+        inp.handle(dict(t='m', e='down', b=0, x=2, y=-1))
+        inp.handle(dict(t='k', e='down', key='Control'))
+        inp.release()
+        calls = native.lib.fc_portal_input.call_args_list
+        self.assertEqual(calls[0].args, (123, 0, 99, 0, 0, 0))
+        self.assertIn(mock.call(123, 1, 0, 0, 0x110, 0), calls)
+        self.assertIn(mock.call(123, 3, 0, 0, 0xffe3, 0), calls)
+        self.assertFalse(inp.buttons or inp.keys)
+
+    def test_windows_release_and_negative_monitor_origin(self):
+        host = mock.Mock()
+        host.user.GetSystemMetrics.side_effect = [-1920, 0, 3840, 1080]
+        inp = capture.WindowsInput(host, dict(src='display:4', x=-1920, y=0, w=1920, h=1080))
+        inp.handle(dict(t='m', e='down', b=2, x=0, y=0))
+        self.assertEqual(host.send.call_args_list[0], mock.call(mouse=(0, 0, 0, 0xc001)))
+        inp.handle(dict(t='k', e='down', code='ControlLeft', key='Control'))
+        inp.release()
+        self.assertIn(mock.call(mouse=(0, 0, 0, 0x10)), host.send.call_args_list)
+        self.assertIn(mock.call(key=(162, 0, 2)), host.send.call_args_list)
+
+    def test_refused_windows_focus_never_clicks_the_covering_app(self):
+        host = mock.Mock()
+        host.rect.return_value = (0, 0, 800, 600)
+        host.user.GetForegroundWindow.return_value = 99
+        host.user.SetForegroundWindow.return_value = False
+        inp = capture.WindowsInput(host, dict(src='window:12', w=800, h=600))
+        with self.assertRaisesRegex(RuntimeError, 'could not focus'):
+            inp.handle(dict(t='m', e='down', b=0, x=.5, y=.5))
+        host.send.assert_not_called()
+
+    def test_pc_reuses_launcher_and_namespaces_panel_ids(self):
+        view = frame_pcview.PCView(['ssh'], mock.Mock(return_value='panel created'), 'frame')
+        view.call = mock.Mock(side_effect=lambda path, **kw: {'screen': True, 'ticket': 'one-use', 'streams': []})
+        view.ensure_tunnel = mock.Mock()
+        view.remote_port = 47900
+        view.show('window:12')
+        self.assertEqual(view.run.call_args.kwargs['stdin'], frame_macview.LAUNCH)
+        self.assertNotEqual(frame_macview.panel_id('window:12'), frame_macview.panel_id('window:12', 'windows'))
+        self.assertFalse(view.prefer_usb)
+        with self.assertRaises(frame_macview.MacViewError):
+            view.show('separate:12')
+
+    def test_session_end_releases_native_input_only_once(self):
+        session = object.__new__(agent.Session)
+        session.lock, session.input_lock = threading.RLock(), threading.RLock()
+        session.stop_event = threading.Event()
+        session.ws, session.input = mock.Mock(), mock.Mock()
+        session.released = False
+        session.end()
+        session.end()
+        session.input.release.assert_called_once()
+        self.assertTrue(session.stop_event.is_set())
+
+    def test_idle_source_is_not_a_stall(self):
+        # PipeWire/WGC deliver frames only on damage: a static desktop sends
+        # its first frame and then nothing. That must not end the session.
+        session = object.__new__(agent.Session)
+        session.lock, session.pending = threading.RLock(), {}
+        session.stats = Stats(lambda: 0)
+        session.stats.captured = 1
+        self.assertIsNone(session.stalled(60000000, 0, 0))
+        # A frame that entered the encoder and never came out is a fault.
+        session.pending[5] = dict(cap=0, arr=0, e0=1000000, tier=0, br=0)
+        self.assertIn('encoder', session.stalled(12000000, 0, 0))
+        self.assertIsNone(session.stalled(10000000, 0, 0))
+        # No initial frame at all after the pipeline opened is a fault.
+        session.pending.clear()
+        self.assertIn('capture', session.stalled(12000000, 0, 1))
+        self.assertIsNone(session.stalled(9000000, 0, 1))
+
+    def test_controller_is_inert_after_close(self):
+        lib = mock.Mock()
+        lib.fc_new.return_value = 1234
+        lib.fc_value.return_value = 100
+        controller = capture.Controller(lib, 60, 5000000)
+        controller.close()
+        lib.fc_free.assert_called_once_with(1234)
+        lib.reset_mock()
+        state = controller.state()
+        self.assertEqual((state['fps'], state['target'], state['scale']), (60, 0, 1))
+        self.assertEqual(controller.call('gate', 1, 1), 0)
+        self.assertEqual(controller.update(1), 0)
+        controller.close()
+        self.assertEqual(lib.method_calls, [])  # nothing touched the freed pointer
+
+    def test_library_path_prepend_adds_no_empty_entry(self):
+        env = {}
+        frame_pcview.prepend(env, 'LD_LIBRARY_PATH', '/opt/fc/lib')
+        self.assertEqual(env['LD_LIBRARY_PATH'], '/opt/fc/lib')
+        frame_pcview.prepend(env, 'LD_LIBRARY_PATH', '/x')
+        self.assertEqual(env['LD_LIBRARY_PATH'], '/x' + os.pathsep + '/opt/fc/lib')
+        with mock.patch.dict(os.environ, clear=True):
+            env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        for name in ('PATH', 'LD_LIBRARY_PATH'):
+            parts = env.get(name, 'x').split(os.pathsep)
+            self.assertNotIn('', parts, name)
+
+    def test_malformed_viewer_input_is_dropped_not_fatal(self):
+        session = object.__new__(agent.Session)
+        session.lock, session.input_lock = threading.RLock(), threading.RLock()
+        session.stop_event, session.key_event = threading.Event(), threading.Event()
+        session.src, session.codec, session.key, session.w, session.h = 'display:1', 'h264', 'r', 100, 100
+        session.source = dict(src='display:1', w=100, h=100, portal=1)
+        session.input_enabled, session.released = True, False
+        session.native = mock.Mock()
+        session.native.now.return_value = 0
+        session.controller, session.agent = mock.Mock(), mock.Mock()
+        session.stats = Stats(lambda: 0)
+        session.produce = lambda: None
+        lib = mock.Mock()
+        lib.fc_portal_input.return_value = 1
+        session.input = capture.PortalInput(mock.Mock(lib=lib), session.source)
+        session.ws = mock.Mock()
+        session.ws.receive.side_effect = [
+            dict(t='m', x='left', y=0), dict(t='wheel', dx=[1]), dict(t='k', e='down', key=None, i='x'),
+            dict(t='fd', drop='many'), dict(t='rx', s=[1]), dict(t='m', x=.5, y=.5), ConnectionError('closed')]
+        with self.assertRaises(ConnectionError):
+            session.start()
+        # Every malformed message was skipped; the good move after them still ran.
+        moves = [c.args for c in lib.fc_portal_input.call_args_list if c.args[1] == 0]
+        self.assertAlmostEqual(moves[-1][2], .5*99)
+        self.assertEqual(session.ws.receive.call_count, 7)
+
+    def test_stats_keep_capture_time_and_bound_records(self):
+        stats = Stats(lambda: 10000000)
+        stats.input(dict(t='m', i=1, tv=9999990))
+        f = stats.add(cap=10000001, arr=10000002, e0=10000003, e1=10000004)
+        self.assertEqual(f['echo'], 1)
+        stats.report(dict(t='rx', s=f['s'], r=10000010))
+        stats.report(dict(t='fd', f=[[f['s'], 10000011, 10000012, 10000013]]))
+        self.assertEqual(stats.snapshot(settle=0)['inputs'][0]['frame'], f['s'])
+        for _ in range(4100):
+            stats.add(cap=10000001)
+        self.assertEqual(len(stats.frames), 4096)
+
+
+class NativeTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if not capture.LIBRARY.exists():
+            if os.environ.get('FRAME_PC_REQUIRE_NATIVE') == '1':
+                raise AssertionError('CI required native PC libraries but they were not built')
+            raise unittest.SkipTest('native PC libraries not built on this host')
+        cls.token = 'test-' + os.urandom(8).hex()
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['FRAME_MAC_VIEW_TOKEN'] = cls.token
+        cls.proc = subprocess.Popen([sys.executable, str(ROOT/'ui/frame_pc_agent.py'), 'serve', '--port', '0',
+            '--page', str(ROOT/'ui/mac-view.html'), '--exit-on-eof'], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, text=True, env=env)
+        line = cls.proc.stdout.readline()
+        if 'listening' not in line:
+            raise AssertionError('Native agent failed: ' + cls.proc.stderr.read())
+        cls.port = int(line.rsplit(':', 1)[1])
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.proc.stdin.close()
+        try:
+            rc = cls.proc.wait(10)
+        except subprocess.TimeoutExpired:
+            cls.proc.kill()
+            raise AssertionError('Native agent did not stop after EOF')
+        error = cls.proc.stderr.read()
+        cls.proc.stdout.close()
+        cls.proc.stderr.close()
+        if rc:
+            raise AssertionError('Native agent exited %s: %s' % (rc, error))
+
+    def request(self, path, method='GET'):
+        conn = http.client.HTTPConnection('127.0.0.1', self.port, timeout=10)
+        try:
+            conn.request(method, path)
+            response = conn.getresponse()
+            return response.status, response.read()
+        finally:
+            conn.close()
+
+    def tearDown(self):
+        self.request('/close?k='+self.token, 'POST')
+
+    @unittest.skipUnless(sys.platform.startswith('linux'), 'Linux PipeWire client libraries')
+    def test_bundled_pipewire_context_needs_no_system_modules(self):
+        # No portal request, remote connection or desktop capture: create and
+        # destroy a private client context to test the dynamically loaded SPA
+        # and protocol modules that ldd cannot discover.
+        code = """
+import ctypes as C, os
+lib = C.CDLL(os.path.join(os.environ['FRAME_PC_NATIVE'], 'lib', 'libpipewire-0.3.so.0'))
+for name, ret, args in [
+    ('pw_init', None, [C.c_void_p, C.c_void_p]),
+    ('pw_main_loop_new', C.c_void_p, [C.c_void_p]),
+    ('pw_main_loop_get_loop', C.c_void_p, [C.c_void_p]),
+    ('pw_context_new', C.c_void_p, [C.c_void_p, C.c_void_p, C.c_size_t]),
+    ('pw_context_find_factory', C.c_void_p, [C.c_void_p, C.c_char_p]),
+    ('pw_context_find_spa_lib', C.c_char_p, [C.c_void_p, C.c_char_p]),
+    ('pw_context_destroy', None, [C.c_void_p]),
+    ('pw_main_loop_destroy', None, [C.c_void_p])]:
+    fn = getattr(lib, name)
+    fn.restype, fn.argtypes = ret, args
+lib.pw_init(None, None)
+loop = lib.pw_main_loop_new(None)
+assert loop, 'bundled SPA loop support did not load'
+context = lib.pw_context_new(lib.pw_main_loop_get_loop(loop), None, 0)
+assert context, 'bundled PipeWire client modules did not load'
+assert lib.pw_context_find_factory(context, b'adapter'), 'video adapter factory is missing'
+# The exported factory is video.adapt, which needs a live follower node to
+# instantiate. Check its configured library and exported factory without
+# pretending a headless context is a consented video stream.
+plugin_name = lib.pw_context_find_spa_lib(context, b'video.adapt')
+assert plugin_name, 'video.adapt has no bundled library mapping'
+plugin = C.CDLL(os.path.join(os.environ['SPA_PLUGIN_DIR'], plugin_name.decode() + '.so'))
+class Factory(C.Structure):
+    _fields_ = [('version', C.c_uint32), ('name', C.c_char_p)]
+plugin.spa_handle_factory_enum.argtypes = [C.POINTER(C.POINTER(Factory)), C.POINTER(C.c_uint32)]
+plugin.spa_handle_factory_enum.restype = C.c_int
+factory, index, names = C.POINTER(Factory)(), C.c_uint32(), []
+while plugin.spa_handle_factory_enum(C.byref(factory), C.byref(index)) > 0:
+    names.append(factory.contents.name)
+assert b'video.adapt' in names, 'bundled SPA video adapter factory is missing'
+lib.pw_context_destroy(context)
+lib.pw_main_loop_destroy(loop)
+"""
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['FRAME_PC_NATIVE'] = str(capture.NATIVE)
+        result = subprocess.run([sys.executable, '-c', code], env=env, capture_output=True, text=True, timeout=15)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_last_raw_picture_survives_a_closed_gate(self):
+        # A source sends ONE changed frame, then becomes idle. It must reach
+        # the encoder after congestion clears, without needing another update.
+        code = """
+import ctypes as C, sys, time
+from frame_pc_capture import Native, GATE, Encoded, pipeline
+native = Native()
+start = None
+closing = False
+phases = []
+def gate(stage, pts, capture, arrived):
+    global start
+    phases.append(stage)
+    if closing: return -1
+    if start is None: start = time.monotonic()
+    return int(stage == 1 or time.monotonic()-start >= .15)
+callback = GATE(gate)
+p = pipeline(dict(src='test'), sys.platform, 'x264enc', 320, 180, 30, 300000)
+p = p.replace('is-live=true', 'is-live=true num-buffers=1')
+error = C.create_string_buffer(1024)
+handle = native.lib.fc_capture_open(p.encode(), callback, error, len(error))
+assert handle, error.value
+try:
+    frame = Encoded()
+    result = 0
+    deadline = time.monotonic()+5
+    while not result and time.monotonic() < deadline:
+        result = native.lib.fc_capture_pull(handle, C.byref(frame))
+    assert result == 1, native.lib.fc_capture_error(handle)
+    assert frame.key and frame.size > 17
+    assert phases.count(0) == 1 and 2 in phases, phases
+finally:
+    closing = True
+    native.lib.fc_capture_close(handle)
+"""
+        env = frame_pcview.PCView([], lambda *a: None, 'frame').agent_environment()
+        env['PYTHONPATH'] = str(ROOT / 'ui')
+        result = subprocess.run([sys.executable, '-c', code], env=env, capture_output=True, text=True, timeout=10)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_auth_and_real_h264_stats(self):
+        self.assertEqual(self.request('/status')[0], 403)
+        status, body = self.request('/ticket?src=test&k='+self.token, 'POST')
+        self.assertEqual(status, 200)
+        ticket = json.loads(body)['ticket']
+        ws = WS(self.port, '/stream?src=test&fps=30&max=640&t='+ticket)
+        try:
+            self.assertEqual(ws.status, 101)
+            key, got, echo = None, 0, False
+            ws.send_text(json.dumps(dict(t='m', e='down', i=7, tv=1, x=.2, y=.3)))
+            deadline = time.monotonic()+10
+            while time.monotonic() < deadline and (got < 5 or not echo):
+                op, data = ws.recv()
+                if op == 1:
+                    m = json.loads(data)
+                    self.assertNotEqual(m.get('t'), 'error', m)
+                    if m.get('t') == 'hello':
+                        key = m['r']
+                        ws.send_text(json.dumps(dict(t='ack')))
+                elif op == 2:
+                    got += 1
+                    seq, echoed = struct.unpack('!II', data[9:17])
+                    now = struct.unpack('!Q', data[1:9])[0]
+                    echo |= echoed == 7
+                    self.assertIn(b'\x00\x00\x00\x01', data[17:])
+                    ws.send_text(json.dumps(dict(t='rx', s=seq, r=now+100)))
+                    ws.send_text(json.dumps(dict(t='fd', f=[[seq, now+200, now+300, now+400]])))
+            self.assertGreaterEqual(got, 5)
+            self.assertTrue(echo)
+            time.sleep(.1)
+            stats = json.loads(self.request('/stats?settle=0&k='+self.token)[1])['streams'][0]
+            self.assertGreater(stats['frames'][0]['e1'], stats['frames'][0]['e0'])
+            self.assertIn('controller', stats)
+            used = WS(self.port, '/stream?src=test&t='+ticket)
+            self.assertEqual(used.status, 403)
+            used.close()
+            self.request('/close?src=test&k='+self.token, 'POST')
+            revoked = WS(self.port, '/stream?src=test&r='+key)
+            self.assertEqual(revoked.status, 403)
+            revoked.close()
+        finally:
+            ws.close()
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_server.py

@@ -472,6 +472,11 @@ class PageScripts(unittest.TestCase):
         r = subprocess.run(["node", str(ROOT / "tests" / "page" / "store_detail.mjs")], capture_output=True, text=True)
         self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
 
+    def test_meta_library_rows_render(self):
+        """tests/page/meta_rows.mjs runs the real Meta library row rendering from index.html."""
+        r = subprocess.run(["node", str(ROOT / "tests" / "page" / "meta_rows.mjs")], capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+
 
 @unittest.skipIf(os.name == "nt", "runs on the Frame (Linux); local-bin/ssh is a POSIX shell script")
 class LocalMode(unittest.TestCase):

ui/frame_android.py

@@ -7,7 +7,7 @@ in the Steam library and gets its own SteamVR panel. Nothing goes through
 Lepton Development, which wipes its apps on exit. See docs/apks.md.
 
 Python stdlib only. CLI: python3 ui/frame_android.py
-  install APK [--vr|--flat] [--no-xr-compat] | info APK | versions APK-or-PKG
+  install APK [SPLIT.apk ...] [--vr|--flat] [--no-xr-compat] | info APK | versions APK-or-PKG
   install-obb PKG OBB [OBB ...] | backup-data PKG ARCHIVE | restore-data PKG ARCHIVE
   refresh-art PKG|--all | patch SRC DST [--add NAME=PATH ...] | list | launch PKG | stop PKG | remove PKG | probe PKG
 """
@@ -18,7 +18,7 @@ import frame_artwork
 import frame_host
 import tempfile
 import zipfile
-from frame_apk_vr import add_launcher_category
+from frame_apk_vr import add_launcher_category, drop_split_required
 from frame_apk_sign import repack
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -142,7 +142,9 @@ def check_installable(info):
                          "(or arm64, or universal) and install that instead")
 
 
-_install_lock = threading.Lock()  # installs are rare; one at a time avoids every race
+# Installs are rare; one at a time avoids every race. Reentrant so a caller (a Quest import's
+# final checks and data copy) can hold it around install_obb and install, which take it too.
+_install_lock = threading.RLock()
 # The slowest transfer a copy is allowed before it times out, in bytes a second (about 4 Mbit/s,
 # a slow or busy Wi-Fi link). A fixed 10 minutes failed any APK over about 300 MB at that rate.
 COPY_MIN_RATE = 512 * 1024
@@ -190,7 +192,303 @@ def _write_meta(d, meta):
 install_hooks = []
 
 
-def install(apk_path, flatscreen=None, name=None, source=None, icon_png=None, xr_compat=None, artwork=None):
+# Split APK members that belong to the split itself, not the app: never merged.
+SPLIT_OWN = re.compile(r'^(AndroidManifest\.xml|stamp-cert-sha256|META-INF/.*)$')
+# What a mergeable split may add: native libraries and assets, nothing else.
+SPLIT_ADDS = re.compile(r'^(lib/[^/]+/[^/]+\.so|assets/.*[^/])$')
+# Manifest elements a config or install-time asset split carries. Anything else (an
+# activity, service, uses-library...) belongs to a feature split, which needs its manifest.
+SPLIT_TAGS = {'manifest', 'application', 'uses-sdk', 'module', 'delivery', 'install-time', 'fusing'}
+# Every merged byte is held in memory while the APK is repacked and signed (as for every
+# patched APK), so splits are bounded by what's actually inflated, not only the headers.
+MAX_SPLIT_MEMBER = 512 * 1024**2
+MAX_SPLIT_TOTAL = 1024**3
+
+
+def _split_manifest(path, name):
+    """(package, split name) from a split APK's manifest, refusing splits that declare
+    anything the merged app would lose with that manifest."""
+    with zipfile.ZipFile(path) as z:
+        elements = frame_apk.manifest_elements(frame_apk._read(z, 'AndroidManifest.xml', frame_apk.MAX_MANIFEST))
+    attrs = next((a for tag, a in elements if tag == 'manifest'), {})
+    split = (attrs.get('split') or (None, None, None))[2]
+    feature = attrs.get('isFeatureSplit')
+    if feature and feature[1]:
+        raise FrameError(f'{name} ({split or "split"}) is a feature split with its own code and manifest; '
+                         'Frame Control can only merge splits that add native libraries or assets')
+    extra = sorted({tag for tag, _ in elements if tag not in SPLIT_TAGS})
+    if extra:
+        raise FrameError(f'{name} ({split or "split"}) declares <{">, <".join(extra)}> in its manifest; '
+                         'Frame Control can only merge splits that add native libraries or assets')
+    return (attrs.get('package') or (None, None, None))[2], split
+
+
+def split_entries(base, splits):
+    """What merging splits into base adds: {entry name: (split path, entry name, size)}.
+
+    Lepton runs one APK per instance, so a split app is merged into one APK. Only splits
+    that add native libraries (the arm64 ABI split) or install-time assets can be: a split
+    with code, components or resources (screen density, language) needs its own manifest
+    or resource table, which Frame Control doesn't merge, so those are refused."""
+    try:
+        with zipfile.ZipFile(base) as z:
+            taken = set(z.namelist())
+        package = apk_info(base)['package']
+        plan, total = {}, 0
+        for path in splits:
+            name = os.path.basename(path)
+            split_pkg, split_name = _split_manifest(path, name)
+            label = f'{name} ({split_name or "split"})'
+            if split_pkg != package:
+                raise FrameError(f'{name} is not part of {package} (it says {split_pkg or "nothing"})')
+            with zipfile.ZipFile(path) as z:
+                for member in z.infolist():
+                    entry = member.filename
+                    if entry.endswith('/') or SPLIT_OWN.match(entry):
+                        continue
+                    if entry == 'resources.arsc':
+                        # A config split for native code may carry an empty table; any resource needs merging.
+                        if not resources_empty(frame_apk._read(z, entry, frame_apk.MAX_ARSC)):
+                            raise FrameError(f'{label} holds screen-density or language resources; Frame Control '
+                                             'can only merge splits that add native libraries or assets')
+                        continue
+                    if entry.startswith('res/'):
+                        raise FrameError(f'{label} holds screen-density or language resources ({entry}); Frame '
+                                         'Control can only merge splits that add native libraries or assets')
+                    if re.match(r'^classes\d*\.dex$', entry):
+                        raise FrameError(f'{label} contains code ({entry}); Frame Control can only merge splits '
+                                         'that add native libraries or assets')
+                    if not SPLIT_ADDS.match(entry):
+                        raise FrameError(f'{label} contains {entry}; Frame Control can only merge splits that '
+                                         'add native libraries or assets')
+                    if entry in taken:
+                        raise FrameError(f'{name} and another part of the app both contain {entry}')
+                    if member.compress_type not in (zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED):
+                        raise FrameError(f'{entry} in {name} uses a compression Android does not')
+                    if member.file_size > MAX_SPLIT_MEMBER:
+                        raise FrameError(f'{entry} in {name} is {member.file_size / 1024**2:.0f} MB, more than '
+                                         f'Frame Control merges ({MAX_SPLIT_MEMBER // 1024**2} MB)')
+                    total += member.file_size
+                    if total > MAX_SPLIT_TOTAL:
+                        raise FrameError(f'the split APKs add more than {MAX_SPLIT_TOTAL // 1024**3} GB, more than '
+                                         'Frame Control merges')
+                    taken.add(entry)
+                    plan[entry] = (path, entry, member.file_size)
+        return plan
+    except (OSError, zipfile.BadZipFile, struct.error, IndexError, frame_apk.ApkError) as e:
+        raise FrameError(f'could not read the split APKs: {e}') from e
+
+
+def resources_empty(data):
+    """True only for a resource table that provably defines nothing: every type chunk's
+    entries absent. Bags (styles, plurals) count, and anything not understood counts too."""
+    def covered(start, end):
+        chunks, at = [], start
+        for chunk in frame_apk._chunks(data, start, end):
+            if chunk[2] != at:
+                return None
+            chunks.append(chunk)
+            at = chunk[2] + chunk[3]
+        return chunks if at == end else None
+
+    try:
+        if len(data) < 12 or struct.unpack_from('<H', data, 0)[0] != 0x0002:
+            return False
+        top = covered(struct.unpack_from('<H', data, 2)[0], len(data))
+        if top is None:
+            return False
+        for ctype, _, off, size in top:
+            if ctype == 0x0001:  # the global string pool
+                continue
+            if ctype != 0x0200:
+                return False
+            inner = covered(off + struct.unpack_from('<H', data, off + 2)[0], off + size)
+            if inner is None:
+                return False
+            for kind, hs, t, _ in inner:
+                if kind in (0x0001, 0x0202):  # type and key names, type specs
+                    continue
+                if kind != 0x0201:
+                    return False
+                flags, count = struct.unpack_from('<xBxxI', data, t + 8)
+                if flags & 0x01:  # sparse: only present entries are listed
+                    if count:
+                        return False
+                elif flags & 0x02:
+                    if any(o != 0xffff for o in struct.unpack_from(f'<{count}H', data, t + hs)):
+                        return False
+                elif any(o != 0xffffffff for o in struct.unpack_from(f'<{count}I', data, t + hs)):
+                    return False
+        return True
+    except (struct.error, IndexError):
+        return False
+
+
+def _zip64_sizes(extra, usize, csize):
+    """(uncompressed, compressed) with 0xffffffff fields taken from a ZIP64 extra field."""
+    at = 0
+    while at + 4 <= len(extra):
+        kind, length = struct.unpack_from('<HH', extra, at)
+        body = extra[at + 4:at + 4 + length]
+        if kind == 0x0001:
+            values, pos = [], 0
+            for field in (usize, csize):
+                if field == 0xffffffff:
+                    if pos + 8 > len(body):
+                        raise FrameError('truncated ZIP64 extra field')
+                    values.append(struct.unpack_from('<Q', body, pos)[0])
+                    pos += 8
+                else:
+                    values.append(field)
+            return tuple(values)
+        at += 4 + length
+    if 0xffffffff in (usize, csize):
+        raise FrameError('ZIP64 sizes without a ZIP64 extra field')
+    return usize, csize
+
+
+def _has_zip64_extra(extra):
+    at = 0
+    while at + 4 <= len(extra):
+        kind, length = struct.unpack_from('<HH', extra, at)
+        if kind == 0x0001:
+            return True
+        at += 4 + length
+    return False
+
+
+def read_member(path, member):
+    """A split member's bytes, read from its raw data and checked against both headers.
+
+    The local header must name the same file, with the same method and (unless a data
+    descriptor carries them, which is then checked) the same sizes and checksum as the
+    central directory; the data must end before the next member; a stored member must be
+    exactly its size and a deflated stream must end exactly at the end of its data, with
+    nothing after it. Output is bounded by the declared size: never trusts zipfile, which
+    stops early at a smaller declared size."""
+    with zipfile.ZipFile(path) as z:
+        info = z.getinfo(member)
+        starts = sorted({i.header_offset for i in z.infolist()} | {z.start_dir})
+    name, size = f'{member} in {os.path.basename(path)}', info.file_size
+    if info.flag_bits & 1 or info.compress_type not in (zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED):
+        raise FrameError(f'{name} is encrypted or uses a compression Android does not')
+    if size > MAX_SPLIT_MEMBER or info.compress_size > MAX_SPLIT_MEMBER:
+        raise FrameError(f'{name} is larger than Frame Control merges ({MAX_SPLIT_MEMBER // 1024**2} MB)')
+    following = next((o for o in starts if o > info.header_offset), None)
+    with open(path, 'rb') as raw:
+        raw.seek(info.header_offset)
+        header = raw.read(30)
+        if len(header) != 30 or header[:4] != b'PK\3\4':
+            raise FrameError(f'{name}: invalid local ZIP header')
+        flags, method, crc, csize, usize, nl, el = struct.unpack_from('<2xHH4xIIIHH', header, 4)
+        local_name, extra = raw.read(nl), raw.read(el)
+        if local_name != info.orig_filename.encode('utf-8' if flags & 0x800 else 'cp437', 'surrogateescape'):
+            raise FrameError(f'{name}: the local header names {local_name.decode("utf-8", "replace")!r}')
+        if method != info.compress_type or (flags & 0x08) != (info.flag_bits & 0x08):
+            raise FrameError(f'{name} does not match its header (local and central entries differ)')
+        start = info.header_offset + 30 + nl + el
+        compressed = raw.read(info.compress_size)
+        if len(compressed) != info.compress_size:
+            raise FrameError(f'{name} is truncated')
+        if flags & 0x08:
+            # Sizes and checksum follow the data: (signature,) crc, then sizes of 4 bytes each,
+            # or 8 for ZIP64. Streaming writers use the ZIP64 form even for small files when
+            # sizes weren't known up front, so the width isn't implied by the final sizes: take
+            # the layout that matches the central directory and fits before the next entry,
+            # preferring one that ends exactly there, then the width the local header implies.
+            zip64 = 0xffffffff in (csize, usize) or _has_zip64_extra(extra)
+            tail = raw.read(24)
+            if len(tail) < 12:
+                raise FrameError(f'{name}: truncated data descriptor')
+            end = start + info.compress_size
+            fits = []
+            for signed in (True, False):
+                if signed and tail[:4] != b'PK\7\x08':
+                    continue
+                for width in (20, 12):
+                    body = tail[4:4 + width] if signed else tail[:width]
+                    if len(body) < width:
+                        continue
+                    values = struct.unpack_from('<IQQ' if width == 20 else '<III', body)
+                    length = width + (4 if signed else 0)
+                    if values == (info.CRC, info.compress_size, size) and \
+                            (following is None or end + length <= following):
+                        exact = following is not None and end + length == following
+                        fits.append((not exact, (width == 20) != zip64, length))
+            if not fits:
+                raise FrameError(f'{name} does not match its header (local and central entries differ, '
+                                 'or its data descriptor is truncated)')
+            crc, csize, usize = info.CRC, info.compress_size, size
+            descriptor = min(fits)[2]
+        else:
+            usize, csize = _zip64_sizes(extra, usize, csize)
+            descriptor = 0
+    if (crc, csize, usize) != (info.CRC, info.compress_size, size):
+        raise FrameError(f'{name} does not match its header (local and central entries differ)')
+    if following is not None and start + info.compress_size + descriptor > following:
+        raise FrameError(f'{name} overlaps the next ZIP entry')
+    if info.compress_type == zipfile.ZIP_STORED:
+        if info.compress_size != size:
+            raise FrameError(f'{name} does not match its header (stored {info.compress_size} bytes, says {size})')
+        data = compressed
+    else:
+        inflate = zlib.decompressobj(-15)
+        try:
+            data = inflate.decompress(compressed, size + 1)
+        except zlib.error as e:
+            raise FrameError(f'{name} is corrupt: {e}') from e
+        if len(data) != size or not inflate.eof or inflate.unconsumed_tail or inflate.unused_data:
+            raise FrameError(f'{name} does not match its header (its compressed data is not exactly '
+                             f'{size} bytes with nothing after it)')
+    if zlib.crc32(data) != info.CRC:
+        raise FrameError(f'{name} does not match its checksum')
+    return data
+
+
+def merge_splits(base, splits, dst):
+    """One installable APK from a base APK and its splits (see split_entries), re-signed
+    with Frame Control's key, without the base's isSplitRequired flag."""
+    plan = split_entries(base, splits)
+    add, total = {}, 0
+    try:
+        for entry, (path, member, size) in plan.items():
+            data = read_member(path, member)
+            total += len(data)
+            if total > MAX_SPLIT_TOTAL:
+                raise FrameError(f'the split APKs add more than {MAX_SPLIT_TOTAL // 1024**3} GB')
+            add[entry] = data
+        with zipfile.ZipFile(base) as z:
+            original = frame_apk._read(z, 'AndroidManifest.xml', frame_apk.MAX_MANIFEST)
+        manifest = drop_split_required(original)
+        repack(base, dst, replace={'AndroidManifest.xml': manifest} if manifest != original else None, add=add)
+    except (OSError, ValueError, IndexError, struct.error, zipfile.BadZipFile, frame_apk.ApkError) as e:
+        raise FrameError(f'could not merge the split APKs: {e}') from e
+    return {'merged': sorted(os.path.basename(p) for p in splits), 'entries': len(plan)}
+
+
+def split_size(splits):
+    """Bytes a merge adds, from the split headers (merge_splits enforces the real sizes)."""
+    total = 0
+    for path in splits:
+        with zipfile.ZipFile(path) as z:
+            total += sum(m.file_size for m in z.infolist() if SPLIT_ADDS.match(m.filename))
+    return total
+
+
+def install(apk_path, flatscreen=None, name=None, source=None, icon_png=None, xr_compat=None, artwork=None,
+            splits=None):
+    """splits: the rest of a split APK (base first, as apk_path); merged into one APK first."""
+    if splits:
+        start = time.time()
+        with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-') as tmp:
+            merged = os.path.join(tmp, 'merged.apk')
+            try:
+                merge_splits(apk_path, list(splits), merged)
+            except Exception as e:  # reported like any other failed install
+                _after_install(None, None, e, start)
+                raise
+            meta = install(merged, flatscreen, name, source or os.path.basename(apk_path), icon_png, xr_compat, artwork)
+            return meta
     start, info = time.time(), None
     try:
         info = apk_info(apk_path)
@@ -273,6 +571,7 @@ def _install(apk_path, info, pkg, flatscreen, name, source, artwork=None):
                                               'source': source or os.path.basename(apk_path)})
         presentation['warnings'] = art_warnings + presentation.get('warnings', [])
         meta = {'package': pkg, 'label': name or info['label'], 'version': info['version'],
+                'version_code': info.get('version_code'),
                 'instance': iid, 'shortcut': shortcut, 'game_id': game_id(shortcut),
                 'vr': info.get('vr', False), 'vr_issues': info.get('vr_issues', []),
                 'launchable': info.get('launchable', False), 'patched': info.get('patched', []),
@@ -359,6 +658,34 @@ except (OSError, ValueError, TypeError, AttributeError):
 """
 
 
+def _apk_parser_script():
+    """Frame-side Python preamble that loads this copy's stdlib APK parser (frame_apk)."""
+    script = 'import sys, types, json, base64\n'
+    for module in ('frame_apk', 'frame_apk_vr'):
+        with open(os.path.join(ROOT, 'ui', module + '.py')) as f:
+            source = f.read()
+        script += f'm = types.ModuleType({module!r}); sys.modules[{module!r}] = m; exec({source!r}, m.__dict__)\n'
+    return script
+
+
+def installed_version_code(pkg):
+    """The version code of pkg's installed app.apk, read on the Frame (only its manifest
+    crosses the link), or None if there is no readable APK. Connection failures raise."""
+    if not PKG_RE.match(pkg or ''):
+        raise FrameError(f'bad package name {pkg!r}')
+    script = _apk_parser_script() + f"""try:
+    code = sys.modules['frame_apk'].apk_info({(APPS_DIR + '/' + pkg + '/app.apk')!r}).get('version_code')
+except Exception:
+    code = None
+print(json.dumps(code if isinstance(code, int) else None))
+"""
+    try:
+        code = json.loads(ssh('python3 -', input=script, timeout=120).strip().splitlines()[-1])
+    except (ValueError, IndexError):
+        return None
+    return code if isinstance(code, int) and not isinstance(code, bool) else None
+
+
 def art_missing(m):
     """True when a Frame Control install has no complete Steam artwork on record."""
     return set((m or {}).get('artwork') or {}) != set(frame_artwork.SLOTS)
@@ -380,13 +707,7 @@ def refresh_art(pkg=None, artwork=None, fill_only=False):
         m = _meta_or_fail(pkg)
         d = f'{APPS_DIR}/{pkg}'
         # Parse the APK on the Frame, transferring only its icon/label, not the APK.
-        modules = {}
-        for module in ('frame_apk', 'frame_apk_vr'):
-            with open(os.path.join(ROOT, 'ui', module + '.py')) as f:
-                modules[module] = f.read()
-        script = 'import sys, types, json, base64\n'
-        for module, source in modules.items():
-            script += f'm = types.ModuleType({module!r}); sys.modules[{module!r}] = m; exec({source!r}, m.__dict__)\n'
+        script = _apk_parser_script()
         script += f"info = sys.modules['frame_apk'].apk_info({(d + '/app.apk')!r})\n"
         script += "info['icon_png'] = base64.b64encode(info.get('icon_png') or b'').decode()\n"
         script += cached_art_script(d) + "info['artwork'] = cached\nprint(json.dumps(info))\n"
@@ -447,10 +768,22 @@ def _clean_meta(m):
     return m
 
 
-def running_instances():
-    """Lepton container name -> adb port, for the instances that are running now."""
-    out = ssh('podman ps --format "{{.Names}} {{.Labels.adb_port}}" 2>/dev/null || true')
-    return dict(line.split()[:2] for line in out.splitlines() if len(line.split()) >= 2)
+def running_instances(strict=False):
+    """Lepton container name -> adb port, for the instances that are running now.
+
+    strict: a failed `podman ps` raises FrameError instead of reading as "nothing running",
+    and containers without an adb port label count too (port None); for callers that must
+    not mistake an error for a stopped instance."""
+    if not strict:
+        out = ssh('podman ps --format "{{.Names}} {{.Labels.adb_port}}" 2>/dev/null || true')
+        return dict(line.split()[:2] for line in out.splitlines() if len(line.split()) >= 2)
+    out = ssh('podman ps --format "{{.Names}} {{.Labels.adb_port}}"')
+    found = {}
+    for line in out.splitlines():
+        cols = line.split()
+        if cols:
+            found[cols[0]] = cols[1] if len(cols) > 1 and cols[1] != '<no' else None
+    return found
 
 
 def list_apps():
@@ -599,8 +932,11 @@ def main():
             r = frame_apk_versions.alternatives(
                 info['package'] if info else args[0], info.get('version_code') if info else None)
         elif cmd == 'install':
-            r = install(args[0], flatscreen=False if '--vr' in args else True if '--flat' in args else None,
-                        xr_compat=False if '--no-xr-compat' in args else None)
+            files = [a for a in args if not a.startswith('--')]
+            if not files:
+                raise FrameError('install requires APK [SPLIT.apk ...]')
+            r = install(files[0], flatscreen=False if '--vr' in args else True if '--flat' in args else None,
+                        xr_compat=False if '--no-xr-compat' in args else None, splits=files[1:])
         elif cmd == 'refresh-art':
             if len(args) != 1:
                 raise FrameError('usage: refresh-art PACKAGE or refresh-art --all')

ui/frame_apk_vr.py

@@ -118,7 +118,7 @@ def detection(data, names):
     info, _ = inspect(data)
     issues = []
     if 'lib/arm64-v8a/libvrapi.so' in names:
-        issues.append("Uses Meta's legacy VrApi, which the Frame doesn't have; it won't run.")
+        issues.append("Uses Meta's legacy VrApi, which the Frame doesn't have; it may not run.")
     if any(n.endswith('/libovrplatformloader.so') for n in names):
         issues.append("Uses Meta's platform SDK; if it checks your Quest store licence it will quit.")
     if 'lib/arm64-v8a/libopenxr_loader.so' in names:
@@ -126,3 +126,46 @@ def detection(data, names):
         issues.append('Uses OpenXR (good).')
     info['vr_issues'] = issues
     return info
+
+
+IS_SPLIT_REQUIRED = 0x01010591  # android:isSplitRequired
+
+
+def drop_split_required(axml_bytes):
+    """The manifest without <application android:isSplitRequired>, for a base APK whose
+    splits were merged into it: Android refuses a lone base that still says it needs them."""
+    chunks = list(frame_apk._chunks(axml_bytes, 8, len(axml_bytes)))
+    pool = next((c for c in chunks if c[0] == 1), None)
+    if pool is None:
+        raise frame_apk.ApkError('AndroidManifest.xml has no string pool')
+    strings = frame_apk._string_pool(axml_bytes, pool[2])
+    resmap = ()
+    for kind, header_size, offset, chunk_size in chunks:
+        if kind == 0x180:
+            resmap = struct.unpack_from('<%dI' % ((chunk_size - header_size) // 4), axml_bytes, offset + header_size)
+    result, changed = bytearray(axml_bytes[:8]), False
+    for kind, hs, off, size in chunks:
+        chunk = bytearray(axml_bytes[off:off + size])
+        if kind == 0x0102 and not changed:
+            name, astart, asize, count = struct.unpack_from('<4xIHHH', chunk, hs)
+            if name < len(strings) and strings[name] == 'application':
+                for i in range(count):
+                    a = hs + astart + i * asize
+                    attr = struct.unpack_from('<I', chunk, a + 4)[0]
+                    known = resmap[attr] if attr < len(resmap) else None
+                    if known == IS_SPLIT_REQUIRED or (known is None and attr < len(strings)
+                                                      and strings[attr] == 'isSplitRequired'):
+                        del chunk[a:a + asize]
+                        struct.pack_into('<I', chunk, 4, len(chunk))
+                        struct.pack_into('<H', chunk, hs + 12, count - 1)
+                        # id/class/style attribute indexes are 1-based positions in the list.
+                        for at in (hs + 14, hs + 16, hs + 18):
+                            index = struct.unpack_from('<H', chunk, at)[0]
+                            struct.pack_into('<H', chunk, at, 0 if index == i + 1 else index - 1 if index > i + 1 else index)
+                        changed = True
+                        break
+        result += chunk
+    if not changed:
+        return axml_bytes
+    struct.pack_into('<I', result, 4, len(result))
+    return bytes(result)

ui/frame_macview.py

@@ -56,12 +56,12 @@ BROWSER_FLAGS = []
 PANEL_BOX = (1920, 1080)
 
 # Opens one viewer on gamescope's X display and gives its window its own panel
-# id. Args: appid url width height tag [browser flags...]. The page puts "[tag]" in its title at
+# id. Args: appid url width height tag profile [browser flags...]. The page puts "[tag]" in its title at
 # once, which is how its X window is found (Chromium may hand the URL to an
 # instance that's already running, so there's no process to follow).
 LAUNCH = r"""set -u
-appid=$1 url=$2 w=$3 h=$4 tag=$5
-shift 5
+appid=$1 url=$2 w=$3 h=$4 tag=$5 profile=$6
+shift 6
 export DISPLAY=:0 LC_ALL=C.UTF-8
 unset WAYLAND_DISPLAY
 if ! xprop -root GAMESCOPE_FOCUSABLE_WINDOWS >/dev/null 2>&1; then
@@ -73,15 +73,15 @@ common=(--ozone-platform=x11 --force-device-scale-factor=1 --no-first-run --no-d
   --disable-features=Translate,MediaRouter --autoplay-policy=no-user-gesture-required
   "--window-size=$w,$h" "$@" "--app=$url")
 if [ -x "$HOME/chromium-xr/chrome" ]; then
-  cmd=("$HOME/chromium-xr/chrome" "--user-data-dir=$HOME/.local/share/frame-control/mac-view" "${common[@]}")
+  cmd=("$HOME/chromium-xr/chrome" "--user-data-dir=$HOME/.local/share/frame-control/$profile" "${common[@]}")
 elif flatpak info org.chromium.Chromium >/dev/null 2>&1; then
   cmd=(flatpak run org.chromium.Chromium
-    "--user-data-dir=$HOME/.var/app/org.chromium.Chromium/data/frame-mac-view" "${common[@]}")
+    "--user-data-dir=$HOME/.var/app/org.chromium.Chromium/data/frame-$profile" "${common[@]}")
 else
   echo "NO_BROWSER"
   exit 3
 fi
-log=/tmp/frame-mac-view.log
+log=/tmp/frame-$profile.log
 setsid nohup "${cmd[@]}" >>"$log" 2>&1 </dev/null &
 for _ in $(seq 1 60); do
   sleep 0.5
@@ -105,9 +105,9 @@ class MacViewError(Exception):
     pass
 
 
-def panel_id(src):
+def panel_id(src, host="mac"):
     """A stable panel id per source, in the range panel-on-frame.sh uses."""
-    return 2_001_000_000 + zlib.crc32(f"mac:{src}".encode()) % 1_000_000
+    return 2_001_000_000 + zlib.crc32(f"{host}:{src}".encode()) % 1_000_000
 
 
 def fit(w, h, box=PANEL_BOX):
@@ -116,6 +116,9 @@ def fit(w, h, box=PANEL_BOX):
 
 
 class MacView:
+    host = "mac"
+    viewer_profile = "mac-view"
+
     def __init__(self, tunnel_ssh, run, frame, track=None):
         self.tunnel_ssh = list(tunnel_ssh)
         self.run = run
@@ -170,10 +173,17 @@ class MacView:
     def _stale(self):
         try:
             built = AGENT.stat().st_mtime
-            return any(p.stat().st_mtime > built for p in (SOURCES / "Sources").glob("*.swift"))
+            return any(p.stat().st_mtime > built for p in [*(SOURCES / "Sources").glob("*.swift"),
+                       ROOT / "desktop" / "controller.c", ROOT / "desktop" / "controller.h"])
         except OSError:
             return False
 
+    def agent_command(self):
+        return [str(AGENT)]
+
+    def agent_environment(self):
+        return {**os.environ, "FRAME_MAC_VIEW_TOKEN": self.token}
+
     def ensure_agent(self):
         with self.lock:
             if self.agent and self.agent.poll() is None:
@@ -182,11 +192,11 @@ class MacView:
             if reason:
                 raise MacViewError(reason)
             self.build()
-            env = {**os.environ, "FRAME_MAC_VIEW_TOKEN": self.token}
+            env = self.agent_environment()
             # The same port as before when restarting, so a running tunnel still
             # fits; otherwise (or if it's gone) whatever the system gives.
             for port in dict.fromkeys([self.port or 0, 0]):
-                self.agent = subprocess.Popen([str(AGENT), "serve", "--port", str(port), "--page", str(PAGE),
+                self.agent = subprocess.Popen([*self.agent_command(), "serve", "--port", str(port), "--page", str(PAGE),
                                                "--exit-on-eof"], env=env, stdin=subprocess.PIPE,
                                               stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
                 line = self.agent.stdout.readline()
@@ -195,7 +205,7 @@ class MacView:
                     break
                 self.agent.kill()
             else:
-                raise MacViewError(f"The Mac streaming helper didn't start: {line.strip() or 'no output'}")
+                raise MacViewError(f"The streaming helper didn't start: {line.strip() or 'no output'}")
             if self.port != int(m.group(1)):
                 self._drop_tunnel()
             self.port = int(m.group(1))
@@ -211,7 +221,7 @@ class MacView:
             with urllib.request.urlopen(req, timeout=10) as r:
                 return json.load(r)
         except (urllib.error.URLError, OSError, ValueError) as e:
-            raise MacViewError(f"The Mac streaming helper didn't answer: {e}")
+            raise MacViewError(f"The streaming helper didn't answer: {e}")
 
     # ---- the tunnel from the Frame ----
 
@@ -396,7 +406,7 @@ class MacView:
         # the agent no longer counts them, so only move when none are out there.
         others = self.shown - {src}
         self.ensure_tunnel(allow_new_port=not others)
-        appid = panel_id(src)
+        appid = panel_id(src, self.host)
         # Unique per launch, so a new window is never confused with an old one.
         tag = "fc" + secrets.token_hex(4)
         # A single-use ticket for this source, not Frame Control's key: the URL
@@ -406,7 +416,7 @@ class MacView:
                   "bpp": q["bpp"]}
         url = f"http://127.0.0.1:{self.remote_port}/view?{urlencode(params)}"
         w, h = fit(width or 1280, height or 720)
-        args = " ".join(_quote(str(a)) for a in (appid, url, w, h, tag, *self.browser_flags))
+        args = " ".join(_quote(str(a)) for a in (appid, url, w, h, tag, self.viewer_profile, *self.browser_flags))
         try:
             out = self.run("bash -s -- " + args, stdin=LAUNCH, timeout=60)
         except Exception as e:  # noqa: BLE001 - the server's Failure carries the Frame's words
@@ -438,7 +448,8 @@ class MacView:
             if self.shown or self.shows != shows or self.launching:
                 return
             try:
-                self.run("pkill -f '[f]rame-control/mac-view|[d]ata/frame-mac-view' || true", timeout=10)
+                pattern = "[f]rame-control/" + self.viewer_profile + "|[d]ata/frame-" + self.viewer_profile
+                self.run("pkill -f " + _quote(pattern) + " || true", timeout=10)
             except Exception:
                 pass
 
@@ -449,7 +460,8 @@ class MacView:
         status = self.call("/status")
         windows = self.call("/windows").get("windows", []) if status.get("screen") else []
         displays = self.call("/displays").get("displays", [])
-        return {"available": True, "screen": status.get("screen", False),
+        return {"available": True, "host": self.host, "selecting": status.get("selecting", False),
+                "selectionError": status.get("selectionError", ""), "screen": status.get("screen", False),
                 "accessibility": status.get("accessibility", False), "streams": status.get("streams", []),
                 "windows": windows, "displays": displays, "tunnel": self.tunnel_up(),
                 "route": self.route}

ui/frame_pc_agent.py

@@ -0,0 +1,624 @@
+#!/usr/bin/env python3
+"""Frame Control's Windows/Linux host. Same ticket, H.264/JPEG, timing and
+input protocol as frame-mac-view; serves the same ui/mac-view.html.
+
+Only loopback is bound. Frame Control owns the master token, the Frame gets
+one-source tickets and reconnect keys. Native libraries are bundled.
+"""
+import argparse
+import base64
+import ctypes as C
+import hashlib
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import math
+import os
+import queue
+from pathlib import Path
+import secrets
+import socket
+import struct
+import sys
+import threading
+import time
+from urllib.parse import parse_qs, urlsplit
+
+from frame_pc_capture import Native, Controller, Windows, WindowsInput, PortalInput, Encoded, GATE, dimensions, pipeline
+from frame_stream_stats import Stats
+
+
+# Viewer fields are untrusted JSON: float('x'), int(None), m['t'] missing.
+MALFORMED = (ValueError, TypeError, KeyError, OverflowError)
+
+
+class Grants:
+    """Caller holds the agent lock, including replacement and Stop."""
+    def __init__(self, token):
+        self.token, self.tickets, self.keys = token, {}, {}
+
+    def master(self, key):
+        return isinstance(key, str) and secrets.compare_digest(key, self.token)
+
+    def ticket(self, src):
+        self.tickets = {k: v for k, v in self.tickets.items() if v[1] > time.monotonic()}
+        if len(self.tickets) >= 128:
+            raise ValueError('Too many pending viewers')
+        ticket = secrets.token_urlsafe(24)
+        self.tickets[ticket] = (src, time.monotonic()+60, None)
+        return ticket
+
+    def redeem(self, src, q):
+        if self.master(q.get('k')):
+            key = secrets.token_urlsafe(24)
+            self.keys[key] = src
+            return key
+        entry = self.tickets.get(q.get('t'))
+        if entry and entry[0] == src and entry[1] > time.monotonic():
+            key = entry[2] or secrets.token_urlsafe(24)
+            self.tickets[q['t']] = (src, entry[1], key)
+            self.keys[key] = src
+            return key
+        key = q.get('r')
+        return key if key and self.keys.get(key) == src else None
+
+    def ack(self, key):
+        self.tickets = {k: v for k, v in self.tickets.items() if v[2] != key}
+
+    def revoke(self, src=None):
+        self.tickets = {k: v for k, v in self.tickets.items() if src is not None and v[0] != src}
+        self.keys = {k: v for k, v in self.keys.items() if src is not None and v != src}
+
+
+class WebSocket:
+    def __init__(self, handler):
+        self.sock, self.reader = handler.connection, handler.rfile
+        self.lock = threading.Lock()
+        self.closed = False
+        self.sock.settimeout(5)
+        self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+
+    def send(self, data, opcode=1):
+        if not isinstance(data, bytes):
+            data = json.dumps(data, separators=(',', ':')).encode()
+        n = len(data)
+        head = bytes([0x80 | opcode, n]) if n < 126 else bytes([0x80 | opcode, 126]) + struct.pack('!H', n) if n <= 65535 else bytes([0x80 | opcode, 127]) + struct.pack('!Q', n)
+        with self.lock:
+            if self.closed:
+                raise ConnectionError('Viewer disconnected')
+            self.sock.sendall(head + data)
+
+    def exact(self, n):
+        data = self.reader.read(n)
+        if len(data) != n:
+            raise ConnectionError('Viewer disconnected')
+        return data
+
+    def receive(self):
+        a, b = self.exact(2)
+        opcode, size = a & 15, b & 127
+        if a & 0x70 or not a & 0x80 or not b & 0x80 or opcode not in (1, 8, 9, 10):
+            raise ValueError('Unsupported WebSocket frame')
+        if size == 126:
+            size = struct.unpack('!H', self.exact(2))[0]
+        elif size == 127:
+            size = struct.unpack('!Q', self.exact(8))[0]
+        if size > 65536 or (opcode >= 8 and size > 125):
+            raise ValueError('WebSocket message too large')
+        mask = self.exact(4)
+        data = bytes(v ^ mask[i % 4] for i, v in enumerate(self.exact(size)))
+        if opcode == 8:
+            raise ConnectionError('Viewer closed')
+        if opcode == 9:
+            self.send(data, 10)
+        if opcode != 1:
+            return {}
+        message = json.loads(data)
+        if not isinstance(message, dict):
+            raise ValueError('Expected an input object')
+        return message
+
+    def close(self):
+        self.closed = True
+        try:
+            self.sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+
+
+class Session:
+    def __init__(self, agent, ws, key, source, query):
+        self.agent, self.native, self.ws, self.key, self.source = agent, agent.native, ws, key, source
+        self.src = source['src']
+        self.codec = query.get('codec', 'h264')
+        if self.codec not in ('h264', 'jpeg'):
+            raise ValueError('Unsupported codec')
+        self.fps = min(120, max(5, int(query.get('fps', 60))))
+        bpp = float(query.get('bpp', .1))
+        if not math.isfinite(bpp):
+            raise ValueError('Invalid bitrate')
+        self.w, self.h = dimensions(source['w'], source['h'], min(3840, max(320, int(query.get('max', 1920)))))
+        self.bitrate = max(300000, int(self.w*self.h*self.fps*min(.5, max(.02, bpp))))
+        self.controller = Controller(self.native.lib, self.fps, self.bitrate)
+        self.stats = Stats(self.native.now)
+        self.stop_event, self.key_event = threading.Event(), threading.Event()
+        self.lock, self.input_lock = threading.RLock(), threading.RLock()
+        self.pending, self.last_submit = {}, 0
+        self.reconfiguring = False
+        self.test_inputs = queue.Queue(maxsize=128)
+        self.input = None if self.src == 'test' else WindowsInput(agent.windows, source) if agent.windows else PortalInput(self.native, source)
+        self.writer = None
+        self.released = False
+        self.input_enabled = self.src == 'test' or self.source.get('devices', 3) == 3
+
+    def gate(self, stage, pts, capture, arrived):
+        # Exceptions cannot cross a ctypes callback boundary.
+        try:
+            with self.lock:
+                if self.stop_event.is_set() or self.reconfiguring:
+                    return -1
+                if stage == 1:
+                    if pts in self.pending:
+                        self.pending[pts]['e0'] = self.native.now()
+                    return 1
+                if stage == 0:
+                    self.stats.captured += 1
+                    self.controller.call('capture', arrived)
+                now = self.native.now()
+                state = self.controller.state()
+                if len(self.pending) >= 3 or now-self.last_submit < 1000000/state['fps'] or not self.controller.call('gate', now, int(stage == 0)):
+                    if stage == 0:
+                        self.stats.skipped += 1
+                    return 0
+                self.pending[pts] = dict(cap=capture, arr=arrived, e0=now, tier=state['tier'], br=state['target'])
+                self.last_submit = now
+                return 1
+        except Exception:
+            self.stop_event.set()
+            return -1
+
+    STALL = 10000000
+
+    def stalled(self, now, opened, captured_at_open):
+        """PipeWire and WGC deliver frames only on screen damage, so an idle
+        desktop legitimately produces no output. Fail only on evidence of a
+        fault: a frame entered the encoder and never came out, or the capture
+        never produced its initial frame after the pipeline opened."""
+        with self.lock:
+            oldest = min((r['e0'] for r in self.pending.values()), default=None)
+            captured = self.stats.captured
+        if oldest is not None and now-oldest > self.STALL:
+            return 'The encoder stopped producing frames; check the video encoder'
+        if captured == captured_at_open and now-opened > self.STALL:
+            return 'No frames captured for 10 seconds; check capture permissions'
+        return None
+
+    def fresh_pipewire(self):
+        if 'portal' not in self.source:
+            return
+        error = C.create_string_buffer(1024)
+        fd = self.native.lib.fc_portal_refresh(self.source['portal'], error, len(error))
+        if fd < 0:
+            raise RuntimeError(error.value.decode(errors='replace'))
+        self.source['fd'] = fd
+
+    def produce(self):
+        native, capture = self.native.lib, None
+        try:
+            encoder = "x264enc" if self.src == "test" and self.native.has("x264enc") else self.agent.encoder
+            self.fresh_pipewire()
+            description = pipeline(self.source, sys.platform, encoder, self.w, self.h, self.fps, self.bitrate, self.codec)
+            self.callback = GATE(self.gate)
+            error = C.create_string_buffer(1024)
+            capture = native.fc_capture_open(description.encode(), self.callback, error, len(error))
+            if not capture:
+                raise RuntimeError(error.value.decode(errors='replace'))
+            last_update = last_stats = self.native.now()
+            last_config = opened = last_update
+            captured_at_open = self.stats.captured
+            applied = (self.w, self.h, self.bitrate)
+            wanted = applied
+            while not self.stop_event.is_set():
+                while not self.test_inputs.empty():
+                    event = self.test_inputs.get_nowait()
+                    try:
+                        native.fc_capture_test(capture, int(event.get('i', 0)) & 0xffffffff)
+                        self.stats.input(event)
+                    except MALFORMED:
+                        pass  # a bad probe field drops the event, not the stream
+                output = Encoded()
+                result = native.fc_capture_pull(capture, C.byref(output))
+                now = self.native.now()
+                if result < 0:
+                    raise RuntimeError(native.fc_capture_error(capture).decode(errors='replace'))
+                if result:
+                    with self.lock:
+                        # At most three raw frames are in flight; no B-frames.
+                        # x264 offsets PTS, so match the FIFO encode order while
+                        # retaining the actual pre-encode capture timestamp.
+                        raw_pts = next(iter(self.pending), None)
+                        record = self.pending.get(raw_pts)
+                        if record is None:
+                            raise RuntimeError('Encoder changed frame timestamps; timing cannot be matched')
+                        data = C.string_at(output.data, output.size)
+                        f = self.stats.add(**record, e1=now, snd=now, b=len(data), k=output.key,
+                                           w=output.width or self.w, h=output.height or self.h)
+                        self.controller.call('sent', f['s'], len(data)+17, now)
+                    self.ws.send(struct.pack('!BQII', output.key, max(0, f['cap']), f['s'], f['echo'])+data, 2)
+                    with self.lock:
+                        f['wire'] = self.native.now()
+                        self.pending.pop(raw_pts, None)
+                stall = self.stalled(now, opened, captured_at_open)
+                if stall:
+                    raise RuntimeError(stall)
+                if self.key_event.is_set():
+                    self.key_event.clear()
+                    if self.codec == 'h264':
+                        native.fc_capture_key(capture)
+                if now-last_update >= 100000:
+                    target = self.controller.update(now)
+                    state = self.controller.state()
+                    w, h = dimensions(self.w, self.h, max(320, int(max(self.w, self.h)*state['scale'])))
+                    if target and self.codec == 'h264' and encoder == 'x264enc':
+                        native.fc_capture_bitrate(capture, target)
+                        self.bitrate = target
+                    # Hardware properties are not uniformly mutable in PLAYING.
+                    # Drain then reopen the pipeline at a keyframe when its
+                    # budget changes materially. The portal fd/session stays
+                    # alive, so this does not bypass or repeat user consent.
+                    desired_bitrate = target or applied[2]
+                    bitrate_change = self.codec == 'h264' and encoder != 'x264enc' and abs(desired_bitrate-applied[2]) > applied[2]*.2
+                    if not self.reconfiguring and now-last_config >= 1000000 and ((w, h) != applied[:2] or bitrate_change):
+                        wanted = (w, h, desired_bitrate)
+                        with self.lock:
+                            self.reconfiguring = True
+                    last_update = now
+                if self.reconfiguring:
+                    with self.lock:
+                        drained = not self.pending
+                    if drained:
+                        native.fc_capture_close(capture)
+                        capture = None
+                        self.fresh_pipewire()
+                        description = pipeline(self.source, sys.platform, encoder, wanted[0], wanted[1], self.fps, wanted[2], self.codec)
+                        capture = native.fc_capture_open(description.encode(), self.callback, error, len(error))
+                        if not capture:
+                            raise RuntimeError(error.value.decode(errors='replace'))
+                        applied, self.bitrate, last_config = wanted, wanted[2], now
+                        opened, captured_at_open = now, self.stats.captured
+                        with self.lock:
+                            self.reconfiguring = False
+                if now-last_stats >= 1000000:
+                    self.ws.send(dict(self.stats.summary(), t='stats', bitrate=self.bitrate,
+                                      size='%dx%d' % (self.w, self.h), tier=self.controller.state()['tier']))
+                    last_stats = now
+        except Exception as e:
+            try:
+                self.ws.send({'t': 'error', 'message': str(e)})
+            except OSError:
+                pass
+        finally:
+            self.stop_event.set()
+            if capture:
+                native.fc_capture_close(capture)
+            self.ws.close()
+
+    def start(self):
+        if self.stop_event.is_set():
+            self.controller.close()
+            return
+        self.ws.send(dict(t='hello', r=self.key))
+        self.ws.send(dict(t='info', src=self.src, title=self.source.get('title', self.source.get('name', 'Test pattern')),
+                          app='PC', codec=self.codec, input=self.input_enabled,
+                          inputMessage='Allow pointer and keyboard control in the host sharing dialog.',
+                          aspect=self.w/self.h, warm=0))
+        with self.lock:
+            if self.stop_event.is_set():
+                self.controller.close()
+                return
+            self.writer = threading.Thread(target=self.produce, daemon=True)
+            self.writer.start()
+        try:
+            while not self.stop_event.is_set():
+                m = self.ws.receive()
+                t = m.get('t')
+                if t == 'ping':
+                    self.ws.send(dict(t='pong', c=m.get('c', 0), a=self.native.now()))
+                elif t == 'ack':
+                    with self.agent.lock:
+                        self.agent.grants.ack(self.key)
+                elif t == 'key-frame':
+                    self.key_event.set()
+                elif t in ('rx', 'fd', 'clock'):
+                    try:
+                        self.stats.report(m)
+                    except MALFORMED:
+                        pass
+                    if t == 'rx' and isinstance(m.get('s'), int):
+                        self.controller.call('ack', m['s'] & 0xffffffff, self.native.now())
+                elif t in ('m', 'wheel', 'k', 'text', 'release'):
+                    with self.input_lock:
+                        if self.stop_event.is_set():
+                            break
+                        if self.input:
+                            if not self.input_enabled and t != 'release':
+                                continue
+                            try:
+                                self.input.handle(m)
+                                self.stats.input(m)
+                            except MALFORMED:
+                                pass  # drop a malformed viewer event; keep the session
+                            except RuntimeError as e:
+                                self.input_enabled = False
+                                try:
+                                    self.input.release()
+                                except RuntimeError:
+                                    pass
+                                self.ws.send(dict(t='error', message=str(e)))
+                        elif m.get('i'):
+                            try:
+                                self.test_inputs.put_nowait(m)
+                            except queue.Full:
+                                pass
+        finally:
+            self.end()
+            self.writer.join(6)
+            if not self.writer.is_alive():
+                self.controller.close()
+
+    def end(self):
+        with self.lock:
+            self.stop_event.set()
+        self.ws.close()
+        with self.input_lock:
+            if self.input and not self.released:
+                self.released = True
+                try:
+                    self.input.release()
+                except (RuntimeError, OSError):
+                    pass
+
+
+class Agent:
+    def __init__(self, native, token, page):
+        self.native, self.page = native, page
+        self.lock = threading.RLock()
+        self.grants = Grants(token)
+        self.sessions, self.sources = {}, {}
+        self.next_id, self.selecting, self.selection_error = 1, False, ''
+        self.windows = Windows() if sys.platform == 'win32' else None
+        self.encoder = 'mfh264enc' if self.windows else 'vah264enc' if native.has('vah264enc') else 'x264enc'
+        self.shutting_down = False
+        self.selection_generation = 0
+
+    def lists(self):
+        if self.windows:
+            windows, displays = self.windows.sources()
+            self.sources = {s['src']: s for s in windows + displays}
+            return windows, displays
+        return [{k: v for k, v in s.items() if k not in ('portal', 'fd', 'node')} for s in self.sources.values()], []
+
+    def source(self, src):
+        if src == 'test':
+            return dict(src='test', title='Test pattern', w=1280, h=720)
+        self.lists()
+        if src not in self.sources:
+            raise ValueError('Choose a window or screen on this computer first')
+        return dict(self.sources[src])
+
+    def select(self):
+        if self.windows or self.selecting or self.shutting_down:
+            return
+        if len(self.sources) >= 8:
+            raise ValueError('Stop a panel before sharing another source')
+        self.selecting, self.selection_error = True, ''
+        generation = self.selection_generation
+        def choose():
+            error = C.create_string_buffer(1024)
+            portal = self.native.lib.fc_portal_select(error, len(error))
+            with self.lock:
+                self.selecting = False
+                if not portal:
+                    self.selection_error = error.value.decode(errors='replace')
+                elif self.shutting_down or generation != self.selection_generation:
+                    self.native.lib.fc_portal_close(portal)
+                else:
+                    fd, node, w, h, devices = [self.native.lib.fc_portal_value(portal, i) for i in range(5)]
+                    src = 'window:' + secrets.token_hex(8)
+                    self.sources[src] = dict(src=src, title='Shared window or screen', app='Linux portal',
+                                             w=w, h=h, fd=fd, node=node, portal=portal, devices=devices)
+        threading.Thread(target=choose, daemon=True).start()
+
+    def stop(self, src=None):
+        with self.lock:
+            if src is None:
+                self.selection_generation += 1
+            self.grants.revoke(src)
+            sessions = [s for s in self.sessions.values() if src is None or s.src == src]
+            for session in sessions:
+                try:
+                    session.ws.send(dict(t='close'))
+                except OSError:
+                    pass
+                session.end()
+        for session in sessions:
+            if session.writer and session.writer is not threading.current_thread():
+                session.writer.join(6)
+        # The capture is stopped before releasing its PipeWire fd/session.
+        with self.lock:
+            if not self.windows:
+                for key, source in list(self.sources.items()):
+                    if src is None or key == src:
+                        if any(s.src == key and s.writer and s.writer.is_alive() for s in sessions):
+                            continue
+                        self.native.lib.fc_portal_close(source['portal'])
+                        self.sources.pop(key, None)
+        return {'closed': len(sessions)}
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = 'HTTP/1.1'
+
+    def log_message(self, *args):
+        pass  # URLs contain credentials
+
+    def reply(self, data, status=200, content='application/json'):
+        if not isinstance(data, bytes):
+            data = json.dumps(data).encode()
+        self.send_response(status)
+        self.send_header('Content-Type', content)
+        self.send_header('Content-Length', str(len(data)))
+        self.send_header('Cache-Control', 'no-store')
+        self.send_header('Connection', 'close')
+        self.end_headers()
+        self.wfile.write(data)
+        self.close_connection = True
+
+    def do_GET(self):
+        self.dispatch('GET')
+
+    def do_POST(self):
+        self.dispatch('POST')
+
+    def dispatch(self, method):
+        agent = self.server.agent
+        url = urlsplit(self.path)
+        q = {k: v[-1] for k, v in parse_qs(url.query).items()}
+        try:
+            if method == 'GET' and url.path == '/ping':
+                return self.reply(b'frame-mac-view', content='text/plain')
+            if method == 'GET' and url.path == '/view':
+                return self.reply(agent.page.read_bytes(), content='text/html; charset=utf-8')
+            if method == 'GET' and url.path == '/stream':
+                return self.stream(q)
+            if not agent.grants.master(q.get('k', self.headers.get('X-Token'))):
+                return self.reply({'error': 'forbidden'}, 403)
+            if method == 'POST' and url.path == '/close':
+                return self.reply(agent.stop(q.get('src')))
+            with agent.lock:
+                windows, displays = agent.lists()
+                if method == 'GET' and url.path == '/status':
+                    data = dict(version=1, host='windows' if agent.windows else 'linux', screen=True,
+                                accessibility=True, selecting=agent.selecting, selectionError=agent.selection_error,
+                                encoder=agent.encoder, finished=[], streams=[dict(id=i, src=s.src,
+                                    title=s.source.get('title', ''), stats=s.stats.summary(), controller=s.controller.state())
+                                    for i, s in agent.sessions.items() if not s.stop_event.is_set()])
+                elif method == 'GET' and url.path in ('/windows', '/displays'):
+                    data = dict(windows=windows, displays=displays, screen=True)
+                elif method == 'POST' and url.path == '/ticket':
+                    agent.source(q.get('src'))
+                    data = {'ticket': agent.grants.ticket(q['src'])}
+                elif method == 'POST' and url.path == '/permissions':
+                    agent.select()
+                    data = {'selecting': agent.selecting}
+                elif method == 'GET' and url.path == '/stats':
+                    data = dict(now=agent.native.now(), streams=[dict(id=i, src=s.src, controller=s.controller.state(),
+                         events=list(s.controller.events), **s.stats.snapshot(max(0, int(q.get('since', 0))), max(0, int(q.get('settle', 1500000)))))
+                         for i, s in agent.sessions.items() if q.get('id', str(i)) == str(i) and not s.stop_event.is_set()])
+                elif method == 'POST' and url.path == '/bench':
+                    data = {'sent': 0}
+                    for s in agent.sessions.values():
+                        if s.src == q.get('src'):
+                            m = {k: v for k, v in q.items() if k not in ('k', 'src')}
+                            for k in ('x', 'y', 'interval'):
+                                if k in m:
+                                    m[k] = float(m[k])
+                            s.ws.send(dict(m, t='bench'))
+                            data['sent'] += 1
+                else:
+                    return self.reply({'error': 'not found'}, 404)
+            self.reply(data)
+        except (ValueError, RuntimeError) as e:
+            self.reply({'error': str(e)}, 400)
+        except (OSError, ConnectionError):
+            self.close_connection = True
+
+    def stream(self, query):
+        agent = self.server.agent
+        with agent.lock:
+            key = agent.grants.redeem(query.get('src'), query)
+            if not key:
+                return self.reply({'error': 'forbidden'}, 403)
+            source = agent.source(query.get('src'))
+            if self.headers.get('Upgrade', '').lower() != 'websocket' or self.headers.get('Sec-WebSocket-Version') != '13':
+                return self.reply({'error': 'expected WebSocket'}, 400)
+            wskey = self.headers.get('Sec-WebSocket-Key', '')
+            if len(base64.b64decode(wskey, validate=True)) != 16:
+                raise ValueError('Bad WebSocket key')
+            if len(agent.sessions) >= 8:
+                raise ValueError('At most eight panels may be open')
+            # Stop can revoke and close only a registered session. Register
+            # under the same lock as redemption, before any capture starts.
+            session = Session(agent, WebSocket(self), key, source, query)
+            for old in list(agent.sessions.values()):
+                if old.key == key or old.src == source['src']:
+                    if old.key != key:
+                        agent.grants.keys.pop(old.key, None)
+                        try:
+                            old.ws.send(dict(t='close'))
+                        except OSError:
+                            pass
+                    old.end()
+                    if old.writer:
+                        old.writer.join(6)
+                        if old.writer.is_alive():
+                            session.controller.close()
+                            raise ValueError('The previous capture is still stopping; retry shortly')
+            ident = agent.next_id
+            agent.next_id += 1
+            agent.sessions[ident] = session
+            accept = base64.b64encode(hashlib.sha1((wskey+'258EAFA5-E914-47DA-95CA-C5AB0DC85B11').encode()).digest()).decode()
+            self.send_response(101)
+            self.send_header('Upgrade', 'websocket')
+            self.send_header('Connection', 'Upgrade')
+            self.send_header('Sec-WebSocket-Accept', accept)
+            self.end_headers()
+        try:
+            session.start()
+        except (OSError, ValueError, RuntimeError):
+            session.end()
+        finally:
+            session.end()
+            if session.writer:
+                session.writer.join(6)
+            if not session.writer or not session.writer.is_alive():
+                session.controller.close()
+            with agent.lock:
+                agent.sessions.pop(ident, None)
+            self.close_connection = True
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('command', choices=['serve'])
+    parser.add_argument('--port', type=int, default=0)
+    parser.add_argument('--page', type=Path, required=True)
+    parser.add_argument('--exit-on-eof', action='store_true')
+    args = parser.parse_args()
+    token = os.environ.get('FRAME_MAC_VIEW_TOKEN')
+    if not token:
+        raise SystemExit('Frame Control must provide a private token')
+    native = Native()
+    server = ThreadingHTTPServer(('127.0.0.1', args.port), Handler)
+    agent = server.agent = Agent(native, token, args.page)
+    if args.exit_on_eof:
+        def eof():
+            sys.stdin.buffer.read()
+            with agent.lock:
+                agent.shutting_down = True
+            agent.stop()
+            server.shutdown()
+        threading.Thread(target=eof, daemon=True).start()
+    print('listening on 127.0.0.1:%d' % server.server_port, flush=True)
+    try:
+        server.serve_forever()
+    finally:
+        agent.shutting_down = True
+        agent.stop()
+        server.server_close()
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except (OSError, RuntimeError, AttributeError) as e:
+        raise SystemExit('PC streaming helper: ' + str(e))

ui/frame_pc_capture.py

@@ -0,0 +1,383 @@
+"""Native PC capture and input bindings. No desktop-streaming app required.
+
+The packaged native library contains our adapter and the shared rate controller;
+GStreamer supplies WGC/Media Foundation and PipeWire/VA-API/x264 libraries.
+"""
+import ctypes as C
+import os
+from pathlib import Path
+import re
+import sys
+import threading
+
+ROOT = Path(__file__).resolve().parent.parent
+NATIVE = Path(os.environ.get('FRAME_PC_NATIVE', ROOT / 'desktop' / 'bundle'))
+LIBRARY = NATIVE / ('pc-host.dll' if sys.platform == 'win32' else 'pc-host.so')
+
+
+class Encoded(C.Structure):
+    _fields_ = [('data', C.c_void_p), ('size', C.c_int), ('key', C.c_int),
+                ('width', C.c_int), ('height', C.c_int), ('pts', C.c_int64)]
+
+
+GATE = C.CFUNCTYPE(C.c_int, C.c_int, C.c_int64, C.c_int64, C.c_int64)
+
+
+class Native:
+    def __init__(self, path=LIBRARY):
+        self.dll_dirs = []
+        if sys.platform == 'win32':
+            # Set process coordinates before loading GStreamer: a plugin may
+            # create a helper HWND during discovery, after which it is too late.
+            user = C.WinDLL('user32')
+            user.SetProcessDpiAwarenessContext.argtypes = [C.c_void_p]
+            user.SetProcessDpiAwarenessContext(C.c_void_p(-4))
+            for folder in (path.parent, path.parent / 'bin'):
+                self.dll_dirs.append(os.add_dll_directory(str(folder)))
+        self.lib = C.CDLL(str(path))
+        signatures = {
+            'fc_now': (C.c_int64, []), 'fc_gst_init': (None, []),
+            'fc_has_element': (C.c_int, [C.c_char_p]),
+            'fc_new': (C.c_void_p, [C.c_int, C.c_int]), 'fc_free': (None, [C.c_void_p]),
+            'fc_ceiling': (None, [C.c_void_p, C.c_int]),
+            'fc_gate': (C.c_int, [C.c_void_p, C.c_int64, C.c_int]),
+            'fc_capture': (None, [C.c_void_p, C.c_int64]),
+            'fc_sent': (None, [C.c_void_p, C.c_uint32, C.c_int, C.c_int64]),
+            'fc_ack': (C.c_int, [C.c_void_p, C.c_uint32, C.c_int64]),
+            'fc_update': (C.c_int, [C.c_void_p, C.c_int64]),
+            'fc_value': (C.c_int64, [C.c_void_p, C.c_int]),
+            'fc_capture_open': (C.c_void_p, [C.c_char_p, GATE, C.c_char_p, C.c_int]),
+            'fc_capture_pull': (C.c_int, [C.c_void_p, C.POINTER(Encoded)]),
+            'fc_capture_error': (C.c_char_p, [C.c_void_p]),
+            'fc_capture_bitrate': (None, [C.c_void_p, C.c_int]),
+            'fc_capture_key': (None, [C.c_void_p]),
+            'fc_capture_test': (None, [C.c_void_p, C.c_uint32]), 'fc_capture_close': (None, [C.c_void_p]),
+        }
+        if sys.platform.startswith('linux'):
+            signatures.update({
+                'fc_portal_select': (C.c_void_p, [C.c_char_p, C.c_int]),
+                'fc_portal_close': (None, [C.c_void_p]),
+                'fc_portal_refresh': (C.c_int, [C.c_void_p, C.c_char_p, C.c_int]),
+                'fc_portal_value': (C.c_int, [C.c_void_p, C.c_int]),
+                'fc_portal_input': (C.c_int, [C.c_void_p, C.c_int, C.c_double, C.c_double, C.c_int, C.c_int]),
+            })
+        for name, (result, args) in signatures.items():
+            fn = getattr(self.lib, name)
+            fn.restype, fn.argtypes = result, args
+        self.lib.fc_gst_init()
+
+    def has(self, name):
+        return bool(self.lib.fc_has_element(name.encode()))
+
+    def now(self):
+        return self.lib.fc_now()
+
+
+class Controller:
+    def __init__(self, lib, fps, ceiling):
+        # close() may run on the stream thread while /status reads state();
+        # after close every entry point is a no-op, never a NULL dereference.
+        self.lib, self.lock, self.fps = lib, threading.RLock(), fps
+        self.enabled = os.environ.get('FRAME_MAC_VIEW_ADAPT') != '0'
+        self.ptr = lib.fc_new(fps, self.enabled)
+        if not self.ptr:
+            raise MemoryError('Unable to allocate the streaming controller')
+        lib.fc_ceiling(self.ptr, ceiling)
+        self.events = []
+
+    def state(self):
+        with self.lock:
+            names = ['target', 'ceiling', 'tier', 'fps', 'scale', 'baseRtt', 'inFlight', 'slack']
+            if not self.ptr:
+                out = dict.fromkeys(names, 0)
+                out.update(fps=self.fps, scale=100)
+            else:
+                out = {k: self.lib.fc_value(self.ptr, i) for i, k in enumerate(names)}
+            out.update(scale=out['scale'] / 100, baseRtt=out['baseRtt'] / 1000,
+                       slack=out['slack'] / 1000, adapt=self.enabled)
+            return out
+
+    def call(self, name, *args):
+        with self.lock:
+            return getattr(self.lib, 'fc_' + name)(self.ptr, *args) if self.ptr else 0
+
+    def update(self, now):
+        with self.lock:
+            if not self.ptr:
+                return 0
+            old = self.state()
+            result = self.lib.fc_update(self.ptr, now)
+            state = self.state()
+            if state['target'] < old['target'] or state['tier'] != old['tier']:
+                self.events.append({'t': now, 'e': 'target %s bit/s; tier %s' % (state['target'], state['tier'])})
+                self.events = self.events[-200:]
+            return result
+
+    def close(self):
+        with self.lock:
+            if self.ptr:
+                self.lib.fc_free(self.ptr)
+                self.ptr = None
+
+
+def dimensions(w, h, maximum):
+    scale = min(1, maximum / max(w, h))
+    return max(2, int(w * scale) // 2 * 2), max(2, int(h * scale) // 2 * 2)
+
+
+def pipeline(source, platform, encoder, w, h, fps, bitrate, codec='h264'):
+    """Only locally constructed numeric source IDs enter the pipeline parser."""
+    if source['src'] == 'test':
+        capture = 'videotestsrc name=source is-live=true pattern=ball'
+    elif platform == 'win32':
+        kind, ident = source['src'].split(':')
+        if kind not in ('window', 'display') or not re.fullmatch(r'[0-9]+', ident):
+            raise ValueError('Invalid Windows capture source')
+        prop = 'window-handle' if kind == 'window' else 'monitor-handle'
+        capture = 'd3d11screencapturesrc capture-api=wgc show-cursor=true show-border=true %s=%d' % (prop, int(ident))
+    else:
+        capture = 'pipewiresrc fd=%d path=%d do-timestamp=true' % (source['fd'], source['node'])
+    # The source gate runs before conversion/encoding. There is no leaky queue
+    # of H.264 frames; every encoded reference frame reaches the socket.
+    raw = '%s ! video/x-raw,framerate=%d/1 ! queue name=raw_queue leaky=downstream max-size-buffers=1 max-size-bytes=0 max-size-time=0 ! identity name=gate ! videoconvert ! videoscale add-borders=false ! video/x-raw,width=%d,height=%d' % (capture, fps, w, h)
+    if codec == 'jpeg':
+        enc = 'jpegenc name=enc quality=80'
+        parse = ''
+    else:
+        choices = {
+            'mfh264enc': 'mfh264enc name=enc low-latency=true bframes=0 gop-size=60',
+            'vah264enc': 'vah264enc name=enc b-frames=0 key-int-max=60',
+            'x264enc': 'x264enc name=enc tune=zerolatency speed-preset=ultrafast bframes=0 key-int-max=60',
+        }
+        enc = choices[encoder] + ' bitrate=%d' % max(1, bitrate // 1000)
+        raw += ',format=NV12' if encoder != 'x264enc' else ',format=I420'
+        parse = ' ! h264parse config-interval=-1 ! video/x-h264,stream-format=byte-stream,alignment=au'
+    return raw + ' ! ' + enc + parse + ' ! appsink name=out sync=false max-buffers=2 drop=false'
+
+
+# X11 keysyms work on Wayland through the RemoteDesktop portal too. The host's
+# keyboard layout handles physical keys; Unicode text is sent as Unicode keysyms.
+KEYSYMS = {'Enter': 0xff0d, 'Tab': 0xff09, 'Backspace': 0xff08, 'Escape': 0xff1b,
+           'Delete': 0xffff, 'ArrowLeft': 0xff51, 'ArrowUp': 0xff52, 'ArrowRight': 0xff53,
+           'ArrowDown': 0xff54, 'Home': 0xff50, 'End': 0xff57, 'PageUp': 0xff55,
+           'PageDown': 0xff56, 'Shift': 0xffe1, 'Control': 0xffe3, 'Alt': 0xffe9, 'Meta': 0xffeb}
+
+
+class PortalInput:
+    def __init__(self, native, source):
+        self.lib, self.source = native.lib, source
+        self.buttons, self.keys = set(), set()
+
+    def emit(self, kind, x=0, y=0, code=0, down=0):
+        if not self.lib.fc_portal_input(self.source['portal'], kind, x, y, code, down):
+            raise RuntimeError('The desktop portal refused input; check the sharing permission')
+
+    def release(self):
+        error = None
+        for values, kind in ((self.buttons, 1), (self.keys, 3)):
+            for code in list(values):
+                try:
+                    self.emit(kind, code=code, down=0)
+                    values.discard(code)
+                except RuntimeError as e:
+                    error = e
+        if error:
+            raise error
+
+    def handle(self, m):
+        t = m['t']
+        if t == 'release':
+            return self.release()
+        if t in ('m', 'wheel'):
+            x, y = (max(0, min(1, float(m.get(k, 0)))) for k in ('x', 'y'))
+            self.emit(0, x * (self.source['w'] - 1), y * (self.source['h'] - 1))
+        if t == 'm' and m.get('e') in ('up', 'down'):
+            b = {0: 0x110, 1: 0x112, 2: 0x111}.get(m.get('b', 0))
+            if b is not None:
+                down = m['e'] == 'down'
+                self.emit(1, code=b, down=down)
+                (self.buttons.add if down else self.buttons.discard)(b)
+        elif t == 'wheel':
+            self.emit(2, max(-4096, min(4096, float(m.get('dx', 0)))), max(-4096, min(4096, float(m.get('dy', 0)))))
+        elif t == 'k':
+            key = str(m.get('key', ''))
+            k = KEYSYMS.get(key) or (ord(key) if len(key) == 1 and ord(key) < 256 else
+                                     0x1000000 + ord(key) if len(key) == 1 else 0)
+            if k:
+                down = m.get('e') == 'down'
+                self.emit(3, code=k, down=down)
+                (self.keys.add if down else self.keys.discard)(k)
+        elif t == 'text':
+            for ch in str(m.get('s', ''))[:4096]:
+                k = ord(ch) if ord(ch) < 256 else 0x1000000 + ord(ch)
+                self.emit(3, code=k, down=1)
+                self.emit(3, code=k, down=0)
+
+
+class Windows:
+    """WGC source handles and SendInput. No elevation or global input hook."""
+    def __init__(self):
+        from ctypes import wintypes as W
+        self.W = W
+        self.user = C.WinDLL('user32', use_last_error=True)
+        self.dwm = C.WinDLL('dwmapi')
+        self.user.IsWindow.argtypes = [W.HWND]
+        self.user.IsWindowVisible.argtypes = [W.HWND]
+        self.user.IsIconic.argtypes = [W.HWND]
+        self.user.GetWindowTextLengthW.argtypes = [W.HWND]
+        self.user.GetWindowTextW.argtypes = [W.HWND, W.LPWSTR, C.c_int]
+        self.user.GetWindowRect.argtypes = [W.HWND, C.POINTER(W.RECT)]
+        self.user.SetForegroundWindow.argtypes = [W.HWND]
+        self.user.GetForegroundWindow.argtypes = []
+        self.user.GetForegroundWindow.restype = W.HWND
+        self.dwm.DwmGetWindowAttribute.argtypes = [W.HWND, W.DWORD, C.c_void_p, W.DWORD]
+        self.callback = C.WINFUNCTYPE(W.BOOL, W.HWND, W.LPARAM)
+        self.monitor_callback = C.WINFUNCTYPE(W.BOOL, W.HMONITOR, W.HDC, C.POINTER(W.RECT), W.LPARAM)
+        self.user.EnumWindows.argtypes = [self.callback, W.LPARAM]
+        self.user.EnumDisplayMonitors.argtypes = [W.HDC, C.c_void_p, self.monitor_callback, W.LPARAM]
+        class Mouse(C.Structure):
+            _fields_ = [('dx', W.LONG), ('dy', W.LONG), ('data', W.DWORD), ('flags', W.DWORD),
+                        ('time', W.DWORD), ('extra', C.c_size_t)]
+        class Key(C.Structure):
+            _fields_ = [('vk', W.WORD), ('scan', W.WORD), ('flags', W.DWORD), ('time', W.DWORD), ('extra', C.c_size_t)]
+        class Union(C.Union):
+            _fields_ = [('mouse', Mouse), ('key', Key)]
+        class Input(C.Structure):
+            _fields_ = [('type', W.DWORD), ('data', Union)]
+        self.Mouse, self.Key, self.Input = Mouse, Key, Input
+        self.user.SendInput.argtypes = [W.UINT, C.POINTER(Input), C.c_int]
+        self.user.SendInput.restype = W.UINT
+
+    def rect(self, hwnd):
+        r = self.W.RECT()
+        if not self.user.IsWindow(hwnd) or self.user.IsIconic(hwnd):
+            raise RuntimeError('The captured window closed or was minimized')
+        # WGC captures the visible extended frame, excluding invisible resize borders.
+        if self.dwm.DwmGetWindowAttribute(hwnd, 9, C.byref(r), C.sizeof(r)):
+            if not self.user.GetWindowRect(hwnd, C.byref(r)):
+                raise RuntimeError('Cannot locate the captured window')
+        return r.left, r.top, r.right - r.left, r.bottom - r.top
+
+    def sources(self):
+        windows, displays = [], []
+        def window(hwnd, _):
+            if not self.user.IsWindowVisible(hwnd) or self.user.IsIconic(hwnd):
+                return True
+            n = self.user.GetWindowTextLengthW(hwnd)
+            if n:
+                title = C.create_unicode_buffer(n + 1)
+                self.user.GetWindowTextW(hwnd, title, n + 1)
+                try:
+                    x, y, w, h = self.rect(hwnd)
+                    if w > 0 and h > 0:
+                        windows.append(dict(src='window:%d' % hwnd, id=hwnd, title=title.value,
+                                            app='Windows', w=w, h=h, x=x, y=y))
+                except RuntimeError:
+                    pass
+            return True
+        def monitor(handle, dc, rect, data):
+            r = rect.contents
+            displays.append(dict(src='display:%d' % handle, name='Display %d' % (len(displays) + 1),
+                                 x=r.left, y=r.top, w=r.right-r.left, h=r.bottom-r.top))
+            return True
+        self.user.EnumWindows(self.callback(window), 0)
+        self.user.EnumDisplayMonitors(None, None, self.monitor_callback(monitor), 0)
+        return windows, displays
+
+    def send(self, mouse=None, key=None):
+        inp = self.Input()
+        inp.type = 0 if mouse else 1
+        if mouse:
+            inp.data.mouse = self.Mouse(*mouse, 0, 0)
+        else:
+            inp.data.key = self.Key(*key, 0, 0)
+        if self.user.SendInput(1, C.byref(inp), C.sizeof(inp)) != 1:
+            raise RuntimeError('Windows refused input (elevated apps and the secure desktop cannot be controlled)')
+
+
+class WindowsInput:
+    def __init__(self, host, source):
+        self.host, self.source = host, source
+        self.buttons, self.keys = set(), set()
+
+    def release(self):
+        error = None
+        for button in list(self.buttons):
+            try:
+                self.host.send(mouse=(0, 0, 0, {0: 4, 1: 0x40, 2: 0x10}[button]))
+                self.buttons.discard(button)
+            except RuntimeError as e:
+                error = e
+        for vk in list(self.keys):
+            try:
+                extended = 1 if vk in (33, 34, 35, 36, 37, 38, 39, 40, 45, 46, 91, 92, 163, 165) else 0
+                self.host.send(key=(vk, 0, 2 | extended))
+                self.keys.discard(vk)
+            except RuntimeError as e:
+                error = e
+        if error:
+            raise error
+
+    def focus(self):
+        if not self.source['src'].startswith('window:'):
+            return
+        hwnd = int(self.source['src'].split(':')[1])
+        user = self.host.user
+        if user.GetForegroundWindow() != hwnd and not user.SetForegroundWindow(hwnd):
+            raise RuntimeError('Windows could not focus this window. Bring it to the front on your PC, then press Stop and Show again.')
+        if user.GetForegroundWindow() != hwnd:
+            raise RuntimeError('The selected window is not in front. Reopen the view after bringing it to the front on your PC.')
+
+    def handle(self, m):
+        t, u = m['t'], self.host.user
+        if t == 'release':
+            return self.release()
+        if t in ('m', 'wheel'):
+            source = self.source
+            if source['src'].startswith('window:'):
+                hwnd = int(source['src'].split(':')[1])
+                x, y, w, h = self.host.rect(hwnd)
+                if m.get('e') == 'down' or t == 'wheel':
+                    self.focus()
+            else:
+                x, y, w, h = (source[k] for k in ('x', 'y', 'w', 'h'))
+            x += max(0, min(1, float(m.get('x', 0)))) * (w - 1)
+            y += max(0, min(1, float(m.get('y', 0)))) * (h - 1)
+            left, top, width, height = (u.GetSystemMetrics(i) for i in (76, 77, 78, 79))
+            self.host.send(mouse=(round((x-left)*65535/max(1,width-1)), round((y-top)*65535/max(1,height-1)), 0, 0xc001))
+        if t == 'm' and m.get('e') in ('up', 'down'):
+            b = m.get('b', 0)
+            if b in (0, 1, 2):
+                down = m['e'] == 'down'
+                self.host.send(mouse=(0, 0, 0, {0: 2, 1: 0x20, 2: 8}[b] * (1 if down else 2)))
+                (self.buttons.add if down else self.buttons.discard)(b)
+        elif t == 'wheel':
+            for name, flag, direction in (('dy', 0x800, -1), ('dx', 0x1000, 1)):
+                delta = int(max(-4096, min(4096, float(m.get(name, 0))))) * direction
+                if delta:
+                    self.host.send(mouse=(0, 0, delta & 0xffffffff, flag))
+        elif t == 'k':
+            code, down = str(m.get('code', '')), m.get('e') == 'down'
+            if down:
+                self.focus()
+            special = {'Enter': 13, 'Escape': 27, 'Tab': 9, 'Backspace': 8, 'Space': 32,
+                       'ArrowLeft': 37, 'ArrowUp': 38, 'ArrowRight': 39, 'ArrowDown': 40,
+                       'Delete': 46, 'Home': 36, 'End': 35, 'PageUp': 33, 'PageDown': 34,
+                       'ShiftLeft': 160, 'ShiftRight': 161, 'ControlLeft': 162, 'ControlRight': 163,
+                       'AltLeft': 164, 'AltRight': 165, 'MetaLeft': 91, 'MetaRight': 92}
+            vk = special.get(code, 0)
+            if re.fullmatch(r'Key[A-Z]', code) or re.fullmatch(r'Digit[0-9]', code):
+                vk = ord(code[-1])
+            if vk:
+                extended = 1 if vk in (33, 34, 35, 36, 37, 38, 39, 40, 45, 46, 91, 92, 163, 165) else 0
+                self.host.send(key=(vk, 0, extended | (0 if down else 2)))
+                (self.keys.add if down else self.keys.discard)(vk)
+            elif down and len(str(m.get('key', ''))) == 1:
+                self.handle({'t': 'text', 's': m['key']})
+        elif t == 'text':
+            self.focus()
+            raw = str(m.get('s', ''))[:4096].encode('utf-16-le')
+            for i in range(0, len(raw), 2):
+                unit = int.from_bytes(raw[i:i+2], 'little')
+                self.host.send(key=(0, unit, 4))
+                self.host.send(key=(0, unit, 6))

ui/frame_pcview.py

@@ -0,0 +1,90 @@
+"""PC host selection behind the existing MacView tunnel/panel controller.
+
+The public /api/macview name and viewer URL remain compatible with the Mac
+base branch. Only helper launch, platform availability and source validation
+are different. No second viewer, SSH supervisor or benchmark launcher.
+"""
+import os
+import sys
+import subprocess
+from frame_macview import MacView, MacViewError, ROOT
+from frame_pc_capture import LIBRARY, NATIVE
+
+
+def prepend(env, name, path):
+    """An empty entry means the current directory to the loader; never add one."""
+    rest = env.get(name, '')
+    env[name] = str(path) + (os.pathsep + rest if rest else '')
+
+
+class PCView(MacView):
+    viewer_profile = 'pc-view'
+    host = 'windows' if sys.platform == 'win32' else 'linux'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.prefer_usb = False  # Mac networksetup probe is platform-specific
+
+    def unavailable(self):
+        if sys.platform not in ('win32', 'linux'):
+            return 'PC streaming needs Windows or a Linux desktop.'
+        if not LIBRARY.is_file():
+            return 'The PC streaming libraries are missing from this build. See docs/pc-in-headset.md.'
+        return None
+
+    def state(self):
+        result = super().state()
+        result["host"] = self.host
+        return result
+
+    def build(self):
+        pass  # native libraries are built and bundled with the app
+
+    def agent_command(self):
+        return [sys.executable, str(ROOT / 'ui' / 'frame_pc_agent.py')]
+
+    def agent_environment(self):
+        env = super().agent_environment()
+        env['GST_PLUGIN_PATH_1_0'] = str(NATIVE / 'lib' / 'gstreamer-1.0')
+        env['GST_PLUGIN_SYSTEM_PATH_1_0'] = ''
+        cache = os.path.join(os.path.expanduser('~'), '.cache', 'frame-control')
+        os.makedirs(cache, exist_ok=True)
+        env['GST_REGISTRY_1_0'] = os.path.join(cache, 'gstreamer-registry.bin')
+        env['GST_REGISTRY_FORK'] = 'no'
+        if sys.platform == 'win32':
+            prepend(env, 'PATH', NATIVE / 'bin')
+        else:
+            prepend(env, 'LD_LIBRARY_PATH', NATIVE / 'lib')
+            env['PIPEWIRE_MODULE_DIR'] = str(NATIVE / 'lib' / 'pipewire-0.3')
+            env['SPA_PLUGIN_DIR'] = str(NATIVE / 'lib' / 'spa-0.2')
+            env['PIPEWIRE_CONFIG_DIR'] = str(NATIVE / 'share' / 'pipewire')
+            env['PIPEWIRE_CONFIG_NAME'] = 'client.conf'
+        return env
+
+    def shutdown(self):
+        self.closing = True
+        try:
+            self.stop()
+        except MacViewError:
+            pass
+        if self.tunnel and self.tunnel.poll() is None:
+            self.tunnel.terminate()
+        if self.agent and self.agent.poll() is None:
+            # EOF gives the host a chance to release held input and portal
+            # sessions, including on Windows where terminate is uncatchable.
+            if self.agent.stdin:
+                self.agent.stdin.close()
+            try:
+                self.agent.wait(10)
+            except subprocess.TimeoutExpired:
+                self.agent.kill()
+                self.agent.wait(5)
+
+    def _show(self, src, quality, width, height):
+        if src.startswith('separate:'):
+            raise MacViewError('Separate virtual displays are a Mac-only feature. Choose a window or screen.')
+        return super()._show(src, quality, width, height)
+
+
+def host_view(*args, **kwargs):
+    return (MacView if sys.platform == 'darwin' else PCView)(*args, **kwargs)

ui/frame_quest.py

@@ -0,0 +1,644 @@
+"""Import from my Quest: copy games you own off your own Meta Quest onto the Frame.
+
+The Quest is plugged into this computer by USB with developer mode on; its own
+adb copies the APK (and split APKs) into a per-user cache. The APK is checked
+before anything goes to the Frame, then installed through frame_android.install
+like any other APK. Game data (the OBB folder and, if asked, the external
+app-data folder) is copied by a second import while the person has the game
+open, since only a running Lepton instance can take it; Frame Control never
+starts the game itself. The cache is always removed. Games that link Meta's Platform SDK
+(libovrplatformloader.so) install with a warning: linking it doesn't mean the game
+enforces a licence check, but if it does the game may quit or hang on the Frame, and
+Frame Control does not remove the check or work around it. See docs/quest-import.md.
+
+Python stdlib only. CLI: python3 ui/frame_quest.py
+  devices | list [--serial SERIAL] | import PACKAGE [--serial SERIAL] [--data] [--allow-downgrade]
+"""
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import shlex
+import shutil
+import subprocess
+import sys
+import tarfile
+import threading
+import time
+import zipfile
+
+import frame_android as android
+import frame_host
+
+OBB = '/sdcard/Android/obb'
+DATA = '/sdcard/Android/data'
+OBB_NAME = r'(main|patch)\.[0-9]+\.{}\.obb'
+# Serials of adb connections that aren't a USB headset: Frame Control's own SSH tunnels
+# to the Frame's Lepton instances (127.0.0.1:<port>, server.AdbTunnel) and emulators.
+TUNNEL_RE = re.compile(r'^(127\.0\.0\.1|localhost|\[::1\]):\d+$')
+QUEST_MAKERS = {'oculus', 'meta'}
+META_APPS = ('com.oculus.', 'com.meta.', 'com.facebook.')
+CACHE_TTL = 6 * 3600  # an import left behind by a crash is swept after this
+ADB_TIMEOUT = 30
+PULL_TIMEOUT = 3 * 3600
+READY_TIMEOUT = 150
+BATCH = 15  # packages per adb shell command while listing
+
+# Linking the Platform SDK doesn't mean a game enforces the licence check (Meta's
+# VRC.Quest.Security.1 has only been Recommended since 2021), so it's a warning, not a refusal.
+ENTITLEMENT = ("Uses Meta's licence check (Platform SDK, libovrplatformloader.so); it may quit, hang, or run "
+               "without online features on the Frame. Frame Control won't remove the check.")
+VRAPI = ("Uses Meta's legacy VrApi and no OpenXR loader. The Frame doesn't have VrApi, so it may not run.")
+NO_DEVICE = ("No Quest found on this computer's USB. Connect the Quest with a cable that carries data, "
+             "put the headset on and allow USB debugging. Developer mode must be on first: it needs a Meta "
+             "developer organisation on a verified Meta account (developers.meta.com), then Developer Mode "
+             "switched on for the headset in the Meta Horizon phone app.")
+UNAUTHORISED = ("The Quest hasn't allowed this computer yet. Put the headset on and accept the \"Allow USB "
+                "debugging\" prompt (tick Always allow from this computer), then try again. No prompt? Unplug "
+                "and replug the cable, or switch developer mode off and on.")
+NO_PERMISSIONS = ("This computer sees the Quest but isn't allowed to open it over USB. On Linux, add a udev "
+                  "rule for Meta's USB vendor id 2833 (see docs/quest-import.md), then replug it.")
+OFFLINE = "adb reports the Quest offline. Unplug and replug the cable, or restart the headset."
+GONE = "The Quest was disconnected. Plug it back in, put it on, and try again."
+
+
+class QuestError(android.FrameError):
+    pass
+
+
+def _adb_cmd():
+    try:
+        return [frame_host.adb()]
+    except frame_host.HostError as e:
+        raise QuestError(str(e)) from e
+
+
+def _friendly(out):
+    low = out.lower()
+    if 'unauthorized' in low:
+        return UNAUTHORISED
+    if 'no permissions' in low or 'insufficient permissions' in low:
+        return NO_PERMISSIONS
+    if 'device offline' in low:
+        return OFFLINE
+    if 'no devices/emulators found' in low or re.search(r"device '[^']*' not found", low):
+        return GONE
+    return None
+
+
+def adb(*args, serial=None, timeout=ADB_TIMEOUT):
+    """Run this computer's adb (the one Frame Control already finds) and return stdout."""
+    cmd = _adb_cmd() + (['-s', serial] if serial else []) + list(args)
+    try:
+        r = subprocess.run(cmd, capture_output=True, stdin=subprocess.DEVNULL, text=True, errors='replace',
+                           timeout=timeout)
+    except subprocess.TimeoutExpired:
+        raise QuestError(f'adb {args[0]} took more than {timeout} s; check the Quest is still connected')
+    except OSError as e:
+        raise QuestError(f'could not run adb: {e}')
+    if r.returncode != 0:
+        out = (r.stderr or '').strip() or (r.stdout or '').strip()
+        raise QuestError(_friendly(out) or out[-600:] or f'adb exited {r.returncode}')
+    return r.stdout
+
+
+# ---- Finding the Quest ------------------------------------------------------
+
+def _parse_devices(out):
+    found = []
+    for line in out.splitlines():
+        line = line.strip()
+        if not line or line.startswith('List of devices') or line.startswith('*'):
+            continue
+        parts = line.split(None, 1)
+        serial, rest = parts[0], (parts[1] if len(parts) > 1 else '')
+        state = 'no permissions' if rest.startswith('no permissions') else (rest.split() or ['unknown'])[0]
+        fields = dict(t.split(':', 1) for t in rest.split() if re.match(r'^[a-z_]+:', t))
+        found.append({'serial': serial, 'state': state, 'usb': 'usb' in fields,
+                      'model': fields.get('model', '').replace('_', ' '), 'manufacturer': ''})
+    return found
+
+
+def devices():
+    """Every adb device on this computer, each with a kind: quest, frame, android (another
+    Android device), frame-tunnel (Frame Control's own SSH-tunnelled connection to a Lepton
+    instance, never touched here), emulator, or unknown (not authorised, offline...)."""
+    found = _parse_devices(adb('devices', '-l', timeout=15))
+    for d in found:
+        if TUNNEL_RE.match(d['serial']):
+            d['kind'] = 'frame-tunnel'
+        elif d['serial'].startswith('emulator-'):
+            d['kind'] = 'emulator'
+        elif d['state'] != 'device':
+            d['kind'] = 'unknown'
+        else:
+            try:
+                props = adb('shell', 'getprop ro.product.manufacturer; getprop ro.product.model',
+                            serial=d['serial'], timeout=15).splitlines() + ['', '']
+            except QuestError:
+                d['kind'] = 'unknown'
+                continue
+            d['manufacturer'], d['model'] = props[0].strip(), props[1].strip() or d['model']
+            maker = d['manufacturer'].lower()
+            d['kind'] = ('quest' if maker in QUEST_MAKERS or 'quest' in d['model'].lower()
+                         else 'frame' if maker == 'valve' else 'android')
+    return found
+
+
+def find_quest(serial=None):
+    """The one connected, authorised Quest, or a QuestError saying what to do."""
+    found = devices()
+    if serial:
+        d = next((d for d in found if d['serial'] == serial), None)
+        if not d:
+            raise QuestError(f'No adb device {serial} on this computer. ' + NO_DEVICE)
+        if d['kind'] == 'quest':
+            return d
+        state = {'unauthorized': UNAUTHORISED, 'no permissions': NO_PERMISSIONS, 'offline': OFFLINE}.get(d['state'])
+        what = ' '.join(x for x in (d['manufacturer'] or d['kind'], d['model']) if x)
+        raise QuestError(state or f"{serial} isn't a Meta Quest ({what}).")
+    quests = [d for d in found if d['kind'] == 'quest']
+    if len(quests) == 1:
+        return quests[0]
+    if quests:
+        raise QuestError('Several Quests are connected: ' + ', '.join(f"{d['model']} ({d['serial']})" for d in quests)
+                         + '. Choose one, or unplug the others.')
+    states = {d['state'] for d in found if d['kind'] == 'unknown'}
+    for state, message in (('unauthorized', UNAUTHORISED), ('no permissions', NO_PERMISSIONS), ('offline', OFFLINE)):
+        if state in states:
+            raise QuestError(message)
+    others = [d for d in found if d['kind'] in ('android', 'frame')]
+    if others:
+        raise QuestError(NO_DEVICE + ' (adb sees ' + ', '.join(
+            f"{d['manufacturer']} {d['model']}".strip() for d in others) + ", which isn't a Quest.)")
+    raise QuestError(NO_DEVICE)
+
+
+# ---- What's on it -------------------------------------------------------------
+
+def _package_script(packages):
+    parts = []
+    for p in packages:
+        parts += [f'echo @@{p}', f'pm path {p}', f'du -sk {OBB}/{p} 2>/dev/null', f'du -sk {DATA}/{p} 2>/dev/null']
+    return '; '.join(parts + ['true'])
+
+
+def _parse_packages(out, packages):
+    apps, current = {}, None
+    for line in out.splitlines():
+        line = line.strip()
+        if line.startswith('@@') and line[2:] in packages:
+            current = apps[line[2:]] = {'package': line[2:], 'apks': [], 'obb': None, 'data': None}
+        elif current is None or not line:
+            continue
+        elif line.startswith('package:'):
+            current['apks'].append(line[len('package:'):])
+        else:
+            size, _, where = line.partition('\t') if '\t' in line else line.partition(' ')
+            if size.isdigit():
+                key = 'obb' if where.strip().startswith(OBB + '/') else 'data' if where.strip().startswith(DATA + '/') else None
+                if key:
+                    current[key] = int(size) * 1024
+    result = []
+    for p in packages:
+        app = apps.get(p)
+        if not app or not app['apks']:
+            continue  # removed while listing
+        app['split'] = len(app['apks']) > 1
+        app['meta'] = p.startswith(META_APPS)
+        result.append(app)
+    return result
+
+
+def packages(serial):
+    """Third-party apps on the Quest: APK paths (several means a split APK), and the size
+    in bytes of the OBB and external data folders (None when there is none)."""
+    out = adb('shell', 'pm list packages -3', serial=serial)
+    names = sorted({l.split(':', 1)[1].strip() for l in out.splitlines() if l.startswith('package:')})
+    names = [n for n in names if android.PKG_RE.match(n)]
+    apps = []
+    for i in range(0, len(names), BATCH):
+        batch = names[i:i + BATCH]
+        apps += _parse_packages(adb('shell', _package_script(batch), serial=serial, timeout=120), batch)
+    return apps
+
+
+def package(serial, pkg):
+    apps = _parse_packages(adb('shell', _package_script([pkg]), serial=serial, timeout=60), [pkg])
+    if not apps:
+        raise QuestError(f"{pkg} isn't installed on the Quest")
+    return apps[0]
+
+
+def status(serial=None, with_apps=True):
+    """For the page: the Quest (or why there isn't one), what else adb sees, and its apps."""
+    try:
+        found = devices()
+    except QuestError as e:
+        return {'quest': None, 'devices': [], 'guidance': str(e), 'apps': []}
+    try:
+        quest = find_quest(serial)
+    except QuestError as e:
+        return {'quest': None, 'devices': found, 'guidance': str(e), 'apps': []}
+    return {'quest': quest, 'devices': found, 'guidance': None,
+            'apps': packages(quest['serial']) if with_apps else []}
+
+
+# ---- Checking what was copied ---------------------------------------------------
+
+def inspect(package_name, base, splits=()):
+    """Refuse what can't run on the Frame (32-bit only, Android newer than Lepton's, splits
+    that can't be merged), before anything is copied to it; warn about what may not run."""
+    names = set()
+    for path in [base, *splits]:
+        try:
+            with zipfile.ZipFile(path) as z:
+                names |= set(z.namelist())
+        except (zipfile.BadZipFile, OSError) as e:
+            raise QuestError(f'{os.path.basename(path)} copied from the Quest is not a readable APK: {e}')
+    info = android.apk_info(base)
+    label = info['label']
+    if info['package'] != package_name:
+        raise QuestError(f"The APK copied for {package_name} says it is {info['package']}; not importing it")
+    platform_sdk = any(n.rsplit('/', 1)[-1] == 'libovrplatformloader.so' for n in names)
+    abis = sorted({n.split('/')[1] for n in names if n.startswith('lib/') and n.count('/') >= 2})
+    if abis and 'arm64-v8a' not in abis:
+        raise QuestError(f"{label} is a 32-bit-only build ({', '.join(abis)}). The Frame runs 64-bit ARM "
+                         "(arm64-v8a) apps only; older Quest games are often 32-bit. Ask the developer "
+                         "whether a 64-bit build exists.")
+    android.check_installable(dict(info, abis=abis))  # Android version
+    if splits:
+        android.split_entries(base, splits)  # a split APK Frame Control can't merge fails now
+    warnings = [ENTITLEMENT] if platform_sdk else []
+    openxr = 'lib/arm64-v8a/libopenxr_loader.so' in names
+    if 'lib/arm64-v8a/libvrapi.so' in names and not openxr:
+        warnings.append(VRAPI)
+    return {'package': info['package'], 'label': label, 'version': info['version'],
+            'version_code': info.get('version_code'), 'abis': abis,
+            'vr': bool(info.get('vr') or openxr), 'platform_sdk': platform_sdk, 'warnings': warnings}
+
+
+# ---- Importing ------------------------------------------------------------------
+
+_import_lock = threading.Lock()
+_sleep = time.sleep
+
+
+def cache_root():
+    return Path(frame_host.cache_dir('quest-import'))
+
+
+def sweep_cache(now=None):
+    """Remove imports a crash left behind (older than CACHE_TTL)."""
+    root, now = cache_root(), now or time.time()
+    if root.is_dir():
+        for d in root.iterdir():
+            try:
+                if now - d.stat().st_mtime > CACHE_TTL:
+                    shutil.rmtree(d, ignore_errors=True)
+            except OSError:
+                pass
+
+
+def _safe(name):
+    return re.sub(r'[^A-Za-z0-9._-]', '_', name)[:120] or 'part.apk'
+
+
+def _remote_sizes(serial, paths):
+    out = adb('shell', 'stat -c %s ' + ' '.join(shlex.quote(p) for p in paths), serial=serial)
+    return sum(int(x) for x in out.split() if x.isdigit())
+
+
+def _pull(serial, remote, local):
+    adb('pull', remote, str(local), serial=serial, timeout=PULL_TIMEOUT)
+
+
+def _wait_ready(meta):
+    """Until the app's Lepton instance has finished booting Android."""
+    container = f"lepton-steamlaunch-{int(meta['instance'])}"
+    deadline = time.monotonic() + READY_TIMEOUT
+    while time.monotonic() < deadline:
+        out = android.ssh(f"podman exec {container} /system/bin/sh -c 'getprop sys.boot_completed' "
+                          "2>/dev/null || true", timeout=30)
+        if out.strip() == '1':
+            return
+        _sleep(3)
+    raise QuestError(f"{meta['label']} didn't start on the Frame within {READY_TIMEOUT // 60} minutes, so its "
+                     "game data couldn't be added. Check it opens from the Steam library, then import again.")
+
+
+def push_data(meta, folder):
+    """Stream a pulled /sdcard/Android/data/<package> folder into the running instance as a
+    tar, written straight into the SSH transfer: nothing is staged on this computer."""
+    import frame_android_data
+    pkg = meta['package']
+    container = f"lepton-steamlaunch-{int(meta['instance'])}"
+    script = f'set -eu; mkdir -p {DATA}/{pkg}; cd {DATA}/{pkg}; tar -x -o -f -'
+    read_end, write_end = os.pipe()
+    state = {'count': 0, 'error': None}
+
+    def write():
+        try:
+            with os.fdopen(write_end, 'wb') as out, \
+                    tarfile.open(fileobj=out, mode='w|', format=tarfile.GNU_FORMAT) as tar:
+                for path in sorted(Path(folder).rglob('*')):
+                    if path.is_symlink() or not (path.is_file() or path.is_dir()):
+                        continue  # regular files and folders only
+                    info = tar.gettarinfo(str(path), arcname=path.relative_to(folder).as_posix())
+                    info.uid = info.gid = 0
+                    info.uname = info.gname = ''
+                    if path.is_file():
+                        with path.open('rb') as f:
+                            tar.addfile(info, f)
+                        state['count'] += 1
+                    else:
+                        tar.addfile(info)
+        except (OSError, tarfile.TarError, ValueError) as e:  # ValueError: the reader closed first
+            state['error'] = e
+
+    writer = threading.Thread(target=write, daemon=True)
+    writer.start()
+    try:
+        with os.fdopen(read_end, 'rb') as src:
+            frame_android_data._stream(shlex.join(['podman', 'exec', '-i', container, '/system/bin/sh', '-c', script]),
+                                       src=src)
+    finally:
+        writer.join(60)
+    if state['error']:
+        raise QuestError(f'could not read the app files copied from the Quest: {state["error"]}')
+    return state['count']
+
+
+def space_needed(apk_bytes, merged_bytes, obb_bytes, data_bytes):
+    """Bytes an import needs free on this computer: the APKs as copied, a merged APK and the
+    install's patched copy of it (each up to merged_bytes), the OBB folder and the
+    Android/data folder (streamed to the Frame, never staged twice)."""
+    return apk_bytes + 2 * merged_bytes + obb_bytes + data_bytes
+
+
+def _check_space(work, need, pkg):
+    free = shutil.disk_usage(str(work)).free
+    if need > free:
+        raise QuestError(f'Importing {pkg} needs about {need / 1024**3:.1f} GB free on this computer '
+                         f'({free / 1024**3:.1f} GB available in {work.parent})')
+
+
+def import_game(package_name, serial=None, data=False, progress=None, allow_downgrade=False):
+    """Copy package_name from the Quest to the Frame. progress(stage, percent).
+
+    Frame Control never starts the game itself. Its game data (OBB, and Android/data if
+    asked) can only be written into a running Lepton instance, and there is no way to
+    boot one without its game, so that's a second import: the person starts the game,
+    imports again, and Frame Control copies the data in and closes the game.
+
+    allow_downgrade: replace a newer version on the Frame with the Quest's older one."""
+    if not android.PKG_RE.match(package_name or ''):
+        raise QuestError('invalid package name')
+    report = progress or (lambda stage, percent=None: None)
+    if not _import_lock.acquire(blocking=False):
+        raise QuestError('Another Quest import is running; wait for it to finish')
+    try:
+        report('Looking for your Quest', 1)
+        quest = find_quest(serial)
+        app = package(quest['serial'], package_name)
+        sweep_cache()
+        work = cache_root() / f'{package_name}-{secrets.token_hex(4)}'
+        work.mkdir(parents=True)
+        try:
+            return _import(quest['serial'], app, data, work, report, allow_downgrade)
+        finally:
+            shutil.rmtree(work, ignore_errors=True)
+    finally:
+        _import_lock.release()
+
+
+def _running(pkg):
+    # strict: a failed `podman ps` raises, never reads as "not running".
+    return f'lepton-steamlaunch-{android.instance_id(pkg)}' in android.running_instances(strict=True)
+
+
+def _installed_code(pkg, meta):
+    """The installed version code: from the install record, else (installs made before
+    records kept it) read from the installed app.apk on the Frame; None if unknown."""
+    code = (meta or {}).get('version_code')
+    if isinstance(code, int) and not isinstance(code, bool):
+        return code
+    return android.installed_version_code(pkg) if meta else None
+
+
+def _version(name, code):
+    return ' '.join(x for x in (f'version {name}' if name else '', f'code {code}' if code is not None else 'unknown code') if x)
+
+
+def _check_downgrade(existing, checked, allow):
+    """Refuse to replace a newer install on the Frame with the Quest's older copy."""
+    if not existing or allow:
+        return
+    have, new = _installed_code(existing['package'], existing), checked['version_code']
+    if have is None or new is None:
+        raise QuestError(f"Frame Control can't tell which version of {checked['label']} is on the Frame, so it "
+                         "won't replace it in case that one is newer. Allow replacing a newer version (or "
+                         "--allow-downgrade) to install your Quest's copy anyway.")
+    if int(new) < int(have):
+        raise QuestError(f"The Frame has a newer {checked['label']} ({_version(existing.get('version'), have)}) than "
+                         f"your Quest ({_version(checked['version'], new)}). Frame Control won't replace it with "
+                         "an older version unless you allow it (Allow replacing a newer version, or "
+                         "--allow-downgrade).")
+
+
+def _check_target(pkg, meta, checked):
+    """The install record of the game open on the Frame, if it is this package, in its own
+    instance, at the Quest's exact version code; else a QuestError."""
+    label = checked['label']
+    if (not meta or meta.get('package') != pkg or android._int(meta.get('instance')) != android.instance_id(pkg)):
+        raise QuestError(f"{label} is open on the Frame, but Frame Control has no matching install record for "
+                         'it. Close it, then import again to install it.')
+    have, new = _installed_code(pkg, meta), checked['version_code']
+    if have is None or new is None or int(have) != int(new):
+        raise QuestError(f"{label} is open on the Frame with a different version (Frame: "
+                         f"{_version(meta.get('version'), have)}; Quest: {_version(checked['version'], new)}). "
+                         "Close it, then import again to install the Quest's version.")
+    return meta
+
+
+def _check_android_package(meta, code):
+    """The package Android itself has installed in the instance is this one, at this version."""
+    pkg = meta['package']
+    container = f"lepton-steamlaunch-{int(meta['instance'])}"
+    out = android.ssh(f"podman exec {container} /system/bin/sh -c 'dumpsys package {pkg}' 2>/dev/null || true",
+                      timeout=60)
+    # Only this package's own block (dumpsys can list other packages too).
+    block = re.search(r'^\s*Package \[' + re.escape(pkg) + r'\] \(.*?(?=^\s*Package \[|\Z)', out, re.M | re.S)
+    found = re.search(r'\bversionCode=(\d+)', block.group(0)) if block else None
+    if not found:
+        raise QuestError(f'Android in {container} does not have {pkg} installed')
+    if int(found.group(1)) != int(code):
+        raise QuestError(f'Android in {container} has {pkg} version code {found.group(1)}, not the '
+                         f"Quest's {code}")
+
+
+def _close(pkg):
+    """Stop the game and confirm its instance is gone: (closed, why not)."""
+    try:
+        android.stop(pkg)
+        for _ in range(6):
+            if not _running(pkg):
+                return True, None
+            _sleep(2)
+        return False, 'it is still running'
+    except Exception as e:  # never replaces the error that led here; unconfirmed counts as not closed
+        return False, str(e) or type(e).__name__
+
+
+def _import(serial, app, data, work, report, allow_downgrade=False):
+    pkg = app['package']
+    obb_bytes = app['obb'] or 0
+    data_bytes = (app['data'] or 0) if data else 0
+    apk_bytes = _remote_sizes(serial, app['apks'])
+    _check_space(work, space_needed(apk_bytes, apk_bytes, obb_bytes, data_bytes), pkg)
+    # 1. The APK (and its splits), checked before anything else is copied.
+    local = []
+    for i, remote in enumerate(app['apks']):
+        report(f'Copying the app from your Quest ({i + 1} of {len(app["apks"])})', 5 + 20 * i // len(app['apks']))
+        name = 'base.apk' if os.path.basename(remote) == 'base.apk' else f'{i:02d}-{_safe(os.path.basename(remote))}'
+        _pull(serial, remote, work / name)
+        if not (work / name).is_file():
+            raise QuestError(f'adb did not copy {remote} from the Quest')
+        local.append(work / name)
+    base = next((p for p in local if p.name == 'base.apk'), local[0])
+    splits = [p for p in local if p != base]
+    report('Checking it can run on the Frame', 27)
+    checked = inspect(pkg, str(base), [str(p) for p in splits])
+    warnings = list(checked['warnings'])
+    label = checked['label']
+    # A merge stores what splits compressed: count it uncompressed, now the files are here.
+    merged = base.stat().st_size + android.split_size([str(p) for p in splits])
+    _check_space(work, space_needed(0, merged, obb_bytes, data_bytes), pkg)
+    wants_data = app['obb'] is not None or bool(data and app['data'] is not None)
+    if not _running(pkg):
+        # 2a. Install. The game is never started here: see import_game. Checked and installed
+        # under the shared install lock, so nothing installs or removes it in between.
+        report('Installing on the Frame', 60)
+        with android._install_lock:
+            if _running(pkg):
+                raise QuestError(f'{label} was started on the Frame during the import. Close it, then import again.')
+            _check_downgrade(android.read_meta(pkg), checked, allow_downgrade)
+            meta = android.install(str(base), splits=[str(p) for p in splits], source='Meta Quest (USB)')
+        report('Done', 100)
+        message = f"Imported {meta['label']} from your Quest. It's in the Steam library."
+        if wants_data:
+            what = ' and '.join(x for x in ('its OBB game data' if app['obb'] is not None else '',
+                                            'its Android/data files' if data and app['data'] is not None else '') if x)
+            message += (f" To add {what}, start {meta['label']} from the Steam library, leave it on its first "
+                        "screen, then import it again here: Frame Control copies the data in and closes the game.")
+        note = android.layer_note(meta)
+        return {'message': ' '.join([message, *warnings, *([note] if note else [])]), 'app': meta, 'obb': [],
+                'files': 0, 'warnings': warnings, 'split': bool(splits), 'needs_game_data': wants_data,
+                'closed': None}
+    # 2b. The game is open on the Frame: add its data to exactly this install, never replacing it.
+    _check_target(pkg, android.read_meta(pkg), checked)  # early, before copying the data off the Quest
+    if not wants_data:
+        raise QuestError(f"{label} is already installed and open on the Frame, and has no game data to add. "
+                         'Close it first to install it again.')
+    obb_files = []
+    if app['obb'] is not None:
+        report('Copying game data (OBB) from your Quest', 30)
+        (work / 'obb').mkdir()
+        _pull(serial, f'{OBB}/{pkg}', work / 'obb')
+        folder = work / 'obb' / pkg
+        files = sorted(p for p in folder.iterdir() if p.is_file()) if folder.is_dir() else []
+        obb_files = [p for p in files if re.fullmatch(OBB_NAME.format(re.escape(pkg)), p.name)]
+        skipped = [p.name for p in files if p not in obb_files]
+        if skipped:
+            warnings.append('Not copied, not standard OBB file names: ' + ', '.join(skipped))
+    data_folder = None
+    if data and app['data'] is not None:
+        report('Copying app files from your Quest', 50)
+        (work / 'data').mkdir()
+        _pull(serial, f'{DATA}/{pkg}', work / 'data')
+        data_folder = work / 'data' / pkg if (work / 'data' / pkg).is_dir() else None
+    result = add_game_data(pkg, checked, [str(p) for p in obb_files], data_folder, report, warnings)
+    result['split'] = bool(splits)
+    return result
+
+
+def add_game_data(pkg, checked, obb_files, data_folder, report, warnings=(), source='your Quest'):
+    """Copy game data into the game open on the Frame, then close it: the second step of a
+    two-step install (Import from my Quest, and My Meta library). checked is inspect()'s
+    result for the APK the data belongs to; obb_files are local OBB paths, data_folder a
+    local Android/data/<package> folder or None. Raises QuestError, after closing the game,
+    if anything fails."""
+    warnings = list(warnings)
+    label = checked['label']
+    copied_obb, copied_files, failure = [], 0, None
+    # Fetching the data can take a long time: check the target again, and hold the shared
+    # install lock (install, remove and install_obb take it too) until the game is closed.
+    with android._install_lock:
+        if not _running(pkg):
+            raise QuestError(f'{label} was closed on the Frame during the import. Start it, then import again.')
+        meta = _check_target(pkg, android.read_meta(pkg), checked)
+        closed, why = None, None
+        try:
+            report('Waiting for Android on the Frame', 70)
+            _wait_ready(meta)
+            _check_android_package(meta, checked['version_code'])
+            if obb_files:
+                report('Copying game data (OBB) to the Frame', 80)
+                copied_obb = android.install_obb(pkg, [str(p) for p in obb_files])['obb']
+            if data_folder:
+                report('Copying app files to the Frame', 92)
+                copied_files = push_data(meta, data_folder)
+        except Exception as e:  # any failure, local (OSError) or on the Frame, is reported below
+            failure = e
+        finally:
+            # Whatever happened, even Ctrl-C part-way through a write, the game is closed so it
+            # never runs on half-copied data. A failed close never hides the original error.
+            interrupted = sys.exc_info()[0] is not None
+            closed, why = _close(pkg)
+            if interrupted and not closed:
+                print(f"Frame Control couldn't close {meta['label']} on the Frame ({why}); close it from Steam "
+                      'before playing.', file=sys.stderr)
+    if failure:
+        message = f"Copying {meta['label']}'s game data failed: {failure}."
+        message += (' The game was closed; start it and import again to retry.' if closed else
+                    f" Frame Control also couldn't close the game ({why}): close it from Steam, then start it "
+                    'and import again.')
+        raise QuestError(message) from failure
+    report('Done', 100)
+    message = f"Added {meta['label']}'s game data from {source}"
+    message += ('; the game is closed, start it again from the Steam library.' if closed else
+                f", but Frame Control couldn't close the game ({why}). Close it from Steam before playing, so it "
+                'starts with the new data.')
+    if copied_obb:
+        message += f' Added {len(copied_obb)} OBB file{"s" if len(copied_obb) != 1 else ""}.'
+    if copied_files:
+        message += f' Copied {copied_files} app file{"s" if copied_files != 1 else ""}.'
+    return {'message': ' '.join([message, *warnings]), 'app': meta, 'obb': copied_obb, 'files': copied_files,
+            'warnings': warnings, 'split': False, 'needs_game_data': False, 'closed': closed}
+
+
+def main():
+    cmd, *args = sys.argv[1:] or ['help']
+    serial = args[args.index('--serial') + 1] if '--serial' in args and args.index('--serial') + 1 < len(args) else None
+    try:
+        if cmd == 'devices':
+            r = devices()
+        elif cmd == 'list':
+            r = packages(find_quest(serial)['serial'])
+        elif cmd == 'import':
+            names = [a for a in args if not a.startswith('--') and a != serial]
+            if len(names) != 1:
+                raise QuestError('usage: import PACKAGE [--serial SERIAL] [--data] [--allow-downgrade]')
+            r = import_game(names[0], serial, data='--data' in args, allow_downgrade='--allow-downgrade' in args,
+                            progress=lambda stage, percent=None: print(f'{percent:>3}% {stage}' if percent is not None
+                                                                       else stage, file=sys.stderr))
+        else:
+            sys.exit(__doc__)
+    except (android.FrameError, OSError) as e:
+        sys.exit(f'error: {e}')
+    print(json.dumps(r, indent=1))
+
+
+if __name__ == '__main__':
+    main()

ui/frame_stream_stats.py

@@ -0,0 +1,88 @@
+"""The desktop stream's timing records, in the Mac viewer/bench schema.
+
+Times are host monotonic microseconds. Zero means unknown, never a fabricated
+capture/display timestamp. Storage is bounded to the same 4096/512 records as
+Stats.swift. The existing macview-bench.py grades these records unchanged.
+"""
+from collections import OrderedDict
+import threading
+
+
+def distribution(values):
+    values = sorted(v for v in values if v is not None)
+    if not values:
+        return {}
+    return {key: round(values[min(len(values)-1, int((len(values)-1)*p + .5))], 1)
+            for key, p in (('p50', .5), ('p95', .95))}
+
+
+class Stats:
+    def __init__(self, now):
+        self.now, self.lock = now, threading.RLock()
+        self.frames, self.inputs = OrderedDict(), OrderedDict()
+        self.captured = self.skipped = self.dropped = 0
+        self.rtt, self.decoder, self.synced = 0, '', False
+        self.sequence = 0
+
+    def add(self, **values):
+        with self.lock:
+            self.sequence = (self.sequence + 1) & 0xffffffff
+            record = dict.fromkeys(('s', 'k', 'b', 'w', 'h', 'cap', 'arr', 'e0', 'e1', 'snd',
+                                    'wire', 'rx', 'dec', 'drw', 'vs', 'echo', 'tier', 'br'), 0)
+            record.update(values, s=self.sequence)
+            self.frames[self.sequence] = record
+            while len(self.frames) > 4096:
+                self.frames.popitem(last=False)
+            for event in self.inputs.values():
+                if not event['frame'] and event['inj'] <= record['cap']:
+                    event.update(frame=self.sequence, cap=record['cap'])
+                    record['echo'] = event['id']
+            return record
+
+    def report(self, message):
+        with self.lock:
+            if message['t'] == 'rx':
+                frame = self.frames.get(message.get('s'))
+                if frame and isinstance(message.get('r'), (int, float)):
+                    frame['rx'] = int(message['r'])
+            elif message['t'] == 'fd':
+                for item in message.get('f', [])[:4096]:
+                    if isinstance(item, list) and len(item) >= 4:
+                        frame = self.frames.get(item[0])
+                        if frame:
+                            for name, val in zip(('dec', 'drw', 'vs'), item[1:4]):
+                                if isinstance(val, (int, float)):
+                                    frame[name] = int(val)
+                self.dropped += max(0, int(message.get('drop', 0)))
+            elif message['t'] == 'clock':
+                self.rtt = float(message.get('rtt', 0))
+                self.decoder = str(message.get('dec', ''))[:1024]
+                self.synced = True
+
+    def input(self, m):
+        if not isinstance(m.get('i'), int) or not m['i']:
+            return
+        with self.lock:
+            self.inputs[m['i']] = dict(id=m['i'], kind=m['t'], tv=m.get('tv') or 0,
+                                       inj=self.now(), frame=0, cap=0)
+            while len(self.inputs) > 512:
+                self.inputs.popitem(last=False)
+
+    def summary(self):
+        with self.lock:
+            now = self.now()
+            frames = [f for f in self.frames.values() if f['cap'] >= now-2000000]
+            out = dict(captured=self.captured, skipped=self.skipped, dropped=self.dropped,
+                       rtt=self.rtt, decoder=self.decoder, synced=self.synced,
+                       fps=sum(f['vs'] > 0 for f in frames)/2, sentFps=len(frames)/2,
+                       mbps=round(sum(f['b'] for f in frames)*4/1e6, 2))
+            for key, start, end in (('capture', 'cap', 'arr'), ('queue', 'arr', 'e0'),
+                                    ('encode', 'e0', 'e1'), ('network', 'e1', 'rx'),
+                                    ('decode', 'rx', 'dec'), ('draw', 'dec', 'drw'), ('total', 'cap', 'drw')):
+                out[key] = distribution([(f[end]-f[start])/1000 for f in frames if f[start] and f[end]])
+            return out
+
+    def snapshot(self, since=0, settle=1500000):
+        with self.lock:
+            return dict(frames=[dict(f) for f in self.frames.values() if f['s'] > since and f['cap'] <= self.now()-settle],
+                        inputs=[dict(i) for i in self.inputs.values()], captured=self.captured, summary=self.summary())

ui/frame_telemetry.py

@@ -512,7 +512,7 @@ def compat_report(report):
         if k in p:
             p[k] = scrub(p[k], n)
     src = str(p.pop('source', '') or '')
-    if src == 'F-Droid':
+    if src in ('F-Droid', 'meta-store'):  # fixed source tags, never a person's file name
         p['source'] = src
     elif src.startswith(('http://', 'https://')) and _scrub_url(src) != '<url>':
         p['source'] = _scrub_url(src)

ui/index.html

@@ -398,8 +398,9 @@
   .cat-card .s { color: var(--muted); font-size: 12px; }
   .cat-card .why { color: var(--muted); font-size: 11.5px; line-height: 1.4; }
   .cat-card .row { margin-top: auto; }
-  .v-works, .v-likely { color: var(--green-hi); } .v-maybe { color: var(--warn); }
-  .v-unlikely, .v-no { color: var(--bad); }
+  .v-works, .v-likely, .item .s.v-works, .item .s.v-likely { color: var(--green-hi); }
+  .v-maybe, .item .s.v-maybe { color: var(--warn); }
+  .v-unlikely, .v-no, .item .s.v-unlikely, .item .s.v-no { color: var(--bad); }  /* over .item .s's grey */
   .vbadge { font-size: 10.5px; letter-spacing: .5px; text-transform: uppercase; white-space: nowrap; margin-left: auto; }
   @media (max-width: 1100px) { .and-grid { grid-template-columns: 1fr; } }
   /* ---- Steam games (owned + store) ---- */
@@ -1005,6 +1006,61 @@
           library under its own name and opens in its own panel. Test launches it and records
           whether it stays up; Report records how it worked for you.</div>
       </div>
+      <section class="panel" id="installQueue" hidden>
+        <div class="shelf-head"><h2>Install queue</h2><span class="count" id="queueCount"></span></div>
+        <div class="list" id="queueList"></div>
+        <div class="hint">Games from the store, your Quest and your Meta library install one after another.
+          Remove takes a game out before it starts.</div>
+      </section>
+      <section class="panel" id="quest">
+        <div class="shelf-head"><h2>Import from my Quest</h2><span class="count" id="questCount"></span><span class="spacer"></span>
+          <button class="small" id="questScan" title="Look for a Meta Quest plugged into this computer by USB">Look for my Quest</button></div>
+        <div class="sub" id="questState" role="status" aria-live="polite">Plug your Quest into this computer by USB, put it on, then Look for my Quest.</div>
+        <label class="sub" style="display:block;margin-top:8px"><input type="checkbox" id="questData"> Also copy each game's files in Android/data (some games keep saves there)</label>
+        <label class="sub" style="display:block;margin-top:4px"><input type="checkbox" id="questOlder"> Allow replacing a newer version on the Frame with the Quest's older one</label>
+        <progress id="questProgress" max="100" hidden aria-label="Import progress" style="width:100%;margin-top:8px"></progress>
+        <div class="list" id="questApps" style="margin-top:8px"></div>
+        <div class="hint">Copies games you own from your own Quest (developer mode on) to the Frame. A game with
+          OBB data takes two imports: the first installs it; start it from the Steam library, then import again to
+          copy its data in. Frame Control never starts the game itself. Games that
+          use Meta's licence check install with a warning: on the Frame that check can't reach Meta, so they may quit,
+          hang, or run without online features. Frame Control won't remove that check. <a href="https://github.com/saphid/frame-control/blob/main/docs/quest-import.md" target="_blank" rel="noopener noreferrer">How it works</a></div>
+      </section>
+      <section class="panel" id="metaLib">
+        <div class="shelf-head"><h2>My Meta library</h2><span class="tag">Experimental</span><span class="count" id="metaCount"></span><span class="spacer"></span>
+          <button class="small" id="metaRefresh" hidden title="Read your Meta library again">Refresh</button>
+          <button class="small" id="metaDisconnect" hidden title="Forget your Meta token on this computer (and sign out of Meta in Frame Control)">Disconnect</button></div>
+        <div class="sub" id="metaState" role="status" aria-live="polite">Off. Nothing is sent to Meta until you connect.</div>
+        <p class="hint" style="color:var(--warn)">Experimental. This uses Meta's undocumented internal API with your own Meta
+          access token. It may stop working whenever Meta changes things, and using it may be against Meta's terms; your
+          account is your responsibility. It only lists and downloads games your account owns, installs them as they are,
+          and never removes a licence check.</p>
+        <div id="metaConnectBox">
+          <label class="sub" style="display:block;margin-top:6px"><input type="checkbox" id="metaAck"> I understand, and want to
+            use my own Meta token with Frame Control</label>
+          <div id="metaSignInRow" hidden style="display:flex;gap:8px;align-items:center;margin-top:6px">
+            <button class="small" id="metaSignIn" disabled title="Opens Meta's own login page in a Frame Control window">Sign in with Meta…</button>
+            <span class="hint" style="margin:0">or paste your token:</span><span class="spacer"></span>
+            <button class="small" id="metaSignOut" title="Clear the Meta sign-in that Frame Control's sign-in window keeps">Sign out of Meta in Frame Control</button></div>
+          <div style="display:flex;gap:8px;margin-top:6px">
+            <input type="password" id="metaToken" autocomplete="off" spellcheck="false" style="flex:1"
+                   placeholder="Your Meta access token (starts with OC or FRL)" aria-label="Meta access token" disabled>
+            <button class="small" id="metaConnect" disabled>Connect</button></div>
+          <div class="hint"><a href="https://github.com/saphid/frame-control/blob/main/docs/meta-library.md#your-token" target="_blank" rel="noopener noreferrer">How to get your token</a>.
+            Sign in with Meta (desktop app) opens Meta's login page in its own Frame Control window and takes the token
+            from there; it never reads your browser.
+            Frame Control checks it with Meta, then keeps it in a private file on this computer (never on the Frame, and
+            never in reports). Disconnect deletes it.</div>
+        </div>
+        <div class="sub" id="metaShare" hidden style="margin-top:6px"></div>
+        <label class="sub" id="metaOlderBox" hidden style="display:block;margin-top:4px"><input type="checkbox" id="metaOlder"> Allow replacing a newer version on the Frame</label>
+        <progress id="metaProgress" max="100" hidden aria-label="Install progress" style="width:100%;margin-top:8px"></progress>
+        <div class="list" id="metaApps" style="margin-top:8px"></div>
+        <div class="hint">Install downloads the game from Meta and installs it like Import from my Quest; a game with OBB
+          data takes a second Install while it is open. Install and test also starts it, adds its data, watches it for
+          about 30 seconds and records whether it ran; Test again does just the test. Results go to the compatibility
+          reports, shared only if you share compatibility results. <a href="https://github.com/saphid/frame-control/blob/main/docs/meta-library.md" target="_blank" rel="noopener noreferrer">How it works</a></div>
+      </section>
       <section class="panel disp" id="display">
       <div class="shelf-head"><h2>Android display</h2><span class="count">Lepton</span><span class="spacer"></span>
         <button class="small" id="dispReload" title="Read the current values again">Refresh</button></div>
@@ -1172,7 +1228,7 @@
     </section>
 
     <section class="panel" id="macview" hidden>
-      <div class="shelf-head"><h2>Mac in the headset</h2><span class="count" id="mvCount"></span><span class="spacer"></span>
+      <div class="shelf-head"><h2 id="mvTitle">Mac in the headset</h2><span class="count" id="mvCount"></span><span class="spacer"></span>
         <select id="mvQuality" title="Picture quality and bandwidth">
           <option value="sharp">Sharp</option><option value="balanced" selected>Balanced</option>
           <option value="light">Light</option><option value="compatible">Compatible (JPEG)</option>
@@ -1189,7 +1245,7 @@
         <button class="small danger" data-mv="stopall">Stop all</button>
       </div>
       <div class="hint">Each window or screen becomes its own panel in the headset. Place it with the SteamVR dashboard
-        (Float in World, Move, Size). Point and click with the laser, scroll with the thumbstick, and type on the Mac's keyboard.</div>
+        (Float in World, Move, Size). Point and click with the laser, scroll with the thumbstick, and type on your computer’s keyboard.</div>
     </section>
 
     <section class="panel" id="privacy">
@@ -1483,6 +1539,8 @@ function applyHostWording(h) {
   // The iPhone app: the server runs on the Frame, and saving goes to the phone's Photos.
   document.body.classList.toggle("mobile", !!h.mobile);
   $("shotsFolder").hidden = !!h.mobile;
+  $("quest").hidden = !!h.mobile;
+  $("metaLib").hidden = !!h.mobile;  // the Quest plugs into a computer; the phone app's server runs on the Frame
   if (!h.mobile) $("shotsFolder").textContent = h.fileManager === "your file manager" ? "Open folder" : `Show in ${h.fileManager}`;
   $("shotsSaveNew").textContent = h.mobile ? `Save all to ${h.computer}` : `Save new to ${h.computer}`;
   $("clipMac").textContent = `Send ${h.computer} clipboard`;
@@ -2635,32 +2693,65 @@ document.body.addEventListener("click", async (e) => {
 // Installs run as server jobs: start one, then poll until it's done. The
 // bottom bar counts what's running; `installing` keeps re-rendered lists from
 // offering Install again for something already on its way.
-const installing = new Set();
+// Android installs wait their turn in the server's install queue (queue_job in
+// server.py); `queued` holds the ones still waiting.
+const installing = new Set(), queued = new Set();
 let jobsRunning = 0;
 function showJobs() {
+  const waiting = queued.size, running = jobsRunning - waiting;
   $("jobs").hidden = !jobsRunning;
-  $("jobsText").textContent = `${jobsRunning} install${jobsRunning === 1 ? "" : "s"} running`;
+  $("jobsText").textContent = [running ? `${running} install${running === 1 ? "" : "s"} running` : "",
+                               waiting ? `${waiting} queued` : ""].filter(Boolean).join(", ");
 }
 async function runJob(label, key, start, onProgress = () => {}) {
   installing.add(key); jobsRunning++; showJobs();
-  log(label + "…");
   try {
-    const { job } = await start();
+    const started = await start();
+    const { job } = started;
+    log(started.queued ? started.message : label + "…");
+    if (started.queued) { queued.add(key); showJobs(); }
+    if (started.queued != null) loadQueue();
     for (let misses = 0; ;) {
       await new Promise(ok => setTimeout(ok, 1500));
       let j;
       try { j = await api(`/api/job?id=${encodeURIComponent(job)}`); misses = 0; }
       catch (e) { if (++misses >= 20 || /no such job/.test(e.message)) throw e; continue; }
+      if (j.queued !== queued.has(key)) { j.queued ? queued.add(key) : queued.delete(key); showJobs(); }
       onProgress(j);
       if (!j.done) continue;
+      if (j.cancelled) { log(`${label}: removed from the install queue`); return null; }
       if (j.error) throw new Error(j.error);
       log(j.message, "ok"); toast(j.message);
       return j.result || {};
     }
   } catch (e) {
     log(`${label} failed: ${e.message}`, "e"); toast(`${label} failed: ${e.message}`, true);
-  } finally { installing.delete(key); jobsRunning--; showJobs(); }
+  } finally { installing.delete(key); queued.delete(key); jobsRunning--; showJobs(); }
 }
+// The install queue as the server has it: also what an earlier visit to this page queued.
+let queueTimer;
+async function loadQueue() {
+  clearTimeout(queueTimer);
+  let jobs;
+  try { ({ jobs } = await api("/api/queue")); } catch { jobs = null; }
+  if (jobs) {
+    $("installQueue").hidden = !jobs.length;
+    $("queueCount").textContent = jobs.length ? `${jobs.length}` : "";
+    $("queueList").innerHTML = jobs.map(j => `<div class="item"><div class="grow"><div class="t">${esc(j.label)}</div>
+        <div class="s">${esc(j.queued ? j.stage || "Queued" : `${j.stage || "Starting"}${j.percent != null ? ` · ${Math.round(j.percent)}%` : ""}`)}</div></div>
+        ${j.queued ? `<button class="small" data-unqueue="${esc(j.job)}">Remove</button>` : `<span class="tag">Installing</span>`}</div>`).join("");
+  }
+  if (!jobs || jobs.length) queueTimer = setTimeout(loadQueue, 2000);
+}
+$("queueList").addEventListener("click", async e => {
+  const b = e.target.closest("[data-unqueue]");
+  if (!b) return;
+  b.disabled = true;
+  try { const d = await api("/api/queue", { action: "remove", job: b.dataset.unqueue }); toast(d.message); }
+  catch (err) { toast(err.message, true); }
+  loadQueue();
+});
+loadQueue();
 const POWER = { suspend: ["Put the Frame to sleep?", "Sleep"], reboot: ["Restart the Frame?", "Restart"],
                 poweroff: ["Shut the Frame down?", "Shut down"] };
 function askPower(what) {
@@ -3329,6 +3420,7 @@ async function installStoreApp() {
   if(existing&&!existing.done)return;
   const state={stage:'Downloading',percent:null,done:false};sourceState.jobs.set(key,state);updateInstall();
   const result=await runJob(`Install ${o.name}`,key,()=>api('/api/sources/install',{source:o.source,id:o.id,version_code:o.version_code??null}),j=>{Object.assign(state,{stage:j.stage||'Downloading',percent:j.percent??null,error:j.error});updateInstall();});
+  if(result===null){sourceState.jobs.delete(key);updateInstall();return;}  // removed from the install queue
   Object.assign(state,{done:true,result,error:result?null:state.error||"We couldn't finish the installation. Try again."});updateInstall();
   if(result)loadAndroid();
 }
@@ -3382,6 +3474,7 @@ async function loadAndroid() {
   try {
     androidApps = (await api("/api/android")).apps;
   } catch (e) { return failed($("andApps"), e); }
+  if (metaLib.connected) renderMetaApps();  // "On the Frame" marks in My Meta library
   $("andCount").textContent = androidApps.length ? `${androidApps.length} installed` : "";
   $("andApps").innerHTML = androidApps.length ? androidApps.map(a => {
     const c = cat.apps && cat.apps.find(x => x.p === a.package);
@@ -3405,6 +3498,209 @@ async function loadAndroid() {
   });
 }
 
+// ---- Import from my Quest (frame_quest.py): adb on this computer, never on the Frame ----
+const quest = { serial: null };
+function questSize(bytes) {
+  if (bytes == null) return "";
+  if (bytes >= 1073741824) return `${(bytes / 1073741824).toFixed(1)} GB`;
+  if (bytes >= 1048576) return `${Math.round(bytes / 1048576)} MB`;
+  return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}
+async function loadQuest() {
+  $("questScan").disabled = true; $("questState").textContent = "Looking for your Quest…"; $("questApps").innerHTML = "";
+  let d;
+  try { d = await api("/api/quest"); }
+  catch (e) { $("questState").textContent = e.message; return; }
+  finally { $("questScan").disabled = false; }
+  quest.serial = d.quest ? d.quest.serial : null;
+  $("questCount").textContent = d.quest ? `${d.apps.length} app${d.apps.length === 1 ? "" : "s"}` : "";
+  if (!d.quest) { $("questState").textContent = d.guidance || "No Quest found."; return; }
+  $("questState").textContent = `${d.quest.model || "Quest"} connected (${d.quest.serial}). Games that use Meta's licence check install with a warning: they may quit or hang on the Frame.`;
+  const installed = new Set(androidApps.map(a => a.package));
+  $("questApps").innerHTML = d.apps.length ? d.apps.map(a => {
+    const bits = [a.split ? `split APK (${a.apks.length} files)` : "single APK"];
+    if (a.obb != null) bits.push(`OBB ${questSize(a.obb)}`);
+    if (a.data != null) bits.push(`Android/data ${questSize(a.data)}`);
+    if (a.meta) bits.push("Meta app: needs Meta's services");
+    return `<div class="item"><div class="grow"><div class="t">${esc(a.package)}</div><div class="s">${esc(bits.join(" · "))}</div></div>
+      ${installed.has(a.package) ? `<span class="tag">On the Frame</span>` : ""}
+      <button class="small" data-quest-import="${esc(a.package)}"${installing.has("quest:" + a.package) ? " disabled" : ""}>${queued.has("quest:" + a.package) ? "Queued" : installed.has(a.package) ? "Import again" : "Import"}</button></div>`;
+  }).join("") : `<div class="sub">No games or apps you installed are on this Quest.</div>`;
+}
+$("questScan").onclick = loadQuest;
+$("questApps").addEventListener("click", e => {
+  const b = e.target.closest("[data-quest-import]");
+  if (!b) return;
+  const pkg = b.dataset.questImport, key = "quest:" + pkg;
+  if (installing.has(key)) return;
+  b.disabled = true; b.textContent = "Queued";
+  const bar = $("questProgress");
+  // Several can be queued: the bar and the status line follow whichever is installing.
+  runJob(`Import ${pkg} from Quest`, key,
+         () => api("/api/quest", { action: "import", package: pkg, serial: quest.serial, data: $("questData").checked, allowDowngrade: $("questOlder").checked }),
+         j => { if (j.queued || j.done) return; b.textContent = "Importing…"; bar.hidden = false; bar.dataset.owner = key;
+                if (j.stage) $("questState").textContent = `${pkg}: ${j.stage}`; bar.value = j.percent ?? 0; })
+    .then(r => { if (bar.dataset.owner === key) bar.hidden = true; if (r && r.app) { b.textContent = "Imported"; $("questState").textContent = r.message || `Imported ${pkg}`; loadAndroid(); }
+                  else { b.disabled = false; b.textContent = "Import";
+                         if (r !== null) $("questState").textContent = `${pkg} wasn't imported; the reason is in the message log below.`; } });
+});
+
+// ---- My Meta library, Experimental (frame_meta.py): the person's own token, games they own ----
+// The token is only ever in the password box until Connect sends it; the server never sends it back.
+const metaLib = { apps: [], results: new Map(), connected: false };
+const META_VERDICT = { works: ["v-works", "Works on Frame"], maybe: ["v-maybe", "Works with problems"], no: ["v-no", "Doesn't work"] };
+function metaShareNote(s) {
+  const box = $("metaShare");
+  if (!metaLib.connected || !s) { box.hidden = true; return; }
+  box.hidden = false;
+  box.innerHTML = s.shared ? "Test results are shared with the compatibility database (Privacy settings)."
+    : s.blocked ? `Test results are saved on this computer only (${esc(s.blocked)}).`
+    : `Test results are saved on this computer only. <button class="small" id="metaShareOn">Share test results</button>`;
+  const on = $("metaShareOn");
+  if (on) on.onclick = async () => {
+    if (!confirm("Share compatibility results?\n\nYour test results (package, version, whether it ran, and why not) go to "
+                 + "Frame Control's shared compatibility database, so everyone sees better verdicts. Never your token, "
+                 + "account or game files. You can turn it off in Privacy settings.")) return;
+    await setTelemetry({ compat: true });
+    loadMeta();
+  };
+}
+function renderMeta(d) {
+  metaLib.connected = !!d.connected;
+  $("metaConnectBox").hidden = metaLib.connected;
+  $("metaDisconnect").hidden = $("metaRefresh").hidden = $("metaOlderBox").hidden = !metaLib.connected;
+  $("metaState").textContent = metaLib.connected
+    ? `Connected${d.user && d.user.name ? ` as ${d.user.name}` : ""}.` : "Off. Nothing is sent to Meta until you connect.";
+  metaShareNote(d.sharing);
+}
+function renderMetaApps() {
+  // Meta lists everything the account owns: games, but also apps and environments.
+  $("metaCount").textContent = metaLib.connected ? `${metaLib.apps.length} app${metaLib.apps.length === 1 ? "" : "s"}` : "";
+  if (!metaLib.connected) { $("metaApps").innerHTML = ""; return; }
+  const installed = new Set(androidApps.map(a => a.package));
+  $("metaApps").innerHTML = metaLib.apps.length ? metaLib.apps.map(a => {
+    // Sizes first: the line is cut short with "…" in a narrow panel, and the package is the least needed.
+    const bits = [a.size ? questSize(a.size) : "", a.data_files ? `OBB ${questSize(a.data_size)}` : "",
+                  a.version ? `v${a.version}${a.version_code != null ? ` (${a.version_code})` : ""}` : "", a.package || "package unknown"];
+    const line = bits.filter(Boolean).join(" · ");
+    const problem = a.problem ? `<div class="s v-no" title="${esc(a.problem)}">${esc(a.problem)}</div>` : "";
+    // Required game data Frame Control can't place as an OBB (data_plan in frame_meta.py): the game may not run without it.
+    const skipped = (a.skipped_files || []).length
+      ? `<div class="s v-maybe" title="${esc(a.skipped_files.join("\n"))}">Not installed: ${a.skipped_files.length} required data file${a.skipped_files.length === 1 ? "" : "s"} (${esc(a.skipped_files.join(", "))}); the game may not run without ${a.skipped_files.length === 1 ? "it" : "them"}.</div>` : "";
+    const v = a.verdict && META_VERDICT[a.verdict.verdict];
+    const verdict = v ? `<div class="s ${v[0]}" title="${esc((a.verdict.lines || []).join("\n"))}">Community: ${v[1]}</div>` : "";
+    const r = metaLib.results.get(a.package);
+    const result = r ? `<div class="s">${esc(r)}</div>` : "";
+    const busy = installing.has("meta:" + a.id) ? " disabled" : "", waits = queued.has("meta:" + a.id);
+    const on = installed.has(a.package);
+    const can = a.package && !a.problem;
+    return `<div class="item"><div class="grow"><div class="t">${esc(a.title)}</div><div class="s" title="${esc(line)}">${esc(line)}</div>${problem}${skipped}${verdict}${result}</div>
+      ${on ? `<span class="tag">On the Frame</span>` : ""}
+      ${waits ? `<span class="tag">Queued</span>` : ""}
+      ${can ? `<button class="small" data-meta-install="${esc(a.id)}"${busy}>${on ? "Install again" : "Install"}</button>
+      <button class="small" data-meta-install="${esc(a.id)}" data-test="1"${busy} title="Install, start it, watch it for about 30 s and record whether it ran">Install and test</button>` : ""}
+      ${on ? `<button class="small" data-meta-test="${esc(a.package)}"${busy} title="Start it again, watch it for about 30 s and record whether it ran">Test again</button>` : ""}</div>`;
+  }).join("") : `<div class="sub">No Quest apps in this Meta account.</div>`;
+}
+async function loadMeta(refresh = false) {
+  let d;
+  try { d = await api("/api/meta"); } catch (e) { $("metaState").textContent = e.message; return; }
+  renderMeta(d);
+  if (!d.connected) { metaLib.apps = []; renderMetaApps(); return; }
+  $("metaState").textContent += " Reading your library…";
+  try { d = await api(`/api/meta?library=1${refresh ? "&refresh=1" : ""}`); }
+  catch (e) { $("metaState").textContent = e.message; return; }
+  renderMeta(d);
+  metaLib.apps = d.apps || [];
+  renderMetaApps();
+}
+// Sign in with Meta: the desktop app only (app/meta-signin.js); a plain browser pastes the token.
+const metaSignInOk = !!(window.frameApp && window.frameApp.meta && window.frameApp.meta.signIn);
+$("metaSignInRow").hidden = !metaSignInOk;
+let metaDisconnecting = false;  // from pressing Disconnect until the server has deleted the token
+$("metaAck").onchange = e => {
+  $("metaToken").disabled = $("metaConnect").disabled = !e.target.checked;
+  $("metaSignIn").disabled = !e.target.checked || metaDisconnecting;
+};
+$("metaSignIn").onclick = async () => {
+  if (!$("metaAck").checked || metaDisconnecting) return;
+  $("metaSignIn").disabled = true;
+  $("metaState").textContent = "Sign in to Meta in the window that opened…";
+  try {
+    const r = await window.frameApp.meta.signIn(true);
+    if (r && r.ok) { toast(r.message || "Connected"); loadMeta(); }
+    else { await loadMeta(); $("metaState").textContent = (r && r.error) || "Sign-in didn't finish."; }
+  } catch (e) { $("metaState").textContent = e.message; }
+  finally { $("metaSignIn").disabled = !$("metaAck").checked || metaDisconnecting; }
+};
+$("metaSignOut").onclick = async () => {
+  try { await window.frameApp.meta.signOut(); toast("Signed out of Meta in Frame Control"); }
+  catch (e) { toast(e.message, true); }
+};
+$("metaConnect").onclick = async () => {
+  const token = $("metaToken").value;
+  $("metaConnect").disabled = true;
+  try {
+    const d = await api("/api/meta", { action: "connect", token, acknowledged: $("metaAck").checked });
+    $("metaToken").value = "";
+    toast(d.message || "Connected");
+    loadMeta();
+  } catch (e) { $("metaState").textContent = e.message; }
+  finally { $("metaConnect").disabled = !$("metaAck").checked; }
+};
+$("metaDisconnect").onclick = async () => {
+  // One Disconnect at a time, guarded from before the confirm until the delete returns.
+  if (metaDisconnecting) return;
+  metaDisconnecting = true; $("metaDisconnect").disabled = $("metaSignIn").disabled = true;
+  if (!confirm("Disconnect your Meta account? Its token is deleted from this computer. Games already installed stay."
+               + (metaSignInOk ? "\n\nThis also signs out of Meta in Frame Control (its Sign in with Meta window), so the next sign-in starts fresh." : ""))) {
+    metaDisconnecting = false; $("metaDisconnect").disabled = false;
+    $("metaSignIn").disabled = !$("metaAck").checked;
+    return;
+  }
+  // No sign-in from here until the token is deleted. Sign-out first: it stops the sign-in
+  // window (and any connect it started) before the account is forgotten.
+  try {
+    if (metaSignInOk) {
+      try { await window.frameApp.meta.signOut(); } catch (e) { toast(`Couldn't sign out of Meta in Frame Control: ${e.message}`, true); }
+    }
+    try { const d = await api("/api/meta", { action: "disconnect" }); toast(d.message || "Disconnected"); }
+    catch (e) { toast(e.message, true); }
+  } finally { metaDisconnecting = false; $("metaDisconnect").disabled = false; }
+  $("metaAck").checked = false; $("metaToken").disabled = $("metaConnect").disabled = $("metaSignIn").disabled = true;
+  metaLib.results.clear(); loadMeta();
+};
+$("metaRefresh").onclick = () => loadMeta(true);
+$("metaApps").addEventListener("click", async e => {
+  const b = e.target.closest("[data-meta-install],[data-meta-test]");
+  if (!b) return;
+  const bar = $("metaProgress");
+  if (b.dataset.metaTest) {
+    const pkg = b.dataset.metaTest, key = "meta:" + (metaLib.apps.find(a => a.package === pkg) || {}).id;
+    if (!confirm("Test it now?\n\nIt opens in the headset for about 30 seconds and records whether it stays up.")) return;
+    b.disabled = true;
+    const r = await runJob(`Test ${pkg}`, key, () => api("/api/meta", { action: "test", package: pkg }));
+    if (r && r.message) metaLib.results.set(pkg, r.message);
+    renderMetaApps(); loadReports();
+    return;
+  }
+  const app = metaLib.apps.find(a => a.id === b.dataset.metaInstall), test = !!b.dataset.test;
+  if (!app || installing.has("meta:" + app.id)) return;
+  if (test && !confirm(`Install and test ${app.title}?\n\nFrame Control starts it in the headset (twice if it has game data to add), `
+                       + "watches it for about 30 seconds and records whether it ran.")) return;
+  b.disabled = true;
+  // Several can be queued: the bar and the status line follow whichever is installing.
+  const r = await runJob(`${test ? "Install and test" : "Install"} ${app.title} from Meta`, "meta:" + app.id,
+    () => api("/api/meta", { action: "install", app: app.id, test, allowDowngrade: $("metaOlder").checked }),
+    j => { renderMetaApps(); if (j.queued || j.done) return; bar.hidden = false; bar.dataset.owner = "meta:" + app.id;
+           if (j.stage) $("metaState").textContent = `${app.title}: ${j.stage}`; bar.value = j.percent ?? 0; });
+  if (bar.dataset.owner === "meta:" + app.id) bar.hidden = true;  // not while another install still shows its progress
+  if (r && r.message) { $("metaState").textContent = r.message; metaLib.results.set(app.package, r.test ? r.test.message : r.message); }
+  else if (r !== null) $("metaState").textContent = `${app.title} wasn't installed; the reason is in the message log below.`;
+  loadAndroid(); renderMetaApps(); if (test) loadReports();
+});
+loadMeta();
+
 async function loadCatalog() {
   try { cat.apps = (await api("/api/android/catalog")).apps; }
   catch (e) { $("catGrid").innerHTML = `<div class="sub">${esc(e.message)}</div>`; return; }
@@ -3955,8 +4251,16 @@ async function loadMacView(restart) {
   if (seq !== mvSeq) return;
   const box = $("macview");
   if (err) { box.hidden = false; return failed($("mvWindows"), err); }
-  if (!s.available) { box.hidden = true; return; }
+  if (!s.available) {
+    box.hidden = !s.host;
+    if (s.host) { $("mvTitle").textContent = "PC in the headset"; $("mvWindows").textContent = s.reason; }
+    return;
+  }
   box.hidden = false;
+  const pc = s.host && s.host !== "mac";
+  $("mvTitle").textContent = pc ? "PC in the headset" : "Mac in the headset";
+  $("mvSeparate").closest("label").hidden = pc;
+  $("mvSeparate").disabled = pc;
   const live = new Set((s.streams || []).map(x => x.src));
   const byStream = src => (s.streams || []).find(x => x.src === src);
   $("mvCount").textContent = live.size ? `${live.size} showing${s.route === "usb" ? " · over USB-C" : ""}` : "";
@@ -3966,6 +4270,12 @@ async function loadMacView(restart) {
   $("mvPerm").hidden = !perm.length;
   $("mvPerm").innerHTML = perm.join(" ") + `<div class="row"><button class="small action" data-mv="perm">Allow…</button>
     <span class="sub">Then press Refresh. macOS may ask you to reopen Frame Control.</span></div>`;
+  if (pc) {
+    $("mvPerm").hidden = s.host !== "linux";
+    $("mvPerm").innerHTML = `<button class="small action" data-mv="perm" ${s.selecting ? "disabled" : ""}>${s.selecting ? "Choose on your computer…" : "Choose a window or screen…"}</button>
+      <span class="sub">Your desktop asks what to share and whether to allow pointer and keyboard control.</span>` +
+      (s.selectionError ? `<div class="sub">${esc(s.selectionError)}</div>` : "");
+  }
   const liveAs = src => live.has(src) ? src : src.startsWith("window:") && live.has("separate:" + src.slice(7)) ? "separate:" + src.slice(7) : "";
   $("mvDisplays").innerHTML = (s.displays || []).map(d =>
     mvRow(d.src, `Whole screen: ${d.name}`, `${d.w}×${d.h}${d.main ? " · main display" : ""}`, d.w, d.h, liveAs(d.src), byStream(liveAs(d.src)))).join("");
@@ -3973,11 +4283,11 @@ async function loadMacView(restart) {
   $("mvWinCount").textContent = wins.length ? `${wins.length}` : "";
   $("mvWindows").innerHTML = !s.screen ? `<div class="sub">Windows appear here once Screen Recording is allowed.</div>`
     : wins.length ? wins.map(w => mvRow(w.src, w.title || w.app, `${w.title ? w.app + " · " : ""}${w.w}×${w.h}`, w.w, w.h, liveAs(w.src), byStream(liveAs(w.src)))).join("")
-    : `<div class="sub">No windows open on this Mac's current desktop.</div>`;
+    : `<div class="sub">No shared windows yet.</div>`;
   // Keep the numbers fresh while something is in the headset and the card is on screen.
   clearTimeout(mvTimer);
   const tick = () => { mvTimer = document.hidden || !box.offsetParent ? setTimeout(tick, 3000) : (loadMacView(), 0); };
-  if (live.size) mvTimer = setTimeout(tick, 3000);
+  if (live.size || s.selecting) mvTimer = setTimeout(tick, 3000);
 }
 $("mvRefresh").onclick = () => loadMacView(true);
 $("mvSeparate").checked = localStorage.getItem("mvSeparate") !== "0";
@@ -3986,7 +4296,7 @@ $("macview").onclick = async e => {
   const b = e.target.closest("[data-mv]"); if (!b) return;
   const src = b.dataset.src;
   if (b.dataset.mv === "show") {
-    const as = $("mvSeparate").checked && src.startsWith("window:") ? "separate:" + src.slice(7) : src;
+    const as = !$("mvSeparate").disabled && $("mvSeparate").checked && src.startsWith("window:") ? "separate:" + src.slice(7) : src;
     await act(`Show ${b.dataset.title} in the headset`, async () => {
       const r = await api("/api/macview", { action: "show", src: as, quality: $("mvQuality").value,
                                             w: +b.dataset.w || undefined, h: +b.dataset.h || undefined });
@@ -3997,7 +4307,7 @@ $("macview").onclick = async e => {
   } else if (b.dataset.mv === "stopall") {
     await act("Stop everything in the headset", () => api("/api/macview", { action: "stop" }), b);
   } else if (b.dataset.mv === "perm") {
-    await act("Ask macOS for permission", () => api("/api/macview", { action: "permissions" }), b);
+    await act("Choose what to share", () => api("/api/macview", { action: "permissions" }), b);
   }
   setTimeout(loadMacView, 800);
 };

ui/mac-view.html

@@ -22,7 +22,7 @@
 </head>
 <body>
 <canvas id="c" width="16" height="9"></canvas>
-<div id="note">Connecting to the Mac…</div>
+<div id="note">Connecting to your computer…</div>
 <div id="hud" hidden></div>
 <script>
 "use strict";
@@ -243,14 +243,14 @@ async function connect() {
     // Refused before ever getting a key: the ticket expired or was revoked,
     // and retrying can't help.
     if (!reconnectKey && ++failedStarts >= 3) {
-      show("This view has expired. Press Show in Frame Control on the Mac to open it again.");
+      show("This view has expired. Press Show in Frame Control on your computer to open it again.");
       return;
     }
     hideNoteOnFrame = true;
     // The Mac may be asleep or the tunnel restarting: keep trying.
     retry = Math.min(retry + 1, 6);
     // Keep the Mac's reason (a missing permission, a closed window) on screen.
-    show(lastError ? `${lastError} Retrying…` : "Lost the Mac. Reconnecting…");
+    show(lastError ? `${lastError} Retrying…` : "Lost the computer. Reconnecting…");
     setTimeout(connect, 500 * 2 ** retry);
   };
 }
@@ -269,7 +269,7 @@ function control(m) {
     document.title = tag ? `${name} [${tag}]` : name;
     if (!m.input) {
       hideNoteOnFrame = false;  // a warning, not a connection notice: let it stay its 8 s
-      show("Clicks and keys need Accessibility permission on the Mac (Frame Control asks for it).", 8000);
+      show(m.inputMessage || "Clicks and keys need Accessibility permission on the Mac (Frame Control asks for it).", 8000);
     }
   } else if (m.t === "error") {
     stats.errors.push(m.message);
@@ -391,7 +391,7 @@ addEventListener("keydown", e => onKey(e, true));
 addEventListener("keyup", e => onKey(e, false));
 addEventListener("blur", () => send({ t: "release" }));
 
-show("Connecting to the Mac…");
+show("Connecting to your computer…");
 connect();
 </script>
 </body>

ui/server.py

@@ -55,8 +55,11 @@ import frame_contact  # noqa: E402
 import frame_host  # noqa: E402
 import frame_link  # noqa: E402
 import frame_macview  # noqa: E402
+import frame_pcview  # noqa: E402
 import frame_media  # noqa: E402
 import frame_panels  # noqa: E402
+import frame_quest  # noqa: E402
+import frame_meta  # noqa: E402
 import frame_report  # noqa: E402
 import frame_store  # noqa: E402
 import frame_telemetry  # noqa: E402
@@ -135,7 +138,7 @@ LINK = None  # the connector (frame_link.Link); None on the Frame itself
 # install's clean-up) to the other headset.
 _work_lock = threading.Lock()
 _work = [0]
-NOT_HEADSET_WORK = {"/api/devices", "/api/contact", "/api/contact/prompt"}
+NOT_HEADSET_WORK = {"/api/devices", "/api/contact", "/api/contact/prompt", "/api/queue"}
 
 
 @contextlib.contextmanager
@@ -284,40 +287,120 @@ def backfill_art(apps=(), titles=()):
     return True
 
 
-def start_job(label, work, progress=False):
-    """Run work() in the background. It returns a dict with a "message"."""
+def _new_job_locked(label, **fields):
     now = time.time()
-    with _jobs_lock:
-        for j in [j for j, v in _jobs.items() if v["done"] and now - v["time"] > JOB_TTL]:
-            del _jobs[j]
-        job = secrets.token_hex(8)
-        _jobs[job] = {"label": label, "done": False, "error": None, "message": None, "result": None, "time": now}
+    for j in [j for j, v in _jobs.items() if v["done"] and now - v["time"] > JOB_TTL]:
+        del _jobs[j]
+    job = secrets.token_hex(8)
+    _jobs[job] = {"label": label, "done": False, "error": None, "message": None, "result": None, "time": now, **fields}
+    return job
 
+
+def _run_job(job, label, work, progress):
     def report(stage, percent=None):
         with _jobs_lock:
             _jobs[job].update(stage=stage, percent=percent)
 
-    def run():
-        fields = {}
-        try:
-            result = work(report) if progress else work()
-            fields = {"message": result.get("message") or f"{label}: done", "result": result}
-        except (Failure, frame_android.FrameError) as e:
-            fields = {"error": unreachable(str(e)) or str(e)}
-            frame_telemetry.diagnostic(f"job {label.split()[0]}", e)
-        except SourceError as e:  # already user-readable, and about a store, not the Frame
-            fields = {"error": str(e)}
-        except Exception as e:
-            fields = {"error": f"{type(e).__name__}: {e}"}
-            frame_telemetry.diagnostic(f"job {label.split()[0]}", e)
-        finally:
-            with _jobs_lock:
-                _jobs[job].update(fields, done=True, time=time.time())
+    fields = {}
+    try:
+        result = work(report) if progress else work()
+        fields = {"message": result.get("message") or f"{label}: done", "result": result}
+    except (Failure, frame_android.FrameError) as e:
+        fields = {"error": unreachable(str(e)) or str(e)}
+        frame_telemetry.diagnostic(f"job {label.split()[0]}", e)
+    except SourceError as e:  # already user-readable, and about a store, not the Frame
+        fields = {"error": str(e)}
+    except Exception as e:
+        fields = {"error": f"{type(e).__name__}: {e}"}
+        frame_telemetry.diagnostic(f"job {label.split()[0]}", e)
+    finally:
+        with _jobs_lock:
+            _jobs[job].update(fields, done=True, time=time.time())
 
-    busy_thread(run).start()
+
+def start_job(label, work, progress=False):
+    """Run work() in the background. It returns a dict with a "message"."""
+    with _jobs_lock:
+        job = _new_job_locked(label)
+    busy_thread(_run_job, job, label, work, progress).start()
     return {"message": f"{label}…", "job": job}
 
 
+# ---- The install queue: Android games and apps, one after another ----------
+#
+# Installs from the Android store, Import from my Quest and My Meta library each copy
+# a game into a Lepton instance, and each refuses to start while another is running.
+# Queued, the page can line up several: one worker runs them in order, each as a
+# normal job (/api/job) that reads "queued" until its turn. A queued install can be
+# removed until it starts; each runs on the headset it was queued for, or not at all.
+
+_queue = []  # [job, label, work, progress, headset id], in order; the running one is not here
+_queue_state = {"worker": False, "running": None}
+
+
+def _restage_locked():
+    ahead = 1 if _queue_state["running"] else 0
+    for i, (job, *_) in enumerate(_queue):
+        n = ahead + i
+        _jobs[job]["stage"] = f"Queued: {n} install{'' if n == 1 else 's'} before it" if n else "Queued: next"
+
+
+def queue_job(label, work, progress=False):
+    """Like start_job, but runs after every install queued before it."""
+    device = LINK.active_device()["id"] if LINK else None
+    with _jobs_lock:
+        job = _new_job_locked(label, queued=True, stage=None, percent=None)
+        _queue.append([job, label, work, progress, device])
+        _restage_locked()
+        ahead = len(_queue) - 1 + (1 if _queue_state["running"] else 0)
+        start, _queue_state["worker"] = not _queue_state["worker"], True
+    if start:
+        threading.Thread(target=_drain_queue, daemon=True).start()
+    return {"message": f"{label}: queued, {ahead} before it" if ahead else f"{label}…", "job": job, "queued": ahead}
+
+
+def _drain_queue():
+    while True:
+        with _jobs_lock:
+            if not _queue:
+                _queue_state.update(worker=False, running=None)
+                return
+            job, label, work, progress, device = _queue.pop(0)
+            _queue_state["running"] = job
+            _jobs[job].update(queued=False, stage=None)
+            _restage_locked()
+
+        def guarded(*report, work=work, device=device):
+            with working(device):  # refused if the app switched headsets since it was queued
+                return work(*report)
+        _run_job(job, label, guarded, progress)
+
+
+def install_queue():
+    """The running install and those waiting, in order."""
+    with _jobs_lock:
+        ids = ([_queue_state["running"]] if _queue_state["running"] else []) + [q[0] for q in _queue]
+        return {"jobs": [{"job": j, "label": _jobs[j]["label"], "queued": bool(_jobs[j].get("queued")),
+                          "stage": _jobs[j].get("stage"), "percent": _jobs[j].get("percent")}
+                         for j in ids if j in _jobs]}
+
+
+def queue_action(body):
+    """{"action": "remove", "job"}: take a waiting install out of the queue."""
+    if body.get("action") != "remove":
+        raise Failure("unknown action", 400)
+    job = body.get("job")
+    with _jobs_lock:
+        for i, q in enumerate(_queue):
+            if q[0] == job:
+                del _queue[i]
+                _jobs[job].update(done=True, queued=False, cancelled=True, stage=None, time=time.time(),
+                                  error="Removed from the install queue")
+                _restage_locked()
+                return {"message": f"Removed {_jobs[job]['label']} from the install queue"}
+    raise Failure("that install isn't waiting in the queue (it may have started or finished)", 409)
+
+
 def job_status(query):
     with _jobs_lock:
         job = _jobs.get((parse_qs(query).get("id") or [""])[0])
@@ -1296,7 +1379,7 @@ def android(body):
                 m = frame_apk_versions.install(pkg, url) if url else frame_catalog.install(pkg)
                 message = f"Installed {m['label']}. It's in the Steam library; launching it opens its own panel."
                 return {"message": f"{message} {frame_android.layer_note(m)}".strip(), "app": m}
-            return start_job(f"Install {pkg}", work)
+            return queue_job(f"Install {pkg}", work)
         if action == "refresh-art":
             if not pkg and not body.get("all"):
                 raise Failure('choose a package or all apps', 400)
@@ -1330,6 +1413,149 @@ def android(body):
     raise Failure("unknown action", 400)
 
 
+# ---- Import from my Quest (frame_quest.py, docs/quest-import.md) --------------
+
+QUEST_ON_FRAME = "Import from my Quest runs on your computer, with the Quest plugged into it by USB."
+QUEST_SERIAL = re.compile(r"^[A-Za-z0-9._:\[\]-]{1,128}$")
+
+
+def quest_serial(value):
+    if value in (None, ""):
+        return None
+    if not isinstance(value, str) or not QUEST_SERIAL.match(value):
+        raise Failure("invalid Quest serial", 400)
+    return value
+
+
+def quest_status(query):
+    """The Quest on this computer's USB (or what to do), and the apps on it."""
+    if LOCAL:
+        return {"quest": None, "devices": [], "guidance": QUEST_ON_FRAME, "apps": []}
+    try:
+        return frame_quest.status(quest_serial((parse_qs(query).get("serial") or [None])[0]))
+    except frame_android.FrameError as e:
+        raise Failure(str(e)) from e
+
+
+def quest(body):
+    """{"action": "import", "package", "serial"?, "data"?}: a background job with progress."""
+    if LOCAL:
+        raise Failure(QUEST_ON_FRAME, 400)
+    if body.get("action") != "import":
+        raise Failure("unknown action", 400)
+    pkg = str(body.get("package", ""))
+    if not frame_android.PKG_RE.match(pkg):
+        raise Failure("invalid Android package id", 400)
+    serial, data, older = quest_serial(body.get("serial")), body.get("data", False), body.get("allowDowngrade", False)
+    if type(data) is not bool or type(older) is not bool:
+        raise Failure("data and allowDowngrade must be true or false", 400)
+    ensure_master()
+    return queue_job(f"Import {pkg} from Quest",
+                     lambda report: frame_quest.import_game(pkg, serial, data=data, progress=report,
+                                                            allow_downgrade=older), progress=True)
+
+
+# ---- My Meta library, Experimental (frame_meta.py, docs/meta-library.md) ------
+#
+# Never echoes the token: answers come from frame_meta.status() and _public(), and every
+# error passes through frame_meta.redact().
+
+META_APP_ID = re.compile(r"^[0-9]{1,25}$")
+
+
+def _meta_failure(e):
+    if isinstance(e, frame_meta.SignInCancelled):
+        return Failure(frame_meta.redact(e, 600), 409)
+    status = 400 if isinstance(e, frame_meta.TokenRejected) or "token" in str(e).lower() else 502
+    return Failure(frame_meta.redact(e, 600), status)
+
+
+def meta_sharing():
+    """Whether test results reach the shared compatibility database (Privacy settings)."""
+    blocked = frame_telemetry.blocked()
+    return {"shared": bool(frame_catalog.compat_db.shared() or frame_telemetry.enabled("compat")),
+            "blocked": blocked or None}
+
+
+def meta_status(query):
+    """The connected account (never its token) and, with library=1, the Quest games it owns
+    with any community verdicts."""
+    q = parse_qs(query)
+    out = dict(frame_meta.status(), sharing=meta_sharing())
+    if out["connected"] and q.get("library") == ["1"]:
+        try:
+            apps = frame_meta.with_verdicts(frame_meta.library(refresh=q.get("refresh") == ["1"]))
+            out["apps"] = [frame_meta._public(a) for a in apps]
+        except frame_android.FrameError as e:
+            raise _meta_failure(e) from None
+    return out
+
+
+def meta(body):
+    """{"action": "connect", "token", "acknowledged": true, "attempt"?} | {"action": "disconnect"} |
+    {"action": "cancel-signin", "attempt"} |
+    {"action": "install", "app", "test"?, "allowDowngrade"?} | {"action": "test", "package"}."""
+    action = body.get("action")
+    try:
+        if action == "connect":
+            if body.get("acknowledged") is not True:
+                raise Failure("My Meta library is experimental: tick that you understand the warning first", 400)
+            if not isinstance(body.get("token"), str):
+                raise Failure("paste your Meta access token", 400)
+            attempt = body.get("attempt")
+            if attempt is not None and not (isinstance(attempt, str) and frame_meta.SIGNIN_ATTEMPT.fullmatch(attempt)):
+                raise Failure("invalid sign-in attempt id", 400)
+            return dict(frame_meta.connect(body["token"], attempt=attempt), sharing=meta_sharing(),
+                        message="Connected your Meta account (Experimental)")
+        if action == "cancel-signin":
+            attempt = body.get("attempt")
+            if not (isinstance(attempt, str) and frame_meta.SIGNIN_ATTEMPT.fullmatch(attempt)):
+                raise Failure("invalid sign-in attempt id", 400)
+            return dict(frame_meta.cancel_signin(attempt), sharing=meta_sharing(),
+                        message="Cancelled that Sign in with Meta; it won't be saved")
+        if action == "disconnect":
+            return dict(frame_meta.disconnect(), sharing=meta_sharing(),
+                        message="Disconnected your Meta account; its token was deleted from this computer")
+        if action == "install":
+            app_id, test, older = str(body.get("app", "")), body.get("test", False), body.get("allowDowngrade", False)
+            if not META_APP_ID.match(app_id):
+                raise Failure("invalid Meta app id", 400)
+            if type(test) is not bool or type(older) is not bool:
+                raise Failure("test and allowDowngrade must be true or false", 400)
+            ensure_master()
+
+            def work(report):
+                try:
+                    return frame_meta.install(app_id, test=test, progress=report, allow_downgrade=older)
+                except frame_android.FrameError as e:
+                    raise frame_meta.MetaError(frame_meta.redact(e, 1200)) from None
+                except Exception as e:  # never let an unexpected error's text carry the token
+                    raise frame_meta.MetaError(frame_meta.redact(f"{type(e).__name__}: {e}", 600)) from None
+            return queue_job(f"{'Install and test' if test else 'Install'} {app_id} from Meta", work, progress=True)
+        if action == "test":
+            pkg = str(body.get("package", ""))
+            if not frame_android.PKG_RE.match(pkg):
+                raise Failure("invalid Android package id", 400)
+            ensure_master()
+
+            def test():
+                # run_test's own errors are fixed texts; anything else could carry the game's
+                # log (an ssh error is its output), so it is never shown, not even redacted.
+                try:
+                    return frame_meta.run_test(pkg)
+                except frame_meta.MetaError:
+                    raise
+                except frame_android.FrameError:
+                    raise frame_meta.MetaError(frame_meta.LOG_UNREADABLE) from None
+                except Exception as e:
+                    raise frame_meta.MetaError(f"The test stopped unexpectedly ({type(e).__name__}); "
+                                               "try again.") from None
+            return start_job(f"Test {pkg}", test)
+    except frame_meta.MetaError as e:
+        raise _meta_failure(e) from None
+    raise Failure("unknown action", 400)
+
+
 # Errors that are the APK's own fault, so they belong in the compatibility
 # database as install_failed. Connection trouble and the like don't.
 APK_FAULTS = {"android_installer", "apk_needs_newer_android", "apk_wrong_abi"}
@@ -2103,8 +2329,9 @@ def push_media(path):
 
 # The tunnel gets its own connection: the shared master's options would win
 # over anything added after them.
-macview = frame_macview.MacView(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8"],
-                                lambda remote, stdin=None, timeout=30: ssh(remote, stdin=stdin, timeout=timeout),
+macview = frame_pcview.host_view(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8"],
+                                lambda remote, stdin=None, timeout=30: ssh(remote, stdin=stdin.encode("utf-8") if stdin is not None else None,
+                                                                           timeout=timeout, text=False).decode("utf-8", errors="replace"),
                                 FRAME, track=_live_tunnels.add)
 
 
@@ -2199,7 +2426,7 @@ def source_install(body):
             raise SourceError('This source is disabled')
     except SourceError as e:
         raise Failure(str(e), 400)
-    return start_job('Install ' + entry, lambda report: apk_search.install(source, entry, version, report), progress=True)
+    return queue_job('Install ' + entry, lambda report: apk_search.install(source, entry, version, report), progress=True)
 
 
 def source_manage(body):
@@ -2242,7 +2469,7 @@ POST = {
     "/api/agent/approval": agent_approval, "/api/assistant/chat": assistant_chat,
     "/api/input": remote_input, "/api/touch": remote_touch,
     "/api/settings/artwork": frame_steamgriddb.save_settings,
-    "/api/sources": source_manage, "/api/sources/install": source_install, "/api/android/display": android_display, "/api/android": android, "/api/titles": titles, "/api/launch": launch, "/api/steam": steam, "/api/volume": set_volume, "/api/clipboard": clipboard,
+    "/api/sources": source_manage, "/api/sources/install": source_install, "/api/android/display": android_display, "/api/android": android, "/api/quest": quest, "/api/meta": meta, "/api/queue": queue_action, "/api/titles": titles, "/api/launch": launch, "/api/steam": steam, "/api/volume": set_volume, "/api/clipboard": clipboard,
         "/api/flatpak": flatpak, "/api/open": open_thing, "/api/shots/save": save_shots,
         "/api/webinstall/check": webinstall_check, "/api/webinstall/start": webinstall_start,
         "/api/webinstall/cancel": webinstall_cancel,
@@ -2465,6 +2692,10 @@ class Handler(BaseHTTPRequestHandler):
                 apps = frame_android.list_apps()
                 backfill_art(apps=apps)
                 self.send_json({"apps": apps})
+            elif path == "/api/quest":
+                self.send_json(quest_status(url.query))
+            elif path == "/api/meta":
+                self.send_json(meta_status(url.query))
             elif path == "/api/titles":
                 ensure_master()
                 titles_list = frame_titles.list_titles()
@@ -2482,6 +2713,8 @@ class Handler(BaseHTTPRequestHandler):
                 self.send_json(_input.send([]) if parse_qs(url.query).get("start") == ["1"] else dict(_input.status))
             elif path == "/api/job":
                 self.send_json(job_status(url.query))
+            elif path == "/api/queue":
+                self.send_json(install_queue())
             elif path == "/api/android/displays":
                 self.send_json(android_displays())
             elif path == "/api/android/reports":