test(connection): align pill expectations with connection redesign

Store: repositories behind a login, and a GitHub token in source settings

.claude/skills/steam-frame/SKILL.md

@@ -22,7 +22,6 @@ desktop or panels.
 | See the Frame from the Mac, or the Mac inside the Frame | `docs/streaming.md` | `scripts/run-on-frame.sh mac-screen` |
 | Files and clipboard | `docs/file-transfer.md` | `scripts/push.sh`, `scripts/paste-to-frame.sh` |
 | Android apps (Lepton) | `docs/apks.md` | `scripts/install-apk.sh` |
-| Browse and install Android apps from inside the headset (APK Store panel) | `docs/apks.md` | `scripts/store-on-frame.sh` |
 | Reach the Frame off the home LAN (Tailscale) | `docs/tailscale.md` | `scripts/tailscale-on-frame.sh` |
 | Install or buy Steam games, Frame ratings | `docs/steam-games.md` | `ui/frame_steam.py` |
 | Flatpaks | `docs/streaming.md` | `scripts/install-apps.sh` |

.github/workflows/checks.yml

@@ -5,6 +5,11 @@ on:
     branches: [main]
   pull_request:
 
+# A newer push to the same pull request supersedes a run still in progress.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   checks:
     runs-on: ubuntu-latest
@@ -17,7 +22,9 @@ jobs:
         with:
           node-version: "24"
       - name: Install zsh
-        run: sudo apt-get update -qq && sudo apt-get install -y -qq zsh
+        # The runner image's third-party apt sources (packages.microsoft.com) sometimes
+        # fail to refresh; Ubuntu's own lists still update, and the install fails if not.
+        run: (sudo apt-get update -qq || true) && sudo apt-get install -y -qq zsh
       - name: Script syntax
         run: |
           sh -n ui/local-bin/ssh
@@ -36,8 +43,8 @@ jobs:
         run: python -m unittest discover -s tests -v
       - name: App syntax
         run: node --check app/main.js && node --check app/build/make-icon.js && node --check app/build/fetch-deps.js && node --check app/preload.js && node --check app/install-link.js && node --check app/updater.js
-      - name: App tests
-        run: node --test app/test/*.test.js
+      - name: Updater tests
+        run: node --test app/test/updater.test.js
       - name: Website
         run: node --test site/test/*.test.mjs && node --check site/public/js/site.js && node --check site/public/js/feedback.js
 
@@ -84,6 +91,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Install zsh
-        run: sudo apt-get update -qq && sudo apt-get install -y -qq zsh
+        # The runner image's third-party apt sources (packages.microsoft.com) sometimes
+        # fail to refresh; Ubuntu's own lists still update, and the install fails if not.
+        run: (sudo apt-get update -qq || true) && sudo apt-get install -y -qq zsh
       - name: End-to-end tests
         run: scripts/e2e.sh

.github/workflows/release.yml

@@ -2,14 +2,22 @@ name: release
 
 # Pushing a v* tag builds Frame Control for macOS, Windows and Linux and attaches
 # the installers to that tag's GitHub release (created as a draft if missing).
-# Pull requests that touch the app build the same installers as artifacts.
+# Pull requests that change how the installers are built (the Electron app, the
+# macOS helper it compiles, or this workflow) build the same installers as
+# artifacts. ui/, scripts/, frame/ and apk-catalog/ are copied in as they are and
+# are tested by the checks workflow; run this one by hand to package them early.
 on:
   push:
     tags: ["v*"]
   pull_request:
-    paths: ["app/**", "ui/**", "scripts/**", "frame/**", "apk-catalog/**", ".github/workflows/release.yml"]
+    paths: ["app/**", "mac/frame-mac-view/**", ".github/workflows/release.yml"]
   workflow_dispatch:
 
+# A newer push to the same pull request supersedes a build still in progress.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   contents: write
 
@@ -94,7 +102,9 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           gh release upload "${GITHUB_REF_NAME}" ${{ matrix.files }} --clobber
+      # Tagged builds are attached to the release above; only other builds need artifacts.
       - uses: actions/upload-artifact@v4
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
         with:
           name: frame-control-${{ matrix.os }}
           path: |

README.md

@@ -189,7 +189,7 @@ entry to `~/.ssh/config` and keys at `~/.ssh/id_ed25519_frame` and
 
 This is a first public test, so reports are really useful, especially from
 Windows and Linux. The quickest way is **Report a problem** in the app (the
-warning-sign button at the top, or **Help → Report a Problem…**). It adds
+speech-bubble button at the top, or **Help → Report a Problem…**). It adds
 diagnostics with personal details removed, shows you exactly what's included,
 and sends it privately to the maintainer; nothing is published. Without the app,
 use the [feedback form](https://frame-control.pages.dev/feedback/). Please include:
@@ -213,6 +213,8 @@ 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 |
@@ -222,7 +224,7 @@ Frame's software fits together, all checked against a real headset and labelled
 | [Frame Control for iPhone](docs/iphone.md) | The iPhone and iPad app, how it runs the server on the Frame, pairing |
 | [Recovery and OS images](docs/recovery-and-images.md) | Where to download the Frame's OS, what's inside, testing without the headset |
 | [AI agents and assistant](docs/agents.md) | Key-free MCP tools, human approvals, and an opt-in assistant panel |
-| [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, and the headset smoke test |
+| [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, the headset smoke test and a Windows test VM |
 | [Open questions](docs/open-questions.md) | What's still unchecked |
 
 <details>

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,7 +11,7 @@ const os = require("os");
 const path = require("path");
 const { SCHEME, parseInstallLink, linkFromArgv } = require("./install-link");
 const updater = require("./updater");
-const { preferenceStore } = require("./preferences");
+const { createMetaSignIn } = require("./meta-signin");
 
 const run = promisify(execFile);
 
@@ -28,7 +28,6 @@ const LOG_DIR = IS_MAC ? path.join(os.homedir(), "Library", "Logs", "Frame Contr
 const LOG = path.join(LOG_DIR, "server.log");
 const BG = "#0d1117";
 const FRAME = process.env.FRAME_ALIAS || "frame";
-const preferences = preferenceStore(path.join(app.getPath("userData"), "client-preferences.json"));
 
 let server = null;
 let url = null;
@@ -281,8 +280,6 @@ ipcMain.handle("server:restart", (e) => {
   if (win && e.sender === win.webContents && e.senderFrame && e.senderFrame.url.startsWith("data:")) restartServer();
 });
 ipcMain.handle("clipboard:read", (e) => fromUi(e) ? clipboard.readText() : "");
-ipcMain.handle("preferences:read", (e) => fromUi(e) ? preferences.read() : {});
-ipcMain.handle("preferences:write", (e, key, value) => fromUi(e) ? preferences.write(key, value) : false);
 // A PNG or JPEG (a screenshot) onto the clipboard as an image.
 ipcMain.handle("clipboard:writeImage", (e, bytes) => {
   if (!fromUi(e) || !(bytes instanceof Uint8Array)) return false;
@@ -352,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",
@@ -39,7 +39,7 @@
       "preload.js",
       "install-link.js",
       "updater.js",
-      "preferences.js",
+      "meta-signin.js",
       "package.json",
       "build/icon.png"
     ],

app/preferences.js

@@ -1,27 +0,0 @@
-// Client choices live outside the local server's changing URL/origin.
-const fs = require("node:fs");
-const path = require("node:path");
-const KEYS = ["mvSeparate", "padUsed"];
-const valid = value => value === "0" || value === "1";
-
-function preferenceStore(file) {
-  function read() {
-    try {
-      const saved = JSON.parse(fs.readFileSync(file, "utf8"));
-      if (!saved || typeof saved !== "object" || Array.isArray(saved)) return {};
-      return Object.fromEntries(KEYS.filter(key => valid(saved[key])).map(key => [key, saved[key]]));
-    } catch { return {}; }
-  }
-  function write(key, value) {
-    if (!KEYS.includes(key) || !valid(value)) throw new Error("Invalid preference");
-    const saved = { ...read(), [key]: value };
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const tmp = file + ".tmp";
-    fs.writeFileSync(tmp, JSON.stringify(saved), { mode: 0o600 });
-    fs.renameSync(tmp, file);
-    return true;
-  }
-  return { read, write };
-}
-
-module.exports = { preferenceStore };

app/preload.js

@@ -6,14 +6,11 @@
 // 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", {
-  preferences: {
-    read: () => ipcRenderer.invoke("preferences:read"),
-    write: (key, value) => ipcRenderer.invoke("preferences:write", key, value),
-  },
   notify: (message, request) => ipcRenderer.invoke("comfort:notify", message, request),
   readClipboard: () => ipcRenderer.invoke("clipboard:read"),
   writeImage: (bytes) => ipcRenderer.invoke("clipboard:writeImage", bytes),
@@ -43,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");
+});

app/test/preferences.test.js

@@ -1,60 +0,0 @@
-const test = require("node:test");
-const assert = require("node:assert/strict");
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-const { preferenceStore } = require("../preferences");
-
-function fixture(t) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "frame-preferences-"));
-  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
-  return path.join(dir, "client-preferences.json");
-}
-
-test("desktop packaging includes every local application module dependency", () => {
-  const root = path.resolve(__dirname, "..");
-  const packaged = new Set(require("../package.json").build.files);
-  for (const file of ["main.js", "preload.js"]) {
-    const source = fs.readFileSync(path.join(root, file), "utf8");
-    for (const match of source.matchAll(/require\(["'](\.\/[^"']+)["']\)/g)) {
-      const target = match[1].slice(2) + ".js";
-      assert.ok(packaged.has(target), `${file} needs packaged ${target}`);
-    }
-  }
-});
-
-test("client choices survive a new native session and local server origin", t => {
-  const file = fixture(t);
-  const first = preferenceStore(file);
-  assert.deepEqual(first.read(), {});
-  first.write("mvSeparate", "0");
-  first.write("padUsed", "1");
-  // A new process/session reads the same client store, regardless of its URL.
-  const second = preferenceStore(file);
-  assert.deepEqual(second.read(), { mvSeparate: "0", padUsed: "1" });
-  second.write("mvSeparate", "1");
-  assert.deepEqual(first.read(), { mvSeparate: "1", padUsed: "1" });
-});
-
-test("only the two non-sensitive binary choices can enter the native store", t => {
-  const file = fixture(t), store = preferenceStore(file);
-  for (const [key, value] of [["token", "secret"], ["__proto__", "1"], ["padUsed", true], ["mvSeparate", "yes"]]) {
-    assert.throws(() => store.write(key, value), /Invalid preference/);
-  }
-  assert.equal(fs.existsSync(file), false);
-  fs.writeFileSync(file, JSON.stringify({ token: "discard", mvSeparate: "0", padUsed: 1 }));
-  assert.deepEqual(store.read(), { mvSeparate: "0" });
-  store.write("padUsed", "1");
-  assert.deepEqual(JSON.parse(fs.readFileSync(file, "utf8")), { mvSeparate: "0", padUsed: "1" });
-});
-
-test("a missing or damaged preference file retains usable defaults", t => {
-  const file = fixture(t), store = preferenceStore(file);
-  assert.deepEqual(store.read(), {});
-  for (const bad of ["{broken", "null", "[]", '"text"']) {
-    fs.writeFileSync(file, bad);
-    assert.deepEqual(store.read(), {});
-  }
-  store.write("padUsed", "1");
-  assert.deepEqual(store.read(), { padUsed: "1" });
-});

docs/apk-repos.md

@@ -58,8 +58,61 @@ form shows the pinned one ("Trusted on first use: …") so you can compare it.
 Re-adding an existing URL preserves its pin; changing it requires deliberately
 removing and re-adding it.
 
+### Repositories behind a login
+
+Some self-hosted repositories sit behind HTTP basic auth. As in F-Droid's own
+client, the login can be part of the address
+(`https://user:pass@example.org/fdroid/repo`), or given separately: in the
+store's **Add a source** form under "This repository needs a login", in the
+server API (`username` and `password` beside `url`), or on the command line,
+where the password is read from standard input so it stays out of shell history
+and `ps`:
+
+```sh
+printf '%s\n' "$PASSWORD" | python3 ui/apk_sources/fdroid.py add 'https://example.org/fdroid/repo' --username me --password-stdin
+```
+
+How the login is kept and used:
+
+- **Kept out of the address.** The `user:pass@` part is removed before anything
+  is saved, so the saved repository URL, its id, the source list, job results
+  and the page never contain it. The store only says "Uses a login".
+- **Stored separately.** Logins live in
+  `frame_host.data_dir('source-credentials.json')`
+  (`~/Library/Application Support/Frame Control/source-credentials.json` on
+  macOS), written with mode 0600 and keyed by source id. They are stored in
+  plain text there, protected by file permissions only (on Windows,
+  the folder's normal ACLs). Removing the repository deletes its login, and
+  the file goes when the last login is removed. Each change holds a lock
+  file (`source-credentials.lock`), so the app and the command line can't undo
+  each other's saves or removals.
+- **HTTPS only.** An `http://` address with a login is refused before any request.
+- **Inside the repository only.** The `Authorization` header is decided
+  separately for every request, redirects included: index, `entry.jar`,
+  APKs and the store's artwork proxy. It is sent only when the request's
+  scheme, host and port match the repository's and its path is inside the
+  repository's directory by whole path segments. A redirect to another host
+  or port, or to another path on the same server, gets no login, and that
+  request's own `Authorization` header is removed. Paths with `.` or `..`
+  segments (plain or percent-encoded), encoded `/` or `\`, double encoding
+  or `;` get no login, since a server could normalise them to a path
+  outside the repository. Index file names like that are refused outright.
+- **Never echoed.** Logins are not written to logs, error messages, API
+  responses or the cache. The CLI prints only the saved source.
+- **Checked before saving.** As with any repository, the whole index must
+  download and verify before anything is saved. HTTP 401 (or 403 when a login
+  was sent) stops the add with "check the username and password" and saves
+  nothing: no repository, no login, no rollback state. A 403 with a login is
+  not treated as rate limiting.
+- **Same verification.** The login changes only who may download. Signature,
+  fingerprint pin or TOFU, index hash and rollback checks apply exactly as for
+  any other repository.
+
+Re-adding the same address with a new login replaces the saved one. Re-adding
+it without a login keeps the saved one.
+
 The API for the search/server integration is in `ui/apk_sources/fdroid.py`:
-`add_repo(url, fingerprint=None, name=None)`, `remove_repo(source_id)`,
+`add_repo(url, fingerprint=None, name=None, username=None, password=None)`, `remove_repo(source_id)`,
 `set_enabled(source_id, enabled)`, and `user_repos()`. The module also exposes
 `sources`, `search`, `details`, and `download` from the shared source contract.
 This change supplies the CLI and API; the integrated source-management UI is

docs/apk-sources.md

@@ -45,10 +45,23 @@ search. Results outside the curated list stay page-only, even if a repository
 claims an open-source license. This prevents an arbitrary tagged mirror from
 becoming a trusted downloader. Extend the curated JSON after provenance review.
 
-Set optional `FRAME_GITHUB_TOKEN` in the process environment for a higher API
-quota. Tokens are sent only to `api.github.com`, never written to the cache,
-never sent to asset hosts, and removed on redirects. The adapter does not
-read `gh` credentials automatically. Metadata is cached for one hour under
+For a higher API quota, add a GitHub access token in the store's source
+settings (the GitHub row's token field) or through the server API
+(`POST /api/sources` with `action: "set-token"` or `"clear-token"` and
+`source: "github"`). `FRAME_GITHUB_TOKEN` in the process environment still
+works and wins over a saved token. A saved token is kept with repository
+logins in `source-credentials.json` (mode 0600, see
+[APK repositories](apk-repos.md#repositories-behind-a-login)). The source list
+reports only whether a token is set, where it came from and whether GitHub
+rejected it, never its value. Tokens are sent as `Authorization: Bearer` only to
+`api.github.com`, never written to the cache, never sent to asset hosts (public
+release downloads don't need them), and removed on redirects. If GitHub answers
+401 to the token, the request is retried once without it, as Obtainium does.
+The rejection is logged without the token and shown in source settings. The
+token is not tried again until it is saved again or the app restarts. Rate-limit
+backoff is kept per login (anonymous, or each token), so saving a token after
+anonymous requests were limited lets the next request go out with it. The
+adapter does not read `gh` credentials automatically. Metadata is cached for one hour under
 `frame_host.cache_dir('apk-sources', 'publisher')`. A cold details request
 fetches at most ten releases. Rate-limit errors are surfaced without retry
 loops. Asset IDs and release tags are not Android version codes: metadata

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.
@@ -177,63 +183,6 @@ See
 [compat-db/README.md](../compat-db/README.md) and
 [apk-catalog/README.md](../apk-catalog/README.md).
 
-## Store and Library in Frame Control
-
-The Android tab has two views. **Store** finds apps across the sources (F-Droid,
-IzzyOnDroid, curated GitHub releases, itch.io). **Library** shows the apps on the
-Frame as cards, with Play and a menu for Test, Report and Remove; the display
-settings and recent reports are below it.
-
-The store groups apps by what a headset is good for, not by F-Droid's list:
-VR, Games, Emulators, Watch & listen, Read & learn, Create, Work, Web & chat
-and Tools (`ui/apk_sources/_categories.py`). A VR app is always in VR. Otherwise
-F-Droid's own categories decide, the finer one first (an app in *Multimedia* and
-*Social Network* is Web & chat).
-
-Apps built around a phone are hidden from browsing unless **Show phone-only
-apps** is on; a search always finds them, labelled *Phone app*. Hidden: apps in
-a category that only makes sense in a phone's own system (launchers, keyboards,
-wallpapers, Xposed modules), apps in a phone-side category (calls and SMS, VPNs,
-fitness, alarms, system tools) unless a useful category says otherwise
-(FluffyChat is in Phone & SMS, but it's a messenger), apps named for a phone
-part (a widget, a launcher, a battery tool), and apps that need hardware the
-Frame lacks (an IR blaster, a watch, NFC, root). They would install and run in
-Lepton, but do nothing useful on the Frame. In the October 2026 indexes that is
-about 1,600 of F-Droid's 4,500 apps and 550 of IzzyOnDroid's 1,300.
-
-Without a search, each source offers its best 300 for the chosen category:
-apps with a banner first, then with screenshots, then the newest.
-
-## The store in the headset: Frame Control's store as a panel (inferred, not yet run on the Frame)
-
-The **APK Store** panel is the Store above, drawn for the laser: the same
-sources, categories and artwork, with Install, Open, Stop and Remove, opened as
-its own floating panel:
-
-```sh
-scripts/store-on-frame.sh open     # copy the server over if it changed, start it, open the panel
-scripts/store-on-frame.sh close
-```
-
-`open` copies the same bundle the iPhone app uses
-(`ios/scripts/make_frame_bundle.py`) to
-`~/.local/share/frame-control/store-server/<version>` on the Frame. It then
-starts `ui/server.py` there with `FRAME_LOCAL=1` on `127.0.0.1:47812`, with a
-fresh `X-Frame-UI` key. Chromium XR (or the `org.chromium.Chromium` Flatpak)
-opens `/store` (`ui/store.html`) in a 1280×800 app window, tagged as panel
-`2001947812` ([panels.md](panels.md)). Downloads, SHA-256 checks and installs
-all run on the Frame, so the Mac can go away after `open`.
-
-The page has a category rail (Home, the store's categories, Installed), eight
-art cards a page, and a featured VR app on Home. It turns pages instead of
-scrolling, because a tagged panel gets mouse clicks and a drag would select
-text; the thumbstick (a mouse wheel) turns pages, and an on-screen keyboard is
-there for search. **Checked on the Mac only** (2026-10-14, 1280×800, against
-the real sources): Home, categories, Installed, the detail sheet. **Still to
-check in the headset:** that the panel opens and takes laser clicks, that an
-install completes when run on the Frame, and that **Open** brings up the app's
-panel.
-
 ## In-headset app store: F-Droid 1.17 (verified 2026-09-25)
 
 F-Droid 1.23 uses an old Compose and crashes on launch. **F-Droid 1.17.2**, the

docs/devices.md

@@ -3,8 +3,9 @@
 Frame Control can manage more than one Steam Frame, and each headset can be
 reached at more than one address: a LAN IP at home, another at the office, its
 mDNS name (`frame.local`), its Tailscale IP or MagicDNS name. The **Devices**
-tab (key 5) lists them, and the connection pill in the header shows what the
-app is doing to reach the one in use, step by step, as it happens.
+tab (key 5) lists them. The connection pill in the header says whether the one in
+use is connected and how (Tailscale, or the network's name); click it to add,
+edit or reorder that headset's addresses, or to see each step of connecting.
 
 The code is in three modules, all stdlib-only Python on your computer:
 
@@ -57,7 +58,7 @@ and ranks them:
 5. addresses that only ever worked on other networks;
 6. Tailscale addresses while Tailscale is off.
 
-Your order on the Devices tab breaks ties. The best-ranked address that answers
+Your order (on the Devices tab, or in the pill's dialog) breaks ties. The best-ranked address that answers
 wins; one that answers first waits up to 0.35 s for a better-ranked one that is
 still trying. If SSH to the winner fails in a way another address could fix
 (a different device answered there, or the link dropped), the next one that
@@ -72,6 +73,16 @@ status --json`, including the Mac app's own CLI) with buttons to add their
 MagicDNS name or IP. **Find on this network** asks mDNS for SteamOS devkit
 services and checks `ALIAS.local` and `frame.local`.
 
+**The pill's dialog** lists the same addresses, with what each one answered, and
+can add, edit, reorder and remove them without leaving the page you're on. When
+the headset reports a LAN IP on the same network as this computer and that IP
+isn't saved, it offers to add it. The offer puts the address first in the list,
+so on that network it wins over the Tailscale name; away from home the Tailscale
+name still leads. A new or edited address is tested straight away. While
+connected, **Reconnect** applies your changes now rather than at the next
+connection: it tries the addresses again, ranked as above, and the best-ranked
+one that answers promptly wins. It doesn't pick a particular address.
+
 ## Networks
 
 A network is told apart by its default gateway: the router's IP address plus its

docs/frame-control.md

@@ -23,9 +23,9 @@ the catalogue, display settings, reports), **Tools** (sending files and text,
 Flatpaks, remote and power), **Devices** (your headsets and their addresses),
 and **Control** (the searchable Control Center, metrics, supported settings and
 headset guidance). Keys 1–6 switch between them. Files can be dropped anywhere in the window. A
-connection pill in the header always shows which headset, which network this
-computer is on, the address in use or being tried, and each step of connecting
-as it happens; click it for the whole timeline. When the Frame can't be
+connection pill in the header always shows which headset and whether it's
+connected, and how (Tailscale, or the network's name). Click it to add, edit or
+reorder the headset's addresses, or to see each step of connecting. When the Frame can't be
 reached, a banner says why in plain words, what was tried, and counts down to
 the next try, filling everything in once it answers. Flatpak and Android installs run in the background; the bottom bar
 counts them while they run.
@@ -133,7 +133,7 @@ rejects invalid types, out-of-range levels and invalid mute states before SSH.
 Other settings link to the existing forms and their validation, progress,
 confirmations and reset behavior: per-instance Android resolution/density/text,
 comfort sessions and alerts, media layouts, Mac streaming quality, privacy,
-sources and artwork. Android display links reveal the **Library** before
+sources and artwork. Android display links reveal **On your Frame** before
 scrolling to the form. Mac streaming remains searchable on all platforms, with
 its action shown only when the server is on macOS.
 

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/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.
@@ -124,7 +132,7 @@ runs.
 
 ## Report a problem
 
-**Report a problem** is the warning-sign button in the header, also in the
+**Report a problem** is the speech-bubble button in the header, also in the
 Privacy panel and under **Help → Report a Problem…**. It sends the report
 privately to Frame Control's PostHog project as a `problem_report` event, the
 same way as the analytics above, so only the maintainer can read it and

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/scripts.md

@@ -89,7 +89,6 @@ controls to place each panel. See [docs/panels.md](panels.md).
 | Script | Runs on | Purpose |
 |---|---|---|
 | `scripts/tailscale-on-frame.sh` | Mac → Frame | Install Tailscale in `~` as a userspace user service so `frame` works from anywhere; `--uninstall` (**verified** on the LAN) |
-| `scripts/store-on-frame.sh` | Mac → Frame | Open the APK Store (Frame Control's Android store) as a panel in the headset; installs run on the Frame (**inferred**; see [docs/apks.md](apks.md)) |
 | `scripts/connect.sh` | Mac | Discover, set up key and `~/.ssh/config`, copy key, optional `--harden` (**verified**; `--harden` untested) |
 | `scripts/install-apps.sh` | Mac → Frame | Install Flatpaks (Remmina, Moonlight, …) on the Frame over SSH as `--user` (**verified** with Remmina) |
 | `scripts/paste-to-frame.sh` | Mac → Frame | Send the Mac clipboard (or stdin) to the Frame clipboard (**verified**) |

docs/streaming.md

@@ -21,6 +21,20 @@ The confidence labels are the same as in [ssh.md](ssh.md).
 | **ADB + scrcpy (Lepton only)** | A mirror of the Android container | **Guess** | `brew install scrcpy android-platform-tools`, then `adb connect frame.local:5555` while Lepton Development is running ([adb_lepton](https://partner.steamgames.com/doc/steamhardware/steamframe/adb_lepton)), then `scrcpy`. This only shows Android apps, not SteamOS. |
 | VNC server on the Frame (krfb / wayvnc) | A mirror of the Plasma desktop | **Inferred (SteamOS)** | Deck users run krfb in Desktop Mode ([one.vg](https://one.vg/blog/remote-control-your-steam-deck)). On the Frame, the in-headset desktop is a virtual screen, and krfb isn't known to be preinstalled. RDP and Steam Link cover this case, so it's not recommended. |
 
+**RDP from Windows, verified 2026-09-30:** Windows 11 25H2's Remote Desktop
+(`mstsc`) against BUILD_ID 20260925.6191901. xrdp picks TLS, not NLA, so
+Remote Desktop never asks for a user or password. It warns that the certificate
+(`www.xrdp.org`) can't be verified. After **Yes**, xrdp shows its own "Login to
+frame" box with the username blank. Any user but `steamos` gets "User does not
+exist, or could not be authenticated". Signing in as `steamos` with the
+Developer Mode password opens a Plasma (X11) desktop within about 6 seconds.
+It's a new session on display `:10`, separate from what the headset shows,
+and it uses about 1.3 GB of the Frame's memory. Closing Remote Desktop leaves
+it running, and the next sign-in reconnects to it. To end it, find its
+session with `loginctl list-sessions` over SSH (its leader is `xrdp-sesexec`)
+and run `loginctl terminate-session <id>`; the headset's own session keeps
+running.
+
 **Recommendation for A:** start with Steam Link for macOS, because Valve
 documents it. Use Windows App (RDP) when you want a proper Linux desktop on the
 Mac with keyboard, mouse, and clipboard.

docs/testing.md

@@ -8,6 +8,7 @@ A fourth, a SteamOS VM, may come later ([issue #6](https://github.com/saphid/ste
 | Unit tests (`tests/*.py`) | `python3 -m unittest discover -s tests` | Nothing | Parsing, validation, request guards; SSH and HTTP are mocked |
 | Fake Frame (`tests/e2e`) | `scripts/e2e.sh` | Linux with Docker | The real server and scripts against a container that behaves like a Frame |
 | Headset smoke test | `scripts/frame-smoke.sh` | A Frame on the `frame` alias | Install, launch and remove on the real device, recorded with its BUILD_ID |
+| [Windows test VM](#windows-test-vm) | `scripts/windows-vm.sh` | A Linux machine with KVM and Docker | The Windows build on a real Windows desktop, against a real Frame when needed |
 
 ## Unit tests
 
@@ -186,6 +187,86 @@ 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.
 
+## Windows test VM
+
+The unit tests run on Windows in CI, but the app itself doesn't. Anything that
+depends on the Windows desktop (Remote Desktop, the installer, the bundled
+Python, file dialogs) needs a real Windows machine. This is a Windows 11 VM in a
+[dockur/windows](https://github.com/dockur/windows) container on a Linux machine
+with KVM, driven from the Mac with `scripts/windows-vm.sh`.
+
+Setting it up, once, on the Linux machine:
+
+- **Windows comes from Microsoft.** The container downloads the Windows 11
+  image from Microsoft on first start. Windows runs unactivated, which is fine
+  for testing. Don't use activation workarounds or third-party Windows images.
+- **Publish its ports on loopback only.** Map `127.0.0.1:2222:22` (SSH),
+  `127.0.0.1:8006:8006` (the web console) and, if you need it,
+  `127.0.0.1:13389:3389`. The Mac reaches them through `ssh -J`. Use
+  `restart: "no"` and `stop_grace_period: 2m` so it only runs when someone is
+  testing, and a `docker stop` shuts Windows down cleanly.
+- **Give it SSH on first sign-in.** The container runs `/oem/install.bat`
+  once. Have it add the OpenSSH Server capability, start `sshd`, set PowerShell
+  as its default shell, and put a dedicated public key (for example
+  `~/.ssh/id_ed25519_winvm` on the Mac) in
+  `C:\ProgramData\ssh\administrators_authorized_keys`.
+- Give it 4 cores, 8 GB of memory and a 32 GB disk. That's enough for the app
+  and the tests.
+
+Using it, with `WINVM_HOST` set to the Linux machine's ssh alias:
+
+```sh
+scripts/windows-vm.sh up                        # start it and wait for SSH (1-2 minutes)
+scripts/windows-vm.sh put Frame-Control-Setup-x64.exe
+scripts/windows-vm.sh ps 'Start-Process "$env:USERPROFILE\Downloads\Frame-Control-Setup-x64.exe" /S -Wait'
+scripts/windows-vm.sh shot screen.png            # what's on its screen
+scripts/windows-vm.sh click 723 359              # screen pixels, as in the screenshot
+scripts/windows-vm.sh keys s t e a m o s ret     # QEMU key names
+scripts/windows-vm.sh down                       # shut Windows down
+```
+
+- **Clicks go through a scheduled task.** Commands over SSH run in a
+  session with no desktop, so `click` and `scroll` write the position to a
+  file, and a scheduled task running as the signed-in user replays it. The
+  VM's screen must be signed in; it is after `up`. Clicks and scrolls sent at
+  the same time run one after another. QEMU's own `mouse_move` is relative
+  and drifts, so the script doesn't use it.
+- **Screenshots may not show the pointer.** Check the result of a click (a
+  menu that opens, a button that changes) rather than the pointer's position.
+- **Windows' `ssh` waits for stdin.** The script closes it for every command.
+  Do the same if you run `ssh` in the VM by hand.
+- **Starting the app.** Run Frame Control in the signed-in session, not over
+  SSH. Use its Start-menu shortcut via `click`, or a scheduled task like the
+  one `click` uses.
+
+**Testing against a real Frame.** The VM reaches the headset on the LAN like
+any other computer. Run **Set Up Connection** in the VM's Frame Control once;
+that makes the VM's keys. So the VM doesn't keep access between test runs,
+afterwards take the lines it added out of the headset's
+`~/.ssh/authorized_keys`: the ones matching the VM's
+`~/.ssh/id_ed25519_frame.pub` and, if pairing made one,
+`~/.ssh/id_rsa_frame_devkit.pub`. Check that `ssh -o BatchMode=yes frame true`
+in the VM now fails. Then, around each run:
+
+```sh
+scripts/windows-vm.sh frame-key add       # let the VM's key into the headset
+# ... test ...
+scripts/windows-vm.sh frame-key remove    # and take it out again
+```
+
+`add` appends the VM's key tagged `windows-vm-test`, unless the headset
+already trusts that key through another line. `remove` deletes only the exact
+line `add` wrote, so it doesn't undo what Set Up Connection did, and it leaves
+the file alone if it can't rewrite it. Follow the shared-device
+procedure in [Headset smoke test](#headset-smoke-test) before installing or
+launching anything on the headset.
+
+**Verified 2026-09-30:** Windows 11 Pro 25H2 (build 26200) against a Frame on
+BUILD_ID 20260925.6191901. The script was used to install Frame Control 0.4.0,
+connect it to the Frame and follow Remote Desktop through to the Frame's
+desktop ([what it does](streaming.md#a-see-and-control-the-frame-from-the-mac)).
+`frame-key` left `authorized_keys` byte-for-byte as it was.
+
 ## 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
 

docs/vr-utilities.md

@@ -26,7 +26,7 @@ it twice reuses the existing process.
 | Compositor CPU | OpenVR compositor render CPU milliseconds, not game CPU time. |
 | System CPU | `/proc/stat` busy-time delta across the sample, with guest time counted once and iowait treated as idle. |
 | GPU clock | `3d00000.gpu/cur_freq`, converted from Hz to MHz; frequency is not load. |
-| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. |
+| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. In the headset HUD only: the app shows them once, in the battery menu at the top. |
 
 OpenVR uses background application mode, which does not start SteamVR or keep
 it running. This mode also returned live timing in a read-only device probe.

ios/FrameControl.xcodeproj/project.pbxproj

@@ -7,8 +7,6 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		C1234567890ABCDEF0123456 /* NativeSessionTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = D1234567890ABCDEF0123456 /* NativeSessionTests.swift */; };
-		A1234567890ABCDEF0123456 /* NativeSessionState.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1234567890ABCDEF0123456 /* NativeSessionState.swift */; };
 		0DEE50BD563B1D8C328C4C0A /* HeadsetServer.swift in Sources */ = {isa = PBXBuildFile; fileRef = EDC7BA8014DBC302D08FD397 /* HeadsetServer.swift */; };
 		12B21D3319BAF5AE79948560 /* FrameLink.swift in Sources */ = {isa = PBXBuildFile; fileRef = 16644E7FDA7ADD5B232EB700 /* FrameLink.swift */; };
 		1A07EC692B0FF723907EA77B /* WebShell.swift in Sources */ = {isa = PBXBuildFile; fileRef = D6C4E6C28315CA8729FCAAEA /* WebShell.swift */; };
@@ -37,8 +35,6 @@
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXFileReference section */
-		D1234567890ABCDEF0123456 /* NativeSessionTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativeSessionTests.swift; sourceTree = "<group>"; };
-		B1234567890ABCDEF0123456 /* NativeSessionState.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativeSessionState.swift; sourceTree = "<group>"; };
 		16644E7FDA7ADD5B232EB700 /* FrameLink.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FrameLink.swift; sourceTree = "<group>"; };
 		1740B691F9C25E5FB6F9EFC3 /* FrameControlTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FrameControlTests.swift; sourceTree = "<group>"; };
 		237D9AF04EEA257AB382F60E /* Keys.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Keys.swift; sourceTree = "<group>"; };
@@ -104,7 +100,6 @@
 			isa = PBXGroup;
 			children = (
 				8A11F3431826A26B247C0695 /* AppModel.swift */,
-				B1234567890ABCDEF0123456 /* NativeSessionState.swift */,
 				93C8E0D7C3F4F628941B3D5A /* FrameControlApp.swift */,
 				BF0FCA7117DA3ABA449B4EE0 /* InstallLink.swift */,
 			);
@@ -116,7 +111,6 @@
 			children = (
 				E81218B75FEEE47B8D8BAE20 /* ComfortNotificationTests.swift */,
 				1740B691F9C25E5FB6F9EFC3 /* FrameControlTests.swift */,
-				D1234567890ABCDEF0123456 /* NativeSessionTests.swift */,
 			);
 			path = FrameControlTests;
 			sourceTree = "<group>";
@@ -266,7 +260,6 @@
 			buildActionMask = 2147483647;
 			files = (
 				F94D0252F8CC5854314B84B2 /* AppModel.swift in Sources */,
-				A1234567890ABCDEF0123456 /* NativeSessionState.swift in Sources */,
 				78427FC66780623F31E7501E /* FrameControlApp.swift in Sources */,
 				E6898C714A92D3979F73B6E1 /* FrameFinder.swift in Sources */,
 				12B21D3319BAF5AE79948560 /* FrameLink.swift in Sources */,
@@ -286,7 +279,6 @@
 			files = (
 				A0C5B00E257230A38DBD9E54 /* ComfortNotificationTests.swift in Sources */,
 				DC043FB74BE2D23F3A5826BF /* FrameControlTests.swift in Sources */,
-				C1234567890ABCDEF0123456 /* NativeSessionTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

ios/FrameControl/App/AppModel.swift

@@ -19,20 +19,6 @@ final class AppModel: ObservableObject {
     /// Install links that arrived before the page was ready for them.
     @Published var pendingInstallLinks: [InstallLink] = []
 
-    /// Native recovery remains reachable even when WebKit cannot draw a page.
-    @Published private(set) var webRecoveryMessage: String?
-    @Published private(set) var webReloadID = 0
-
-    func webContentFailed(at url: URL, message: String) {
-        guard phase == .ready(url) else { return }
-        webRecoveryMessage = message
-    }
-
-    func retryWebContent() {
-        webRecoveryMessage = nil
-        webReloadID += 1
-    }
-
     private var link: FrameLink?
     private var server: HeadsetServer?
     private var forwarder: PortForwarder?
@@ -113,7 +99,18 @@ final class AppModel: ObservableObject {
 
     /// "host", "host:port" or "[v6]:port", plus a user name.
     nonisolated static func parse(host: String, user: String) -> FrameSettings? {
-        FrameSettings.parse(host: host, user: user)
+        var target = FrameSettings(host: host.trimmingCharacters(in: .whitespaces), user: user.trimmingCharacters(in: .whitespaces))
+        if target.host.hasPrefix("["), let close = target.host.firstIndex(of: "]") {
+            let rest = target.host[target.host.index(after: close)...]
+            if rest.hasPrefix(":"), let port = Int(rest.dropFirst()) { target.port = port }
+            target.host = String(target.host[target.host.index(after: target.host.startIndex)..<close])
+        } else if target.host.filter({ $0 == ":" }).count == 1, let colon = target.host.lastIndex(of: ":"),
+                  let port = Int(target.host[target.host.index(after: colon)...]) {
+            target.port = port
+            target.host = String(target.host[..<colon])
+        }
+        guard !target.host.isEmpty, !target.user.isEmpty, (1...65535).contains(target.port) else { return nil }
+        return target
     }
 
     /// This phone's line for ~/.ssh/authorized_keys on the Frame.
@@ -148,7 +145,6 @@ final class AppModel: ObservableObject {
     private func invalidate() {
         attempt += 1
         retrying = false
-        webRecoveryMessage = nil
     }
 
     /// quiet: a background retry, which leaves the failure screen up until it works.

ios/FrameControl/App/NativeSessionState.swift

@@ -1,142 +0,0 @@
-import Foundation
-
-/// The persisted SSH target and its editable, lossless address form.
-struct FrameSettings: Codable, Equatable {
-    var host: String
-    var port: Int = 22
-    var user: String = "steamos"
-
-    var address: String {
-        let name = host.contains(":") ? "[\(host)]" : host
-        return port == 22 ? name : "\(name):\(port)"
-    }
-
-    static func parse(host: String, user: String) -> FrameSettings? {
-        var host = host.trimmingCharacters(in: .whitespacesAndNewlines)
-        let user = user.trimmingCharacters(in: .whitespacesAndNewlines)
-        var port = 22
-        if host.hasPrefix("[") {
-            guard let close = host.firstIndex(of: "]") else { return nil }
-            let rest = host[host.index(after: close)...]
-            if !rest.isEmpty {
-                guard rest.hasPrefix(":"), let value = Int(rest.dropFirst()) else { return nil }
-                port = value
-            }
-            host = String(host[host.index(after: host.startIndex)..<close])
-        } else if host.filter({ $0 == ":" }).count == 1, let colon = host.lastIndex(of: ":") {
-            guard let value = Int(host[host.index(after: colon)...]) else { return nil }
-            port = value
-            host = String(host[..<colon])
-        }
-        guard !host.isEmpty, !user.isEmpty, (1...65535).contains(port) else { return nil }
-        return FrameSettings(host: host, port: port, user: user)
-    }
-}
-
-/// Each search owns its callbacks. Cancelling invalidates even probes that cannot
-/// be cancelled while Network.framework finishes opening a connection.
-struct FrameSearchState {
-    private(set) var generation = UUID()
-    private(set) var manualAddress: String?
-
-    mutating func start(manualAddress: String?) -> UUID {
-        generation = UUID()
-        let typed = manualAddress?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        self.manualAddress = typed.isEmpty ? nil : typed
-        return generation
-    }
-
-    mutating func stop() { generation = UUID() }
-    func accepts(_ generation: UUID) -> Bool { self.generation == generation }
-    var discovers: Bool { manualAddress == nil }
-
-    static func address(manual: String, discovered: String?) -> String {
-        let typed = manual.trimmingCharacters(in: .whitespacesAndNewlines)
-        return typed.isEmpty ? (discovered ?? "frame.local") : typed
-    }
-}
-
-/// One automatic recovery per session; only a deliberate retry or a new session
-/// replenishes it. A successful load alone must not create a process-crash loop.
-struct WebDocumentState {
-    struct Delivery: Equatable {
-        let generation: UUID
-        let documentID: String
-    }
-
-    private(set) var generation = UUID()
-    private(set) var documentID: String?
-    private(set) var delivering = false
-    private var reloads = 0
-
-    mutating func beginDocument() {
-        generation = UUID()
-        documentID = nil
-        delivering = false
-    }
-
-    mutating func resetSession() {
-        reloads = 0
-        beginDocument()
-    }
-
-    mutating func shouldReloadAfterFailure() -> Bool {
-        beginDocument()
-        guard reloads < 1 else { return false }
-        reloads += 1
-        return true
-    }
-
-    mutating func ready(_ id: String, generation: UUID) {
-        guard self.generation == generation else { return }
-        documentID = id
-    }
-
-    mutating func beginDelivery() -> Delivery? {
-        guard !delivering, let documentID else { return nil }
-        delivering = true
-        return Delivery(generation: generation, documentID: documentID)
-    }
-
-    /// Only acknowledgement from the same live document may consume a link.
-    mutating func finishDelivery(_ delivery: Delivery, acknowledged: Bool) -> Bool {
-        guard delivery.generation == generation, delivering, delivery.documentID == documentID else { return false }
-        delivering = false
-        if !acknowledged { documentID = nil }
-        return acknowledged
-    }
-}
-
-/// Small app-scoped preferences survive the tunnel's intentionally ephemeral port.
-struct FramePreferences {
-    private let defaults: UserDefaults
-    private static let keys = ["mvSeparate", "padUsed"]
-    private static let prefix = "frame.control.preference."
-
-    init(defaults: UserDefaults = .standard) { self.defaults = defaults }
-
-    func read() -> [String: String] {
-        var result: [String: String] = [:]
-        for key in Self.keys {
-            if let value = defaults.object(forKey: Self.prefix + key) as? String, ["0", "1"].contains(value) {
-                result[key] = value
-            }
-        }
-        return result
-    }
-
-    @discardableResult
-    func write(key: String, value: String) -> Bool {
-        guard Self.keys.contains(key), ["0", "1"].contains(value) else { return false }
-        defaults.set(value, forKey: Self.prefix + key)
-        return true
-    }
-}
-
-/// True for the first caller only.
-final class Once: @unchecked Sendable {
-    private let lock = NSLock()
-    private var done = false
-    func claim() -> Bool { lock.withLock { defer { done = true }; return !done } }
-}
-

ios/FrameControl/SSH/FrameFinder.swift

@@ -1,4 +1,3 @@
-import Combine
 import Foundation
 import Network
 
@@ -19,30 +18,20 @@ final class FrameFinder: ObservableObject {
 
     private var browser: NWBrowser?
     private var probeTask: Task<Void, Never>?
-    private var search = FrameSearchState()
-    private let probe: @Sendable (String) async -> Bool
-    private let discoveryEnabled: Bool
+    private var fallback = "frame.local"
 
-    init(probe: @escaping @Sendable (String) async -> Bool = { await FrameFinder.sshAnswers(host: $0) },
-         discoveryEnabled: Bool = true) {
-        self.probe = probe
-        self.discoveryEnabled = discoveryEnabled
-    }
-
-    func start(fallback: String?, manual: Bool = false) {
+    func start(fallback: String?) {
         stop()
-        let mine = search.start(manualAddress: manual ? fallback : nil)
-        let host = FrameSearchState.address(manual: search.manualAddress ?? "", discovered: fallback)
+        self.fallback = (fallback?.isEmpty == false ? fallback : nil) ?? "frame.local"
         found = nil
         since = Date()
-        if search.discovers && discoveryEnabled { browse(generation: mine) }
+        browse()
         probeTask = Task { [weak self] in
             while !Task.isCancelled {
-                guard let self, self.search.accepts(mine) else { return }
-                if self.found == nil {
-                    let answers = await self.probe(host)
-                    guard !Task.isCancelled, self.search.accepts(mine) else { return }
-                    if answers, self.found == nil { self.found = Found(host: host, name: host) }
+                guard let self else { return }
+                let host = self.fallback
+                if self.found == nil, await Self.sshAnswers(host: host) {
+                    self.found = Found(host: host, name: host)
                 }
                 try? await Task.sleep(nanoseconds: 3_000_000_000)
             }
@@ -50,21 +39,20 @@ final class FrameFinder: ObservableObject {
     }
 
     func stop() {
-        search.stop()
         browser?.cancel()
         browser = nil
         probeTask?.cancel()
         probeTask = nil
     }
 
-    private func browse(generation: UUID) {
+    private func browse() {
         let browser = NWBrowser(for: .bonjour(type: "_steamos-devkit._tcp", domain: nil), using: .tcp)
         browser.browseResultsChangedHandler = { [weak self] results, _ in
             for result in results {
                 guard case let .service(name, _, _, _) = result.endpoint else { continue }
                 Self.resolve(result.endpoint) { host in
                     Task { @MainActor in
-                        guard let self, self.search.accepts(generation), self.search.discovers, let host else { return }
+                        guard let self, let host else { return }
                         // A found device is used over the fallback probe.
                         self.found = Found(host: host, name: name)
                     }
@@ -103,8 +91,12 @@ final class FrameFinder: ObservableObject {
 
     /// Whether something answers on the SSH port of "host" or "host:port" within a few seconds.
     nonisolated static func sshAnswers(host address: String) async -> Bool {
-        guard let target = FrameSettings.parse(host: address, user: "steamos") else { return false }
-        return await sshAnswers(host: target.host, port: UInt16(target.port))
+        var host = address, port: UInt16 = 22
+        if let target = AppModel.parse(host: address, user: "steamos") {
+            host = target.host
+            port = UInt16(target.port)
+        }
+        return await sshAnswers(host: host, port: port)
     }
 
     nonisolated static func sshAnswers(host: String, port: UInt16) async -> Bool {

ios/FrameControl/SSH/FrameLink.swift

@@ -4,6 +4,13 @@ import Foundation
 import NIOCore
 import NIOSSH
 
+/// Where the Frame is and who to log in as.
+struct FrameSettings: Codable, Equatable {
+    var host: String
+    var port: Int = 22
+    var user: String = "steamos"
+}
+
 struct FrameFailure: LocalizedError {
     let message: String
     /// Retrying can't help: the Frame's identity changed, or it refused this phone's login.
@@ -133,6 +140,12 @@ final class FrameLink: @unchecked Sendable {
     }
 }
 
+/// True for the first caller only.
+final class Once: @unchecked Sendable {
+    private let lock = NSLock()
+    private var done = false
+    func claim() -> Bool { lock.withLock { defer { done = true }; return !done } }
+}
 
 func shellQuote(_ s: String) -> String {
     "'" + s.replacingOccurrences(of: "'", with: "'\\''") + "'"

ios/FrameControl/Views/RootView.swift

@@ -10,31 +10,15 @@ struct RootView: View {
             case .setup:
                 SetupView(model: model)
             case .connecting(let step):
-                ConnectingView(step: step, host: model.settings?.address) { model.showSetup() }
+                ConnectingView(step: step, host: model.settings?.host) { model.showSetup() }
             case .failed(let message) where model.retrying && !model.needsPairing:
-                WaitingView(host: model.settings?.address ?? "", detail: message, deviceName: model.deviceName,
+                WaitingView(host: model.settings.map { $0.port == 22 ? $0.host : "\($0.host):\($0.port)" } ?? "", detail: message, deviceName: model.deviceName,
                             reachable: { Task { await model.connect(quiet: true) } }, change: { model.showSetup() })
             case .failed(let message):
                 FailedView(message: message, canRetry: model.settings != nil, retrying: model.retrying, needsPairing: model.needsPairing,
                            retry: { Task { await model.connect() } }, change: { model.showSetup() })
             case .ready(let url):
                 WebShell(url: url, model: model).ignoresSafeArea()
-                    .accessibilityHidden(model.webRecoveryMessage != nil)
-                    .allowsHitTesting(model.webRecoveryMessage == nil)
-                if let message = model.webRecoveryMessage {
-                    RecoveryLayout {
-                        VStack(spacing: 16) {
-                            Image(systemName: "arrow.clockwise.circle").font(.system(size: 44)).foregroundStyle(.orange)
-                            Text("Reload Frame Control").font(.title3.bold())
-                            Text(message).multilineTextAlignment(.center).foregroundStyle(Color.frameMuted)
-                            Button("Try again") { model.retryWebContent() }
-                                .buttonStyle(.borderedProminent).controlSize(.large)
-                            Button("Change headset") { model.showSetup() }
-                        }
-                        .padding(32).frame(maxWidth: 480)
-                    }
-                    .background(Color.frameBackground.ignoresSafeArea())
-                }
             }
         }
         .preferredColorScheme(.dark)
@@ -49,37 +33,20 @@ extension Color {
     static let frameMuted = Color(red: 0.561, green: 0.596, blue: 0.627)
 }
 
-/// Recovery controls remain reachable on short screens and with large text.
-private struct RecoveryLayout<Content: View>: View {
-    @ViewBuilder let content: Content
-
-    var body: some View {
-        GeometryReader { geometry in
-            ScrollView {
-                content
-                    .frame(maxWidth: .infinity)
-                    .frame(minHeight: geometry.size.height)
-            }
-        }
-    }
-}
-
 struct ConnectingView: View {
     let step: String
     let host: String?
     let cancel: () -> Void
 
     var body: some View {
-        RecoveryLayout {
-            VStack(spacing: 18) {
-                Image("AppIconImage").resizable().frame(width: 76, height: 76).clipShape(RoundedRectangle(cornerRadius: 17))
-                ProgressView().controlSize(.large)
-                Text(step).font(.headline).multilineTextAlignment(.center)
-                if let host { Text(host).font(.subheadline).foregroundStyle(Color.frameMuted) }
-                Button("Change headset", action: cancel).padding(.top, 8)
-            }
-            .padding(32)
+        VStack(spacing: 18) {
+            Image("AppIconImage").resizable().frame(width: 76, height: 76).clipShape(RoundedRectangle(cornerRadius: 17))
+            ProgressView().controlSize(.large)
+            Text(step).font(.headline).multilineTextAlignment(.center)
+            if let host { Text(host).font(.subheadline).foregroundStyle(Color.frameMuted) }
+            Button("Change headset", action: cancel).padding(.top, 8)
         }
+        .padding(32)
     }
 }
 
@@ -92,23 +59,21 @@ struct FailedView: View {
     let change: () -> Void
 
     var body: some View {
-        RecoveryLayout {
-            VStack(spacing: 16) {
-                Image(systemName: needsPairing ? "lock.trianglebadge.exclamationmark" : "wifi.exclamationmark")
-                    .font(.system(size: 44)).foregroundStyle(.orange)
-                Text(needsPairing ? "Pair with the Frame again" : "Can't reach the Frame").font(.title3.bold())
-                Text(message).multilineTextAlignment(.center).foregroundStyle(Color.frameMuted)
-                if retrying { Text("Trying again every few seconds.").font(.footnote).foregroundStyle(Color.frameMuted) }
-                if needsPairing {
-                    Button("Pair again", action: change).buttonStyle(.borderedProminent).controlSize(.large)
-                } else if canRetry {
-                    Button("Try again", action: retry).buttonStyle(.borderedProminent).controlSize(.large)
-                }
-                if !needsPairing { Button(canRetry ? "Change headset" : "Back", action: change) }
+        VStack(spacing: 16) {
+            Image(systemName: needsPairing ? "lock.trianglebadge.exclamationmark" : "wifi.exclamationmark")
+                .font(.system(size: 44)).foregroundStyle(.orange)
+            Text(needsPairing ? "Pair with the Frame again" : "Can't reach the Frame").font(.title3.bold())
+            Text(message).multilineTextAlignment(.center).foregroundStyle(Color.frameMuted)
+            if retrying { Text("Trying again every few seconds.").font(.footnote).foregroundStyle(Color.frameMuted) }
+            if needsPairing {
+                Button("Pair again", action: change).buttonStyle(.borderedProminent).controlSize(.large)
+            } else if canRetry {
+                Button("Try again", action: retry).buttonStyle(.borderedProminent).controlSize(.large)
             }
-            .padding(32)
-            .frame(maxWidth: 480)
+            if !needsPairing { Button(canRetry ? "Change headset" : "Back", action: change) }
         }
+        .padding(32)
+        .frame(maxWidth: 480)
     }
 }
 
@@ -121,37 +86,34 @@ struct WaitingView: View {
     let reachable: () -> Void
     let change: () -> Void
     @State private var pulse = false
-    @Environment(\.accessibilityReduceMotion) private var reduceMotion
 
     var body: some View {
-        RecoveryLayout {
-            VStack(spacing: 18) {
-                Image("AppIconImage").resizable().frame(width: 76, height: 76)
-                    .clipShape(RoundedRectangle(cornerRadius: 17))
-                    .opacity(reduceMotion || pulse ? 1 : 0.55)
-                    .animation(reduceMotion ? nil : .easeInOut(duration: 1.2).repeatForever(autoreverses: true), value: pulse)
-                Text("Waiting for your Frame").font(.title3.bold())
-                Text("Put the headset on, or press its power button, to wake it. Frame Control connects by itself as soon as it's awake.")
-                    .multilineTextAlignment(.center)
-                VStack(alignment: .leading, spacing: 10) {
-                    Tip(icon: "wifi", text: "Same Wi-Fi as this \(deviceName), or both on Tailscale.")
-                    Tip(icon: "bolt.horizontal", text: "Asleep, the Frame drops off the network entirely; nothing can wake it remotely.")
-                }
-                .padding(14)
-                .background(Color.framePanel, in: RoundedRectangle(cornerRadius: 12))
-                Text(detail).font(.footnote).foregroundStyle(Color.frameMuted).multilineTextAlignment(.center)
-                Button("Connect to a different Frame", action: change).font(.footnote)
+        VStack(spacing: 18) {
+            Image("AppIconImage").resizable().frame(width: 76, height: 76)
+                .clipShape(RoundedRectangle(cornerRadius: 17))
+                .opacity(pulse ? 1 : 0.55)
+                .animation(.easeInOut(duration: 1.2).repeatForever(autoreverses: true), value: pulse)
+            Text("Waiting for your Frame").font(.title3.bold())
+            Text("Put the headset on, or press its power button, to wake it. Frame Control connects by itself as soon as it's awake.")
+                .multilineTextAlignment(.center)
+            VStack(alignment: .leading, spacing: 10) {
+                Tip(icon: "wifi", text: "Same Wi-Fi as this \(deviceName), or both on Tailscale.")
+                Tip(icon: "bolt.horizontal", text: "Asleep, the Frame drops off the network entirely; nothing can wake it remotely.")
             }
-            .padding(28)
-            .frame(maxWidth: 480)
-            .onAppear { pulse = true }
-            .task(id: host) {
-                while !Task.isCancelled {
-                    try? await Task.sleep(nanoseconds: 3_000_000_000)
-                    if !Task.isCancelled, !host.isEmpty, await FrameFinder.sshAnswers(host: host), !Task.isCancelled {
-                        reachable()
-                        return
-                    }
+            .padding(14)
+            .background(Color.framePanel, in: RoundedRectangle(cornerRadius: 12))
+            Text(detail).font(.footnote).foregroundStyle(Color.frameMuted).multilineTextAlignment(.center)
+            Button("Connect to a different Frame", action: change).font(.footnote)
+        }
+        .padding(28)
+        .frame(maxWidth: 480)
+        .onAppear { pulse = true }
+        .task(id: host) {
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: 3_000_000_000)
+                if !host.isEmpty, await FrameFinder.sshAnswers(host: host) {
+                    reachable()
+                    return
                 }
             }
         }

ios/FrameControl/Views/SetupView.swift

@@ -13,9 +13,10 @@ struct SetupView: View {
     @State private var showHelp = false
     @FocusState private var passwordFocused: Bool
 
-    /// An explicit target always wins over discovery.
+    /// Where Connect goes: what the finder saw, else what was typed, else frame.local.
     private var host: String {
-        FrameSearchState.address(manual: manualHost, discovered: finder.found?.host)
+        let typed = manualHost.trimmingCharacters(in: .whitespaces)
+        return finder.found?.host ?? (typed.isEmpty ? "frame.local" : typed)
     }
 
     var body: some View {
@@ -33,19 +34,19 @@ struct SetupView: View {
         .scrollDismissesKeyboard(.interactively)
         .background(Color.frameBackground)
         .onAppear {
-            manualHost = model.settings?.address ?? ""
+            manualHost = model.settings?.host ?? ""
             user = model.settings?.user ?? "steamos"
-            var fallback = model.settings?.address
+            var fallback = model.settings?.host
             #if DEBUG
             fallback = ProcessInfo.processInfo.environment["FRAME_TEST_FALLBACK"] ?? fallback  // Simulator test hook
             #endif
-            finder.start(fallback: fallback, manual: !manualHost.isEmpty)
+            finder.start(fallback: fallback)
         }
         .onDisappear { finder.stop() }
         // After a few seconds of not finding it, say exactly what to check.
         .task(id: finder.since) {
             try? await Task.sleep(nanoseconds: 8_000_000_000)
-            if !Task.isCancelled { showHelp = true }
+            showHelp = true
         }
     }
 
@@ -119,7 +120,7 @@ struct SetupView: View {
                     Text("Address").font(.footnote).foregroundStyle(Color.frameMuted)
                     TextField("frame.local, an IP, or a Tailscale name", text: $manualHost)
                         .keyboardType(.URL).textInputAutocapitalization(.never).autocorrectionDisabled()
-                        .onSubmit { finder.start(fallback: manualHost, manual: true) }
+                        .onSubmit { finder.start(fallback: manualHost) }
                         .padding(10).background(Color.black.opacity(0.28), in: RoundedRectangle(cornerRadius: 8))
                     TextField("User", text: $user)
                         .textInputAutocapitalization(.never).autocorrectionDisabled()
@@ -148,9 +149,7 @@ struct SetupView: View {
         }
         .onChange(of: manualHost) { _, value in
             // A typed address replaces the search.
-            showHelp = false
-            let typed = value.trimmingCharacters(in: .whitespacesAndNewlines)
-            finder.start(fallback: typed, manual: !typed.isEmpty)
+            if !value.trimmingCharacters(in: .whitespaces).isEmpty, finder.found?.host != value { finder.start(fallback: value) }
         }
     }
 

ios/FrameControl/Web/WebShell.swift

@@ -31,13 +31,14 @@ struct WebShell: UIViewRepresentable {
         web.isInspectable = true
         #endif
         context.coordinator.web = web
-        context.coordinator.load(url, reloadID: model.webReloadID)
+        web.load(URLRequest(url: url))
         return web
     }
 
     func updateUIView(_ web: WKWebView, context: Context) {
-        if context.coordinator.loaded != url || context.coordinator.reloadID != model.webReloadID {
-            context.coordinator.load(url, reloadID: model.webReloadID)
+        if context.coordinator.loaded != url {
+            context.coordinator.loaded = url
+            web.load(URLRequest(url: url))
         }
         context.coordinator.deliverInstallLinks()
     }
@@ -46,21 +47,16 @@ struct WebShell: UIViewRepresentable {
     (() => {
       const call = (name, arg) => window.webkit.messageHandlers.frameApp.postMessage({ name, arg: arg ?? null });
       let installCb = null;
-      window.__frameDocumentID = crypto.randomUUID();
       window.frameApp = {
         platform: "ios",
-        preferences: {
-          read: () => call("preferencesRead"),
-          write: (key, value) => call("preferencesWrite", { key, value }),
-        },
         notify: (message, request) => call("notify", { message, request }),
         readClipboard: () => call("readClipboard"),
         setUpConnection: () => call("setUpConnection"),
         open: (what) => call("open", what),
         saveImages: (images) => call("saveImages", images),
-        onInstallLink: (cb) => { installCb = cb; return call("installLinkReady", window.__frameDocumentID); },
+        onInstallLink: (cb) => { installCb = cb; return call("installLinkReady"); },
       };
-      window.__frameInstallLink = (req) => { if (!installCb) return false; installCb(req); return true; };
+      window.__frameInstallLink = (req) => { if (installCb) installCb(req); };
     })();
     """
 
@@ -68,18 +64,7 @@ struct WebShell: UIViewRepresentable {
         let model: AppModel
         weak var web: WKWebView?
         var loaded: URL?
-        private(set) var document = WebDocumentState()
-        private(set) var reloadID = 0
-        private var activeNavigation: WKNavigation?
-        private let preferences = FramePreferences()
-
-        @MainActor
-        func load(_ url: URL, reloadID: Int) {
-            loaded = url
-            self.reloadID = reloadID
-            document.resetSession()
-            activeNavigation = web?.load(URLRequest(url: url))
-        }
+        private var installReady = false
 
         init(model: AppModel) {
             self.model = model
@@ -133,14 +118,6 @@ struct WebShell: UIViewRepresentable {
                         send(settings.authorizationStatus == .authorized || settings.authorizationStatus == .provisional, nil)
                     }
                 }
-            case "preferencesRead":
-                replyHandler(preferences.read(), nil)
-            case "preferencesWrite":
-                guard let args = arg as? [String: Any], let key = args["key"] as? String,
-                      let value = args["value"] as? String, preferences.write(key: key, value: value) else {
-                    return replyHandler(nil, "Invalid preference")
-                }
-                replyHandler(true, nil)
             case "readClipboard":
                 replyHandler(UIPasteboard.general.string ?? "", nil)
             case "setUpConnection":
@@ -158,20 +135,9 @@ struct WebShell: UIViewRepresentable {
                 share(images)
                 replyHandler(["message": "Choose Save Image to keep \(images.count == 1 ? "it" : "them") in Photos"], nil)
             case "installLinkReady":
-                guard let id = arg as? String, let web,
-                      let data = try? JSONSerialization.data(withJSONObject: id, options: .fragmentsAllowed),
-                      let json = String(data: data, encoding: .utf8) else {
-                    return replyHandler(nil, "Invalid document")
-                }
-                let generation = document.generation
-                web.evaluateJavaScript("window.__frameDocumentID === \(json)") { [weak self] result, error in
-                    guard let self else { return replyHandler(nil, "Page closed") }
-                    if error == nil, result as? Bool == true {
-                        self.document.ready(id, generation: generation)
-                        self.deliverInstallLinks()
-                    }
-                    replyHandler(nil, nil)
-                }
+                installReady = true
+                deliverInstallLinks()
+                replyHandler(nil, nil)
             default:
                 replyHandler(nil, "unknown request \(name)")
             }
@@ -179,23 +145,13 @@ struct WebShell: UIViewRepresentable {
 
         @MainActor
         func deliverInstallLinks() {
-            guard let web, let loaded, model.phase == .ready(loaded), reloadID == model.webReloadID,
-                  let link = model.pendingInstallLinks.first, let delivery = document.beginDelivery() else { return }
-            let req = ["kind": link.kind.rawValue, "target": link.target]
-            guard let json = try? JSONSerialization.data(withJSONObject: req),
-                  let text = String(data: json, encoding: .utf8),
-                  let idData = try? JSONSerialization.data(withJSONObject: delivery.documentID, options: .fragmentsAllowed),
-                  let id = String(data: idData, encoding: .utf8) else {
-                _ = document.finishDelivery(delivery, acknowledged: false)
-                return
-            }
-            // Keep the head queued until the live document confirms its callback ran.
-            web.evaluateJavaScript("window.__frameDocumentID === \(id) && window.__frameInstallLink(\(text)) === true") { [weak self] result, error in
-                guard let self, let loaded = self.loaded, self.model.phase == .ready(loaded),
-                      self.reloadID == self.model.webReloadID else { return }
-                guard self.document.finishDelivery(delivery, acknowledged: error == nil && result as? Bool == true) else { return }
-                if self.model.pendingInstallLinks.first == link { self.model.pendingInstallLinks.removeFirst() }
-                self.deliverInstallLinks()
+            guard installReady, let web, !model.pendingInstallLinks.isEmpty else { return }
+            let links = model.pendingInstallLinks
+            model.pendingInstallLinks = []
+            for link in links {
+                let req = ["kind": link.kind.rawValue, "target": link.target]
+                guard let json = try? JSONSerialization.data(withJSONObject: req), let text = String(data: json, encoding: .utf8) else { continue }
+                web.evaluateJavaScript("window.__frameInstallLink(\(text))")
             }
         }
 
@@ -230,55 +186,13 @@ struct WebShell: UIViewRepresentable {
             (root.presentedViewController ?? root).present(sheet, animated: true)
         }
 
-        // A new document cannot receive links using the previous page's callback.
-        @MainActor
-        func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) {
-            activeNavigation = navigation
-            document.beginDocument()
-        }
-
-        @MainActor
-        func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
-            recover(webView, message: "The app page stopped responding. Try loading it again, or change headset.")
-        }
-
-        @MainActor
-        func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
-            navigationFailed(webView, navigation: navigation, error: error)
-        }
-
-        @MainActor
-        func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
-            navigationFailed(webView, navigation: navigation, error: error)
-        }
-
-        @MainActor
-        private func navigationFailed(_ webView: WKWebView, navigation: WKNavigation?, error: Error) {
-            guard navigation === activeNavigation, (error as NSError).code != NSURLErrorCancelled else { return }
-            recover(webView, message: "Couldn't load the app page. \(error.localizedDescription)")
-        }
-
-        @MainActor
-        private func recover(_ webView: WKWebView, message: String) {
-            guard let loaded, model.phase == .ready(loaded), reloadID == model.webReloadID,
-                  model.webRecoveryMessage == nil else { return }
-            activeNavigation = nil
-            if document.shouldReloadAfterFailure() {
-                // Reload the original authenticated URL, including its session key.
-                activeNavigation = webView.load(URLRequest(url: loaded))
-            } else {
-                model.webContentFailed(at: loaded, message: message)
-            }
-        }
-
+        #if DEBUG
         /// Simulator test hook: FRAME_TEST_JS runs in the page once it has loaded.
-        @MainActor
         func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
-            #if DEBUG
             guard let js = ProcessInfo.processInfo.environment["FRAME_TEST_JS"] else { return }
             DispatchQueue.main.asyncAfter(deadline: .now() + 4) { webView.evaluateJavaScript(js) }
-            #endif
         }
+        #endif
 
         // MARK: navigation: the app's page stays here; other sites open in Safari
 

ios/FrameControlTests/NativeSessionTests.swift

@@ -1,100 +0,0 @@
-import Foundation
-import XCTest
-#if !NATIVE_CONTRACT_STANDALONE
-@testable import Frame_Control
-#endif
-
-final class NativeSessionTests: XCTestCase {
-    func testSavedAddressesRoundTripWithoutLosingPortOrIPv6() throws {
-        for host in ["frame.local", "100.100.100.2", "2001:db8::42", "fe80::1%en0"] {
-            for port in [22, 2222, 65535] {
-                let target = FrameSettings(host: host, port: port, user: "alex")
-                let saved = try JSONDecoder().decode(FrameSettings.self, from: JSONEncoder().encode(target))
-                XCTAssertEqual(FrameSettings.parse(host: saved.address, user: saved.user), target)
-            }
-        }
-        XCTAssertEqual(FrameSettings.parse(host: "  [2001:db8::42]:2222\n", user: " steamos "),
-                       FrameSettings(host: "2001:db8::42", port: 2222))
-        for host in ["", "frame.local:0", "frame.local:65536", "frame.local:no", "[::1]:no", "[::1]junk", "[::1"] {
-            XCTAssertNil(FrameSettings.parse(host: host, user: "steamos"), host)
-        }
-    }
-
-    func testManualTargetWinsAndSearchCallbacksExpire() {
-        XCTAssertEqual(FrameSearchState.address(manual: " 100.100.100.2:2222 ", discovered: "192.168.1.237"), "100.100.100.2:2222")
-        XCTAssertEqual(FrameSearchState.address(manual: " \n", discovered: "192.168.1.237"), "192.168.1.237")
-        XCTAssertEqual(FrameSearchState.address(manual: "", discovered: nil), "frame.local")
-        var search = FrameSearchState()
-        let bonjour = search.start(manualAddress: nil)
-        XCTAssertTrue(search.discovers)
-        let manual = search.start(manualAddress: "100.100.100.2:2222")
-        XCTAssertFalse(search.discovers)
-        XCTAssertFalse(search.accepts(bonjour))
-        XCTAssertTrue(search.accepts(manual))
-        search.stop()
-        XCTAssertFalse(search.accepts(manual))
-        _ = search.start(manualAddress: "")
-        XCTAssertTrue(search.discovers)
-    }
-
-    func testRecoveryIsBoundedUntilAnExplicitRetry() {
-        var page = WebDocumentState()
-        XCTAssertTrue(page.shouldReloadAfterFailure())
-        page.beginDocument()
-        page.ready("reloaded", generation: page.generation)
-        XCTAssertFalse(page.shouldReloadAfterFailure())
-        XCTAssertFalse(page.shouldReloadAfterFailure())
-        page.resetSession()
-        XCTAssertTrue(page.shouldReloadAfterFailure())
-    }
-
-    func testReplacementDocumentsCannotConsumeQueuedLinks() throws {
-        var page = WebDocumentState()
-        var queue = ["first", "second"]
-        XCTAssertNil(page.beginDelivery())
-        let oldGeneration = page.generation
-        page.ready("first document", generation: oldGeneration)
-        let oldDelivery = try XCTUnwrap(page.beginDelivery())
-        XCTAssertNil(page.beginDelivery(), "Serialize delivery while an acknowledgement is pending")
-        XCTAssertTrue(page.shouldReloadAfterFailure())
-        page.ready("stale readiness", generation: oldGeneration)
-        XCTAssertNil(page.beginDelivery())
-        if page.finishDelivery(oldDelivery, acknowledged: true) { queue.removeFirst() }
-        XCTAssertEqual(queue, ["first", "second"])
-        page.ready("replacement", generation: page.generation)
-        let failedDelivery = try XCTUnwrap(page.beginDelivery())
-        if page.finishDelivery(failedDelivery, acknowledged: false) { queue.removeFirst() }
-        XCTAssertEqual(queue, ["first", "second"])
-        XCTAssertNil(page.beginDelivery(), "An evaluation error needs fresh readiness")
-        page.ready("replacement", generation: page.generation)
-        let liveDelivery = try XCTUnwrap(page.beginDelivery())
-        if page.finishDelivery(liveDelivery, acknowledged: true) { queue.removeFirst() }
-        XCTAssertEqual(queue, ["second"])
-        XCTAssertNotNil(page.beginDelivery())
-        page.beginDocument()
-        XCTAssertNil(page.beginDelivery(), "Even healthy main-document navigation resets readiness")
-    }
-
-    func testPreferencesPersistAcrossSessionsAndRejectOtherKeysAndValues() throws {
-        let suite = "frame-control-contract-\(UUID().uuidString)"
-        let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
-        let first = FramePreferences(defaults: defaults)
-        XCTAssertEqual(first.read(), [:])
-        XCTAssertTrue(first.write(key: "mvSeparate", value: "0"))
-        XCTAssertTrue(first.write(key: "padUsed", value: "1"))
-        let second = FramePreferences(defaults: try XCTUnwrap(UserDefaults(suiteName: suite)))
-        XCTAssertEqual(second.read(), ["mvSeparate": "0", "padUsed": "1"])
-        for (key, value) in [("other", "1"), ("mvSeparate", "false"), ("padUsed", ""), ("padUsed", "2")] {
-            XCTAssertFalse(second.write(key: key, value: value))
-        }
-        XCTAssertEqual(first.read(), ["mvSeparate": "0", "padUsed": "1"])
-        XCTAssertNil(defaults.object(forKey: "frame.control.preference.other"))
-        defaults.set("bad", forKey: "frame.control.preference.mvSeparate")
-        defaults.set("1", forKey: "frame.control.preference.unknown")
-        XCTAssertEqual(second.read(), ["padUsed": "1"])
-        defaults.set(true, forKey: "frame.control.preference.padUsed")
-        XCTAssertEqual(second.read(), [:], "Only stored strings are supported")
-    }
-
-}

ios/scripts/make_frame_bundle.py

@@ -18,8 +18,7 @@ import tarfile
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[2]
-PATTERNS = ["ui/*.py", "ui/*.html", "ui/*.js", "ui/*.css", "ui/local-bin/*", "ui/apk_sources/*.py", "ui/apk_sources/*.json", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py", "frame/android/*.js",
-            "frame/openxr-compat/XrApiLayer_FRAME_compat.json", "frame/openxr-compat/prebuilt/arm64-v8a/*.so.gz",
+PATTERNS = ["ui/*.py", "ui/*.html", "ui/*.js", "ui/*.css", "ui/local-bin/*", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
             "frame/devkit-utils/**/*", "apk-catalog/*.py", "apk-catalog/pins.json", "apk-catalog/site/apps.js",
             "frame/kdeconnect/packages.json", "frame/kdeconnect/NOTICE.md", "frame/kdeconnect/LICENSES/*/*",
             "frame/kdeconnect/packages/*.pkg.tar.zst", "LICENSE", "THIRD_PARTY_NOTICES.md"]

scripts/e2e.sh

@@ -23,7 +23,8 @@ started=$SECONDS
 
 print "==> Building fakeframe-frame (from $base) and fakeframe-host"
 # Quiet when it works; if a build fails, build again with the full log so CI shows why.
-build() { docker build -q "$@" >/dev/null || { docker build --progress=plain "$@"; exit 2 } }
+# That second build also rides out a flaky package mirror: only its failure is fatal.
+build() { docker build -q "$@" >/dev/null || docker build --progress=plain "$@" || exit 2 }
 build --build-arg BASE="$base" -t fakeframe-frame -f tests/fakeframe/Containerfile tests/fakeframe
 build -t fakeframe-host -f tests/fakeframe/host.Containerfile tests/fakeframe
 

scripts/store-on-frame.sh

@@ -1,116 +0,0 @@
-#!/usr/bin/env zsh
-# Mac-side: the APK Store in the headset. Frame Control's Android catalogue
-# (the same rated F-Droid list, Install, Open and Remove) as its own floating
-# panel on the Steam Frame, so you can browse and install apps from inside.
-# See docs/apks.md → "The store in the headset".
-#
-# Frame Control's server runs on the Frame itself (FRAME_LOCAL=1, as the iPhone
-# app runs it) on the Frame's loopback, and Chromium opens ui/store.html as a
-# panel. Installs then download and verify the APK on the Frame; the Mac isn't
-# needed after `open`.
-#
-# Usage:
-#   scripts/store-on-frame.sh open     # copy the server over if it changed, start it, open the panel
-#   scripts/store-on-frame.sh close    # close the panel and stop the server
-#   scripts/store-on-frame.sh status
-set -euo pipefail
-
-FRAME_ALIAS=${FRAME_ALIAS:-frame}
-HERE=${0:A:h}
-ROOT=${HERE:h}
-PORT=47812           # the Frame's 127.0.0.1 only
-APPID=2001947812     # the panel's id (panel-on-frame.sh's range)
-# Not ~/.cache/frame-control: the iPhone app prunes other versions there.
-REMOTE=.local/share/frame-control/store-server
-
-cmd=${1:-}
-
-# Same bundle the iPhone app copies (ios/scripts/make_frame_bundle.py), so the
-# server on the Frame has exactly the files the desktop app ships.
-deploy() {
-  local tmp version
-  tmp=$(mktemp -d)
-  trap "rm -rf ${(q)tmp}" EXIT
-  version=$(python3 "$ROOT/ios/scripts/make_frame_bundle.py" "$tmp/bundle.tar.gz")
-  if ! ssh "$FRAME_ALIAS" "test -f $REMOTE/$version/ui/server.py"; then
-    print -u2 "==> Copying Frame Control ($version) to the Frame"
-    ssh "$FRAME_ALIAS" "set -e; mkdir -p $REMOTE; cd $REMOTE; rm -rf $version.tmp; mkdir $version.tmp
-      tar xzf - -C $version.tmp; rm -rf $version; mv $version.tmp $version" <"$tmp/bundle.tar.gz"
-  fi
-  # Older versions, unless a server is still running from one.
-  ssh "$FRAME_ALIAS" "cd $REMOTE && for d in */; do d=\${d%/}; [ \"\$d\" = $version ] && continue
-    pgrep -f \"\$PWD/\$d/\" >/dev/null && continue; rm -rf -- \"\$d\"; done"
-  print -r -- "$version"
-}
-
-# Runs on the Frame. Args: dir port appid key
-OPEN=$(cat <<'EOF'
-set -u
-dir=$HOME/$1 port=$2 appid=$3 key=$4
-export DISPLAY=:0 LC_ALL=C.UTF-8
-unset WAYLAND_DISPLAY
-xprop -root GAMESCOPE_FOCUSABLE_WINDOWS >/dev/null 2>&1 || { echo "The headset isn't showing anything (gamescope's :0 isn't up). Wake it and try again." >&2; exit 2; }
-if [ -x "$HOME/chromium-xr/chrome" ]; then
-  # Steam's overlay library crashes Chromium's zygote (docs/webxr-chromium.md).
-  browser=(env LD_PRELOAD= "$HOME/chromium-xr/chrome" --user-data-dir="$HOME/.local/share/frame-control/store")
-elif flatpak info org.chromium.Chromium >/dev/null 2>&1; then
-  browser=(flatpak run org.chromium.Chromium --user-data-dir="$HOME/.var/app/org.chromium.Chromium/frame-store")
-else
-  echo "The store needs a Chromium on the Frame: Chromium XR (docs/webxr-chromium.md) or the org.chromium.Chromium Flatpak (scripts/install-apps.sh)." >&2
-  exit 3
-fi
-# A fresh server each time, so it runs this version with this key.
-[ -f /tmp/frame-store-server.pid ] && kill "$(cat /tmp/frame-store-server.pid)" 2>/dev/null
-# Match the browser by its profile flag and the server by its script path: this
-# launcher's own command line holds the bundle path, so a looser pattern kills it.
-pkill -f '[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) ' || true
-pkill -f '[s]tore-server/[^/ ]*/ui/server[.]py' || true
-sleep 0.5
-cd "$dir" || exit 1
-FRAME_LOCAL=1 FRAME_UI_KEY=$key FRAME_DEVICE=headset setsid nohup python3 -I -u -B "$dir/ui/server.py" --port "$port" \
-  >/tmp/frame-store-server.log 2>&1 </dev/null &
-echo $! > /tmp/frame-store-server.pid
-up=
-for _ in $(seq 1 40); do
-  curl -s -o /dev/null "http://127.0.0.1:$port/store" && { up=1; break; }
-  sleep 0.25
-done
-[ -n "$up" ] || { echo "Frame Control's server didn't start on the Frame:" >&2; tail -n 15 /tmp/frame-store-server.log >&2; exit 1; }
-setsid nohup "${browser[@]}" --ozone-platform=x11 --force-device-scale-factor=1 --no-first-run --no-default-browser-check \
-  --password-store=basic --disable-session-crashed-bubble --noerrdialogs --disable-infobars \
-  --disable-features=Translate,MediaRouter --window-size=1280,800 \
-  "--app=http://127.0.0.1:$port/store?key=$key" >/tmp/frame-store.log 2>&1 </dev/null &
-# Tag the window so it's its own panel (docs/panels.md).
-for _ in $(seq 1 60); do
-  sleep 0.5
-  for win in $(xwininfo -root -children 2>/dev/null | awk '/^ +0x/ {print $1}'); do
-    xprop -id "$win" _NET_WM_NAME WM_NAME 2>/dev/null | grep -qF "APK Store" || continue
-    if xprop -id "$win" -f STEAM_GAME 32c -set STEAM_GAME "$appid" 2>/dev/null; then
-      echo "panel valve.steam.desktopgame.$appid window $win"
-      exit 0
-    fi
-  done
-done
-echo "Chromium started, but its window didn't appear within 30 s:" >&2
-tail -n 15 /tmp/frame-store.log >&2
-exit 1
-EOF
-)
-
-case "$cmd" in
-  open)
-    version=$(deploy | tail -n 1)
-    key=$(openssl rand -hex 16)
-    ssh "$FRAME_ALIAS" bash -s -- "$REMOTE/$version" "$PORT" "$APPID" "$key" <<<"$OPEN"
-    ;;
-  close)
-    ssh "$FRAME_ALIAS" 'pkill -f "[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) " || true
-      pkill -f "[s]tore-server/[^/ ]*/ui/server[.]py" || true
-      [ -f /tmp/frame-store-server.pid ] && kill "$(cat /tmp/frame-store-server.pid)" 2>/dev/null; rm -f /tmp/frame-store-server.pid; true'
-    ;;
-  status)
-    ssh "$FRAME_ALIAS" "ls $REMOTE 2>/dev/null; curl -s -o /dev/null http://127.0.0.1:$PORT/store && echo 'server up' || echo 'server down'
-      pgrep -af '[-]-user-data-dir=[^ ]*/(frame-control/store|frame-store) |[s]tore-server/[^/ ]*/ui/server[.]py' | head -n 1 | cut -c1-120"
-    ;;
-  *) sed -n '2,15p' "$0"; exit 2 ;;
-esac

scripts/windows-vm.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env zsh
+# Mac or Linux: drive a Windows 11 test VM for Frame Control's Windows build.
+# The VM is a dockur/windows container on another machine; this reaches it over
+# SSH through that machine. See docs/testing.md#windows-test-vm.
+#
+# Usage: scripts/windows-vm.sh <command> [args]
+#   up | down | status      start it (waits for SSH), shut Windows down cleanly, show state
+#   ps '<PowerShell>'       run PowerShell as the VM's user
+#   put <file> [<dir>]      copy a file in (default: the user's Downloads)
+#   shot <out.png>          save the VM's screen
+#   click <x> <y>           click screen pixel x,y in the signed-in session
+#   scroll <x> <y> <n>      turn the wheel n notches at x,y (negative scrolls down)
+#   keys <key>...           type QEMU key names: a, shift-a, ret, tab, esc, spc ...
+#   frame-key add|remove    let the VM's Frame Control key into the headset (`frame`
+#                           alias) for a test run, then take it out again
+#
+# Set WINVM_HOST to the ssh alias of the machine running the container. Optional:
+# WINVM_CONTAINER (frame-winvm), WINVM_USER (frame), WINVM_PORT (2222: the VM's
+# sshd, published on that machine's loopback), WINVM_KEY (~/.ssh/id_ed25519_winvm).
+set -euo pipefail
+setopt extendedglob
+
+host=${WINVM_HOST:?set WINVM_HOST to the ssh alias of the machine running the VM}
+ctr=${WINVM_CONTAINER:-frame-winvm}
+user=${WINVM_USER:-frame}
+port=${WINVM_PORT:-2222}
+key=${WINVM_KEY:-$HOME/.ssh/id_ed25519_winvm}
+opts=(-o ConnectTimeout=20 -o StrictHostKeyChecking=accept-new
+      -o UserKnownHostsFile=${TMPDIR:-/tmp}/windows-vm-known_hosts -i $key -J $host)
+TAG=windows-vm-test  # comment on the VM's key in the headset's authorized_keys
+
+die() { print -u2 "windows-vm: $*"; exit 1 }
+int() { [[ $1 == (-|)<-99999> ]] || die "not a whole number (up to 99999): $1" }
+# These go into commands run by a shell on the other machine, so keep them plain.
+for v in $host $ctr $user; do [[ $v == [A-Za-z0-9_.]##[A-Za-z0-9_.-]# ]] || die "not a plain name: $v"; done
+[[ $port == <1-65535> ]] || die "WINVM_PORT isn't a port: $port"
+
+# Windows' OpenSSH waits for stdin to close, so it always gets /dev/null. The
+# script travels UTF-16 base64-encoded, so no quoting survives two shells.
+vm_ps() {
+  local b64=$(print -rn -- "\$ProgressPreference = 'SilentlyContinue'"$'\n'"$1" |
+              iconv -f UTF-8 -t UTF-16LE | base64 | tr -d '\n')
+  ssh $opts -p $port $user@127.0.0.1 "powershell -NoProfile -NonInteractive -OutputFormat Text -EncodedCommand $b64" </dev/null
+}
+
+# QEMU's monitor inside the container: one command per line on stdin.
+monitor() { ssh $host "docker exec -i $ctr nc -q 1 -U /run/shm/monitor.sock" >/dev/null }
+
+# Input has to come from the signed-in desktop session, not SSH's session 0, so
+# a scheduled task running as the user replays one click or wheel turn written
+# to input.txt, then deletes the file to say it's done. Any error stops it
+# before that, so the caller times out instead of reporting a click.
+INPUT_PS1='$ErrorActionPreference = "Stop"
+$a = (Get-Content "$PSScriptRoot\input.txt").Trim() -split "\s+"
+Add-Type -Namespace WinVm -Name Input -MemberDefinition @"
+[DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+[DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
+[DllImport("user32.dll")] public static extern void mouse_event(uint flags, int dx, int dy, int data, System.IntPtr extra);
+"@
+[WinVm.Input]::SetProcessDPIAware() | Out-Null
+if (-not [WinVm.Input]::SetCursorPos([int]$a[0], [int]$a[1])) { throw "SetCursorPos failed" }
+Start-Sleep -Milliseconds 150
+if ($a[2] -eq "click") {
+  [WinVm.Input]::mouse_event(0x2, 0, 0, 0, [IntPtr]::Zero); Start-Sleep -Milliseconds 60
+  [WinVm.Input]::mouse_event(0x4, 0, 0, 0, [IntPtr]::Zero)
+} else { [WinVm.Input]::mouse_event(0x800, 0, 0, 120 * [int]$a[3], [IntPtr]::Zero) }
+Remove-Item "$PSScriptRoot\input.txt"'
+
+pointer() {  # x y click|wheel [notches]
+  local b64=$(print -rn -- $INPUT_PS1 | base64 | tr -d '\n')
+  vm_ps '$ErrorActionPreference = "Stop"
+$d = Join-Path $env:LOCALAPPDATA "windows-vm"; $req = "$d\input.txt"; $mine = $false
+# Giving up: end the helper first, or it could wake up and act in a later request.
+function Abandon {
+  Stop-ScheduledTask -TaskName WindowsVmInput -ErrorAction SilentlyContinue
+  foreach ($i in 1..25) {
+    if ((Get-ScheduledTask -TaskName WindowsVmInput -ErrorAction SilentlyContinue).State -ne "Running") { break }
+    Start-Sleep -Milliseconds 200
+  }
+  Remove-Item $req -ErrorAction SilentlyContinue
+}
+trap { [Console]::Error.WriteLine("windows-vm: $_"); if ($mine) { Abandon }; exit 1 }
+# One request at a time: the helper, the task and input.txt are shared. Windows
+# frees the mutex when this process ends, however it ends.
+$lock = New-Object Threading.Mutex($false, "windows-vm-input")
+try { $mine = $lock.WaitOne(15000) } catch [Threading.AbandonedMutexException] { $mine = $true }
+if (-not $mine) { [Console]::Error.WriteLine("windows-vm: another click or scroll is still in progress"); exit 1 }
+New-Item -ItemType Directory -Force $d | Out-Null
+[IO.File]::WriteAllText($req, "'"$*"'")
+[IO.File]::WriteAllText("$d\input.ps1", [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("'$b64'")))
+$act = New-ScheduledTaskAction -Execute powershell.exe -Argument "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$d\input.ps1`""
+$who = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive
+Register-ScheduledTask -TaskName WindowsVmInput -Action $act -Principal $who -Force | Out-Null
+Start-ScheduledTask -TaskName WindowsVmInput
+foreach ($i in 1..50) { if (-not (Test-Path $req)) { exit 0 }; Start-Sleep -Milliseconds 200 }
+Abandon
+[Console]::Error.WriteLine("windows-vm: no input after 10 s: is $env:USERNAME signed in on the VM screen, and is x,y on it?"); exit 1'
+}
+
+(( $# )) || die "usage: see the top of $0"
+cmd=$1; shift
+case $cmd in
+  up)
+    ssh $host "docker start $ctr" >/dev/null
+    for i in {1..60}; do
+      vm_ps 'exit 0' 2>/dev/null && { print "up"; exit 0 }
+      sleep 5
+    done
+    die "Windows didn't answer on SSH within 5 minutes" ;;
+  down)   # the container turns SIGTERM into an ACPI shutdown and waits for Windows
+    ssh $host "docker stop -t 150 $ctr" >/dev/null && print "down" ;;
+  status) ssh $host "docker ps -a --filter 'name=^$ctr\$' --format '{{.Names}}: {{.Status}}'" ;;
+  ps)     (( $# == 1 )) || die "usage: ps '<PowerShell>'"; vm_ps "$1" ;;
+  put)
+    [[ -f ${1:-} ]] || die "usage: put <file> [<dir>]"
+    scp -q $opts -P $port $1 "$user@127.0.0.1:${2:-C:/Users/$user/Downloads}/${1:t}" </dev/null ;;
+  shot)
+    (( $# == 1 )) || die "usage: shot <out.png>"
+    print "screendump /tmp/windows-vm-shot.ppm" | monitor
+    sleep 1
+    ssh $host "docker exec $ctr sh -c 'cat /tmp/windows-vm-shot.ppm && rm /tmp/windows-vm-shot.ppm'" | python3 -c '
+import re, struct, sys, zlib
+d = sys.stdin.buffer.read()
+m = re.match(rb"P6\s+(\d+)\s+(\d+)\s+255\s", d) or sys.exit("windows-vm: no screen dump")
+w, h = int(m[1]), int(m[2]); px = d[m.end():]
+raw = b"".join(b"\0" + px[y * w * 3:(y + 1) * w * 3] for y in range(h))
+chunk = lambda t, b: struct.pack(">I", len(b)) + t + b + struct.pack(">I", zlib.crc32(t + b))
+open(sys.argv[1], "wb").write(b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+                              + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b""))
+' $1
+    print $1 ;;
+  click)  (( $# == 2 )) || die "usage: click <x> <y>"; int $1; int $2; pointer $1 $2 click ;;
+  scroll) (( $# == 3 )) || die "usage: scroll <x> <y> <n>"; int $1; int $2; int $3; pointer $1 $2 wheel $3 ;;
+  keys)
+    (( $# )) || die "usage: keys <key>..."
+    for k; do [[ $k == [a-z0-9_.,/=-]## ]] || die "not a QEMU key name: $k"; done
+    for k; do print "sendkey $k"; done | monitor ;;
+  frame-key)
+    [[ ${1:-} == (add|remove) ]] || die "usage: frame-key add|remove"
+    pub=(${=$(vm_ps 'Get-Content (Join-Path $env:USERPROFILE ".ssh\id_ed25519_frame.pub")' | tr -d '\r')})
+    [[ ${pub[1]:-} == ssh-ed25519 && ${pub[2]:-} == [A-Za-z0-9+/=]## ]] ||
+      die "the VM has no Frame Control key yet: run Set Up Connection in the app first"
+    # $1: add|remove, $2: the key's base64, $3: the exact line this script owns.
+    ssh frame "sh -s -- $1 '$pub[2]' '$pub[1] $pub[2] $TAG'" <<'EOF'
+f=~/.ssh/authorized_keys
+if [ "$1" = add ]; then
+  if grep -qxF "$3" "$f"; then exit 0; fi
+  if grep -qF "$2" "$f"; then echo "the headset already trusts this key through another entry; left as it is"; exit 0; fi
+  [ -z "$(tail -c 1 "$f")" ] || echo >> "$f"   # a last line without a newline would swallow ours
+  echo "$3" >> "$f"
+else
+  t=$(mktemp "$f.XXXXXX") || exit 1
+  grep -vxF "$3" "$f" > "$t"   # 0: lines left, 1: none left, more: couldn't read or write
+  if [ $? -gt 1 ] || ! chmod 600 "$t" || ! mv "$t" "$f"; then
+    rm -f "$t"; echo "couldn't rewrite $f; it's unchanged" >&2; exit 1
+  fi
+fi
+EOF
+    print "frame-key $1: done" ;;
+  *) die "unknown command: $cmd (see the top of $0)" ;;
+esac

tests/client_preferences.cjs

@@ -1,72 +0,0 @@
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const vm = require('node:vm');
-const html = fs.readFileSync(require.resolve('../ui/index.html'), 'utf8');
-
-async function session(native, initial = {}, duringRead) {
-  const saved = { ...initial }, element = { checked: true, disabled: false };
-  const storage = { getItem: key => saved[key] ?? null, setItem: (key, value) => { saved[key] = String(value); } };
-  for (const key of ['mvSeparate', 'padUsed']) Object.defineProperty(storage, key, {
-    get: () => saved[key], set: value => { saved[key] = String(value); },
-  });
-  const calls = [];
-  const context = vm.createContext({ window: { frameApp: native ? { preferences: native } : undefined }, localStorage: storage,
-    $: () => element, log: (...args) => calls.push(args),
-    api: async () => ({ state: 'off' }), padStart: () => calls.push('start'), padShow: s => calls.push(s.state) });
-  const marker = html.indexOf('// ---- client preferences');
-  const start = marker >= 0 ? marker : html.indexOf('$("mvSeparate").checked =');
-  vm.runInContext(html.slice(start, html.indexOf('$("macview").onclick', start)), context);
-  if (duringRead) duringRead(context, element);
-  await vm.runInContext('typeof clientPreferences === "undefined" ? Promise.resolve() : clientPreferences.ready', context);
-  return { element, saved, calls, context, async change(value) {
-    element.checked = value; element.onchange({ target: element });
-    await new Promise(resolve => setImmediate(resolve));
-  } };
-}
-
-test('a layout choice survives moving from one native local origin to another', async () => {
-  const values = {};
-  const native = { read: async () => ({ ...values }), write: async (key, value) => { values[key] = value; } };
-  const first = await session(native);
-  await first.change(false);
-  assert.equal(first.element.checked, false);
-  const second = await session(native); // fresh origin storage
-  assert.equal(second.element.checked, false);
-});
-
-test('native values win over stale origin values and missing values migrate', async () => {
-  const values = { mvSeparate: '0' };
-  const native = { read: async () => ({ ...values }), write: async (key, value) => { values[key] = value; } };
-  const page = await session(native, { mvSeparate: '1', padUsed: '1' });
-  assert.equal(page.element.checked, false);
-  assert.equal(values.padUsed, '1');
-});
-
-test('ordinary browser storage and a failed native read retain usable choices', async () => {
-  assert.equal((await session(null, { mvSeparate: '0' })).element.checked, false);
-  const native = { read: async () => { throw Error('Unavailable'); }, write: async () => true };
-  const page = await session(native, { mvSeparate: '0' });
-  assert.equal(page.element.checked, false);
-  assert.equal(page.element.disabled, false);
-});
-
-test('starting input during a native read wins over its stale remembered value', async () => {
-  let resolveRead;
-  const writes = [];
-  const native = { read: () => new Promise(resolve => { resolveRead = resolve; }), write: async (key,value) => writes.push({key,value}) };
-  const page = await session(native, {}, context => {
-    vm.runInContext("clientPreferences.set('padUsed','1')",context);
-    resolveRead({padUsed:'0'});
-  });
-  await new Promise(resolve=>setImmediate(resolve));
-  assert.equal(vm.runInContext("clientPreferences.get('padUsed')",page.context),'1');
-  assert.deepEqual(writes,[{key:'padUsed',value:'1'}]);
-});
-
-test('one failed migration does not hide another native preference', async () => {
-  const native = {read:async()=>({padUsed:'1'}),write:async()=>{throw Error('disk unavailable');}};
-  const page=await session(native,{mvSeparate:'0'});
-  assert.equal(page.element.checked,false);
-  assert.equal(vm.runInContext("clientPreferences.get('padUsed')",page.context),'1');
-});

tests/control_center.cjs

@@ -14,7 +14,7 @@ function fixture() {
   const elements = new Map();
   function element(id) {
     if (!elements.has(id)) elements.set(id, {id,hidden:false,disabled:false,textContent:'',innerHTML:'',value:'',dataset:{},
-      classList:{toggle(){}},querySelectorAll(){return [];},close(){this.open=false;},setAttribute(key,value){this[key]=value;},addEventListener(key,callback){this[key]=callback;},focus(){this.focused=true;}});
+      classList:{toggle(){}},querySelectorAll(){return [];},setAttribute(key,value){this[key]=value;},addEventListener(key,callback){this[key]=callback;},focus(){this.focused=true;}});
     return elements.get(id);
   }
   const cards = cc.catalog.map(item=>{const e=element(item.id);e.dataset.ccCard=item.id;return e;});
@@ -42,7 +42,7 @@ function sharedPage({productionApi=false} = {}) {
   const f=fixture(), requests=[], writes=[], host=deferred(), job=deferred();
   const context={document:f.document,FrameControlCenter:cc,window:{frameApp:{setUpConnection(){}}},
     Date,setInterval,clearInterval,setTimeout:()=>1,clearTimeout(){},$:f.element,QUICK:[],installing:new Set(),
-    battery(){},setVolume(){},renderHome(){},gb:String,dur:String,esc:String,meter(){},toast(){},
+    battery(){},setVolume(){},gb:String,dur:String,esc:String,meter(){},toast(){},
     runJob(title,id){context.installing.add(id);return job.promise;},
     api:(path,body,device)=>{
       if(path==='/api/host')return host.promise;
@@ -64,12 +64,11 @@ function sharedPage({productionApi=false} = {}) {
       const request=deferred();request.path=path;request.opts=opts;requests.push(request);return request.promise;
     };
     Object.assign(context,{renderPill(){},renderConnDlg(){},renderBanner(){},viaText(){},netLabel(){},
-      padReset(){},ctrlReset(){},resetShots(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
+      resetShots(){},closeDevPop(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
     vm.runInContext(`const UI_KEY = 'test-only';
       const link = {s:null,device:'frame-a',phase:'connected',rev:0,net:null};
-      const disp = {}, gm = {seq:0}, cat = {}, wi = {}, sourceState = {jobs:new Map(),detail:null,detailRequest:0};
-      let viewGen = 0, lastImg = null, lastShot = null, androidApps = [], androidSeq = 0, titlesSeq = 0, page = 'control';
-      const androidPending = new Set();`,context);
+      const disp = {}, gm = {seq:0}, cat = {}, wi = {};
+      let viewGen = 0, lastImg = null, lastShot = null, androidApps = [], titlesSeq = 0, page = 'control';`,context);
     const apiStart=pageSource.indexOf('const HEADSET_FREE ='),apiEnd=pageSource.indexOf('// What a panel shows',apiStart);
     const onlineStart=pageSource.indexOf('function setOnline('),onlineEnd=pageSource.indexOf('function reloadAll()',onlineStart);
     const connectionStart=pageSource.indexOf('function onConnection('),connectionEnd=pageSource.indexOf('// Read the event stream',connectionStart);
@@ -439,13 +438,34 @@ test('mounted filters show empty state, counts, reset and host-dependent feature
   f.ui.host({os:'SteamOS',mobile:true});assert.equal(f.element('macLink').hidden,true);
   f.element('connectionLink').onclick({preventDefault(){}});assert.equal(f.opened,1);
 });
-test('every Control Center workflow reaches its intentional workspace', () => {
-  const {workspaceFixture}=require('./workspace_fixture.cjs');
-  const f=workspaceFixture();
-  const expected={view:'capture',shots:'capture',vrTools:'tools',comfort:'tools',pad:'tools',library:'games',getgames:'games',sideloaded:'games',android:'apps',display:'settings',androidLibrary:'apps',appStore:'apps',power:'settings',transfer:'tools',media:'tools',linuxApps:'apps',artworkSettings:'settings',privacy:'settings',panels:'tools',macview:'tools',devices:'devices'};
+test('every linked workflow selects its real page and section, preserving shortcuts', () => {
+  const html=fs.readFileSync(require.resolve('../ui/index.html'),'utf8');
+  const start=html.indexOf('const PAGES ='),end=html.indexOf('window.addEventListener("hashchange", showPage);',start);
+  const ids=new Set([...html.matchAll(/\bid="([^"]+)"/g)].map(m=>m[1]));
+  let activePage,scrolled;
+  const nodes=['home','games','android','tools','devices','control'].map(page=>({dataset:{page},classList:{toggle(key,on){if(on)activePage=page;}}}));
+  const sections=new Map();
+  const context={location:{hash:'#control'},document:{querySelectorAll:s=>s==='.page'?nodes:[],title:''},
+    window:{scrollTo(){}},$:id=>{
+      if(!ids.has(id))return null;
+      if(!sections.has(id))sections.set(id,{hidden:false,scrollIntoView(){scrolled=id;}});
+      return sections.get(id);
+    },live:false,toggleLive(){},scrollToY(){},loadMacView(){},loadPanelSwitcher(){}};
+  const androidStart=html.indexOf('function showAndroidTab(');
+  const androidEnd=html.indexOf("document.querySelectorAll('[data-store-tab]').forEach(button => button.onclick",androidStart);
+  vm.createContext(context);vm.runInContext(html.slice(androidStart,androidEnd)+html.slice(start,end)+'\nPAGES.push("devices", "control");',context);
+  vm.runInContext('showPage()',context);assert.equal(activePage,'control');
+  const expected={view:'home',shots:'home',vrTools:'home',comfort:'home',pad:'home',library:'games',getgames:'games',sideloaded:'games',android:'android',display:'android',androidLibrary:'android',appStore:'android',
+    power:'tools',transfer:'tools',media:'tools',apps:'tools',artworkSettings:'tools',privacy:'tools',panels:'tools',macview:'tools',devices:'devices'};
   for(const item of cc.catalog) for(const [href] of item.links||[]) {
     if(!href.startsWith('#')||href==='#connection')continue;
-    f.navigate(href);assert.equal(f.activePage,expected[href.slice(1)],href);
+    const id=href.slice(1);assert.ok(ids.has(id)||['android','devices'].includes(id),href);
+    context.location.hash=href;scrolled=null;vm.runInContext('showPage()',context);
+    assert.equal(activePage,expected[id],href);
+    if(!['android','devices'].includes(id))assert.equal(scrolled,id,href);
+    if(id==='display'||id==='androidLibrary') { assert.equal(sections.get('androidLibrary').hidden,false);assert.equal(sections.get('appStore').hidden,true); }
+    if(id==='appStore') { assert.equal(sections.get('appStore').hidden,false);assert.equal(sections.get('androidLibrary').hidden,true); }
   }
-  assert.equal(f.run('PAGES.length'),4);
+  assert.equal(vm.runInContext('PAGES[4]',context),'devices');
+  assert.equal(vm.runInContext('PAGES[5]',context),'control');
 });

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/ctrl_gestures.mjs

@@ -23,7 +23,7 @@ function page({ mode = "abs", rect = { left: 0, top: 0, width: 640, height: 360
   const sent = [];
   const canvas = { width: 1280, height: 720, getBoundingClientRect: () => rect };
   const env = {
-    devGen: 0, ctrl, $: () => canvas, ctrlMode: () => mode, ctrlShow: () => {}, toast: () => {},
+    ctrl, $: () => canvas, ctrlMode: () => mode, ctrlShow: () => {}, toast: () => {},
     ctrlTarget: () => (mode !== "abs" ? { ok: true } : target.panel ? { ok: true, panel: target.panel } : { why: "gone" }),
     api: api || (async (path, body) => { sent.push(...body.events); return { state: "ready", sent: true }; }),
     requestAnimationFrame: cb => { setTimeout(cb, 0); return 1; },

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/page/pad_queue.mjs

@@ -8,7 +8,7 @@ const fail = msg => { console.log("FAIL " + msg); process.exit(1); };
 function page(api) {
   const pad = { state: "ready", queue: [], sending: false };
   const shown = [];
-  const fns = new Function("pad", "api", "padShow", "devGen", code + "; return { padSend, padFlush };")(pad, api, s => { shown.push(s); pad.state = s.state; }, 0);
+  const fns = new Function("pad", "api", "padShow", code + "; return { padSend, padFlush };")(pad, api, s => { shown.push(s); pad.state = s.state; });
   return { pad, shown, ...fns };
 }
 

tests/page/source_login.mjs

@@ -0,0 +1,79 @@
+// The store's "Add a source" login handling and GitHub token field, run in node against
+// the real functions from ui/index.html. A login typed into the address must leave the
+// address field (into the login fields) before anything is sent, and stay out of it.
+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 { moveLogin, sourceToken } = new Function(
+  "const esc = s => String(s).replace(/[&<>\"']/g, c => `&#${c.charCodeAt(0)};`); const storeName = s => s;\n" +
+  grab("decodeLenient") + grab("moveLogin") + grab("sourceToken") + "return { moveLogin, sourceToken };")();
+
+function form(url, username = "", password = "") {
+  const details = { open: false };
+  const field = value => ({ value, closest: () => details });
+  return { details, elements: { url: field(url), username: field(username), password: field(password) } };
+}
+
+let f = form("https://alice:s3cr%40t@repo.example/fdroid/repo");
+moveLogin(f);
+if (f.elements.url.value !== "https://repo.example/fdroid/repo") fail("address still holds the login: " + f.elements.url.value);
+if (f.elements.username.value !== "alice" || f.elements.password.value !== "s3cr@t") fail("login not moved into its fields");
+if (!f.details.open) fail("login fields not shown");
+
+f = form("https://alice:fromurl@repo.example/repo", "typed", "typedpw");
+moveLogin(f);
+if (f.elements.url.value.includes("fromurl") || f.elements.username.value !== "typed" || f.elements.password.value !== "typedpw")
+  fail("typed login replaced, or address kept the login");
+
+// Undecodable logins and unusual spellings the URL parser accepts still lose their login; undecodable bytes stay as typed.
+for (const [url, address, user, pass] of [
+  ["https://alice:100%done@repo.example/private/repo", "https://repo.example/private/repo", "alice", "100%done"],
+  ["https:\t//alice:s3cret@repo.example/repo", "https://repo.example/repo", "alice", "s3cret"],
+  ["ht\ntps://alice:s3cret@repo.example/repo", "https://repo.example/repo", "alice", "s3cret"],
+  ["https:alice:s3cret@repo.example/repo", "https://repo.example/repo", "alice", "s3cret"],
+  ["\u0000https://alice:s3cret@repo.example/repo", "https://repo.example/repo", "alice", "s3cret"],
+  ["https://alice:%FF@repo.example/private/repo", "https://repo.example/private/repo", "alice", "%FF"],
+  ["https://al%20ice:p%40ss:word@repo.example/r", "https://repo.example/r", "al ice", "p@ss:word"],
+  ["https://alice:p%FF\u00e4@repo.example/repo", "https://repo.example/repo", "alice", "p%FF\u00e4"],
+  ["fdroidrepos://alice:pw@repo.example/repo?fingerprint=AB", "fdroidrepos://repo.example/repo?fingerprint=AB", "alice", "pw"],
+  ["https://alice@repo.example/repo", "https://repo.example/repo", "alice", ""],
+]) {
+  f = form(url);
+  moveLogin(f);
+  if (f.elements.url.value !== address) fail(`address kept the login: ${url} -> ${f.elements.url.value}`);
+  if (f.elements.username.value !== user || f.elements.password.value !== pass)
+    fail(`login for ${url}: ${f.elements.username.value} / ${f.elements.password.value}`);
+}
+
+// An address the parser rejects that may hold a login is refused and left as typed, never sent.
+for (const url of ["https://alice\\name:pw@repo.example/repo", "https:\\\\alice:s3cret@repo.example/repo", "fdroidrepos://alice:p\\w@repo.example/repo", "https://alice:s3cret@repo example/repo", "https:alice:s3cret@repo example/repo", "https://repo.example:bad\\a@b"]) {
+  f = form(url);
+  if (moveLogin(f) !== false) fail("accepted an invalid address with a login: " + url);
+  if (f.elements.username.value || f.elements.password.value) fail("guessed a login from an invalid address: " + url);
+}
+
+for (const url of ["https://repo.example/repo", "not a url", "https://repo.example/a@b", "fdroidrepos:///a@b", "fdroidrepos:/a@b", "https://repo.example/r?x=a@b#c@d"]) {
+  f = form(url);
+  moveLogin(f);
+  if (f.elements.url.value !== url || f.elements.username.value) fail("changed an address without a login: " + url);
+}
+
+const html = sourceToken({ id: "github", name: "GitHub releases", token: { set: true, from: "saved", rejected: true } });
+if (!html.includes("rejected") || !html.includes('data-clear-token="github"')) fail("token row: " + html);
+if (sourceToken({ id: "fdroid", name: "F-Droid" }) !== "") fail("token field on a source without one");
+const slow = "https://a:" + "%FF".repeat(4000) + "@repo.example/r", t0 = Date.now();
+f = form(slow); moveLogin(f);
+if (Date.now() - t0 > 200 || f.elements.password.value !== "%FF".repeat(4000)) fail("decoding malformed escapes is slow or wrong");
+console.log("ok");

tests/page/store_detail.mjs

@@ -25,7 +25,7 @@ const code = names.map(grab).join("");
 
 // A fake page: elements by id. The install panel's elements exist only while
 // #detailBody holds the real app page, as in the browser.
-function page(api = async () => ({}), androidApps = []) {
+function page(api = async () => ({})) {
   const els = { appDetail: { open: false, scrollTop: 0, showModal() { this.open = true; } } };
   const inPage = id => ["detailInstall", "detailInstallNote", "detailProgress", "detailOffers"].includes(id);
   const $ = id => inPage(id) && !(els.detailBody?.innerHTML || "").includes(`id="${id}"`) ? null
@@ -34,8 +34,8 @@ function page(api = async () => ({}), androidApps = []) {
   const document = { activeElement: null, querySelector: () => null };
   const console = { error() {} };
   const calls = [];
-  const fns = new Function("$", "sourceState", "document", "console", "api", "androidApps", code + "; return { renderAppDetail, openStoreApp };")(
-    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); }, androidApps);
+  const fns = new Function("$", "sourceState", "document", "console", "api", code + "; return { renderAppDetail, openStoreApp };")(
+    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); });
   return { els, sourceState, calls, ...fns };
 }
 
@@ -54,14 +54,6 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
   if (html.includes('role="alert"')) fail("a good listing showed the error state");
 }
 
-// A catalogue listing that is already installed offers its management page.
-{
-  const p = page(undefined, [{ package: offer.package }]);
-  p.sourceState.detail = { app: { name: offer.name, offers: [{ ...offer }] }, choice: 0 };
-  if (p.renderAppDetail() !== true) fail("an installed listing reported a render failure");
-  if (p.els.detailInstall.textContent !== "View installed app") fail("installed listing offered another install");
-}
-
 // A listing that can't render (no offer to show) gets a clear message, not an empty dialog.
 {
   const p = page();

tests/standalone_review.cjs

@@ -1,219 +0,0 @@
-// Production standalone scripts with deterministic DOM/network boundaries. No browser/headset.
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const vm = require('node:vm');
-const root = process.env.STANDALONE_SOURCE_ROOT || path.resolve(__dirname, '..');
-const read = name => fs.readFileSync(path.join(root, 'ui', name), 'utf8');
-const script = html => html.match(/<script>([\s\S]*?)<\/script>/)[1];
-const tick = async () => { for (let i = 0; i < 16; i++) await Promise.resolve(); };
-
-function fixture(html) {
-  const elements = new Map(), events = new Map(), requests = [];
-  const document = {
-    activeElement: null,
-    getElementById: id => element(id),
-    querySelector: selector => selector === 'main' ? element('main') : document.querySelectorAll(selector)[0],
-    querySelectorAll: selector => [...elements.values()].flatMap(el => el.children).filter(el => el.matches(selector)),
-    addEventListener: (name, fn) => { if (!events.has(name)) events.set(name, []); events.get(name).push(fn); },
-  };
-  class Element {
-    constructor(id, attrs = '', text = '') {
-      this.id = id; this.dataset = {}; this.children = []; this.hidden = false; this.open = false;
-      this.isConnected = true; this.value = ''; this.checked = false; this.disabled = /\bdisabled\b/.test(attrs);
-      this.textContent = text; this.attrs = {}; this.listeners = new Map();
-      for (const [, key, value] of attrs.matchAll(/([\w-]+)="([^"]*)"/g)) {
-        this.attrs[key] = value;
-        if (key.startsWith('data-')) this.dataset[key.slice(5).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value;
-      }
-      for (const [, key] of attrs.matchAll(/\bdata-([\w-]+)(?=\s|$)/g)) if (!Object.hasOwn(this.dataset, key)) this.dataset[key] = '';
-    }
-    matches(s) {
-      if (s === 'button:not(:disabled)') return this.tag === 'button' && !this.disabled;
-      if (s.startsWith('#')) return this.id === s.slice(1);
-      const data = s.match(/\[data-([\w-]+)(?:="([^"]*)")?\]/);
-      if (data) return Object.hasOwn(this.dataset, data[1]) && (data[2] === undefined || this.dataset[data[1]] === data[2]);
-      return false;
-    }
-    set innerHTML(value) {
-      this.html = value;
-      for (const child of this.children) { child.isConnected = false; if (document.activeElement === child) document.activeElement = null; }
-      this.children = [...value.matchAll(/<(button|h2)\b([^>]*)>([\s\S]*?)<\/\1>/g)].map(([, tag, attrs, text]) => {
-        const child = new Element((attrs.match(/\bid="([^"]+)"/) || [])[1], attrs, text);
-        child.tag = tag; child.parent = this; return child;
-      });
-    }
-    get innerHTML() { return this.html || ''; }
-    querySelectorAll(s) { return this.children.filter(el => el.matches(s)); }
-    querySelector(s) { return this.querySelectorAll(s)[0] || null; }
-    contains(el) { return el === this || this.children.includes(el); }
-    closest(s) { return this.matches(s) ? this : this.parent?.closest(s) || null; }
-    setAttribute(k, v) { this.attrs[k] = v; }
-    append(el) { el.parent = this; }
-    focus() { if (!this.disabled && this.isConnected) document.activeElement = this; }
-    showModal() { this.open = true; this.modalOpened = true; }
-    close() { this.open = false; this.onclose?.(); }
-    addEventListener(name, fn) { this.listeners.set(name, fn); }
-    reset() {}
-  }
-  function element(id) {
-    const dynamic = [...elements.values()].flatMap(el => el.children).find(el => el.id === id);
-    if (dynamic) return dynamic;
-    if (!elements.has(id)) elements.set(id, new Element(id));
-    return elements.get(id);
-  }
-  element('detail').hidden = element('kbd').hidden = true;
-  document.body = element('body');
-  // The sheet is stable; its contents are replaced by the production redraw.
-  element('detail').contains = el => el === element('detail') || element('sheet').contains(el);
-  const context = {document, location: {search: '', hash: ''}, URLSearchParams,
-    window: {addEventListener: (name, fn) => events.set(name, [fn])},
-    setTimeout: () => 1, clearTimeout() {}, Event: class {},
-    fetch: (url, options) => new Promise((resolve, reject) => requests.push({url, options, resolve, reject})),
-  };
-  vm.createContext(context);
-  vm.runInContext(script(html).replace('__FRAME_KEY__', JSON.stringify('ios +&?key/#')), context);
-  const run = code => vm.runInContext(code, context);
-  const answer = async (index, data, ok = true) => { (typeof index === 'number' ? requests[index] : index).resolve({ok, json: async () => data}); await tick(); };
-  return {element, document, context, requests, run, answer, events};
-}
-
-test('Assistant Back encodes the injected key for the same-origin workspace only', () => {
-  const html = read('assistant.html'), f = fixture(html);
-  const back = f.element('back');
-  const fallback = html.match(/<a[^>]*href="([^"]*)"[^>]*>Back to Frame Control/)[1];
-  const destination = new URL(back.href || fallback, 'http://127.0.0.1:8123/assistant#confirm=private');
-  assert.equal(destination.origin, 'http://127.0.0.1:8123');
-  assert.equal(destination.pathname, '/');
-  assert.equal(destination.hash, '');
-  assert.equal(destination.searchParams.get('key'), 'ios +&?key/#');
-  const index = fs.readFileSync(path.join(__dirname, '../ui/index.html'), 'utf8');
-  const expression = index.match(/const UI_KEY = ([^;]+);/)[1];
-  assert.equal(vm.runInNewContext(expression, {URLSearchParams, location: {search: destination.search}}), 'ios +&?key/#');
-  for (const [, href] of html.matchAll(/href="(https?:[^\"]+)"/g)) assert.ok(!href.includes('key='));
-  assert.match(html, /referrerpolicy="no-referrer"/);
-});
-
-test('installed read failure is persistent, retry recovers, and cached entries are marked stale', async () => {
-  const f = fixture(read('store.html'));
-  f.run('st.view = "installed"; render()');
-  assert.doesNotMatch(f.element('content').innerHTML, /Nothing installed yet/);
-  f.requests[0].reject(Error('offline')); await tick();
-  assert.equal(f.run('st.installedState'), 'error');
-  assert.match(f.element('content').innerHTML, /data-retry-installed/);
-  assert.doesNotMatch(f.element('content').innerHTML, /Nothing installed yet/);
-  const retry = f.element('content').querySelector('[data-retry-installed]');
-  for (const listener of f.events.get('click')) listener({target: retry});
-  assert.equal(f.requests[1].url, '/api/android');
-  await f.answer(1, {apps: [{package: 'cached.app', label: 'Cached app'}]});
-  assert.equal(f.run('st.installedState'), 'ready');
-  const failed = f.run('loadInstalled()');
-  assert.match(f.element('content').innerHTML, /last (?:known|read)|stale/i);
-  f.requests[2].reject(Error('refresh failed')); await failed;
-  assert.match(f.element('content').innerHTML, /Cached app/);
-  assert.match(f.element('content').innerHTML, /last (?:known|read)|stale/i);
-  assert.match(f.element('content').innerHTML, /data-retry-installed/);
-  const empty = f.run('loadInstalled()'); await f.answer(3, {apps: []}); await empty;
-  assert.match(f.element('content').innerHTML, /Nothing installed yet/);
-  assert.doesNotMatch(f.element('content').innerHTML, /data-retry-installed/);
-});
-
-test('newest installed read wins over older success and failure without pruning cached data', async () => {
-  const f = fixture(read('store.html'));
-  f.run('st.needsData.add("new.app"); st.jobs.set("data:new.app", {done: false})');
-  const newer = f.run('loadInstalled()'); await f.answer(1, {apps: [{package: 'new.app', label: 'New app'}]}); await newer;
-  await f.answer(0, {apps: []});
-  assert.equal(f.run('st.installed.has("new.app")'), true);
-  assert.equal(f.run('st.needsData.has("new.app")'), true);
-  const old = f.run('loadInstalled()'), newest = f.run('loadInstalled()');
-  await f.answer(4, {apps: []}); await newest; // bootstrap's catalogue search is request 2
-  f.requests[3].reject(Error('late failure')); await old;
-  assert.equal(f.run('st.installedState'), 'ready');
-  assert.equal(f.run('st.installedError'), '');
-  assert.equal(f.run('st.installed.size'), 0);
-});
-
-test('an old success cannot mask the newest failure, and malformed data is not successful empty', async () => {
-  const f = fixture(read('store.html'));
-  f.run('st.view = "installed"');
-  const newest = f.run('loadInstalled()'); f.requests[1].reject(Error('latest offline')); await newest;
-  await f.answer(0, {apps: []});
-  assert.equal(f.run('st.installedState'), 'error');
-  assert.equal(f.run('st.installedError'), 'latest offline');
-  assert.doesNotMatch(f.element('content').innerHTML, /Nothing installed yet/);
-  const malformed = f.run('loadInstalled()'); await f.answer(2, {}); await malformed;
-  assert.equal(f.run('st.installedState'), 'error');
-  assert.match(f.element('content').innerHTML, /data-retry-installed/);
-});
-
-test('catalogue details distinguish unknown and stale installed state', async () => {
-  const f = fixture(read('store.html'));
-  f.context.app = {name: 'Example', package: 'example.app', detailed: true, offers: [{source: 'test', id: 'example'}]};
-  f.run('openDetail(app)');
-  assert.doesNotMatch(f.element('sheet').innerHTML, /data-act="install"/);
-  f.requests[0].reject(Error('offline')); await tick();
-  assert.doesNotMatch(f.element('sheet').innerHTML, /data-act="install"/);
-  const loaded = f.run('loadInstalled()'); await f.answer(f.requests.at(-1), {apps: []}); await loaded;
-  assert.match(f.element('sheet').innerHTML, /data-act="install"/);
-});
-
-test('named native Store dialog enters, contains and restores focus across async redraws', async () => {
-  const html = read('store.html');
-  assert.match(html.match(/<[^>]*id="detail"[^>]*>/)[0], /<dialog\b[^>]*aria-labelledby="detailTitle"/);
-  const f = fixture(html);
-  await f.answer(0, {apps: []});
-  f.context.app = {name: 'Example', offers: [{source: 'test', id: 'example'}]};
-  f.run('st.view = "games"; st.apps = [app]; st.loading = false; render()');
-  const opener = f.element('content').querySelector('[data-i="0"]'); opener.focus();
-  f.run('openDetail(app)');
-  assert.equal(f.element('detail').modalOpened, true);
-  assert.equal(f.element('toast').parent, f.element('detail'));
-  assert.equal(f.document.activeElement.id, 'detailTitle');
-  const install = f.element('sheet').querySelector('[data-act="install"]'); install.focus();
-  await f.answer(2, {description: 'Details arrived'}); // request 1 is bootstrap search
-  assert.equal(f.document.activeElement.dataset.act, 'install');
-  assert.notEqual(f.document.activeElement, install);
-  const close = f.element('sheet').querySelector('[data-act="close"]'); close.focus();
-  f.run('st.jobs.set("test:example", {done: false, stage: "Downloading", percent: 20}); drawDetail(); render()');
-  assert.equal(f.document.activeElement.dataset.act, 'close');
-  const keydown = f.element('detail').onkeydown || f.element('detail').listeners.get('keydown');
-  const event = {key: 'Tab', shiftKey: false, preventDefault() {this.prevented = true;}};
-  keydown(event);
-  assert.equal(event.prevented, true);
-  assert.equal(f.document.activeElement.dataset.act, 'close'); // only remaining action
-  f.run('st.jobs.delete("test:example"); drawDetail()');
-  const first = f.element('sheet').querySelector('[data-act="install"]'); first.focus();
-  const reverse = {key: 'Tab', shiftKey: true, preventDefault() {this.prevented = true;}}; keydown(reverse);
-  assert.equal(reverse.prevented, true); assert.equal(f.document.activeElement.dataset.act, 'close');
-  first.focus(); f.run('st.jobs.set("test:example", {done: false}); drawDetail()');
-  assert.equal(f.document.activeElement.dataset.act, 'close'); // focused action disappeared
-  f.run('closeDetail()');
-  assert.equal(f.element('detail').open, false);
-  assert.equal(f.element('toast').parent, f.document.body);
-  assert.equal(f.document.activeElement.dataset.i, '0');
-  assert.notEqual(f.document.activeElement, opener); // render replaced the background card
-});
-
-test('dialog Retry recovers installed knowledge without losing focus, and cancel restores its opener', async () => {
-  const f = fixture(read('store.html'));
-  f.context.app = {name: 'Example', detailed: true, offers: [{source: 'test', id: 'example'}]};
-  f.run('st.view = "games"; st.apps = [app]; render()');
-  const opener = f.element('content').querySelector('[data-i="0"]'); opener.focus();
-  f.run('openDetail(app)');
-  f.requests[0].reject(Error('offline')); await tick();
-  await f.answer(1, {apps: [f.context.app], sources: []});
-  const retry = f.element('sheet').querySelector('[data-retry-installed]'); retry.focus();
-  for (const listener of f.events.get('click')) listener({target: retry});
-  assert.equal(f.document.activeElement.dataset.act, 'close');
-  await f.answer(f.requests.at(-1), {apps: []});
-  assert.equal(f.document.activeElement.dataset.act, 'close');
-  assert.match(f.element('sheet').innerHTML, /data-act="install"/);
-  const cancel = {preventDefault() {this.prevented = true;}};
-  f.element('detail').oncancel(cancel);
-  assert.equal(cancel.prevented, true); assert.equal(f.element('detail').open, false);
-  assert.equal(f.document.activeElement.dataset.i, '0');
-  // Removing the app while details are open falls back to Search on close.
-  f.run('openDetail(app); st.apps = []; render(); closeDetail()');
-  assert.equal(f.document.activeElement, f.element('q'));
-});

tests/test_apk_artwork.py

@@ -19,9 +19,7 @@ class ArtworkTests(unittest.TestCase):
     def setUp(self):
         with _images._lock:
             _images._urls.clear()
-            _images._tokens.clear()
             _images._cache.clear()
-            _images._dns.clear()
 
     def test_only_registered_source_images_are_fetchable(self):
         with patch.object(_images, 'fetch') as fetch:
@@ -73,13 +71,9 @@ class ArtworkTests(unittest.TestCase):
             _images.remember('https://example.com/a.png', PNG[:8] + b'x' * _images.MAX_IMAGE)
 
     def test_handles_are_bounded(self):
-        with patch.object(_images, 'MAX_TOKENS', 50):
-            first = _images.register('https://example.com/0.png')
-            for i in range(1, 60):
-                _images.register('https://example.com/%d.png' % i)
-            self.assertEqual((len(_images._urls), len(_images._tokens)), (50, 50))
-            self.assertNotEqual(_images.register('https://example.com/0.png'), first)  # forgotten, so a new handle
-            self.assertEqual(_images.register('https://example.com/59.png'), _images.register('https://example.com/59.png'))
+        for i in range(4100):
+            _images.register('https://example.com/%d.png' % i)
+        self.assertEqual(len(_images._urls),4096)
 
     def test_plain_language_verdict_is_evidence_based(self):
         self.assertEqual(search.verdict({})['label'], 'Not yet checked on the Frame')

tests/test_apk_search.py

@@ -122,7 +122,7 @@ class SearchTests(SettingsTest):
                     break
                 time.sleep(.01)
             self.assertTrue(arrived[1]['event'].wait(2))
-        self.assertEqual(arrived[1]['query'][:2], ('second', 50))
+        self.assertEqual(arrived[1]['query'], ('second', 50))
 
     def test_set_enabled_does_not_hold_search_lock_in_source(self):
         free = []
@@ -325,7 +325,7 @@ class EndpointTests(SettingsTest):
             mod.add_repo.side_effect = SourceError('repository fingerprint mismatch')
             job = self.wait(self.request('POST', '/api/sources', {'action': 'add', 'url': link})[1]['job'])
             self.assertEqual(job['error'], 'repository fingerprint mismatch')  # no "SourceError:" prefix
-            for url in ('http://repo.example/repo', 'fdroidrepo://repo.example/repo', 'https://u@repo.example/'):
+            for url in ('http://repo.example/repo', 'fdroidrepo://repo.example/repo', 'https://repo.example:x/'):
                 self.assertEqual(self.request('POST', '/api/sources', {'action': 'add', 'url': url})[0], 400)
             self.assertEqual(self.request('POST', '/api/sources', {'action': 'remove', 'source': 'fdroid'})[0], 200)
             mod.remove_repo.assert_called_once_with(source_id='fdroid')

tests/test_client_preferences.py

@@ -1,14 +0,0 @@
-"""Exercise the production preference bootstrap across separate web origins."""
-import shutil
-import subprocess
-import unittest
-from pathlib import Path
-
-
-@unittest.skipUnless(shutil.which('node'), 'Node exercises the shared page behavior')
-class ClientPreferences(unittest.TestCase):
-    def test_behavior(self):
-        root = Path(__file__).resolve().parents[1]
-        result = subprocess.run(['node', '--test', str(root / 'tests/client_preferences.cjs')],
-                                capture_output=True, text=True)
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

tests/test_control_center.py

@@ -63,20 +63,6 @@ class Coverage(unittest.TestCase):
         self.assertIn('*.js', ui['filter'])
         self.assertIn('*.css', ui['filter'])
 
-    def test_bundle_runs_the_server_on_its_own(self):
-        # The iPhone app and scripts/store-on-frame.sh start ui/server.py from this bundle alone.
-        import io, tarfile, tempfile
-        spec = importlib.util.spec_from_file_location('frame_bundle_run', ROOT / 'ios/scripts/make_frame_bundle.py')
-        bundle = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(bundle)
-        with tempfile.TemporaryDirectory() as tmp, tarfile.open(fileobj=io.BytesIO(bundle.build()), mode='r:gz') as tar:
-            tar.extractall(tmp)
-            result = subprocess.run([sys.executable, '-I', '-B', '-c',
-                                     'import sys; sys.path.insert(0, "ui"); import server, apk_sources.search; '
-                                     'apk_sources.search.modules()[1] and sys.exit("source modules failed: %r" % apk_sources.search.modules()[1])'],
-                                    cwd=tmp, capture_output=True, text=True, timeout=60)
-        self.assertEqual(result.returncode, 0, result.stderr[-2000:])
-
     def test_status_exposes_kernel_thermal_trips_without_guessing_thresholds(self):
         # Run the real aggregator with every external probe stubbed.
         names = ('read', 'process_names', 'performance', 'os_release', 'battery', 'power_source',

tests/test_devices.py

@@ -323,6 +323,20 @@ class Pins(Base):
 
 
 class Registry(Base):
+    def test_an_address_added_first_wins_on_its_own_network(self):
+        # The page's "Add 192.168.x.x" offer: the headset is reached over Tailscale, which has
+        # worked here before. The LAN address has to go ahead of it to be used at home.
+        d = self.reg.add_device("frame-4", hosts=["frame.tail1234.ts.net"])
+        self.reg.record_success(d["id"], "frame.tail1234.ts.net", "n-home", 6.0)
+        self.reg.add_address(d["id"], "192.168.1.40", kind="lan", first=True)
+        self.reg.record_success(d["id"], "192.168.1.40", "n-home", 1.0)  # Test now found it
+        addrs = self.reg.get(d["id"])["addresses"]
+        self.assertEqual([a["host"] for a in addrs], ["192.168.1.40", "frame.tail1234.ts.net"])
+        at_home = [a["host"] for a, _ in fd.order_addresses(addrs, "n-home", True)]
+        self.assertEqual(at_home[0], "192.168.1.40")
+        away = [a["host"] for a, _ in fd.order_addresses(addrs, "n-cafe", True)]
+        self.assertEqual(away[0], "frame.tail1234.ts.net")  # elsewhere Tailscale still leads
+
     def test_address_editing(self):
         d = self.reg.add_device("frame-3", hosts=["192.168.1.40"])
         a = self.reg.add_address(d["id"], "frame-3.local", label="mDNS")

tests/test_fdroid_sources.py

@@ -81,7 +81,7 @@ class Repositories(unittest.TestCase):
             state.clear()
             self.addCleanup(state.clear)
 
-    def fetch(self, url, path, maximum):
+    def fetch(self, url, path, maximum, auth=None):
         name = url.rsplit('/', 1)[-1]
         if self.v1 and name == 'entry.jar':
             raise urllib.error.HTTPError(url, 404, 'missing', None, None)
@@ -311,7 +311,7 @@ class Repositories(unittest.TestCase):
         source = self.add()
         other = dict(source, id='other-repo')
         started, release = threading.Event(), threading.Event()
-        def fetch(url, path, maximum):
+        def fetch(url, path, maximum, auth=None):
             if threading.current_thread().name == 'slow':
                 started.set()
                 release.wait(5)
@@ -355,7 +355,7 @@ class Repositories(unittest.TestCase):
         self.files['entry.jar'], _ = entry_jar(50)
         source = fdroid.add_repo(URL)
         jars = {'older': entry_jar(100)[0], 'newer': entry_jar(200)[0]}
-        def fetch(url, path, maximum):
+        def fetch(url, path, maximum, auth=None):
             name = threading.current_thread().name
             if name in jars and url.endswith('entry.jar'):
                 Path(path).write_bytes(jars[name])
@@ -401,7 +401,7 @@ class Repositories(unittest.TestCase):
         source = dict(id='overlap', name='Overlap', url=URL, fingerprint=None)
         self.v1 = True
         inner = []
-        def fetch(url, path, maximum):
+        def fetch(url, path, maximum, auth=None):
             if url.endswith('index-v1.jar') and not inner:
                 inner.append(1)  # the v1 load passed its fallback check; a v2 load finishes now
                 self.v1 = False
@@ -471,7 +471,7 @@ class Repositories(unittest.TestCase):
         source = self.add()
         self.expire(source)
         release = threading.Event()
-        def slow(url, path, maximum):
+        def slow(url, path, maximum, auth=None):
             release.wait(5)
             self.fetch(url, path, maximum)
         self.fetch_mock.side_effect = slow
@@ -528,7 +528,7 @@ class Repositories(unittest.TestCase):
         self.expire(source)
         before = self.fetch_mock.call_count
         release = __import__('threading').Event()
-        def slow(url, path, maximum):
+        def slow(url, path, maximum, auth=None):
             release.wait(5)
             self.fetch(url, path, maximum)
         self.fetch_mock.side_effect = slow

tests/test_frame_android_library.py

@@ -121,11 +121,26 @@ class LauncherTests(unittest.TestCase):
 FIXTURES = ROOT / 'tests/fixtures/library'
 
 
+def wait_for_idle_resolvers(timeout=10):
+    # Name lookups that outlast their deadline give their slot back from their own thread,
+    # which a busy runner may not schedule before the next test; wait until all are back.
+    from apk_sources import _images
+    held = []
+    try:
+        end = time.monotonic() + timeout
+        while _images._resolvers.acquire(timeout=max(0, end - time.monotonic())):
+            held.append(1)
+            if len(held) == 4:
+                return
+        raise AssertionError('artwork name lookups from an earlier test are still running')
+    finally:
+        for _ in held:
+            _images._resolvers.release()
+
+
 class ArtworkTests(unittest.TestCase):
     def setUp(self):
-        from apk_sources import _images
-        _images._dns.clear()  # each test answers lookups its own way
-        self.addCleanup(_images._dns.clear)
+        wait_for_idle_resolvers()
 
     def test_source_inputs_and_url(self):
         from apk_sources import _images
@@ -237,10 +252,7 @@ class ArtworkTests(unittest.TestCase):
             self.assertEqual(sum('Too many' in e for e in errors), 2)
         finally:
             gate.set()
-        deadline = time.monotonic() + 5
-        while time.monotonic() < deadline and not _images._resolvers.acquire(blocking=False):
-            time.sleep(0.01)
-        _images._resolvers.release()  # the stuck lookups finished and gave their slots back
+        wait_for_idle_resolvers()  # the stuck lookups finished and gave their slots back
 
     def test_resolver_slot_released_when_thread_cannot_start(self):
         from apk_sources import _images
@@ -248,10 +260,14 @@ class ArtworkTests(unittest.TestCase):
             for _ in range(6):
                 with self.assertRaises(RuntimeError):
                     _images.get('https://example.org/a.png', deadline=time.monotonic() + 1)
-        for _ in range(4):  # every slot came back
-            self.assertTrue(_images._resolvers.acquire(blocking=False))
-        for _ in range(4):
-            _images._resolvers.release()
+        held = 0
+        try:
+            while held < 4 and _images._resolvers.acquire(blocking=False):
+                held += 1
+            self.assertEqual(held, 4)  # every slot came back
+        finally:
+            for _ in range(held):  # even on failure, so later tests don't inherit the leak
+                _images._resolvers.release()
 
     def test_deadline_covers_name_resolution(self):
         import threading

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_ios_contracts.py

@@ -1,175 +0,0 @@
-"""iPhone packaging and Foundation contracts; no headset, downloads or Xcode build."""
-import sandbox  # noqa: F401
-import fnmatch
-import importlib.util
-import io
-import json
-from pathlib import Path
-import shutil
-import subprocess
-import sys
-import tarfile
-import tempfile
-import unittest
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-class BundleContracts(unittest.TestCase):
-    @classmethod
-    def setUpClass(cls):
-        spec = importlib.util.spec_from_file_location("ios_bundle_contract", ROOT / "ios/scripts/make_frame_bundle.py")
-        cls.bundle = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(cls.bundle)
-        cls.tmp = tempfile.TemporaryDirectory()
-        cls.root = Path(cls.tmp.name)
-        with tarfile.open(fileobj=io.BytesIO(cls.bundle.build()), mode="r:gz") as archive:
-            archive.extractall(cls.root)
-
-    @classmethod
-    def tearDownClass(cls):
-        cls.tmp.cleanup()
-
-    def test_required_resources_ship_to_both_clients(self):
-        resources = ["frame/android/library_artwork.js", "frame/openxr-compat/XrApiLayer_FRAME_compat.json",
-                     "frame/openxr-compat/prebuilt/arm64-v8a/libXrApiLayer_FRAME_compat.so.gz"]
-        config = json.loads((ROOT / "app/package.json").read_text())
-        for resource in resources:
-            with self.subTest(resource=resource):
-                self.assertTrue((self.root / resource).is_file(), resource)
-                # Match the desktop's real resource filters as well as the phone archive.
-                packaged = False
-                for entry in config["build"]["extraResources"]:
-                    source = entry["from"].removeprefix("../")
-                    if Path(resource).is_relative_to(source):
-                        relative = str(Path(resource).relative_to(source))
-                        packaged |= any(fnmatch.fnmatch(relative, pattern) for pattern in entry.get("filter", ["**/*"]))
-                self.assertTrue(packaged, "desktop resource contract: " + resource)
-
-    def test_extracted_runtime_can_render_and_load_xr_layer(self):
-        result = subprocess.run([sys.executable, "-I", "-B", "-c", """
-import sys, zipfile
-from unittest.mock import patch
-sys.path.insert(0, 'ui')
-import frame_android as android
-with patch.object(android, 'ssh', return_value='rendered') as ssh:
-    assert android.shortcut_tool('render', '/synthetic/app') == 'rendered'
-    assert 'ART_RENDERER = ' in ssh.call_args.kwargs['input']
-    assert len(ssh.call_args.kwargs['input']) > 1000
-with zipfile.ZipFile('synthetic.apk', 'w') as apk:
-    apk.writestr('lib/arm64-v8a/libopenxr_loader.so', b'synthetic loader')
-files = android.xr_compat_files('synthetic.apk')
-assert set(files) == set(android.XR_COMPAT_FILES)
-assert files['lib/arm64-v8a/libXrApiLayer_FRAME_compat.so'].startswith(b'\\x7fELF')
-"""], cwd=self.root, capture_output=True, text=True, timeout=30)
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-
-
-class NativeContracts(unittest.TestCase):
-    @unittest.skipUnless(sys.platform == "darwin" and shutil.which("swiftc"), "macOS Swift compiles actual Foundation production sources")
-    def test_foundation_contracts(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            main = Path(tmp) / "main.swift"
-            main.write_text("import XCTest\nlet suite = XCTestSuite(forTestCaseClass: NativeSessionTests.self)\nsuite.run()\nexit(suite.testRun!.hasSucceeded ? 0 : 1)\n")
-            executable = Path(tmp) / "native-contracts"
-            developer = subprocess.check_output(["xcode-select", "-p"], text=True).strip()
-            frameworks = str(Path(developer) / "Platforms/MacOSX.platform/Developer/Library/Frameworks")
-            libraries = str(Path(developer) / "Platforms/MacOSX.platform/Developer/usr/lib")
-            shared = str(Path(developer).parent / "SharedFrameworks")
-            result = subprocess.run(["swiftc", "-I", libraries, "-L", libraries, "-F", frameworks, "-Xlinker", "-rpath", "-Xlinker", frameworks,
-                                     "-Xlinker", "-rpath", "-Xlinker", libraries,
-                                     "-Xlinker", "-rpath", "-Xlinker", shared,
-                                     "-D", "NATIVE_CONTRACT_STANDALONE",
-                                     str(ROOT / "ios/FrameControl/App/NativeSessionState.swift"),
-                                     str(ROOT / "ios/FrameControlTests/NativeSessionTests.swift"),
-                                     str(main), "-o", str(executable)], capture_output=True, text=True, timeout=60)
-            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-            result = subprocess.run([str(executable)], capture_output=True, text=True, timeout=30)
-            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-            self.assertIn("Executed 5 tests", result.stdout + result.stderr)
-
-    @unittest.skipUnless(sys.platform == "darwin" and shutil.which("swiftc"), "macOS exercises the production finder with controlled probes")
-    def test_finder_ignores_late_probes_after_edit_and_stop(self):
-        harness = r'''import Foundation
-actor Probes {
-    var pending: [String: CheckedContinuation<Bool, Never>] = [:]
-    func probe(_ host: String) async -> Bool {
-        await withCheckedContinuation { pending[host] = $0 }
-    }
-    func has(_ host: String) -> Bool { pending[host] != nil }
-    func answer(_ host: String) { pending.removeValue(forKey: host)!.resume(returning: true) }
-}
-@main struct FinderContracts {
-    @MainActor static func wait(_ condition: () async -> Bool) async {
-        for _ in 0..<100 {
-            if await condition() { return }
-            try! await Task.sleep(nanoseconds: 5_000_000)
-        }
-        fatalError("controlled callback did not run")
-    }
-    @MainActor static func main() async {
-        let probes = Probes()
-        let finder = FrameFinder(probe: { await probes.probe($0) }, discoveryEnabled: false)
-        finder.start(fallback: "old.local")
-        await wait { await probes.has("old.local") }
-        finder.start(fallback: "100.100.100.2:2222", manual: true)
-        await wait { await probes.has("100.100.100.2:2222") }
-        await probes.answer("old.local")
-        // Let the cancelled task return its deliberately late successful answer.
-        try! await Task.sleep(nanoseconds: 20_000_000)
-        precondition(finder.found == nil, "A stale probe replaced the edited target")
-        await probes.answer("100.100.100.2:2222")
-        await wait { finder.found != nil }
-        precondition(finder.found?.host == "100.100.100.2:2222")
-        finder.start(fallback: "stopped.local", manual: true)
-        await wait { await probes.has("stopped.local") }
-        finder.stop()
-        await probes.answer("stopped.local")
-        try! await Task.sleep(nanoseconds: 20_000_000)
-        precondition(finder.found == nil, "A stopped search published a result")
-        print("Production FrameFinder: stale and cancelled probes ignored; manual target retained")
-    }
-}
-'''
-        with tempfile.TemporaryDirectory() as tmp:
-            main = Path(tmp) / "FinderContracts.swift"
-            main.write_text(harness)
-            executable = Path(tmp) / "finder-contracts"
-            result = subprocess.run(["swiftc", "-parse-as-library",
-                                     str(ROOT / "ios/FrameControl/App/NativeSessionState.swift"),
-                                     str(ROOT / "ios/FrameControl/SSH/FrameFinder.swift"),
-                                     str(main), "-o", str(executable)], capture_output=True, text=True, timeout=60)
-            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-            result = subprocess.run([str(executable)], capture_output=True, text=True, timeout=15)
-            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-
-    @unittest.skipUnless(shutil.which("node"), "Node executes the unmodified production bridge script")
-    def test_bridge_preferences_and_document_acknowledgement(self):
-        source = (ROOT / "ios/FrameControl/Web/WebShell.swift").read_text()
-        bridge = source.split('static let bridge = """', 1)[1].split('"""', 1)[0]
-        script = r'''const vm = require('node:vm');
-const assert = require('node:assert/strict');
-const calls = [];
-const window = {webkit: {messageHandlers: {frameApp: {postMessage: body => {calls.push(body); return Promise.resolve(true)}}}}};
-vm.runInNewContext(process.argv[1], {window, crypto: {randomUUID: () => 'document-42'}});
-assert.equal(window.__frameInstallLink({}), false);
-window.frameApp.preferences.read();
-window.frameApp.preferences.write('mvSeparate', '0');
-assert.equal(JSON.stringify(calls), JSON.stringify([
-  {name: 'preferencesRead', arg: null}, {name: 'preferencesWrite', arg: {key: 'mvSeparate', value: '0'}}
-]));
-const received = [];
-window.frameApp.onInstallLink(req => received.push(req));
-assert.equal(calls.at(-1).name, 'installLinkReady');
-assert.equal(calls.at(-1).arg, 'document-42');
-assert.equal(window.__frameInstallLink({target: 'a'}), true);
-assert.equal(received[0].target, 'a');
-window.frameApp.onInstallLink(() => {throw new Error('callback failed')});
-assert.throws(() => window.__frameInstallLink({}), /callback failed/);
-'''
-        result = subprocess.run(["node", "-e", script, bridge], capture_output=True, text=True, timeout=15)
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_link.py

@@ -897,6 +897,47 @@ class Connecting(unittest.TestCase):
         self.assertEqual(self.routes, [])
         self.assertTrue(all("ControlPath=none" in c for c in self.calls() if "-G" not in c))
 
+    def test_a_test_started_earlier_cant_overwrite_a_newer_one(self):
+        d = self.device("nothing.invalid")
+        entered = {1: threading.Event(), 2: threading.Event()}
+        release = {1: threading.Event(), 2: threading.Event()}
+        calls = []
+
+        def probe(host, port, update=None):
+            calls.append(host)
+            n = len(calls)
+            entered[n].set()
+            release[n].wait(10)
+            return {"state": "refused", "detail": f"test {n}", "ip": None, "rtt_ms": None}
+
+        tests = [threading.Thread(target=self.link.test, args=(d["id"],), daemon=True) for _ in range(2)]
+        with mock.patch.object(fl, "probe", probe):
+            try:
+                tests[0].start()
+                self.assertTrue(entered[1].wait(5), "the first test never probed")
+                tests[1].start()
+                self.assertTrue(entered[2].wait(5), "the second test never probed")
+                # The first finishes while the second is still probing: it mustn't show its
+                # rows or mark the second done.
+                release[1].set()
+                tests[0].join(10)
+                self.assertFalse(tests[0].is_alive())
+                running = self.link.snapshot()["tests"][d["id"]]
+                self.assertFalse(running["done"])
+                self.assertEqual(running["rows"][0]["detail"], "Waiting")
+                release[2].set()
+                tests[1].join(10)
+                self.assertFalse(tests[1].is_alive())
+            finally:
+                for e in release.values():
+                    e.set()
+                for t in tests:
+                    if t.ident:  # started
+                        t.join(10)
+        result = self.link.snapshot()["tests"][d["id"]]
+        self.assertTrue(result["done"])
+        self.assertEqual(result["rows"][0]["detail"], "test 2")
+
     def test_switching_to_a_headset_that_never_answers_stops_using_the_last_one(self):
         self.device("localhost")
         self.hosts({"localhost": "ok"})

tests/test_link_ui.py

@@ -56,18 +56,19 @@ class LinkUI(unittest.TestCase):
         r = subprocess.run(["node", "-e", script], capture_output=True, text=True)
         self.assertEqual(r.returncode, 0, r.stderr)
 
-    def test_the_pill_leads_with_the_reason(self):
-        # The header pill cut off "Offline: checking the headset's identity failed · retry in…":
-        # the reason comes first, in a few words, and only the countdown gets cut.
+    def test_the_pill_keeps_the_failure_detail_in_its_tooltip(self):
+        # The connection redesign keeps the state and retry countdown in the pill,
+        # with the full failure explanation in its tooltip and details dialog.
         self.run_page(r'''
   link.s = changed;
   renderPill();
-  assert.match($('conn').innerHTML, /<b>Office Frame<\/b><span>SSH identity changed · retry in 12 s<\/span>/);
-  assert.equal($('conn').title, 'Office Frame is offline: SSH identity changed · retry in 12 s. Click for details.');
+  assert.match($('conn').innerHTML, /<b>Office Frame<\/b><span>Offline<span class="via"> · retrying in 12 s<\/span>/);
+  assert.ok($('conn').title.includes(changed.error.message));
   // Without a short reason: the stage that failed.
   link.s = {...changed, retry_at: null, error: {stage: 'identity', message: 'Something.'}};
   renderPill();
-  assert.match($('conn').innerHTML, /<span>Checking the headset&#39;s identity failed<\/span>/);
+  assert.match($('conn').innerHTML, /<span>Offline<\/span>/);
+  assert.ok($('conn').title.includes('Something.'));
 ''')
 
     def test_the_banner_never_doubles_a_full_stop(self):

tests/test_server.py

@@ -88,12 +88,6 @@ class ServerGuards(unittest.TestCase):
                 self.assertIn(mime, headers['Content-Type'])
                 self.assertIn(marker, payload)
 
-    def test_store_page_served_with_anti_framing_headers(self):
-        status, headers, payload = self.request("GET", "/store")
-        self.assertEqual(status, 200)
-        self.assertEqual(headers["X-Frame-Options"], "DENY")
-        self.assertIn(b"<title>APK Store</title>", payload)
-
     def test_foreign_host_rejected(self):
         # DNS rebinding: a hostile name pointed at 127.0.0.1.
         for path in ("/", "/api/status"):
@@ -478,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):

tests/test_service_regressions.py

@@ -1,761 +0,0 @@
-"""Offline production-seam coverage for SERVICES01–04; no headset or provider calls."""
-import sandbox  # noqa: F401
-import contextlib
-import hashlib
-import json
-import os
-from pathlib import Path
-import shutil
-import subprocess
-import sys
-import tempfile
-import threading
-import unittest
-from unittest import mock
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
-import server
-import frame_agent as agent
-import frame_android as android
-
-
-class TargetTests(unittest.TestCase):
-    def setUp(self):
-        self.active = {'id': 'a', 'name': 'Headset A'}
-        self.link = mock.Mock()
-        self.link.active_device.side_effect = lambda: dict(self.active)
-        self.stack = contextlib.ExitStack()
-        self.addCleanup(self.stack.close)
-        self.stack.enter_context(mock.patch.object(server, 'LINK', self.link))
-        self.stack.enter_context(mock.patch.object(server, 'PRIVATE', False))
-        self.stack.enter_context(mock.patch.object(server, '_work', [0]))
-        self.stack.enter_context(mock.patch.object(server, '_backfill', {'running': False, 'last': 0.0}))
-        self.stack.enter_context(mock.patch.object(server.macview, 'retarget'))
-        self.stack.enter_context(mock.patch.object(server._input, 'stop'))
-        self.stack.enter_context(mock.patch.object(server.frame_link, 'devices_action', self.switch))
-
-    def switch(self, link, body, setup, busy):
-        if busy():
-            raise server.frame_devices.DeviceError('Wait for work')
-        self.active.update(id='b', name='Headset B')
-        return {'message': 'switched'}
-
-    def test_route_closes_touch_and_never_sends_to_old_process(self):
-        touch = server.TouchAgent()
-        proc = mock.Mock()
-        proc.poll.return_value = None
-        touch.proc, touch.status = proc, {'state': 'ready'}
-        before = (server.FRAME, list(server.HOST_OPTS))
-        try:
-            with mock.patch.object(server, '_touch', touch), mock.patch.object(touch, 'start'):
-                server.route('headset-b', [])
-                result = server.remote_touch({'events': [{'dx': 17, 'dy': -4}]})
-                self.assertFalse(result['sent'])
-                self.assertEqual(touch.status['state'], 'off')
-                proc.stdin.write.assert_not_called()
-                self.assertTrue(proc.stdin.close.called or proc.terminate.called)
-        finally:
-            server.route(*before)
-
-    def test_route_invalidates_touch_start_already_inside_popen(self):
-        touch = server.TouchAgent()
-        touch.launching = touch.generation
-        proc = mock.Mock()
-        proc.poll.return_value = None
-        entered, release = threading.Event(), threading.Event()
-        before = (server.FRAME, list(server.HOST_OPTS))
-        def popen(*a, **kw):
-            entered.set()
-            if not release.wait(2):
-                raise AssertionError('test did not release launch')
-            return proc
-        with mock.patch.object(server, '_touch', touch), \
-                mock.patch.object(server, 'ensure_master'), \
-                mock.patch.object(server.subprocess, 'Popen', side_effect=popen), \
-                mock.patch.object(touch, '_watch', return_value=(False, True)):
-            thread = threading.Thread(target=touch._launch, args=(0,))
-            thread.start()
-            try:
-                self.assertTrue(entered.wait(2))
-                server.route('headset-b', [])
-                release.set()
-                thread.join(2)
-                self.assertFalse(thread.is_alive())
-                self.assertIsNone(touch.proc)
-                self.assertEqual(touch.status['state'], 'off')
-                self.assertTrue(proc.terminate.called or proc.stdin.close.called)
-            finally:
-                release.set()
-                thread.join(2)
-                server._live_tunnels.discard(proc)
-                server.route(*before)
-
-    def test_backfill_counts_work_until_error_cleanup(self):
-        entered, release = threading.Event(), threading.Event()
-        writes = []
-        def check(*a, **kw):
-            entered.set()
-            if not release.wait(2):
-                raise AssertionError('test did not release backfill')
-        def refresh(*a, **kw):
-            writes.append(self.active['id'])
-            raise RuntimeError('art failure')
-        original = server.threading.Thread
-        threads = []
-        def thread_factory(*a, **kw):
-            thread = original(*a, **kw)
-            threads.append(thread)
-            return thread
-        with mock.patch.object(server.frame_android, 'shortcut_tool', side_effect=check), \
-                mock.patch.object(server.frame_android, 'refresh_art', side_effect=refresh), \
-                mock.patch.object(server.threading, 'Thread', side_effect=thread_factory):
-            server.backfill_art(apps=[{'package': 'org.test.app', 'art_pending': True}])
-            try:
-                self.assertTrue(entered.wait(2))
-                self.assertGreater(server._work[0], 0)
-                with self.assertRaises(server.Failure):
-                    server.devices_post({'action': 'use', 'id': 'b'})
-            finally:
-                release.set()
-                for thread in threads:
-                    thread.join(2)
-        self.assertEqual(writes, ['a'])
-        self.assertEqual(server._work[0], 0)
-        self.assertFalse(server._backfill['running'])
-        server.devices_post({'action': 'use', 'id': 'b'})
-
-    def test_listing_cannot_switch_before_backfill_registration(self):
-        handler = server.Handler.__new__(server.Handler)
-        handler.path = '/api/android'
-        handler.local_request = lambda: True
-        handler.send_json = mock.Mock()
-        handler.send_error_json = mock.Mock()
-        attempts = []
-        def listing():
-            try:
-                server.devices_post({'action': 'use', 'id': 'b'})
-            except server.Failure:
-                attempts.append('refused')
-            return []
-        with mock.patch.object(server, 'ensure_master'), \
-                mock.patch.object(android, 'list_apps', side_effect=listing), \
-                mock.patch.object(server, 'backfill_art') as backfill, \
-                mock.patch.object(server.apk_search, 'artwork_for', return_value={}):
-            handler.do_GET()
-        self.assertEqual(attempts, ['refused'])
-        backfill.assert_called_once()
-        self.assertEqual(server._work[0], 0)
-
-    def test_failed_worker_start_releases_count_and_throttle(self):
-        with mock.patch.object(server.threading.Thread, 'start', side_effect=RuntimeError('cannot start')):
-            with self.assertRaisesRegex(RuntimeError, 'cannot start'):
-                server.backfill_art(apps=[{'package': 'org.test.app', 'art_pending': True}])
-        self.assertEqual(server._work[0], 0)
-        self.assertFalse(server._backfill['running'])
-        self.assertEqual(server._backfill['last'], 0)
-
-    def test_backfill_refuses_identifiers_from_an_old_listing_target(self):
-        self.active.update(id='b', name='Headset B')
-        with mock.patch.object(android, 'refresh_art') as refresh:
-            with self.assertRaises(server.Failure):
-                server.backfill_art(apps=[{'package': 'org.test.app', 'art_pending': True}], meant='a')
-        refresh.assert_not_called()
-        self.assertEqual(server._work[0], 0)
-        self.assertFalse(server._backfill['running'])
-
-    def test_failed_thread_constructor_releases_count_and_throttle(self):
-        with mock.patch.object(server.threading, 'Thread', side_effect=RuntimeError('thread allocation')):
-            with self.assertRaisesRegex(RuntimeError, 'thread allocation'):
-                server.backfill_art(apps=[{'package': 'org.test.app', 'art_pending': True}])
-        self.assertEqual(server._work[0], 0)
-        self.assertEqual(server._backfill, {'running': False, 'last': 0})
-
-    def test_approval_same_device_runs_once_and_releases_work_on_error(self):
-        with mock.patch.object(agent, 'approvals', agent.Approvals()), \
-                mock.patch.object(server, 'launch', side_effect=RuntimeError('launch failed')) as launch:
-            body = {'name': 'launch', 'arguments': {'appid': '620'}}
-            approval = agent.call(server, body)
-            agent.approvals.decide(approval['confirmation'], True)
-            with self.assertRaisesRegex(RuntimeError, 'launch failed'):
-                agent.call(server, dict(body, confirmation=approval['confirmation']))
-            with self.assertRaises(ValueError):
-                agent.call(server, dict(body, confirmation=approval['confirmation']))
-            launch.assert_called_once()
-        self.assertEqual(server._work[0], 0)
-
-    def test_approval_records_target_and_rejects_switch(self):
-        with mock.patch.object(agent, 'approvals', agent.Approvals()), mock.patch.object(server, 'launch') as launch:
-            body = {'name': 'launch', 'arguments': {'appid': '620'}}
-            approval = agent.call(server, body)
-            self.assertEqual(approval['action']['target'], self.active)
-            self.assertEqual(agent.approvals.inspect(approval['confirmation'])['action']['target'], self.active)
-            agent.approvals.decide(approval['confirmation'], True)
-            server.devices_post({'action': 'use', 'id': 'b'})
-            with self.assertRaises(ValueError):
-                agent.call(server, dict(body, confirmation=approval['confirmation']))
-            launch.assert_not_called()
-            self.assertEqual(server._work[0], 0)
-
-    def test_approval_dispatch_holds_existing_work_guard(self):
-        attempts = []
-        def launch(args):
-            try:
-                server.devices_post({'action': 'use', 'id': 'b'})
-            except server.Failure:
-                attempts.append('refused')
-            return {'message': 'launched'}
-        with mock.patch.object(agent, 'approvals', agent.Approvals()), mock.patch.object(server, 'launch', side_effect=launch):
-            body = {'name': 'launch', 'arguments': {'appid': '620'}}
-            approval = agent.call(server, body)
-            agent.approvals.decide(approval['confirmation'], True)
-            result = agent.call(server, dict(body, confirmation=approval['confirmation']))
-        self.assertEqual(result['message'], 'launched')
-        self.assertEqual(attempts, ['refused'])
-        self.assertEqual(self.active['id'], 'a')
-        self.assertEqual(server._work[0], 0)
-
-
-class FinalLaunchTests(unittest.TestCase):
-    """Production delivery/cleanup with separate temporary A/B remote homes."""
-    def setUp(self):
-        self.stack = contextlib.ExitStack()
-        self.addCleanup(self.stack.close)
-        self.root = Path(self.stack.enter_context(tempfile.TemporaryDirectory()))
-        self.before = (server.FRAME, list(server.HOST_OPTS))
-        self.stack.enter_context(mock.patch.object(server, 'LOCAL', False))
-        self.stack.enter_context(mock.patch.object(server, 'LINK', None))
-        self.stack.enter_context(mock.patch.object(server, '_work', [0]))
-        self.stack.enter_context(mock.patch.object(server.macview, 'retarget'))
-        self.stack.enter_context(mock.patch.object(server, '_touch'))
-        self.stack.enter_context(mock.patch.object(server, 'ensure_master'))
-        local = self.root / 'local'
-        (local / 'packages').mkdir(parents=True)
-        packages = []
-        for n in (1, 2):
-            name, data = 'test%d.pkg.tar.zst' % n, ('offline package %d' % n).encode()
-            (local / 'packages' / name).write_bytes(data)
-            packages.append((name, hashlib.sha256(data).hexdigest()))
-        self.stack.enter_context(mock.patch.object(server, 'KDECONNECT', local))
-        self.agent = server.InputAgent(packages=packages)
-        self.stack.enter_context(mock.patch.object(server, '_input', self.agent))
-        self.stack.callback(lambda: server.route(*self.before))
-        for alias in ('target-a', 'target-b'):
-            (self.root / alias).mkdir()
-        server.route('target-a', ['-o', 'HostName=192.0.2.1'])
-        self.original_route = tuple([*server.SSH, server.FRAME])
-        self.calls = []
-        self.real_popen = subprocess.Popen
-
-    def remote(self, argv, **kw):
-        target, command = argv[-2:]
-        self.assertIn(target, ('target-a', 'target-b'))
-        feed = kw.get('input')
-        if isinstance(feed, str):
-            feed = feed.encode()
-        home = self.root / target
-        proc = self.real_popen(['sh', '-c', command], cwd=home,
-                               env={**os.environ, 'HOME': str(home)},
-                               stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-        out, err = proc.communicate(feed, timeout=3)
-        self.calls.append({'route': tuple(argv[:-1]), 'command': command, 'input': feed})
-        return subprocess.CompletedProcess(argv, proc.returncode,
-                                           out.decode() if kw.get('text') else out,
-                                           err.decode() if kw.get('text') else err)
-
-    def delivery_boundary(self, boundary, cancel=False):
-        entered, release = threading.Event(), threading.Event()
-        def remote(argv, **kw):
-            result = self.remote(argv, **kw)
-            command = argv[-1]
-            hit = ((boundary == 'stamp' and 'cmp -s' in command)
-                   or (boundary == 'mkdir' and command.startswith('mkdir -p'))
-                   or (boundary == 'copy' and command.startswith('cd ')))
-            if hit and not entered.is_set():
-                entered.set()
-                if not release.wait(3):
-                    raise AssertionError('delivery barrier not released')
-            return result
-        self.agent.launching = self.agent.generation
-        with mock.patch.object(server.frame_host, 'run_ssh', side_effect=remote), \
-                mock.patch.object(server.subprocess, 'Popen') as launch:
-            worker = threading.Thread(target=self.agent._launch, args=(self.agent.generation,))
-            worker.start()
-            try:
-                self.assertTrue(entered.wait(3))
-                if cancel:
-                    self.agent.stop()
-                else:
-                    server.route('target-b', ['-o', 'HostName=192.0.2.2'])
-                release.set()
-                worker.join(3)
-                self.assertFalse(worker.is_alive())
-                launch.assert_not_called()
-            finally:
-                release.set()
-                worker.join(3)
-        self.assertTrue(all(c['route'] == self.original_route for c in self.calls), self.calls)
-        copies = [c for c in self.calls if c['command'].startswith('cd ')]
-        self.assertEqual(len(copies), 1 if boundary == 'copy' else 0)
-        for alias in ('target-a', 'target-b'):
-            self.assertFalse(list((self.root / alias).rglob('*.part')))
-            self.assertFalse(list((self.root / alias).glob('**/incoming/*')))
-        self.assertIsNone(self.agent.proc)
-        self.assertEqual(self.agent.status['state'], 'off')
-        self.assertEqual(server._work[0], 0)
-
-    def test_switch_after_stamp_cannot_deliver_to_b(self):
-        self.delivery_boundary('stamp')
-
-    def test_switch_after_mkdir_cleans_only_a(self):
-        self.delivery_boundary('mkdir')
-
-    def test_switch_after_first_copy_stops_next_copy_and_cleans_a(self):
-        self.delivery_boundary('copy')
-
-    def test_cancel_after_first_copy_stops_next_copy_and_cleans_a(self):
-        self.delivery_boundary('copy', cancel=True)
-
-    def test_deferred_no_output_cleanup_keeps_the_original_route(self):
-        watching, release = threading.Event(), threading.Event()
-        proc = mock.Mock()
-        proc.poll.return_value = None
-        proc.wait.return_value = 0
-        def stdout():
-            watching.set()
-            if not release.wait(3):
-                raise AssertionError('watch barrier not released')
-            yield from ()
-        proc.stdout = stdout()
-        with mock.patch.object(server.frame_host, 'run_ssh', side_effect=self.remote), \
-                mock.patch.object(server.subprocess, 'Popen', return_value=proc):
-            self.agent.start()
-            try:
-                self.assertTrue(watching.wait(3))
-                self.assertEqual(server._work[0], 0, 'watch lifetime must not block device switching')
-                server.route('target-b', ['-o', 'HostName=192.0.2.2'])
-                release.set()
-                # The real watch completes and discard runs after route publication.
-                for _ in range(150):
-                    if any(c['command'].startswith('rm -rf') for c in self.calls):
-                        break
-                    threading.Event().wait(.01)
-                self.assertTrue(any(c['command'].startswith('rm -rf') for c in self.calls))
-            finally:
-                release.set()
-        self.assertTrue(all(c['route'] == self.original_route for c in self.calls), self.calls)
-        self.assertFalse(list((self.root / 'target-a').glob('**/incoming/*')))
-        self.assertIsNone(self.agent.proc)
-        self.assertEqual(self.agent.status['state'], 'off')
-    def test_package_retry_keeps_the_original_ssh_route(self):
-        first, second = mock.Mock(), mock.Mock()
-        first.stdout = [b'{"state":"need-packages"}\n']
-        second.stdout = [b'{"state":"ready"}\n']
-        first.poll.return_value = second.poll.return_value = 0
-        first.wait.side_effect = lambda: server.route('target-a', ['-o', 'HostName=192.0.2.2'])
-        second.wait.return_value = 0
-        with mock.patch.object(server.frame_host, 'run_ssh', side_effect=self.remote), \
-                mock.patch.object(server.subprocess, 'Popen', side_effect=[first, second]) as popen:
-            self.agent.launching = self.agent.generation
-            self.agent._launch(self.agent.generation)
-        self.assertEqual(popen.call_count, 2)
-        self.assertTrue(all(tuple(call.args[0][:-1]) == self.original_route for call in popen.call_args_list))
-        self.assertTrue(all(c['route'] == self.original_route for c in self.calls), self.calls)
-        self.assertEqual(len([c for c in self.calls if c['command'].startswith('cd ')]), 4)
-
-
-
-class FinalGetStartTests(unittest.TestCase):
-    setUp = TargetTests.setUp
-    switch = TargetTests.switch
-    def handler(self, path, meant):
-        handler = server.Handler.__new__(server.Handler)
-        handler.command, handler.path = 'GET', path
-        handler.headers = {'Host': '127.0.0.1:8123', 'X-Frame-UI': server.UI_KEY}
-        if meant is not None:
-            handler.headers['X-Frame-Device'] = meant
-        handler.send_json, handler.send_error_json = mock.Mock(), mock.Mock()
-        return handler
-
-    def test_stale_authenticated_get_start_is_rejected_before_start(self):
-        self.active.update(id='b', name='Headset B')
-        for name in ('input', 'touch'):
-            with self.subTest(name=name):
-                fresh = server.InputAgent(packages=[]) if name == 'input' else server.TouchAgent()
-                handler = self.handler('/api/%s?start=1' % name, 'a')
-                with mock.patch.object(server, '_' + name, fresh), mock.patch.object(fresh, 'start') as start:
-                    handler.do_GET()
-                start.assert_not_called()
-                self.assertEqual(handler.send_error_json.call_args.args[1], 409)
-                self.assertEqual(server._work[0], 0)
-
-    def test_desktop_get_start_requires_an_intended_device(self):
-        for name in ('input', 'touch'):
-            with self.subTest(name=name):
-                fresh = server.InputAgent(packages=[]) if name == 'input' else server.TouchAgent()
-                handler = self.handler('/api/%s?start=1' % name, None)
-                with mock.patch.object(server, '_' + name, fresh), mock.patch.object(fresh, 'start') as start:
-                    handler.do_GET()
-                start.assert_not_called()
-                self.assertEqual(handler.send_error_json.call_args.args[1], 400)
-                self.assertEqual(server._work[0], 0)
-
-    def test_get_start_validation_and_thread_registration_are_one_reservation(self):
-        attempts = []
-        fresh = server.TouchAgent()
-        def register():
-            try:
-                server.devices_post({'action': 'use', 'id': 'b'})
-            except server.Failure:
-                attempts.append('refused')
-        with mock.patch.object(server, '_touch', fresh), mock.patch.object(fresh, 'start', side_effect=register):
-            handler = self.handler('/api/touch?start=1', 'a')
-            handler.do_GET()
-        self.assertEqual(attempts, ['refused'])
-        self.assertEqual(self.active['id'], 'a')
-        self.assertEqual(server._work[0], 0)
-
-    def test_delayed_launch_uses_the_synchronously_captured_route(self):
-        pending = []
-        class QueuedThread:
-            def __init__(self, target, args=(), kwargs=None, **ignored):
-                self.target, self.args, self.kwargs = target, args, kwargs or {}
-            def start(self):
-                pending.append(self)
-        before = (server.FRAME, list(server.HOST_OPTS))
-        try:
-            for switched in (False, True):
-                with self.subTest(switched=switched):
-                    fresh = server.TouchAgent()
-                    proc = mock.Mock()
-                    proc.poll.return_value = None
-                    with mock.patch.object(server, '_touch', fresh), \
-                            mock.patch.object(server.threading, 'Thread', QueuedThread), \
-                            mock.patch.object(server, 'ensure_master'), \
-                            mock.patch.object(fresh, '_watch', return_value=(False, True)), \
-                            mock.patch.object(server.subprocess, 'Popen', return_value=proc) as popen:
-                        server.route('target-a', ['-o', 'HostName=192.0.2.1'])
-                        original = tuple([*server.SSH, server.FRAME])
-                        handler = self.handler('/api/touch?start=1', 'a')
-                        handler.do_GET()
-                        self.assertEqual(len(pending), 1)
-                        # Also change options without a generation change: this
-                        # proves the route was captured before the thread runs.
-                        server.route('target-b' if switched else 'target-a', ['-o', 'HostName=192.0.2.2'])
-                        thread = pending.pop()
-                        thread.target(*thread.args, **thread.kwargs)
-                        if switched:
-                            popen.assert_not_called()
-                            self.assertIsNone(fresh.proc)
-                        else:
-                            self.assertEqual(tuple(popen.call_args.args[0][:-1]), original)
-                        fresh.stop()
-                        server._live_tunnels.discard(proc)
-        finally:
-            server.route(*before)
-
-    def test_same_target_start_status_and_local_ios_remain_usable(self):
-        for link, meant, query in ((self.link, 'a', '?start=1'), (self.link, 'stale', ''),
-                                    (None, None, '?start=1')):
-            for name in ('input', 'touch'):
-                with self.subTest(name=name, query=query, local=link is None):
-                    fresh = server.InputAgent(packages=[]) if name == 'input' else server.TouchAgent()
-                    handler = self.handler('/api/' + name + query, meant)
-                    with mock.patch.object(server, 'LINK', link), mock.patch.object(server, 'LOCAL', link is None), \
-                            mock.patch.object(server, '_' + name, fresh), mock.patch.object(fresh, 'start') as start:
-                        handler.do_GET()
-                    self.assertEqual(start.call_count, 1 if query else 0)
-                    handler.send_error_json.assert_not_called()
-                    self.assertEqual(server._work[0], 0)
-
-
-class UpdateTests(unittest.TestCase):
-    """Execute generated remote commands in a temporary home; only Steam is synthetic."""
-    def exercise(self, failure, repair_failure=None):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            d = root / 'Applications/Android/org.test.app'
-            d.mkdir(parents=True)
-            old = {'package': 'org.test.app', 'version': '1', 'label': 'Old', 'instance': 2800000001,
-                   'shortcut': 42, 'flatscreen': False, 'artwork': {}}
-            files = {'app.apk': b'old APK', 'launch.sh': b'old launcher', 'instance.id': b'2800000001',
-                     'meta.json': json.dumps(old).encode(), 'shortcut.id': b'42', 'user-save': b'precious data'}
-            for name, data in files.items():
-                (d / name).write_bytes(data)
-            (d / 'launch.sh').chmod(0o755)
-            save = root / '.local/share/Steam/steamapps/compatdata/2800000001/internal/save'
-            save.parent.mkdir(parents=True)
-            save.write_bytes(b'Android saved data')
-            apk = root / 'new.apk'
-            apk.write_bytes(b'new APK')
-            info = {'package': 'org.test.app', 'version': '2', 'label': 'New', 'vr': False}
-            writes = []
-            repairing = [False]
-            repair_failure_pending = [False]
-            cleanup_attempts = []
-            def ssh(cmd, input=None, **kw):
-                repair_stage = None
-                if repairing[0] and repair_failure_pending[0]:
-                    if '/meta.json.tmp' in cmd and cmd.startswith('cat >'):
-                        repair_stage = 'meta'
-                    elif '/update-recovery.json.tmp' in cmd and cmd.startswith('cat >'):
-                        repair_stage = 'checkpoint'
-                    elif cmd.startswith('rm -rf ') and '.frame-update-backup' in cmd:
-                        repair_stage = 'cleanup'
-                    if repair_failure == 'cleanup-partial' and repair_stage == 'cleanup':
-                        (d / '.frame-update-backup/ready').unlink()
-                        repair_failure_pending[0] = False
-                        raise android.FrameError('partial repair cleanup')
-                    if repair_failure == repair_stage:
-                        repair_failure_pending[0] = False
-                        raise android.FrameError('transient repair ' + repair_stage)
-                if failure == 'cleanup' and cmd == 'rm -rf Applications/Android/org.test.app/.frame-update-backup' and not cleanup_attempts:
-                    cleanup_attempts.append(cmd)
-                    raise android.FrameError('backup cleanup unavailable')
-                if repairing[0] and cmd == 'python3 -':
-                    return json.dumps({'icon_png': '', 'artwork': {}})
-                if failure == 'rollback' and 'frame-update-backup' in cmd and ('cp -' in cmd or 'mv ' in cmd) and writes and not repairing[0]:
-                    raise android.FrameError('restore connection lost')
-                if failure == 'meta' and '/meta.json.tmp' in cmd and not writes:
-                    writes.append('meta failed')
-                    raise android.FrameError('metadata unavailable')
-                if isinstance(input, str):
-                    input = input.encode()
-                p = subprocess.run(['sh', '-c', cmd], input=input, cwd=root,
-                                   env={**os.environ, 'HOME': str(root)}, capture_output=True)
-                if p.returncode:
-                    raise android.FrameError(p.stderr.decode())
-                if repair_stage and repair_failure == repair_stage + '-after':
-                    repair_failure_pending[0] = False
-                    raise android.FrameError('lost repair ' + repair_stage + ' response')
-                if failure == 'meta-after' and '/meta.json.tmp' in cmd and not writes:
-                    writes.append('meta response lost')
-                    raise android.FrameError('metadata response lost')
-                return p.stdout.decode()
-            def copy(src, dest, **kw):
-                target = root / dest
-                shutil.copyfile(src, target)
-                if kw.get('executable'):
-                    target.chmod(0o755)
-            def shortcut_tool(*args, **kw):
-                if args[0] == 'add':
-                    return '43'
-                if args[0] == 'remove':
-                    if not repairing[0]:
-                        raise android.FrameError('shortcut cleanup unavailable')
-                    return '{}'
-                raise AssertionError(args)
-            def library(*a, **kw):
-                if repairing[0]:
-                    self.assertEqual(a[1], 'Old')
-                    self.assertTrue(kw['vr'])
-                    self.assertEqual(kw['fill_only'], not (d / 'update-recovery.json').exists())
-                    (root / 'steam-state').write_text('old library settings')
-                    if repair_failure_pending[0] and repair_failure == 'library':
-                        repair_failure_pending[0] = False
-                        raise android.FrameError('transient repair library failure')
-                    return {'artwork': {}, 'warnings': []}
-                # A partial library mutation is externally observable even when configure fails.
-                (root / 'steam-state').write_text('new library settings')
-                if failure in ('library', 'rollback', 'orphan'):
-                    writes.append('library failed')
-                    raise android.FrameError('Steam unavailable after partial configure')
-                return {'artwork': {}, 'warnings': []}
-            with mock.patch.object(android.frame_artwork, 'prepare', return_value=({}, [])), \
-                    mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android, '_copy', side_effect=copy), \
-                    mock.patch.object(android, '_shortcut_ids', return_value=set() if failure == 'orphan' else {42}), \
-                    mock.patch.object(android, 'shortcut_tool', side_effect=shortcut_tool), \
-                    mock.patch.object(android, 'apply_library', side_effect=library):
-                with self.assertRaises(android.FrameError) as error:
-                    android._install(str(apk), info, info['package'], True, None, None)
-            if failure != 'rollback':
-                for name, data in files.items():
-                    self.assertEqual((d / name).read_bytes(), data, name)
-                self.assertFalse((d / 'lepton-show-flatscreen').exists())
-                self.assertTrue((d / 'launch.sh').stat().st_mode & 0o100)
-                self.assertFalse((d / 'app.apk.part').exists())
-                self.assertFalse((d / 'meta.json.tmp').exists())
-            self.assertEqual((d / 'user-save').read_bytes(), b'precious data')
-            self.assertEqual(save.read_bytes(), b'Android saved data')
-            # Steam's API cannot guarantee a full rollback. Never hide that residual state.
-            self.assertIn('repair', str(error.exception).lower())
-            record = json.loads((d / 'update-recovery.json').read_text())
-            self.assertIn('error', record)
-            self.assertIn('repair', record)
-            if failure == 'rollback':
-                self.assertIn('restore connection lost', str(error.exception))
-                self.assertTrue((d / '.frame-update-backup').is_dir())
-            if failure == 'orphan':
-                self.assertEqual(record['orphan_shortcut'], 43)
-                self.assertIn('shortcut cleanup unavailable', str(error.exception))
-            snapshot = {str(p.relative_to(d)): p.read_bytes() for p in d.rglob('*') if p.is_file()}
-            with mock.patch.object(android.frame_artwork, 'prepare', return_value=({}, [])), \
-                    mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android, '_copy', side_effect=AssertionError('pending recovery must refuse before copying')):
-                with self.assertRaises(android.FrameError):
-                    android._install(str(apk), info, info['package'], True, None, None)
-            self.assertEqual({str(p.relative_to(d)): p.read_bytes() for p in d.rglob('*') if p.is_file()}, snapshot,
-                             'Retry must preserve all prior recovery evidence byte for byte')
-            repairing[0] = True
-            with mock.patch.object(android.frame_artwork, 'prepare', return_value=({}, [])), \
-                    mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android, '_shortcut_ids', return_value={42}), \
-                    mock.patch.object(android, 'shortcut_tool', side_effect=shortcut_tool) as api, \
-                    mock.patch.object(android, 'apply_library', side_effect=library):
-                if repair_failure:
-                    repair_failure_pending[0] = True
-                    with self.assertRaises(android.FrameError):
-                        android.refresh_art(info['package'], fill_only=True)
-                    # A later failure must retain either the ready snapshot or a
-                    # durable terminal checkpoint, never an unconfirmed dead end.
-                    if (d / 'update-recovery.json').exists():
-                        retry_record = json.loads((d / 'update-recovery.json').read_text())
-                        for key in ('error', 'rollback_error', 'orphan_shortcut', 'cleanup_error'):
-                            self.assertEqual(retry_record[key], record[key], key)
-                        self.assertTrue((d / '.frame-update-backup/ready').exists() or
-                                        retry_record.get('repair_completed') is True)
-                    else:
-                        self.assertFalse((d / '.frame-update-backup').exists())
-                    self.assertEqual((d / 'app.apk').read_bytes(), files['app.apk'])
-                    self.assertEqual((d / 'launch.sh').read_bytes(), files['launch.sh'])
-                    self.assertFalse((d / 'lepton-show-flatscreen').exists())
-                    coherent = json.loads((d / 'meta.json').read_text())
-                    self.assertEqual(coherent['version'], '1')
-                    self.assertFalse(coherent['flatscreen'])
-                repaired = android.refresh_art(info['package'], fill_only=True)
-            if failure == 'orphan':
-                api.assert_called_once_with('remove', '43')
-            self.assertEqual(repaired['version'], '1')
-            self.assertFalse(repaired['flatscreen'])
-            self.assertEqual((root / 'steam-state').read_text(), 'old library settings')
-            for name in ('app.apk', 'launch.sh', 'instance.id', 'shortcut.id', 'user-save'):
-                self.assertEqual((d / name).read_bytes(), files[name], name)
-            self.assertFalse((d / 'update-recovery.json').exists())
-            self.assertFalse((d / '.frame-update-backup').exists())
-            self.assertFalse((d / 'lepton-show-flatscreen').exists())
-            self.assertEqual(save.read_bytes(), b'Android saved data')
-            return record
-
-    def test_late_library_failure_restores_executable_metadata_and_preserves_data(self):
-        self.exercise('library')
-
-    def test_meta_write_failure_restores_executable_metadata_and_preserves_data(self):
-        self.exercise('meta')
-
-    def test_missing_snapshot_cannot_claim_an_unconfirmed_rollback_is_repaired(self):
-        def ssh(cmd, **kw):
-            if cmd.startswith('test -f'):
-                return 'yes'
-            if cmd.startswith('cat ') and cmd.endswith('update-recovery.json'):
-                return json.dumps({'files_restored': False, 'library_may_have_changed': True})
-            if cmd == 'python3 -':
-                return json.dumps({'icon_png': '', 'artwork': {}})
-            return ''
-        meta = {'package': 'org.test.app', 'label': 'Old', 'shortcut': 42, 'flatscreen': False}
-        with mock.patch.object(android, 'ssh', side_effect=ssh), \
-                mock.patch.object(android, '_meta_or_fail', return_value=meta), \
-                mock.patch.object(android, '_shortcut_ids', return_value={42}), \
-                mock.patch.object(android.frame_artwork, 'prepare', return_value=({}, [])), \
-                mock.patch.object(android, '_write_meta'), \
-                mock.patch.object(android, 'apply_library', return_value={}) as library:
-            with self.assertRaisesRegex(android.FrameError, 'unconfirmed'):
-                android.refresh_art('org.test.app')
-        library.assert_not_called()
-
-    def test_retry_preserves_absent_snapshot_uncertainty_and_repair_still_refuses(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            d = root / 'Applications/Android/org.test.app'
-            d.mkdir(parents=True)
-            record = {'files_restored': False, 'files_unchanged': False, 'error': 'original lost rollback',
-                      'library_may_have_changed': True, 'orphan_shortcut': 43}
-            (d / 'update-recovery.json').write_text(json.dumps(record))
-            evidence = (d / 'update-recovery.json').read_bytes()
-            def ssh(cmd, input=None, **kw):
-                result = subprocess.run(['sh', '-c', cmd], cwd=root, capture_output=True)
-                if result.returncode:
-                    raise android.FrameError(result.stderr.decode())
-                return result.stdout.decode()
-            with mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android.frame_artwork, 'prepare', side_effect=AssertionError('must refuse before artwork')), \
-                    mock.patch.object(android, '_copy', side_effect=AssertionError('must refuse before copy')):
-                with self.assertRaisesRegex(android.FrameError, 'Pending'):
-                    android._install('unused.apk', {'label': 'New'}, 'org.test.app', True, None, None)
-                self.assertEqual((d / 'update-recovery.json').read_bytes(), evidence)
-                with self.assertRaisesRegex(android.FrameError, 'unconfirmed'):
-                    android.refresh_art('org.test.app')
-                self.assertEqual((d / 'update-recovery.json').read_bytes(), evidence)
-
-    def test_recovery_appearing_after_preflight_is_not_owned_by_the_new_attempt(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            d = root / 'Applications/Android/org.test.app'
-            d.mkdir(parents=True)
-            meta = {'package': 'org.test.app', 'instance': 2800000001, 'shortcut': 42, 'label': 'Old'}
-            (d / 'meta.json').write_text(json.dumps(meta))
-            (d / 'app.apk').write_bytes(b'old APK')
-            record = b'{"orphan_shortcut":43,"files_restored":false,"error":"prior failure"}'
-            def prepare(*args):
-                (d / 'update-recovery.json').write_bytes(record)
-                (d / 'app.apk.part').write_bytes(b'prior partial evidence')
-                return {}, []
-            def ssh(cmd, input=None, **kw):
-                if isinstance(input, str):
-                    input = input.encode()
-                result = subprocess.run(['sh', '-c', cmd], input=input, cwd=root, capture_output=True)
-                if result.returncode:
-                    raise android.FrameError(result.stderr.decode())
-                return result.stdout.decode()
-            with mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android.frame_artwork, 'prepare', side_effect=prepare), \
-                    mock.patch.object(android, '_copy', side_effect=AssertionError('pending recovery must refuse before copy')):
-                with self.assertRaisesRegex(android.FrameError, 'Pending'):
-                    android._install('unused.apk', {'label': 'New'}, 'org.test.app', True, None, None)
-            self.assertEqual((d / 'update-recovery.json').read_bytes(), record)
-            self.assertEqual((d / 'app.apk.part').read_bytes(), b'prior partial evidence')
-            self.assertEqual((d / 'app.apk').read_bytes(), b'old APK')
-            self.assertFalse((d / '.frame-update-backup').exists())
-
-    def test_snapshot_without_record_cannot_be_repaired_or_overwritten(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            d = root / 'Applications/Android/org.test.app'
-            backup = d / '.frame-update-backup'
-            backup.mkdir(parents=True)
-            (backup / 'ready').touch()
-            (backup / 'app.apk').write_bytes(b'old APK evidence')
-            def ssh(cmd, input=None, **kw):
-                result = subprocess.run(['sh', '-c', cmd], cwd=root, capture_output=True)
-                if result.returncode:
-                    raise android.FrameError(result.stderr.decode())
-                return result.stdout.decode()
-            with mock.patch.object(android, 'ssh', side_effect=ssh), \
-                    mock.patch.object(android.frame_artwork, 'prepare', side_effect=AssertionError('must refuse before artwork')):
-                with self.assertRaisesRegex(android.FrameError, 'Pending'):
-                    android._install('unused.apk', {'label': 'New'}, 'org.test.app', True, None, None)
-                with self.assertRaisesRegex(android.FrameError, 'unconfirmed'):
-                    android.refresh_art('org.test.app')
-            self.assertFalse((d / 'update-recovery.json').exists())
-            self.assertEqual((backup / 'app.apk').read_bytes(), b'old APK evidence')
-
-    def test_meta_write_response_loss_restores_old_metadata_too(self):
-        self.exercise('meta-after')
-
-    def test_new_shortcut_cleanup_failure_is_recorded_and_repaired(self):
-        self.exercise('orphan')
-
-    def test_backup_cleanup_failure_rolls_back_and_has_a_repair_path(self):
-        self.exercise('cleanup')
-
-    def test_restore_failure_reports_and_keeps_recovery_evidence(self):
-        self.exercise('rollback')
-
-    def test_repair_retains_recovery_until_all_stages_and_cleanup_succeed(self):
-        for stage in ('library', 'meta', 'meta-after', 'checkpoint',
-                      'checkpoint-after', 'cleanup', 'cleanup-partial', 'cleanup-after'):
-            with self.subTest(stage=stage):
-                self.exercise('rollback', repair_failure=stage)
-
-
-if __name__ == '__main__':
-    unittest.main()

tests/test_source_logins.py

@@ -0,0 +1,566 @@
+"""Repositories and sources behind a login: F-Droid basic auth and GitHub tokens.
+
+A fake HTTPS layer stands in for the network (urllib's real redirect, error and
+request processing still run), so these tests see every request and its headers.
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import base64
+import contextlib
+import http.client
+import io
+import json
+import os
+from pathlib import Path
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from unittest.mock import Mock, patch
+import urllib.request
+import urllib.response
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+from apk_sources import SourceAuthError, SourceError, SourceLimited, _credentials, _images, _web, fdroid, github, search
+import server
+
+FIXTURES = Path(__file__).parent / 'fixtures' / 'fdroid'
+PIN = (FIXTURES / 'fingerprint.txt').read_text().strip()
+REPO = 'https://repo.example/fdroid/repo/'
+USER, PASSWORD = 'alice', 's3cr@t-pässword'
+TOKEN = 'ghp_frameControlTestToken0123456789'
+SECRETS = (PASSWORD, TOKEN, base64.b64encode((USER + ':' + PASSWORD).encode()).decode())
+REAL_BUILD_OPENER = urllib.request.build_opener
+
+
+def basic(user, password):
+    return 'Basic ' + base64.b64encode((user + ':' + password).encode()).decode()
+
+
+class FakeHTTPS(urllib.request.HTTPSHandler):
+    """Answers https requests from route(url, authorization) -> (status, headers, body)."""
+
+    def __init__(self, route):
+        super().__init__()
+        self.route, self.seen = route, []
+
+    def https_open(self, req):
+        auth = req.get_header('Authorization')
+        self.seen.append((req.full_url, auth))
+        status, headers, body = self.route(req.full_url, auth)
+        message = http.client.HTTPMessage()
+        for key, value in headers.items():
+            message[key] = value
+        response = urllib.response.addinfourl(io.BytesIO(body), message, req.full_url, status)
+        response.msg = 'fake'
+        return response
+
+
+class Base(unittest.TestCase):
+    def setUp(self):
+        tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        self.root = Path(tmp.name)
+        for name, value in [('data_dir', lambda *p: self.root.joinpath('data', *p)),
+                            ('cache_dir', lambda *p: self.root.joinpath('cache', *p))]:
+            mock = patch.object(fdroid.frame_host, name, value)
+            mock.start()
+            self.addCleanup(mock.stop)
+        self.web = FakeHTTPS(self.route)
+        mock = patch('urllib.request.build_opener', lambda *handlers: REAL_BUILD_OPENER(*handlers, self.web))
+        mock.start()
+        self.addCleanup(mock.stop)
+        mock = patch.dict(os.environ, {github.ENV: ''})
+        mock.start()
+        self.addCleanup(mock.stop)
+        for state in (_web._limited, fdroid._stale, fdroid._retry_at, fdroid._refreshing, github._rejected):
+            state.clear()
+            self.addCleanup(state.clear)
+        self.stderr = io.StringIO()
+        mock = patch('sys.stderr', self.stderr)
+        mock.start()
+        self.addCleanup(mock.stop)
+
+    def route(self, url, auth):
+        raise AssertionError('unexpected request ' + url)
+
+    def assertNoSecrets(self, *texts):
+        for text in texts:
+            for secret in SECRETS + (USER + ':',):
+                self.assertNotIn(secret, text)
+
+    def disk(self):
+        """Everything saved under the data and cache folders except the credentials file."""
+        out = []
+        for path in self.root.rglob('*'):
+            if path.is_file() and path.name != 'source-credentials.json':
+                out.append(path.read_bytes().decode('utf-8', 'replace'))
+        return '\n'.join(out)
+
+    def credentials_file(self):
+        return self.root / 'data' / 'source-credentials.json'
+
+
+class Repository(Base):
+    """A repository at REPO that wants USER and PASSWORD."""
+    def setUp(self):
+        super().setUp()
+        self.login = basic(USER, PASSWORD)
+        self.redirect = None  # file name -> absolute URL it redirects to
+        self.forbidden = 401
+
+    def serve(self, name):
+        return (FIXTURES / ('example.apk' if name.endswith('.apk') else name)).read_bytes()
+
+    def route(self, url, auth):
+        for mirror in ('https://mirror.example/fdroid/repo/', 'https://repo.example/elsewhere/'):
+            if url.startswith(mirror):  # serves anyone; a login must never get here unless same-origin
+                return 200, {}, self.serve(url[len(mirror):])
+        self.assertTrue(url.startswith(REPO), url)
+        if auth != self.login:
+            return self.forbidden, {'WWW-Authenticate': 'Basic realm="repo"'}, b'no'
+        name = url[len(REPO):]
+        if self.redirect and name in self.redirect:
+            return 302, {'Location': self.redirect[name]}, b''
+        return 200, {}, self.serve(name)
+
+    def add(self, **kw):
+        return fdroid.add_repo('https://alice:s3cr%40t-p%C3%A4ssword@repo.example/fdroid/repo', PIN, **kw)
+
+
+class RepositoryLogin(Repository):
+    def test_add_search_download_with_login_in_the_url(self):
+        source = self.add()
+        self.assertEqual(source['url'], REPO)
+        self.assertEqual(source['fingerprint'], PIN)
+        saved = fdroid.user_repos()[0]
+        self.assertEqual(saved['url'], REPO)
+        self.assertNotIn('login', saved)
+        self.assertEqual(len(fdroid.search(source, 'example offline')), 1)
+        downloaded = fdroid.download(source, 'org.example.app', 1)
+        self.assertTrue(downloaded['verified'])
+        self.assertTrue(self.web.seen)
+        self.assertTrue(all(auth == self.login for url, auth in self.web.seen))
+        self.assertTrue(all('@' not in url for url, auth in self.web.seen))  # never in the URL
+        self.assertTrue(next(s for s in fdroid.sources() if s['id'] == source['id'])['login'])
+        self.assertNoSecrets(json.dumps(source), json.dumps(fdroid.sources()), self.disk(), self.stderr.getvalue())
+        # The settings file holds no part of the login; the credentials file holds it, privately.
+        settings = (self.root / 'data' / 'apk-repos.json').read_text()
+        self.assertNotIn(USER, settings)
+        self.assertTrue(self.credentials_file().is_file())
+        if os.name != 'nt':
+            self.assertEqual(stat.S_IMODE(self.credentials_file().stat().st_mode), 0o600)
+
+    def test_login_given_apart_and_saved_login_reused_on_refresh(self):
+        source = fdroid.add_repo(REPO, PIN, username=USER, password=PASSWORD)
+        self.assertEqual(source['url'], REPO)
+        self.web.seen.clear()
+        fdroid._load(fdroid.user_repos()[0], force=True)  # as a background refresh would
+        self.assertTrue(self.web.seen)
+        self.assertTrue(all(auth == self.login for url, auth in self.web.seen))
+        fdroid.add_repo(REPO)  # re-adding without a login keeps the saved one
+        self.assertTrue(_credentials.has(source['id']))
+
+    def test_wrong_or_missing_login_saves_nothing(self):
+        for kw, message in [({'username': USER, 'password': 'wrong'}, 'check the username and password'),
+                            ({}, 'needs a username and password')]:
+            with self.subTest(kw=kw):
+                with self.assertRaisesRegex(SourceAuthError, message) as caught:
+                    fdroid.add_repo(REPO, PIN, **kw)
+                self.assertNoSecrets(str(caught.exception), repr(caught.exception))
+                self.assertNotIn('wrong', str(caught.exception))
+                self.assertEqual(fdroid.user_repos(), [])
+                self.assertFalse(self.credentials_file().exists())
+                self.assertFalse((self.root / 'data' / 'apk-repo-state.json').exists())
+                self.assertEqual(_web._limited, {})  # an auth failure isn't a rate limit
+
+    def test_403_with_a_login_is_a_login_error_not_a_rate_limit(self):
+        self.forbidden = 403
+        with self.assertRaisesRegex(SourceAuthError, 'check the username and password'):
+            fdroid.add_repo(REPO, PIN, username=USER, password='wrong')
+        self.assertEqual(_web._limited, {})
+        self.assertEqual(fdroid.user_repos(), [])
+
+    def test_signature_checks_still_apply(self):
+        with self.assertRaisesRegex(SourceError, 'fingerprint mismatch'):
+            fdroid.add_repo(REPO, '0' * 64, username=USER, password=PASSWORD)
+        self.assertEqual(fdroid.user_repos(), [])
+        self.assertFalse(self.credentials_file().exists())
+
+    def test_cross_origin_redirect_never_gets_the_login(self):
+        self.redirect = {'entry.jar': 'https://mirror.example/fdroid/repo/entry.jar',
+                         'index-v2.json': 'https://repo.example/elsewhere/index-v2.json'}
+        source = self.add()
+        self.assertEqual(source['fingerprint'], PIN)  # the mirror's copy still had to verify
+        mirror = [auth for url, auth in self.web.seen if url.startswith('https://mirror.example/')]
+        same_origin = [auth for url, auth in self.web.seen if url.startswith('https://repo.example/elsewhere/')]
+        self.assertEqual(mirror, [None])
+        self.assertEqual(same_origin, [None])  # same origin but outside the repository: no login either
+
+    def test_traversal_names_are_refused_and_never_get_the_login(self):
+        for name in ('%252e%252e/%252e%252e/evil/collect.apk', '..;/..;/evil/collect.apk', 'a%2f..%2f..%2fevil.apk',
+                     'a%5c..%5cevil.apk', '%2e%2e/evil.apk', 'x;y.apk', '100%25.apk'):
+            with self.subTest(name=name), self.assertRaisesRegex(SourceError, 'unsafe|outside'):
+                fdroid._child(REPO, name)
+        self.assertEqual(fdroid._child(REPO, '/app/en-US/phoneScreenshots/#0 a.png'),
+                         REPO + 'app/en-US/phoneScreenshots/%230%20a.png')
+        # Even if such a URL reached the downloader directly, the login stays home.
+        login = _credentials.basic(REPO, USER, PASSWORD)
+        for url in (REPO + '%252e%252e/%252e%252e/evil/collect.apk', REPO + '..;/..;/evil/collect.apk'):
+            with self.subTest(url=url), tempfile.TemporaryDirectory() as tmp:
+                self.web.seen.clear()
+                with contextlib.suppress(SourceError):  # the repository answers 401 without the login
+                    fdroid._fetch(url, Path(tmp) / 'out', 1 << 20, auth=login)
+                self.assertEqual(self.web.seen, [(url, None)])
+
+    def test_same_origin_redirect_outside_the_repository_gets_no_login(self):
+        self.redirect = {'example1.apk': 'https://repo.example/elsewhere/example1.apk'}
+        source = self.add()
+        self.web.seen.clear()
+        self.assertTrue(fdroid.download(source, 'org.example.app', 1)['verified'])
+        self.assertEqual(self.web.seen, [(REPO + 'example1.apk', self.login),
+                                         ('https://repo.example/elsewhere/example1.apk', None)])
+
+    def test_other_ports_and_http_never_get_the_login(self):
+        login = _credentials.basic(REPO, USER, PASSWORD)
+        for url in ('https://repo.example:8443/fdroid/repo/x', 'http://repo.example/fdroid/repo/x',
+                    'https://other.example/fdroid/repo/x', 'https://repo.example.evil/x'):
+            self.assertFalse(login.matches(url), url)
+        self.assertTrue(login.matches('https://REPO.example:443/anything'))
+        self.assertNoSecrets(repr(login))
+        handler = _credentials.Handler(login)
+        req = urllib.request.Request('https://other.example/x', headers={'Authorization': 'Basic stale'})
+        self.assertIsNone(handler.https_request(req).get_header('Authorization'))
+
+    def test_http_and_bad_logins_are_refused_before_any_request(self):
+        for url, kw in [('http://alice:pw@repo.example/fdroid/repo', {}),
+                        ('http://repo.example/fdroid/repo', {'username': USER, 'password': PASSWORD}),
+                        (REPO, {'username': 'a:b', 'password': PASSWORD}),
+                        (REPO, {'username': USER, 'password': 'x\r\nX-Evil: 1'}),
+                        (REPO, {'password': PASSWORD}),
+                        ('https://alice:pw@repo.example/fdroid/repo', {'username': 'bob'})]:
+            with self.subTest(url=url, kw=kw), self.assertRaises(SourceError) as caught:
+                fdroid.add_repo(url, PIN, **kw)
+            self.assertNotIn('pw', str(caught.exception).replace('password', ''))
+            self.assertNoSecrets(str(caught.exception))
+        self.assertEqual(self.web.seen, [])
+
+    def test_remove_deletes_the_login(self):
+        source = self.add()
+        other = _credentials.bearer('https://api.github.com/', TOKEN)
+        _credentials.put('github', other)
+        fdroid.remove_repo(source['id'])
+        self.assertFalse(_credentials.has(source['id']))
+        self.assertNotIn(PASSWORD, self.credentials_file().read_text())
+        _credentials.remove('github')
+        self.assertFalse(self.credentials_file().exists())  # nothing left: the file goes
+
+    def test_cli_reads_the_password_from_stdin(self):
+        out = io.StringIO()
+        argv = ['fdroid.py', 'add', REPO, '--fingerprint', PIN, '--username', USER, '--password-stdin']
+        with patch.object(sys, 'argv', argv), patch.object(sys, 'stdin', io.StringIO(PASSWORD + '\n')), \
+                contextlib.redirect_stdout(out):
+            fdroid.main()
+        self.assertEqual(json.loads(out.getvalue())['url'], REPO)
+        self.assertNoSecrets(out.getvalue())
+        self.assertTrue(_credentials.has(fdroid.user_repos()[0]['id']))
+
+    def test_artwork_from_the_repository_gets_the_login_and_only_there(self):
+        source = self.add()
+        self.assertEqual(_credentials.for_url(REPO + 'icons/a.png').header(), self.login)
+        self.assertTrue(_credentials.has(source['id']))
+        self.assertIsNone(_credentials.for_url('https://repo.example/other/a.png'))  # outside the repository
+        self.assertIsNone(_credentials.for_url('https://cdn.example/fdroid/repo/a.png'))
+
+
+class GitHubToken(Base):
+    def setUp(self):
+        super().setUp()
+        self.accept = {TOKEN}
+        self.releases = json.dumps([]).encode()
+        self.anonymous_limited = False
+
+    def route(self, url, auth):
+        if url.startswith('https://api.github.com/'):
+            if auth is not None and auth not in {'Bearer ' + t for t in self.accept}:
+                return 401, {}, b'{"message": "Bad credentials"}'
+            if auth is None and self.anonymous_limited:
+                return 403, {'X-RateLimit-Remaining': '0', 'X-RateLimit-Reset': str(int(time.time()) + 1800)}, b'{}'
+            if url.endswith('/redirected'):
+                return 302, {'Location': 'https://github.com/landed'}, b''
+            return 200, {}, self.releases
+        if url == 'https://github.com/landed':
+            return 200, {}, b'{"ok": true}'
+        raise AssertionError('unexpected request ' + url)
+
+    def test_saved_token_goes_only_to_the_api(self):
+        github.set_token(TOKEN)
+        self.assertEqual(github._api('/repos/a/b/releases'), [])
+        self.assertEqual(self.web.seen, [('https://api.github.com/repos/a/b/releases', 'Bearer ' + TOKEN)])
+        auth = github._credential(github._token()[0])
+        self.assertEqual(_web.read('https://api.github.com/redirected', ('api.github.com', 'github.com'), auth=auth),
+                         b'{"ok": true}')
+        self.assertEqual(self.web.seen[-2:], [('https://api.github.com/redirected', 'Bearer ' + TOKEN),
+                                              ('https://github.com/landed', None)])  # redirect: no token
+        status = github.sources()[0]['token']
+        self.assertEqual(status, {'set': True, 'from': 'saved', 'rejected': False})
+        self.assertNoSecrets(json.dumps(github.sources()), self.disk(), self.stderr.getvalue())
+        if os.name != 'nt':
+            self.assertEqual(stat.S_IMODE(self.credentials_file().stat().st_mode), 0o600)
+
+    def test_rejected_token_retries_once_without_it(self):
+        github.set_token(TOKEN)
+        self.accept = set()
+        self.assertEqual(github._api('/repos/a/b/releases'), [])
+        self.assertEqual([auth for _, auth in self.web.seen], ['Bearer ' + TOKEN, None])
+        self.assertTrue(github.token_status()['rejected'])
+        self.assertIn('rejected', self.stderr.getvalue())
+        self.assertNoSecrets(self.stderr.getvalue())
+        self.web.seen.clear()
+        github._api('/repos/a/b/other')
+        self.assertEqual([auth for _, auth in self.web.seen], [None])  # not tried again this run
+        github.set_token(TOKEN)  # saving it again gives it a fresh chance
+        self.assertFalse(github.token_status()['rejected'])
+
+    def test_environment_variable_wins(self):
+        github.set_token(TOKEN)
+        env = 'ghp_fromTheEnvironment'
+        self.accept = {env}
+        with patch.dict(os.environ, {github.ENV: env}):
+            github._api('/repos/a/b/releases')
+            self.assertEqual(self.web.seen[-1][1], 'Bearer ' + env)
+            self.assertEqual(github.token_status(), {'set': True, 'from': 'env', 'rejected': False})
+        self.assertEqual(github.token_status()['from'], 'saved')
+
+    def test_clear_removes_it_from_disk(self):
+        github.set_token(TOKEN)
+        github.clear_token()
+        self.assertFalse(self.credentials_file().exists())
+        self.assertEqual(github.token_status(), {'set': False, 'from': None, 'rejected': False})
+        github._api('/repos/a/b/releases')
+        self.assertEqual(self.web.seen[-1][1], None)
+
+    def test_saving_a_token_escapes_the_anonymous_rate_limit(self):
+        self.anonymous_limited = True
+        with self.assertRaisesRegex(SourceLimited, 'GitHub is limiting requests'):
+            github._api('/repos/a/b/releases')
+        self.assertEqual(self.web.seen[-1][1], None)
+        github.set_token(TOKEN)
+        self.assertEqual(github._api('/repos/a/b/other'), [])  # tried, with the token's own quota
+        self.assertEqual(self.web.seen[-1], ('https://api.github.com/repos/a/b/other', 'Bearer ' + TOKEN))
+        github.clear_token()
+        count = len(self.web.seen)
+        with self.assertRaisesRegex(SourceLimited, 'GitHub is limiting requests'):
+            github._api('/repos/a/b/third')
+        self.assertEqual(len(self.web.seen), count)  # anonymous is still backing off: no request
+
+    def test_bad_tokens_are_refused(self):
+        for token in ('', '   ', 'two words', 'x\nAuthorization: y'):
+            with self.subTest(token=token), self.assertRaises(SourceError):
+                github.set_token(token)
+        self.assertFalse(self.credentials_file().exists())
+
+
+PNG = b'\x89PNG\r\n\x1a\nfixture'
+PRIVATE = 'https://repo.example/private/repo/'
+TRAVERSALS = [PRIVATE + '%2e%2e/%2e%2e/evil/collect.png', PRIVATE + '%2E%2E/x.png', PRIVATE + '../../evil/x.png',
+              PRIVATE + './icons/a.png', PRIVATE + '..%2f..%2fevil/x.png', PRIVATE + 'a%5c..%5c..%5cevil.png',
+              PRIVATE + 'a;b/../../evil.png', PRIVATE + '%252e%252e/%252e%252e/evil.png',
+              'https://repo.example/private/repository/x.png', 'https://repo.example/private/repo%2fx.png']
+
+
+class ArtworkScope(Base):
+    """The artwork proxy: actual outgoing headers, through _images.get's own HTTP code."""
+
+    def setUp(self):
+        super().setUp()
+        self.sent, self.redirects = [], {}
+        _credentials.put('fdroid-user-private', _credentials.basic(PRIVATE, USER, PASSWORD))
+        test = self
+
+        class Response:
+            def __init__(self, status, location=''):
+                self.status, self.location, self.body = status, location, PNG if status == 200 else b''
+
+            def getheader(self, name, default=''):
+                return self.location if name == 'Location' else default
+
+            def read1(self, n):
+                chunk, self.body = self.body[:n], self.body[n:]
+                return chunk
+
+        class Connection:
+            def __init__(self, host, port, timeout=None):
+                self.host, self.port = host, port
+
+            def request(self, method, path, headers):
+                url = 'https://%s%s' % (self.host, path)
+                test.sent.append((url, headers.get('Authorization')))
+                self.url = url
+
+            def getresponse(self):
+                if self.url in test.redirects:
+                    return Response(302, test.redirects[self.url])
+                return Response(200)
+
+            def close(self):
+                pass
+
+        # A public address, no real socket or TLS, and Connection in place of http.client's.
+        for target, name, value in [(_images, '_resolve', lambda host, port, timeout: [(2, 1, 6, '', ('93.184.216.34', port))]),
+                                    (_images.socket, 'create_connection', lambda *a, **k: Mock()),
+                                    (_images.ssl, 'create_default_context', lambda: Mock()),
+                                    (_images.http.client, 'HTTPConnection', Connection)]:
+            mock = patch.object(target, name, value)
+            mock.start()
+            self.addCleanup(mock.stop)
+
+    def test_artwork_in_the_repository_gets_the_login(self):
+        self.assertEqual(_images.get(PRIVATE + 'icons/a%20b.png'), PNG)
+        self.assertEqual(self.sent, [(PRIVATE + 'icons/a%20b.png', basic(USER, PASSWORD))])
+
+    def test_paths_a_server_could_normalise_outside_the_repository_get_nothing(self):
+        for url in TRAVERSALS:
+            with self.subTest(url=url):
+                self.sent.clear()
+                self.assertEqual(_images.get(url), PNG)
+                self.assertEqual(self.sent, [(url, None)])
+                self.assertIsNone(_credentials.for_url(url))
+
+    def test_redirect_to_a_traversal_gets_nothing(self):
+        start = PRIVATE + 'icons/a.png'
+        self.redirects[start] = PRIVATE + '%2e%2e/%2e%2e/evil/collect.png'
+        self.assertEqual(_images.get(start), PNG)
+        self.assertEqual(self.sent, [(start, basic(USER, PASSWORD)), (self.redirects[start], None)])
+
+
+class ScopedHandler(Base):
+    """Handler(scoped=True), for callers (artwork-like) that must stay inside a scope, redirects included."""
+
+    def route(self, url, auth):
+        if url == PRIVATE + 'icons/a.png':
+            return 302, {'Location': PRIVATE + '%2e%2e/%2e%2e/evil/collect.png'}, b''
+        return 200, {}, PNG
+
+    def test_redirect_into_a_traversal_is_stripped(self):
+        login = _credentials.basic(PRIVATE, USER, PASSWORD)
+        opener = urllib.request.build_opener(_credentials.Handler(login, scoped=True))
+        with opener.open(PRIVATE + 'icons/a.png') as r:
+            self.assertEqual(r.read(), PNG)
+        self.assertEqual(self.web.seen, [(PRIVATE + 'icons/a.png', basic(USER, PASSWORD)),
+                                         (PRIVATE + '%2e%2e/%2e%2e/evil/collect.png', None)])
+        for url in TRAVERSALS:
+            self.assertFalse(_credentials.in_scope(login, url), url)
+        self.assertTrue(_credentials.in_scope(login, PRIVATE + 'a/b%20c.png?x=1'))
+        self.assertTrue(_credentials.in_scope(login, PRIVATE.rstrip('/')))
+
+
+CHURN = '''
+import sys
+sys.path.insert(0, sys.argv[1])
+from apk_sources import _credentials
+for i in range(int(sys.argv[3])):
+    key = sys.argv[2] + str(i)
+    _credentials.put(key, _credentials.basic('https://h.example/', 'u', 'p'))
+    if i % 2:
+        _credentials.remove(key)
+'''
+
+
+class TwoProcesses(Base):
+    def test_interleaved_saves_and_removals_are_not_lost(self):
+        ui = str(Path(__file__).resolve().parents[1] / 'ui')
+        env = dict(os.environ, FRAME_CONTROL_DATA_DIR=str(self.root / 'data'))
+        count = 60
+        procs = [subprocess.Popen([sys.executable, '-c', CHURN, ui, prefix, str(count)], env=env,
+                                  stdout=subprocess.PIPE, stderr=subprocess.PIPE) for prefix in ('a', 'b')]
+        for p in procs:
+            out, err = p.communicate(timeout=120)
+            self.assertEqual(p.returncode, 0, err.decode())
+        saved = set(json.loads(self.credentials_file().read_text()))
+        self.assertEqual(saved, {p + str(i) for p in 'ab' for i in range(0, count, 2)})
+        if os.name != 'nt':
+            self.assertEqual(stat.S_IMODE(self.credentials_file().stat().st_mode), 0o600)
+
+
+@unittest.skipUnless(shutil.which('node'), 'needs node')
+class PageLogin(unittest.TestCase):
+    def test_login_leaves_the_address_field_before_sending(self):
+        """tests/page/source_login.mjs runs the real page functions from index.html."""
+        r = subprocess.run(['node', str(Path(__file__).parent / 'page' / 'source_login.mjs')],
+                           capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+        self.assertIn('ok', r.stdout)
+
+
+class Endpoints(Repository):
+    """The server API: logins in, never out, in responses or the server log."""
+
+    def setUp(self):
+        super().setUp()
+        mock = patch.object(search, 'modules', return_value=([fdroid, github], []))
+        mock.start()
+        self.addCleanup(mock.stop)
+        self.httpd = server.ThreadingHTTPServer(('127.0.0.1', 0), server.Handler)
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+        self.addCleanup(self.httpd.server_close)
+        self.addCleanup(self.httpd.shutdown)
+
+    def request(self, method, path, body=None):
+        c = http.client.HTTPConnection('127.0.0.1', self.httpd.server_port)
+        c.request(method, path, json.dumps(body) if body is not None else None,
+                  {'X-Frame-UI': '1', 'Content-Type': 'application/json'})
+        r = c.getresponse()
+        raw = r.read().decode()
+        c.close()
+        self.replies.append(raw)
+        return r.status, json.loads(raw)
+
+    def job(self, reply):
+        for _ in range(500):
+            job = self.request('GET', '/api/job?id=' + reply['job'])[1]
+            if job['done']:
+                return job
+            time.sleep(.01)
+        self.fail('job did not finish')
+
+    def test_add_with_login_and_token_settings(self):
+        self.replies = []
+        bad = self.job(self.request('POST', '/api/sources', {'action': 'add', 'url': REPO, 'fingerprint': PIN,
+                                                             'username': USER, 'password': 'wrong'})[1])
+        self.assertIn('check the username and password', bad['error'])
+        self.assertEqual(fdroid.user_repos(), [])
+        code, reply = self.request('POST', '/api/sources', {'action': 'add', 'url': REPO, 'fingerprint': PIN,
+                                                            'username': USER, 'password': PASSWORD})
+        self.assertEqual(code, 200)
+        job = self.job(reply)
+        self.assertIsNone(job['error'])
+        listed = self.request('GET', '/api/sources')[1]['sources']
+        repo = next(s for s in listed if s['id'] == job['result']['source']['id'])
+        self.assertEqual((repo['url'], repo['login']), (REPO, True))
+        self.assertEqual(self.request('POST', '/api/sources', {'action': 'set-token', 'source': 'github',
+                                                               'token': TOKEN})[0], 200)
+        github_row = next(s for s in self.request('GET', '/api/sources')[1]['sources'] if s['id'] == 'github')
+        self.assertEqual(github_row['token'], {'set': True, 'from': 'saved', 'rejected': False})
+        self.assertEqual(self.request('POST', '/api/sources', {'action': 'set-token', 'source': 'fdroid',
+                                                               'token': TOKEN})[0], 400)
+        self.assertEqual(self.request('POST', '/api/sources', {'action': 'clear-token', 'source': 'github'})[0], 200)
+        self.assertFalse(_credentials.has('github'))
+        self.assertEqual(self.request('POST', '/api/sources', {'action': 'remove', 'source': repo['id']})[0], 200)
+        self.assertFalse(self.credentials_file().exists())
+        self.assertNoSecrets(*self.replies, self.stderr.getvalue(), self.disk())
+
+    def test_login_in_the_url_is_accepted(self):
+        self.replies = []
+        url = 'https://alice:s3cr%40t-p%C3%A4ssword@repo.example/fdroid/repo'
+        job = self.job(self.request('POST', '/api/sources', {'action': 'add', 'url': url, 'fingerprint': PIN})[1])
+        self.assertIsNone(job['error'])
+        self.assertEqual(fdroid.user_repos()[0]['url'], REPO)
+        self.assertNoSecrets(*self.replies, self.stderr.getvalue())
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_standalone_review.py

@@ -1,16 +0,0 @@
-"""Standalone page regressions with production JavaScript and no live services."""
-import shutil
-import subprocess
-import unittest
-from pathlib import Path
-
-
-@unittest.skipUnless(shutil.which('node'), 'Node exercises the standalone page scripts')
-class StandaloneReview(unittest.TestCase):
-    def test_behavior(self):
-        root = Path(__file__).resolve().parents[1]
-        result = subprocess.run(
-            ['node', '--test', str(root / 'tests/standalone_review.cjs')],
-            capture_output=True, text=True, timeout=30,
-        )
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

tests/test_store_categories.py

@@ -1,361 +0,0 @@
-"""The store's Frame categories (ui/apk_sources/_categories.py): which apps go where, which are
-phone-only and hidden, and how the browse, search and library artwork use them. Offline."""
-import sandbox  # noqa: F401  (first: keeps tests off real data and services)
-import json
-from pathlib import Path
-import sys
-import tempfile
-import types
-import unittest
-from unittest.mock import patch
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
-from apk_sources import SourceError, _categories, _images, fdroid, search  # noqa: E402
-import test_fdroid_sources as fixtures  # noqa: E402  (a module, so its tests don't run twice)
-FIXTURES, PIN, URL = fixtures.FIXTURES, fixtures.PIN, fixtures.URL
-
-
-def kind(**entry):
-    return _categories.classify(dict({'name': 'App', 'summary': ''}, **entry))
-
-
-class Classify(unittest.TestCase):
-    def test_vr_first_whatever_else_it_is(self):
-        self.assertEqual(kind(vr=True, categories=['Phone & SMS']), {'category': 'vr', 'phone_only': False})
-
-    def test_fine_categories_decide(self):
-        self.assertEqual(kind(categories=['Games', 'Puzzle Game'])['category'], 'games')
-        self.assertEqual(kind(categories=['Games', 'Emulator'])['category'], 'emulators')
-        # A chat app is in Multimedia too; the finer Social Network wins.
-        self.assertEqual(kind(categories=['Multimedia', 'Internet', 'Social Network'])['category'], 'web')
-        self.assertEqual(kind(categories=['Reading', 'Ebook Reader'])['category'], 'read')
-        self.assertEqual(kind(categories=['Multimedia', 'Podcast'])['category'], 'watch')
-
-    def test_broad_categories_alone(self):
-        self.assertEqual(kind(categories=['Multimedia']), {'category': 'watch', 'phone_only': False})
-        self.assertEqual(kind(categories=['Writing']), {'category': 'work', 'phone_only': False})
-
-    def test_phone_only(self):
-        for categories in (['System', 'Launcher'], ['Internet', 'VPN & Proxy'], ['Theming', 'Wallpaper'],
-                           ['Sports & Health'], ['Connectivity'], ['Time', 'Alarm Clock'], ['Habit Tracker']):
-            with self.subTest(categories=categories):
-                self.assertTrue(kind(categories=categories)['phone_only'])
-        self.assertTrue(kind(name='[ROOT] Night Light', categories=['Development'])['phone_only'])
-        self.assertTrue(kind(name='5G Proxy Client', summary='Routes traffic')['phone_only'])
-
-    def test_games_and_media_keep_phone_words(self):
-        # 'Battery' in a game's name or a widget in a music player doesn't hide a game or a player.
-        self.assertFalse(kind(name='Widget Wars', categories=['Strategy Game'])['phone_only'])
-        self.assertFalse(kind(name='Music', summary='with a home screen widget', categories=['Local Media Player'])['phone_only'])
-
-    def test_emulators_by_name_without_categories(self):
-        self.assertEqual(kind(name='RetroArch', summary='Frontend for emulators')['category'], 'emulators')
-
-    def test_unknown_is_neither_hidden_nor_guessed(self):
-        self.assertEqual(kind(name='Thing'), {'category': None, 'phone_only': False})
-        self.assertEqual(kind(categories=['Something New']), {'category': None, 'phone_only': False})
-
-    def test_matches(self):
-        phone = {'category': 'tools', 'phone_only': True}
-        self.assertFalse(_categories.matches(phone))
-        self.assertTrue(_categories.matches(phone, phone=True))
-        self.assertTrue(_categories.matches({'category': 'games', 'phone_only': False}, 'games'))
-        self.assertFalse(_categories.matches({'category': 'watch', 'phone_only': False}, 'games'))
-
-    def test_every_store_category_has_a_label(self):
-        self.assertEqual({c for c, _ in _categories.CATEGORIES}, _categories.IDS)
-        targets = set(_categories.FINE) | {c for c in _categories.BROAD.values() if c}
-        self.assertLessEqual(targets, _categories.IDS)
-        self.assertLessEqual(set(_categories.PRIORITY), _categories.IDS)
-
-
-class FDroidCategories(unittest.TestCase):
-    setUp, fetch, add = fixtures.Repositories.setUp, fixtures.Repositories.fetch, fixtures.Repositories.add
-
-    def index(self, version, categories):
-        raw = json.loads((FIXTURES / ('artwork-' + version + '.json')).read_text())
-        if version == 'v2':
-            raw['packages']['org.example.app']['metadata']['categories'] = categories
-        else:
-            raw['apps'][0]['categories'] = categories
-        path = self.root / ('index-' + version + '.json')
-        path.write_text(json.dumps(raw))
-        if version == 'v1':
-            fdroid._v1(path.read_bytes(), path)
-        return path
-
-    def test_categories_survive_v1_and_v2(self):
-        source = self.add()
-        for version in ('v1', 'v2'):
-            with self.subTest(version=version):
-                apps = fdroid._reduce(self.index(version, ['Games', 'Puzzle Game', 7]), source)
-                self.assertEqual(apps['org.example.app']['categories'], ['Games', 'Puzzle Game'])
-
-    def save(self, source, apps):
-        fdroid._write(fdroid.frame_host.cache_dir('apk-sources', source['id'] + '.json'),
-                      {'version': fdroid.CACHE_VERSION, 'url': URL, 'fingerprint': PIN, 'apps': apps})
-
-    def app(self, pkg, name, updated, categories=(), banner=None):
-        return {'source': 'x', 'id': pkg, 'package': pkg, 'name': name, 'summary': '', 'updated': updated,
-                'categories': list(categories), 'images': {'icon': None, 'banner': banner, 'screenshots': []}}
-
-    def test_browse_shows_artwork_then_newest_and_filters_before_the_limit(self):
-        source = self.add()
-        self.save(source, {a['id']: a for a in (
-            self.app('a.old', 'Aaa', '2020-01-01', ['Puzzle Game']),
-            self.app('b.new', 'Bbb', '2026-01-01', ['Puzzle Game']),
-            self.app('c.art', 'Ccc', '2019-01-01', ['Puzzle Game'], banner=URL + 'b.png'),
-            self.app('d.sms', 'Ddd', '2026-02-01', ['Phone & SMS']))})
-        self.assertEqual([a['id'] for a in fdroid.search(source, '', limit=10)], ['c.art', 'd.sms', 'b.new', 'a.old'])
-        keep = lambda e: _categories.matches(dict(e, **_categories.classify(e)))
-        self.assertEqual([a['id'] for a in fdroid.search(source, '', limit=1, keep=keep)], ['c.art'])
-        self.assertEqual([a['id'] for a in fdroid.search(source, 'a', limit=10)], ['a.old', 'c.art'])  # a query sorts by name
-
-    def test_lookup_reads_the_saved_index_only(self):
-        source = self.add()
-        self.assertEqual(fdroid.lookup(dict(source, id='never-loaded'), ['org.example.app']), {})
-        self.save(source, {'a.b': self.app('a.b', 'A', None)})
-        before = self.fetch_mock.call_count
-        self.assertEqual(list(fdroid.lookup(source, ['a.b', 'missing'])), ['a.b'])
-        self.assertEqual(self.fetch_mock.call_count, before)
-        self.assertEqual(fdroid.lookup(dict(source, enabled=False), ['a.b']), {})
-
-
-def fake_source(entries, kind_='fake', lookup=None):
-    mod = types.SimpleNamespace(KIND=kind_)
-    mod.sources = lambda: [{'id': kind_, 'kind': kind_, 'name': kind_.title(), 'url': 'https://example.org/',
-                            'builtin': True, 'enabled': True, 'trust': 'community'}]
-    mod.search = lambda source, query, limit=50: [dict(e) for e in entries][:limit]
-    mod.details = lambda source, entry_id: next(dict(e) for e in entries if e['id'] == entry_id)
-    if lookup is not None:
-        mod.lookup = lookup
-    return mod
-
-
-ENTRY = {'source': 'fake', 'package': None, 'summary': '', 'free': True, 'downloadable': True,
-         'min_sdk': 24, 'abis': ['arm64-v8a'], 'vr': None}
-
-
-class Search(unittest.TestCase):
-    def setUp(self):
-        tmp = tempfile.TemporaryDirectory()
-        self.addCleanup(tmp.cleanup)
-        p = patch.object(search, 'settings_path', return_value=Path(tmp.name) / 'sources.json')
-        p.start()
-        self.addCleanup(p.stop)
-        for state in (search._running, search._pending, search._status):
-            state.clear()
-            self.addCleanup(state.clear)
-
-    def run_search(self, entries, **kwargs):
-        with patch.object(search, 'modules', return_value=([fake_source(entries)], [])):
-            return search.search(**kwargs)
-
-    def test_category_and_phone_filters(self):
-        entries = [dict(ENTRY, id='g', name='Game', categories=['Puzzle Game']),
-                   dict(ENTRY, id='s', name='Texts', categories=['Phone & SMS']),
-                   dict(ENTRY, id='v', name='Video', categories=['Local Media Player'])]
-        result = self.run_search(entries)
-        self.assertEqual(sorted(a['name'] for a in result['apps']), ['Game', 'Video'])
-        self.assertEqual({a['name']: a['category'] for a in result['apps']}, {'Game': 'games', 'Video': 'watch'})
-        self.assertIn({'id': 'emulators', 'label': 'Emulators'}, result['categories'])
-        self.assertEqual([a['name'] for a in self.run_search(entries, category='games')['apps']], ['Game'])
-        self.assertEqual(len(self.run_search(entries, phone=True)['apps']), 3)
-        with self.assertRaisesRegex(SourceError, 'Unknown category'):
-            self.run_search(entries, category='phones')
-
-    def test_listing_offers_three_screenshots_details_all(self):
-        shots = ['https://example.org/%d.png' % i for i in range(8)]
-        entry = dict(ENTRY, id='g', name='Game', images={'icon': None, 'banner': None, 'screenshots': shots})
-        listed = self.run_search([entry])['apps'][0]['offers'][0]
-        self.assertEqual(len(listed['artwork']['screenshots']), 3)
-        self.assertEqual(len(search.decorate(entry)['artwork']['screenshots']), 8)
-
-    def test_browse_asks_sources_for_more_than_a_search(self):
-        seen = []
-        mod = fake_source([])
-        mod.search = lambda source, query, limit=50: seen.append((query, limit)) or []
-        with patch.object(search, 'modules', return_value=([mod], [])):
-            search.search('')
-            search.search('chess')
-        self.assertEqual(seen, [('', search.BROWSE_LIMIT), ('chess', 50)])
-
-
-class LibraryArtwork(unittest.TestCase):
-    def setUp(self):
-        tmp = tempfile.TemporaryDirectory()
-        self.addCleanup(tmp.cleanup)
-        p = patch.object(search, 'settings_path', return_value=Path(tmp.name) / 'sources.json')
-        p.start()
-        self.addCleanup(p.stop)
-
-    def test_by_package_from_saved_indexes_then_by_name_for_curated_apps(self):
-        icon = {'images': {'icon': 'https://example.org/icon.png', 'banner': None, 'screenshots': []}}
-        repo = fake_source([], 'fdroid', lookup=lambda source, packages: {
-            p: dict(icon, name='x') for p in packages if p == 'org.antennapod'})
-        github = fake_source([dict(icon, id='icosa/open-brush', name='Open Brush')], 'github')
-        bare = fake_source([dict(icon, id='x', name='Elsewhere', package='org.elsewhere')], 'itch')
-        apps = [{'package': 'org.antennapod', 'label': 'AntennaPod'}, {'package': 'com.Icosa.OpenBrush', 'label': 'Open Brush'},
-                {'package': 'org.elsewhere', 'label': 'Elsewhere'}, {'package': 'org.none', 'label': 'None'}]
-        with patch.object(search, 'modules', return_value=([repo, github, bare], [])):
-            found = search.artwork_for(apps)
-        self.assertEqual(sorted(found), ['com.Icosa.OpenBrush', 'org.antennapod'])
-        self.assertTrue(found['org.antennapod']['icon'].startswith('/source-image/'))
-
-    def test_a_failing_source_is_skipped(self):
-        def broken(source, packages):
-            raise SourceError('no')
-        with patch.object(search, 'modules', return_value=([fake_source([], 'fdroid', lookup=broken)], [])):
-            self.assertEqual(search.artwork_for([{'package': 'a.b', 'label': 'A'}]), {})
-
-
-class ImageHandles(unittest.TestCase):
-    def test_same_url_same_handle_without_scanning(self):
-        with _images._lock:
-            _images._urls.clear()
-            _images._tokens.clear()
-        a = _images.register('https://example.org/a.png')
-        self.assertEqual(_images.register('https://example.org/a.png'), a)
-        self.assertNotEqual(_images.register('https://example.org/b.png'), a)
-
-
-
-class Route(unittest.TestCase):
-    def test_search_filters_are_checked(self):
-        import server
-        with patch.object(server.apk_search, 'search', return_value={'apps': []}) as run:
-            server.source_search('q=&category=games&phone=1')
-            self.assertEqual(run.call_args.kwargs['category'], 'games')
-            self.assertIs(run.call_args.kwargs['phone'], True)
-            server.source_search('q=chess')
-            self.assertEqual((run.call_args.kwargs['category'], run.call_args.kwargs['phone']), (None, False))
-            for bad in ('phone=maybe', 'category=' + 'x' * 41):
-                with self.subTest(bad=bad), self.assertRaises(server.Failure):
-                    server.source_search(bad)
-
-
-
-class ReviewCases(unittest.TestCase):
-    """Real index entries (October 2026) that the first rules got wrong."""
-    def test_useful_apps_with_a_phone_side_stay(self):
-        for categories, category in ((['Connectivity', 'Email', 'Internet', 'Writing'], 'web'),  # Thunderbird
-                                     (['Connectivity', 'Internet', 'Multimedia', 'Podcast'], 'watch'),  # FocusPodcast
-                                     (['Contact', 'Email'], 'web'),
-                                     (['Cloud Storage & File Sync', 'File Manager', 'System'], 'tools')):
-            with self.subTest(categories=categories):
-                self.assertEqual(kind(categories=categories), {'category': category, 'phone_only': False})
-
-    def test_phone_side_alone_or_with_a_broad_category_is_hidden(self):
-        for categories in (['Internet', 'VPN & Proxy'], ['App Manager', 'Development', 'System'], ['Navigation']):
-            with self.subTest(categories=categories):
-                self.assertTrue(kind(categories=categories)['phone_only'])
-        self.assertTrue(kind(categories=['Launcher', 'Games'])['phone_only'])  # system ones always
-
-    def test_no_root_needed_is_not_a_root_tool(self):
-        for summary in ('Linux on Android, no root required', 'Linux Without Root Access', 'SSH server without root',
-                        'Works on non-rooted phones', 'Rootless and simple'):
-            with self.subTest(summary=summary):
-                self.assertFalse(kind(summary=summary, categories=['Development'])['phone_only'])
-        self.assertTrue(kind(summary='Needs root to tune the kernel', categories=['Development'])['phone_only'])
-
-    def test_izzyondroid_names(self):
-        self.assertEqual(kind(categories=['Office'])['category'], 'work')
-        self.assertTrue(kind(categories=['Xposed'])['phone_only'])
-
-
-
-class ReviewCasesTwo(unittest.TestCase):
-    """Round two of real entries (October 2026)."""
-    def test_messengers_with_phone_or_push_stay(self):
-        for categories in (['Internet', 'Messaging', 'Phone & SMS'], ['Internet', 'Messaging', 'Push'],
-                           ['Connectivity', 'Messaging', 'Phone & SMS', 'Voice & Video Chat']):
-            with self.subTest(categories=categories):
-                self.assertEqual(kind(categories=categories), {'category': 'web', 'phone_only': False})
-
-    def test_broad_only_sources_can_escape_a_phone_side(self):
-        self.assertEqual(kind(categories=['System', 'Development']), {'category': 'tools', 'phone_only': False})
-        self.assertEqual(kind(categories=['Connectivity', 'Internet']), {'category': 'web', 'phone_only': False})
-        self.assertTrue(kind(categories=['VPN & Proxy', 'Internet'])['phone_only'])  # it has finer ones, none useful
-
-    def test_summary_features_dont_make_a_phone_app(self):
-        self.assertFalse(kind(name='OSS Weather', summary='Forecasts with home screen widgets', categories=['Weather'])['phone_only'])
-        self.assertFalse(kind(name='Digital Calculator', summary='Hardware keyboard support', categories=['Calculator', 'System'])['phone_only'])
-        self.assertTrue(kind(name='Clock Widget', categories=['Clock'])['phone_only'])  # but the name says what it is
-
-    def test_saying_root_isnt_needed(self):
-        for summary in ('VNC server app that does not require root privileges', "Backups that don't need root access",
-                        "It doesn't need root", 'Linux without root', 'Works on non-rooted phones', 'Rootless'):
-            with self.subTest(summary=summary):
-                self.assertFalse(kind(summary=summary, categories=['Remote Access'])['phone_only'])
-        for summary in ('Requires root', 'Needs root access to change the kernel', 'For rooted devices'):
-            with self.subTest(summary=summary):
-                self.assertTrue(kind(summary=summary, categories=['Remote Access'])['phone_only'])
-
-    def test_hardware_the_frame_lacks(self):
-        self.assertTrue(kind(name='IR Blaster Remote', categories=['Multimedia', 'Remote Controller', 'System'])['phone_only'])
-        self.assertTrue(kind(name='Wear Sync for Breezy', summary='Weather on your Wear OS watch', categories=['Connectivity', 'Weather'])['phone_only'])
-
-
-class SearchFindsPhoneApps(unittest.TestCase):
-    setUp, run_search = Search.setUp, Search.run_search
-
-    def test_a_search_finds_what_browsing_hides(self):
-        entries = [dict(ENTRY, id='s', name='Texts', categories=['Phone & SMS'])]
-        self.assertEqual(self.run_search(entries)['apps'], [])
-        found = self.run_search(entries, query='texts')['apps']
-        self.assertEqual([(a['name'], a['offers'][0]['phone_only']) for a in found], [('Texts', True)])
-
-
-
-class ArtworkLookups(unittest.TestCase):
-    """A page of cards asks for dozens of images at once; they mustn't fail for want of a lookup slot."""
-    def setUp(self):
-        _images._dns.clear()
-        self.addCleanup(_images._dns.clear)
-
-    def test_public_answers_are_kept_private_ones_are_not(self):
-        public = [(2, 1, 6, '', ('93.184.216.34', 443))]
-        with patch.object(_images.socket, 'getaddrinfo', return_value=public) as lookup:
-            for _ in range(3):
-                self.assertEqual(_images._resolve('example.org', 443, 5), public)
-        self.assertEqual(lookup.call_count, 1)
-        private = [(2, 1, 6, '', ('10.0.0.5', 443))]
-        with patch.object(_images.socket, 'getaddrinfo', return_value=private) as lookup:
-            _images._resolve('inside.example', 443, 5)
-            _images._resolve('inside.example', 443, 5)
-        self.assertEqual(lookup.call_count, 2)
-
-    def test_waiting_for_a_slot_counts_against_the_budget(self):
-        import threading, time
-        gate = threading.Event()
-        for _ in range(4):  # every slot busy for the whole test
-            _images._resolvers.acquire()
-        threading.Timer(0.06, lambda: [_images._resolvers.release() for _ in range(4)]).start()
-        with patch.object(_images.socket, 'getaddrinfo', side_effect=lambda *a, **k: gate.wait(2) and []):
-            start = time.monotonic()
-            with self.assertRaises(SourceError):
-                _images._resolve('slow.example', 443, 0.1)
-            self.assertLess(time.monotonic() - start, 0.16)
-        gate.set()
-
-    def test_many_at_once_wait_for_a_slot(self):
-        import threading, time
-        public = [(2, 1, 6, '', ('93.184.216.34', 443))]
-        def slow(*a, **k):
-            time.sleep(0.05)
-            return public
-        errors = []
-        def one(i):
-            try:
-                _images._resolve('host%d.example' % i, 443, 5)
-            except SourceError as e:
-                errors.append(e)
-        with patch.object(_images.socket, 'getaddrinfo', side_effect=slow):
-            threads = [threading.Thread(target=one, args=(i,)) for i in range(12)]
-            [t.start() for t in threads]
-            [t.join() for t in threads]
-        self.assertEqual(errors, [])
-
-
-if __name__ == '__main__':
-    unittest.main()

tests/test_ui_review.py

@@ -1,13 +0,0 @@
-"""Production client race/error regressions, without any headset or browser writes."""
-import shutil
-import subprocess
-import unittest
-from pathlib import Path
-
-
-@unittest.skipUnless(shutil.which('node'), 'Node exercises production page functions')
-class UIReview(unittest.TestCase):
-    def test_behavior(self):
-        root = Path(__file__).resolve().parents[1]
-        result = subprocess.run(['node', '--test', str(root / 'tests/ui_review.cjs')], capture_output=True, text=True)
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

tests/test_ui_workspace.py

@@ -1,14 +0,0 @@
-"""Production navigation and app actions, without a browser or headset."""
-import shutil
-import subprocess
-import unittest
-from pathlib import Path
-
-
-@unittest.skipUnless(shutil.which('node'), 'Node exercises shared page behavior')
-class Workspace(unittest.TestCase):
-    def test_behavior(self):
-        root = Path(__file__).resolve().parents[1]
-        result = subprocess.run(['node', '--test', str(root / 'tests/ui_workspace.cjs')],
-                                capture_output=True, text=True)
-        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

tests/ui_review.cjs

@@ -1,116 +0,0 @@
-const test = require('node:test'), assert = require('node:assert/strict');
-const fs = require('node:fs'), vm = require('node:vm');
-const {workspaceFixture, html} = require('./workspace_fixture.cjs');
-const store = fs.readFileSync(require.resolve('../ui/store.html'),'utf8');
-const pick = (s,a,b) => s.slice(s.indexOf(a),s.indexOf(b,s.indexOf(a)));
-const tick = async () => { for (let i=0;i<16;i++) await Promise.resolve(); };
-function connectionFixture() {
-  const f=workspaceFixture(), c=f.context;
-  Object.assign(c,{URLSearchParams,Date,clearTimeout,link:{s:{phase:'connected'},device:'a',phase:'connected',rev:0},disp:{list:[],seq:0},cat:{apps:null},wi:{},devGen:1,androidSeq:0,androidPending:new Set(),titlesSeq:0,volTimer:null,refreshing:null,lastImg:null,lastShot:null,
-    sourceState:{jobs:new Map(),detail:null,detailRequest:0},touches:new Map(),gesture:null,padType:{blur(){},value:''},
-    log(){},renderPill(){},renderConnDlg(){},renderHome(){},resetShots(){},renderBanner(){},loadDevices(){},renderDevices(){},renderTests(){},viaText(){return 'test';},netLabel(){return 'test';},refresh:()=>Promise.resolve(),reloadAll(){},checkContactPrompt(){},ctrlReset(){},padShow:s=>{c.pad.state=s.state;}});
-  c.window.connDevice='a';
-  f.run('const UI_KEY="test";'+pick(html,'const HEADSET_FREE =','// What a panel shows'));
-  f.run(pick(html,'function onConnection(s) {','// Read the event stream'));
-  return f;
-}
-test('helper starts and status reads name the headset shown when requested',async()=>{
-  const f=connectionFixture(),c=f.context,requests=[];
-  c.fetch=async(path,opts)=>{requests.push({path,opts});return {ok:true,json:async()=>({state:'ready'})};};
-  await f.run("api('/api/input?start=1')");
-  await f.run("api('/api/touch?start=1')");
-  c.window.connDevice='b';
-  await f.run("api('/api/input')");
-  assert.deepEqual(requests.map(r=>r.opts.headers['X-Frame-Device']),['a','a','b']);
-  assert.ok(requests.every(r=>r.opts.method===undefined&&r.opts.body===undefined));
-  delete c.window.connDevice; // A local iOS server has one fixed SSH route.
-  await f.run("api('/api/touch?start=1')");
-  assert.equal(requests[3].opts.headers['X-Frame-Device'],undefined);
-});
-test('a late input failure cannot replay A keystrokes on B',async()=>{
-  const f=connectionFixture(),c=f.context,writes=[];let rejectA;
-  Object.assign(c,{pad:{state:'ready',queue:[],sending:false},fetch:(path,opts)=>{writes.push({device:opts.headers['X-Frame-Device'],events:JSON.parse(opts.body).events});return writes.length===1?new Promise((_,reject)=>rejectA=reject):Promise.resolve({ok:true,json:async()=>({state:'ready',sent:true})});}});
-  f.run(pick(html,'const isMove = e =>','function padKey('));f.run('padSend({key:"for A"})');
-  f.run('onConnection({phase:"connected",device:{id:"b",name:"B"},devices_rev:1,now:0})');
-  assert.equal(c.pad.state,'off');assert.equal(c.pad.queue.length,0);
-  rejectA(Error('lost A'));await tick();c.pad.state='ready';f.run('padSend({key:"for B"})');await tick();
-  assert.equal(writes.length,2);assert.equal(writes[1].device,'b');assert.equal(writes[1].events[0].key,'for B');
-});
-test('a device switch discards completed install results and the open detail',()=>{
-  const f=connectionFixture(),c=f.context;
-  Object.assign(c,{pad:{state:'off',queue:[]},padReset(){},sourceState:{jobs:new Map([['test:one',{done:true,result:{package:'app.on.a',game_data:true}}]]),detail:{app:{}},detailRequest:0}});
-  f.el('appDetail').open=true;
-  f.run('onConnection({phase:"connected",device:{id:"b",name:"B"},devices_rev:1,now:0})');
-  assert.equal(c.sourceState.jobs.size,0);assert.equal(c.sourceState.detail,null);assert.equal(f.el('appDetail').open,false);
-});
-test('only a preview matching current diagnostics consent can be sent or copied',async()=>{
-  const els=new Map(),$=id=>{if(!els.has(id))els.set(id,{checked:false,value:'',textContent:'',children:[]});return els.get(id);};let pending=[],sent;
-  const c={$ ,api:(path,body)=>path==='/api/report/preview'?new Promise(resolve=>pending.push({body,resolve})):Promise.resolve({}),log(){},renderContact(){}};vm.createContext(c);
-  vm.runInContext(pick(html,'const bug = {','function openBugReport()'),c);
-  vm.runInContext(pick(html,'$("bugForm").onsubmit =','if (window.frameApp && window.frameApp.onReportProblem)'),c);
-  $('bugForm').reportValidity=()=>true;$('bugDiag').checked=true;$('bugLogs').checked=true;
-  const a=vm.runInContext('loadBugPreview()',c);$('bugLogs').checked=false;const b=vm.runInContext('loadBugPreview()',c);
-  assert.doesNotMatch(vm.runInContext('bugReportText().body',c),/SECRET/);
-  pending[1].resolve({text:'safe summary'});await b;pending[0].resolve({text:'SECRET SERVER LOG'});await a;
-  c.api=(path,body)=>{if(path==='/api/report')sent=body;return Promise.resolve({id:'stub',message:'stub'});};
-  await $('bugForm').onsubmit({preventDefault(){}});assert.equal(sent.diagnostics,'safe summary');
-  $('bugDiag').checked=false;await vm.runInContext('loadBugPreview()',c);
-  assert.doesNotMatch(vm.runInContext('bugReportText().body',c),/safe summary|SECRET/);
-  $('bugDiag').checked=true;c.api=(path,body)=>new Promise(resolve=>pending.push({body,resolve}));
-  const late=vm.runInContext('loadBugPreview()',c);$('bugDiag').checked=false;await vm.runInContext('loadBugPreview()',c);
-  pending[2].resolve({text:'LATE SECRET'});await late;
-  assert.doesNotMatch(vm.runInContext('bugReportText().body',c),/SECRET/);
-});
-test('clearing Steam search invalidates a pending query and pending country lookup',async()=>{
-  const el={value:'Portal'},gm={country:'US',src:'store',store:[],storeQ:null,seq:0,shownBySource:{}};let resolve;
-  const c={$:()=>el,gm,api:()=>new Promise(r=>resolve=r),renderChips(){},filterGames(){},encodeURIComponent};vm.createContext(c);
-  vm.runInContext(pick(html,'async function searchStore() {','function setGameSource('),c);
-  const a=vm.runInContext('searchStore()',c);el.value='';await vm.runInContext('searchStore()',c);resolve({results:[{name:'Portal'}]});await a;
-  assert.equal(gm.storeQ,null);assert.equal(gm.store.length,0);
-});
-test('failed installed reads remain unknown or stale with retry, never successful empty',async()=>{
-  const els=new Map(),$=id=>{if(!els.has(id))els.set(id,{textContent:'',innerHTML:'',setAttribute(){}});return els.get(id);};
-  const st={installed:new Map(),needsData:new Set(),jobs:new Map(),view:'installed',q:'',loading:false,apps:[],page:0,installedState:'unknown',installedError:'',installedRequest:0};
-  const c={$ ,st,api:async()=>{throw Error('offline');},toast(){},document:{querySelectorAll:()=>[]},PER_PAGE:8,catLabel:x=>x,esc:x=>x};vm.createContext(c);
-  vm.runInContext(pick(store,'async function loadInstalled() {','async function search('),c);vm.runInContext(pick(store,'function list() {','function card('),c);vm.runInContext(pick(store,'function render(error) {','function turn('),c);
-  await vm.runInContext('loadInstalled()',c);vm.runInContext('render()',c);
-  assert.doesNotMatch($('content').innerHTML,/Nothing installed yet/);assert.match($('content').innerHTML,/data-retry-installed/);
-  st.installed.set('app',{package:'app',label:'Cached App'});st.installedState='ready';
-  c.card=()=>'<button>Cached App</button>';await vm.runInContext('loadInstalled()',c);vm.runInContext('render()',c);
-  assert.match($('content').innerHTML,/Cached App/);assert.match($('content').innerHTML,/data-retry-installed/);
-  c.api=async()=>({apps:[]});await vm.runInContext('loadInstalled()',c);vm.runInContext('render()',c);
-  assert.match($('content').innerHTML,/Nothing installed yet/);assert.doesNotMatch($('content').innerHTML,/data-retry-installed/);
-});
-
-test('capture control discards old releases, timers and readiness on a target switch',async()=>{
-  const f=connectionFixture(),c=f.context,writes=[];let rejectA;
-  Object.assign(c,{ctrl:{on:true,queue:[],sending:false,state:'ready',held:new Set(['left']),keys:new Set([30]),pointers:new Map(),g:null,rel:[1,2]},desk:{panels:[{window:4}],focus:'old',shown:'old',loaded:true},cancelAnimationFrame(){},ctrlShow(){},ctrlAim:e=>e,
-    pad:{queue:[],state:'off'},padReset(){},fetch:(path,opts)=>{writes.push({device:opts.headers['X-Frame-Device'],events:JSON.parse(opts.body).events});return writes.length===1?new Promise((_,reject)=>rejectA=reject):Promise.resolve({ok:true,json:async()=>({state:'ready',sent:true})});}});
-  f.run(pick(html,'function ctrlReset() {','// Pointer moves:'));
-  f.run('ctrlSend([{key:30,down:false}])');
-  f.run('onConnection({phase:"connected",device:{id:"b",name:"B"},devices_rev:1,now:0})');
-  assert.equal(c.ctrl.on,false);assert.equal(c.ctrl.state,'off');assert.equal(c.ctrl.held.size,0);assert.equal(c.desk.panels.length,0);
-  rejectA(Error('lost A'));await tick();
-  assert.equal(c.ctrl.queue.length,0);assert.equal(c.ctrl.retryAt,0);assert.equal(writes.length,1);
-});
-
-test('late installation completion cannot populate the new headset detail',async()=>{
-  const f=workspaceFixture(),c=f.context,offer={source:'catalog',id:'one',name:'One',package:'app.one',downloadable:true};let finish,progress,refreshes=0;
-  Object.assign(c,{sourceState:{jobs:new Map()},currentOffer:()=>offer,sourcePage:()=>'',loadAndroid:()=>refreshes++,
-    runJob:async(_label,_key,start,update)=>{progress=update;await start();return new Promise(resolve=>finish=resolve);},api:async()=>({job:'a'})});
-  f.run(pick(html,'function updateInstall() {','async function openStoreApp('));f.run(pick(html,'async function installStoreApp() {','async function changeSource('));
-  const pending=f.run('installStoreApp()');await tick();
-  c.devGen++;c.sourceState.jobs.clear();f.el('detailInstall').textContent='New headset';
-  progress({stage:'Installing',percent:90});finish({package:'app.one',game_data:true});await pending;
-  assert.equal(c.sourceState.jobs.size,0);assert.equal(f.el('detailInstall').textContent,'New headset');assert.equal(refreshes,0);
-});
-
-test('late input startup and touch poll responses cannot re-enable the old target',async()=>{
-  const f=workspaceFixture(),c=f.context;let finish;
-  Object.assign(c,{pad:{state:'off'},clientPreferences:{set(){}},padShow:s=>{c.pad.state=s.state;},api:()=>new Promise(resolve=>finish=resolve)});
-  f.run(pick(html,'async function padStart() {','$("padOn").onclick'));
-  const start=f.run('padStart()');c.devGen++;c.pad.state='off';finish({state:'ready'});await start;assert.equal(c.pad.state,'off');
-  Object.assign(c,{ctrl:{on:true,state:'off'},ctrlShow(){},ctrlFlush(){throw Error('Must not flush stale input');}});
-  f.run(pick(html,'async function ctrlPoll(', '$("viewer").tabIndex'));
-  const poll=f.run('ctrlPoll(0)');c.devGen++;c.ctrl.on=false;finish({state:'ready'});await poll;assert.equal(c.ctrl.state,'off');
-});

tests/ui_workspace.cjs

@@ -1,289 +0,0 @@
-const test=require('node:test');
-const assert=require('node:assert/strict');
-const {workspaceFixture,html}=require('./workspace_fixture.cjs');
-const deferred=()=>{let resolve,reject;const promise=new Promise((ok,bad)=>{resolve=ok;reject=bad;});return {promise,resolve,reject};};
-function installFixture() {
-  const f=workspaceFixture();
-  Object.assign(f.context,{wi:{queue:[]},wiNext(){f.calls.push(['review']);},sendFiles:files=>f.calls.push(['files',files])});
-  const start=html.indexOf('function openInstallChooser()'),end=html.indexOf('function renderHome(',start);
-  f.run(html.slice(start,end));return f;
-}
-test('Add / Install retains cancellation and hands chosen files to the existing transfer flow',()=>{
-  const f=installFixture(),input=f.el('installFileInput');let clicks=0;
-  input.click=()=>clicks++;f.run('openInstallChooser()');f.el('installChooseFile').onclick();assert.equal(clicks,1);
-  input.files=[];input.onchange();assert.equal(f.el('installChooser').open,true);assert.equal(f.calls.length,0);
-  const files=[{name:'game.zip'},{name:'player.apk'}];input.files=files;input.value='chosen';input.onchange();
-  assert.equal(f.el('installChooser').open,false);assert.equal(f.context.location.hash,'#transfer');assert.equal(input.value,'');
-  assert.deepEqual(Array.from(f.calls[0][1]),files);
-});
-test('chooser destinations reapply explicit views when their hash is already active',()=>{
-  const cases=[['#appStore',"selectApps('installed')",f=>assert.equal(f.el('appStore').hidden,false)],
-    ['#linuxApps',"selectApps('browse')",f=>assert.equal(f.el('appsLinux').hidden,false)],
-    ['#getgames',"selectLibrary('all','installed')",f=>assert.equal(f.context.gm.src,'owned')],
-    ['#steamStore',"selectLibrary('all','owned')",f=>assert.equal(f.context.gm.src,'store')]];
-  for(const [hash,change,verify] of cases){
-    const f=installFixture();f.navigate(hash);f.run(change);f.run('openInstallChooser()');let prevented=false;
-    f.el('installChooser').onclick({target:{closest:()=>({getAttribute:()=>hash})},preventDefault(){prevented=true;}});
-    assert.equal(prevented,true,hash);assert.equal(f.el('installChooser').open,false);verify(f);
-  }
-});
-test('download links accept supported direct and manifest forms and reject malformed handoffs',()=>{
-  const f=installFixture();
-  for(const [raw,expected] of [
-    [' https://example.com/game.zip ',{kind:'url',target:'https://example.com/game.zip'}],
-    ['frame-control://install?url=https%3A%2F%2Fexample.com%2Fapp.apk',{kind:'url',target:'https://example.com/app.apk'}],
-    ['frame-control://install?manifest=https%3A%2F%2Fexample.com%2Fgame.json',{kind:'manifest',target:'https://example.com/game.json'}]
-  ]){f.context.raw=raw;assert.deepEqual(JSON.parse(JSON.stringify(f.run('installLinkRequest(raw)'))),expected);}
-  for(const raw of ['file:///tmp/app.apk','javascript:alert(1)','https://user:secret@example.com/a.apk',
-    'frame-control://other?url=https://example.com/a.apk','frame-control://install/path?url=https://example.com/a.apk',
-    'frame-control://install?url=https://example.com/a.apk&manifest=https://example.com/a.json',
-    'frame-control://install?url=https://example.com/a.apk&url=https://example.com/b.apk',
-    'frame-control://install?manifest=garbage','not a URL','https://example.com/'+ 'x'.repeat(2050)]){
-    f.context.raw=raw;assert.throws(()=>f.run('installLinkRequest(raw)'));
-  }
-});
-test('link form queues a review only, with inline errors and a bounded waiting queue',()=>{
-  const f=installFixture(),submit=()=>f.el('installLinkForm').onsubmit({preventDefault(){}});
-  f.run('openInstallChooser()');f.el('installUrl').value='invalid';submit();
-  assert.equal(f.el('installChooser').open,true);assert.equal(f.el('installLinkError').hidden,false);assert.equal(f.context.wi.queue.length,0);assert.equal(f.calls.length,0);
-  f.el('installUrl').value='https://example.com/game.zip';submit();
-  assert.equal(f.el('installChooser').open,false);assert.equal(f.context.wi.queue.length,1);assert.deepEqual(f.calls,[['review']]);
-  f.context.wi.queue=Array(5).fill({kind:'url',target:'https://example.com/game.zip'});f.run('openInstallChooser()');submit();
-  assert.equal(f.el('installChooser').open,true);assert.equal(f.context.wi.queue.length,5);assert.match(f.el('installLinkError').textContent,/Finish or close/);
-});
-test('link review checks metadata but starts no download before the existing confirmation',async()=>{
-  const f=installFixture(),writes=[];
-  Object.assign(f.context,{log(){},gb:n=>String(n),api:async(path,body)=>{writes.push({path,body});return {id:'plan-1',name:'Game',host:'example.com',linkHost:'example.com',file:'game.zip',kindLabel:'PC game',size:100};}});
-  f.el('wiGo').focus=()=>{};f.el('wiDlg').addEventListener=()=>{};
-  const start=html.indexOf('const wi ='),end=html.indexOf('async function wiPoll(',start);f.run(html.slice(start,end));
-  f.run("wi.queue.push({kind:'url',target:'https://example.com/game.zip'})");await f.run('wiNext()');
-  assert.equal(writes.length,1);assert.equal(writes[0].path,'/api/webinstall/check');assert.equal(f.el('wiDlg').open,true);assert.equal(f.el('wiGo').disabled,false);
-  const cancel=html.indexOf('$("wiCancel").onclick = async () =>');f.run(html.slice(cancel,html.indexOf('// Escape',cancel)));
-  await f.el('wiCancel').onclick();assert.equal(f.el('wiDlg').open,false);assert.equal(writes.length,1);
-});
-test('catalog installs retain progress, failure retry and installed-app handoff',async()=>{
-  const f=workspaceFixture(),offer={source:'fdroid',id:'org.player',package:'org.player',name:'Player',downloadable:true,version_code:42},writes=[];
-  let success=false,refreshes=0,opened;
-  Object.assign(f.context,{sourceState:{jobs:new Map()},currentOffer:()=>offer,sourcePage:()=>'',openInstalledApp:pkg=>opened=pkg,
-    api:async(path,body)=>{writes.push({path,body});return {job:'job-1'};},loadAndroid:()=>refreshes++,
-    runJob:async(label,key,start,progress)=>{await start();progress({stage:'Installing',percent:75});assert.equal(f.el('detailProgress').value,75);return success?{package:'org.player'}:undefined;}});
-  const start=html.indexOf('function updateInstall()'),end=html.indexOf('async function openStoreApp(',start);f.run(html.slice(start,end));
-  const install=html.indexOf('async function installStoreApp()');f.run(html.slice(install,html.indexOf('async function changeSource(',install)));
-  await f.run('installStoreApp()');assert.equal(f.el('detailInstall').textContent,'Try again');assert.match(f.el('detailInstallNote').textContent,/couldn't finish/);
-  success=true;await f.run('installStoreApp()');assert.equal(f.el('detailInstall').textContent,'Open in Steam');assert.equal(refreshes,1);
-  assert.equal(writes.length,2);assert.deepEqual(JSON.parse(JSON.stringify(writes[0])),{path:'/api/sources/install',body:{source:'fdroid',id:'org.player',version_code:42}});
-  f.context.sourceState.jobs.clear();f.context.androidApps=[{package:'org.player'}];f.el('appDetail').showModal();f.run('updateInstall()');
-  assert.equal(f.el('detailInstall').textContent,'View installed app');await f.run('installStoreApp()');assert.equal(opened,'org.player');assert.equal(writes.length,2);assert.equal(f.el('appDetail').open,false);
-});
-test('Steam actions distinguish owned installation, installed play and non-owned store handoff',()=>{
-  const f=workspaceFixture();
-  f.context.gm.byId=new Map([[1,{installed:false}],[2,{installed:true}]]);
-  const start=html.indexOf('function gameButtons(');f.run(html.slice(start,html.indexOf('function moreGames(',start)));
-  assert.match(f.run("gameButtons(1,'Owned',false)"),/data-gm="install"/);
-  assert.match(f.run("gameButtons(2,'Installed',false)"),/data-launch="2"/);
-  for(const free of [false,true]){const output=f.run(`gameButtons(3,'Store',${free})`);assert.match(output,free?/Get on Steam/:/Buy on Steam/);assert.doesNotMatch(output,/data-gm="install"/);}
-  f.context.gm.dl={appid:1,percent:30};assert.match(f.run("gameButtons(1,'Owned',false)"),/Downloading 30%/);
-});
-test('Apps Games Tools Settings expose installed, browse, ownership and intentional legacy routes',()=>{
-  const f=workspaceFixture();
-  assert.deepEqual(f.links.map(a=>a.getAttribute()),['#apps','#games','#tools','#settings']);
-  f.navigate('');assert.equal(f.activePage,'apps');assert.equal(f.el('androidLibrary').hidden,false);assert.equal(f.el('appStore').hidden,true);
-  f.navigate('#games');assert.equal(f.activePage,'games');assert.equal(f.el('getgames').hidden,true);assert.equal(f.el('library').hidden,false);assert.equal(f.el('sideloaded').hidden,false);
-  f.navigate('#getgames');assert.equal(f.el('getgames').hidden,false);assert.equal(f.el('library').hidden,true);assert.equal(f.context.gm.src,'owned');
-  f.navigate('#steamStore');assert.equal(f.context.gm.src,'store');assert.equal(f.el('getgames').hidden,false);
-  f.navigate('#appStore');assert.equal(f.activePage,'apps');assert.equal(f.el('appStore').hidden,false);assert.equal(f.el('androidLibrary').hidden,true);
-  f.navigate('#linuxApps');assert.equal(f.activePage,'apps');assert.equal(f.el('appsLinux').hidden,false);
-  f.navigate('#androidLibrary');assert.equal(f.el('appsLinux').hidden,true);assert.equal(f.el('androidLibrary').hidden,false);
-  f.navigate('#display');assert.equal(f.activePage,'settings');assert.equal(f.el('androidSettings').hidden,false);assert.equal(f.el('settingsDirectory').hidden,true);
-  f.navigate('#settings');assert.equal(f.el('settingsDirectory').hidden,false);assert.equal(f.el('settingsWorkspace').hidden,true);
-  for(const [route,page,primary] of [['#devices','devices','settings'],['#control','control','settings'],['#shots','capture','tools'],['#view','capture','tools'],['#pad','tools','tools'],['#comfort','tools','tools'],['#library','games','games'],['#discover','apps','apps'],['#privacy','settings','settings']]){
-    f.navigate(route);assert.equal(f.activePage,page,route);assert.equal(f.run('primaryPage(page)'),primary,route);
-  }
-});
-test('app views and game scopes restore separate scroll positions, queries and filters',()=>{
-  const f=workspaceFixture();f.navigate('#appStore');f.el('sourceQ').value='video';f.scroll(480);
-  f.run("selectApps('installed')");f.el('libQ').value='player';f.scroll(220);
-  f.navigate('#games');f.scroll(160);f.navigate('#apps');assert.equal(f.context.window.scrollY,220);
-  f.run("selectApps('browse')");assert.equal(f.context.window.scrollY,480);assert.equal(f.el('sourceQ').value,'video');assert.equal(f.el('libQ').value,'player');
-  f.navigate('#games');assert.equal(f.context.window.scrollY,160);
-  f.run("selectLibrary('steam')");f.scroll(600);f.run("selectLibrary('sideloaded')");f.scroll(80);f.run("selectLibrary('steam')");assert.equal(f.context.window.scrollY,600);
-  f.context.location.hash='#apps';f.scroll(0);f.run('showPage()');f.navigate('#games');assert.equal(f.context.window.scrollY,600);
-});
-test('Android browse opens Apps Browse after visiting the Steam store',()=>{
-  const f=workspaceFixture();f.navigate('#steamStore');f.navigate('#androidLibrary');
-  const start=html.indexOf('function showAndroidTab(tab)'),end=html.indexOf("document.querySelectorAll('[data-store-tab]')",start);
-  f.run(html.slice(start,end));f.run("showAndroidTab('browse')");f.run('showPage()');
-  assert.equal(f.activePage,'apps');assert.equal(f.el('appStore').hidden,false);
-});
-test('empty installed library opens Browse even when its route is already in the address bar',()=>{
-  const f=workspaceFixture();let click;
-  f.context.libState={q:'',filter:'all'};f.el('andApps').addEventListener=(name,fn)=>click=fn;
-  const helper=html.indexOf('function showAndroidTab(tab)');
-  f.run(html.slice(helper,html.indexOf("document.querySelectorAll('[data-store-tab]')",helper)));
-  const start=html.indexOf('function renderLibrary()');
-  f.run(html.slice(start,html.indexOf('document.addEventListener("click",',start)));
-  f.navigate('#appStore');f.run("selectApps('installed');renderLibrary()");
-  assert.match(f.el('andApps').innerHTML,/data-store-go="browse"/);assert.equal(f.el('appStore').hidden,true);
-  click({target:{closest:()=>({dataset:{storeGo:'browse'}})}});
-  assert.equal(f.context.location.hash,'#appStore');assert.equal(f.el('appStore').hidden,false);assert.equal(f.el('appsInstalled').hidden,true);
-});
-test('owned scope excludes installed games and keeps unknown compatibility visible',()=>{
-  const f=workspaceFixture(),gm=f.context.gm;
-  Object.assign(gm,{owned:[{id:1,installed:true,name:'Installed',frame:3,sort:'installed'},{id:2,installed:false,name:'Owned unknown',frame:0,sort:'owned',lastPlayed:0}],q:'',filters:{owned:new Set(['0','1','2','3'])},shown:0});
-  f.context.moreGames=()=>{};
-  const start=html.indexOf('function filterGames('),end=html.indexOf('function price(',start);
-  f.run(html.slice(start,end));f.run('filterGames()');
-  assert.deepEqual(Array.from(gm.results,g=>g.id),[2]);
-});
-test('installed load succeeds while optional catalog is unresolved, and errors keep local retry',async()=>{
-  const f=workspaceFixture(),pending=deferred();
-  let result={apps:[{package:'org.example.player',label:'Player',running:false}]},fail=false;
-  f.context.api=path=>path==='/api/android'?fail?Promise.reject(Error('Temporary network failure')):Promise.resolve(result):pending.promise;
-  f.context.renderLibrary=()=>f.el('andApps').innerHTML='installed';
-  f.run('let androidSeq=0; const androidPending=new Set(); let installedPackage=null;');
-  const start=html.indexOf('async function loadAndroid() {'),end=html.indexOf("$('androidRetry').onclick",start);
-  f.run(html.slice(start,end));await f.run('loadAndroid()');
-  assert.equal(f.el('andApps').innerHTML,'installed');assert.equal(f.el('androidLoadError').hidden,true);
-  fail=true;await f.run('loadAndroid()');assert.equal(f.el('andApps').innerHTML,'installed');assert.equal(f.el('androidLoadError').hidden,false);
-  assert.match(f.el('androidLoadMessage').textContent,/Temporary network failure/);
-  fail=false;await f.run('loadAndroid()');assert.equal(f.el('androidLoadError').hidden,true);
-  assert.ok(html.includes('loadAndroid();\n\n// ---- Android display'),'startup must not wait for catalog completion');
-});
-test('older installed responses cannot replace a newer read',async()=>{
-  const f=workspaceFixture(),old=deferred(),next=deferred();let calls=0;
-  f.context.api=()=>++calls===1?old.promise:next.promise;f.context.renderLibrary=()=>{};
-  f.run('let androidSeq=0;const androidPending=new Set();let installedPackage=null;');
-  const start=html.indexOf('async function loadAndroid() {'),end=html.indexOf("$('androidRetry').onclick",start);
-  f.run(html.slice(start,end));const a=f.run('loadAndroid()'),b=f.run('loadAndroid()');
-  next.resolve({apps:[{package:'new'}]});await b;old.resolve({apps:[{package:'old'}]});await a;
-  assert.equal(f.context.androidApps[0].package,'new');
-});
-test('Android Open dispatch is deduplicated while pending and returns to an enabled row',async()=>{
-  const f=workspaceFixture(),request=deferred(),writes=[];
-  Object.assign(f.context,{devGen:1,installing:new Set(),toast(){},act:async(label,work)=>work(),
-    api:(path,body)=>{writes.push({path,body});return request.promise;},loadAndroid:async()=>{},renderLibrary(){},cat:{apps:null},loadReports(){}});
-  f.run('const androidPending=new Set();let installedPackage=null;');
-  const start=html.indexOf('document.body.addEventListener("click", async e => {',html.indexOf('$("catChips").onclick'));
-  const end=html.indexOf('loadAndroid();\n\n// ---- Android display',start);
-  f.run(html.slice(start,end));
-  const button={dataset:{and:'launch',pkg:'org.example.player',name:'Player'},disabled:false,textContent:'Open'};
-  const event={target:{closest:()=>button}};
-  const a=f.listeners['body-click'](event);await f.listeners['body-click'](event);
-  assert.equal(button.disabled,true);assert.equal(button.textContent,'Wait…');assert.equal(button.ariaBusy,'true');assert.equal(writes.length,1);
-  assert.deepEqual(JSON.parse(JSON.stringify(writes[0])),{path:'/api/android',body:{action:'launch',package:'org.example.player'}});
-  request.resolve({message:'Opened'});await a;assert.equal(button.disabled,false);assert.equal(button.textContent,'Open');assert.equal(button.ariaBusy,'false');
-});
-test('entering Apps Installed refreshes data without clearing cached rows',()=>{
-  const f=workspaceFixture();f.el('andApps').innerHTML='cached installed apps';f.navigate('#games');f.navigate('#apps');
-  assert.equal(f.calls.filter(c=>c[0]==='android').length,1);
-  f.run("selectApps('installed')");assert.equal(f.calls.filter(c=>c[0]==='android').length,2);
-  f.navigate('#settings');f.navigate('#apps');assert.equal(f.calls.filter(c=>c[0]==='android').length,3);
-  assert.equal(f.el('andApps').innerHTML,'cached installed apps');
-});
-test('actions from detail synchronize existing rows and stay pending through the follow-up read',async()=>{
-  for(const action of ['launch','stop']) {
-    const f=workspaceFixture(),request=deferred(),refresh=deferred();let writes=0,renders=0;
-    const makeButton=pkg=>({dataset:{and:action,pkg,name:'Player'},disabled:false,textContent:action==='stop'?'Stop':'Open'});
-    const detail=makeButton('org.example.player'),row=makeButton('org.example.player'),other=makeButton('org.other');
-    const originalQuery=f.context.document.querySelectorAll;
-    f.context.document.querySelectorAll=selector=>selector==='[data-and="launch"], [data-and="stop"]'?[row,detail,other]:originalQuery(selector);
-    Object.assign(f.context,{devGen:1,installing:new Set(),log(){},toast(){},api:()=>{writes++;return request.promise;},
-      loadAndroid:()=>refresh.promise,renderLibrary(){renders++;row.disabled=false;row.textContent=action==='stop'?'Stop':'Open';row.ariaBusy='false';},cat:{apps:null},loadReports(){}});
-    f.run('const androidPending=new Set();let installedPackage=null;');
-    f.run(html.slice(html.indexOf('async function act('),html.indexOf('\nfunction setConn(')));
-    const start=html.indexOf('document.body.addEventListener("click", async e => {',html.indexOf('$("catChips").onclick'));
-    f.run(html.slice(start,html.indexOf('loadAndroid();\n\n// ---- Android display',start)));
-    f.el('installedDetail').showModal();const pending=f.listeners['body-click']({target:{closest:()=>detail}});f.el('installedDetail').close();
-    for(const button of [row,detail]){assert.equal(button.disabled,true);assert.equal(button.textContent,'Wait…');assert.equal(button.ariaBusy,'true');}
-    assert.equal(other.disabled,false);await f.listeners['body-click']({target:{closest:()=>row}});assert.equal(writes,1);
-    request.resolve({message:'Done'});await new Promise(resolve=>setImmediate(resolve));
-    assert.equal(row.disabled,true);assert.equal(detail.disabled,true);assert.equal(renders,0,'stay pending while refreshed app state is unresolved');
-    refresh.resolve();await pending;assert.equal(renders,1);assert.equal(row.disabled,false);assert.equal(detail.disabled,false);assert.equal(f.run('androidPending.size'),0);
-  }
-});
-test('regenerated Android rows and details keep the compact accessible pending state',()=>{
-  const f=workspaceFixture(),app={package:'org.example.player',label:'Player',running:false};
-  Object.assign(f.context,{androidApps:[app],storeIcon:()=>'<span>icon</span>'});
-  f.run("const androidPending=new Set(['org.example.player']);let installedPackage=null;");
-  const start=html.indexOf('function libCard(a)'),end=html.indexOf('function renderLibrary()',start);f.run(html.slice(start,end));
-  for(const running of [false,true]) {
-    app.running=running;const row=f.run('libCard(androidApps[0])');f.run("openInstalledApp('org.example.player')");
-    assert.match(row,/disabled aria-busy="true">Wait…<\/button>/);
-    assert.match(f.el('installedDetailBody').innerHTML,/disabled aria-busy="true">Wait…<\/button>/);
-  }
-  f.run('androidPending.clear()');const row=f.run('libCard(androidApps[0])');assert.doesNotMatch(row,/aria-busy="true"/);assert.match(row,/>Stop<\/button>/);
-});
-test('explicit Capture section links take priority over saved destination scroll',()=>{
-  const f=workspaceFixture();f.navigate('#capture');f.scroll(700);f.calls.length=0;
-  f.navigate('#shots');assert.ok(f.calls.some(c=>c[0]==='section'&&c[1]==='shots'));
-  f.calls.length=0;f.navigate('#view');assert.ok(f.calls.some(c=>c[0]==='section'&&c[1]==='view'));
-  f.calls.length=0;f.navigate('#view');assert.ok(f.calls.some(c=>c[0]==='section'&&c[1]==='view'));
-});
-test('viewer keyboard shortcuts act only in the Capture workspace',()=>{
-  const f=workspaceFixture(),events=[];let handler;
-  f.context.document.activeElement={tagName:'BODY'};
-  f.context.document.addEventListener=(name,callback)=>handler=callback;
-  Object.assign(f.context,{ctrl:{on:false},zoom:1,setZoom:n=>events.push(['zoom',n])});
-  f.el('ctrlBtn').click=()=>events.push(['control']);f.el('fullBtn').click=()=>events.push(['fullscreen']);
-  const start=html.indexOf('document.addEventListener("keydown", e => {',html.indexOf('$("canvas").addEventListener("pointerdown"'));
-  const end=html.indexOf('\n});',start)+4;f.run(html.slice(start,end));
-  f.navigate('#capture');handler({key:'+'});handler({key:'c'});handler({key:'f'});assert.equal(events.length,3);
-  f.navigate('#home');handler({key:'+'});handler({key:'c'});handler({key:'f'});assert.equal(events.length,3);
-});
-test('late Mac streaming responses cannot reveal a different tool panel',async()=>{
-  for(const rejects of [false,true]) {
-    const f=workspaceFixture(),response=deferred();
-    Object.assign(f.context,{api:()=>response.promise,clearTimeout(){},setTimeout(){},failed(){}});
-    f.run('let mvSeq=0,mvTimer=0;');
-    const start=html.indexOf('async function loadMacView(restart)'),end=html.indexOf('$("mvRefresh").onclick',start);
-    f.run(html.slice(start,end));f.context.location.hash='#macview';const pending=f.run('loadMacView()');
-    f.navigate('#transfer');assert.equal(f.el('macview').hidden,true);
-    rejects?response.reject(Error('Network failed')):response.resolve({available:true,streams:[],displays:[],windows:[]});
-    await pending;assert.equal(f.el('macview').hidden,true);assert.equal(f.el('transfer').hidden,false);
-  }
-});
-test('Home task count includes the current Steam download',()=>{
-  const f=workspaceFixture();Object.assign(f.context,{state:{hostname:'Frame',battery:{percent:80}},stateRead:{valid:true},online:true});
-  f.context.gm.dl={appid:1,percent:42};f.run('renderHome()');
-  assert.equal(f.el('homeJobs').textContent,'1 task in progress');assert.match(f.el('homeDownload').textContent,/42%/);
-});
-test('a late screenshot read cannot replace newer navigation or clear a newer viewer request',async()=>{
-  const f=workspaceFixture(),old=deferred(),newer=deferred();let reads=0;
-  Object.assign(f.context,{shotBlob:()=>++reads===1?old.promise:newer.promise,URL:{createObjectURL:()=> 'blob:shot',revokeObjectURL(){}},
-    Image:class{set src(value){this.onload();}},draw(){},shotApp:()=> 'Game',toast(){},desk:{shown:null}});
-  const start=html.indexOf('async function openShot(s)'),end=html.indexOf('async function saveShots(',start);
-  f.run(html.slice(start,end));f.navigate('#capture');const pending=f.run("openShot({id:1,file:'one.png',time:1})");
-  assert.equal(f.el('viewer').classList.contains('busy'),true);
-  f.navigate('#library');f.scroll(240);assert.equal(f.el('viewer').classList.contains('busy'),false);
-  old.resolve({});await pending;assert.equal(f.activePage,'games');assert.equal(f.context.location.hash,'#library');assert.equal(f.context.window.scrollY,240);
-  f.navigate('#capture');const first=f.run("openShot({id:2,file:'two.png',time:1})");
-  f.navigate('#home');f.navigate('#capture');f.run('viewGen++');f.el('viewer').classList.toggle('busy',true);
-  newer.resolve({});await first;assert.equal(f.activePage,'capture');assert.equal(f.context.location.hash,'#capture');assert.equal(f.el('viewer').classList.contains('busy'),true);
-});
-test('Steam discovery preserves an unsubmitted query across a source change',()=>{
-  const f=workspaceFixture();Object.assign(f.context.gm,{src:'store',q:'owned query',storeDraft:'',storeQ:'submitted query'});
-  f.context.renderChips=()=>{};f.context.filterGames=()=>{};
-  const start=html.indexOf('function setGameSource(src)'),end=html.indexOf('$("gmSrc").onclick',start);
-  f.run(html.slice(start,end));f.el('gmQ').value='unsubmitted search';f.run("setGameSource('owned')");
-  assert.equal(f.el('gmQ').value,'owned query');f.run("setGameSource('store')");assert.equal(f.el('gmQ').value,'unsubmitted search');
-});
-test('expanded owned and store results survive source and destination returns',async()=>{
-  const f=workspaceFixture(),gm=f.context.gm;
-  const games=Array.from({length:120},(_,i)=>({id:i+1,name:'Game '+String(i+1).padStart(3,'0'),sort:String(i).padStart(3,'0'),frame:3,installed:false,lastPlayed:0}));
-  Object.assign(gm,{owned:games,store:games,storeQ:'game',storeDraft:'game',country:'US',q:'',results:[],filters:{owned:new Set(['3']),store:new Set(['3'])},seq:0});
-  Object.assign(f.context,{FLABEL:{3:'Verified'},FCLASS:{3:'verified'},CDN:'https://example.invalid',renderChips(){}});
-  f.el('gmGrid').insertAdjacentHTML=(position,s)=>f.el('gmGrid').innerHTML+=s;
-  const start=html.indexOf('function filterGames('),end=html.indexOf('$("gmSrc").onclick',start);
-  f.run(html.slice(start,end));
-  f.navigate('#getgames');f.run('filterGames();moreGames()');f.scroll(7000);
-  assert.equal(gm.shown,96);assert.match(f.el('gmGrid').innerHTML,/Game 096/);
-  f.navigate('#steamStore');f.run('moreGames()');f.scroll(6500);
-  assert.equal(gm.shown,96);f.navigate('#getgames');assert.equal(gm.shown,96);assert.match(f.el('gmGrid').innerHTML,/Game 096/);assert.equal(f.context.window.scrollY,7000);
-  f.navigate('#steamStore');assert.equal(gm.shown,96);assert.match(f.el('gmGrid').innerHTML,/Game 096/);assert.equal(f.context.window.scrollY,6500);
-  f.run('filterGames()');assert.equal(gm.shown,48,'a deliberate filter change resets expansion');
-  const response=deferred();f.context.api=()=>response.promise;f.el('gmQ').value='new search';const search=f.run('searchStore()');
-  f.navigate('#getgames');const ownedMarkup=f.el('gmGrid').innerHTML;
-  response.resolve({results:games.slice(0,60)});await search;
-  assert.equal(f.el('gmGrid').innerHTML,ownedMarkup,'a late store response leaves current owned results intact');
-  f.navigate('#steamStore');assert.equal(gm.shown,48);assert.equal(gm.storeQ,'new search');
-});

tests/workspace_fixture.cjs

@@ -1,39 +0,0 @@
-// Execute the production workspace code with only browser/transport boundaries replaced.
-const fs = require('node:fs');
-const vm = require('node:vm');
-const html = fs.readFileSync(require.resolve('../ui/index.html'), 'utf8');
-function workspaceFixture() {
-  const elements = new Map(), listeners = {}, calls = [];
-  const classes = () => { const set=new Set(); return {add(k){set.add(k);},toggle(k,on){if(on===undefined)on=!set.has(k);on?set.add(k):set.delete(k);return on;},remove(k){set.delete(k);},contains:k=>set.has(k)}; };
-  function el(id) {
-    if (!elements.has(id)) elements.set(id,{id,hidden:false,disabled:false,open:false,innerHTML:'',textContent:'',value:'',dataset:{},classList:classes(),
-      setAttribute(k,v){this[k]=v;},removeAttribute(k){delete this[k];},querySelectorAll(){return [];},
-      append(node){node.parent=this;},prepend(node){node.parent=this;},scrollIntoView(){calls.push(['section',id]);},
-      showModal(){this.open=true;},close(){this.open=false;}});
-    return elements.get(id);
-  }
-  const pages=[...html.matchAll(/data-page="([^"]+)"/g)].map((m,i)=>Object.assign(el('page-'+i),{dataset:{page:m[1]}}));
-  const nav=html.match(/<nav id="nav"[^>]*>([\s\S]*?)<\/nav>/)[1];
-  const links=[...nav.matchAll(/<a href="([^"]+)"/g)].map((m,i)=>Object.assign(el('nav-'+i),{getAttribute:()=>m[1]}));
-  const controls={};
-  for (const [attr,values] of [['scope',['installed','owned','store']],['library-source',['all','steam','sideloaded']],['app-view',['installed','browse','linux']]]) {
-    const prop=attr.replace(/-([a-z])/g,(_,c)=>c.toUpperCase());
-    controls[`[data-${attr}]`]=values.map(v=>Object.assign(el(attr+'-'+v),{dataset:{[prop]:v}}));
-  }
-  const win={scrollY:0,scrollTo(a,b){this.scrollY=typeof a==='object'?a.top:b;calls.push(['scroll',this.scrollY]);},addEventListener(k,fn){listeners[k]=fn;}};
-  let hash='#apps';const location={get hash(){return hash;},set hash(value){hash=value&&!String(value).startsWith('#')?'#'+value:String(value);}};
-  const context={URL,document:{querySelectorAll:s=>s==='.page'?pages:s==='#nav a'?links:controls[s]||[],title:'',body:{addEventListener(k,fn){listeners['body-'+k]=fn;}}},
-    window:win,location,requestAnimationFrame:fn=>fn(),$:el,live:false,toggleLive(on){this.live=on;calls.push(['live',on]);},
-    loadAndroid(){calls.push(['android']);},
-    loadMacView(){calls.push(['macview']);},loadPanelSwitcher(){calls.push(['panels']);},loadDisplays(){calls.push(['displays']);},
-    gm:{src:'owned',dl:null,byId:new Map(),shown:0,shownBySource:{owned:0,store:0}},setGameSource(src){context.gm.src=src;},state:null,stateRead:{valid:false},online:null,devGen:0,androidApps:[],jobsRunning:0,viewGen:0,
-    esc:s=>String(s??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]))};
-  vm.createContext(context);
-  const start=html.indexOf('const PAGES ='),end=html.indexOf('window.addEventListener("hashchange", showPage);',start);
-  vm.runInContext(html.slice(start,end),context);
-  return {html,context,elements,el,calls,pages,links,listeners,run:code=>vm.runInContext(code,context),
-    navigate(hash){context.location.hash=hash;vm.runInContext('showPage()',context);},
-    get activePage(){return pages.find(p=>p.classList.contains('on'))?.dataset.page;},
-    scroll(y){win.scrollY=y;listeners.scroll();}};
-}
-module.exports={workspaceFixture,html};

ui/apk_sources/__init__.py

@@ -45,6 +45,10 @@ class SourceError(Exception):
     """User-readable failure from a source (network, format, verification)."""
 
 
+class SourceAuthError(SourceError):
+    """The server refused our login (HTTP 401, or 403 when a login was sent)."""
+
+
 class SourceLimited(SourceError):
     """The source's host asked us to slow down; retry_after is in seconds."""
 

ui/apk_sources/_categories.py

@@ -1,116 +0,0 @@
-"""Store categories that make sense on a Steam Frame, and which apps only make sense on a phone.
-
-Sources describe apps in their own terms (F-Droid's categories, a VR flag). The store groups
-them for a headset instead: VR first, then games and the flat apps worth having in a panel
-(video, reading, making things). Apps built around a phone's hardware or system (calls and
-SMS, launchers, widgets, keyboards, fitness, root tools) are marked phone_only; the store
-hides them unless asked, since Lepton can run them but they do nothing useful on the Frame.
-"""
-import re
-
-# (id, label), in the order the store shows them.
-CATEGORIES = (
-    ('vr', 'VR'),
-    ('games', 'Games'),
-    ('emulators', 'Emulators'),
-    ('watch', 'Watch & listen'),
-    ('read', 'Read & learn'),
-    ('create', 'Create'),
-    ('work', 'Work'),
-    ('web', 'Web & chat'),
-    ('tools', 'Tools'),
-)
-IDS = {c for c, _ in CATEGORIES}
-
-# F-Droid's category names -> a store category; None = only useful on a phone.
-# F-Droid has broad categories ('Multimedia') and, since 2025, finer ones ('Podcast'); an app
-# usually has both. A finer one decides, since 'Social Network' + 'Multimedia' is a chat app.
-BROAD = {
-    'Games': 'games', 'Multimedia': 'watch', 'Reading': 'read', 'Science & Education': 'read',
-    'Graphics': 'create', 'Writing': 'work', 'Money': 'work', 'Time': 'work', 'Internet': 'web',
-    'Development': 'tools', 'Security': 'tools',
-    'Office': 'work', 'Food': 'read',  # IzzyOnDroid's own names
-    'Connectivity': None, 'Navigation': None, 'Phone & SMS': None, 'Sports & Health': None,
-    'System': None, 'Theming': None,
-}
-FINE = {
-    'emulators': ('Emulator',),
-    'games': ('Action Game', 'Board Game', 'Card Game', 'Casual Game', 'Dice', 'Educational Game', 'Party Game',
-              'Platformer Game', 'Puzzle Game', 'Role-Playing Game', 'Shooter Game', 'Sport Game',
-              'Strategy Game', 'Visual Novel', 'Word Game'),
-    'watch': ('Local Media Player', 'Online Media Player', 'Podcast', 'Radio', 'Cast', 'Lyrics', 'Gallery',
-              'Ambient Sound'),
-    'read': ('Ebook Reader', 'Audiobook', 'News', 'Translation & Dictionary', 'Religion', 'Recipe Manager'),
-    'create': ('Draw', 'Music Practice Tool', 'Recorder'),
-    'web': ('Browser', 'Email', 'Messaging', 'Social Network', 'Forum', 'Voice & Video Chat', 'AI Chat',
-            'Bookmark'),
-    'work': ('Note', 'Task', 'Text Editor', 'Calendar & Agenda', 'Calculator', 'Unit Convertor',
-             'Finance Manager', 'Time Tracker', 'Schedule', 'Inventory'),
-    'tools': ('Code & Forge', 'Password & 2FA', 'File Manager', 'File Encryption & Vault', 'Text Encryption',
-              'Remote Access', 'Remote Controller', 'Cloud Storage & File Sync', 'Network Analyzer',
-              'File Transfer', 'Text to Speech', 'Speech Recognizer', 'Download', 'Game Helper', 'Weather'),
-}
-FINE_TARGET = {name: target for target, names in FINE.items() for name in names}
-# Only make sense as part of a phone's own system: any one of these makes an app phone-only.
-PHONE_SYSTEM = {
-    'Launcher', 'Keyboard & IME', 'Wallpaper', 'Icon Pack', 'Flashlight', 'Battery', 'Notification', 'Volume',
-    'Theming', 'Emergency Action', 'Xposed', 'Automation',
-}
-# Phone things that are often a side of a useful app (Thunderbird is in Contact, FluffyChat in
-# Phone & SMS, Nextcloud in Connectivity, a file manager in System): phone-only unless a useful
-# category says otherwise. A finer one when the source has them; a broad one when it only has
-# broad ones (IzzyOnDroid often does).
-PHONE_SIDE = {
-    'Phone & SMS', 'Push', 'Contact', 'Camera', 'OCR', 'Location Tracker & Sharer', 'Navigation',
-    'Public Transport', 'Workout', 'Diet', 'Medication', 'Health Manager', 'Alarm Clock', 'Pass Wallet',
-    'Wallet', 'VPN & Proxy', 'DNS & Hosts', 'Firewall', 'App Manager', 'App Store & Updater', 'System',
-    'Connectivity',
-}
-PHONE_CATEGORIES = PHONE_SYSTEM | PHONE_SIDE
-# Fine categories that aren't useful on a headset either, but don't make an app phone-only on their own.
-PHONE_LEANING = {'Clock', 'Timer', 'Stopwatch', 'Habit Tracker', 'Shopping List', 'Market & Price',
-                 'Meditation', 'Mental Health', 'Sports & Health'}
-# When an app has several, the one that best describes it on a headset wins.
-PRIORITY = ('emulators', 'games', 'watch', 'read', 'create', 'web', 'work', 'tools')
-
-EMULATOR = re.compile(r'\bemulat(or|ion|es)\b|\b(retroarch|ppsspp|dolphin|dosbox|scummvm|mame|mupen64|melonds|citra|duckstation|flycast)\b', re.I)
-# What an app is, from its name: these are phone parts, whatever the categories say.
-PHONE_NAME = re.compile(r'\b(launcher|home ?screen|widgets?|keyboard|wallpapers?|ringtones?|dialer|sms|mms|'
-                        r'caller id|lock ?screen|status ?bar|step counter|pedometer|5g|4g|lte|hotspot|tethering|'
-                        r'magisk|xposed|battery)\b|\[root\]', re.I)
-# "Doesn't need root" isn't a root tool; taken out before HARDWARE looks for "needs root".
-NOT_ROOT = re.compile(r"\b(no|non|without|not|never|doesn.?t (need|require)|does not (need|require)|don.?t (need|require))[- ]+(the )?root(ed|ing)?\b"
-                      r"|\broot(less|[- ]free| (is )?not (required|needed))\b", re.I)
-# Needs hardware or a device the Frame doesn't have, from the name or summary.
-HARDWARE = re.compile(r'\b(infra-?red|ir (blaster|remote|transmitter)|wear ?os|smart ?watch(es)?|nfc|sim card|'
-                      r'(requires?|needs?|for) (a )?root(ed)?( (access|device|phone))?)\b', re.I)
-
-
-def classify(entry):
-    """{'category': one of IDS or None, 'phone_only': bool} for a store entry."""
-    if entry.get('vr') is True:
-        return {'category': 'vr', 'phone_only': False}
-    name, summary = str(entry.get('name') or ''), str(entry.get('summary') or '')
-    names = [c for c in entry.get('categories') or () if isinstance(c, str)]
-    fine = {FINE_TARGET[c] for c in names if c in FINE_TARGET}
-    broad = {BROAD[c] for c in names if BROAD.get(c)}
-    category = next((c for c in PRIORITY if c in fine), None) or next((c for c in PRIORITY if c in broad), None)
-    if category is None and EMULATOR.search(name + ' ' + summary):
-        category = 'emulators'
-    only_broad = all(c in BROAD for c in names)  # this source has no finer categories for it
-    useful = fine or (broad if only_broad else set())
-    phone = any(c in PHONE_SYSTEM for c in names) or (not useful and any(c in PHONE_SIDE for c in names))
-    if names and category is None and all(c in PHONE_CATEGORIES or c in PHONE_LEANING or BROAD.get(c, 1) is None
-                                          for c in names):
-        phone = True
-    if category not in ('games', 'emulators', 'watch', 'read', 'create'):
-        phone = phone or bool(PHONE_NAME.search(name)) or bool(HARDWARE.search(NOT_ROOT.sub(' ', name + ' ' + summary)))
-    return {'category': category, 'phone_only': phone}
-
-
-def matches(entry, category=None, phone=False):
-    """Whether a classified entry belongs in a browse for this category ('' or None = any). A search
-    shows phone-only apps too (search passes phone=True), so a wrong guess never hides an app."""
-    if entry.get('phone_only') and not phone:
-        return False
-    return not category or entry.get('category') == category

ui/apk_sources/_credentials.py

@@ -0,0 +1,270 @@
+"""Logins for sources behind one: HTTP basic auth and access tokens.
+
+Saved apart from the source settings, in frame_host.data_dir('source-credentials.json')
+(mode 0600), keyed by a caller-chosen name: an F-Droid source id, 'github'. Each
+credential belongs to one exact origin (https, host, port) and is only ever sent
+to a request for that origin: Handler adds it to each request, redirects
+included, and removes any Authorization header from every other request.
+
+Scoped use (for_url, and Handler(..., scoped=True), which F-Droid repositories and
+artwork use) is stricter: the URL must also be under the credential's scope by whole
+path segments, with no dot segments, encoded slashes or ';' a server could normalise
+into a path outside it. Origin-only matching suits a host-wide token (GitHub's API).
+
+Secrets leave this module only as an Authorization header value. Credential's
+repr hides them, and nothing here puts them in an exception message.
+
+Each change is a read-modify-write under an inter-process lock (the CLI and the
+app may both save), so one process can't undo another's save or removal.
+"""
+import base64
+import contextlib
+import errno
+import json
+import os
+import tempfile
+import threading
+import urllib.parse
+import urllib.request
+
+import frame_host
+
+_lock = threading.RLock()
+MAX = 4096  # longest username, password or token accepted
+
+
+def _path():
+    return frame_host.data_dir('source-credentials.json')
+
+
+@contextlib.contextmanager
+def _changing():
+    """This thread, then this process, holds the credentials file for a read-modify-write."""
+    path = _path().with_name('source-credentials.lock')
+    with _lock:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(str(path), 'a+b') as f:
+            if os.name == 'nt':
+                import msvcrt
+                while True:
+                    try:
+                        f.seek(0)
+                        msvcrt.locking(f.fileno(), msvcrt.LK_LOCK, 1)
+                        break
+                    except OSError as e:  # LK_LOCK gives up after ~10 s of contention; keep waiting
+                        if e.errno not in (errno.EACCES, errno.EDEADLK):
+                            raise
+                try:
+                    yield
+                finally:
+                    f.seek(0)
+                    msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+                try:
+                    yield
+                finally:
+                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
+def path_segments(path):
+    """A URL path's decoded segments, or None if a server might read it as another path:
+    '.' or '..' (plain or percent-encoded), encoded '/' or '\\', '%' left after decoding
+    (double encoding), or ';' path parameters."""
+    if ';' in path or '\\' in path:
+        return None
+    parts = [urllib.parse.unquote(part) for part in path.split('/')]
+    if any(part in ('.', '..') or '/' in part or '\\' in part or '%' in part or ';' in part for part in parts):
+        return None
+    return parts
+
+
+def in_scope(credential, url):
+    """True if url is on credential's origin and under its scope by whole, plain path segments."""
+    if credential is None or not credential.matches(url):
+        return False
+    try:
+        path, scope = urllib.parse.urlsplit(url).path, urllib.parse.urlsplit(credential.scope).path
+    except ValueError:
+        return False
+    parts, base = path_segments(path), path_segments(scope)
+    if parts is None or base is None:
+        return False
+    if base and base[-1] == '':
+        base = base[:-1]  # 'https://h/repo/' covers '/repo/x', not '/repository'
+    return parts[:len(base)] == base
+
+
+def origin(url):
+    """'https://host:port' for an https URL; ValueError for anything else."""
+    p = urllib.parse.urlsplit(url)
+    port = p.port  # raises ValueError on a bad port
+    if p.scheme.lower() != 'https' or not p.hostname:
+        raise ValueError('credentials are only sent over HTTPS')
+    host = p.hostname.lower()
+    return 'https://%s:%d' % ('[%s]' % host if ':' in host else host, port or 443)
+
+
+def _check(value, what, allow_empty=False):
+    if not isinstance(value, str) or (not value and not allow_empty) or len(value) > MAX:
+        raise ValueError('invalid ' + what)
+    if any(ord(c) < 32 or ord(c) == 127 for c in value):
+        raise ValueError(what + ' must not contain control characters')
+    return value
+
+
+class Credential:
+    """A username and password (basic) or a token (bearer) for one origin.
+
+    scope is the URL prefix it belongs under: in_scope checks it (by path segments),
+    matches() checks only the origin."""
+    __slots__ = ('origin', 'scope', 'username', '_secret')
+
+    def __init__(self, scope, secret, username=None):
+        self.origin = origin(scope)
+        self.scope = scope
+        if username is not None:
+            _check(username, 'username')
+            if ':' in username:
+                raise ValueError('username must not contain ":"')
+            _check(secret, 'password', allow_empty=True)
+        else:
+            _check(secret, 'token')
+            if any(c.isspace() for c in secret):
+                raise ValueError('token must not contain spaces')
+        self.username, self._secret = username, secret
+
+    @property
+    def kind(self):
+        return 'bearer' if self.username is None else 'basic'
+
+    def header(self):
+        if self.username is None:
+            return 'Bearer ' + self._secret
+        return 'Basic ' + base64.b64encode((self.username + ':' + self._secret).encode('utf-8')).decode('ascii')
+
+    def matches(self, url):
+        """True only for a URL on exactly this credential's origin."""
+        try:
+            return origin(url) == self.origin
+        except ValueError:
+            return False
+
+    def same(self, other):
+        return isinstance(other, Credential) and (self.origin, self.username, self._secret) == (
+            other.origin, other.username, other._secret)
+
+    def __repr__(self):
+        return '<Credential %s for %s>' % (self.kind, self.origin)
+
+    def _json(self):
+        return {'scope': self.scope, 'username': self.username, 'secret': self._secret}
+
+
+def basic(scope, username, password):
+    """Basic auth for scope's origin, e.g. basic('https://example.org/fdroid/repo/', 'me', 'pw')."""
+    return Credential(scope, password, username)
+
+
+def bearer(scope, token):
+    """An access token for scope's origin, sent as 'Authorization: Bearer <token>'."""
+    return Credential(scope, token)
+
+
+def _read():
+    try:
+        with open(str(_path()), encoding='utf-8') as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            raise ValueError
+        return data
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return {}  # unreadable: as if none were saved; the next save rewrites it
+
+
+def _save(data):
+    path = _path()
+    if not data:
+        try:
+            os.remove(str(path))
+        except FileNotFoundError:
+            pass
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix='.credentials-', suffix='.part')  # created 0600
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(data, f, separators=(',', ':'))
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, str(path))
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def get(key):
+    """The saved Credential for key, or None."""
+    with _lock:
+        item = _read().get(key)
+    try:
+        return Credential(item['scope'], item['secret'], item.get('username'))
+    except (TypeError, KeyError, ValueError):
+        return None
+
+
+def has(key):
+    return get(key) is not None
+
+
+def put(key, credential):
+    if not isinstance(credential, Credential):
+        raise TypeError('put() needs a Credential')
+    with _changing():
+        data = _read()
+        data[key] = credential._json()
+        _save(data)
+
+
+def remove(key):
+    """Delete key's credential from disk; True if there was one."""
+    with _changing():
+        data = _read()
+        if key not in data:
+            return False
+        del data[key]
+        _save(data)
+        return True
+
+
+def for_url(url):
+    """A saved credential url is in the scope of (see in_scope), or None. Call it again for
+    each redirect hop: the answer depends only on the URL being requested."""
+    with _lock:
+        keys = list(_read())
+    for key in keys:
+        credential = get(key)
+        if in_scope(credential, url):
+            return credential
+    return None
+
+
+class Handler(urllib.request.BaseHandler):
+    """Adds the credential to requests for its origin (redirects included) and strips
+    Authorization from every other request, so a redirect elsewhere never gets it.
+    scoped=True also requires each request, redirects included, to be in_scope."""
+    handler_order = 900  # after the default processors
+
+    def __init__(self, credential, scoped=False):
+        self.credential, self.scoped = credential, scoped
+
+    def _request(self, req):
+        req.remove_header('Authorization')
+        allowed = in_scope if self.scoped else lambda c, url: c is not None and c.matches(url)
+        if allowed(self.credential, req.full_url):
+            req.add_unredirected_header('Authorization', self.credential.header())
+        return req
+
+    http_request = https_request = _request

ui/apk_sources/_images.py

@@ -9,12 +9,10 @@ import threading
 import time
 from urllib.parse import urljoin, urlsplit
 
-from apk_sources import SourceError
+from apk_sources import SourceError, _credentials
 
 _lock = threading.Lock()
-_urls = OrderedDict()  # token -> URL, oldest first
-_tokens = {}  # URL -> token
-MAX_TOKENS = 16384
+_urls = OrderedDict()
 _cache = OrderedDict()
 MAX_IMAGE = 8 * 1024 * 1024
 MAX_CACHE = 64 * 1024 * 1024
@@ -33,24 +31,24 @@ def register(url):
     if not isinstance(url, str) or not valid_url(url):
         return None
     with _lock:
-        token = _tokens.get(url)
-        if token in _urls:
-            _urls.move_to_end(token)
-            return '/source-image/' + token
+        for token, known in _urls.items():
+            if known == url:
+                _urls.move_to_end(token)
+                return '/source-image/' + token
         token = secrets.token_urlsafe(24)
-        _urls[token], _tokens[url] = url, token
-        while len(_urls) > MAX_TOKENS:  # a store browse lists a few thousand images
-            _tokens.pop(_urls.popitem(last=False)[1], None)
+        _urls[token] = url
+        while len(_urls) > 4096:
+            _urls.popitem(last=False)
     return '/source-image/' + token
 
 
-def artwork(entry, shots=12):
+def artwork(entry):
     images = entry.get('images') or {}
     if not isinstance(images, dict):
         images = {}
     return {'icon': register(images.get('icon') or entry.get('icon')),
             'banner': register(images.get('banner')),
-            'screenshots': [path for path in (register(u) for u in (images.get('screenshots') or [])[:min(shots, 12)]) if path]}
+            'screenshots': [path for path in (register(u) for u in (images.get('screenshots') or [])[:12]) if path]}
 
 
 def image_type(data):
@@ -73,37 +71,12 @@ def fetch(url, redirects=3, deadline=None, limit=MAX_IMAGE):
 
 # Lookups that outlast their deadline keep running; cap them so they can't pile up.
 _resolvers = threading.BoundedSemaphore(4)
-# A page of store cards asks for dozens of images from the same few hosts at once: their public
-# addresses are kept for a few minutes, so most requests don't need a lookup (or a slot) at all.
-_dns = {}  # (host, port) -> (addresses, expires)
-DNS_TTL = 300
 
 
 def _resolve(host, port, timeout):
-    with _lock:
-        known = _dns.get((host, port))
-    if known and known[1] > time.monotonic():
-        return known[0]
-    found = _lookup(host, port, timeout)
-    try:
-        public = bool(found) and all(ipaddress.ip_address(a[4][0]).is_global for a in found)
-    except (TypeError, ValueError, IndexError):
-        public = False
-    if public:  # private answers are refused by the caller, and never kept
-        with _lock:
-            _dns[(host, port)] = (found, time.monotonic() + DNS_TTL)
-            while len(_dns) > 256:
-                _dns.pop(next(iter(_dns)))
-    return found
-
-
-def _lookup(host, port, timeout):
     # getaddrinfo has no timeout of its own; a thread keeps a slow resolver inside the budget.
-    # A request waits for a free slot within its own budget rather than failing at once.
-    started = time.monotonic()
-    if not _resolvers.acquire(timeout=max(0, min(timeout, 10))):
+    if not _resolvers.acquire(blocking=False):
         raise SourceError('Too many slow artwork name lookups are still running; try again shortly')
-    timeout -= time.monotonic() - started  # the wait for a slot comes out of the same budget
     found = {}
 
     def run():
@@ -168,7 +141,11 @@ def get(url, headers=None, redirects=3, deadline=None, limit=MAX_IMAGE):
         path = p.path or '/'
         if p.query:
             path += '?' + p.query
-        conn.request('GET', path, headers={'User-Agent': 'FrameControl/0.3.1', **(headers or {})})
+        sent = {'User-Agent': 'FrameControl/0.3.1', **(headers or {})}
+        login = _credentials.for_url(url)  # a repository behind a login: its own artwork only, per hop
+        if login:
+            sent['Authorization'] = login.header()
+        conn.request('GET', path, headers=sent)
         live[0].settimeout(min(10, left()))
         response = conn.getresponse()
         if response.status in (301, 302, 303, 307, 308) and redirects:

ui/apk_sources/_web.py

@@ -3,7 +3,7 @@ import hashlib, os, shutil, tempfile, threading, time, urllib.error, urllib.pars
 from email.utils import parsedate_to_datetime
 
 import frame_host
-from . import SourceError, SourceLimited
+from . import SourceAuthError, SourceError, SourceLimited, _credentials
 
 UA = 'FrameControl/0.1'
 APK_CAP = 2 * 1024 ** 3  # cached APKs across all sources, least recently used go first
@@ -38,7 +38,7 @@ def release(path):
         else:
             _in_use.pop(path, None)
 BACKOFF = 600  # seconds to leave a host alone after 403/429 without Retry-After
-_limited = {}  # host -> time.time() before which we don't contact it
+_limited = {}  # host (+ login identity) -> time.time() before which we don't ask it with that login
 _limited_lock = threading.Lock()
 
 
@@ -46,8 +46,16 @@ def _host(url):
     return (urllib.parse.urlsplit(url).hostname or '').lower()
 
 
-def throttle(url, headers=None):
-    """Remember that url's host asked us to back off; return the delay in seconds."""
+def _who(url, auth=None):
+    """Backoff key: the host, per login. A token has its own quota, so anonymous
+    rate limiting mustn't hold back requests made with one (or the reverse)."""
+    if auth is None:
+        return _host(url)
+    return _host(url) + ' ' + hashlib.sha256(auth.header().encode()).hexdigest()[:16]
+
+
+def throttle(url, headers=None, auth=None):
+    """Remember that url's host asked us (with this login) to back off; return the delay in seconds."""
     headers = headers or {}
     now, delay = time.time(), None
     value = (headers.get('Retry-After') or '').strip()
@@ -62,14 +70,15 @@ def throttle(url, headers=None):
     if delay is None and headers.get('X-RateLimit-Remaining') == '0' and reset.isdigit():
         delay = int(reset) - now  # GitHub
     delay = min(max(delay if delay is not None else BACKOFF, 1), 6 * 3600)
+    key = _who(url, auth)
     with _limited_lock:
-        _limited[_host(url)] = max(_limited.get(_host(url), 0), now + delay)
+        _limited[key] = max(_limited.get(key, 0), now + delay)
     return delay
 
 
-def wait_time(url):
+def wait_time(url, auth=None):
     with _limited_lock:
-        return max(0, _limited.get(_host(url), 0) - time.time())
+        return max(0, _limited.get(_who(url, auth), 0) - time.time())
 
 
 def limited_error(name, seconds, hint=''):
@@ -136,6 +145,8 @@ def checked_url(url, hosts):
 
 
 class Redirect(urllib.request.HTTPRedirectHandler):
+    """Only to the allowed hosts, and never carrying an Authorization header along:
+    a credential passed to open_url() is added again, by its Handler, only on its origin."""
     def __init__(self, hosts):
         self.hosts = hosts
 
@@ -147,13 +158,15 @@ class Redirect(urllib.request.HTTPRedirectHandler):
         return result
 
 
-def open_url(url, hosts, headers=None):
+def open_url(url, hosts, headers=None, auth=None):
+    """auth: an _credentials.Credential, sent only to requests on its own origin."""
     checked_url(url, hosts)
-    return urllib.request.build_opener(Redirect(hosts)).open(
+    handlers = [Redirect(hosts)] + ([_credentials.Handler(auth)] if auth else [])
+    return urllib.request.build_opener(*handlers).open(
         urllib.request.Request(url, headers={'User-Agent': UA, **(headers or {})}), timeout=60)
 
 
-def read(url, hosts, headers=None, ttl=3600, name=None, hint=''):
+def read(url, hosts, headers=None, ttl=3600, name=None, hint='', auth=None):
     path = os.path.join(cache(), hashlib.sha256(url.encode()).hexdigest() + '.data')
     name = name or _host(url) or 'The source'
 
@@ -165,13 +178,13 @@ def read(url, hosts, headers=None, ttl=3600, name=None, hint=''):
         if os.path.isfile(path) and time.time() - os.path.getmtime(path) < ttl:
             with open(path, 'rb') as f:
                 return f.read()
-        wait = wait_time(url)
+        wait = wait_time(url, auth)
         if wait:
             data = cached()
             if data is None:
                 raise limited_error(name, wait, hint)
             return data
-        with open_url(url, hosts, headers) as r:
+        with open_url(url, hosts, headers, auth) as r:
             data = r.read(8 * 1024 * 1024 + 1)
         if len(data) > 8 * 1024 * 1024:
             raise SourceError('Source index is too large')
@@ -185,8 +198,10 @@ def read(url, hosts, headers=None, ttl=3600, name=None, hint=''):
                 os.remove(tmp)
         return data
     except urllib.error.HTTPError as e:
+        if e.code == 401:  # not 403: GitHub also uses that for rate limits, token or not
+            raise SourceAuthError('%s refused the login (HTTP 401)' % name) from e
         if e.code in (403, 429):
-            delay = throttle(url, e.headers)
+            delay = throttle(url, e.headers, auth)
             data = cached()
             if data is None:
                 raise limited_error(name, delay, hint) from e

ui/apk_sources/fdroid.py

@@ -20,13 +20,13 @@ import zipfile
 
 if __package__ in (None, ''):
     sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-from apk_sources import SourceError, SourceLimited, _web
+from apk_sources import SourceAuthError, SourceError, SourceLimited, _credentials, _web
 import frame_host
 from frame_apk_sign import _der_parts, _cert_key, der
 from frame_catalog import _IndexReader, _reduce_index, _sha256
 
 KIND = 'fdroid'
-CACHE_VERSION = 3  # 3: categories
+CACHE_VERSION = 2
 TMP_PREFIX = '.download-'  # in the cache folder, then the server's PID, so server.sweep_tmp can clear a stopped run's
 _LOCK = threading.RLock()  # settings only; never held while downloading
 _load_locks = {}
@@ -71,6 +71,39 @@ def _url(url, fingerprint=None):
     return urllib.parse.urlunsplit(('https', p.netloc.lower(), p.path.rstrip('/') + '/', '', '')), pin
 
 
+def _split_login(url, username=None, password=None):
+    """(url without user:pass, credential or None). The address may carry the login, as
+    F-Droid's client accepts (https://user:pass@host/fdroid/repo), or it may be given apart."""
+    try:
+        p = urllib.parse.urlsplit(url)
+        p.port
+    except ValueError as e:
+        raise SourceError('invalid repository URL') from e
+    if '@' in p.netloc:
+        if p.username is None:
+            raise SourceError('invalid repository URL')
+        linked = urllib.parse.unquote(p.username), None if p.password is None else urllib.parse.unquote(p.password)
+        if username not in (None, '', linked[0]) or (linked[1] is not None and password not in (None, '', linked[1])):
+            raise SourceError('the address and the username/password fields disagree')
+        username = linked[0]
+        password = linked[1] if linked[1] is not None else password
+        url = urllib.parse.urlunsplit((p.scheme, p.netloc.rpartition('@')[2], p.path, p.query, p.fragment))
+    if username in (None, ''):
+        if password:
+            raise SourceError('a password needs a username')
+        return url, None
+    clean, _ = _url(url)
+    try:
+        return url, _credentials.basic(clean, username, password or '')
+    except ValueError as e:
+        raise SourceError('cannot use that login: ' + str(e)) from None
+
+
+def _login(source):
+    """The saved login for a user repository, or None."""
+    return None if source.get('builtin') else _credentials.get(source['id'])
+
+
 def _child(base, name):
     name = str(name).lstrip('/')
     decoded = urllib.parse.unquote(name)
@@ -81,6 +114,9 @@ def _child(base, name):
     url = urllib.parse.urljoin(base, urllib.parse.quote(decoded, safe='/'))  # names may contain '#' or spaces
     if not url.startswith(base) or urllib.parse.urlsplit(url).query or urllib.parse.urlsplit(url).fragment:
         raise SourceError('repository file is outside its repository')
+    # Nothing a server could normalise elsewhere: double-encoded dots, ';' parameters, encoded slashes.
+    if _credentials.path_segments(urllib.parse.urlsplit(url).path) is None:
+        raise SourceError('unsafe repository file name')
     return url
 
 
@@ -91,14 +127,17 @@ class _HTTPSRedirect(urllib.request.HTTPRedirectHandler):
         return super().redirect_request(req, fp, code, msg, headers, newurl)
 
 
-def _fetch(url, path, maximum):
+def _fetch(url, path, maximum, auth=None):
+    """auth: the repository's login, sent only inside the repository (its origin and directory,
+    by whole plain path segments), on every request including redirects."""
     host = urllib.parse.urlsplit(url).hostname
-    wait = _web.wait_time(url)
+    wait = _web.wait_time(url, auth)
     if wait:
         raise _web.limited_error(host, wait)
     request = urllib.request.Request(url, headers={'User-Agent': 'FrameControl/1.0'})
+    handlers = [_HTTPSRedirect()] + ([_credentials.Handler(auth, scoped=True)] if auth else [])
     try:
-        with urllib.request.build_opener(_HTTPSRedirect()).open(request, timeout=60) as r, open(path, 'wb') as f:
+        with urllib.request.build_opener(*handlers).open(request, timeout=60) as r, open(path, 'wb') as f:
             total = 0
             while True:
                 chunk = r.read(1 << 20)
@@ -109,8 +148,11 @@ def _fetch(url, path, maximum):
                     raise SourceError('repository file exceeds size limit')
                 f.write(chunk)
     except urllib.error.HTTPError as e:
+        if e.code == 401 or (e.code == 403 and auth):
+            raise SourceAuthError('The repository refused the login (HTTP %d); check the username and password'
+                                  % e.code if auth else 'This repository needs a username and password') from None
         if e.code in (403, 429):
-            raise _web.limited_error(host, _web.throttle(url, e.headers)) from e
+            raise _web.limited_error(host, _web.throttle(url, e.headers, auth)) from e
         raise
 
 
@@ -342,7 +384,7 @@ def sources():
     return [dict(id=i, kind=KIND, name=n, url=u, fingerprint=p, builtin=True,
                  # The archive only holds superseded versions; it clutters search unless asked for.
                  enabled=settings['enabled'].get(i, i != 'fdroid-archive'), trust='community')
-            for i, n, u, p in builtins] + settings['repos']
+            for i, n, u, p in builtins] + [dict(s, login=_credentials.has(s['id'])) for s in settings['repos']]
 
 
 def _text(value):
@@ -432,7 +474,6 @@ def _reduce(path, source):
                     name=_text(meta.get('name')) or pkg, summary=_summary(meta.get('summary')),
                     icon=images['icon'], images=images, developer=_text(meta.get('authorName')) or None,
                     page=meta.get('webSite') or source['url'], vr=None, free=True,
-                    categories=[c for c in meta.get('categories') or [] if isinstance(c, str)][:8],
                     license=meta.get('license'), downloadable=bool(latest.get('sha256')),
                     versions=versions, **{k: latest[k] for k in ('version', 'version_code', 'min_sdk', 'abis', 'size', 'updated')})
     return result
@@ -451,7 +492,6 @@ def _v1(content, path):
         localized = app.get('localized', {})
         meta = {k: _text({locale: fields[k] for locale, fields in localized.items() if fields.get(k)}) or app.get(k)
                 for k in ('name', 'summary', 'license', 'webSite', 'authorName')}
-        meta['categories'] = app.get('categories') or []
         for field in ('icon', 'featureGraphic', 'phoneScreenshots', 'sevenInchScreenshots'):
             images = {}
             for locale, fields in localized.items():
@@ -516,10 +556,12 @@ def _source_lock(source_id):
         return _load_locks.setdefault(source_id, threading.Lock())
 
 
-def _load(source, force=False):
+def _load(source, force=False, auth=None):
+    """auth: a login to use instead of the saved one (while adding, before anything is saved)."""
     if not re.fullmatch(r'[a-z0-9-]+', source['id']):
         raise SourceError('invalid source id')
     _url(source['url'], source.get('fingerprint'))
+    auth = auth or _login(source)
     cache = frame_host.cache_dir('apk-sources', source['id'] + '.json')
     found = None if force else _cached(source, cache)
     if found:
@@ -537,7 +579,7 @@ def _load(source, force=False):
                 jar, raw = Path(tmp) / 'index.jar', Path(tmp) / 'index.json'
                 v2 = True
                 try:
-                    _fetch(source['url'] + 'entry.jar', jar, 8 * 1024 * 1024)
+                    _fetch(source['url'] + 'entry.jar', jar, 8 * 1024 * 1024, auth=auth)
                 except urllib.error.HTTPError as e:
                     if e.code not in (404, 410):
                         raise
@@ -545,7 +587,7 @@ def _load(source, force=False):
                         raise SourceError('repository no longer serves its signed v2 index; '
                                           'refusing to fall back to the older v1 index') from e
                     v2 = False
-                    _fetch(source['url'] + 'index-v1.jar', jar, 256 * 1024 * 1024)
+                    _fetch(source['url'] + 'index-v1.jar', jar, 256 * 1024 * 1024, auth=auth)
                     content, pin = _jar(jar, 'index-v1.json', source.get('fingerprint'))
                     timestamp = _v1(content, raw)
                     _check_timestamp(source, timestamp)
@@ -554,7 +596,7 @@ def _load(source, force=False):
                     signed = json.loads(content)
                     timestamp, entry = signed.get('timestamp'), signed['index']
                     _check_timestamp(source, timestamp)
-                    _fetch(_child(source['url'], entry['name']), raw, 512 * 1024 * 1024)
+                    _fetch(_child(source['url'], entry['name']), raw, 512 * 1024 * 1024, auth=auth)
                     if _sha256(raw) != entry['sha256'] or (entry.get('size') is not None and raw.stat().st_size != entry['size']):
                         raise SourceError('index SHA-256 or size mismatch')
                 apps = _reduce(raw, source)
@@ -574,7 +616,10 @@ def _load(source, force=False):
             raise SourceError('cannot load repository: ' + str(e)) from e
 
 
-def add_repo(url, fingerprint=None, name=None):
+def add_repo(url, fingerprint=None, name=None, username=None, password=None):
+    """Check and save a repository. A login (in the URL or apart) is kept out of the
+    saved URL, in _credentials, and saved only once the repository's index verified."""
+    url, login = _split_login(url, username, password)
     url, pin = _url(url, fingerprint)
     with _LOCK:
         existing = next((s for s in _read()['repos'] if s['url'] == url), None)
@@ -585,15 +630,26 @@ def add_repo(url, fingerprint=None, name=None):
     source = dict(id='fdroid-user-' + hashlib.sha256(url.encode()).hexdigest()[:20], kind=KIND,
                   name=name or (existing or {}).get('name') or urllib.parse.urlsplit(url).hostname,
                   url=url, builtin=False, enabled=True, trust='user', fingerprint=pin)
-    _, source['fingerprint'] = _load(source, force=True)  # network work outside the settings lock
+    # Network work outside the settings lock; without a new login, a saved one (re-adding) is used.
+    _, source['fingerprint'] = _load(source, force=True, auth=login)
     source['trust_on_first_use'] = existing.get('trust_on_first_use', False) if existing else pin is None
     with _LOCK:
         settings = _read()
         current = next((s for s in settings['repos'] if s['id'] == source['id']), None)
         if current and current['fingerprint'] != source['fingerprint']:
             raise SourceError('repository already has a different pinned fingerprint; remove it first')
-        settings['repos'] = [s for s in settings['repos'] if s['id'] != source['id']] + [source]
-        _write(_storage(), settings)
+        previous = _credentials.get(source['id'])
+        if login:
+            _credentials.put(source['id'], login)
+        try:
+            settings['repos'] = [s for s in settings['repos'] if s['id'] != source['id']] + [source]
+            _write(_storage(), settings)
+        except BaseException:
+            if login and previous:  # not saved after all: leave the login as it was
+                _credentials.put(source['id'], previous)
+            elif login:
+                _credentials.remove(source['id'])
+            raise
     return source
 
 
@@ -604,6 +660,7 @@ def remove_repo(source_id):
             raise SourceError('unknown user repository')
         settings['repos'] = [s for s in settings['repos'] if s['id'] != source_id]
         _write(_storage(), settings)
+        _credentials.remove(source_id)
     with _state_file_lock(), _LOCK:  # lock order: state file, then _LOCK
         states = _states()
         if states.pop(source_id, None) is not None:  # re-adding is a deliberate new trust decision
@@ -627,39 +684,16 @@ def set_enabled(source_id, enabled):
         _write(_storage(), settings)
 
 
-def _showcase(a):
-    """Browse order without a query: apps with real artwork first, then the most recently updated."""
-    images = a.get('images') or {}
-    return (not images.get('banner'), not images.get('screenshots'), not images.get('icon'),
-            ''.join(chr(0x10ffff - ord(c)) for c in str(a.get('updated') or '')))
-
-
-def search(source, query, limit=50, keep=None):
-    """keep: optional filter applied before the limit (the store's category browse)."""
+def search(source, query, limit=50):
     if not source.get('enabled', True):
         return []
     apps, _ = _load(source)
     words = query.casefold().split()
-    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)
-             and (keep is None or keep(a))]
-    if words:
-        found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
-    else:
-        found.sort(key=_showcase)
+    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)]
+    found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
     return [{k: v for k, v in a.items() if k != 'versions'} for a in found[:max(0, limit)]]
 
 
-def lookup(source, packages):
-    """Entries for these packages from the saved index only (never downloads); missing ones are left out."""
-    if not source.get('enabled', True):
-        return {}
-    found = _cached(source, frame_host.cache_dir('apk-sources', source['id'] + '.json'))
-    if not found:
-        return {}
-    apps = found[0]
-    return {p: {k: v for k, v in apps[p].items() if k != 'versions'} for p in packages if p in apps}
-
-
 def details(source, entry_id):
     if not source.get('enabled', True):
         raise SourceError('repository is disabled')
@@ -688,7 +722,7 @@ def download(source, entry_id, version_code=None):
             fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix='.part')
             os.close(fd)
             try:
-                _fetch(_child(source['url'], version['name']), tmp, 4 * 1024 ** 3)
+                _fetch(_child(source['url'], version['name']), tmp, 4 * 1024 ** 3, auth=_login(source))
                 if _sha256(tmp) != sha:
                     raise SourceError('APK SHA-256 mismatch; download discarded')
                 os.replace(tmp, path)
@@ -709,6 +743,8 @@ def main():
     add.add_argument('url')
     add.add_argument('--fingerprint')
     add.add_argument('--name')
+    add.add_argument('--username', help='for a repository behind a login (HTTP basic auth)')
+    add.add_argument('--password-stdin', action='store_true', help='read the password from the first line of stdin')
     sub.add_parser('list')
     remove = sub.add_parser('remove')
     remove.add_argument('source')
@@ -727,7 +763,12 @@ def main():
 def _cli(parser, args):
     try:
         if args.command == 'add':
-            result = add_repo(args.url, args.fingerprint, args.name)
+            password = None
+            if args.password_stdin:
+                if not args.username:
+                    raise SourceError('--password-stdin needs --username')
+                password = sys.stdin.readline().rstrip('\r\n')
+            result = add_repo(args.url, args.fingerprint, args.name, args.username, password)
         elif args.command == 'list':
             result = sources()
         elif args.command == 'remove':

ui/apk_sources/github.py

@@ -1,17 +1,77 @@
 """Curated publisher releases; optional topic discovery is page-only."""
-import fnmatch, json, os, re, urllib.parse
+import fnmatch, hashlib, json, os, re, sys, threading, urllib.parse
 
-from . import SourceError, _web
+from . import SourceAuthError, SourceError, _credentials, _web
 
 KIND = 'github'
 API = 'https://api.github.com'
+ENV = 'FRAME_GITHUB_TOKEN'  # wins over a token saved in source settings
+CREDENTIAL = 'github'  # _credentials key; only ever sent to api.github.com
+_rejected = set()  # SHA-256 of tokens GitHub answered 401 to (this run only)
+_rejected_lock = threading.Lock()
 TOPICS = ('oculus-quest', 'openxr', 'quest')
 HOSTS = ('github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com')
 
 
 def sources():
     return [{'id': KIND, 'kind': KIND, 'name': 'GitHub releases', 'url': 'https://github.com',
-             'builtin': True, 'enabled': True, 'trust': 'community'}]
+             'builtin': True, 'enabled': True, 'trust': 'community', 'token': token_status()}]
+
+
+def _token():
+    """(token, where it came from) or (None, None). The environment variable wins."""
+    env = os.environ.get(ENV)
+    if env:
+        return env, 'env'
+    saved = _credentials.get(CREDENTIAL)
+    if saved and saved.kind == 'bearer':
+        return saved, 'saved'
+    return None, None
+
+
+def _credential(token):
+    if isinstance(token, _credentials.Credential):
+        return token
+    try:
+        return _credentials.bearer(API + '/', token)
+    except ValueError as e:
+        raise SourceError('%s is not a usable GitHub token: %s' % (ENV, e)) from None
+
+
+def _digest(credential):
+    return hashlib.sha256(credential.header().encode()).hexdigest()
+
+
+def token_status():
+    """Whether a token is set, where from, and whether GitHub rejected it; never the token."""
+    token, where = _token()
+    rejected = False
+    if token is not None:
+        try:
+            with _rejected_lock:
+                rejected = _digest(_credential(token)) in _rejected
+        except SourceError:
+            rejected = True
+    return {'set': token is not None, 'from': where, 'rejected': rejected}
+
+
+def set_token(token):
+    """Save a personal access token for api.github.com (FRAME_GITHUB_TOKEN still wins)."""
+    if not isinstance(token, str) or not token.strip():
+        raise SourceError('Paste a GitHub token')
+    try:
+        credential = _credentials.bearer(API + '/', token.strip())
+    except ValueError as e:
+        raise SourceError('That is not a usable GitHub token: ' + str(e)) from None
+    _credentials.put(CREDENTIAL, credential)
+    with _rejected_lock:
+        _rejected.discard(_digest(credential))  # a fresh chance
+    return {'message': 'GitHub token saved' + (' (%s is set and is used instead)' % ENV if os.environ.get(ENV) else '')}
+
+
+def clear_token():
+    _credentials.remove(CREDENTIAL)
+    return {'message': 'GitHub token removed'}
 
 
 def _curated():
@@ -20,13 +80,33 @@ def _curated():
 
 
 def _api(path):
+    """GET from the GitHub API, with the user's token if there is one. If GitHub rejects
+    the token (401), retry once without it, like Obtainium, and remember the rejection."""
     headers = {'Accept': 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28'}
-    token = os.environ.get('FRAME_GITHUB_TOKEN')
-    if token:
-        headers['Authorization'] = 'Bearer ' + token
+    token, _ = _token()
+    auth = _credential(token) if token is not None else None
+    with _rejected_lock:
+        if auth and _digest(auth) in _rejected:
+            auth = None  # already refused this run: don't spend a request on it again
+    hint = ' (add a GitHub token in the store\'s source settings, or set %s, to raise the limit)' % ENV
+    if token is not None and not auth:
+        hint = ' (GitHub rejected your token; replace it in the store\'s source settings)'
+
+    def get(auth):
+        return _web.read(API + path, ('api.github.com',), headers, name='GitHub',
+                         hint='' if auth else hint, auth=auth)
     try:
-        return json.loads(_web.read(API + path, ('api.github.com',), headers, name='GitHub',
-                                    hint='' if token else ' (set FRAME_GITHUB_TOKEN to raise the limit)'))
+        try:
+            data = get(auth)
+        except SourceAuthError:
+            if not auth:
+                raise
+            with _rejected_lock:
+                _rejected.add(_digest(auth))
+            print('GitHub rejected the access token (HTTP 401); continuing without it', file=sys.stderr)
+            hint = ' (GitHub rejected your token; replace it in the store\'s source settings)'
+            data = get(None)
+        return json.loads(data)
     except (ValueError, TypeError) as e:
         raise SourceError('Invalid GitHub response') from e
 

ui/apk_sources/search.py

@@ -15,7 +15,7 @@ import time
 import unicodedata
 
 import frame_host
-from apk_sources import SourceError, SourceLimited, _categories as categories
+from apk_sources import SourceError, SourceLimited
 
 _lock = threading.RLock()
 _running = {}
@@ -23,7 +23,6 @@ _pending = {}  # source id -> newest query waiting for the running one
 _game_data = {}  # package -> downloaded OBB paths waiting for "Add game data"
 _status = {}
 TIMEOUT = 12
-BROWSE_LIMIT = 300  # apps per source when browsing without a query, before grouping
 
 
 def modules():
@@ -114,6 +113,14 @@ def manage_repo(action, **kwargs):
     return getattr(module, action)(**kwargs)
 
 
+def set_token(source_id, token):
+    """Save (token) or remove (None) a source's access token; status is in sources()."""
+    module, _ = resolve(source_id)
+    if not hasattr(module, 'set_token'):
+        raise SourceError('This source does not use an access token')
+    return module.set_token(token) if token is not None else module.clear_token()
+
+
 def normalise(name):
     return ' '.join(re.findall(r'\w+', unicodedata.normalize('NFKC', name or '').casefold()))
 
@@ -159,11 +166,9 @@ def verdict(entry):
     return {'label': 'Not yet checked on the Frame', 'tone': 'unknown'}
 
 
-def decorate(entry, shots=12):
-    """shots: screenshots to offer; a listing card shows three, the detail page all of them."""
+def decorate(entry):
     from apk_sources import _images
-    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry, shots),
-                **categories.classify(entry))
+    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry))
 
 
 def details(source_id, entry_id):
@@ -181,12 +186,10 @@ def offer_rank(entry):
             entry.get('trust') == 'official')
 
 
-def group(entries, query='', vr=None, installable=False, category=None, phone=False):
+def group(entries, query='', vr=None, installable=False):
     groups = {}
     for entry in entries:
-        entry = decorate(entry, shots=3)
-        if not categories.matches(entry, category, phone):
-            continue
+        entry = decorate(entry)
         if vr is not None and (entry.get('vr') is True) != vr:  # unknown counts as flat
             continue
         if installable and entry['fit']['installable'] is not True:
@@ -200,7 +203,7 @@ def group(entries, query='', vr=None, installable=False, category=None, phone=Fa
         offers.sort(key=offer_rank, reverse=True)
         best = offers[0]
         result.append({'name': best.get('name'), 'package': best.get('package'),
-                       'summary': best.get('summary'), 'category': best.get('category'), 'offers': offers})
+                       'summary': best.get('summary'), 'offers': offers})
     q = normalise(query)
 
     def browse(a):  # a headset store: VR first, then apps with artwork, newest first
@@ -220,10 +223,10 @@ def group(entries, query='', vr=None, installable=False, category=None, phone=Fa
     return result
 
 
-def _launch(module, source, query, limit, category=None, phone=False):
+def _launch(module, source, query, limit):
     """One search per source at a time; the newest different query runs next."""
     key = source['id']
-    task = {'event': threading.Event(), 'query': (query, limit, category or None, bool(phone)), 'started': time.monotonic(),
+    task = {'event': threading.Event(), 'query': (query, limit), 'started': time.monotonic(),
             'job': (module, source)}
     with _lock:
         old = _running.get(key)
@@ -242,17 +245,13 @@ def _launch(module, source, query, limit, category=None, phone=False):
 
 def _start(key, task):
     module, source = task['job']
-    query, limit, category, phone = task['query']
-    kwargs = {}
-    if (category or not phone) and 'keep' in inspect.signature(module.search).parameters:
-        # Large sources filter before their limit, so a category browse isn't cut to the first few hundred.
-        kwargs['keep'] = lambda e: categories.matches(dict(e, **categories.classify(e)), category, phone)
+    query, limit = task['query']
 
     def run():
         queued = None
         try:
             task['entries'] = [dict(e, source=key, source_name=source['name'], trust=source.get('trust'))
-                               for e in module.search(source, query, limit=limit, **kwargs) if e.get('free') is True]
+                               for e in module.search(source, query, limit=limit) if e.get('free') is True]
             task['stale'] = bool(getattr(module, 'stale', lambda s: False)(source))
         except Exception as e:
             task['error'] = str(e)
@@ -268,20 +267,14 @@ def _start(key, task):
     threading.Thread(target=run, daemon=True).start()
 
 
-def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50, category=None, phone=False):
+def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50):
     items, errors = registry()
     if source and source not in [s['id'] for _, s in items]:
         raise SourceError('Unknown source')
-    if category and category not in categories.IDS:
-        raise SourceError('Unknown category')
-    if not query.strip():
-        limit = max(limit, BROWSE_LIMIT)
-    else:
-        phone = True  # the phone-only guess hides apps from browsing, never from a search for them
     chosen = [(m, s) for m, s in items if s['enabled'] and (not source or s['id'] == source)]
     # Page-only sources (SideQuest) can't be searched; offer a link to browse them instead.
     elsewhere = [{'name': s['name'], 'url': s['url']} for m, s in chosen if s.get('page_only')]
-    tasks = [(s, _launch(m, s, query, limit, category, phone)) for m, s in chosen if not s.get('page_only')]
+    tasks = [(s, _launch(m, s, query, limit)) for m, s in chosen if not s.get('page_only')]
     entries, statuses = [], list(errors)
     for s, task in tasks:
         status = {'id': s['id'], 'name': s['name']}
@@ -296,8 +289,7 @@ def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, l
         statuses.append(status)
         with _lock:
             _status[s['id']] = {k: v for k, v in status.items() if k not in ('id', 'name')}
-    return {'apps': group(entries, query, vr, installable, category, phone), 'sources': statuses, 'elsewhere': elsewhere,
-            'categories': [{'id': c, 'label': label} for c, label in categories.CATEGORIES]}
+    return {'apps': group(entries, query, vr, installable), 'sources': statuses, 'elsewhere': elsewhere}
 
 
 def warm():
@@ -307,35 +299,7 @@ def warm():
     items, _ = registry()
     for m, s in items:
         if s['enabled'] and not s.get('page_only'):
-            _launch(m, s, '', BROWSE_LIMIT)  # same as the first browse, so that search reuses it
-
-
-def artwork_for(apps):
-    """Store artwork for installed apps ({'package', 'label'} each), from saved indexes only:
-    by package where a source has one, else by name (curated GitHub apps). {package: artwork}."""
-    from apk_sources import _images
-    items, _ = registry()
-    wanted = {a['package']: normalise(a.get('label')) for a in apps if a.get('package')}
-    found = {}
-    for module, source in items:
-        if not source['enabled'] or source.get('page_only'):
-            continue
-        try:
-            if hasattr(module, 'lookup'):
-                hits = module.lookup(source, [p for p in wanted if p not in found])
-            elif module.KIND == 'github':  # a small local list; its entries have names, not packages
-                names = {n: p for p, n in wanted.items() if n and p not in found}
-                hits = {names[normalise(e['name'])]: e for e in module.search(source, '', limit=100)
-                        if normalise(e.get('name')) in names}
-            else:
-                continue
-        except (SourceError, OSError, ValueError, KeyError, TypeError):
-            continue
-        for package, entry in hits.items():
-            art = _images.artwork(entry)
-            if art['icon'] or art['banner'] or art['screenshots']:
-                found.setdefault(package, art)
-    return found
+            _launch(m, s, '', 50)  # same as the first browse, so that search reuses it
 
 
 def install(source_id, entry_id, version_code=None, progress=None):

ui/assistant.html

@@ -14,7 +14,7 @@ button.primary { background:#176b9c } button:disabled { opacity:.5; cursor:wait
 summary { overflow-wrap:anywhere; cursor:pointer }
 pre { white-space:pre-wrap; overflow-wrap:anywhere; font:inherit; max-height:380px; overflow:auto } [hidden] { display:none!important } #status { min-height:1.5em } small { color:#b8c6d5 }
 </style>
-<header><h1>Frame Control · Assistant</h1><a id="back" href="/" referrerpolicy="no-referrer">Back to Frame Control</a></header>
+<header><h1>Frame Control · Assistant</h1><a href="/">Back to Frame Control</a></header>
 <section id="approval" hidden aria-labelledby="approval-title">
 <h2 id="approval-title">An agent wants to change your Frame</h2>
 <p>Review the exact action below. Approve only if you asked for it. Approval expires after five minutes and works once.</p>
@@ -42,8 +42,6 @@ pre { white-space:pre-wrap; overflow-wrap:anywhere; font:inherit; max-height:380
 'use strict';
 const $ = id => document.getElementById(id);
 const key = __FRAME_KEY__;
-const backParams = new URLSearchParams({key});
-$('back').href = '/?' + backParams;
 let generation = 0;
 async function api(path, body) {
   const response = await fetch(path, {method:body === undefined ? 'GET' : 'POST',

ui/control-center.js

@@ -20,7 +20,7 @@
       keywords:'battery charging charger charge time estimate remaining power watts usb health heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
     {id:'storage', category:'device', icon:'files', title:'Storage & memory', kind:'read', label:'Read-only metrics',
       description:'Check free user and system storage plus available RAM. Manage installed apps in their existing libraries, or use SFTP for files.',
-      keywords:'disk space root home free total ram memory capacity cleanup usage storage', special:'storage', links:[['#library','Installed games'],['#linuxApps','Linux apps'],['#power','SFTP & remote tools']]},
+      keywords:'disk space root home free total ram memory capacity cleanup usage storage', special:'storage', links:[['#library','Installed games'],['#apps','Linux apps'],['#power','SFTP & remote tools']]},
     {id:'microphone', category:'device', icon:'audio', title:'Microphone & audio routing', kind:'headset', label:'In the headset',
       description:'Frame Control controls the default output volume only. Microphone mute, input gain, output selection, balance and per-app mixers have no verified API here.',
       keywords:'mic input microphone audio sink output device gain mute eq equalizer spatial audio balance headphones',
@@ -77,7 +77,7 @@
       guidance:'Seeking, subtitles, native HEIC/MPO and large splat scenes are not supported yet.'},
     {id:'flatpak', category:'apps', icon:'apps', title:'Linux desktop apps', kind:'flow', label:'Existing controls',
       description:'Install user Flatpaks by Flathub ID, choose quick picks like VLC and Moonlight, and manage installed apps.',
-      keywords:'flatpak firefox vlc remmina moonlight flathub install remove', links:[['#linuxApps','Manage Linux apps']]},
+      keywords:'flatpak firefox vlc remmina moonlight flathub install remove', links:[['#apps','Manage Linux apps']]},
     {id:'connection', category:'network', icon:'network', title:'Headsets & addresses', kind:'flow', label:'Existing controls',
       description:'Manage headsets, LAN, USB-C, mDNS and Tailscale addresses. Inspect connection attempts and choose the device you want to control.',
       keywords:'wifi wi-fi network ip ssh pairing keys discovery alias tailscale usb offline reconnect', links:[['#devices','Manage headsets','desktop'],['#connection','Connection details']],

ui/frame_agent.py

@@ -90,13 +90,6 @@ def validate(name, args):
 
 
 def call(server, body):
-    # Keep target validation, token consumption and dispatch inside one work
-    # reservation, including direct callers outside the HTTP handler.
-    with server.working():
-        return _call(server, body)
-
-
-def _call(server, body):
     name, args = body.get('name'), body.get('arguments', {})
     action = validate(name, args)
     if name in ('install', 'uninstall', 'panel') and not server.FLATPAK_ID.fullmatch(args['id']):
@@ -105,7 +98,6 @@ def _call(server, body):
         raise ValueError('Expected a Steam app ID')
     if name == 'keep_awake' and args['action'] == 'status':
         return keep_awake(server, 'status')
-    action['target'] = server.agent_target()
     token = body.get('confirmation')
     if not token:
         return approvals.request(action)

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
@@ -185,64 +187,308 @@ def _write_meta(d, meta):
     ssh(f'cat > {d}/meta.json.tmp && mv {d}/meta.json.tmp {d}/meta.json', input=json.dumps(meta, indent=1))
 
 
-# Only files this installer owns. Lepton compatdata and any other files beside
-# the app (including user data) are never part of update rollback.
-UPDATE_FILES = ('app.apk', 'launch.sh', 'instance.id', 'lepton-show-flatscreen',
-                'shortcut.id', 'meta.json', 'artwork')
-
-
-class UpdateRecoveryPending(FrameError):
-    """A new attempt does not own, and must not rewrite, an earlier recovery."""
-
-
-def _update_guard(d):
-    return (f'if [ -e {d}/update-recovery.json ] || [ -e {d}/.frame-update-backup ]; '
-            'then echo FRAME_UPDATE_RECOVERY_PENDING; exit 0; fi; ')
-
-
-def _check_update_guard(reply, d):
-    if reply.strip() == 'FRAME_UPDATE_RECOVERY_PENDING':
-        pkg = d.rsplit('/', 1)[-1]
-        raise UpdateRecoveryPending(f'Pending APK update recovery at {d}; prior record and backup preserved. '
-                                    f'Repair with `python3 ui/frame_android.py refresh-art {pkg}` before retrying')
-
-
-def _backup_update(d):
-    backup = f'{d}/.frame-update-backup'
-    files = ' '.join(UPDATE_FILES[1:])
-    # The APK is only ever replaced by rename, so a hard link keeps its old bytes
-    # without a second multi-gigabyte copy. Smaller mutable files need copies.
-    reply = ssh(_update_guard(d) + f'set -eu; mkdir {backup}; ln {d}/app.apk {backup}/app.apk; '
-        f'for f in {files}; do if [ -e {d}/"$f" ]; then cp -pR {d}/"$f" {backup}/"$f"; fi; done; '
-        f'touch {backup}/ready', timeout=120)
-    _check_update_guard(reply, d)
-
-
-def _restore_update(d, keep_backup=False):
-    backup = f'{d}/.frame-update-backup'
-    # Retain the snapshot if any restore step fails, so refresh-art can retry.
-    ssh(f'set -eu; test -f {backup}/ready; '
-        f'for f in {" ".join(UPDATE_FILES)}; do '
-        f'if [ -e {backup}/"$f" ]; then '
-        f'rm -rf {d}/"$f"; cp -pR {backup}/"$f" {d}/"$f"; '
-        f'else rm -rf {d}/"$f"; fi; done; '
-        f'rm -f {d}/app.apk.part {d}/meta.json.tmp; '
-        + ('' if keep_backup else f'rm -rf {backup}'), timeout=120)
-
-
-def _finish_update_recovery(d):
-    # The durable repair_completed checkpoint is written before this command.
-    # A partial cleanup or lost reply can then be retried without another restore.
-    ssh(f'rm -rf {d}/.frame-update-backup && '
-        f'rm -f {d}/update-recovery.json {d}/update-recovery.json.tmp', timeout=30)
-
-
 # Called after every install, worked or not, as fn(info, meta, error, seconds):
 # info is None if the APK couldn't be read, meta None and error set if it failed.
 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)
@@ -295,22 +541,16 @@ def _after_install(info, meta, error, start):
 
 
 def _install(apk_path, info, pkg, flatscreen, name, source, artwork=None):
-    d = f'{APPS_DIR}/{pkg}'
-    # Outside this attempt's transaction/error handler: a refusal cannot replace
-    # an earlier orphan ID, rollback uncertainty, snapshot or recovery record.
-    _check_update_guard(ssh(_update_guard(d)), d)
     try:
         images, art_warnings = frame_artwork.prepare(name or info['label'], info.get('icon_png'), artwork)
     except (ValueError, OSError) as e:
         raise FrameError(f'could not prepare artwork: {e}') from e
     iid = instance_id(pkg)
+    d = f'{APPS_DIR}/{pkg}'
     existing = read_meta(pkg)
-    ok, created, backed_up, library_started = False, None, False, False
+    ok, created = False, None
     try:
         ssh(f'mkdir -p {d}')
-        if existing:
-            _backup_update(d)
-            backed_up = True
         _copy(apk_path, f'{d}/app.apk.part')
         _copy(LAUNCHER, f'{d}/launch.sh', executable=True, timeout=120)
         marker = f'touch {d}/lepton-show-flatscreen' if flatscreen else f'rm -f {d}/lepton-show-flatscreen'
@@ -324,7 +564,6 @@ def _install(apk_path, info, pkg, flatscreen, name, source, artwork=None):
             if not shortcut:
                 raise FrameError(f'Steam did not return a shortcut id (got {reply[:80]!r})')
             created = shortcut
-        library_started = True  # configure can mutate Steam before raising
         presentation = apply_library(shortcut, name or info['label'], d, images,
                                      vr=not flatscreen, home=home,
                                      exe=f'{home}/{d}/launch.sh', start_dir=f'{home}/{d}',
@@ -332,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', []),
@@ -340,72 +580,26 @@ def _install(apk_path, info, pkg, flatscreen, name, source, artwork=None):
                 'library_warnings': presentation.get('warnings', []),
                 'artwork': presentation.get('artwork', {}), 'library_version': 2}
         _write_meta(d, meta)
-        if backed_up:
-            ssh(f'rm -rf {d}/.frame-update-backup', timeout=30)
         ok = True
         return meta
-    except UpdateRecoveryPending:
-        raise  # a recovery appeared after preflight; this attempt still owns nothing
-    except Exception as error:
-        if existing:
-            orphan, cleanup_error = None, None
-            if created:
-                try:
-                    shortcut_tool('remove', str(created))
-                except Exception as e:
-                    orphan, cleanup_error = created, str(e) or type(e).__name__
-                created = None  # any failed cleanup is recorded and retried by repair
-            rollback_error = None
-            if backed_up:
-                try:
-                    _restore_update(d)
-                except Exception as e:
-                    rollback_error = str(e) or type(e).__name__
-            if library_started or rollback_error or cleanup_error or not backed_up:
-                repair = f'python3 ui/frame_android.py refresh-art {pkg}'
-                record = {'error': str(error) or type(error).__name__,
-                          'files_restored': backed_up and rollback_error is None,
-                          'files_unchanged': not backed_up,
-                          'library_may_have_changed': library_started,
-                          'rollback_error': rollback_error, 'repair': repair,
-                          'orphan_shortcut': orphan, 'cleanup_error': cleanup_error,
-                          'backup': f'{d}/.frame-update-backup'}
-                evidence_error = None
-                try:
-                    ssh(f'cat > {d}/update-recovery.json.tmp && '
-                        f'mv {d}/update-recovery.json.tmp {d}/update-recovery.json', input=json.dumps(record))
-                except Exception as e:
-                    evidence_error = str(e) or type(e).__name__
-                state = 'Previous app files restored' if record['files_restored'] else 'App file rollback unconfirmed'
-                message = (f'{error}. {state}; Steam library may need repair. '
-                           f'Repair with `{repair}`. Recovery: {d}/update-recovery.json; '
-                           f'backup: {record["backup"]}')
-                if rollback_error:
-                    message += f'; rollback failed: {rollback_error}'
-                if cleanup_error:
-                    message += f'; shortcut {orphan} cleanup failed: {cleanup_error}'
-                if evidence_error:
-                    message += f'; could not save recovery record: {evidence_error}'
-                raise FrameError(message) from error
-        raise
     finally:
         if not ok and created:
             try:
                 shortcut_tool('remove', str(created))
-            except Exception:
+            except FrameError:
                 pass
         if not ok and not existing:
             # A first install that failed part-way: don't leave an orphan folder behind.
             try:
                 ssh(f'rm -rf {d}', timeout=30)
-            except Exception:
+            except FrameError:
                 pass
-        elif not ok and backed_up:
-            # No executable files or backups are deleted here. Rollback above
-            # reports its own failure and retains the snapshot for repair.
+        elif not ok:
+            # An update that failed: the app still works, but a partial copy of the new APK
+            # (scp leaves one; it can be gigabytes) mustn't stay beside it.
             try:
                 ssh(f'rm -f {d}/app.apk.part', timeout=30)
-            except Exception:
+            except FrameError:
                 pass
 
 
@@ -464,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)
@@ -481,44 +703,11 @@ def refresh_art(pkg=None, artwork=None, fill_only=False):
             except Exception as e:  # one app's failure must not stop the others
                 results.append({'package': app['package'], 'label': app.get('label'), 'error': str(e) or type(e).__name__})
         return results
-    if not PKG_RE.fullmatch(pkg or ''):
-        raise FrameError(f'bad package name {pkg!r}')
     with _install_lock:  # shared with install and remove: a removed app is never recreated
-        d = f'{APPS_DIR}/{pkg}'
-        recovering = ssh(f'test -f {d}/update-recovery.json && echo yes || true').strip() == 'yes'
-        if not recovering and ssh(f'test -e {d}/.frame-update-backup && echo yes || true').strip() == 'yes':
-            raise FrameError(f'Update snapshot at {d}/.frame-update-backup has no recovery record; '
-                             'rollback is unconfirmed. Inspect and preserve the snapshot before repair')
-        recovery = json.loads(ssh(f'cat {d}/update-recovery.json')) if recovering else {}
-        if recovery.get('repair_completed') is True:
-            m = _meta_or_fail(pkg)
-            _finish_update_recovery(d)
-            return m
-        if recovering:
-            snapshot = ssh(f'if [ -f {d}/.frame-update-backup/ready ]; then echo ready; '
-                           f'elif [ -d {d}/.frame-update-backup ]; then echo incomplete; fi').strip()
-            if snapshot == 'ready':
-                _restore_update(d, keep_backup=True)
-            elif snapshot == 'incomplete':
-                raise FrameError(f'Incomplete update snapshot at {d}/.frame-update-backup; '
-                                 'original app files were not changed. Inspect and remove this '
-                                 'incomplete snapshot before retrying refresh-art')
-            elif not (recovery.get('files_restored') or recovery.get('files_unchanged')):
-                raise FrameError(f'App rollback is unconfirmed and {d}/.frame-update-backup is absent; '
-                                 'inspect the APK, launcher, display marker and metadata before repair. '
-                                 f'Keep {d}/update-recovery.json as evidence')
         m = _meta_or_fail(pkg)
-        orphan = _int(recovery.get('orphan_shortcut'))
-        if orphan and orphan != m['shortcut']:
-            shortcut_tool('remove', str(orphan))
+        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"
@@ -537,7 +726,7 @@ def refresh_art(pkg=None, artwork=None, fill_only=False):
         try:
             result = apply_library(m['shortcut'], m['label'], d, images, vr=not m.get('flatscreen', True),
                                    home=home, exe=f'{home}/{d}/launch.sh', start_dir=f'{home}/{d}', details=m,
-                                   fill_only=fill_only and not created and not recovering)
+                                   fill_only=fill_only and not created)
         except Exception:
             if created:
                 try:
@@ -549,14 +738,6 @@ def refresh_art(pkg=None, artwork=None, fill_only=False):
         m['library_warnings'] = warnings + result.get('warnings', [])
         m['artwork_refreshed'] = time.strftime('%Y-%m-%dT%H:%M:%S')
         _write_meta(d, m)
-        if recovering:
-            # Keep the original failure/orphan evidence and snapshot until the
-            # whole repair is committed. Persist completion before cleanup so
-            # any failed/lost cleanup response leaves a safe retry path.
-            recovery['repair_completed'] = True
-            ssh(f'cat > {d}/update-recovery.json.tmp && '
-                f'mv {d}/update-recovery.json.tmp {d}/update-recovery.json', input=json.dumps(recovery))
-            _finish_update_recovery(d)
         return m
 
 def _int(v):
@@ -587,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():
@@ -739,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_devices.py

@@ -740,7 +740,9 @@ class Registry:
                 return a
         raise DeviceError(f"{host} isn't one of this headset's addresses")
 
-    def add_address(self, device_id, host, kind=None, label=""):
+    def add_address(self, device_id, host, kind=None, label="", first=False):
+        """Add an address at the end of the list, or at the front (first=True), where the
+        user's order makes it win over the others that work on the same network."""
         with self._changing():
             d = self._find(device_id)
             a = new_address(host, kind, label)
@@ -748,7 +750,7 @@ class Registry:
                 raise DeviceError(f"{a['host']} is already on the list")
             if len(d["addresses"]) >= 32:
                 raise DeviceError("That's enough addresses for one headset")
-            d["addresses"].append(a)
+            d["addresses"].insert(0 if first else len(d["addresses"]), a)
             self.save()
             return copy.deepcopy(a)
 

ui/frame_link.py

@@ -356,6 +356,7 @@ class Link:
         self.version = 0
         self.stopped = False
         self.kicks = []                 # reasons someone asked for a (re)connect
+        self.test_gen = {}              # device id -> its newest test of the addresses (see test())
         self.busy = False               # the loop is handling kicks
         self.state = {"phase": "idle", "reason": None, "device": None, "network": None, "stages": [],
                       "probes": [], "via": None, "error": None, "retry_at": None, "attempt": 0,
@@ -1306,9 +1307,13 @@ class Link:
         started = now()
         rows = [{"host": a["host"], "kind": a["kind"], "state": "waiting", "detail": "Waiting", "ip": None,
                  "rtt_ms": None, "ssh": None} for a in device["addresses"]]
+        with self.cond:
+            gen = self.test_gen[device_id] = self.test_gen.get(device_id, 0) + 1
 
         def put(**fields):
             with self.cond:
+                if gen != self.test_gen[device_id]:
+                    return  # a newer test has started: its results are the ones to show
                 self.state["tests"][device_id] = dict({"started": started, "done": False, "rows": rows}, **fields)
                 self.version += 1
                 self.cond.notify_all()
@@ -1617,7 +1622,8 @@ def devices_action(link, body, open_setup, busy=lambda: 0):
                 raise frame_devices.DeviceError(f"Removed, but couldn't edit ~/.ssh/config: {e}")
         msg = f"Removed {d['name']}" + (f" and its '{d['alias']}' entry in ~/.ssh/config" if removed else "")
     elif action == "address-add":
-        a = reg.add_address(did, body.get("host"), body.get("kind") or None, body.get("label") or "")
+        a = reg.add_address(did, body.get("host"), body.get("kind") or None, body.get("label") or "",
+                            first=body.get("first") is True)
         if is_active and link.state["phase"] == "failed":
             link.kick("retry")
         msg = f"Added {a['host']}"

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_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/server.py

@@ -57,6 +57,8 @@ import frame_link  # noqa: E402
 import frame_macview  # 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
@@ -114,12 +116,6 @@ def route(alias, host_opts):
         moved = alias != FRAME
         if moved:
             frame_catalog._env.clear()  # the SteamOS and Lepton builds reports record are per headset
-            # Invalidate launches before publishing the new route. send/stop share
-            # a writer lock, so an old process cannot receive events after this.
-            for name in ("_input", "_touch"):
-                agent = globals().get(name)
-                if agent:
-                    agent.stop()
         FRAME = frame_android.FRAME = alias
         HOST_OPTS = list(host_opts)
         MUX[:] = [*MUX_BASE, *HOST_OPTS]
@@ -129,6 +125,9 @@ def route(alias, host_opts):
     mv = globals().get("macview")
     if mv:
         mv.retarget(alias, host_opts)  # its tunnel is its own ssh: it must follow the headset too
+    agent = globals().get("_input")
+    if moved and agent:
+        agent.stop()  # typing and pointing mustn't go on reaching the headset switched away from
 
 
 LINK = None  # the connector (frame_link.Link); None on the Frame itself
@@ -138,7 +137,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
@@ -162,42 +161,13 @@ def busy_thread(fn, *args):
     with _work_lock:
         _work[0] += 1
 
-    released = False
-
-    def release():
-        nonlocal released
-        with _work_lock:
-            if not released:
-                released = True
-                _work[0] -= 1
-
     def run():
         try:
             fn(*args)
         finally:
-            release()
-    try:
-        worker = threading.Thread(target=run, daemon=True)
-    except Exception:
-        release()
-        raise
-    start = worker.start
-
-    def start_counted():
-        try:
-            start()
-        except Exception:
-            release()
-            raise
-    worker.start = start_counted
-    return worker
-
-
-def agent_target():
-    """Stable identity and reviewable name for a human-approved agent action."""
-    device = LINK.active_device() if LINK else {"id": "local" if LOCAL else FRAME,
-                                               "name": "This headset" if LOCAL else FRAME}
-    return {"id": device["id"], "name": device["name"]}
+            with _work_lock:
+                _work[0] -= 1
+    return threading.Thread(target=run, daemon=True)
 
 APPID = re.compile(r"^\d{1,10}$")
 FLATPAK_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+){2,}$")
@@ -286,13 +256,18 @@ _backfill = {"running": False, "last": 0.0}
 _backfill_lock = threading.Lock()
 
 
-def backfill_art(apps=(), titles=(), meant=None):
+def backfill_art(apps=(), titles=()):
     """Apply art Frame Control couldn't at install time (Steam wasn't running), once Steam is up.
 
     Only entries marked art_pending at install; it fills empty Steam slots and never replaces art or
     names the user may have customised. Runs in the background, at most once every five minutes."""
     pkgs = [a["package"] for a in apps if a.get("art_pending")]
     gids = [t["id"] for t in titles if t.get("art_pending")]
+    with _backfill_lock:
+        if not (pkgs or gids) or _backfill["running"] or time.time() - _backfill["last"] < 300:
+            return False
+        _backfill.update(running=True, last=time.time())
+
     def run():
         try:
             frame_android.shortcut_tool("list")  # Steam isn't up: try again on a later listing
@@ -307,57 +282,124 @@ def backfill_art(apps=(), titles=(), meant=None):
         finally:
             with _backfill_lock:
                 _backfill["running"] = False
-    # Listing callers hold working() until this counted worker is registered.
-    # Other callers may supply the identity captured with their listing.
-    with working(meant):
-        with _backfill_lock:
-            if not (pkgs or gids) or _backfill["running"] or time.time() - _backfill["last"] < 300:
-                return False
-            previous = dict(_backfill)
-            _backfill.update(running=True, last=time.time())
-        try:
-            busy_thread(run).start()
-        except Exception:
-            with _backfill_lock:
-                _backfill.update(previous)
-            raise
+    threading.Thread(target=run, daemon=True).start()
     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])
@@ -373,26 +415,22 @@ def ensure_master():
         LINK.ensure()
 
 
-def ssh(remote, *, stdin=None, timeout=30, text=True, route=None):
-    # Long-lived helper delivery/cleanup owns an immutable command prefix. It
-    # must not reconnect through the currently selected headset after a switch.
-    route_gen = LINK.gen if LINK and route is None else None
-    alias = route[-1] if route is not None else FRAME
+def ssh(remote, *, stdin=None, timeout=30, text=True):
+    route_gen = LINK.gen if LINK else None  # which headset this command is for
     try:
-        if route is None:
-            ensure_master()
+        ensure_master()
         # Never let ssh inherit our stdin: under the app it's the pipe held open for
         # --exit-on-eof, and Windows' ssh.exe waits on it forever.
         feed = {"input": stdin} if stdin is not None else {"stdin": subprocess.DEVNULL}
-        r = frame_host.run_ssh([*(route if route is not None else [*SSH, FRAME]), remote], capture_output=True, **feed,
+        r = frame_host.run_ssh([*SSH, FRAME, remote], capture_output=True, **feed,
                                text=text, errors="replace" if text else None, timeout=timeout)
     except subprocess.TimeoutExpired:
-        raise frame_host.link_failure(Failure(f"Timed out talking to {alias}"))
+        raise frame_host.link_failure(Failure(f"Timed out talking to {FRAME}"))
     if r.returncode != 0:
         err = (r.stderr or r.stdout) if text else (r.stderr or r.stdout).decode(errors="replace")
         if r.returncode == 255 and repair_ssh_config(err):
-            return ssh(remote, stdin=stdin, timeout=timeout, text=text, route=route)
-        if r.returncode == 255 and LINK and route is None and unreachable(err):
+            return ssh(remote, stdin=stdin, timeout=timeout, text=text)
+        if r.returncode == 255 and LINK and unreachable(err):
             LINK.lost(err, route_gen)  # ssh itself failed: the connector reconnects
         failure = Failure(strip_ansi(err).strip() or f"ssh exited {r.returncode}")
         failure.stdout = r.stdout if text else r.stdout.decode(errors="replace")
@@ -911,18 +949,6 @@ class InputAgent:
         self.packages = kdeconnect_packages() if packages is None else packages
         # generation counts stop()s; launching is the generation a launch is under way for.
         self.status, self.launching, self.generation = {"state": "off"}, None, 0
-        # Each launch thread retains its owner through delivery, retry and late
-        # cleanup, even when a new generation starts concurrently.
-        self._launch_local = threading.local()
-
-    def delivery_ssh(self, command, **kwargs):
-        context = getattr(self._launch_local, "context", None)
-        if context:
-            with self.lock:
-                if self.generation != context[0]:
-                    raise Failure("stopped")
-            return ssh(command, route=context[1], **kwargs)
-        return ssh(command, **kwargs)
 
     def command(self, folder=""):
         code = base64.b64encode(self.source.read_bytes()).decode()
@@ -945,14 +971,14 @@ class InputAgent:
             return ""  # nothing to copy (the agent says so if it needed them)
         if not force:
             # Bytes, so Windows doesn't turn the stamp's line ends into CRLF.
-            have = self.delivery_ssh(f"{{ test -x /usr/lib/kdeconnectd || cmp -s - {KDECONNECT_HOME}/root/.frame-control-packages; }}"
+            have = ssh(f"{{ test -x /usr/lib/kdeconnectd || cmp -s - {KDECONNECT_HOME}/root/.frame-control-packages; }}"
                        " && echo yes || true", stdin=kdeconnect_stamp(self.packages).encode(), text=False, timeout=20)
             if have.strip() == b"yes":
                 return ""
         # A folder of its own: a cancelled start's agent may still be cleaning up another.
         folder = f"{KDECONNECT_HOME}/incoming/{secrets.token_hex(8)}"
+        ssh(f"mkdir -p {folder}", timeout=20)
         try:
-            self.delivery_ssh(f"mkdir -p {folder}", timeout=20)
             for name, sha in self.packages:
                 path = KDECONNECT / "packages" / name
                 if not path.is_file() or file_sha256(path) != sha:
@@ -960,7 +986,7 @@ class InputAgent:
                                   " (a build runs app/build/fetch-deps.js to add it)", 500)
                 report(f"Copying KDE Connect to the Frame ({name.rsplit('-', 3)[0]})")
                 quoted = shlex.quote(name)
-                self.delivery_ssh(f"cd {folder} && cat > {quoted}.part && mv {quoted}.part {quoted}",
+                ssh(f"cd {folder} && cat > {quoted}.part && mv {quoted}.part {quoted}",
                     stdin=path.read_bytes(), text=False, timeout=600)
         except (Failure, OSError):
             self.discard(folder)  # a partial copy is no use to anyone
@@ -972,35 +998,18 @@ class InputAgent:
         folder = folder.removeprefix("~/")
         if folder.startswith(f"{KDECONNECT_HOME}/incoming/") and not LOCAL:
             try:
-                context = getattr(self._launch_local, "context", None)
-                ssh(f"rm -rf {folder}", timeout=20, **({"route": context[1]} if context else {}))
+                ssh(f"rm -rf {folder}", timeout=20)
             except (Failure, OSError):
                 pass  # never let tidying up get in the way of reporting and retrying
 
     def start(self):
-        with _route_lock, self.lock:
+        with self.lock:
             if self.launching == self.generation or (self.proc and self.proc.poll() is None):
                 return
             # (A launch from before a stop() may still be finishing; it ends itself.)
             self.launching, self.status = self.generation, {"state": "starting"}
             generation = self.generation
-            route = tuple([*SSH, FRAME])
-
-        def run():
-            self._launch_local.context = (generation, route)
-            try:
-                self._launch(generation)
-            finally:
-                del self._launch_local.context
-        try:
-            threading.Thread(target=run, daemon=True).start()
-        except Exception:
-            with self.lock:
-                if self.launching == generation:
-                    self.launching = None
-                if self.generation == generation:
-                    self.status = {"state": "error", "message": "Couldn't start the input worker"}
-            raise
+        threading.Thread(target=self._launch, args=(generation,), daemon=True).start()
 
     def _launch(self, generation, force=False):
         try:
@@ -1013,43 +1022,22 @@ class InputAgent:
                     self.status = {"state": "error", "message": f"Couldn't start the keyboard and trackpad: {e}"}
 
     def _launch_once(self, generation, force):
-        previous = getattr(self._launch_local, "context", None)
-        if previous is None:  # direct synchronous callers, including offline probes
-            with _route_lock, self.lock:
-                self._launch_local.context = (generation, tuple([*SSH, FRAME]))
-        try:
-            self._launch_routed(generation, force, self._launch_local.context[1])
-        finally:
-            if previous is None:
-                del self._launch_local.context
-
-    def _launch_routed(self, generation, force, route):
         def report(message):
             with self.lock:
                 if self.generation == generation:
                     self.status = {"state": "installing", "message": message}
         folder = ""
-        errors = None
         try:
             errors = tempfile.TemporaryFile()
-            with self.lock:
-                if self.generation != generation:
-                    raise Failure("stopped")
             ensure_master()
-            with self.lock:
-                if self.generation != generation:
-                    raise Failure("stopped")
             folder = self.deliver(report, force)
             with self.lock:
                 stopped = self.generation != generation
-                command = [*route, self.command(folder)] if not stopped else None
             if stopped:  # turned off while copying
                 raise Failure("stopped")
-            proc = subprocess.Popen(command, stdin=subprocess.PIPE,
+            proc = subprocess.Popen([*SSH, FRAME, self.command(folder)], stdin=subprocess.PIPE,
                                     stdout=subprocess.PIPE, stderr=errors)
         except (Failure, OSError) as e:
-            if errors is not None:
-                errors.close()
             self.discard(folder)  # no agent will take the copy over
             message = str(e)
             friendly = unreachable(message)
@@ -1068,11 +1056,8 @@ class InputAgent:
             if not stale:
                 self.proc = proc
         if stale:  # turned off meanwhile
-            self.close(proc)
-        try:
-            wanted, heard = self._watch(proc, errors, retry=not force)
-        finally:
-            errors.close()
+            proc.terminate()
+        wanted, heard = self._watch(proc, errors, retry=not force)
         if not heard:
             # The agent never started (or was stopped first), so it can't tidy the copy up.
             self.discard(folder)
@@ -1126,35 +1111,29 @@ class InputAgent:
         Returns the state, with "sent" saying whether the events went; if not,
         the page keeps them and sends them again once the state is "ready".
         """
-        with self.write_lock:
-            with self.lock:
-                proc, ready = self.proc, self.status.get("state") == "ready"
-            sent = False
-            start = not (proc and proc.poll() is None)
-            if not start and ready and events:
-                try:
+        with self.lock:
+            proc, ready = self.proc, self.status.get("state") == "ready"
+        sent = False
+        if not (proc and proc.poll() is None):
+            self.start()
+        elif ready and events:
+            try:
+                # One writer at a time: two devices sending at once mustn't tear a line.
+                with self.write_lock:
                     proc.stdin.write((json.dumps(events) + "\n").encode())
                     proc.stdin.flush()
-                    sent = True
-                except (BrokenPipeError, OSError, ValueError):
-                    pass  # _watch reports how it ended
-        # start() captures the route under _route_lock. Never acquire that lock
-        # under write_lock: route() takes them in the opposite order to stop us.
-        if start:
-            self.start()
+                sent = True
+            except (BrokenPipeError, OSError, ValueError):
+                pass  # _watch reports how it ended
         with self.lock:
             return {**self.status, "sent": sent}
 
     def stop(self):
-        with self.write_lock:
-            with self.lock:
-                proc, self.proc, self.status = self.proc, None, {"state": "off"}
-                self.generation += 1
-            if proc and proc.poll() is None:
-                self.close(proc)
-
-    def close(self, proc):
-        proc.terminate()
+        with self.lock:
+            proc, self.proc, self.status = self.proc, None, {"state": "off"}
+            self.generation += 1
+        if proc and proc.poll() is None:
+            proc.terminate()
 
 
 _input = InputAgent()
@@ -1271,14 +1250,6 @@ class TouchAgent(InputAgent):
     def __init__(self):
         super().__init__(source=HERE / "frame_touch.py", packages=[])
 
-    def close(self, proc):
-        # EOF lets the helper release held keys/buttons in finally, including
-        # when a start was invalidated while Popen was still returning.
-        try:
-            proc.stdin.close()
-        except (BrokenPipeError, OSError, ValueError):
-            proc.terminate()
-
     def deliver(self, report, force=False):
         return ""
 
@@ -1407,7 +1378,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)
@@ -1441,6 +1412,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"}
@@ -2285,19 +2399,26 @@ def source_text(body, key, optional=False):
     return value.strip()
 
 
+def login_text(body, key):
+    """A username, password or token: kept exactly (no stripping) and never echoed back."""
+    value = body.get(key)
+    if value in (None, ''):
+        return None
+    if not isinstance(value, str) or len(value) > 4096:
+        raise Failure('Provide a valid ' + key, 400)
+    return value
+
+
 def source_search(query):
     args = parse_qs(query)
     q = args.get('q', [''])[0]
     vr = args.get('vr', [''])[0]
     installable = args.get('installable', [''])[0]
-    category, phone = args.get('category', [''])[0], args.get('phone', [''])[0]
-    if (len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0')
-            or phone not in ('', 'true', 'false', '1', '0') or len(category) > 40):
+    if len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0'):
         raise Failure('Invalid search filters', 400)
     try:
         return apk_search.search(q, vr=None if not vr else vr in ('true', '1'),
-                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'),
-                                 category=category or None, phone=phone in ('true', '1'))
+                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'))
     except SourceError as e:
         raise Failure(str(e), 400)
 
@@ -2313,7 +2434,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):
@@ -2326,19 +2447,31 @@ def source_manage(body):
         if action == 'add':
             url = source_text(body, 'url')
             fingerprint, name = source_text(body, 'fingerprint', True), source_text(body, 'name', True)
-            parts = urlparse(url)
-            if parts.scheme not in ('https', 'fdroidrepos') or not parts.hostname or parts.username:
-                raise Failure('Use an HTTPS or fdroidrepos:// repository URL without credentials', 400)
+            username, password = login_text(body, 'username'), login_text(body, 'password')
+            try:
+                parts = urlparse(url)
+                parts.port
+            except ValueError:
+                raise Failure('Use an HTTPS or fdroidrepos:// repository URL', 400) from None
+            if parts.scheme not in ('https', 'fdroidrepos') or not parts.hostname:
+                raise Failure('Use an HTTPS or fdroidrepos:// repository URL', 400)
             apk_search.repo_module()  # fail now if this build can't manage repositories
 
             def add():  # downloads and verifies the whole index: a job, not a request
-                source = apk_search.manage_repo('add_repo', url=url, fingerprint=fingerprint, name=name)
+                # A login (here or in the URL) is stored apart and never comes back in a response.
+                login = {'username': username, 'password': password} if username or password else {}
+                source = apk_search.manage_repo('add_repo', url=url, fingerprint=fingerprint, name=name, **login)
                 message = 'Added ' + source['name']
                 if source.get('trust_on_first_use'):
                     message += '. Trusted on first use: ' + source['fingerprint'].upper()
                 return {'message': message, 'source': {k: source.get(k) for k in
                                                        ('id', 'name', 'fingerprint', 'trust_on_first_use')}}
             return start_job('Add repository', add)
+        if action in ('set-token', 'clear-token'):
+            token = login_text(body, 'token') if action == 'set-token' else None
+            if action == 'set-token' and not token:
+                raise Failure('Paste a token', 400)
+            return apk_search.set_token(source_text(body, 'source'), token)
         if action == 'game-data':
             package = source_text(body, 'package')
             return start_job('Add game data', lambda: apk_search.add_game_data(package))
@@ -2356,7 +2489,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,
@@ -2529,9 +2662,6 @@ class Handler(BaseHTTPRequestHandler):
         try:
             if path in ("/", "/index.html"):
                 self.send_bytes((HERE / "index.html").read_bytes(), "text/html; charset=utf-8")
-            elif path == "/store":
-                # The Android store as a headset panel (scripts/store-on-frame.sh).
-                self.send_bytes((HERE / "store.html").read_bytes(), "text/html; charset=utf-8")
             elif path == "/api/settings/artwork":
                 self.send_json(frame_steamgriddb.settings())
             elif path == "/artwork-settings.js":
@@ -2578,21 +2708,18 @@ class Handler(BaseHTTPRequestHandler):
             elif path == "/api/apk-versions":
                 self.send_json(apk_versions(url.query))
             elif path == "/api/android":
-                with working():
-                    ensure_master()
-                    apps = frame_android.list_apps()
-                    backfill_art(apps=apps)
-                try:  # store artwork for the library's cards, from saved indexes only
-                    art = apk_search.artwork_for(apps)
-                except Exception:
-                    art = {}
-                self.send_json({"apps": [dict(a, store_art=art[a['package']]) if a.get('package') in art else a
-                                         for a in apps]})
+                ensure_master()
+                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":
-                with working():
-                    ensure_master()
-                    titles_list = frame_titles.list_titles()
-                    backfill_art(titles=titles_list)
+                ensure_master()
+                titles_list = frame_titles.list_titles()
+                backfill_art(titles=titles_list)
                 self.send_json({"titles": titles_list})
             elif path == "/api/titles/job":
                 self.send_json(title_job(url.query))
@@ -2600,21 +2727,14 @@ class Handler(BaseHTTPRequestHandler):
                 self.send_json({"notices": licenses()})
             elif path == "/api/panels":
                 self.send_json(panels())
-            elif path in ("/api/touch", "/api/input"):
-                agent = _touch if path == "/api/touch" else _input
-                if parse_qs(url.query).get("start") == ["1"]:
-                    # Validate and reserve before start() captures its immutable
-                    # route and schedules a worker. Status-only polls stay free.
-                    meant = self.headers.get("X-Frame-Device")
-                    if LINK and not meant:
-                        raise Failure("Control start needs the intended X-Frame-Device headset", 400)
-                    with working(meant):
-                        result = agent.send([])
-                else:
-                    result = dict(agent.status)
-                self.send_json(result)
+            elif path == "/api/touch":
+                self.send_json(_touch.send([]) if parse_qs(url.query).get("start") == ["1"] else dict(_touch.status))
+            elif path == "/api/input":
+                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":

ui/store.html

@@ -1,558 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>APK Store</title>
-<!-- Frame Control's Android store as a panel in the headset (docs/apks.md →
-     "The store in the headset"). Served by ui/server.py running on the Frame
-     (FRAME_LOCAL=1), opened by scripts/store-on-frame.sh at 1280×800. The same
-     sources, categories and artwork as the Store in Frame Control (/api/search,
-     ui/apk_sources/_categories.py), drawn for the laser: big targets, pages
-     instead of drag-scrolling (the panel gets mouse clicks, so a drag would
-     select text), the thumbstick (a mouse wheel) turns pages, and an on-screen
-     keyboard for search. -->
-<style>
-  :root {
-    --bg: #0f1722; --rail: #131d2a; --card: #1b2938; --card-hi: #23364a; --line: #ffffff14;
-    --text: #e3e8ee; --bright: #fff; --dim: #93a4ba; --blue: #1a9fff; --link: #66c0f4;
-    --good: #8ed36b; --bad: #ef7a64;
-    --action: linear-gradient(to right, #47bfff 5%, #1a44c2 95%);
-    --play: linear-gradient(to right, #75b022 5%, #588a1b 95%);
-  }
-  * { box-sizing: border-box; }
-  [hidden] { display: none !important; }
-  html, body { margin: 0; height: 100%; background: radial-gradient(ellipse at 70% -20%, #1d3a5a 0%, transparent 60%), var(--bg);
-    color: var(--text); font: 19px/1.35 "Motiva Sans", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-    overflow: hidden; user-select: none; -webkit-user-select: none; }
-  button { font: inherit; color: inherit; background: #ffffff0d; border: 1px solid var(--line); border-radius: 12px;
-    min-height: 52px; padding: 0 20px; cursor: pointer; }
-  button:hover { background: #ffffff1c; }
-  button:disabled { opacity: .45; cursor: default; }
-  :focus-visible { outline: 3px solid var(--link); outline-offset: 3px; }
-  button.primary { background: var(--action); border: 0; font-weight: 600; color: #fff; }
-  button.play { background: var(--play); border: 0; font-weight: 600; color: #fff; }
-  button.danger { color: var(--bad); }
-  svg { width: 22px; height: 22px; flex: none; }
-  .app { display: grid; grid-template-columns: 236px 1fr; height: 100%; }
-  /* Rail */
-  .rail { background: #0c131ccc; border-right: 1px solid var(--line); padding: 18px 12px; display: flex; flex-direction: column; gap: 3px; }
-  .rail h1 { font-size: 22px; margin: 2px 10px 12px; display: flex; align-items: center; gap: 10px; color: var(--bright); }
-  .rail h1 svg { width: 28px; height: 28px; color: var(--blue); }
-  .rail button { display: flex; align-items: center; gap: 12px; width: 100%; min-height: 47px; text-align: left; border: 0;
-    background: transparent; color: #b5c0cb; font-size: 17px; font-weight: 500; padding: 0 12px; border-radius: 10px; }
-  .rail button:hover { background: #ffffff10; color: var(--bright); }
-  .rail button[aria-pressed="true"] { background: #1a9fff2e; color: var(--bright); box-shadow: inset 4px 0 0 var(--blue); }
-  .rail .sep { height: 1px; background: var(--line); margin: 6px 8px; }
-  .rail .n { margin-left: auto; font-size: 13px; color: #c6e2f5; background: #1a9fff2e; border-radius: 10px; padding: 1px 8px; }
-  .rail .n:empty { display: none; }
-  .rail label { margin-top: auto; display: flex; align-items: center; gap: 10px; padding: 10px 12px; font-size: 15px; color: var(--dim); cursor: pointer; }
-  .rail input { width: 22px; height: 22px; accent-color: var(--blue); margin: 0; }
-  /* Main */
-  main { display: flex; flex-direction: column; min-width: 0; padding: 18px 22px; gap: 12px; }
-  .bar { display: flex; gap: 12px; align-items: center; }
-  .search { flex: 1; display: flex; align-items: center; gap: 12px; background: #0c1520; border: 1px solid var(--line);
-    border-radius: 12px; min-height: 54px; padding: 0 18px; color: var(--dim); }
-  .search input { flex: 1; background: none; border: 0; color: var(--text); font: inherit; outline: none; min-width: 0; }
-  .search input::placeholder { color: var(--dim); }
-  .heading { display: flex; align-items: baseline; gap: 14px; min-height: 30px; }
-  .heading b { color: var(--bright); font-size: 25px; letter-spacing: -.4px; }
-  .heading span { color: var(--dim); font-size: 16px; }
-  .heading .note { margin-left: auto; font-size: 14px; color: var(--dim); max-width: 520px; text-align: right; }
-  .content { flex: 1; min-height: 0; display: flex; flex-direction: column; gap: 14px; }
-  .installed-status { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 10px 16px;
-    border: 1px solid var(--line); border-radius: 12px; background: #ffffff0a; font-size: 16px; }
-  .installed-status button { flex: none; }
-  .grid { flex: 1; min-height: 0; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); grid-template-rows: repeat(2, minmax(0, 1fr)); gap: 14px; }
-  .grid.one-row { grid-template-rows: minmax(0, 1fr); }
-  .card { display: flex; flex-direction: column; padding: 0; overflow: hidden; text-align: left; min-height: 0; border-radius: 14px;
-    background: var(--card); border: 1px solid var(--line); }
-  .card:hover { background: var(--card-hi); border-color: #66c0f480; }
-  .card .art { flex: 0 0 52%; }
-  .card .body { display: flex; flex-direction: column; gap: 6px; padding: 10px 12px 12px; min-height: 0; flex: 1; width: 100%; }
-  .card .title { display: flex; align-items: center; gap: 10px; min-width: 0; }
-  .card .title strong { font-size: 17px; color: var(--bright); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
-  .card .sum { color: var(--dim); font-size: 14px; line-height: 1.35; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
-  .card .foot { margin-top: auto; display: flex; justify-content: space-between; align-items: center; gap: 6px; font-size: 13px; color: var(--dim); }
-  /* Artwork: a banner, else screenshots side by side, else the icon over its own blur, else an initial. */
-  .art { position: relative; display: block; overflow: hidden; width: 100%;
-    background: radial-gradient(ellipse at 75% 10%, hsl(var(--hue) 50% 40%), transparent 70%), linear-gradient(140deg, hsl(var(--hue) 35% 18%), #101827); }
-  .art > img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
-  .art .initial { position: absolute; inset: 0; display: grid; place-items: center; font-size: 64px; font-weight: 700; color: #ffffff45; }
-  .art.shots { display: flex; gap: 6px; justify-content: center; padding: 8px 8px 0; }
-  .art.shots > img { position: relative; inset: auto; width: auto; max-width: 31%; height: 100%; object-position: top; border-radius: 6px 6px 0 0; box-shadow: 0 4px 14px #0008; }
-  .art.iconart > .backdrop { position: absolute; inset: -30%; width: 160%; height: 160%; object-fit: cover; filter: blur(28px) saturate(1.4) brightness(.55); }
-  .art.iconart > .mark { position: absolute; left: 50%; top: 50%; width: 36%; height: auto; aspect-ratio: 1; transform: translate(-50%, -50%); border-radius: 22%; box-shadow: 0 8px 24px #0009; object-fit: cover; }
-  .art.shots .initial, .art.iconart .initial { display: none; }
-  .art .vr { position: absolute; z-index: 2; top: 8px; left: 8px; }
-  .icon { position: relative; display: inline-grid; place-items: center; width: 38px; height: 38px; border-radius: 9px; overflow: hidden; flex: none;
-    background: hsl(var(--hue) 35% 28%); color: #fff; font-size: 18px; font-weight: 600; }
-  .icon img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
-  .vr { font-size: 12px; font-weight: 700; letter-spacing: .8px; color: #0e141b; background: #c2e7ff; border-radius: 5px; padding: 2px 7px; }
-  .fit { font-size: 12px; font-weight: 600; border-radius: 5px; padding: 2px 8px; white-space: nowrap; }
-  .fit.works { color: #c3efb2; background: #59bf4029; } .fit.ready { color: #bfe3fa; background: #1a9fff26; } .fit.blocked { color: #f3b2a6; background: #d9412629; }
-  .tag { font-size: 12px; font-weight: 600; color: #d6f5c8; background: #2d5a1f; border-radius: 10px; padding: 2px 9px; white-space: nowrap; }
-  /* Home */
-  .hero { position: relative; flex: 0 0 42%; padding: 0; border: 0; border-radius: 16px; overflow: hidden; text-align: left; isolation: isolate; }
-  .hero .art { position: absolute; inset: 0; height: 100%; }
-  .hero::after { content: ""; position: absolute; inset: 0; z-index: 1; background: linear-gradient(90deg, #081421f0 0%, #08142180 50%, #08142100 85%); }
-  .hero .copy { position: relative; z-index: 2; padding: 26px 30px; max-width: 560px; display: flex; flex-direction: column; gap: 10px; align-items: flex-start; }
-  .hero .eyebrow { display: flex; gap: 10px; align-items: center; font-size: 13px; font-weight: 700; letter-spacing: 1.6px; text-transform: uppercase; color: #c2e7ff; }
-  .hero strong { font-size: 38px; color: #fff; line-height: 1.05; letter-spacing: -.8px; }
-  .hero .blurb { color: #e0e8ef; font-size: 17px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
-  .hero .cta { margin-top: 4px; background: #ffffff22; border: 1px solid #ffffff44; border-radius: 10px; padding: 9px 18px; font-size: 16px; color: #fff; }
-  /* Pager */
-  .pager { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
-  .pager button { min-width: 180px; }
-  .dots { display: flex; gap: 8px; align-items: center; color: var(--dim); font-size: 15px; }
-  .empty { grid-column: 1 / -1; grid-row: 1 / -1; display: grid; place-items: center; align-content: center; gap: 14px; color: var(--dim); text-align: center; padding: 30px; }
-  .empty h2 { margin: 0; color: var(--bright); font-size: 24px; }
-  .skeleton { border-radius: 14px; background: linear-gradient(100deg, #1b2938 30%, #24364a 50%, #1b2938 70%); background-size: 300% 100%; animation: shimmer 1.4s infinite; }
-  @keyframes shimmer { to { background-position: -150% 0; } }
-  /* Detail sheet and keyboard sit over everything. */
-  .overlay { position: fixed; inset: 0; background: transparent; color: inherit; display: grid; place-items: center; z-index: 10;
-    margin: 0; border: 0; padding: 0; width: 100%; height: 100%; max-width: none; max-height: none; }
-  .overlay::backdrop { background: #000b; }
-  .sheet { background: #16212e; border: 1px solid var(--line); border-radius: 22px; width: 1000px; max-height: 740px; overflow: hidden;
-    display: flex; flex-direction: column; box-shadow: 0 30px 80px #000c; }
-  .sheet > .art { flex: 0 0 250px; }
-  .sheet .gallery { flex: 0 0 250px; display: flex; gap: 10px; padding: 14px 14px 0; background: #0c131c; justify-content: center; overflow: hidden; }
-  .sheet .gallery img { height: 100%; width: auto; max-width: 32%; object-fit: cover; object-position: top; border-radius: 10px 10px 0 0; }
-  .sheet .inner { padding: 20px 28px 22px; display: flex; flex-direction: column; gap: 12px; flex: 1; min-height: 0; }
-  .sheet .top { display: flex; gap: 18px; align-items: center; }
-  .sheet .top .icon { width: 72px; height: 72px; border-radius: 16px; font-size: 32px; }
-  .sheet h2 { margin: 0; font-size: 30px; color: var(--bright); line-height: 1.1; }
-  .sheet .meta { color: var(--dim); font-size: 16px; }
-  .sheet .text { font-size: 17px; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
-  .sheet .why { background: #ffffff0a; border-radius: 12px; padding: 10px 16px; font-size: 15px; color: #c5d0db; }
-  .sheet .why ul { margin: 4px 0 0; padding-left: 22px; }
-  .sheet .acts { display: flex; gap: 12px; flex-wrap: wrap; margin-top: 8px; align-items: center; }
-  .sheet .acts .close { margin-left: auto; }
-  .progress { flex: 1; min-width: 260px; display: flex; flex-direction: column; gap: 6px; font-size: 15px; color: var(--dim); }
-  .progress .track { height: 8px; border-radius: 4px; background: #ffffff14; overflow: hidden; }
-  .progress .fill { height: 100%; background: var(--blue); width: 30%; transition: width .3s; }
-  .progress.busy .fill { animation: busy 1.2s ease-in-out infinite; }
-  @keyframes busy { from { margin-left: -30%; } to { margin-left: 100%; } }
-  .kbd { position: fixed; left: 0; right: 0; bottom: 0; background: #131d2af5; border-top: 1px solid var(--line);
-    padding: 12px; display: grid; gap: 8px; z-index: 20; box-shadow: 0 -20px 50px #0009; }
-  .kbd .row { display: flex; gap: 8px; justify-content: center; }
-  .kbd button { min-width: 76px; min-height: 60px; padding: 0 10px; font-size: 21px; }
-  .kbd .wide { min-width: 320px; }
-  .toast { position: fixed; left: 50%; top: 18px; transform: translateX(-50%); background: #0d2236; border: 1px solid var(--blue);
-    border-radius: 14px; padding: 12px 20px; z-index: 30; max-width: 900px; box-shadow: 0 10px 30px #0008; }
-  .toast.bad { background: #3a1416; border-color: var(--bad); }
-</style>
-</head>
-<body>
-<div class="app">
-  <div class="rail" role="navigation" aria-label="Store">
-    <h1><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="M4 7h16l-1.5 12.5a1 1 0 0 1-1 .9H6.5a1 1 0 0 1-1-.9z"/><path d="M8.5 9V6a3.5 3.5 0 0 1 7 0v3"/></svg>APK Store</h1>
-    <div id="cats"></div>
-    <div class="sep"></div>
-    <button data-view="installed" aria-pressed="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true"><rect x="3.5" y="4" width="7" height="7" rx="1.5"/><rect x="13.5" y="4" width="7" height="7" rx="1.5"/><rect x="3.5" y="14" width="7" height="7" rx="1.5"/><rect x="13.5" y="14" width="7" height="7" rx="1.5"/></svg>Installed<span class="n" id="instN"></span></button>
-    <label title="Apps built around a phone: calls and SMS, launchers, keyboards, widgets, fitness, system tools. Searching always finds them."><input type="checkbox" id="phone"> Show phone-only apps</label>
-  </div>
-  <main>
-    <div class="bar">
-      <label class="search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/></svg><input id="q" placeholder="Search games and apps" autocomplete="off" spellcheck="false" aria-label="Search games and apps"></label>
-      <button id="kbdBtn" title="On-screen keyboard">⌨︎ Keyboard</button>
-    </div>
-    <div class="heading"><b id="title">Home</b><span id="count"></span><span class="note" id="note"></span></div>
-    <div class="content" id="content"></div>
-    <div class="pager">
-      <button id="prev">◀ Previous</button>
-      <span class="dots" id="page"></span>
-      <button id="next">Next ▶</button>
-    </div>
-  </main>
-</div>
-
-<dialog class="overlay" id="detail" aria-labelledby="detailTitle" hidden><div class="sheet" id="sheet"></div></dialog>
-<div class="kbd" id="kbd" hidden></div>
-<div class="toast" id="toast" hidden></div>
-
-<script>
-const UI_KEY = new URLSearchParams(location.search).get("key") || "1";
-const $ = id => document.getElementById(id);
-const esc = s => String(s ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
-const PER_PAGE = 8;
-// Same ids and order as STORE_CATS in index.html and ui/apk_sources/_categories.py.
-const CATS = [
-  ["", "Home", '<path d="M4 11.5 12 5l8 6.5V19a1 1 0 0 1-1 1h-4.5v-5h-5v5H5a1 1 0 0 1-1-1z"/>'],
-  ["vr", "VR", '<path d="M3.5 8.5A1.5 1.5 0 0 1 5 7h14a1.5 1.5 0 0 1 1.5 1.5v6A1.5 1.5 0 0 1 19 16h-3.5l-2-2.5h-3l-2 2.5H5a1.5 1.5 0 0 1-1.5-1.5z"/><circle cx="8" cy="11.5" r="1.5"/><circle cx="16" cy="11.5" r="1.5"/>'],
-  ["games", "Games", '<path d="M7 9h10a4 4 0 0 1 3.9 4.9l-.6 2.6a2 2 0 0 1-3.4.9L14.5 15h-5l-2.4 2.4a2 2 0 0 1-3.4-.9l-.6-2.6A4 4 0 0 1 7 9z"/><path d="M8 11.5v3M6.5 13h3"/>'],
-  ["emulators", "Emulators", '<rect x="4" y="5" width="16" height="11" rx="1.5"/><path d="M9 20h6M12 16v4M8 10.5h3M9.5 9v3"/>'],
-  ["watch", "Watch & listen", '<rect x="3.5" y="5.5" width="17" height="11" rx="1.5"/><path d="m10.5 8.5 4 2.5-4 2.5z"/><path d="M8 20h8"/>'],
-  ["read", "Read & learn", '<path d="M12 7c-2-1.5-5-2-8-1.5v12c3-.5 6 0 8 1.5 2-1.5 5-2 8-1.5v-12c-3-.5-6 0-8 1.5zM12 7v12"/>'],
-  ["create", "Create", '<path d="m14.5 5.5 4 4L9 19H5v-4z"/><path d="m12.5 7.5 4 4"/>'],
-  ["work", "Work", '<rect x="4" y="7" width="16" height="12" rx="1.5"/><path d="M9 7V5.5A1.5 1.5 0 0 1 10.5 4h3A1.5 1.5 0 0 1 15 5.5V7M4 12h16"/>'],
-  ["web", "Web & chat", '<circle cx="12" cy="12" r="8"/><path d="M4 12h16M12 4c2.5 2.5 2.5 13.5 0 16M12 4c-2.5 2.5-2.5 13.5 0 16"/>'],
-  ["tools", "Tools", '<path d="M14.5 6.5a4 4 0 0 0-5.3 5.3L4.5 16.5l3 3 4.7-4.7a4 4 0 0 0 5.3-5.3l-2.4 2.4-2.6-.4-.4-2.6z"/>'],
-];
-const catLabel = id => (CATS.find(c => c[0] === id) || [])[1] || "";
-const FIT = { works: "Works on the Frame", ready: "Fits the Frame", blocked: "Won't run" };
-// view: "" (home), a category id, or "installed"; jobs: offer key -> {stage, percent, done, result, error}
-// installedFrom: offer key -> package it installed as (GitHub listings have no package);
-// needsData: installed packages still waiting for their game data (any view, while installed)
-const st = { view: "", q: "", phone: false, page: 0, apps: [], installed: new Map(), jobs: new Map(), installedFrom: new Map(),
-             needsData: new Set(), installedState: "unknown", installedError: "", installedRequest: 0,
-             request: 0, loading: false, retry: 0 };
-
-async function api(path, body) {
-  const opts = body === undefined ? { headers: { "X-Frame-UI": UI_KEY } } : {
-    method: "POST", headers: { "Content-Type": "application/json", "X-Frame-UI": UI_KEY }, body: JSON.stringify(body) };
-  const r = await fetch(path, opts);
-  const j = await r.json().catch(() => ({}));
-  if (!r.ok) throw new Error(j.error || `HTTP ${r.status}`);
-  return j;
-}
-let toastTimer;
-function toast(msg, bad = false) {
-  const t = $("toast");
-  t.textContent = msg; t.className = "toast" + (bad ? " bad" : ""); t.hidden = false;
-  clearTimeout(toastTimer); toastTimer = setTimeout(() => t.hidden = true, bad ? 8000 : 4500);
-}
-
-// ---- Artwork (only the server's /source-image/ handles are ever used as an image) ----
-const hue = name => [...String(name)].reduce((n, c) => (n * 31 + c.charCodeAt(0)) >>> 0, 7) % 360;
-const initial = name => [...String(name || "?")][0].toUpperCase();
-const valid = u => /^\/source-image\/[\w-]+$/.test(u || "");
-const img = (u, cls = "") => valid(u) ? `<img${cls ? ` class="${cls}"` : ""} src="${esc(u)}" alt="" decoding="async">` : "";
-function art(name, a = {}, extra = "") {
-  const base = `style="--hue:${hue(name)}"`, ini = `<span class="initial" aria-hidden="true">${esc(initial(name))}</span>`;
-  if (valid(a.banner)) return `<span class="art" ${base}>${ini}${img(a.banner)}${extra}</span>`;
-  const shots = (a.screenshots || []).filter(valid).slice(0, 3);
-  if (shots.length) return `<span class="art shots" ${base}>${ini}${shots.map(u => img(u)).join("")}${extra}</span>`;
-  if (valid(a.icon)) return `<span class="art iconart" ${base}>${ini}${img(a.icon, "backdrop")}${img(a.icon, "mark")}${extra}</span>`;
-  return `<span class="art" ${base}>${ini}${extra}</span>`;
-}
-const icon = (name, a = {}) => `<span class="icon" style="--hue:${hue(name)}" aria-hidden="true">${esc(initial(name))}${img(a.icon)}</span>`;
-document.addEventListener("error", e => {
-  const el = e.target;
-  if (!el.matches?.(".art img, .icon img")) return;
-  if (!el.dataset.retried) { el.dataset.retried = "1"; setTimeout(() => { el.src = el.getAttribute("src").split("?")[0] + "?retry=1"; }, 1500); return; }
-  const box = el.closest(".shots, .iconart"); el.remove();
-  if (box && !box.querySelector("img")) box.classList.remove("shots", "iconart");
-}, true);
-const text = s => String(s || "").replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ");
-
-// ---- Data ----
-async function loadInstalled() {
-  const request = ++st.installedRequest;
-  st.installedState = "loading"; st.installedError = "";
-  $("instN").textContent = "?";
-  render(); if (typeof drawDetail === "function") drawDetail();
-  try {
-    const result = await api("/api/android");
-    if (request !== st.installedRequest) return;
-    if (!Array.isArray(result.apps)) throw new Error("Invalid installed-app response");
-    st.installed = new Map(result.apps.map(a => [a.package, a]));
-    st.installedState = "ready";
-    for (const pkg of st.needsData) if (!st.installed.has(pkg)) { st.needsData.delete(pkg); st.jobs.delete("data:" + pkg); }  // removed
-  } catch (e) {
-    if (request !== st.installedRequest) return;
-    st.installedState = "error"; st.installedError = e.message;
-  }
-  $("instN").textContent = st.installedState === "ready" ? st.installed.size || "" : "?";
-  render(); if (typeof drawDetail === "function") drawDetail();
-}
-async function search(quiet) {
-  const request = ++st.request;
-  clearTimeout(st.retry);
-  if (st.view === "installed") { st.loading = false; st.page = 0; return render(); }  // a pending search is now stale
-  st.loading = !quiet; if (!quiet) render();
-  const params = new URLSearchParams({ q: st.q, category: st.view, phone: String(st.phone) });
-  try {
-    const result = await api("/api/search?" + params);
-    if (request !== st.request) return;
-    st.apps = result.apps; st.loading = false;
-    const loading = result.sources.filter(s => s.status === "loading").map(s => s.name);
-    $("note").textContent = loading.length ? `Still fetching ${loading.join(" and ")}; more apps will appear.` : "";
-    if (loading.length) st.retry = setTimeout(() => request === st.request && search(true), 6000);
-    if (!quiet) st.page = 0;
-    render();
-  } catch (e) {
-    if (request !== st.request) return;
-    st.loading = false; st.apps = []; render(`Couldn't reach the app shelves: ${e.message}`);
-  }
-}
-const offerKey = app => `${app.offers[0].source}:${app.offers[0].id}`;
-// Always the latest state: an Installed card's own copy goes stale after Stop or Remove.
-function installedOf(app) {
-  const pkg = app.installed?.package || app.package || st.installedFrom.get(offerKey(app));
-  return pkg ? st.installed.get(pkg) : undefined;
-}
-
-// ---- Pages ----
-function list() {
-  if (st.view === "installed") {
-    const q = st.q.toLowerCase();
-    return [...st.installed.values()].filter(m => !q || `${m.label} ${m.package}`.toLowerCase().includes(q))
-      .map(m => ({ installed: m, name: m.label || m.package, package: m.package, summary: m.version ? `v${String(m.version).replace(/^v/i, "")}` : "",
-                   offers: [{ name: m.label, artwork: m.store_art || {}, vr: m.vr && !m.flatscreen }] }));
-  }
-  return st.home ? st.home.rest : st.apps;
-}
-function card(app, i) {
-  const o = app.offers[0], m = installedOf(app), job = st.jobs.get(offerKey(app));
-  const state = m ? `<span class="tag">${st.installedState !== "ready" ? "Installed (last read)" : m.running ? "Running" : "Installed"}</span>`
-    : job && !job.done ? `<span class="tag">Installing…</span>`
-    : FIT[o.verdict?.tone] ? `<span class="fit ${o.verdict.tone}">${FIT[o.verdict.tone]}</span>` : "";
-  const kind = o.phone_only ? "Phone app" : catLabel(app.category || o.category) || (m ? (o.vr ? "VR app" : "Android app") : "Android app");
-  return `<button class="card" data-i="${i}" aria-label="${esc(app.name)}">${art(app.name, o.artwork, o.vr ? '<span class="vr">VR</span>' : "")}
-    <span class="body"><span class="title">${icon(app.name, o.artwork)}<strong>${esc(app.name)}</strong></span>
-    <span class="sum">${esc(text(app.summary))}</span><span class="foot"><span>${esc(kind)}</span>${state}</span></span></button>`;
-}
-function render(error) {
-  const home = st.view === "" && !st.q;
-  $("title").textContent = st.q ? `Results for “${st.q}”` : st.view === "installed" ? "Installed" : st.view ? catLabel(st.view) : "Home";
-  document.querySelectorAll("[data-view]").forEach(b => b.setAttribute("aria-pressed", String(b.dataset.view === st.view)));
-  const content = $("content");
-  const cached = st.installed.size > 0;
-  const installedNotice = st.installedState === "ready" ? "" : `<div class="installed-status" role="status"><span>${
-    st.installedState === "error" ? `Couldn't read installed apps: ${esc(st.installedError)}`
-      : st.installedState === "loading" ? "Reading installed apps…" : "Installed apps haven't been read yet."
-  }${cached ? " Showing last known apps; their status may be out of date." : " Installed status is unknown."}</span>${
-    st.installedState === "loading" ? "" : '<button data-retry-installed>Retry installed apps</button>'
-  }</div>`;
-  if (st.loading) {
-    content.innerHTML = installedNotice + `<div class="grid">${Array.from({ length: PER_PAGE }, () => '<div class="skeleton"></div>').join("")}</div>`;
-    $("count").textContent = ""; $("page").textContent = ""; $("prev").disabled = $("next").disabled = true; return;
-  }
-  // Home: a featured VR app and four picks, then pages of one app from each category in turn.
-  st.home = null;
-  if (home && st.apps.length) {
-    const ok = st.apps.filter(a => a.offers[0].verdict?.tone !== "blocked");
-    const heroes = ok.filter(a => a.offers[0].vr && valid(a.offers[0].artwork?.banner));
-    const featured = heroes[Math.floor(Date.now() / 864e5) % (heroes.length || 1)] || ok.find(a => valid(a.offers[0].artwork?.banner));
-    const queues = CATS.slice(1).map(([id]) => ok.filter(a => a.category === id && a !== featured));
-    const mixed = [];
-    for (let i = 0; queues.some(q => q[i]); i++) queues.forEach(q => q[i] && mixed.push(q[i]));
-    st.home = { featured, rest: mixed.slice(0, 4 + 5 * PER_PAGE) };  // six pages of picks; the categories have the rest
-  }
-  const items = list();
-  const first = st.home?.featured ? 4 : PER_PAGE;  // the first home page shares its space with the banner
-  const pages = Math.max(1, items.length <= first ? 1 : 1 + Math.ceil((items.length - first) / PER_PAGE));
-  st.page = Math.min(st.page, pages - 1);
-  const start = st.page === 0 ? 0 : first + (st.page - 1) * PER_PAGE;
-  const shown = items.slice(start, start + (st.page === 0 ? first : PER_PAGE));
-  $("count").textContent = home || (st.view === "installed" && !cached && st.installedState !== "ready") ? ""
-    : `${items.length.toLocaleString()} app${items.length === 1 ? "" : "s"}${st.view === "installed" && st.installedState !== "ready" ? " (last read)" : ""}`;
-  $("page").textContent = `Page ${st.page + 1} of ${pages}`;
-  $("prev").disabled = st.page === 0; $("next").disabled = st.page >= pages - 1;
-  const empty = error ? `<div class="empty"><h2>No connection</h2>${esc(error)}</div>`
-    : st.view === "installed" && st.installedState !== "ready" && !cached ? `<div class="empty"><h2>${st.installedState === "loading" ? "Reading installed apps…" : "Installed apps unavailable"}</h2>Read the installed list before checking what's on your Frame.</div>`
-    : st.view === "installed" && !st.q ? `<div class="empty"><h2>Nothing installed yet</h2>Pick an app in the store and press Install.<button class="primary" data-view="">Browse the store</button></div>`
-    : `<div class="empty"><h2>No apps here</h2>Try another category${st.phone ? "" : ", or show phone-only apps"}.</div>`;
-  let html = installedNotice;
-  if (st.page === 0 && st.home?.featured) {
-    const f = st.home.featured, o = f.offers[0];
-    html += `<button class="hero" data-feature="1" aria-label="${esc(f.name)}">${art(f.name, o.artwork)}<span class="copy">
-      <span class="eyebrow">${o.vr ? '<span class="vr">VR</span>' : ""}Featured</span><strong>${esc(f.name)}</strong>
-      <span class="blurb">${esc(text(f.summary))}</span><span class="cta">See ${esc(f.name)} ›</span></span></button>`;
-  }
-  html += `<div class="grid${st.page === 0 && st.home?.featured ? " one-row" : ""}">${shown.length ? shown.map((a, i) => card(a, start + i)).join("") : empty}</div>`;
-  content.innerHTML = html;
-}
-function turn(by) {
-  if (by < 0 ? $("prev").disabled : $("next").disabled) return;
-  st.page += by; render();
-}
-
-// ---- Detail sheet ----
-let current = null;  // {app, installed}
-let detailReturn = null, removeConfirmed = false;
-const detailIdentity = app => app.package || app.installed?.package || offerKey(app);
-const ver = v => String(v || "").replace(/^v/i, "");
-const size = n => n >= 1e9 ? (n / 1e9).toFixed(1) + " GB" : n >= 1e6 ? Math.round(n / 1e6) + " MB" : Math.max(1, Math.round(n / 1e3)) + " KB";
-function openDetail(app, opener = document.activeElement) {
-  detailReturn = { node: opener, identity: detailIdentity(app) }; removeConfirmed = false;
-  current = app; drawDetail(); $("detail").hidden = false;
-  $("detail").append($("toast"));  // Notifications stay above the native modal's backdrop.
-  if (!$("detail").open) $("detail").showModal();
-  $("detailTitle").focus();
-  const o = app.offers[0];
-  if (o.source && o.id && !app.detailed) {  // the full entry has all the screenshots
-    api(`/api/sources/details?source=${encodeURIComponent(o.source)}&id=${encodeURIComponent(o.id)}`)
-      .then(full => { if (current === app) { app.offers[0] = { ...o, ...full }; app.detailed = true; drawDetail(); } }).catch(() => {});
-  }
-}
-function drawDetail() {
-  const app = current; if (!app) return;
-  const focused = document.activeElement, hadFocus = $("sheet").contains(focused);
-  const focusedAction = hadFocus && focused.dataset.act;
-  const o = app.offers[0], m = installedOf(app), key = offerKey(app), job = st.jobs.get(key), data = m && st.jobs.get("data:" + m.package);
-  if (app.installed && !m) return closeDetail();  // removed
-  const shots = (o.artwork?.screenshots || []).filter(valid);
-  const top = valid(o.artwork?.banner) ? art(app.name, { banner: o.artwork.banner })
-    : shots.length ? `<div class="gallery">${shots.slice(0, 3).map(u => img(u)).join("")}</div>` : art(app.name, o.artwork || {});
-  const meta = [o.developer, o.source_name, o.version ? `v${ver(o.version)}` : m?.version ? `v${ver(m.version)}` : "", o.size ? size(o.size) : ""].filter(Boolean).join(" · ");
-  const reasons = (o.fit?.reasons || []).filter(Boolean);
-  let acts;
-  const progress = j => {
-    const pct = typeof j.percent === "number" ? Math.max(3, Math.min(100, j.percent)) : null;
-    return `<div class="progress${pct === null ? " busy" : ""}"><span>${esc(j.stage || "Downloading")}${pct === null ? "…" : ` ${Math.round(pct)}%`}</span><div class="track"><div class="fill" style="${pct === null ? "" : `width:${pct}%`}"></div></div></div>`;
-  };
-  const gameData = !(m && st.needsData.has(m.package)) ? "" : data && !data.done ? progress(data)
-    : `<button class="primary" data-act="game-data">Add game data</button><span class="meta">Open it once on the Frame first.</span>`;
-  if (job && !job.done) {
-    acts = progress(job);
-  } else if (m) {
-    acts = gameData + (m.running ? `<button data-act="stop">■ Stop</button>` : `<button class="play" data-act="launch">▶ Open</button>`)
-      + `<button class="danger" data-act="remove"${removeConfirmed ? ' data-sure="1"' : ""}>${removeConfirmed ? "Remove it and its data?" : "Remove"}</button>`;
-  } else if (!o.source) {
-    acts = "";
-  } else if (o.downloadable === false) {
-    acts = `<button disabled>Get it from the developer's page</button>`;
-  } else if (o.verdict?.tone === "blocked") {
-    acts = `<button disabled>Won't run on the Frame</button>`;
-  } else if (st.installedState !== "ready") {
-    acts = `<button disabled>${st.installedState === "loading" ? "Checking installed apps…" : "Read installed apps before installing"}</button>`;
-  } else {
-    acts = `<button class="primary" data-act="install">Install</button>`;
-  }
-  const blurb = o.description || o.summary || (app.installed ? "" : app.summary);  // an Installed card's summary is its version, already in meta
-  const failed = data?.error || job?.error;
-  const note = (failed ? `<div class="meta" style="color:var(--bad)">${esc(failed)}</div>` : "")
-    + (st.installedState === "ready" ? "" : `<div class="meta" role="status">${m ? "Showing last known installed status; it may be out of date." : "Installed status is unknown."}${st.installedState === "loading" ? " Reading installed apps…" : ' <button data-retry-installed>Retry installed apps</button>'}</div>`);
-  $("sheet").innerHTML = `${top}<div class="inner">
-    <div class="top">${icon(app.name, o.artwork)}<div><h2 id="detailTitle" tabindex="-1">${esc(app.name)}</h2><div class="meta">${esc(meta)}</div></div>
-      ${o.vr ? '<span class="vr" style="margin-left:auto">VR</span>' : ""}</div>
-    ${blurb ? `<div class="text">${esc(text(blurb))}</div>` : ""}
-    ${o.verdict ? `<div class="why"><b>${esc(o.verdict.label)}</b>${reasons.length ? `<ul>${reasons.slice(0, 3).map(r => `<li>${esc(r)}</li>`).join("")}</ul>` : ""}</div>` : ""}
-    ${note}<div class="acts">${acts}<button class="close" data-act="close">Close</button></div></div>`;
-  if (hadFocus) {
-    const replacement = focusedAction ? $("sheet").querySelector(`[data-act="${focusedAction}"]`)
-      : focused.matches("[data-retry-installed]") ? $("sheet").querySelector("[data-retry-installed]") : $("detailTitle");
-    (replacement && !replacement.disabled ? replacement : $("sheet").querySelector('[data-act="close"]')).focus();
-  }
-}
-function closeDetail() {
-  if (!current && !$("detail").open) return;
-  const origin = detailReturn;
-  current = null; detailReturn = null; removeConfirmed = false;
-  if ($("detail").open) $("detail").close();
-  $("detail").hidden = true;
-  document.body.append($("toast"));
-  if (origin?.node?.isConnected) return origin.node.focus();
-  // Polling can replace the background cards too. Find the same app in the current page.
-  const items = list();
-  const card = [...document.querySelectorAll(".card[data-i]")].find(b => detailIdentity(items[+b.dataset.i]) === origin?.identity);
-  const feature = st.home?.featured && detailIdentity(st.home.featured) === origin?.identity && document.querySelector("[data-feature]");
-  (card || feature || $("q")).focus();
-}
-$("detail").onclose = () => { if (!$("detail").open) closeDetail(); };
-$("detail").oncancel = e => { e.preventDefault(); closeDetail(); };
-$("detail").onkeydown = e => {
-  if (e.key !== "Tab") return;
-  const buttons = [...$("sheet").querySelectorAll("button:not(:disabled)")];
-  const first = buttons[0], last = buttons[buttons.length - 1];
-  if (e.shiftKey && (document.activeElement === first || document.activeElement === $("detailTitle"))) { e.preventDefault(); last.focus(); }
-  else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
-};
-
-async function runJob(key, start) {
-  const job = { stage: "Downloading", percent: null, done: false };
-  st.jobs.set(key, job); drawDetail(); render();
-  try {
-    const { job: id } = await start();
-    for (let misses = 0; ;) {
-      await new Promise(ok => setTimeout(ok, 1500));
-      let j;
-      try { j = await api(`/api/job?id=${encodeURIComponent(id)}`); misses = 0; }
-      catch (e) { if (++misses >= 20 || /no such job/.test(e.message)) throw e; continue; }
-      Object.assign(job, { stage: j.stage || job.stage, percent: j.percent ?? null });
-      if (!j.done) { drawDetail(); continue; }
-      if (j.error) throw new Error(j.error);
-      toast(j.message); job.result = j.result || {};
-      break;
-    }
-  } catch (e) { job.error = e.message; toast(e.message, true); }
-  finally {
-    job.done = true;
-    if (!job.error) st.jobs.delete(key);  // a failure stays, so the sheet can say why
-    await loadInstalled(); render(); drawDetail();
-  }
-  return job;
-}
-$("sheet").onclick = async e => {
-  const b = e.target.closest("[data-act]"); if (!b || !current) return;
-  const app = current, o = app.offers[0], m = installedOf(app), act = b.dataset.act, key = offerKey(app);
-  if (act === "close") return closeDetail();
-  if (act === "install") {
-    toast(`Installing ${app.name}. The first time takes a minute…`);
-    const job = await runJob(key, () => api("/api/sources/install", { source: o.source, id: o.id, version_code: o.version_code ?? null }));
-    if (job.result?.package) {
-      st.installedFrom.set(key, job.result.package);
-      if (job.result.game_data) st.needsData.add(job.result.package);
-    }
-    return render(), drawDetail();
-  }
-  if (act === "game-data" && m) {  // its own job, by package: a failed copy keeps the pending data, so it can be tried again
-    const job = await runJob("data:" + m.package, () => api("/api/sources", { action: "game-data", package: m.package }));
-    if (!job.error) st.needsData.delete(m.package);
-    return render(), drawDetail();
-  }
-  const pkg = m?.package; if (!pkg) return;
-  if (act === "remove" && b.dataset.sure !== "1") {
-    removeConfirmed = true;
-    b.dataset.sure = "1"; b.textContent = "Remove it and its data?"; return;  // no confirm(): a separate window the laser has to find
-  }
-  b.disabled = true;
-  try {
-    const r = await api("/api/android", { action: act, package: pkg });
-    toast(r.message);
-    if (act === "remove") { st.needsData.delete(pkg); st.jobs.delete("data:" + pkg); }
-    if (act === "launch") closeDetail();
-  } catch (err) { toast(err.message, true); }
-  await loadInstalled(); render();
-  if (current === app) drawDetail();
-};
-$("detail").onclick = e => { if (e.target === $("detail")) closeDetail(); };
-
-// ---- Navigation ----
-$("cats").innerHTML = CATS.map(([id, label, path]) => `<button data-view="${id}" aria-pressed="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round" stroke-linecap="round" aria-hidden="true">${path}</svg>${esc(label)}</button>`).join("");
-document.addEventListener("click", e => {
-  if (e.target.closest("[data-retry-installed]")) { loadInstalled(); return; }
-  const v = e.target.closest("[data-view]");
-  if (v && !e.target.closest("#sheet")) {
-    st.view = v.dataset.view; st.q = ""; $("q").value = "";
-    if (st.view === "installed") loadInstalled().then(() => search()); else search();
-    return;
-  }
-  const featured = e.target.closest("[data-feature]");
-  if (featured) return openDetail(st.home.featured, featured);
-  const c = e.target.closest(".card[data-i]");
-  if (c) openDetail(list()[+c.dataset.i], c);
-});
-$("phone").onchange = e => { st.phone = e.target.checked; search(); };
-$("prev").onclick = () => turn(-1);
-$("next").onclick = () => turn(1);
-// The thumbstick arrives as a mouse wheel: one notch, one page.
-let wheelAt = 0;
-document.querySelector("main").addEventListener("wheel", e => {
-  e.preventDefault();
-  if (!$("detail").hidden || Date.now() - wheelAt < 350 || Math.abs(e.deltaY) < 4) return;
-  wheelAt = Date.now(); turn(e.deltaY > 0 ? 1 : -1);
-}, { passive: false });
-let qTimer;
-$("q").oninput = e => { clearTimeout(qTimer); qTimer = setTimeout(() => { st.q = e.target.value.trim(); search(); }, 250); };
-document.addEventListener("keydown", e => { if (e.key === "Escape") { closeDetail(); $("kbd").hidden = true; } });
-
-// ---- On-screen keyboard (a text field on a panel may not bring up Steam's) ----
-const ROWS = ["1234567890", "qwertyuiop", "asdfghjkl", "zxcvbnm"];
-$("kbd").innerHTML = ROWS.map(r => `<div class="row">${[...r].map(k => `<button data-k="${k}">${k}</button>`).join("")}</div>`).join("")
-  + `<div class="row"><button data-k="clear">Clear</button><button class="wide" data-k=" ">space</button><button data-k="back">⌫</button><button data-k="done" class="primary">Done</button></div>`;
-$("kbd").onclick = e => {
-  const b = e.target.closest("[data-k]"); if (!b) return;
-  const k = b.dataset.k, q = $("q");
-  if (k === "done") { $("kbd").hidden = true; return; }
-  q.value = k === "clear" ? "" : k === "back" ? q.value.slice(0, -1) : q.value + k;
-  q.dispatchEvent(new Event("input"));
-};
-$("kbdBtn").onclick = () => $("kbd").hidden = !$("kbd").hidden;
-
-loadInstalled().then(() => search());
-</script>
-</body>
-</html>