Copy new screenshots and Steam clips to the computer automatically

Settings → Copy to this computer, off by default, with a switch each for
screenshots and Steam clips. While a headset is connected, a worker in the
server looks about once a minute and copies what's new with save_shots and
frame_clips.export_clip: only what's newer than turning it on, never what it
copied before (remembered per headset in auto-sync.json, so deleted files stay
deleted), never Steam's background recording or a clip written to in the last
30 s. It waits for other work on the headset, backs off to 15 minutes while
the headset is unreachable, and pauses when this computer is out of space.
Copy everything now copies the rest once.

The Frame-side clip listing now reports each recording's idle time, by the
Frame's clock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

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

@@ -43,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: Updater tests
-        run: node --test app/test/updater.test.js
+      - name: App tests
+        run: node --test app/test/*.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
 

README.md

@@ -63,17 +63,17 @@ About 4,500 F-Droid apps rated for the Frame. One click installs each as its own
 <tr>
 <td valign="top">
 
-**📁 Files, games and clipboard**<br>
-Drag files onto the window to send them. Drop a game's .zip, folder or .exe to add it to the Steam library, with Proton or the Linux runtime picked for you. Send text or your clipboard straight to the headset's desktop.
+**📁 Files and games**<br>
+Drag files onto the window to send them. Drop a game's .zip, folder or .exe to add it to the Steam library, with Proton or the Linux runtime picked for you.
 
 </td>
 <td valign="top">
 
-**📸 Screenshots**<br>
-Browse the shots you take in the headset and save them to your Pictures folder.
+**📸 Screenshots and recordings**<br>
+Browse the shots you take in the headset and save them to your Pictures folder, or have new ones and your Steam clips copied over automatically. Record what the headset shows, with its sound, or export Steam's clips at any length, as .mp4 files in your Videos folder ([not tested on a headset yet](docs/recording.md)).
 
-**⌨️ Keyboard and trackpad**<br>
-Type and point in the Frame's apps from your computer or phone, through KDE Connect, which Frame Control brings along and sets up on the Frame. Nothing else to install, anywhere.
+**⌨️ Type on the headset**<br>
+Type and point in the Frame's apps from your computer or phone, through KDE Connect, which Frame Control brings along and sets up on the Frame. Copy text to the headset's clipboard and back again. Nothing else to install, anywhere. Press T to open it.
 
 </td>
 </tr>
@@ -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:
@@ -223,7 +223,6 @@ Frame's software fits together, all checked against a real headset and labelled
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |
 | [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 |
-| [Eye tracking and heart rate](docs/tracking.md) | Our OpenXR → OSC bridge, BlueZ heart-rate panel and optional local session log; SlimeVR feasibility notes |
 | [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, the headset smoke test and a Windows test VM |
 | [Open questions](docs/open-questions.md) | What's still unchecked |

app/main.js

@@ -11,6 +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,6 +29,7 @@ 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;
@@ -280,6 +282,14 @@ 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() : "");
+// Text from the headset's clipboard onto this computer's.
+ipcMain.handle("clipboard:write", (e, text) => {
+  if (!fromUi(e) || typeof text !== "string") return false;
+  clipboard.writeText(text);
+  return true;
+});
+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;

app/package-lock.json

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

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",
@@ -39,6 +39,7 @@
       "preload.js",
       "install-link.js",
       "updater.js",
+      "preferences.js",
       "meta-signin.js",
       "package.json",
       "build/icon.png"

app/preferences.js

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

@@ -1,5 +1,5 @@
-// Lets the page read this computer's clipboard through Electron, so sending it
-// to the Frame needs no pbpaste, PowerShell, xclip or wl-clipboard. Also tells
+// Lets the page read and write this computer's clipboard through Electron, so sending
+// it to the Frame, and copying the Frame's back, needs no pbpaste, PowerShell, xclip or wl-clipboard. Also tells
 // the page where a dropped file or folder lives, so a folder can be sideloaded
 // as a title without zipping it (the local server reads it from there).
 // It can put a screenshot on the clipboard as an image, open Set Up Connection when
@@ -11,8 +11,13 @@
 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"),
+  writeClipboard: (text) => ipcRenderer.invoke("clipboard:write", text),
   writeImage: (bytes) => ipcRenderer.invoke("clipboard:writeImage", bytes),
   setUpConnection: () => ipcRenderer.invoke("connection:setup"),
   restartServer: () => ipcRenderer.invoke("server:restart"),  // the "couldn't start" page's Try Again

app/test/preferences.test.js

@@ -0,0 +1,60 @@
+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/agents.md

@@ -97,7 +97,7 @@ replies, screenshots and approval payloads are not sent to analytics.
 
 ## Assistant panel
 
-Open **Tools → Open assistant**, or `http://127.0.0.1:47810/assistant`.
+Open **Settings** (the gear in the header) **→ Open assistant settings**, or `http://127.0.0.1:47810/assistant`.
 To put the same page in the headset, with the HTTP server still running:
 
 ```sh

docs/android-backups.md

@@ -0,0 +1,57 @@
+# Import an Android game backup
+
+A SideQuest backup can contain a small APK and much larger `main.…obb` and
+`patch.…obb` files. All of them belong to the same game. Installing only the APK
+can leave the game unable to start because its assets are missing.
+
+In **Add / Install → Import Android game** (or **Apps → Browse → Import Android game**), choose the APK and its OBB files together.
+You can also drop them anywhere in the window. In the desktop app, dropping the
+APK alone finds matching OBB files beside it; dropping a folder containing the
+APK and OBBs also works. Browsers can read only the files you explicitly choose.
+
+The import screen shows the game app and its game-data files together. **Import
+game & data** installs the APK, starts its own Steam library instance, waits for
+Android and the installed package, copies the OBBs, and closes the game. Open it
+again from the Steam library to play. The screen explains this before import;
+choosing files alone never starts a game.
+
+Files are matched using the package inside the APK and the standard
+`main|patch.<version>.<package>.obb` name, not the APK's filename. Both main and
+patch files are preserved. OBB version numbers need not equal the APK's current
+version code: updates can reuse older expansion files. The copy uses the existing
+SHA-256 transfer check inside Android and writes to that game's own
+`/sdcard/Android/obb/<package>` folder.
+
+If no data files are selected, the screen reminds you to include any OBBs in the
+backup before offering **Install game app**. An APK cannot reliably tell Frame
+Control whether separate expansion files are required. Game-data files are never
+silently sent to Downloads by this flow.
+
+If setup fails, the import screen keeps the error and retry instructions visible.
+The APK may already be installed, but the game is not reported ready. Import the
+same backup again, or choose just its OBB files to add data to an existing install.
+The importer checks the installed package and version before writing data and
+closes the instance after a failed copy. Unrelated or duplicate files, running
+games that would be replaced, and downgrades are rejected. Uploaded staging files
+are discarded after use or cancellation; abandoned imports expire after an hour
+when the importer is next used, and dead-server staging folders are swept at
+startup.
+
+This flow handles one ordinary APK and standard OBB files for one game at a time.
+Split APKs, XAPK/APKS archives, nested Android/data folders and private save
+archives need their own import handling. PC ZIP/folder/EXE imports keep their
+existing route. Quest USB and Meta library imports keep their existing workflow.
+
+Validation covers actual APK parsing, the three-file backup layout, package
+matching, sibling discovery, browser upload staging and cleanup, instance/version
+guards and failure recovery with mocked headset operations. Browser verification
+uses the real page and upload/inspection endpoints with simulated installation.
+**Verified 2026-10-20 on a real Steam Frame**, BUILD_ID `20260925.6191901`:
+F-Droid Basic 2.0.2 with two synthetic main/patch OBBs completed the automatic
+install/start/copy/close sequence. Reopening its persistent instance confirmed
+both SHA-256 hashes in `/sdcard/Android/obb/org.fdroid.basic`. The test app,
+shortcut and instance were removed afterward, the shared device lock was
+released, and the battery remained at 99%. See [device evidence](evidence/android-import/device.json).
+The headset was unworn; this checks transfer and persistence, not rendering,
+Resident Evil 4 gameplay, or a game that exits before data can be copied. This
+flow does not change APK compatibility or remove licence checks.

docs/apks.md

@@ -183,6 +183,63 @@ 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/charge-limit.md

@@ -0,0 +1,156 @@
+# Battery charge limit (80%): research
+
+**Question:** can Frame Control set an 80% battery charge limit on the Frame
+over SSH or adb, safely?
+
+**Verdict: don't build it yet; it needs a headset check.** Valve's supported
+mechanism (the one Steam's own charge-limit setting uses on the Deck) is not
+configured for the Frame. The only control the Frame seems to have is a
+vendor charger attribute that Valve's own charging daemon also manages.
+Research as of 2026-10-23. **Not tested on a headset.**
+
+## How Steam does it on other devices
+
+- Steam's **Settings → Power → Battery Charge Limit** shipped to the Deck in
+  SteamOS 3.7.8 (beta client 2025-05-08)
+  ([GamingOnLinux](https://www.gamingonlinux.com/2025/05/steamos-3-7-7-beta-brings-a-battery-charge-limit-option-and-improved-lenovo-legion-go-s-support/)).
+- Steam calls SteamOS Manager on the session bus:
+  `com.steampowered.SteamOSManager1.BatteryChargeLimit1`, with properties
+  `MaxChargeLevel` (`i`, read/write; `-1` resets to the default) and
+  `SuggestedMinimumLimit` (`i`, read-only). The CLI is
+  `steamosctl get-max-charge-level` / `set-max-charge-level` /
+  `suggested-minimum-charge-limit`. Source: `data/interfaces/com.steampowered.SteamOSManager1.xml`
+  and `steamos-manager/src/bin/steamosctl.rs` in
+  [holo/steamos-manager](https://gitlab.steamos.cloud/holo/steamos-manager),
+  read at commit `83981ab` (2026-10-21).
+- The root daemon writes the value to sysfs only if the device's TOML in
+  `data/devices/` has a `[battery_charge_limit]` section. Two methods exist
+  (`steamos-manager/src/power.rs`, `BatteryChargeLimitMethod`):
+  - `hwmon_attribute`: the Deck writes `max_battery_charge_level` on
+    `steamdeck_hwmon` (`data/devices/steam-deck.toml`).
+  - `acpi_sb`: ROG Ally, MSI Claw and others write the standard
+    `charge_control_end_threshold` on the ACPI battery
+    (`/sys/bus/{platform,acpi}/drivers/…battery…/PNP0C0A:00/…/power_supply/*/`).
+    On ARM there's no ACPI, so this path can't match there either.
+- With no `[battery_charge_limit]` section, the interface fails with
+  `UnknownInterface` (Steam can still show its toggle on unsupported hardware:
+  [steam-for-linux#12044](https://github.com/ValveSoftware/steam-for-linux/issues/12044)).
+
+## What the Frame has
+
+- **Upstream `data/devices/steam-frame.toml`** (matched by
+  `dt.compatible = "qcom,sm8650"`, variant `Deckard`) configures GPU clocks
+  and performance profiles only. It has **no `[battery_charge_limit]`**, so
+  SteamOS Manager on the Frame has no charge-limit backend. Its git history
+  (2026-09-10 to 2026-10-12) never added one.
+- **Battery driver:** the Frame's battery is
+  `/sys/class/power_supply/max1720x_bat_7-36`, and the charger is a
+  `tcpm-source-psy-…` USB-PD supply ([how-the-frame-works.md](how-the-frame-works.md)).
+  Both were verified 2026-09-25, and `ui/frame_status.py` `battery()` and
+  `power_source()` read them. The Maxim MAX1720x is a **fuel gauge** and
+  can't control charging. Mainline `drivers/power/supply/max1720x_battery.c`
+  exposes only read-only properties (capacity, voltage, current, temp,
+  charge_full…), with no `charge_control_end_threshold`. Valve's build is
+  patched: it reports `time_to_full_now`, which mainline doesn't have. Even
+  so, a charge stop would have to come from the separate charger IC, not this
+  node.
+- **Not the qcom_battmgr path.** Some other SM8650/SM8750 handhelds get
+  `charge_control_end_threshold` from Qualcomm's `qcom_battmgr`
+  (pmic_glink) driver, clamped at 55% or above. A third-party distro enabled
+  Steam's limit on those by patching steamos-manager
+  ([armada-os/armada#758](https://github.com/armada-os/armada/pull/758)). The
+  Frame's battery isn't exposed by `qcom_battmgr`, so that doesn't carry over.
+  (Unverified: whether a `qcom_battmgr` node also exists on the Frame. The
+  read-only checks below answer this.)
+- **What third parties found:**
+  [y0usaf/frame-charge](https://github.com/y0usaf/frame-charge) reports that
+  the Frame has no `charge_control_end_threshold` and falls back to a vendor
+  `charging_pause` attribute. It also reports that `constant_charge_current`
+  changes on its own, which it attributes to Valve's `deckard_charge_daemon`
+  (`deckard-charger.service`). By its own README, that tool has only run its
+  read-only `status` on a Frame and has **not** been tested against real
+  charging. Two questions are still open: whether pausing stops the current,
+  and whether Valve's daemon undoes it.
+
+## Why not build it now
+
+- **No supported endpoint.** The only Valve-supported interface,
+  `BatteryChargeLimit1`, isn't backed on the Frame. Writing sysfs ourselves
+  would bypass Steam and SteamOS Manager, and it needs root (`sudo -S` with
+  the user's password).
+- **A rival owner.** Valve's charge daemon already adjusts charging
+  parameters. Toggling `charging_pause` underneath it could be undone without
+  warning, fight it in a loop, or leave charging paused.
+- **Stuck at a low charge.** If the app or the Frame dies while charging is
+  paused, the Frame could sit at a low charge on the charger. Whether a
+  reboot clears `charging_pause` is unknown.
+- **The UI would mislead.** Steam's setting (if it shows at all) wouldn't
+  reflect our limit.
+- **adb doesn't help.** Wi-Fi adb (`frame:5555`) reaches the Lepton Android
+  container only. USB-C adb reaches the Linux side as `steamos` (non-root, the
+  same as SSH, [ssh.md](ssh.md)). Neither adds a charging-control route.
+  Android's `dumpsys battery` in Lepton is a container view, not the hardware.
+
+**Revisit when** a SteamOS update adds `[battery_charge_limit]` to
+`steam-frame.toml` (or `steamosctl get-max-charge-level` stops returning
+`UnknownInterface` on the Frame). Then the feature is just a SteamOS Manager
+call:
+
+- Read: `steamosctl get-max-charge-level`
+- Set: `steamosctl set-max-charge-level 80`
+- Undo: `steamosctl set-max-charge-level -- -1`
+
+That runs as `steamos` with no sudo. It's the same value Steam's own
+Settings → Power shows, so both stay in sync.
+
+## Headset checks (read-only first)
+
+Run these over SSH as `steamos`. Steps 1–4 only read.
+
+```sh
+# 1. Does SteamOS Manager offer the interface on this build?
+steamosctl get-max-charge-level; steamosctl suggested-minimum-charge-limit
+busctl --user introspect com.steampowered.SteamOSManager1 \
+  /com/steampowered/SteamOSManager1 | grep -i -A3 ChargeLimit
+grep -n battery_charge_limit /usr/share/steamos-manager/devices/*frame* 2>/dev/null
+
+# 2. Which power supplies exist, and which drivers back them?
+for d in /sys/class/power_supply/*; do
+  echo "== $d ($(cat $d/type)) driver=$(basename "$(readlink -f $d/device/driver)" 2>/dev/null)"
+  ls $d
+done
+
+# 3. Any charge-control attributes, with their values and permissions?
+ls -l /sys/class/power_supply/*/{charge_control_*,charging_pause,charging_enable,constant_charge_current*,charge_behaviour} 2>/dev/null
+grep -H . /sys/class/power_supply/*/{charge_control_*,charging_pause,charging_enable,constant_charge_current*,charge_behaviour} 2>/dev/null
+
+# 4. What is Valve's charger daemon, and what does it touch?
+systemctl status deckard-charger.service --no-pager
+systemctl cat deckard-charger.service
+journalctl -b -u deckard-charger.service --no-pager | tail -50
+```
+
+If step 1 succeeds on some build, test `steamosctl set-max-charge-level 80`
+on a charger at a charge above 80%. Watch `current_now` on the
+`max1720x_bat_*` node fall to about 0, then `steamosctl set-max-charge-level -- -1` and
+confirm charging resumes. Do this on a supervised Frame only. If only step 3
+finds a vendor attribute, **stop**: don't write it, and leave the question
+with Valve.
+
+## Sources
+
+- steamos-manager source, commit `83981ab` (2026-10-21):
+  `data/devices/steam-frame.toml`, `data/devices/steam-deck.toml`,
+  `data/interfaces/com.steampowered.SteamOSManager1.xml`,
+  `steamos-manager/src/power.rs`, `steamos-manager/src/manager/user.rs`.
+  [gitlab.steamos.cloud/holo/steamos-manager](https://gitlab.steamos.cloud/holo/steamos-manager)
+- Mainline [`max1720x_battery.c`](https://github.com/torvalds/linux/blob/master/drivers/power/supply/max1720x_battery.c)
+- [ValveSoftware/steam-for-linux#12044](https://github.com/ValveSoftware/steam-for-linux/issues/12044):
+  the Steam toggle shows on unsupported hardware
+- [armada-os/armada#758](https://github.com/armada-os/armada/pull/758):
+  `qcom_battmgr` threshold on other SM8650/SM8750 devices
+- [y0usaf/frame-charge](https://github.com/y0usaf/frame-charge): third-party,
+  untested on real charging
+- [GamingOnLinux: SteamOS 3.7.7 beta charge limit](https://www.gamingonlinux.com/2025/05/steamos-3-7-7-beta-brings-a-battery-charge-limit-option-and-improved-lenovo-legion-go-s-support/)
+- Repo: [how-the-frame-works.md](how-the-frame-works.md) (battery and
+  charger nodes), [ssh.md](ssh.md) (adb scope), `ui/frame_status.py`

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/evidence/android-import/device.json

@@ -0,0 +1,34 @@
+{
+  "date": "2026-10-20T03:53:25Z",
+  "build_id": "20260925.6191901",
+  "app": "F-Droid Basic 2.0.2 (org.fdroid.basic, version code 2000052)",
+  "input": "One real APK plus synthetic main and patch OBBs named with older version code 2000050",
+  "sibling_discovery": true,
+  "automatic_import": "passed",
+  "closed_after_import": true,
+  "independent_readback": [
+    "5023b41e7ac80f8b26a868db1f66884976bf864fab81a070ad37539f3481b352  /sdcard/Android/obb/org.fdroid.basic/main.2000050.org.fdroid.basic.obb",
+    "aecbed7433e81aaeef40942069d03ad23130f09d93b7e78bbe224865a9573157  /sdcard/Android/obb/org.fdroid.basic/patch.2000050.org.fdroid.basic.obb"
+  ],
+  "cleanup": {
+    "test_install_removed": true,
+    "running_instances_before": {},
+    "running_instances_after": {},
+    "battery_before": [
+      "100",
+      "Full",
+      "Charging"
+    ],
+    "battery_after": [
+      "99",
+      "Discharging",
+      "Charging"
+    ],
+    "shared_lock_released": true
+  },
+  "limits": [
+    "No headset rendering or gameplay assertion; headset unworn.",
+    "Synthetic expansion files verify transport and persistence, not Resident Evil 4 compatibility.",
+    "A game that exits before its Lepton instance can accept data was not tested."
+  ]
+}

docs/family-comfort.md

@@ -58,7 +58,7 @@ not been verified and is not guaranteed.
 
 ## Casting
 
-**Cast headset view** starts the existing headset Live view and requests full
+**Cast to this screen** (Home → **Right now**) starts the existing headset Live view and requests full
 screen where supported. Show that screen to people in the room, or use the
 computer/phone's own screen mirroring. It creates no new stream transport,
 public URL or LAN server. iPhone uses the inline viewer if full screen is not

docs/file-transfer.md

@@ -15,6 +15,10 @@ depends on SSH working through the `frame` alias from `scripts/connect.sh`.
 | KDE Connect | KDE Connect on both | Guess | There's a macOS build of KDE Connect, but whether it's present or installable on the Frame wasn't confirmed. It would give you clipboard sync, file send, and remote input. Worth checking on-device. |
 | microSD | Physical card | Confirmed that the slot exists ([Wikipedia](https://en.wikipedia.org/wiki/Steam_Frame)) | Offline fallback. |
 
+Screenshots and Steam clips have their own buttons on **Tools → Capture &
+Live**, and **Settings → Copy to this computer** copies new ones here
+automatically: see [recording.md](recording.md#copying-new-ones-automatically).
+
 ## Clipboard
 
 `scripts/paste-to-frame.sh` sends the Mac clipboard (or stdin) to the
@@ -36,3 +40,28 @@ desktop has to be running in the headset. It's text only, and pastes over about
 
 A simpler fallback: `ssh frame 'cat > ~/clip.txt'` < file, then open it in the
 headset.
+
+### In Frame Control
+
+**Tools → Type on the headset** (also on Home, and press `T` anywhere) has the
+clipboard next to the keyboard and trackpad, both ways:
+
+- **Send text** or **Send this computer's clipboard** puts text on the headset's
+  clipboard, as above.
+- **Copy the headset's clipboard** brings it back: copy something in a desktop
+  app on the Frame, then press it, and paste on your computer. It calls
+  Klipper's `getClipboardContents` on the same D-Bus bus, and sends the text
+  back as base64, so accents, emoji and line breaks arrive unchanged. The
+  desktop app and the iPhone app put it on their own clipboard. With the server
+  in a browser, the server sets the clipboard of the computer it runs on:
+  `pbcopy` on macOS, PowerShell's `Set-Clipboard` (or `clip.exe`) on Windows,
+  `wl-copy`, `xclip` or `xsel` on Linux.
+
+It's text only, and copying back takes up to 1 MB; a bigger clipboard is
+refused with a message, so send big things as a file. An empty clipboard, or
+one holding an image, says so. Neither the server nor its log ever records what
+was on the clipboard.
+
+**Not tested on a headset yet.** Reading uses the same Klipper interface as
+sending, which was verified on 2026-09-25, but `getClipboardContents` itself
+hasn't been tried on a Frame. The fake Frame (`tests/fakeframe`) answers it.

docs/frame-control.md

@@ -17,15 +17,21 @@ python3 ui/server.py         # anywhere: then open http://127.0.0.1:47810
 
 ## Features
 
-The window has six tabs: **Home** (headset view, status, screenshots),
-**Games** (installed games, sideloaded titles, getting games), **Android** (apps,
-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
+The window has six tabs: **Home** (what the headset's doing and what you'd do
+next, the headset view, screenshots, family and comfort, the keyboard and
+trackpad, and VR performance, folded away), **Games** (installed games,
+sideloaded titles, getting games), **Android** (apps, the catalogue, display
+settings, reports), **Tools** (in the headset: your computer's windows, the media
+player and the panel switcher; then 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, and `T` opens Type on the headset. The gear in the header (key 7) opens **Settings**:
+privacy and updates, library artwork and the assistant. The battery chip opens
+the headset's details: storage, memory, temperature, Wi-Fi, uptime and SteamOS
+build. Files can be dropped anywhere in the window. A
+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.
@@ -43,6 +49,10 @@ counts them while they run.
   gamescope's flat layer instead.
 - **Screenshots** you take in the headset with Steam's shortcut: browse them and
   save them to `~/Pictures/SteamFrame`.
+- **Record** what the headset shows, with its sound, to an `.mp4` in
+  `~/Videos/SteamFrame`, and **Steam clips**: export clips and background
+  recordings from Steam's game recording at any length, without re-encoding.
+  See [recording.md](recording.md). Not tested on a headset yet.
 - **Battery** with charging state: charge rate in watts, time to full or empty,
   charger type and wattage (for example USB-C PD 20 W), and battery temperature.
 - **Status**: storage, memory, temperature, Wi-Fi, uptime, and whether SteamVR,
@@ -74,8 +84,14 @@ counts them while they run.
   their own Android app. A game's `.zip`, folder or `.exe` becomes a title in
   the Steam library (Valve's Devkit Game path, with Proton or the Steam Linux
   Runtime picked from the program's header), listed under **Sideloaded titles**
-  with Launch and Remove; see [sideloading.md](sideloading.md). Send typed text, or your computer's clipboard, to the
-  Frame clipboard.
+  with Launch and Remove; see [sideloading.md](sideloading.md).
+- **Type on the headset** (on Home, in Tools, in the Control Center, or press
+  `T`): use your computer's keyboard and mouse, or a phone's touchscreen, in the
+  Frame's apps through KDE Connect, and move clipboard text both ways. Send
+  typed text or your computer's clipboard to the headset, or copy the headset's
+  clipboard back: copy in a desktop app on the Frame, then **Copy the headset's
+  clipboard**. The clipboard needs the desktop panel open in the headset; it's
+  text only, up to 1 MB. See [file-transfer.md](file-transfer.md#clipboard).
 - **Mac in the headset** (macOS): show any Mac window, or a whole screen, as
   its own panel in the headset. Place it with the SteamVR dashboard, click and
   scroll with the laser, and type on the Mac. Streams hardware H.264 through
@@ -133,7 +149,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 **On your Frame** before
+sources and artwork. Android display links reveal the **Library** before
 scrolling to the form. Mac streaming remains searchable on all platforms, with
 its action shown only when the server is on macOS.
 
@@ -214,8 +230,8 @@ Google publishes no arm64 Linux platform-tools. Set Up Connection runs
 `ui/frame_connect.py` in your terminal emulator (GNOME Terminal, Konsole, xterm
 and others). The log is at
 `~/.config/Frame Control/logs/server.log`. Running `ui/server.py` in a browser
-instead of the app, sending the clipboard needs `wl-clipboard` (Wayland) or
-`xclip` (X11).
+instead of the app, sending the clipboard, or copying the headset's to this
+computer, needs `wl-clipboard` (Wayland), `xclip` or `xsel` (X11).
 
 ## Building
 
@@ -239,5 +255,5 @@ Control implementations. MCP wraps this HTTP API without API keys. Changes
 require a separate user approval; power also retains its password prompt. The
 assistant uses a user-chosen endpoint and sends nothing until the user opts in
 for a message. Screenshot context is separately opt-in. Model replies cannot
-operate the headset. Tools → Open assistant opens the page; the linked guide
+operate the headset. Settings → Open assistant settings opens the page; the linked guide
 covers putting it in a Chromium panel on the Frame.

docs/how-the-frame-works.md

@@ -20,15 +20,6 @@ SteamVR  (vrserver, vrcompositor, vrdashboard)       ← renders the room + pane
 Lepton (Android 11, podman container "lepton-dev") ← its own panel, app 3056000
 ```
 
-## Tracking additions (verified 2026-09-28)
-
-On SteamOS 0.4.1, build `20260925.6191901`, SteamVR exposes combined gaze
-through `XR_EXT_eye_gaze_interaction` in a headless OpenXR 1.0 session. Our
-reader obtained valid tracked samples and sent OSC to a configured loopback
-receiver. BlueZ LE discovery works; GTK4/GI can render our heart-rate panel.
-No BLE strap or SlimeVR trackers were attached. See [tracking](tracking.md)
-for the evidence, privacy defaults and untested integration boundaries.
-
 ## Facts worth knowing
 
 | Fact | Where it matters |

docs/iphone.md

@@ -102,8 +102,9 @@ app installed opens its App Store page.
 Things iOS asks the first time: **Local Network** (tap Allow, or the app can't
 see the Frame), and **Paste** when you send the iPhone's clipboard (tap Allow
 Paste, or set Settings → Apps → Frame Control → Paste from Other Apps → Allow).
-Sending text to the Frame's clipboard needs the desktop panel open in the
-headset, as on the desktop app.
+Sending text to the Frame's clipboard, or copying the Frame's to the phone
+(**Type on the headset → Copy the headset's clipboard**), needs the desktop
+panel open in the headset, as on the desktop app.
 
 Not yet exercised: Android display changes through podman (no Android app was
 running), a real sleep/restart/shut down on the Frame, and a physical iPhone.
@@ -114,8 +115,8 @@ don't.
 
 ## Family and comfort
 
-The shared Home card sets session limits, breaks and check-ins, and offers
-**Cast headset view**. **Enable / test notifications** requests iOS notification
+The shared Home card sets session limits, breaks and check-ins; **Cast to this
+screen** is in Home's **Right now** card. **Enable / test notifications** requests iOS notification
 permission and sends a local test. These are local notifications, not APNs push;
 iOS background suspension can interrupt phone alerts. The headset timer still
 runs. See [the behavior and verification limits](family-comfort.md).

docs/open-questions.md

@@ -143,6 +143,15 @@ check in the headset:
 - Keys from SteamVR's on-screen keyboard.
 - Whether Flathub Chromium decodes H.264 (otherwise use Compatible).
 
+## Battery charge limit (2026-10-23)
+
+Can an 80% charge limit be set over SSH or adb? **Not safely yet.** SteamOS
+Manager's `BatteryChargeLimit1` (the interface Steam's own setting uses) has
+no backend in the Frame's device config, and the battery node is a
+`max1720x` fuel gauge with no `charge_control_end_threshold`. Research and
+read-only headset checks are in [charge-limit.md](charge-limit.md). Not tested
+on a headset.
+
 ## Unconfirmed claims made in these docs
 
 - `/home` and `/etc` persist across Frame OS updates. This is inferred from

docs/panels.md

@@ -125,7 +125,7 @@ a limit on the number of floating panels.
   separate from Frame Control. Public reports describe some Proton support;
   Windows-only does not by itself prove a Frame app cannot run. Local status
   and sources are in [VR utilities](vr-utilities.md).
-- **Our performance HUD:** Home → VR comfort and performance → Open HUD in
+- **Our performance HUD:** Home → VR performance (unfold it) → Open HUD in
   headset creates its own gamescope panel using built-in tools. It needs no
   third-party overlay app. [Metrics and verification](vr-utilities.md).
 

docs/privacy.md

@@ -132,8 +132,8 @@ runs.
 
 ## Report a problem
 
-**Report a problem** is the warning-sign button in the header, also in the
-Privacy panel and under **Help → Report a Problem…**. It sends the report
+**Report a problem** is the speech-bubble button in the header, also in the
+Settings page (**Privacy & updates**) 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
 nothing is published. It works whatever the analytics settings are, because
@@ -287,3 +287,12 @@ then every 6 hours: the latest release's `update.json` on GitHub, or
 `api.github.com/repos/saphid/frame-control/releases/latest` if that fails.
 Those requests carry no id. To stop it, set
 `FRAME_CONTROL_NO_UPDATE_CHECK=1`. See [releasing.md](releasing.md).
+
+## Screenshots and clips
+
+Copying screenshots and Steam clips to your computer, by hand or with
+**Settings → Copy to this computer**, goes straight from the headset to your
+computer over the same SSH connection as everything else. Nothing is uploaded
+anywhere. What automatic copying has copied is listed, by file id, in
+`auto-sync.json` in Frame Control's data folder; see
+[recording.md](recording.md#copying-new-ones-automatically).

docs/recording.md

@@ -0,0 +1,158 @@
+# Recording and Steam clips
+
+Frame Control can record what the headset shows, with its sound, and save it as
+an `.mp4` on your computer. It can also export the clips and background
+recordings from Steam's own game recording, at any length, as one `.mp4` each.
+Both are on **Tools → Capture & Live**. Everything is saved to
+`~/Videos/SteamFrame`, next to the screenshots in `~/Pictures/SteamFrame`.
+Nothing needs installing on the computer or on the Frame: the work is done by
+the `ffmpeg` that SteamOS ships.
+
+**Not tested on a headset yet.** This is built from what the code already does
+on the Frame (the live view, the media player) and from how Steam is reported
+to store its recordings. The parts we're least sure of are listed under
+[What hasn't been checked](#what-hasnt-been-checked). Please report what you see.
+
+## Record
+
+Press **Record** next to **Live**. The button turns into **Stop**, and a line
+under the viewer counts the time. Press **Stop**: the recording is finished on
+the Frame, converted to `.mp4` there (without re-encoding) and copied to
+`~/Videos/SteamFrame/rec-<date>-<time>.mp4`. The line says when it's saved.
+
+- **What's in it**: the same picture as **Live**, SteamVR's copy of the headset
+  view (one undistorted 1920×1080 eye, from `/dev/video99`), at 30 fps and
+  8 Mbit/s, encoded with x264 (the Frame's hardware encoder crashes `ffmpeg`).
+  The sound is what the headset plays: the monitor of PipeWire's default
+  output, read through its PulseAudio server (`-f pulse -i @DEFAULT_MONITOR@`).
+  The microphone isn't recorded.
+- **Without sound**: before each recording Frame Control checks for a fraction
+  of a second that `ffmpeg` can read that audio. If it can't, the recording goes
+  ahead as video only, and the page and the saved message say so.
+- **Limits**: a recording stops by itself after 20 minutes and is saved as if
+  you'd pressed Stop. It needs about 2.9 GB free on the Frame to start (room for
+  a full-length recording twice, while it's converted), and checks the space on
+  your computer before copying. One recording runs at a time.
+- **Where it waits on the Frame**: `~/.cache/frame-control/video/`, not `/tmp`,
+  which is a RAM disk on SteamOS. It's deleted once copied.
+- **If the connection drops or the app quits** while recording, the Frame
+  stops `ffmpeg` cleanly when the SSH channel closes, as the live view does. A
+  recording that was never copied is deleted when the next one starts.
+
+Recording and **Live** can run together; both read the same device.
+
+## Steam clips
+
+**Steam clips** lists what Steam's game recording has kept on the Frame: saved
+clips and background recordings, newest first, with the game, length and size.
+**Export** joins one into a single `.mp4` in `~/Videos/SteamFrame`, named after
+its folder (for example `clip_620_20261020_202134.mp4`), however long it is.
+Steam's own export is reported to stop at about 60 seconds. Exports run in the
+background; ones already on your computer are marked.
+
+How it works: Steam keeps each recording as MPEG-DASH segments, one folder per
+recording session.
+
+```
+~/.local/share/Steam/userdata/<account>/gamerecordings/
+  video/bg_<appid>_<YYYYMMDD>_<HHMMSS>/                 background recording
+  clips/clip_<appid>_<YYYYMMDD>_<HHMMSS>/video/bg_<...>/ a saved clip
+      session.mpd
+      init-stream0.m4s  chunk-stream0-00001.m4s  chunk-stream0-00002.m4s ...
+      init-stream1.m4s  chunk-stream1-00001.m4s ...
+```
+
+Each stream's `init-stream` segment followed by its chunks, in number order, is
+a playable fragmented MP4 of that stream. On the Frame, `ui/frame_clips.py`
+builds those files and has `ffmpeg` put the video and audio into one `.mp4`
+with `-c copy`, so nothing is re-encoded and it takes seconds. The result is
+copied to the computer and deleted from the Frame. The export needs free space
+on the Frame of about twice the recording's size while it runs.
+
+The listing doesn't rely on the folder names: any folder under `clips/` or
+`video/` (up to four levels down) holding `init-stream*.m4s` counts. A stream
+missing its init segment or its chunks is left out. Missing chunk numbers are
+shown as "pieces missing"; the rest still exports.
+
+## Copying new ones automatically
+
+**Settings → Copy to this computer** copies new screenshots and Steam clips
+here on their own. It's off until you turn it on, with a switch each for
+screenshots and Steam clips. While a headset is connected, Frame Control looks
+about once a minute and copies what's new with the same code as **Save** and
+**Export**: screenshots to `~/Pictures/SteamFrame`, clips to
+`~/Videos/SteamFrame`.
+
+- **Only what's new.** It copies what you take after turning it on, so the
+  shots and clips already on the headset don't all arrive at once. **Copy
+  everything now** copies everything that isn't on this computer yet, once.
+- **Deleted stays deleted.** What it has copied is remembered, per headset, in
+  `auto-sync.json` in Frame Control's data folder, so a file you delete here
+  isn't copied again (**Copy everything now** would bring it back).
+- **Saved clips only.** Steam's background recording is a rolling buffer, not
+  something you chose to keep, so it isn't copied; export it by hand. A clip
+  Steam wrote to in the last 30 seconds is still being saved and waits for the
+  next look.
+- **It gives way.** It waits while an install, an export, a recording or
+  anything else is running on the headset, and stops between files if one
+  starts. While a copy is running, switching headsets waits for it, as it does
+  for an export. When the headset can't be reached it waits longer each time,
+  up to 15 minutes, and starts over once it answers.
+- **When this computer is full** (under 512 MB free, or a copy runs out of
+  space) it pauses and says so in Settings and above the lists. Free some space
+  and press **Resume**.
+- **With several headsets** it copies from the one you're connected to.
+
+Settings shows when it last checked, how many files it last copied and when,
+and the last problem it had. The screenshot and clip lists say when it's on.
+
+## For developers
+
+`ui/frame_clips.py` holds the logic, so other features can reuse it (automatic
+copying, in `ui/frame_autosync.py`, does):
+
+- `list_clips(run_frame)` and `export_clip(id, run_frame, run, fetch)` are the
+  computer's side; the server passes how to reach the Frame.
+- `list_recordings(userdata)` and `export(userdata, id)` are the Frame's side,
+  run as `python3 - list` / `python3 - export ID` with the file on stdin.
+- `Recorder` runs one recording from Start to the copy.
+- `parse_id` checks a clip id (`<account>/<clips|video>/<folder>...`, plain
+  names only, no `.` or `..`) before it reaches a path or a shell.
+
+The API, with the same guards as every other request:
+
+| Request | Does |
+|---|---|
+| `GET /api/record` | The recording's state: `idle`, `starting`, `recording` (with `elapsed`, `audio`, `limit`), `stopping`, `saving`, `saved` (with `file`) or `failed` (with `error`) |
+| `POST /api/record {"action": "start"\|"stop"}` | Start or stop |
+| `GET /api/clips` | Steam's recordings on the Frame, each with `saved` |
+| `POST /api/clips/export {"id"}` | Starts an export; poll `/api/job` |
+| `POST /api/open {"what": "videos"}` | Opens `~/Videos/SteamFrame` |
+| `GET /api/autosync` | Automatic copying: `screenshots`, `clips`, `since` (the watermark), `checked`, `copied`, `copied_time`, `error`, `paused`, `waiting` (clips still being written) |
+| `POST /api/autosync {"action": "settings", "screenshots", "clips"}` | Turn either on or off; turning it on sets `since` to now |
+| `POST /api/autosync {"action": "now"\|"resume"}` | Copy everything not here yet, once; or resume after running out of space |
+
+They aren't available when the server runs on the Frame itself (the iPhone
+app), since they save to a computer.
+
+Tests: `tests/test_clips.py`, and `tests/test_autosync.py` for automatic
+copying (with a fake headset). They run the recording's shell under bash with a
+stand-in `ffmpeg`, so Stop, the time limit and the clean-up are tested as they
+run on the Frame. Where `ffmpeg` is installed, they also make a 65-second DASH
+recording with Steam's file names and export it with the real `ffmpeg`.
+
+## What hasn't been checked
+
+None of this has run on a Steam Frame yet. In particular:
+
+- That SteamOS's `ffmpeg` can read `@DEFAULT_MONITOR@`. It has the PulseAudio
+  output device (the media player plays through it), so the input is expected,
+  but if it fails the recording is video only, as above.
+- Audio and video sync. Both inputs are stamped with the wall clock, because
+  the camera device and the audio server otherwise count from different clocks.
+- The exact layout of `gamerecordings` on the Frame's SteamOS build, and
+  whether a clip's segments start mid-recording. The parser is deliberately
+  loose about the layout.
+- How much x264 at 1080p30 costs the Frame while a game is running.
+- Automatic copying: that 30 seconds without a write is a safe sign Steam has
+  finished saving a clip, and how a once-a-minute listing feels on the Frame.

docs/scripts.md

@@ -89,6 +89,7 @@ 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/sidequest.md

@@ -24,7 +24,7 @@ No SideQuest implementation code was copied.
 | Installed-app management (launch, uninstall, backup) | List, launch, stop, remove, probe | Already mostly covered. Backup added here. |
 | Update notices / account library | Compatible-version lookup; no source-aware installed update notices | Useful later, medium; needs original version code and source identity recorded on install. |
 | Custom repositories | Built-in F-Droid catalogue and compatible-version indexes | Separate user-repos worker. Legacy SideQuest source has a fixed SideQuestRepos index; arbitrary current custom-repo support was not verified. |
-| Drag-and-drop APK/OBB install | APK drag-and-drop already works | OBB backend added here; future UI can call it. UI drop wiring is not included. |
+| Drag-and-drop APK/OBB install | APK drag-and-drop already works | The [Android backup importer](android-backups.md) now groups the APK and matching OBBs, detects desktop siblings and guides installation and data setup. |
 | Tags, price, headset filters, reviews | Text search and Lepton verdicts, not Quest headset metadata | Useful, medium; search worker owns filters. Keep source headset claims distinct from tested Frame compatibility. |
 | Screenshot/video capture and streaming | Frame screenshots/VR capture already present | Reuse existing tools; do not port Quest capture commands. |
 | Device settings and ADB utilities | Frame/Android display settings, SSH and own-instance tools | Borrow selectively; Quest CPU/GPU presets and wireless-ADB setup do not map directly to Lepton. |
@@ -65,6 +65,8 @@ flow, not evidence of an anonymous download API. It is not implemented here.
 - `search()` raises a user-readable `SourceError` with the browse URL (zero
   limit returns no rows). It does not invent app results or report a false
   “no matching games”. The aggregate search UI should surface this source error.
+  In the app, Discover doesn't link to it; the **Sources** dialog lists SideQuest
+  with a link to its website instead of an on/off switch.
 - `details()` accepts a numeric listing id and returns its canonical page link,
   `downloadable: False`, empty versions/tags/headsets and the `images` shape
   `{icon: None, banner: None, screenshots: []}`. Name is explicitly a listing id;
@@ -83,6 +85,9 @@ local SHA-256 alone must not be called publisher verification.
 
 ## OBB files
 
+For the app's guided APK and OBB import, see [Import an Android game backup](android-backups.md).
+The CLI helper below remains available for a running instance.
+
 ```sh
 python3 ui/frame_android.py install-obb org.example.game main.42.org.example.game.obb
 python3 ui/frame_android.py install-obb org.example.game main.42.org.example.game.obb patch.42.org.example.game.obb

docs/streaming.md

@@ -144,7 +144,7 @@ capture it.
 
 ## Input: type and point in the Frame from the Mac or iPhone
 
-**Built: Home → Keyboard and trackpad**, in every version of Frame Control
+**Built: Home → Type on the headset** (or press `T`), in every version of Frame Control
 (Mac, Windows, Linux, iPhone and iPad), with nothing to install on the device
 you're holding. On a phone the panel is a trackpad (drag to move, tap to click,
 two fingers to scroll, two-finger tap to right-click) plus a text field that

docs/testing.md

@@ -187,13 +187,6 @@ refuses ids with a hyphen (`missing/invalid arguments`), which the fake had
 accepted. The fake now refuses them the same way, and Frame Control makes ids
 Steam accepts.
 
-## Tracking protocols and fake BlueZ
-
-`tests/test_tracking.py` exercises our gaze conversion, OSC sender, HRS parser
-and BlueZ lifecycle with an in-memory fake object tree. It runs in the normal
-unit suite without Bluetooth, GTK or OpenXR. Real Frame results and the absent
-strap/tracker boundaries are recorded in [tracking](tracking.md).
-
 ## Windows test VM
 
 The unit tests run on Windows in CI, but the app itself doesn't. Anything that

docs/tracking.md

@@ -1,329 +0,0 @@
-# Eye tracking and heart rate
-
-Frame Control's own tools run on the Frame, using OpenXR and BlueZ. No
-VRCFaceTracking, LunaHR, Pulsoid or other tracking app is required. This is a
-command-line first version; it does not add a desktop app tab.
-
-## What was checked
-
-**Verified 2026-09-28**, on a real aarch64 Frame running SteamOS 0.4.1,
-BUILD_ID `20260925.6191901`:
-
-| Check | Result |
-|---|---|
-| OpenXR gaze | SteamVR advertises `XR_EXT_eye_gaze_interaction`, `XR_MND_headless` and `XR_KHR_convert_timespec_time`. `supportsEyeGazeInteraction=1`. A headless session reached FOCUSED and produced 269 valid, tracked orientations in the first ten-second probe. |
-| Our gaze → OSC bridge | A separate ten-second run produced 280 valid samples and 280 correctly padded 44-byte `/tracking/eye/CenterPitchYaw` messages at an explicitly configured loopback receiver. Only counters and packet-layout checks were retained. |
-| Bluetooth stack | BlueZ active, adapter powered, central/peripheral roles available. LE discovery started and stopped successfully. No pairing or adapter power settings changed. |
-| Our heart-rate panel | GTK4/GI runs on the stock image. A **synthetic 72 BPM** notification displayed in our X11 window, tagged `STEAM_GAME=2000000027`. Window capture checked; no real heart-rate measurement was taken. |
-| SlimeVR, separate feasibility check | Native aarch64 server v21.1.0 ran with an isolated Temurin 21 JRE, created its driver sockets and accepted a local TCP connection on port 21110. Driver v6.0.0 loaded with all shared libraries resolved; `HmdDriverFactory("IServerTrackedDeviceProvider_004")` returned a non-null provider and error 0. |
-
-![Our heart-rate panel on the Frame, showing synthetic 72 BPM](img/heart-rate-panel.png)
-
-The image is a capture of our own Frame window using a fake notification,
-not a real sensor reading.
-
-**Untested:** a real BLE strap's notifications, physical fit/contact behaviour,
-end-to-end heart-rate display/OSC/log with a strap, avatar response in VRChat,
-gaze accuracy/calibration, coexistence with every immersive app, in-headset
-panel placement, SlimeVR tracker/calibration data and the SlimeVR driver running
-inside SteamVR. No trackers or strap are attached. The driver was loaded in a
-separate process; it was **not registered or activated in SteamVR**. Steam and
-SteamVR were not stopped or restarted.
-
-**Verified blocker resolved:** importing `tkinter` fails because `libtk8.6.so`
-is absent. The panel uses the installed GTK4/GI bindings instead. The Frame's
-OpenXR headers advertise a newer API version than the runtime accepts; our
-reader requests OpenXR 1.0 explicitly.
-
-## Install our tools
-
-From this checkout on your computer, while the Frame is awake:
-
-```sh
-python3 scripts/tracking-on-frame.py install
-```
-
-This copies our Python code and compiles our small C OpenXR reader into
-`~/.local/share/frame-control/tracking/` on the Frame. It uses the Frame's
-existing compiler, OpenXR headers/loader, Python, dbus-python, GI and GTK4.
-Nothing is downloaded, and no sudo, driver registration, system setting,
-service or autostart is added. `FRAME_ALIAS` can select another SSH alias.
-The desktop app/server keeps its existing stdlib-only dependency set.
-
-## Eye tracking → OSC
-
-Start with a ten-second capability/data-availability check:
-
-```sh
-python3 scripts/tracking-on-frame.py gaze --seconds 10
-```
-
-This prints support, session-state numbers and sample counters. It opens no
-OSC socket and prints no gaze coordinates. Exit 0 means at least one valid
-sample, 3 means no valid sample was observed, and 1 means an API/runtime error.
-If there are no valid samples, wake/wear the headset and check its tracking
-setup; a successful capability check alone does not prove usable gaze.
-
-To send to VRChat running **on the Frame**, explicitly enable OSC in VRChat
-and choose its local UDP endpoint:
-
-```sh
-python3 scripts/tracking-on-frame.py gaze --seconds 3600 --osc 127.0.0.1 9000
-```
-
-For a receiver on another computer, replace `127.0.0.1` with that computer's
-IP address and choose its listening port. Addresses are IP literals (IPv4 or
-IPv6); there is no discovery or default destination. Loopback here always
-means **the Frame**, not the computer running the SSH command. OSC uses
-unencrypted UDP: configure only a receiver you intend to receive this data.
-
-**Documented:** [VRChat's eye OSC interface](https://docs.vrchat.com/docs/osc-eye-tracking)
-accepts `/tracking/eye/CenterPitchYaw` with two floats in degrees, positive down
-and right. We locate OpenXR's combined gaze pose relative to VIEW (the head),
-rotate its -Z forward vector and convert that direction to these angles.
-Only active, orientation-valid **and tracked** samples are sent, at up to
-30 Hz. No eyelid/blink, individual-eye or face values are invented. We do not
-send neutral gaze on tracking loss; VRChat's documented timeout restores its
-automatic eye behaviour after input stops.
-
-**Privacy:** gaze is personal data. It stays in process memory and a private
-pipe between our reader and bridge. There is no gaze log option, telemetry,
-OSC receiver or raw gaze on stdout/stderr. Only an explicit `--osc IP PORT`
-opens an output socket. Runtime diagnostics and validity counters are not
-measurements. Stop with Ctrl-C or let `--seconds` expire (maximum 24 hours).
-A lost headless session ends the run; it does not silently reconnect.
-
-## BLE heart rate → our panel, OSC and optional log
-
-First discover/pair your strap in SteamOS's Bluetooth settings. Select that
-strap's Bluetooth address explicitly; our tool does not scan for or connect
-to arbitrary nearby devices.
-
-```sh
-python3 scripts/tracking-on-frame.py heart \
-  --device AA:BB:CC:DD:EE:FF --panel --seconds 3600
-```
-
-This uses BlueZ's standard Heart Rate Service (`180d`) and Heart Rate
-Measurement (`2a37`) notifications. It finds the characteristic only beneath
-the selected device's HRS service. The reader handles 8- and 16-bit BPM,
-contact flags and optional energy/RR fields; energy and RR intervals are
-validated for length but discarded. Zero BPM, reported loss of skin contact,
-malformed packets and readings older than five seconds are not shown as a
-current measurement. A disconnect stops the run; reconnect and start again.
-This is a social/fitness readout, not a medical monitor.
-
-The panel is our GTK4 window on gamescope's X display. Use SteamVR's panel
-controls to float/dock it (see [panels](panels.md)). **Stop**, closing the panel,
-Ctrl-C, SSH hangup or the duration limit ends our subscription. A connection
-that was already open when we started is preserved; a connection we opened
-is disconnected on exit. No Bluetooth power or pairing state is changed.
-
-Add either output explicitly:
-
-```sh
-python3 scripts/tracking-on-frame.py heart \
-  --device AA:BB:CC:DD:EE:FF --panel --seconds 3600 \
-  --osc 127.0.0.1 9000 --address /avatar/parameters/HeartRate \
-  --log /home/steamos/heart-session.csv
-```
-
-The OSC value is integer BPM. `HeartRate` is a chosen avatar parameter, **not a
-built-in VRChat heart-rate feature**; your avatar/receiver must define the
-matching parameter. `--address` can select another literal OSC path. The local
-panel works without OSC, a log or an avatar integration.
-
-The optional CSV contains only `unix_seconds,bpm`. It is created privately
-(mode 0600), refuses existing files/symlinks, and lives **on the Frame** at the
-path you specify. Nothing is logged by default, and heart-rate values are not
-printed to the terminal. Delete your session file when you no longer need it.
-
-### Checking heart rate against a reference
-
-`scripts/heart-check.py` runs on your computer. `listen` shows our OSC
-readings live as they arrive, so you can watch them next to another device:
-
-```sh
-python3 scripts/heart-check.py listen --port 9000 --out ours.csv
-```
-
-Point the Frame at it with `--osc <your computer's IP> 9000`. `compare` lines
-up two recordings by time and reports the mean difference, bias, the share
-within ±5 BPM and the delay between them. It passes when the mean difference
-is at most 5 BPM, at least 80% of reference readings are matched and nothing
-was shown while the sensor reported lost skin contact:
-
-```sh
-python3 scripts/heart-check.py compare ours.csv reference.csv
-python3 scripts/heart-check.py compare ours.csv ~/Downloads/export.zip
-```
-
-The reference can be a CSV (`time,bpm[,flags]`, time in unix seconds or ISO
-8601) or an Apple Health export (`export.zip` or `export.xml`). Only heart-rate
-records within the recording's time range are read. Everything stays on your
-computer.
-
-`scripts/heart-test-strap.swift` turns a Mac into a synthetic strap. It
-advertises the standard Heart Rate Service and sends a fixed, known sequence
-(8-bit and 16-bit values and a skin-contact loss), printing each sent value, so
-`compare` can check that the Frame shows exactly what was sent. It needs
-Bluetooth permission for the process that runs it. **Untested on 2026-09-29:**
-it compiled, but on this Mac, launched from an agent session, macOS never
-delivered a Bluetooth state and no permission prompt appeared, so it never
-advertised.
-
-## Pulse from the eye cameras (experimental)
-
-The Frame has no heart-rate sensor. **Verified 2026-09-29** (SteamOS 0.4.1,
-build `20260925.6191901`): its sensors are an ambient light/proximity sensor
-(`vcnl4000`), a hall sensor (`als31300`), two passthrough cameras
-(`arcimx616`), two tracking cameras (`og01a1b`) and two IR eye cameras
-(`og0ve10`). There is no optical heart-rate (PPG) sensor.
-
-The experiment asks whether the eye cameras can see a pulse anyway. With each
-heartbeat, the blood volume in the skin around the eye changes slightly and
-its IR reflectance changes with it. This is camera-based photoplethysmography;
-near-IR works, though the signal is weaker than in green light.
-
-```sh
-python3 scripts/tracking-on-frame.py pulse --seconds 60 --show
-```
-
-How it works:
-
-- **Capture (verified).** SteamVR ships `eyetracking --calib N`, which saves
-  both eye cameras for N seconds as 400×400 8-bit IR PNGs with a monotonic
-  timestamp per frame, at about 90 fps per eye. SteamVR's live eye tracker,
-  part of `steamvr.service`, gets its frames from the DSP and stops its
-  cameras when the headset is off. Unworn captures ran alongside it: its PID
-  and log were unchanged and our OpenXR gaze session still started
-  afterwards. **Untested:** whether the capture and the live tracker coexist
-  while the headset is worn and tracking.
-- **Privacy.** Each image is reduced to a 16×16 grid of patch averages as
-  soon as it is complete, then deleted. Three worker processes do this beside
-  the capture. If more than 900 images (about five seconds) ever wait, we stop
-  reading them and delete them undecoded until the capture ends, and report
-  an error. The capture directory is removed on exit, even after errors. No image is kept or leaves the Frame. The estimate
-  is printed only with `--show`, and sent or saved only with `--osc` or
-  `--log`, as for the strap.
-- **Estimate.** Patch traces are averaged down to 15 Hz and turned into
-  relative change. A 2-second moving median removes drift and blinks.
-  Patches with frequent spikes (the eyeball and eyelid) are dropped, as are
-  dark or saturated ones. The 20% of patches with the clearest rhythm between
-  42 and 180 BPM are combined in the frequency domain. Output is an overall
-  estimate plus one estimate per second over 15-second windows. A result
-  counts as **clear** only when the top patches agree and the combined signal
-  stands out from the noise. Otherwise the command exits 3 and sends no OSC.
-  `--log` still records the per-second estimates, so a comparison shows how
-  far off an unclear result was.
-  The thresholds are provisional until checked on real wearers.
-
-**Verified on the Frame, unworn, 2026-09-29:** captures of 3,600-5,400 eye
-frames never had more than 8 images on disk, finished a few seconds after the
-capture ended and left no capture directory. **The estimator alone gave a
-false "clear" pulse.** With nobody wearing the headset, five runs reported a
-steady, self-consistent rhythm (90, 90, 93, 94 and 96 BPM; patch agreement
-100%, signal/noise 0.63-0.70), and earlier runs reported 127-129 BPM at lower
-signal/noise. It is a periodic camera or illumination artifact, and its
-frequency drifts between runs. A wearer-less scene cannot contain a pulse, so
-the signal/noise gate cannot tell this artifact from one. Because of that,
-`pulse` reads the Frame's proximity sensor (`vcnl4000`) before and after the
-capture. It reads about 3 unworn (**verified**). If either reading is below 20
-the result is never called clear, nothing is sent over OSC, and the command
-exits 3. **Inferred, unmeasured:** that a worn reading is well above 20; the
-cut-off is provisional until someone wears the headset. If the sensor can't be
-read, the guard is skipped. Confirming a real pulse also needs a reference
-(below).
-
-**Do not interrupt the capture. Verified on the Frame, 2026-09-29:** sending
-SIGTERM to `eyetracking --calib` left the DSP service's eye camera (OV6211)
-stuck "streaming": its log had no "Stopping streaming" line, and every later
-request failed with "Failed to start streaming". Head tracking kept working.
-Clearing it needs the DSP service restarted or the Frame rebooted, so `pulse`
-never signals the tool. After Ctrl-C or a failure it keeps deleting images
-until the tool ends by itself (at most the `--seconds` plus a few seconds),
-and only kills a tool that overruns by 30 s, with a warning that the eye
-cameras may need a reboot. So an interrupted run can take a while to return.
-
-**Verified on synthetic data** (unit tests): a 0.3% brightness pulse in a
-third of the patches, with noise, drift, blinks and eye movement, is
-recovered within 1.5 BPM at 58, 72 and 115 BPM; noise and blinks alone are
-not reported as a pulse. **Not yet verified:** whether a real wearer's eye
-images contain a usable pulse, and how accurate it is. That needs someone
-wearing the headset and a reference, as below.
-
-### Comparing with an Apple Watch
-
-1. On the watch, start a workout (for example **Other**) so it measures heart
-   rate every few seconds rather than occasionally.
-2. Put the Frame on, sit still and look ahead. Run:
-
-   ```sh
-   python3 scripts/tracking-on-frame.py pulse --seconds 120 --show \
-     --log /home/steamos/pulse.csv
-   ```
-
-   The per-second estimates print at the end. Compare them with what the
-   watch showed.
-3. End the workout. On the iPhone, open Health → your picture → **Export All
-   Health Data**, and AirDrop `export.zip` to the Mac.
-4. On the Mac:
-
-   ```sh
-   scp frame:pulse.csv . && ssh frame rm pulse.csv
-   python3 scripts/heart-check.py compare pulse.csv ~/Downloads/export.zip
-   ```
-
-This first version analyses after the capture ends, because the method must
-prove itself before a live panel is worth building. The Apple Watch is a
-reference, not ground truth: in workouts it is typically within a few BPM of
-a chest strap when you are still.
-
-## SlimeVR: feasibility only
-
-SlimeVR is an independent application stack. Neither of our features installs,
-launches or depends on it. Users who want it can follow
-[SlimeVR's setup documentation](https://docs.slimevr.dev/server/index.html).
-The consented upstream releases tested were
-[server v21.1.0](https://github.com/SlimeVR/SlimeVR-Server/releases/tag/v21.1.0)
-and [driver v6.0.0](https://github.com/SlimeVR/SlimeVR-OpenVR-Driver/releases/tag/v6.0.0),
-under SlimeVR's MIT/Apache-2.0 licensing.
-
-**Verified layout, read-only:** the Frame's registered runtime is `/opt/steamvr`;
-its native driver is `drivers/cv/bin/linuxarm64/driver_cv.so`, with a
-`drivers/cv/driver.vrdrivermanifest`. Frame controller manifests/resources are
-under `drivers/frame_controller/`. Configuration is under
-`~/.config/openvr/config/`, not the Steam client's config directory. The
-SlimeVR release also uses `slimevr/bin/linuxarm64/driver_slimevr.so` plus its
-manifest. Nothing in those installed SteamVR directories was changed.
-
-**Inferred:** the matching ABI/layout and standalone factory success make
-SteamVR integration plausible. They do not prove successful driver `Init`,
-server/driver IPC, tracking, or calibration. That needs a separate integration
-check with hardware and an agreed SteamVR restart. No Java executable was on
-PATH for this check, so an isolated JRE was used. SlimeVR's server opens LAN
-listeners; our temporary server was stopped and the temporary downloads,
-configuration and logs were removed. It is not left installed or running.
-
-## Tests and remaining checks
-
-```sh
-python3 -m unittest discover -s tests
-```
-
-`tests/test_tracking.py` covers HRS packet parsing, contact/staleness, OSC
-padding/types and a real loopback socket, quaternion signs, opt-in networking,
-private/exclusive logging and a fake BlueZ object tree. The fake checks service
-ownership, notification routing, delayed GATT discovery and connection cleanup.
-It does not pretend to be a physical strap or a real OpenXR runtime.
-
-Before calling hardware support complete, attach a strap and check BPM against
-its own display/reference, loss of contact, disconnect/reconnect, Stop, OSC and
-CSV together. Check avatar eyes while looking up/down/left/right in a supported
-VRChat session. No third-party tracking app is needed for either test.
-
-Independent review attempt: `devin -p --model swe-2-max` with the frozen diff,
-contribution standards and read-only instructions returned no output for ten
-minutes. It was terminated with exit 143. No completed review or actual model
-identity was returned; hardware checks and independent review remain follow-up
-work before making the draft ready.

docs/vr-apks.md

@@ -94,7 +94,7 @@ A new shortcut is rolled back if artwork fails; failure is never reported as
 an installed app with a blank tile.
 
 Artwork preference is **SteamGridDB → source images → generated fallback**.
-Set the optional free key in Frame Control's **Library artwork settings**, or
+Set the optional free key in Frame Control's **Settings → Library artwork**, or
 `STEAMGRIDDB_API_KEY` (`FRAME_STEAMGRIDDB_API_KEY` also works). Environment
 settings override the saved key. Without a key there are no provider calls or
 warnings. Saved keys stay in host app data, mode 0600 on POSIX, and are never

docs/vr-utilities.md

@@ -11,7 +11,7 @@ checks below. The PR stays draft.
 
 ## Our performance HUD
 
-On **Home → VR comfort and performance**, the app shows a timestamped sample
+On **Home → VR performance** (folded until you open it), the app shows a timestamped sample
 with each status refresh (30 seconds, or Refresh). **Open HUD in headset**
 starts our text HUD as a gamescope panel, refreshed every two seconds. In the
 SteamVR dashboard, select **Frame Control HUD**, then Float in World or dock
@@ -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.

docs/vr-video.md

@@ -6,7 +6,7 @@ is required.** Chromium and immersive WebXR are not in this playback path.
 
 ## Use it
 
-In **Tools → Media in the headset**, send a file, choose its layout and press
+In **Tools → Media player** (or **Play a video or photo** on Home), send a file, choose its layout and press
 **Play**. **Theatre** gives it a larger screen and an 85% black surround.
 **Stop** removes both. Refresh reads the library and the player's state.
 The screen follows your head; it isn't a saved world-space panel.

frame/tracking/gaze.c

@@ -1,135 +0,0 @@
-/* Frame Control's OpenXR gaze source. No values on stdout/stderr or disk.
- * The Python bridge supplies a private pipe with --fd; standalone probes only
- * report counters. Uses a headless session, never submits frames or takes focus. */
-#define XR_USE_TIMESPEC
-#include <time.h>
-#include <openxr/openxr.h>
-#include <openxr/openxr_platform.h>
-#include <signal.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <unistd.h>
-
-static volatile sig_atomic_t stopped;
-static void stop(int sig) { (void)sig; stopped = 1; }
-#define CHECK(call) do { result = (call); if (XR_FAILED(result)) { \
-    fprintf(stderr, "%s failed (%d)\n", #call, result); goto cleanup; } } while (0)
-
-int main(int argc, char **argv) {
-    int seconds = 10, fd = -1, running = 0, rc = 1;
-    unsigned active = 0, valid = 0, samples = 0;
-    for (int i = 1; i < argc; i++) {
-        if (!strcmp(argv[i], "--seconds") && i+1 < argc) seconds = atoi(argv[++i]);
-        else if (!strcmp(argv[i], "--fd") && i+1 < argc) fd = atoi(argv[++i]);
-        else { fprintf(stderr, "usage: gaze [--seconds 1..86400] [--fd private-pipe]\n"); return 2; }
-    }
-    if (seconds < 1 || seconds > 86400 || (fd != -1 && fd < 3)) return 2;
-    FILE *out = fd == -1 ? NULL : fdopen(fd, "w");
-    if (fd != -1 && !out) return 2;
-    signal(SIGINT, stop); signal(SIGTERM, stop); signal(SIGHUP, stop); signal(SIGPIPE, SIG_IGN);
-    XrResult result;
-    XrInstance instance = XR_NULL_HANDLE;
-    XrSession session = XR_NULL_HANDLE;
-    XrActionSet set = XR_NULL_HANDLE;
-    XrSpace gaze = XR_NULL_HANDLE, view = XR_NULL_HANDLE;
-    const char *extensions[] = {"XR_EXT_eye_gaze_interaction", "XR_MND_headless", "XR_KHR_convert_timespec_time"};
-    XrInstanceCreateInfo create = {.type = XR_TYPE_INSTANCE_CREATE_INFO};
-    strcpy(create.applicationInfo.applicationName, "Frame Control gaze");
-    create.applicationInfo.apiVersion = XR_MAKE_VERSION(1, 0, 0);
-    create.enabledExtensionCount = 3; create.enabledExtensionNames = extensions;
-    CHECK(xrCreateInstance(&create, &instance));
-    XrSystemGetInfo get = {.type = XR_TYPE_SYSTEM_GET_INFO, .formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY};
-    XrSystemId system;
-    CHECK(xrGetSystem(instance, &get, &system));
-    XrSystemEyeGazeInteractionPropertiesEXT eye = {.type = XR_TYPE_SYSTEM_EYE_GAZE_INTERACTION_PROPERTIES_EXT};
-    XrSystemProperties props = {.type = XR_TYPE_SYSTEM_PROPERTIES, .next = &eye};
-    CHECK(xrGetSystemProperties(instance, system, &props));
-    printf("supportsEyeGazeInteraction=%u\n", eye.supportsEyeGazeInteraction);
-    if (!eye.supportsEyeGazeInteraction) goto cleanup;
-    XrSessionCreateInfo sc = {.type = XR_TYPE_SESSION_CREATE_INFO, .systemId = system};
-    CHECK(xrCreateSession(instance, &sc, &session));
-    XrActionSetCreateInfo asc = {.type = XR_TYPE_ACTION_SET_CREATE_INFO};
-    strcpy(asc.actionSetName, "gaze"); strcpy(asc.localizedActionSetName, "Gaze");
-    CHECK(xrCreateActionSet(instance, &asc, &set));
-    XrActionCreateInfo ac = {.type = XR_TYPE_ACTION_CREATE_INFO, .actionType = XR_ACTION_TYPE_POSE_INPUT};
-    strcpy(ac.actionName, "gaze_pose"); strcpy(ac.localizedActionName, "Gaze pose");
-    XrAction action;
-    CHECK(xrCreateAction(set, &ac, &action));
-    XrPath profile, input;
-    CHECK(xrStringToPath(instance, "/interaction_profiles/ext/eye_gaze_interaction", &profile));
-    CHECK(xrStringToPath(instance, "/user/eyes_ext/input/gaze_ext/pose", &input));
-    XrActionSuggestedBinding binding = {action, input};
-    XrInteractionProfileSuggestedBinding suggested = {.type = XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING,
-        .interactionProfile = profile, .countSuggestedBindings = 1, .suggestedBindings = &binding};
-    CHECK(xrSuggestInteractionProfileBindings(instance, &suggested));
-    XrSessionActionSetsAttachInfo attach = {.type = XR_TYPE_SESSION_ACTION_SETS_ATTACH_INFO, .countActionSets = 1, .actionSets = &set};
-    CHECK(xrAttachSessionActionSets(session, &attach));
-    XrActionSpaceCreateInfo space = {.type = XR_TYPE_ACTION_SPACE_CREATE_INFO, .action = action, .poseInActionSpace.orientation.w = 1};
-    CHECK(xrCreateActionSpace(session, &space, &gaze));
-    XrReferenceSpaceCreateInfo ref = {.type = XR_TYPE_REFERENCE_SPACE_CREATE_INFO, .referenceSpaceType = XR_REFERENCE_SPACE_TYPE_VIEW,
-        .poseInReferenceSpace.orientation.w = 1};
-    CHECK(xrCreateReferenceSpace(session, &ref, &view));
-    PFN_xrConvertTimespecTimeToTimeKHR convert;
-    CHECK(xrGetInstanceProcAddr(instance, "xrConvertTimespecTimeToTimeKHR", (PFN_xrVoidFunction *)&convert));
-    struct timespec start, now;
-    clock_gettime(CLOCK_MONOTONIC, &start);
-    while (!stopped) {
-        clock_gettime(CLOCK_MONOTONIC, &now);
-        if (now.tv_sec - start.tv_sec >= seconds) break;
-        XrEventDataBuffer event = {.type = XR_TYPE_EVENT_DATA_BUFFER};
-        while ((result = xrPollEvent(instance, &event)) == XR_SUCCESS) {
-            if (event.type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED) {
-                XrSessionState state = ((XrEventDataSessionStateChanged *)&event)->state;
-                printf("sessionState=%d\n", state); fflush(stdout);
-                if (state == XR_SESSION_STATE_READY && !running) {
-                    XrSessionBeginInfo begin = {.type = XR_TYPE_SESSION_BEGIN_INFO, .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO};
-                    CHECK(xrBeginSession(session, &begin)); running = 1;
-                } else if (state == XR_SESSION_STATE_STOPPING) {
-                    CHECK(xrEndSession(session)); running = 0; stopped = 1;
-                } else if (state == XR_SESSION_STATE_EXITING || state == XR_SESSION_STATE_LOSS_PENDING) stopped = 1;
-            } else if (event.type == XR_TYPE_EVENT_DATA_INSTANCE_LOSS_PENDING) stopped = 1;
-            event.type = XR_TYPE_EVENT_DATA_BUFFER;
-        }
-        if (XR_FAILED(result)) goto cleanup;
-        if (running && !stopped) {
-            XrActiveActionSet activeSet = {set, XR_NULL_PATH};
-            XrActionsSyncInfo sync = {.type = XR_TYPE_ACTIONS_SYNC_INFO, .countActiveActionSets = 1, .activeActionSets = &activeSet};
-            CHECK(xrSyncActions(session, &sync));
-            if (result != XR_SUCCESS) {
-                struct timespec delay = {.tv_nsec = 33333333};
-                nanosleep(&delay, NULL);
-                continue; /* No stale gaze when the runtime denies focus. */
-            }
-            XrActionStateGetInfo ag = {.type = XR_TYPE_ACTION_STATE_GET_INFO, .action = action};
-            XrActionStatePose pose = {.type = XR_TYPE_ACTION_STATE_POSE};
-            CHECK(xrGetActionStatePose(session, &ag, &pose));
-            samples++;
-            if (pose.isActive) {
-                active++;
-                XrTime time; CHECK(convert(instance, &now, &time));
-                XrSpaceLocation location = {.type = XR_TYPE_SPACE_LOCATION};
-                CHECK(xrLocateSpace(gaze, view, time, &location));
-                XrSpaceLocationFlags needed = XR_SPACE_LOCATION_ORIENTATION_VALID_BIT | XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT;
-                if ((location.locationFlags & needed) == needed) {
-                    valid++;
-                    if (out) {
-                        XrQuaternionf q = location.pose.orientation;
-                        if (fprintf(out, "%g %g %g %g\n", q.x, q.y, q.z, q.w) < 0 || fflush(out)) goto cleanup;
-                    }
-                }
-            }
-        }
-        struct timespec delay = {.tv_nsec = 33333333}; nanosleep(&delay, NULL);
-    }
-    printf("samples=%u active=%u valid=%u\n", samples, active, valid);
-    rc = valid ? 0 : 3; /* Distinguish a working session from observed gaze. */
-cleanup:
-    if (view) xrDestroySpace(view);
-    if (gaze) xrDestroySpace(gaze);
-    if (session) xrDestroySession(session);
-    if (set) xrDestroyActionSet(set);
-    if (instance) xrDestroyInstance(instance);
-    if (out) fclose(out);
-    return rc;
-}

frame/tracking/pulse.py

@@ -1,481 +0,0 @@
-"""Experimental pulse estimate from the Frame's IR eye-tracking cameras.
-
-Skin brightens and darkens very slightly with each heartbeat as blood volume
-changes (photoplethysmography). The eye cameras film the skin around each eye
-under steady IR light at about 90 frames per second, so that rhythm may be
-visible in the average brightness of small patches of skin.
-
-Capture uses SteamVR's own `eyetracking --calib` mode, which writes PNG pairs
-to /tmp. Each image is reduced to a grid of patch averages the moment it is
-complete, then deleted; the capture directory is removed on exit. No image
-leaves the Frame or outlives the run. This is an experiment, not a medical
-measurement.
-"""
-from array import array
-import bisect
-import cmath
-import json
-import math
-import os
-from pathlib import Path
-import re
-import shutil
-import subprocess
-import time
-
-ET_DIR = Path("/opt/steamvr/tools/eyetracking")
-ET_BIN = ET_DIR / "bin/linuxarm64/eyetracking"
-ET_WEIGHTS = ET_DIR / "resources/et_dsp_20250610_03136.weights"
-GRID = 16        # 16 × 16 patches of 25 × 25 pixels on the 400 × 400 image
-RATE = 15.0      # analysis sample rate, Hz; the band of interest ends at 3 Hz
-LOW, HIGH = 42.0, 180.0  # BPM search band
-# The Frame's proximity sensor (vcnl4000) reads about 3 with nobody wearing it.
-# A worn reading has not been measured yet, so the cut-off is provisional.
-IIO = Path("/sys/bus/iio/devices")
-WORN_MIN = 20.0
-WINDOW = 15.0    # seconds per windowed estimate
-
-
-# ---------------------------------------------------------------- capture ---
-
-def grid_means(pixels, width, height, stride, channels, grid=GRID):
-    """Average of channel 0 in each of grid × grid equal patches."""
-    bw, bh = width // grid, height // grid
-    sums = [0] * (grid * grid)
-    for y in range(bh * grid):
-        start = y * stride
-        row = pixels[start:start + width * channels:channels]
-        base = (y // bh) * grid
-        for bx in range(grid):
-            sums[base + bx] += sum(row[bx * bw:(bx + 1) * bw])
-    area = bw * bh
-    return [s / area for s in sums]
-
-
-def load_grid(path):
-    import gi
-    gi.require_version("GdkPixbuf", "2.0")
-    from gi.repository import GdkPixbuf
-    image = GdkPixbuf.Pixbuf.new_from_file(str(path))
-    return grid_means(image.read_pixel_bytes().get_data(), image.get_width(), image.get_height(),
-                      image.get_rowstride(), image.get_n_channels())
-
-
-def reduce_file(loader, path):
-    """Reduce one image to its patch grid and delete it, whatever happens."""
-    try:
-        return loader(path)
-    finally:
-        os.unlink(path)
-
-
-class Capture:
-    """Run SteamVR's eye-camera capture and reduce frames as they arrive."""
-    NAME = re.compile(r"^(left|right)_(\d+)\.png$")
-    # Only SteamVR's own capture directories are read and removed.
-    PREFIX = "/tmp/etcalib_"
-    # Printed by the capture tool; its output is only flushed when it exits.
-    WRITING = re.compile(r"Writing capture to: (\S+)")
-    # About five seconds of frames (~65 MB in RAM-backed /tmp). If reduction
-    # falls further behind than this, the capture stops rather than letting
-    # eye images pile up.
-    MAX_BACKLOG = 900
-
-    def __init__(self, seconds, runner=subprocess.Popen, loader=load_grid, workers=3):
-        self.seconds, self.runner, self.loader, self.workers = seconds, runner, loader, workers
-        self.grids = {"left": {}, "right": {}}
-        self.directory = None
-        self.pool = None
-        self.submitted = set()
-        self.futures = {}
-        self.new = set()  # every capture directory that appeared during our run
-        self.before = None  # capture directories that existed before the run
-        self.log = None
-
-    def candidates(self):
-        parent, stem = os.path.split(self.PREFIX)
-        return {Path(entry.path) for entry in os.scandir(parent)
-                if entry.name.startswith(stem) and entry.is_dir(follow_symlinks=False)}
-
-    def run(self):
-        # The capture tool's output goes to a private temporary file, read for
-        # failure messages. It is block-buffered, so the capture directory is
-        # found by watching for a new one rather than waiting for its name.
-        import tempfile
-        self.before = before = self.candidates()
-        process = None
-        with tempfile.TemporaryFile("w+") as log:
-            self.log = log
-            try:
-                if self.workers:
-                    # SteamVR pins its eye tracker to cores 0-1; decoding runs beside it.
-                    import concurrent.futures
-                    import multiprocessing
-                    self.pool = concurrent.futures.ProcessPoolExecutor(
-                        self.workers, mp_context=multiprocessing.get_context("fork"))
-                process = self.runner([str(ET_BIN), "-b", "CDSP", "-w", str(ET_WEIGHTS), "--calib", str(self.seconds)],
-                                      cwd=str(ET_BIN.parent), stdout=log, stderr=subprocess.STDOUT)
-                deadline = time.monotonic() + self.seconds + 30
-                while True:
-                    # Checked on every poll: a second capture directory means
-                    # we can't tell which images are ours, so stop.
-                    self.new |= self.candidates() - before
-                    if len(self.new) > 1:
-                        raise RuntimeError("another eye-camera capture is running")
-                    if not self.directory and self.new:
-                        self.directory = next(iter(self.new))
-                    finished = process.poll() is not None
-                    self.reduce(final=finished)
-                    if finished:
-                        break
-                    if time.monotonic() > deadline:
-                        raise RuntimeError("eye-camera capture did not finish")
-                    time.sleep(0.02)
-                log.seek(0)
-                text = log.read()
-                if process.returncode or not self.directory:
-                    reason = "cameras unavailable" if "Failed to" in text else f"exit {process.returncode}"
-                    raise RuntimeError(f"eye-camera capture failed ({reason})")
-                named = self.written(log)
-                if named and named != self.directory:
-                    raise RuntimeError("the capture wrote somewhere else; not using those images")
-                return self.frames()
-            finally:
-                # Each step runs even if an earlier one failed: eye images must
-                # be removed whatever else went wrong.
-                # Ctrl-C and SIGTERM (raised as KeyboardInterrupt) are held
-                # until the images are gone, then re-raised.
-                interrupted, failed = None, None
-                for step in (lambda: self.finish(process),
-                             lambda: self.pool and self.pool.shutdown(wait=True, cancel_futures=True),
-                             self.adopt_reported):
-                    try:
-                        step()
-                    except BaseException as error:
-                        if isinstance(error, Exception):
-                            failed = failed or error
-                        else:
-                            interrupted = interrupted or error
-                self.log = None
-                self.remove()
-                if interrupted:
-                    raise interrupted
-                if failed:
-                    raise RuntimeError(f"the eye-camera capture did not stop cleanly: {failed}")
-
-    def finish(self, process):
-        """Let the capture tool end by itself, deleting its images meanwhile.
-
-        Never signal it: stopping the tool early leaves the headset's eye
-        camera stuck streaming until the DSP service restarts (verified on the
-        Frame with SIGTERM). Its run is bounded by `seconds`, so waiting is
-        short. Only if it overruns by a wide margin is it killed."""
-        if not process:
-            return
-        interrupted = None
-        give_up = time.monotonic() + self.seconds + 30
-        while True:
-            try:
-                if process.poll() is not None:
-                    break
-                self.discard()
-                if time.monotonic() > give_up:
-                    process.kill()
-                    process.wait()
-                    raise RuntimeError("the eye-camera capture had to be killed; "
-                                       "the eye cameras may need a reboot to stream again")
-                time.sleep(0.05)
-            except KeyboardInterrupt as error:  # keep cleaning up until it ends
-                interrupted = interrupted or error
-        if interrupted:
-            raise interrupted
-
-    def discard(self):
-        """Delete the eye images written so far, without reading them."""
-        if self.before is not None:
-            self.new |= self.candidates() - self.before
-        for directory in self.new | ({self.directory} if self.directory else set()):
-            if str(directory).startswith(self.PREFIX) and directory.is_dir() and not directory.is_symlink():
-                for entry in os.scandir(directory):
-                    if self.NAME.match(entry.name):
-                        try:
-                            os.unlink(entry.path)
-                        except OSError:
-                            pass
-
-    def adopt_reported(self):
-        """The directory the tool reported is ours by its own account."""
-        named = self.written(self.log)
-        if named and str(named).startswith(self.PREFIX):
-            self.new.add(named)
-
-    def written(self, log):
-        """The directory the capture tool reported, once its output is flushed."""
-        log.seek(0)
-        match = self.WRITING.search(log.read())
-        return Path(match.group(1)) if match else None
-
-    def reduce(self, final=False):
-        """Reduce and delete every complete image; an image is complete once a
-        later one of the same eye exists, or the capture has ended."""
-        if not self.directory or not self.directory.is_dir():
-            return
-        pending = {"left": [], "right": []}
-        for entry in os.scandir(self.directory):
-            match = self.NAME.match(entry.name)
-            if match:
-                pending[match.group(1)].append((int(match.group(2)), entry.path))
-        if sum(len(files) for files in pending.values()) > self.MAX_BACKLOG:
-            raise RuntimeError("eye-image processing fell behind; capture abandoned")
-        for eye, files in pending.items():
-            files.sort()
-            ready = files if final else files[:-1]
-            for index, path in ready:
-                if path in self.submitted:
-                    continue
-                self.submitted.add(path)
-                if self.pool:
-                    self.futures[(eye, index)] = self.pool.submit(reduce_file, self.loader, path)
-                else:
-                    self.grids[eye][index] = array("f", reduce_file(self.loader, path))
-        for key, future in list(self.futures.items()):
-            if final or future.done():
-                self.grids[key[0]][key[1]] = array("f", future.result())
-                del self.futures[key]
-
-    def frames(self):
-        """[(monotonic seconds, eye, grid)] joined with the capture metadata."""
-        meta = json.loads((self.directory / "meta.json").read_text())
-        frames = []
-        for pair in meta["frames"]:
-            for eye in ("left", "right"):
-                info = pair.get(eye) or {}
-                match = self.NAME.match(Path(info.get("fname", "")).name)
-                grid = self.grids[eye].get(int(match.group(2))) if match else None
-                if info.get("valid") and grid is not None:
-                    frames.append((float(info["tsMono"]), eye, grid))
-        return frames
-
-    def remove(self):
-        """Remove every capture directory that appeared during the run. Eye
-        images must not outlive it, so a failure to delete is an error."""
-        left = []
-        if self.before is not None:
-            try:
-                self.new |= self.candidates() - self.before  # even if interrupted before the first poll
-            except OSError:
-                pass
-        for directory in self.new | ({self.directory} if self.directory else set()):
-            if str(directory).startswith(self.PREFIX) and directory.is_dir() and not directory.is_symlink():
-                try:
-                    shutil.rmtree(directory)
-                except OSError:
-                    left.append(str(directory))
-        if left:
-            raise RuntimeError("could not delete eye images in " + ", ".join(sorted(left)))
-
-
-# --------------------------------------------------------------- analysis ---
-
-def fft(values):
-    """In-place iterative radix-2 FFT of a list whose length is a power of 2."""
-    n = len(values)
-    a = list(values)
-    j = 0
-    for i in range(1, n):
-        bit = n >> 1
-        while j & bit:
-            j ^= bit
-            bit >>= 1
-        j |= bit
-        if i < j:
-            a[i], a[j] = a[j], a[i]
-    size = 2
-    while size <= n:
-        step = cmath.exp(-2j * math.pi / size)
-        half = size // 2
-        for start in range(0, n, size):
-            w = 1
-            for k in range(start, start + half):
-                t = w * a[k + half]
-                a[k + half] = a[k] - t
-                a[k] += t
-                w *= step
-        size *= 2
-    return a
-
-
-def resample(times, values, rate=RATE):
-    """Average samples into 1/rate bins from the first sample; empty bins are
-    filled from the previous bin."""
-    if not times:
-        return []
-    start = times[0]
-    count = int((times[-1] - start) * rate) + 1
-    sums, counts = [0.0] * count, [0] * count
-    for t, v in zip(times, values):
-        i = min(int((t - start) * rate), count - 1)
-        sums[i] += v
-        counts[i] += 1
-    out, last = [], None
-    for s, c in zip(sums, counts):
-        last = s / c if c else last
-        out.append(last)
-    first = next(v for v in out if v is not None)
-    return [first if v is None else v for v in out]
-
-
-def clean(signal, rate=RATE):
-    """Relative change with slow drift removed; None if the patch is mostly
-    blinks or eye movement. Spikes (blinks, saccades) become gaps at the
-    local level rather than clipped steps, which would add false rhythm."""
-    mean = sum(signal) / len(signal)
-    x = [v / mean - 1 for v in signal]
-    half = int(rate)  # 2-second centred moving median removes drift and blinks
-    trend = []
-    for i in range(len(x)):
-        chunk = sorted(x[max(0, i - half):i + half + 1])
-        trend.append(chunk[len(chunk) // 2])
-    residual = [v - m for v, m in zip(x, trend)]
-    mad = sorted(abs(v) for v in residual)[len(residual) // 2] or 1e-9
-    limit = 4 * 1.4826 * mad
-    spikes = sum(1 for v in residual if abs(v) > limit)
-    if spikes > 0.05 * len(residual):
-        return None
-    return [v if abs(v) <= limit else 0.0 for v in residual]
-
-
-def spectrum(signal, rate=RATE):
-    """[(bpm, power)] within the search band, Hann-windowed and zero-padded."""
-    n = len(signal)
-    size = 1
-    while size < max(n * 4, 256):
-        size *= 2
-    window = [0.5 - 0.5 * math.cos(2 * math.pi * i / (n - 1)) for i in range(n)] if n > 1 else [1.0]
-    padded = [s * w for s, w in zip(signal, window)] + [0.0] * (size - n)
-    result = fft(padded)
-    out = []
-    for k in range(size // 2):
-        bpm = k * rate / size * 60
-        if LOW <= bpm <= HIGH:
-            out.append((bpm, abs(result[k]) ** 2))
-    return out
-
-
-def peak(spec):
-    """Peak BPM with parabolic interpolation between spectral bins."""
-    i = max(range(len(spec)), key=lambda k: spec[k][1])
-    if 0 < i < len(spec) - 1:
-        a, b, c = spec[i - 1][1], spec[i][1], spec[i + 1][1]
-        denominator = a - 2 * b + c
-        offset = 0.5 * (a - c) / denominator if denominator else 0.0
-        return spec[i][0] + offset * (spec[1][0] - spec[0][0])
-    return spec[i][0]
-
-
-def snr(spec, bpm, width=4.0):
-    """Power near the pulse and its first harmonic against the rest of the band."""
-    near = sum(p for f, p in spec if abs(f - bpm) <= width or abs(f - 2 * bpm) <= width)
-    rest = sum(p for f, p in spec) - near
-    if near <= 0:
-        return 0.0
-    return near / rest if rest > 0 else float("inf")
-
-
-def normalised(spec):
-    total = sum(p for _, p in spec) or 1.0
-    return [p / total for _, p in spec]
-
-
-def usable(values):
-    """Patches that are neither dark nor saturated for the whole recording."""
-    mean = sum(values) / len(values)
-    return 8 <= mean <= 245
-
-
-def estimate(times, patches, rate=RATE, share=0.2, window=WINDOW):
-    """Estimate pulse from patch brightness traces.
-
-    times: monotonic seconds per frame. patches: {name: [brightness per frame]}.
-    Selects the share of usable patches with the clearest periodic signal,
-    combines their spectra and reports the overall and windowed estimates.
-    """
-    cleaned = {}
-    for name, values in patches.items():
-        if usable(values):
-            signal = clean(resample(times, values, rate), rate)
-            if signal is not None and any(signal):  # flat patches carry no rhythm
-                cleaned[name] = signal
-    if not cleaned or len(next(iter(cleaned.values()))) < rate * 8:
-        raise ValueError("need at least 8 seconds of usable eye-camera frames")
-    quality = []
-    for name, signal in cleaned.items():
-        spec = spectrum(signal, rate)
-        own = peak(spec)
-        quality.append((snr(spec, own), name, own, spec))
-    quality.sort(reverse=True)
-    chosen = quality[:max(4, int(len(quality) * share))]
-    combined = [sum(values) for values in zip(*(normalised(spec) for _, _, _, spec in chosen))]
-    bins = [f for f, _ in chosen[0][3]]
-    bpm = peak(list(zip(bins, combined)))
-    top = chosen[:8]
-    agree = sum(1 for _, _, own, _ in top if abs(own - bpm) <= 5) / len(top)
-    series = []
-    samples = int(window * rate)
-    length = len(next(iter(cleaned.values())))
-    for end in range(samples, length + 1, int(rate)):
-        specs = [spectrum(cleaned[name][end - samples:end], rate) for _, name, _, _ in chosen]
-        total = [sum(values) for values in zip(*(normalised(s) for s in specs))]
-        window_bins = [f for f, _ in specs[0]]
-        series.append((times[0] + end / rate, peak(list(zip(window_bins, total)))))
-    return {
-        "bpm": bpm,
-        "agreement": agree,
-        "patches": len(chosen),
-        "usable": len(cleaned),
-        "snr": snr(list(zip(bins, combined)), bpm),
-        "series": series,
-    }
-
-
-def analyse(frames):
-    """Estimate from Capture.frames(); both eyes' patches are analysed together
-    on a shared time base, each sample taken from that eye's nearest frame."""
-    times = sorted({t for t, _, _ in frames})
-    patches = {}
-    for eye in ("left", "right"):
-        eye_frames = sorted((t, grid) for t, e, grid in frames if e == eye)
-        if not eye_frames:
-            continue
-        eye_times = [t for t, _ in eye_frames]
-        nearest = []
-        for t in times:
-            i = bisect.bisect_left(eye_times, t)
-            if i == len(eye_times) or (i > 0 and t - eye_times[i - 1] <= eye_times[i] - t):
-                i -= 1
-            nearest.append(i)
-        for k in range(len(eye_frames[0][1])):
-            patches[f"{eye}{k}"] = [eye_frames[i][1][k] for i in nearest]
-    return estimate(times, patches)
-
-
-def proximity(root=None):
-    """The headset's proximity reading, or None if it can't be read."""
-    try:
-        for device in sorted(Path(root or IIO).glob("iio:device*")):
-            if (device / "name").read_text().strip() == "vcnl4000":
-                return float((device / "in_proximity_raw").read_text())
-    except (OSError, ValueError):
-        pass
-    return None
-
-
-def worn(reading):
-    """False only when the sensor says the headset is not on a face."""
-    return reading is None or reading >= WORN_MIN
-
-
-def reliable(result):
-    """Whether the estimate is clear enough to show as a reading. Thresholds
-    are provisional until checked against a reference on a real wearer."""
-    return result["agreement"] >= 0.75 and result["snr"] >= 0.5

frame/tracking/tracking.py

@@ -1,438 +0,0 @@
-#!/usr/bin/env python3
-"""Frame-local tracking tools. No network destination or data log by default."""
-import argparse
-import math
-import os
-from pathlib import Path
-import signal
-import socket
-import struct
-import subprocess
-import time
-
-
-class TrackingError(RuntimeError):
-    """A safe, actionable status message containing no sensor data."""
-
-
-HRS = "0000180d-0000-1000-8000-00805f9b34fb"
-MEASUREMENT = "00002a37-0000-1000-8000-00805f9b34fb"
-DEVICE = "org.bluez.Device1"
-SERVICE = "org.bluez.GattService1"
-CHARACTERISTIC = "org.bluez.GattCharacteristic1"
-
-
-def heart_rate(data):
-    """Validate the Bluetooth HRS measurement, returning BPM/contact only.
-
-    Energy and RR intervals are checked for length but never retained.
-    None means contact is supported and the strap reports no skin contact.
-    """
-    data = bytes(data)
-    if len(data) < 2 or data[0] & 0xe0:
-        raise ValueError("invalid HRS measurement")
-    flags = data[0]
-    size = 2 if flags & 1 else 1
-    end = 1 + size + (2 if flags & 8 else 0)
-    if len(data) < end:
-        raise ValueError("truncated HRS measurement")
-    extra = len(data) - end
-    if (flags & 16 and (extra < 2 or extra % 2)) or (not flags & 16 and extra):
-        raise ValueError("invalid HRS optional fields")
-    if flags & 4 and not flags & 2:
-        return None
-    bpm = int.from_bytes(data[1:1 + size], "little")
-    return bpm if bpm else None
-
-
-def gaze_angles(quaternion):
-    """OpenXR head-relative -Z forward → VRChat degrees, down/right positive."""
-    if len(quaternion) != 4 or not all(math.isfinite(v) for v in quaternion):
-        raise ValueError("invalid gaze orientation")
-    norm = math.sqrt(sum(v * v for v in quaternion))
-    if not 0.9 < norm < 1.1:
-        raise ValueError("invalid gaze orientation")
-    x, y, z, w = (v / norm for v in quaternion)
-    # Rotate OpenXR's forward vector (0, 0, -1) into VIEW space.
-    dx, dy, dz = -2 * (x*z + w*y), 2 * (w*x - y*z), 2 * (x*x + y*y) - 1
-    return math.degrees(math.atan2(-dy, math.hypot(dx, dz))), math.degrees(math.atan2(dx, -dz))
-
-
-def osc_message(address, values):
-    if not address.startswith("/") or any(c.isspace() or c in '\0#*,?[]{}' for c in address):
-        raise ValueError("OSC address must be a literal path")
-    def string(value):
-        encoded = value.encode("utf-8") + b"\0"
-        return encoded + b"\0" * (-len(encoded) % 4)
-    tags, payload = ",", b""
-    for value in values:
-        if type(value) is int:
-            tags += "i"
-            payload += struct.pack(">i", value)
-        else:
-            if not math.isfinite(value):
-                raise ValueError("OSC value must be finite")
-            tags += "f"
-            payload += struct.pack(">f", value)
-    return string(address) + string(tags) + payload
-
-
-class Osc:
-    def __init__(self, endpoint=None):
-        self.sock = None
-        self.target = None
-        if endpoint:
-            import ipaddress
-            address = ipaddress.ip_address(endpoint[0])
-            port = int(endpoint[1])
-            if address.is_unspecified or address.is_multicast or not 1 <= port <= 65535:
-                raise ValueError("OSC needs a unicast IP address and port 1..65535")
-            self.sock = socket.socket(socket.AF_INET6 if address.version == 6 else socket.AF_INET, socket.SOCK_DGRAM)
-            self.target = (str(address), port)
-
-    def send(self, address, values):
-        if self.sock:
-            self.sock.sendto(osc_message(address, values), self.target)
-
-    def close(self):
-        if self.sock:
-            self.sock.close()
-
-
-class HeartSession:
-    def __init__(self, osc, address, log=None, clock=time.monotonic):
-        self.osc, self.address, self.clock = osc, address, clock
-        self.bpm, self.updated = None, None
-        self.log = None
-        if log:
-            # Exclusive creation refuses existing files and symlinks; mode is
-            # private even with a permissive process umask.
-            fd = os.open(log, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
-            self.log = os.fdopen(fd, "w")
-            self.log.write("unix_seconds,bpm\n")
-
-    def notification(self, data):
-        self.bpm = heart_rate(data)
-        self.updated = self.clock()
-        if self.bpm is not None:
-            self.osc.send(self.address, [self.bpm])
-            if self.log:
-                self.log.write(f"{time.time():.3f},{self.bpm}\n")
-                self.log.flush()
-
-    def current(self):
-        if self.updated is None or self.clock() - self.updated > 5:
-            return None
-        return self.bpm
-
-    def close(self):
-        if self.log:
-            self.log.close()
-
-
-class BluezHeart:
-    """One explicitly selected, already discovered strap; no ambient scan."""
-    def __init__(self, bus, interface, address, on_value):
-        self.bus, self.interface, self.on_value = bus, interface, on_value
-        self.device = self.characteristic = None
-        self.connected_here = False
-        self.notifying = False
-        self.match = None
-        objects = self.objects()
-        matches = [path for path, interfaces in objects.items()
-                   if str(interfaces.get(DEVICE, {}).get("Address", "")).upper() == address.upper()]
-        if len(matches) != 1:
-            raise TrackingError("Strap not found uniquely in BlueZ; pair/discover it in SteamOS Bluetooth settings first")
-        self.device = matches[0]
-        self.match = bus.add_signal_receiver(self.changed, signal_name="PropertiesChanged",
-                                            dbus_interface="org.freedesktop.DBus.Properties",
-                                            bus_name="org.bluez", path_keyword="path")
-        try:
-            if not objects[self.device][DEVICE].get("Connected"):
-                self.call(self.device, DEVICE).Connect(timeout=20)
-                self.connected_here = True
-        except Exception:
-            self.close()
-            raise
-
-    def objects(self):
-        return self.call("/", "org.freedesktop.DBus.ObjectManager").GetManagedObjects()
-
-    def call(self, path, kind):
-        return self.interface(self.bus.get_object("org.bluez", path), kind)
-
-    def subscribe(self):
-        objects = self.objects()
-        if not objects.get(self.device, {}).get(DEVICE, {}).get("ServicesResolved"):
-            return False
-        services = {p for p, obj in objects.items() if str(obj.get(SERVICE, {}).get("UUID", "")).lower() == HRS
-                    and obj[SERVICE].get("Device") == self.device}
-        for path, obj in objects.items():
-            props = obj.get(CHARACTERISTIC, {})
-            if props.get("Service") in services and str(props.get("UUID", "")).lower() == MEASUREMENT:
-                if "notify" not in props.get("Flags", []):
-                    raise TrackingError("Heart-rate characteristic does not support notifications")
-                self.characteristic = path
-                self.call(path, CHARACTERISTIC).StartNotify()
-                self.notifying = True
-                return True
-        raise TrackingError("Selected device has no standard Heart Rate Service measurement")
-
-    def changed(self, kind, changes, invalidated, path=None):
-        if kind == CHARACTERISTIC and path == self.characteristic and "Value" in changes:
-            self.on_value(changes["Value"])
-        elif kind == DEVICE and path == self.device and "Connected" in changes and not changes["Connected"]:
-            self.on_value(None)
-
-    def close(self):
-        try:
-            if self.notifying:
-                self.call(self.characteristic, CHARACTERISTIC).StopNotify()
-        finally:
-            if self.match:
-                self.match.remove()
-            if self.connected_here:
-                self.call(self.device, DEVICE).Disconnect()
-
-
-def run_gaze(args, osc):
-    binary = Path(__file__).with_name("gaze")
-    command = [str(binary), "--seconds", str(args.seconds)]
-    if not args.osc:
-        return subprocess.call(command)
-    read_fd, write_fd = os.pipe()
-    process = None
-    try:
-        process = subprocess.Popen(command + ["--fd", str(write_fd)], pass_fds=(write_fd,))
-        os.close(write_fd)
-        write_fd = None
-        with os.fdopen(read_fd) as source:
-            read_fd = None
-            for line in source:
-                try:
-                    angles = gaze_angles([float(v) for v in line.split()])
-                except ValueError:
-                    continue
-                osc.send("/tracking/eye/CenterPitchYaw", angles)
-        return process.wait()
-    finally:
-        if read_fd is not None:
-            os.close(read_fd)
-        if write_fd is not None:
-            os.close(write_fd)
-        if process and process.poll() is None:
-            process.terminate()
-            try:
-                process.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                process.kill()
-                process.wait()
-
-
-class HeartPanel:
-    """Our GTK panel, using the Frame's existing GTK4/GI platform libraries."""
-    def __init__(self):
-        os.environ["GDK_BACKEND"] = "x11"
-        import gi
-        gi.require_version("Gtk", "4.0")
-        gi.require_version("GdkX11", "4.0")
-        from gi.repository import Gtk, Gdk, GdkX11, GLib
-        Gtk.init()
-        self.running = True
-        self.window = Gtk.Window(title="Frame Control · Heart rate")
-        self.window.set_default_size(480, 320)
-        self.window.connect("close-request", self.stop)
-        Gtk.Settings.get_default().set_property("gtk-application-prefer-dark-theme", True)
-        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=16)
-        box.set_valign(Gtk.Align.CENTER)
-        box.set_halign(Gtk.Align.CENTER)
-        box.set_size_request(440, -1)
-        for side in ("top", "bottom", "start", "end"):
-            getattr(box, "set_margin_" + side)(24)
-        self.window.set_child(box)
-        title = Gtk.Label(label="Heart rate")
-        title.add_css_class("title-2")
-        box.append(title)
-        self.reading = Gtk.Label(label="—")
-        self.reading.add_css_class("reading")
-        box.append(self.reading)
-        self.status = Gtk.Label(label="Waiting for strap")
-        box.append(self.status)
-        button = Gtk.Button(label="Stop")
-        button.connect("clicked", self.stop)
-        box.append(button)
-        css = Gtk.CssProvider()
-        css.load_from_data(b".reading { font-size: 144px; font-weight: 700; }")
-        Gtk.StyleContext.add_provider_for_display(Gdk.Display.get_default(), css, Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION)
-        self.window.present()
-        context = GLib.MainContext.default()
-        while context.pending():
-            context.iteration(False)
-        try:
-            xid = GdkX11.X11Surface.get_xid(self.window.get_surface())
-            subprocess.run(["xprop", "-id", str(xid), "-f", "STEAM_GAME", "32c", "-set", "STEAM_GAME", "2000000027"],
-                           check=True, stdout=subprocess.DEVNULL)
-        except Exception:
-            self.window.destroy()
-            raise
-
-    def stop(self, *args):
-        self.running = False
-        return True
-
-    def update(self, bpm):
-        self.reading.set_label(str(bpm) if bpm is not None else "—")
-        self.status.set_label("beats per minute" if bpm is not None else "Waiting for strap")
-
-    def close(self):
-        self.window.destroy()
-
-
-def run_heart(args, osc):
-    import dbus
-    from dbus.mainloop.glib import DBusGMainLoop
-    from gi.repository import GLib
-    DBusGMainLoop(set_as_default=True)
-    session = HeartSession(osc, args.address, args.log)
-    reader, root = None, None
-    failure = []
-    def value(data):
-        if data is None:
-            session.bpm = None
-            failure.append("Strap disconnected; reconnect and start again")
-            return
-        try:
-            session.notification(data)
-        except ValueError:
-            session.bpm = None
-        except OSError:
-            failure.append("OSC or session log write failed")
-    try:
-        reader = BluezHeart(dbus.SystemBus(), dbus.Interface, args.device, value)
-        context = GLib.MainContext.default()
-        deadline = time.monotonic() + 20
-        while not reader.subscribe():
-            if time.monotonic() > deadline:
-                raise TrackingError("Timed out waiting for the strap's GATT services")
-            while context.pending():
-                context.iteration(False)
-            time.sleep(0.1)
-        end = time.monotonic() + args.seconds
-        print("Heart-rate notifications started; readings stay local unless OSC or a log was selected.")
-        if args.panel:
-            root = HeartPanel()
-        running = lambda: root.running if root else True
-        while running() and time.monotonic() < end and not failure:
-            while context.pending():
-                context.iteration(False)
-            if root:
-                root.update(session.current())
-            time.sleep(0.05)
-        if failure:
-            raise TrackingError(failure[0])
-        return 0
-    finally:
-        if root:
-            root.close()
-        try:
-            if reader:
-                reader.close()
-        finally:
-            session.close()
-
-
-def run_pulse(args, osc):
-    """Experimental: estimate pulse from the IR eye cameras (see pulse.py)."""
-    import pulse
-    if not pulse.ET_BIN.exists():
-        raise TrackingError("SteamVR's eye-tracking tool is not installed on this Frame")
-    print(f"Capturing {args.seconds} s from the eye cameras. Wear the headset and keep still.", flush=True)
-    readings = [pulse.proximity()]
-    try:
-        frames = pulse.Capture(args.seconds).run()
-        readings.append(pulse.proximity())
-    except RuntimeError as error:  # capture status only; no image data
-        raise TrackingError(str(error))
-    print(f"Captured {len(frames)} eye frames; images already deleted. Analysing...", flush=True)
-    try:
-        result = pulse.analyse(frames)
-    except ValueError as error:
-        raise TrackingError(str(error))
-    on_face = all(pulse.worn(reading) for reading in readings)
-    if not on_face:
-        # Unworn, the cameras still show a steady periodic artifact that looks
-        # like a pulse (verified on the Frame), so it is never called clear.
-        print("The proximity sensor says the headset is not being worn; no pulse can be read.")
-    clear = on_face and pulse.reliable(result)
-    offset = time.time() - time.monotonic()  # the capture's timestamps are CLOCK_MONOTONIC
-    if args.log:
-        fd = os.open(args.log, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
-        with os.fdopen(fd, "w") as log:
-            log.write("unix_seconds,bpm\n")
-            for when, bpm in result["series"]:
-                log.write(f"{when + offset:.3f},{bpm:.1f}\n")
-    if clear:
-        osc.send(args.address, [round(result["bpm"])])
-    if args.show:
-        print(f"Estimate: {result['bpm']:.1f} BPM ({'clear' if clear else 'NOT clear'}; "
-              f"patch agreement {result['agreement']:.0%}, signal/noise {result['snr']:.2f}, "
-              f"{result['patches']} of {result['usable']} usable patches)")
-        print("Per-second estimates (15 s windows): "
-              + " ".join(str(round(bpm)) for _, bpm in result["series"]))
-    else:
-        print("A clear pulse was found." if clear else "No clear pulse was found.")
-    return 0 if clear else 3
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    commands = parser.add_subparsers(dest="command", required=True)
-    gaze = commands.add_parser("gaze", help="headless OpenXR; prints counters only without --osc")
-    heart = commands.add_parser("heart", help="standard BLE HRS from an explicitly selected strap")
-    pulse = commands.add_parser("pulse", help="experimental pulse estimate from the IR eye cameras")
-    for command in (gaze, heart, pulse):
-        command.add_argument("--osc", nargs=2, metavar=("IP", "PORT"), help="explicit UDP destination; no default")
-    for command in (gaze, heart):
-        command.add_argument("--seconds", type=int, default=10, help="bounded run, 1..86400 seconds (default: 10)")
-    pulse.add_argument("--seconds", type=int, default=60, help="capture length, 20..300 seconds (default: 60)")
-    heart.add_argument("--device", required=True, help="strap Bluetooth address already discovered by BlueZ")
-    heart.add_argument("--panel", action="store_true", help="show our panel on gamescope DISPLAY=:0")
-    for command in (heart, pulse):
-        command.add_argument("--address", default="/avatar/parameters/HeartRate", help="integer BPM OSC parameter")
-        command.add_argument("--log", help="new private CSV file; disabled by default")
-    pulse.add_argument("--show", action="store_true", help="print the estimate and per-second series")
-    args = parser.parse_args()
-    if not 1 <= args.seconds <= 86400:
-        parser.error("--seconds must be 1..86400")
-    if args.command == "pulse" and not 20 <= args.seconds <= 300:
-        parser.error("pulse --seconds must be 20..300")
-    def interrupted(signum, frame):
-        raise KeyboardInterrupt
-    signal.signal(signal.SIGTERM, interrupted)
-    if hasattr(signal, "SIGHUP"):
-        signal.signal(signal.SIGHUP, interrupted)
-    osc = None
-    try:
-        if args.command in ("heart", "pulse"):
-            osc_message(args.address, [0])
-            if getattr(args, "panel", False):
-                os.environ["DISPLAY"] = ":0"
-        osc = Osc(args.osc)
-        run = {"gaze": run_gaze, "heart": run_heart, "pulse": run_pulse}[args.command]
-        return run(args, osc)
-    except TrackingError as error:
-        print(str(error))
-        return 1
-    except KeyboardInterrupt:
-        return 130
-    except Exception as error:
-        # Never dump notifications, gaze, BLE addresses or exception payloads.
-        print(f"Tracking stopped ({type(error).__name__}). Check the device, runtime and selected output.")
-        return 1
-    finally:
-        if osc:
-            osc.close()
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

ios/FrameControl.xcodeproj/project.pbxproj

@@ -7,6 +7,8 @@
 	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 */; };
@@ -35,6 +37,8 @@
 /* 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>"; };
@@ -100,6 +104,7 @@
 			isa = PBXGroup;
 			children = (
 				8A11F3431826A26B247C0695 /* AppModel.swift */,
+				B1234567890ABCDEF0123456 /* NativeSessionState.swift */,
 				93C8E0D7C3F4F628941B3D5A /* FrameControlApp.swift */,
 				BF0FCA7117DA3ABA449B4EE0 /* InstallLink.swift */,
 			);
@@ -111,6 +116,7 @@
 			children = (
 				E81218B75FEEE47B8D8BAE20 /* ComfortNotificationTests.swift */,
 				1740B691F9C25E5FB6F9EFC3 /* FrameControlTests.swift */,
+				D1234567890ABCDEF0123456 /* NativeSessionTests.swift */,
 			);
 			path = FrameControlTests;
 			sourceTree = "<group>";
@@ -260,6 +266,7 @@
 			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 */,
@@ -279,6 +286,7 @@
 			files = (
 				A0C5B00E257230A38DBD9E54 /* ComfortNotificationTests.swift in Sources */,
 				DC043FB74BE2D23F3A5826BF /* FrameControlTests.swift in Sources */,
+				C1234567890ABCDEF0123456 /* NativeSessionTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

ios/FrameControl/App/AppModel.swift

@@ -19,6 +19,20 @@ 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?
@@ -99,18 +113,7 @@ final class AppModel: ObservableObject {
 
     /// "host", "host:port" or "[v6]:port", plus a user name.
     nonisolated static func parse(host: String, user: String) -> FrameSettings? {
-        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
+        FrameSettings.parse(host: host, user: user)
     }
 
     /// This phone's line for ~/.ssh/authorized_keys on the Frame.
@@ -145,6 +148,7 @@ 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

@@ -0,0 +1,142 @@
+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,3 +1,4 @@
+import Combine
 import Foundation
 import Network
 
@@ -18,20 +19,30 @@ final class FrameFinder: ObservableObject {
 
     private var browser: NWBrowser?
     private var probeTask: Task<Void, Never>?
-    private var fallback = "frame.local"
+    private var search = FrameSearchState()
+    private let probe: @Sendable (String) async -> Bool
+    private let discoveryEnabled: Bool
 
-    func start(fallback: String?) {
+    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) {
         stop()
-        self.fallback = (fallback?.isEmpty == false ? fallback : nil) ?? "frame.local"
+        let mine = search.start(manualAddress: manual ? fallback : nil)
+        let host = FrameSearchState.address(manual: search.manualAddress ?? "", discovered: fallback)
         found = nil
         since = Date()
-        browse()
+        if search.discovers && discoveryEnabled { browse(generation: mine) }
         probeTask = Task { [weak self] in
             while !Task.isCancelled {
-                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)
+                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) }
                 }
                 try? await Task.sleep(nanoseconds: 3_000_000_000)
             }
@@ -39,20 +50,21 @@ final class FrameFinder: ObservableObject {
     }
 
     func stop() {
+        search.stop()
         browser?.cancel()
         browser = nil
         probeTask?.cancel()
         probeTask = nil
     }
 
-    private func browse() {
+    private func browse(generation: UUID) {
         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, let host else { return }
+                        guard let self, self.search.accepts(generation), self.search.discovers, let host else { return }
                         // A found device is used over the fallback probe.
                         self.found = Found(host: host, name: name)
                     }
@@ -91,12 +103,8 @@ 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 {
-        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)
+        guard let target = FrameSettings.parse(host: address, user: "steamos") else { return false }
+        return await sshAnswers(host: target.host, port: UInt16(target.port))
     }
 
     nonisolated static func sshAnswers(host: String, port: UInt16) async -> Bool {

ios/FrameControl/SSH/FrameLink.swift

@@ -4,13 +4,6 @@ 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.
@@ -140,12 +133,6 @@ 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,15 +10,31 @@ struct RootView: View {
             case .setup:
                 SetupView(model: model)
             case .connecting(let step):
-                ConnectingView(step: step, host: model.settings?.host) { model.showSetup() }
+                ConnectingView(step: step, host: model.settings?.address) { model.showSetup() }
             case .failed(let message) where model.retrying && !model.needsPairing:
-                WaitingView(host: model.settings.map { $0.port == 22 ? $0.host : "\($0.host):\($0.port)" } ?? "", detail: message, deviceName: model.deviceName,
+                WaitingView(host: model.settings?.address ?? "", 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)
@@ -33,20 +49,37 @@ 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 {
-        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)
+        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)
         }
-        .padding(32)
     }
 }
 
@@ -59,21 +92,23 @@ struct FailedView: View {
     let change: () -> Void
 
     var body: some View {
-        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)
+        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) }
             }
-            if !needsPairing { Button(canRetry ? "Change headset" : "Back", action: change) }
+            .padding(32)
+            .frame(maxWidth: 480)
         }
-        .padding(32)
-        .frame(maxWidth: 480)
     }
 }
 
@@ -86,34 +121,37 @@ struct WaitingView: View {
     let reachable: () -> Void
     let change: () -> Void
     @State private var pulse = false
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
 
     var body: some View {
-        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.")
+        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)
             }
-            .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
+            .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
+                    }
                 }
             }
         }

ios/FrameControl/Views/SetupView.swift

@@ -13,10 +13,9 @@ struct SetupView: View {
     @State private var showHelp = false
     @FocusState private var passwordFocused: Bool
 
-    /// Where Connect goes: what the finder saw, else what was typed, else frame.local.
+    /// An explicit target always wins over discovery.
     private var host: String {
-        let typed = manualHost.trimmingCharacters(in: .whitespaces)
-        return finder.found?.host ?? (typed.isEmpty ? "frame.local" : typed)
+        FrameSearchState.address(manual: manualHost, discovered: finder.found?.host)
     }
 
     var body: some View {
@@ -34,19 +33,19 @@ struct SetupView: View {
         .scrollDismissesKeyboard(.interactively)
         .background(Color.frameBackground)
         .onAppear {
-            manualHost = model.settings?.host ?? ""
+            manualHost = model.settings?.address ?? ""
             user = model.settings?.user ?? "steamos"
-            var fallback = model.settings?.host
+            var fallback = model.settings?.address
             #if DEBUG
             fallback = ProcessInfo.processInfo.environment["FRAME_TEST_FALLBACK"] ?? fallback  // Simulator test hook
             #endif
-            finder.start(fallback: fallback)
+            finder.start(fallback: fallback, manual: !manualHost.isEmpty)
         }
         .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)
-            showHelp = true
+            if !Task.isCancelled { showHelp = true }
         }
     }
 
@@ -120,7 +119,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) }
+                        .onSubmit { finder.start(fallback: manualHost, manual: true) }
                         .padding(10).background(Color.black.opacity(0.28), in: RoundedRectangle(cornerRadius: 8))
                     TextField("User", text: $user)
                         .textInputAutocapitalization(.never).autocorrectionDisabled()
@@ -149,7 +148,9 @@ struct SetupView: View {
         }
         .onChange(of: manualHost) { _, value in
             // A typed address replaces the search.
-            if !value.trimmingCharacters(in: .whitespaces).isEmpty, finder.found?.host != value { finder.start(fallback: value) }
+            showHelp = false
+            let typed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+            finder.start(fallback: typed, manual: !typed.isEmpty)
         }
     }
 

ios/FrameControl/Web/WebShell.swift

@@ -31,14 +31,13 @@ struct WebShell: UIViewRepresentable {
         web.isInspectable = true
         #endif
         context.coordinator.web = web
-        web.load(URLRequest(url: url))
+        context.coordinator.load(url, reloadID: model.webReloadID)
         return web
     }
 
     func updateUIView(_ web: WKWebView, context: Context) {
-        if context.coordinator.loaded != url {
-            context.coordinator.loaded = url
-            web.load(URLRequest(url: url))
+        if context.coordinator.loaded != url || context.coordinator.reloadID != model.webReloadID {
+            context.coordinator.load(url, reloadID: model.webReloadID)
         }
         context.coordinator.deliverInstallLinks()
     }
@@ -47,16 +46,22 @@ 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"),
+        writeClipboard: (text) => call("writeClipboard", text),
         setUpConnection: () => call("setUpConnection"),
         open: (what) => call("open", what),
         saveImages: (images) => call("saveImages", images),
-        onInstallLink: (cb) => { installCb = cb; return call("installLinkReady"); },
+        onInstallLink: (cb) => { installCb = cb; return call("installLinkReady", window.__frameDocumentID); },
       };
-      window.__frameInstallLink = (req) => { if (installCb) installCb(req); };
+      window.__frameInstallLink = (req) => { if (!installCb) return false; installCb(req); return true; };
     })();
     """
 
@@ -64,7 +69,18 @@ struct WebShell: UIViewRepresentable {
         let model: AppModel
         weak var web: WKWebView?
         var loaded: URL?
-        private var installReady = false
+        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))
+        }
 
         init(model: AppModel) {
             self.model = model
@@ -118,8 +134,20 @@ 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 "writeClipboard":
+                guard let text = arg as? String else { return replyHandler(nil, "Expected text") }
+                UIPasteboard.general.string = text
+                replyHandler(true, nil)
             case "setUpConnection":
                 model.showSetup()
                 replyHandler(nil, nil)
@@ -135,9 +163,20 @@ struct WebShell: UIViewRepresentable {
                 share(images)
                 replyHandler(["message": "Choose Save Image to keep \(images.count == 1 ? "it" : "them") in Photos"], nil)
             case "installLinkReady":
-                installReady = true
-                deliverInstallLinks()
-                replyHandler(nil, nil)
+                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)
+                }
             default:
                 replyHandler(nil, "unknown request \(name)")
             }
@@ -145,13 +184,23 @@ struct WebShell: UIViewRepresentable {
 
         @MainActor
         func 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))")
+            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()
             }
         }
 
@@ -186,13 +235,55 @@ struct WebShell: UIViewRepresentable {
             (root.presentedViewController ?? root).present(sheet, animated: true)
         }
 
-        #if DEBUG
+        // 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)
+            }
+        }
+
         /// 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

@@ -0,0 +1,100 @@
+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,7 +18,8 @@ import tarfile
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[2]
-PATTERNS = ["ui/*.py", "ui/*.html", "ui/*.js", "ui/*.css", "ui/local-bin/*", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
+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",
             "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/heart-check.py

@@ -1,274 +0,0 @@
-#!/usr/bin/env python3
-"""Check Frame Control's heart-rate readings against a reference, on your computer.
-
-  python3 scripts/heart-check.py listen --port 9000 --out ours.csv
-  python3 scripts/heart-check.py compare ours.csv reference.csv
-  python3 scripts/heart-check.py compare ours.csv ~/Downloads/export.zip
-
-`listen` receives our integer-BPM OSC messages (send them here with
-`tracking-on-frame.py heart --osc <this computer's IP> 9000`) and shows each
-reading live, so you can watch it next to a reference such as your Apple
-Watch. `--out` also records `unix_seconds,bpm` to a new private file.
-
-`compare` lines up two recordings by time and reports how far apart they are.
-The reference can be:
-- a CSV whose first column is a time (unix seconds or ISO 8601) and whose
-  second is BPM, such as our own log, `listen --out`, or the test strap's
-  output (a third `flags` column marks skin-contact loss as "no reading");
-- an Apple Health export (`export.zip` or `export.xml`, from Health → your
-  profile → Export All Health Data). Only heart-rate records within the
-  recording's time range are read.
-
-Everything stays on this computer. Nothing is uploaded.
-"""
-import argparse
-import bisect
-import csv
-from datetime import datetime
-import io
-import os
-from pathlib import Path
-import re
-import socket
-import struct
-import sys
-import time
-import zipfile
-from xml.etree import ElementTree
-
-ADDRESS = "/avatar/parameters/HeartRate"
-
-
-def parse_osc(packet):
-    """Return (address, values) for a single OSC message with i/f arguments."""
-    def string(offset):
-        end = packet.index(b"\0", offset)
-        return packet[offset:end].decode("utf-8"), (end + 4) & ~3
-    address, offset = string(0)
-    tags, offset = string(offset)
-    if not tags.startswith(","):
-        raise ValueError("not an OSC message")
-    values = []
-    for tag in tags[1:]:
-        if tag not in "if" or offset + 4 > len(packet):
-            raise ValueError("unsupported OSC argument")
-        values.append(struct.unpack(">i" if tag == "i" else ">f", packet[offset:offset + 4])[0])
-        offset += 4
-    return address, values
-
-
-def listen(port, address, out, seconds, clock=time.time, stream=sys.stdout):
-    log = None
-    if out:
-        log = os.fdopen(os.open(out, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w")
-        log.write("unix_seconds,bpm\n")
-    received = 0
-    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
-        sock.bind(("0.0.0.0", port))
-        sock.settimeout(0.5)
-        print(f"Listening for {address} on UDP port {port}. Ctrl-C stops.", file=stream, flush=True)
-        end = clock() + seconds if seconds else None
-        try:
-            while end is None or clock() < end:
-                try:
-                    packet = sock.recv(1024)
-                except socket.timeout:
-                    continue
-                try:
-                    path, values = parse_osc(packet)
-                except (ValueError, UnicodeDecodeError):
-                    continue
-                if path != address or len(values) != 1:
-                    continue
-                now = clock()
-                bpm = int(values[0])
-                received += 1
-                print(f"{time.strftime('%H:%M:%S', time.localtime(now))}  {bpm:3d} bpm", file=stream, flush=True)
-                if log:
-                    log.write(f"{now:.3f},{bpm}\n")
-                    log.flush()
-        except KeyboardInterrupt:
-            pass
-        finally:
-            if log:
-                log.close()
-    return received
-
-
-def parse_time(text):
-    text = text.strip()
-    if re.fullmatch(r"\d+(\.\d+)?", text):
-        return float(text)
-    # Apple Health uses "2026-09-29 09:12:03 +1000".
-    text = re.sub(r" ([+-]\d{2}):?(\d{2})$", r"\1\2", text).replace("Z", "+0000")
-    for pattern in ("%Y-%m-%d %H:%M:%S%z", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S.%f%z"):
-        try:
-            return datetime.strptime(text, pattern).timestamp()
-        except ValueError:
-            pass
-    raise ValueError(f"unrecognised time {text!r}")
-
-
-def read_csv(path):
-    """[(time, bpm or None)], sorted. A header row is skipped."""
-    samples = []
-    with open(path, newline="") as source:
-        for row in csv.reader(source):
-            if len(row) < 2:
-                continue
-            try:
-                when, bpm = parse_time(row[0]), int(float(row[1]))
-            except (ValueError, OverflowError):
-                continue  # header or unparseable line
-            try:
-                flags = int(float(row[2])) if len(row) > 2 else None
-            except (ValueError, OverflowError):
-                flags = None  # an unrecognised flag leaves the reading as it is
-            if flags is not None and flags & 4 and not flags & 2:
-                bpm = None  # contact supported and not detected: no reading
-            samples.append((when, bpm))
-    return sorted(samples, key=lambda s: s[0])
-
-
-def read_health(path, start, end):
-    """Heart-rate records from an Apple Health export between start and end."""
-    samples = []
-    def scan(source):
-        for _, element in ElementTree.iterparse(source):
-            if element.tag == "Record" and element.get("type") == "HKQuantityTypeIdentifierHeartRate":
-                try:
-                    when = parse_time(element.get("startDate") or "")
-                    value = round(float(element.get("value") or ""))
-                except (ValueError, OverflowError):
-                    continue
-                if start <= when <= end:
-                    samples.append((when, value))
-            element.clear()
-    if zipfile.is_zipfile(path):
-        with zipfile.ZipFile(path) as archive:
-            names = [n for n in archive.namelist() if n.endswith("/export.xml") or n == "export.xml"]
-            if not names:
-                raise ValueError("no export.xml in that archive; use Health's Export All Health Data")
-            with archive.open(names[0]) as source:
-                scan(source)
-    else:
-        with open(path, "rb") as source:
-            scan(source)
-    return sorted(samples)
-
-
-def read_any(path, start=None, end=None):
-    path = str(path)
-    if path.endswith((".zip", ".xml")):
-        return read_health(path, start, end)
-    return read_csv(path)
-
-
-def value_at(samples, when, hold, times=None):
-    """Our reading at a moment: the latest sample no older than `hold` seconds.
-    `times` is the samples' time column, if the caller has already built it."""
-    times = times if times is not None else [s[0] for s in samples]
-    i = bisect.bisect_right(times, when) - 1
-    if i < 0 or when - times[i] > hold:
-        return None
-    return samples[i][1]
-
-
-def compare(ours, reference, max_lag=10.0, hold=5.0):
-    """Compare our readings with the reference at each reference moment.
-
-    `lag` is the delay added to reference times before looking up ours (our
-    readings arrive after the sensor's). The best lag within ±max_lag is used.
-    """
-    real = [(t, b) for t, b in reference if b is not None]
-    if not real or not any(b is not None for _, b in ours):
-        raise ValueError("both recordings need at least one reading")
-    best = None
-    ours_times = [t for t, _ in ours]
-    steps = int(max_lag * 4)
-    for step in range(-steps, steps + 1):
-        lag = step / 4
-        pairs = [(value_at(ours, t + lag, hold, ours_times), b) for t, b in real]
-        pairs = [(o, r) for o, r in pairs if o is not None]
-        if not pairs:
-            continue
-        error = sum(abs(o - r) for o, r in pairs) / len(pairs)
-        key = (-len(pairs), error, abs(lag))
-        if best is None or key < best[0]:
-            best = (key, lag, pairs)
-    if best is None:
-        raise ValueError("the recordings do not overlap in time")
-    _, lag, pairs = best
-    differences = [o - r for o, r in pairs]
-    # While the reference says "no reading" (lost skin contact), we must not
-    # produce new readings. Count ours that arrive during such a stretch.
-    gaps = [t for t, b in reference if b is None]
-    reference_times = [t for t, _ in reference]
-    shown_in_gaps = 0
-    for t, bpm in ours:
-        i = bisect.bisect_right(reference_times, t - lag) - 1
-        if bpm is not None and i >= 0 and reference[i][1] is None:
-            shown_in_gaps += 1
-    return {
-        "reference_readings": len(real),
-        "matched": len(pairs),
-        "lag_seconds": lag,
-        "mean_abs_error": sum(abs(d) for d in differences) / len(differences),
-        "bias": sum(differences) / len(differences),
-        "max_abs_error": max(abs(d) for d in differences),
-        "within_5": sum(1 for d in differences if abs(d) <= 5) / len(differences),
-        "exact": sum(1 for d in differences if d == 0) / len(differences),
-        "no_contact_moments": len(gaps),
-        "shown_during_no_contact": shown_in_gaps,
-    }
-
-
-def report(result, tolerance, stream=sys.stdout):
-    print(f"Reference readings: {result['reference_readings']}, matched: {result['matched']}", file=stream)
-    print(f"Best alignment: ours {result['lag_seconds']:+.2f} s after the reference", file=stream)
-    print(f"Mean absolute difference: {result['mean_abs_error']:.2f} BPM "
-          f"(bias {result['bias']:+.2f}, worst {result['max_abs_error']})", file=stream)
-    print(f"Within ±5 BPM: {result['within_5']:.0%}; identical: {result['exact']:.0%}", file=stream)
-    if result["no_contact_moments"]:
-        print(f"No-contact moments: {result['no_contact_moments']}, where we showed a stale "
-              f"reading: {result['shown_during_no_contact']}", file=stream)
-    coverage = result["matched"] / result["reference_readings"]
-    passed = (result["mean_abs_error"] <= tolerance and coverage >= 0.8
-              and not result["shown_during_no_contact"])
-    print(("PASS" if passed else "FAIL") + f" (mean difference ≤ {tolerance} BPM, ≥80% of reference "
-          f"readings matched, nothing shown without contact)", file=stream)
-    return passed
-
-
-def main(argv=None):
-    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    commands = parser.add_subparsers(dest="command", required=True)
-    heard = commands.add_parser("listen", help="show and optionally record our OSC readings live")
-    heard.add_argument("--port", type=int, default=9000)
-    heard.add_argument("--address", default=ADDRESS)
-    heard.add_argument("--out", help="new private CSV file")
-    heard.add_argument("--seconds", type=float, default=0, help="stop after this long (default: until Ctrl-C)")
-    check = commands.add_parser("compare", help="compare our recording with a reference")
-    check.add_argument("ours", type=Path)
-    check.add_argument("reference", type=Path)
-    check.add_argument("--tolerance", type=float, default=5.0, help="allowed mean difference in BPM (default 5)")
-    check.add_argument("--max-lag", type=float, default=10.0, help="largest time offset to search, seconds")
-    args = parser.parse_args(argv)
-    if args.command == "listen":
-        count = listen(args.port, args.address, args.out, args.seconds)
-        print(f"Received {count} readings.")
-        return 0 if count else 3
-    try:
-        ours = read_csv(args.ours)
-        if not ours:
-            raise ValueError("our recording has no readings")
-        reference = read_any(args.reference, ours[0][0] - 60, ours[-1][0] + 60)
-        result = compare(ours, reference, args.max_lag)
-    except (ValueError, OSError, csv.Error, ElementTree.ParseError, zipfile.BadZipFile) as error:
-        print(f"Could not compare: {error}")
-        return 1
-    return 0 if report(result, args.tolerance) else 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

scripts/heart-test-strap.swift

@@ -1,100 +0,0 @@
-// A synthetic Bluetooth heart-rate strap for testing, run on the Mac.
-//
-//   swiftc -O scripts/heart-test-strap.swift -o /tmp/heart-test-strap
-//   /tmp/heart-test-strap [seconds]      # default 60
-//
-// Advertises the standard Heart Rate Service (180d) as "FC Test Strap" and,
-// while a central is subscribed, sends one Heart Rate Measurement (2a37) per
-// second from a fixed, known sequence. Each sent value is printed to stdout as
-// `unix_seconds,bpm,flags` so scripts/heart-check.py can compare what the
-// Frame received with what was sent. Every value is synthetic; this is not a
-// sensor. macOS asks for Bluetooth permission the first time it runs.
-import CoreBluetooth
-import Foundation
-
-let hrs = CBUUID(string: "180D")
-let measurement = CBUUID(string: "2A37")
-
-/// The known sequence: an 8-bit ramp, 16-bit encodings, a skin-contact loss
-/// (which must show as no reading) and a recovery.
-func packet(_ second: Int) -> (bpm: Int, flags: UInt8) {
-    switch second % 60 {
-    case 0..<30: return (60 + second % 60 * 4, 0x06)   // 60…176, contact detected
-    case 30..<40: return (180 - (second % 60 - 30) * 3, 0x07) // 16-bit value
-    case 40..<45: return (150, 0x04)                  // contact lost
-    default: return (72 + (second % 60 - 45), 0x06)
-    }
-}
-
-final class Strap: NSObject, CBPeripheralManagerDelegate {
-    let seconds: Int
-    var manager: CBPeripheralManager!
-    var characteristic: CBMutableCharacteristic!
-    var subscribed = false
-    var sent = 0
-
-    init(seconds: Int) {
-        self.seconds = seconds
-        super.init()
-        manager = CBPeripheralManager(delegate: self, queue: nil)
-    }
-
-    func peripheralManagerDidUpdateState(_ peripheral: CBPeripheralManager) {
-        guard peripheral.state == .poweredOn else {
-            FileHandle.standardError.write("Bluetooth state \(peripheral.state.rawValue)\n".data(using: .utf8)!)
-            if peripheral.state == .unauthorized || peripheral.state == .unsupported || peripheral.state == .poweredOff {
-                FileHandle.standardError.write("Bluetooth unavailable (state \(peripheral.state.rawValue))\n".data(using: .utf8)!)
-                exit(1)
-            }
-            return
-        }
-        characteristic = CBMutableCharacteristic(type: measurement, properties: [.notify], value: nil, permissions: [])
-        let service = CBMutableService(type: hrs, primary: true)
-        service.characteristics = [characteristic]
-        peripheral.add(service)
-    }
-
-    func peripheralManager(_ peripheral: CBPeripheralManager, didAdd service: CBService, error: Error?) {
-        if let error { fail("add service: \(error.localizedDescription)") }
-        peripheral.startAdvertising([CBAdvertisementDataLocalNameKey: "FC Test Strap",
-                                     CBAdvertisementDataServiceUUIDsKey: [hrs]])
-    }
-
-    func peripheralManagerDidStartAdvertising(_ peripheral: CBPeripheralManager, error: Error?) {
-        if let error { fail("advertise: \(error.localizedDescription)") }
-        FileHandle.standardError.write("Advertising FC Test Strap\n".data(using: .utf8)!)
-        Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in self.tick() }
-    }
-
-    func peripheralManager(_ peripheral: CBPeripheralManager, central: CBCentral, didSubscribeTo characteristic: CBCharacteristic) {
-        subscribed = true
-        FileHandle.standardError.write("Central subscribed\n".data(using: .utf8)!)
-    }
-
-    func peripheralManager(_ peripheral: CBPeripheralManager, central: CBCentral, didUnsubscribeFrom characteristic: CBCharacteristic) {
-        subscribed = false
-        FileHandle.standardError.write("Central unsubscribed\n".data(using: .utf8)!)
-    }
-
-    func tick() {
-        guard subscribed else { return }
-        if sent >= seconds { exit(0) }
-        let (bpm, flags) = packet(sent)
-        var bytes: [UInt8] = [flags, UInt8(bpm & 0xff)]
-        if flags & 1 != 0 { bytes.append(UInt8(bpm >> 8)) }
-        if manager.updateValue(Data(bytes), for: characteristic, onSubscribedCentrals: nil) {
-            print(String(format: "%.3f,%d,%d", Date().timeIntervalSince1970, bpm, flags))
-            fflush(stdout)
-            sent += 1
-        }
-    }
-
-    func fail(_ message: String) -> Never {
-        FileHandle.standardError.write("\(message)\n".data(using: .utf8)!)
-        exit(1)
-    }
-}
-
-let seconds = CommandLine.arguments.count > 1 ? Int(CommandLine.arguments[1]) ?? 60 : 60
-let strap = Strap(seconds: seconds)
-RunLoop.main.run()

scripts/store-on-frame.sh

@@ -0,0 +1,116 @@
+#!/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/tracking-on-frame.py

@@ -1,60 +0,0 @@
-#!/usr/bin/env python3
-"""Install or run our local-only tracking tools on the Frame.
-
-  python3 scripts/tracking-on-frame.py install
-  python3 scripts/tracking-on-frame.py gaze --seconds 10
-  python3 scripts/tracking-on-frame.py gaze --seconds 3600 --osc 127.0.0.1 9000
-  python3 scripts/tracking-on-frame.py heart --device AA:BB:CC:DD:EE:FF --panel
-  python3 scripts/tracking-on-frame.py pulse --seconds 60 --show   # experimental
-
-FRAME_ALIAS overrides the SSH alias (default: frame). Runs in the foreground;
-Ctrl-C stops the reader. No service, autostart, sudo or SteamVR settings changes.
-"""
-import os
-from pathlib import Path
-import shlex
-import subprocess
-import sys
-import tarfile
-
-REMOTE = '"$HOME/.local/share/frame-control/tracking"'
-INSTALL = '''set -eu
-base="$HOME/.local/share/frame-control/tracking"
-mkdir -p "$base"
-stage=$(mktemp -d "$base/.install.XXXXXX")
-trap 'rm -rf "$stage"' EXIT
- tar -xf - -C "$stage"
-cc -O2 -Wall -Wextra -Werror "$stage/gaze.c" \\
-  -L/opt/steamvr/bin/linuxarm64 -Wl,-rpath,/opt/steamvr/bin/linuxarm64 \\
-  -lopenxr_loader -o "$stage/gaze"
-chmod 700 "$stage/gaze" "$stage/tracking.py"
-chmod 600 "$stage/pulse.py"
-mv "$stage/gaze" "$stage/tracking.py" "$stage/pulse.py" "$base/"
-echo 'Installed Frame Control tracking tools (no service started).'
-'''
-
-
-def main():
-    if len(sys.argv) < 2 or sys.argv[1] not in ("install", "gaze", "heart", "pulse"):
-        print(__doc__)
-        return 2
-    host = os.environ.get("FRAME_ALIAS", "frame")
-    if not host or host.startswith("-"):
-        raise ValueError("invalid SSH alias")
-    ssh = ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=10", host]
-    if sys.argv[1] == "install":
-        import tempfile
-        source = Path(__file__).resolve().parents[1] / "frame" / "tracking"
-        with tempfile.TemporaryFile() as archive:
-            with tarfile.open(fileobj=archive, mode="w") as tar:
-                for name in ("gaze.c", "tracking.py", "pulse.py"):
-                    tar.add(source / name, arcname=name)
-            archive.seek(0)
-            return subprocess.call(ssh + ["bash -c " + shlex.quote(INSTALL)], stdin=archive)
-    # Allocate a tty so SSH forwards Ctrl-C and hangup to the foreground process.
-    command = 'exec python3 ' + REMOTE + '/tracking.py ' + shlex.join(sys.argv[1:])
-    return subprocess.call(ssh[:-1] + ["-tt", host, command])
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

tests/client_preferences.cjs

@@ -0,0 +1,72 @@
+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 [];},setAttribute(key,value){this[key]=value;},addEventListener(key,callback){this[key]=callback;},focus(){this.focused=true;}});
+      classList:{toggle(){}},querySelectorAll(){return [];},close(){this.open=false;},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(){},gb:String,dur:String,esc:String,meter(){},toast(){},
+    battery(){},setVolume(){},renderHome(){},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,11 +64,12 @@ 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(){},
-      resetShots(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
+      padReset(){},ctrlReset(){},resetShots(){},resetClips(){},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 = {};
-      let viewGen = 0, lastImg = null, lastShot = null, androidApps = [], titlesSeq = 0, page = 'control';`,context);
+      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 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);
@@ -438,34 +439,13 @@ 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 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(){},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'};
+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'};
   for(const item of cc.catalog) for(const [href] of item.links||[]) {
     if(!href.startsWith('#')||href==='#connection')continue;
-    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); }
+    f.navigate(href);assert.equal(f.activePage,expected[href.slice(1)],href);
   }
-  assert.equal(vm.runInContext('PAGES[4]',context),'devices');
-  assert.equal(vm.runInContext('PAGES[5]',context),'control');
+  assert.equal(f.run('PAGES.length'),4);
 });

tests/e2e/test_device.py

@@ -45,6 +45,13 @@ class Device(harness.FrameTestCase):
         self.assertRegex(out['message'], r'^copied via Klipper \(\d+ chars\)$')
         self.assertEqual(state()['clipboard'], [text])
 
+    def test_clipboard_comes_back_from_klipper(self):
+        text = 'from the headset: 世界 🎧\n\nwith trailing newlines\n\n'
+        ok('POST', '/api/clipboard', {'text': text})
+        out = ok('POST', '/api/clipboard', {'read': True})
+        self.assertEqual(out['text'], text)
+        self.assertRegex(out['message'], r"^Copied \d+ characters from the headset's clipboard$")
+
     def test_flatpak_install_and_remove(self):
         # Installs run as background jobs (server.start_job); uninstall answers at once.
         job = finished(ok('POST', '/api/flatpak', {'id': 'org.videolan.VLC', 'action': 'install'}))

tests/fakeframe/rootfs/usr/local/bin/qdbus6

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 """Stub for qdbus6: records Klipper setClipboardContents calls, the way
 Frame Control sends text to the headset desktop's clipboard (server.PASTE,
-verified 2026-09-25)."""
+verified 2026-09-25), and answers getClipboardContents with the last one
+(server.COPY). Printing the string and a newline is how qdbus prints a
+returned QString; getClipboardContents itself is a guess, not seen on a headset."""
 import os
 import sys
 
@@ -15,5 +17,10 @@ if args[:3] == ['org.kde.klipper', '/klipper', 'org.kde.klipper.klipper.setClipb
         sys.exit('Could not connect to D-Bus server')
     with fs.update() as s:
         s['clipboard'].append(args[3])
+elif args == ['org.kde.klipper', '/klipper', 'org.kde.klipper.klipper.getClipboardContents']:
+    if not os.environ.get('DBUS_SESSION_BUS_ADDRESS'):
+        sys.exit('Could not connect to D-Bus server')
+    clips = fs.read()['clipboard']
+    sys.stdout.buffer.write((clips[-1] if clips else '').encode() + b'\n')
 else:
     sys.exit(f'qdbus6 stub: unsupported {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 = {
-    ctrl, $: () => canvas, ctrlMode: () => mode, ctrlShow: () => {}, toast: () => {},
+    devGen: 0, 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/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", code + "; return { padSend, padFlush };")(pad, api, s => { shown.push(s); pad.state = s.state; });
+  const fns = new Function("pad", "api", "padShow", "devGen", code + "; return { padSend, padFlush };")(pad, api, s => { shown.push(s); pad.state = s.state; }, 0);
   return { pad, shown, ...fns };
 }
 

tests/page/store_detail.mjs

@@ -19,13 +19,13 @@ function grab(name) {
   fail(`unbalanced ${name}`);
 }
 const names = ["esc", "storeName", "storeHue", "storeInitial", "storeText", "storeOpenSource", "sourcePage", "storeImage",
-               "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
-               "updateInstall", "openStoreApp", "loadOfferDetails"];
+               "GLYPH_VR", "GLYPH_APP", "RUNS", "storeRuns", "storeKind", "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
+               "updateInstall", "openStoreApp", "loadOfferDetails", "installStoreApp"];
 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 () => ({})) {
+function page(api = async () => ({}), androidApps = []) {
   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,10 @@ function page(api = async () => ({})) {
   const document = { activeElement: null, querySelector: () => null };
   const console = { error() {} };
   const calls = [];
-  const fns = new Function("$", "sourceState", "document", "console", "api", code + "; return { renderAppDetail, openStoreApp };")(
-    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); });
+  const fns = new Function("$", "sourceState", "document", "console", "api", "androidApps", "runJob", "loadAndroid", "act", "window", "devGen", code + "; return { renderAppDetail, openStoreApp };")(
+    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); }, androidApps,
+    async (title, key, work) => work(), () => {}, async (title, work) => work(),
+    { open() { fail("an in-app installation opened an external page"); } }, 0);
   return { els, sourceState, calls, ...fns };
 }
 
@@ -54,6 +56,14 @@ 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();
@@ -68,7 +78,7 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
 {
   const p = page(async () => { throw new Error("offline"); });
   p.sourceState.apps = [{ name: "Broken", offers: [] }];
-  await p.openStoreApp(0);
+  await p.openStoreApp(0, true);
   if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes('role="alert"')) fail("broken listing didn't open with the error");
   if (p.calls.length) fail("asked for details of a listing that couldn't render");
 }
@@ -90,4 +100,18 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
   if (!p.els.detailBody.innerHTML.includes('id="detailTitle">Open Brush<')) fail("page lost after a failed details request");
   if (!p.els.detailInstallNote.textContent.includes("couldn't be refreshed")) fail("no note after a failed details request");
 }
+// The featured Install starts a new or failed job, while a job already running or
+// installed opens its details without another install or a launch command.
+for (const [job, expected] of [[null, 1], [{ done: false }, 0],
+    [{ done: true, result: { package: offer.package } }, 0], [{ done: true, error: "offline" }, 1]]) {
+  const p = page(async path => path === "/api/sources/install" ? { package: offer.package } : {});
+  p.sourceState.apps = [{ name: "Open Brush", offers: [{ ...offer }] }];
+  if (job) p.sourceState.jobs.set(`${offer.source}:${offer.id}`, job);
+  await p.openStoreApp(0, true);
+  if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes('id="detailInstall"')) fail("hero installation didn't open details");
+  const installs = p.calls.filter(([path]) => path === "/api/sources/install");
+  if (installs.length !== expected) fail(`expected ${expected} installation requests, got ${installs.length}`);
+  if (installs.some(([, body]) => body.source !== offer.source || body.id !== offer.id)) fail("installed a different offer");
+  if (p.calls.some(([path]) => path === "/api/android")) fail("hero Install launched an already installed app");
+}
 console.log("ok");

tests/standalone_review.cjs

@@ -0,0 +1,219 @@
+// 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_android_import.py

@@ -0,0 +1,177 @@
+"""Local APK/OBB backups: inspect as a unit, verify the target, and finish setup."""
+import sandbox  # noqa: F401
+import io
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+import frame_android_import as backup
+import server
+from apk_fixtures import apk, manifest
+
+PKG = 'com.Armature.VR4'
+META = {'package': PKG, 'label': PKG, 'version': '', 'version_code': 210,
+        'instance': 2800000001, 'shortcut': 123, 'game_id': 456}
+
+
+class BackupTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+        self.apk = self.root / 'VR4-Android-Shipping-arm64.apk'
+        self.apk.write_bytes(apk({'AndroidManifest.xml': manifest(PKG, 0x7f010000, 0x7f010001, 26)}))
+        self.obb = [self.root / f'{kind}.203.{PKG}.obb' for kind in ('main', 'patch')]
+        for p in self.obb:
+            p.write_bytes(b'game data')
+
+    def test_desktop_apk_finds_matching_siblings_but_browser_requires_selection(self):
+        (self.root / 'main.1.org.other.game.obb').write_bytes(b'other game')
+        with patch.object(backup.android, 'ssh') as ssh:
+            desktop = backup.inspect([str(self.apk)], discover=True)
+            browser = backup.inspect([str(self.apk)])
+            selected = backup.inspect([str(self.apk), *map(str, self.obb)])
+        ssh.assert_not_called()
+        self.assertEqual(desktop['obb'], self.obb)
+        self.assertEqual(browser['obb'], [])
+        self.assertEqual(backup.public(selected)['obb'][0]['name'], self.obb[0].name)
+        self.assertEqual(backup.public(selected)['package'], PKG)
+        self.assertNotIn(str(self.root), str(backup.public(selected)))
+
+    def test_wrong_data_empty_data_duplicate_names_and_multiple_apks_fail_before_install(self):
+        other = self.root / 'main.203.org.other.game.obb'
+        other.write_bytes(b'other game')
+        with self.assertRaisesRegex(backup.android.FrameError, 'does not belong'):
+            backup.inspect([str(self.apk), str(other)])
+        self.obb[0].write_bytes(b'')
+        with self.assertRaisesRegex(backup.android.FrameError, 'nonempty'):
+            backup.inspect([str(self.apk), str(self.obb[0])])
+        second = self.root / 'another.apk'
+        second.write_bytes(self.apk.read_bytes())
+        with self.assertRaisesRegex(backup.android.FrameError, 'one game at a time'):
+            backup.inspect([str(self.apk), str(second)])
+        self.obb[0].write_bytes(b'data')
+        folder = self.root / 'copy'
+        folder.mkdir()
+        duplicate = folder / self.obb[0].name
+        duplicate.write_bytes(b'data')
+        with self.assertRaisesRegex(backup.android.FrameError, 'unique names'):
+            backup.inspect([str(self.apk), str(self.obb[0]), str(duplicate)])
+
+    def test_obb_only_repairs_existing_game_and_requests_apk_when_not_installed(self):
+        with patch.object(backup.android, 'read_meta', return_value=None):
+            with self.assertRaisesRegex(backup.android.FrameError, 'Add its APK'):
+                backup.inspect(list(map(str, self.obb)))
+        with patch.object(backup.android, 'read_meta', return_value=META):
+            plan = backup.inspect(list(map(str, self.obb)))
+        self.assertIsNone(plan['apk'])
+        self.assertEqual(plan['checked']['version_code'], 210)
+
+    def test_apk_and_both_data_files_install_launch_verify_copy_close_in_order(self):
+        plan = backup.inspect([str(self.apk), *map(str, self.obb)])
+        order = []
+        def added(pkg, checked, files, *args, **kwargs):
+            order.append('copy-close')
+            self.assertEqual(pkg, PKG)
+            self.assertEqual(files, self.obb)
+            return {'closed': True, 'message': 'copied', 'app': META, 'needs_game_data': False}
+        with patch.object(backup.quest, '_running', side_effect=[False, False, True]), \
+                patch.object(backup.android, 'read_meta', return_value=None), \
+                patch.object(backup.android, 'install', side_effect=lambda *a, **k: order.append('install') or META), \
+                patch.object(backup.android, 'launch', side_effect=lambda *a: order.append('launch')), \
+                patch.object(backup.quest, '_wait_ready', side_effect=lambda *a: order.append('ready')), \
+                patch.object(backup.quest, '_check_android_package', side_effect=lambda *a: order.append('verify')), \
+                patch.object(backup.quest, 'add_game_data', side_effect=added):
+            result = backup.install(plan)
+        self.assertEqual(order, ['install', 'launch', 'ready', 'verify', 'copy-close'])
+        self.assertIn('2 game-data files', result['message'])
+        self.assertIn('Ready to open', result['message'])
+
+    def test_copy_failure_closes_game_and_keeps_retry_instruction(self):
+        plan = backup.inspect([str(self.apk), *map(str, self.obb)])
+        with patch.object(backup.quest, '_running', side_effect=[False, True]), \
+                patch.object(backup.android, 'read_meta', return_value=None), \
+                patch.object(backup.android, 'install', return_value=META), \
+                patch.object(backup.quest, '_wait_ready'), patch.object(backup.quest, '_check_android_package'), \
+                patch.object(backup.quest, 'add_game_data', side_effect=backup.android.FrameError('transfer failed')), \
+                patch.object(backup.quest, '_close', return_value=(True, None)) as close:
+            with self.assertRaisesRegex(backup.android.FrameError, 'installed, but.*Import the same backup again'):
+                backup.install(plan)
+        close.assert_called_once_with(PKG)
+
+    def test_changed_files_are_rejected_before_frame_access(self):
+        plan = backup.inspect([str(self.apk), *map(str, self.obb)])
+        self.obb[0].write_bytes(b'changed contents')
+        with patch.object(backup.android, 'ssh') as ssh:
+            with self.assertRaisesRegex(backup.android.FrameError, 'backup changed'):
+                backup.install(plan)
+        ssh.assert_not_called()
+
+    def test_running_game_and_newer_installed_version_are_not_replaced(self):
+        plan = backup.inspect([str(self.apk), *map(str, self.obb)])
+        newer = {**META, 'version_code': plan['checked']['version_code'] + 1}
+        for running, existing, message in [(True, None, 'Close'), (False, newer, 'newer')]:
+            with self.subTest(running=running), \
+                    patch.object(backup.quest, '_running', return_value=running), \
+                    patch.object(backup.android, 'read_meta', return_value=existing), \
+                    patch.object(backup.android, 'install') as install:
+                with self.assertRaisesRegex(backup.android.FrameError, message):
+                    backup.install(plan)
+                install.assert_not_called()
+
+    def test_apk_without_data_installs_without_launching(self):
+        plan = backup.inspect([str(self.apk)])
+        with patch.object(backup.quest, '_running', return_value=False), \
+                patch.object(backup.android, 'read_meta', return_value=None), \
+                patch.object(backup.android, 'install', return_value=META), \
+                patch.object(backup.android, 'launch') as launch:
+            result = backup.install(plan)
+        launch.assert_not_called()
+        self.assertFalse(result['needs_game_data'])
+
+
+class StagingTests(unittest.TestCase):
+    setUp = BackupTests.setUp
+    def tearDown(self):
+        for entry in server._android_backups.values():
+            server._discard_android_backup(entry)
+        server._android_backups.clear()
+
+    def test_uploaded_batch_is_inspected_together_and_cancel_removes_all_uploads(self):
+        token = server.android_backup({'action': 'begin'})['token']
+        for path in [self.apk, *self.obb]:
+            class Request:
+                headers = {'X-Filename': path.name, 'X-Mode': 'android-backup',
+                           'X-Android-Backup': token, 'Content-Length': str(path.stat().st_size)}
+                rfile = io.BytesIO(path.read_bytes())
+            server.Handler.upload(Request())
+        read = server.android_backup({'action': 'inspect', 'token': token})
+        self.assertEqual(len(read['plan']['obb']), 2)
+        folders = list(server._android_backups[token]['dirs'])
+        server.android_backup({'action': 'discard', 'token': token})
+        self.assertTrue(all(not Path(p).exists() for p in folders))
+        self.assertTrue(self.apk.exists())
+
+    def test_headset_change_refuses_import_and_pc_folder_is_left_to_title_importer(self):
+        class Link:
+            device = 'a'
+            def active_device(self):
+                return {'id': self.device}
+        link = Link()
+        with patch.object(server, 'LINK', link):
+            read = server.android_backup({'action': 'inspect', 'paths': [str(self.apk)]})
+            link.device = 'b'
+            with self.assertRaisesRegex(server.Failure, 'headset changed'):
+                server.android_backup({'action': 'install', 'token': read['token']})
+        pc = self.root / 'pc'
+        pc.mkdir()
+        (pc / 'game.exe').write_bytes(b'program')
+        self.assertEqual(server.android_backup({'action': 'inspect', 'paths': [str(pc)], 'probe': True}),
+                         {'android': False})
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_apk_artwork.py

@@ -19,7 +19,9 @@ 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:
@@ -71,9 +73,13 @@ class ArtworkTests(unittest.TestCase):
             _images.remember('https://example.com/a.png', PNG[:8] + b'x' * _images.MAX_IMAGE)
 
     def test_handles_are_bounded(self):
-        for i in range(4100):
-            _images.register('https://example.com/%d.png' % i)
-        self.assertEqual(len(_images._urls),4096)
+        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'))
 
     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'], ('second', 50))
+        self.assertEqual(arrived[1]['query'][:2], ('second', 50))
 
     def test_set_enabled_does_not_hold_search_lock_in_source(self):
         free = []

tests/test_autosync.py

@@ -0,0 +1,291 @@
+"""Copying new screenshots and clips to the computer on their own (ui/frame_autosync.py).
+
+The headset is a fake: lists of shots and clips, and save/export functions that
+record what they were asked to copy. No SSH, no headset.
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import errno
+import json
+import shutil
+import sys
+import tempfile
+import threading
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "ui"))
+import frame_autosync as fa  # noqa: E402
+
+NOW = 1_800_000_000.0
+GB = 1024**3
+
+
+def shot(n, t, saved=False):
+    return {"id": f"1/620/20261020{n:06d}_1.jpg", "time": t, "saved": saved}
+
+
+def clip(n, t, idle=600, kind="clip", saved=False):
+    return {"id": f"1/clips/clip_620_{n}/video/bg", "kind": kind, "time": t, "idle": idle, "saved": saved}
+
+
+class FakeFrame:
+    def __init__(self):
+        self.shots, self.clips = [], []
+        self.saved, self.exported, self.calls = [], [], []
+        self.device, self.busy, self.down = "frame-a", False, False
+        self.save_error = self.export_error = None
+
+    def list_shots(self):
+        self.calls.append("list_shots")
+        if self.down:
+            raise RuntimeError("ssh: connect to host frame port 22: Connection timed out")
+        return {"shots": list(self.shots)}
+
+    def list_clips(self):
+        self.calls.append("list_clips")
+        if self.down:
+            raise RuntimeError("ssh: connect to host frame port 22: Connection timed out")
+        return {"clips": list(self.clips)}
+
+    def save_shots(self, device, ids):
+        self.calls.append("save_shots")
+        if self.save_error:
+            raise self.save_error
+        self.saved.append((device, list(ids)))
+        for s in self.shots:
+            if s["id"] in ids:
+                s["saved"] = True
+
+    def export_clip(self, device, clip_id):
+        self.calls.append("export_clip")
+        if self.export_error:
+            raise self.export_error
+        self.exported.append((device, clip_id))
+        for c in self.clips:
+            if c["id"] == clip_id:
+                c["saved"] = True
+
+
+class AutoSyncTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+        self.frame = FakeFrame()
+        self.now = [NOW]
+        self.free = [100 * GB]
+        self.sync = self.make()
+
+    def make(self):
+        f = self.frame
+        return fa.AutoSync(f.list_shots, f.save_shots, f.list_clips, f.export_clip,
+                           lambda: f.device, lambda: f.busy,
+                           offline=lambda e: "The Frame isn't answering." if "timed out" in str(e) else None,
+                           shots_folder=self.dir / "Pictures", clips_folder=self.dir / "Videos",
+                           path=self.dir / "auto-sync.json", clock=lambda: self.now[0],
+                           space=lambda folder: self.free[0])
+
+    def test_off_by_default_and_does_nothing(self):
+        self.frame.shots = [shot(1, NOW + 10)]
+        self.frame.clips = [clip(1, NOW + 10)]
+        s = self.sync.state()
+        self.assertFalse(s["screenshots"] or s["clips"])
+        self.assertEqual(self.sync.tick(), fa.INTERVAL)
+        self.assertEqual(self.frame.calls, [])  # not even a listing
+        self.assertFalse((self.dir / "auto-sync.json").exists())
+
+    def test_settings_persist(self):
+        self.sync.update({"screenshots": True})
+        again = self.make().state()
+        self.assertTrue(again["screenshots"])
+        self.assertFalse(again["clips"])
+        self.assertEqual(again["since"], NOW)
+        saved = json.loads((self.dir / "auto-sync.json").read_text())
+        self.assertEqual((saved["screenshots"], saved["clips"]), (True, False))
+
+    def test_only_what_is_newer_than_turning_it_on(self):
+        self.frame.shots = [shot(1, NOW - 3600), shot(2, NOW + 5), shot(3, NOW + 50, saved=True)]
+        self.frame.clips = [clip(1, NOW - 3600), clip(2, NOW + 5)]
+        self.sync.update({"screenshots": True, "clips": True})
+        self.assertEqual(self.sync.tick(), fa.INTERVAL)
+        self.assertEqual(self.frame.saved, [("frame-a", [shot(2, 0)["id"]])])
+        self.assertEqual(self.frame.exported, [("frame-a", clip(2, 0)["id"])])
+        s = self.sync.state()
+        self.assertEqual((s["copied"], s["copied_time"], s["checked"], s["error"]), (2, NOW, NOW, None))
+
+    def test_watermark_moves_when_turned_off_and_on_again(self):
+        self.sync.update({"screenshots": True})
+        self.now[0] += 1000
+        self.sync.update({"clips": True})  # already on: the watermark stays
+        self.assertEqual(self.sync.state()["since"], NOW)
+        self.sync.update({"screenshots": False, "clips": False})
+        self.sync.update({"screenshots": True})
+        self.assertEqual(self.sync.state()["since"], NOW + 1000)
+
+    def test_copy_everything_now_once(self):
+        self.frame.shots = [shot(1, NOW - 3600), shot(2, NOW - 60)]
+        self.frame.clips = [clip(1, NOW - 3600), clip(2, NOW - 60, kind="background")]
+        self.sync.copy_all()  # works with the toggles off too
+        self.assertTrue(self.sync.state()["pending"])
+        self.sync.tick()
+        self.assertEqual(self.frame.saved, [("frame-a", [shot(1, 0)["id"], shot(2, 0)["id"]])])
+        self.assertEqual(self.frame.exported, [("frame-a", clip(1, 0)["id"])])  # never the background recording
+        self.assertFalse(self.sync.state()["pending"])
+        self.frame.calls.clear()
+        self.sync.tick()
+        self.assertEqual(self.frame.calls, [])  # off again afterwards
+
+    def test_not_copied_again_after_deleting_it_here(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.sync.tick()
+        for s in self.frame.shots + self.frame.clips:
+            s["saved"] = False  # the person deleted the files
+        self.frame.saved.clear()
+        self.frame.exported.clear()
+        self.make().tick()  # remembered across restarts too
+        self.assertEqual((self.frame.saved, self.frame.exported), ([], []))
+
+    def test_saved_by_hand_counts_as_copied(self):
+        self.sync.update({"screenshots": True})
+        self.frame.shots = [shot(1, NOW + 5, saved=True)]
+        self.sync.tick()
+        self.frame.shots[0]["saved"] = False
+        self.sync.tick()
+        self.assertEqual(self.frame.saved, [])
+
+    def test_remembered_per_headset(self):
+        self.sync.update({"screenshots": True})
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.sync.tick()
+        self.frame.device = "frame-b"
+        self.frame.shots = [shot(1, NOW + 5)]  # the same name on another headset
+        self.sync.tick()
+        self.assertEqual([d for d, _ in self.frame.saved], ["frame-a", "frame-b"])
+
+    def test_clip_still_being_recorded_waits(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5, idle=4), clip(2, NOW + 6, idle=None)]
+        self.sync.tick()
+        self.assertEqual(self.frame.exported, [])
+        self.assertEqual(self.sync.state()["waiting"], 2)
+        self.frame.clips[0]["idle"] = fa.SETTLE + 1
+        self.sync.tick()
+        self.assertEqual(self.frame.exported, [("frame-a", clip(1, 0)["id"])])
+        self.assertEqual(self.sync.state()["waiting"], 1)
+
+    def test_no_headset_no_work(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.device = None
+        self.assertEqual(self.sync.tick(), fa.INTERVAL)
+        self.assertEqual(self.frame.calls, [])
+
+    def test_waits_for_other_work(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.frame.busy = True
+        self.assertEqual(self.sync.tick(), fa.BUSY_WAIT)
+        self.assertEqual(self.frame.calls, [])
+        self.frame.busy = False
+        self.sync.tick()
+        self.assertEqual(len(self.frame.saved), 1)
+
+    def test_stops_between_items_when_other_work_starts(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5), clip(2, NOW + 6)]
+        export = self.frame.export_clip
+
+        def then_busy(device, clip_id):
+            export(device, clip_id)
+            self.frame.busy = True  # an install started meanwhile
+        self.frame.export_clip = then_busy
+        sync = self.make()
+        self.assertEqual(sync.tick(), fa.BUSY_WAIT)
+        self.assertEqual(len(self.frame.exported), 1)
+
+    def test_backs_off_while_unreachable(self):
+        self.sync.update({"screenshots": True})
+        self.frame.down = True
+        waits = [self.sync.tick() for _ in range(6)]
+        self.assertEqual(waits[:4], [120, 240, 480, 900])
+        self.assertEqual(waits[-1], fa.MAX_BACKOFF)
+        self.assertEqual(self.sync.state()["error"], "The Frame isn't answering.")
+        self.frame.down = False
+        self.assertEqual(self.sync.tick(), fa.INTERVAL)
+        self.assertIsNone(self.sync.state()["error"])
+        self.frame.down = True
+        self.assertEqual(self.sync.tick(), 120)  # starts over after a good look
+
+    def test_pauses_when_this_computer_is_nearly_full(self):
+        self.sync.update({"screenshots": True})
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.free[0] = 10 * 1024**2
+        self.sync.tick()
+        s = self.sync.state()
+        self.assertIn("out of space", s["paused"])
+        self.assertEqual(self.frame.saved, [])
+        self.free[0] = 100 * GB
+        self.frame.calls.clear()
+        self.sync.tick()
+        self.assertEqual(self.frame.calls, [])  # stays paused, also after a restart
+        self.assertTrue(self.make().state()["paused"])
+        self.sync.resume()
+        self.sync.tick()
+        self.assertEqual(len(self.frame.saved), 1)
+        self.assertIsNone(self.sync.state()["paused"])
+
+    def test_pauses_when_a_copy_runs_out_of_space(self):
+        self.sync.update({"screenshots": True, "clips": True})
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.frame.export_error = RuntimeError("Not enough free space on this computer: it needs 900 MB")
+        self.sync.tick()
+        self.assertIn("ran out of space", self.sync.state()["paused"])
+        self.sync.resume()
+        self.frame.export_error = None
+        self.frame.shots = [shot(1, NOW + 5)]
+        self.frame.save_error = OSError(errno.ENOSPC, "No space left on device")
+        self.sync.tick()
+        self.assertTrue(self.sync.state()["paused"])
+
+    def test_space_on_the_frame_is_not_a_pause(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.frame.export_error = RuntimeError("Not enough free space on the Frame to export it: it needs 900 MB")
+        self.sync.tick()
+        s = self.sync.state()
+        self.assertIsNone(s["paused"])
+        self.assertIn("Not enough free space on the Frame", s["error"])
+
+    def test_an_item_that_keeps_failing_is_left_alone(self):
+        self.sync.update({"clips": True})
+        self.frame.clips = [clip(1, NOW + 5)]
+        self.frame.export_error = RuntimeError("ffmpeg couldn't join the recording")
+        for _ in range(fa.TRIES + 2):
+            self.sync.tick()
+        self.assertEqual(self.frame.calls.count("export_clip"), fa.TRIES)
+
+    def test_worker_stops(self):
+        stop = threading.Event()
+        t = threading.Thread(target=self.sync.run, args=(stop,), daemon=True)
+        t.start()
+        stop.set()
+        self.sync.update({})  # wakes it
+        t.join(5)
+        self.assertFalse(t.is_alive())
+
+
+class Server(unittest.TestCase):
+    def test_route_and_settings(self):
+        import server
+        self.assertIn("/api/autosync", server.POST)
+        with self.assertRaises(server.Failure):
+            server.auto_sync({"action": "explode"})
+        state = server.auto_sync({"action": "settings", "screenshots": "yes"})  # not a bool: ignored
+        self.assertFalse(state["screenshots"])
+        if server.LINK is None:
+            with self.assertRaises(server.Failure):
+                server.auto_sync({"action": "now"})  # nothing connected
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_client_preferences.py

@@ -0,0 +1,14 @@
+"""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_clipboard.py

@@ -0,0 +1,241 @@
+"""The clipboard both ways: the headset's read script, the server's answers, and the
+writer for this computer's clipboard on each platform. No headset: SSH and every
+clipboard program are mocked, and the read script runs against stub pgrep and qdbus6."""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import base64
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "ui"))
+import frame_host  # noqa: E402
+import server  # noqa: E402
+
+TEXT = "héllo, 世界 🎧\nsecond line\n\n"  # accents, CJK, an emoji outside the BMP, trailing newlines
+
+
+def b64(text):
+    return base64.b64encode(text.encode()).decode()
+
+
+class ReadCommand(unittest.TestCase):
+    def test_reads_klipper_on_the_desktop_bus(self):
+        self.assertIn("org.kde.klipper.klipper.getClipboardContents", server.COPY)
+        self.assertIn("DBUS_SESSION_BUS_ADDRESS=$bus qdbus6 org.kde.klipper /klipper", server.COPY)
+        self.assertIn(server.DESKTOP_CLOSED, server.COPY)
+        self.assertIn(server.CLIPBOARD_TOO_BIG, server.COPY)
+        self.assertIn(f"-gt {server.CLIPBOARD_LIMIT + 1} ]", server.COPY)  # the limit, plus qdbus6's newline
+        self.assertIn("base64 -w 0", server.COPY)
+
+    def test_command_carries_the_script_intact(self):
+        encoded = server.COPY_CMD.split("echo ", 1)[1].split(" |", 1)[0]
+        self.assertEqual(base64.b64decode(encoded).decode(), server.COPY)
+        self.assertNotIn("'", server.COPY_CMD)
+
+    def test_send_still_uses_the_same_bus(self):
+        self.assertIn(server.DESKTOP_BUS, server.PASTE)
+        self.assertIn(server.DESKTOP_BUS, server.COPY)
+        self.assertIn("setClipboardContents", server.PASTE)
+
+
+@unittest.skipUnless(sys.platform.startswith("linux") and shutil.which("bash") and shutil.which("base64"),
+                     "the script reads /proc, as on the Frame")
+class ReadScript(unittest.TestCase):
+    """server.COPY for real, with plasmashell's pid and Klipper stubbed."""
+
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp(prefix="frame-clip-"))
+        self.addCleanup(shutil.rmtree, self.dir, True)
+        self.clip = self.dir / "clip"
+        # A process whose environment holds the desktop's bus address, standing in for plasmashell.
+        self.plasma = subprocess.Popen(["sleep", "60"], env={**os.environ, "DBUS_SESSION_BUS_ADDRESS": "unix:path=/fake"})
+        self.addCleanup(self.plasma.wait)
+        self.addCleanup(self.plasma.kill)
+        (self.dir / "pgrep").write_text(f'#!/bin/sh\n[ -e "{self.dir}/closed" ] || echo {self.plasma.pid}\n')
+        (self.dir / "qdbus6").write_text(
+            '#!/bin/sh\n[ "$DBUS_SESSION_BUS_ADDRESS" = unix:path=/fake ] || exit 1\n'
+            f'[ "$3" = org.kde.klipper.klipper.getClipboardContents ] || exit 1\ncat "{self.clip}"; echo\n')
+        for name in ("pgrep", "qdbus6"):
+            (self.dir / name).chmod(0o755)
+
+    def run_script(self):
+        def local_ssh(remote, **kw):
+            r = subprocess.run(["bash", "-c", server.COPY], capture_output=True, text=True,
+                               env={**os.environ, "PATH": f"{self.dir}:{os.environ['PATH']}"})
+            if r.returncode:
+                raise server.Failure(r.stderr.strip())
+            return r.stdout
+        with mock.patch.object(server, "ssh", local_ssh):
+            return server.headset_clipboard()
+
+    def test_unicode_and_newlines_come_back_exactly(self):
+        self.clip.write_bytes(TEXT.encode())
+        self.assertEqual(self.run_script(), TEXT)
+
+    def test_empty(self):
+        self.clip.write_bytes(b"")
+        with self.assertRaises(server.Failure) as cm:
+            self.run_script()
+        self.assertEqual(cm.exception.status, 400)
+        self.assertIn("empty", str(cm.exception))
+
+    def test_too_big_is_refused_on_the_headset(self):
+        self.clip.write_bytes(b"x" * (server.CLIPBOARD_LIMIT + 1))
+        with self.assertRaises(server.Failure) as cm:
+            self.run_script()
+        self.assertEqual(cm.exception.status, 413)
+        self.assertIn("1 MB", str(cm.exception))
+        self.clip.write_bytes(b"x" * server.CLIPBOARD_LIMIT)
+        self.assertEqual(len(self.run_script()), server.CLIPBOARD_LIMIT)
+
+    def test_desktop_closed(self):
+        (self.dir / "closed").touch()
+        with self.assertRaises(server.Failure) as cm:
+            self.run_script()
+        self.assertEqual(cm.exception.status, 409)
+
+
+class HeadsetClipboard(unittest.TestCase):
+    def read(self, out=None, error=None):
+        def fake_ssh(remote, **kw):
+            self.assertEqual(remote, server.COPY_CMD)
+            self.assertNotIn("stdin", kw)
+            if error:
+                raise server.Failure(error)
+            return out
+        with mock.patch.object(server, "ssh", fake_ssh):
+            return server.headset_clipboard()
+
+    def test_drops_only_qdbus6s_newline(self):
+        self.assertEqual(self.read(b64(TEXT + "\n") + "\n"), TEXT)
+        self.assertEqual(self.read(b64("one line\n")), "one line")
+
+    def test_empty_and_images_say_so(self):
+        for out, words in ((b64("\n"), "empty"), ("", "empty"), (b64("▨ 640x480 32bpp\n"), "image")):
+            with self.assertRaises(server.Failure) as cm:
+                self.read(out)
+            self.assertEqual(cm.exception.status, 400)
+            self.assertIn(words, str(cm.exception))
+
+    def test_unreadable_output_is_a_fault(self):
+        for out in ("not base64!", base64.b64encode(b"\xff\xfe\n").decode()):
+            with self.assertRaises(server.Failure) as cm:
+                self.read(out)
+            self.assertEqual(cm.exception.status, 502)
+
+    def test_failures(self):
+        for error, status in (("The headset's desktop isn't open (plasmashell is not running).", 409),
+                              ("The headset's clipboard holds too much to copy (over 1 MB).", 413),
+                              ("Klipper call failed (bus: none)", 502)):
+            with self.assertRaises(server.Failure) as cm:
+                self.read(error=error)
+            self.assertEqual(cm.exception.status, status, error)
+
+
+class ClipboardRequests(unittest.TestCase):
+    def test_read_returns_the_text_for_the_page(self):
+        with mock.patch.object(server, "headset_clipboard", return_value=TEXT):
+            out = server.clipboard({"read": True})
+        self.assertEqual(out["text"], TEXT)
+        self.assertNotIn(TEXT, out["message"])
+
+    def test_to_computer_sets_this_computers_clipboard(self):
+        with mock.patch.object(server, "headset_clipboard", return_value=TEXT), \
+                mock.patch.object(frame_host, "set_clipboard_text") as put:
+            out = server.clipboard({"toComputer": True})
+        put.assert_called_once_with(TEXT)
+        self.assertNotIn("text", out)
+        self.assertEqual(out["message"], f"Copied {len(TEXT)} characters from the headset to this computer's clipboard")
+
+    def test_to_computer_without_a_clipboard_program(self):
+        with mock.patch.object(server, "headset_clipboard", return_value=TEXT), \
+                mock.patch.object(frame_host, "set_clipboard_text", side_effect=frame_host.HostError("Can't set the clipboard")):
+            with self.assertRaises(server.Failure) as cm:
+                server.clipboard({"toComputer": True})
+        self.assertEqual(cm.exception.status, 500)
+
+    def test_to_computer_refused_when_the_server_runs_on_the_headset(self):
+        with mock.patch.object(server, "LOCAL", True), mock.patch.object(server, "headset_clipboard") as read:
+            with self.assertRaises(server.Failure) as cm:
+                server.clipboard({"toComputer": True})
+        self.assertEqual(cm.exception.status, 400)
+        read.assert_not_called()
+
+    def test_flags_must_be_true(self):
+        # Anything else is a send, and an empty one is refused before SSH.
+        with mock.patch.object(server, "ssh") as ssh:
+            for body in ({"read": "yes"}, {"toComputer": 1}):
+                with self.assertRaises(server.Failure):
+                    server.clipboard(body)
+        ssh.assert_not_called()
+
+
+class SetClipboardText(unittest.TestCase):
+    def put(self, platform, have, text=TEXT, fail=()):
+        runs = []
+
+        def run(cmd, **kw):
+            runs.append((cmd, kw))
+            if cmd[0] in fail:
+                if fail[cmd[0]] == "timeout":
+                    raise subprocess.TimeoutExpired(cmd, 10)
+                return subprocess.CompletedProcess(cmd, 1)
+            return subprocess.CompletedProcess(cmd, 0)
+        flags = {"MAC": platform == "mac", "WINDOWS": platform == "windows", "LINUX": platform == "linux"}
+        with mock.patch.multiple(frame_host, **flags), \
+                mock.patch.object(frame_host.shutil, "which", lambda name: f"/bin/{name}" if name in have else None), \
+                mock.patch.object(frame_host.subprocess, "run", run):
+            frame_host.set_clipboard_text(text)
+        for _, kw in runs:
+            # Nothing captured or logged, and no pipes left for a clipboard daemon to hold open.
+            self.assertEqual((kw["stdout"], kw["stderr"]), (subprocess.DEVNULL, subprocess.DEVNULL))
+        return runs
+
+    def test_mac_pbcopy_in_utf8(self):
+        [(cmd, kw)] = self.put("mac", {"pbcopy"})
+        self.assertEqual(cmd, ["pbcopy"])
+        self.assertEqual(kw["input"], TEXT.encode("utf-8"))
+        self.assertEqual(kw["env"]["LC_CTYPE"], "UTF-8")
+
+    def test_windows_powershell_gets_base64_utf8(self):
+        [(cmd, kw)] = self.put("windows", {"powershell.exe", "clip.exe"})
+        self.assertEqual(cmd[0], "powershell.exe")
+        self.assertIn("Set-Clipboard", cmd[-1])
+        self.assertIn("FromBase64String", cmd[-1])
+        self.assertEqual(base64.b64decode(kw["input"]).decode("utf-8"), TEXT)
+
+    def test_windows_clip_fallback_gets_utf16_with_a_bom(self):
+        runs = self.put("windows", {"powershell.exe", "clip.exe"}, fail={"powershell.exe": 1})
+        self.assertEqual([c[0] for c, _ in runs], ["powershell.exe", "clip.exe"])
+        data = runs[1][1]["input"]
+        self.assertEqual(data[:2], b"\xff\xfe")
+        self.assertEqual(data[2:].decode("utf-16-le"), TEXT)
+
+    def test_linux_tries_wayland_then_x11(self):
+        [(cmd, kw)] = self.put("linux", {"wl-copy", "xclip", "xsel"})
+        self.assertEqual(cmd, ["wl-copy"])
+        self.assertEqual(kw["input"], TEXT.encode())
+        runs = self.put("linux", {"wl-copy", "xclip", "xsel"}, fail={"wl-copy": 1, "xclip": "timeout"})
+        self.assertEqual([c for c, _ in runs], [["wl-copy"], ["xclip", "-selection", "clipboard", "-in"],
+                                                ["xsel", "--clipboard", "--input"]])
+        [(cmd, _)] = self.put("linux", {"xsel"})
+        self.assertEqual(cmd[0], "xsel")
+
+    def test_nothing_to_set_it_with(self):
+        with self.assertRaises(frame_host.HostError) as cm:
+            self.put("linux", set())
+        self.assertIn("wl-clipboard", str(cm.exception))
+        with self.assertRaises(frame_host.HostError):
+            self.put("linux", {"wl-copy"}, fail={"wl-copy": 1})
+        with self.assertRaises(frame_host.HostError):
+            self.put("mac", set())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_clips.py

@@ -0,0 +1,562 @@
+"""Recordings of the headset view and Steam clip exports (ui/frame_clips.py), without a headset.
+
+Steam's recordings are fixture trees in the layout frame_clips.py describes. The
+recording's shell runs for real under bash with a stand-in ffmpeg, so Stop, the time
+limit and the clean-up are the real script's behaviour. With ffmpeg installed here, a
+65-second DASH recording is made in Steam's file naming and exported for real.
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "ui"))
+import frame_clips as clips  # noqa: E402
+
+POSIX = os.name != "nt" and shutil.which("bash")
+
+
+def write(path, data=b"x"):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    return path
+
+
+def session(folder, streams=(0, 1), chunks=3, mpd=None, first=1, pad=5):
+    """A session folder as Steam writes it: init + numbered chunks per stream."""
+    for n in streams:
+        write(folder / f"init-stream{n}.m4s", f"init{n};".encode())
+        for c in range(first, first + chunks):
+            write(folder / f"chunk-stream{n}-{c:0{pad}d}.m4s", f"s{n}c{c};".encode())
+    if mpd is not None:
+        write(folder / "session.mpd", mpd.encode())
+    return folder
+
+
+class Ids(unittest.TestCase):
+    def test_good_ids(self):
+        for cid in ("123/video/bg_620_20261020_201950",
+                    "123/clips/clip_620_20261020_202134/video/bg_620_20261020_201950",
+                    "9/clips/a/b/c/d"):
+            self.assertEqual(clips.parse_id(cid)[0], cid.split("/")[0])
+        self.assertEqual(clips.export_name("123/clips/clip_620_20261020_202134/video/bg_620_1"),
+                         "clip_620_20261020_202134.mp4")
+
+    def test_no_traversal_or_shell_from_ids(self):
+        for cid in ("", None, 5, "123", "123/video", "123/other/bg", "abc/video/bg", "/123/video/bg",
+                    "123/video/..", "123/video/.", "123/video/bg/../../../../.ssh", "123/video/.hidden",
+                    "123/video/bg;rm -rf ~", "123/video/bg$(id)", "123/video/bg name", "123/video/bg\n",
+                    "123/video/%2e%2e", "123\\video\\bg", "123/video//bg", "123/clips/a/b/c/d/e",
+                    "123/video/" + "a" * 101, "1234567890123/video/bg"):
+            with self.subTest(cid=cid), self.assertRaises(ValueError):
+                clips.parse_id(cid)
+            with self.subTest(cid=cid), self.assertRaises(ValueError):
+                clips.export_name(cid)
+
+    def test_export_paths_checked_before_delete(self):
+        good = f"{clips.WORK}/export-0123456789abcdef/clip_620.mp4"
+        self.assertEqual(clips.remove_command(good), f'rm -rf "$HOME"/{clips.WORK}/export-0123456789abcdef')
+        for bad in (None, "", "/etc/passwd", f"{clips.WORK}/export-0123456789abcdef/../../x.mp4",
+                    f"{clips.WORK}/export-xyz/clip.mp4", f"{clips.WORK}/../export-0123456789abcdef/a.mp4",
+                    f"{clips.WORK}/export-0123456789abcdef/a.mp4; rm -rf ~", ".ssh/export-0123456789abcdef/a.mp4"):
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                clips.remove_command(bad)
+
+    def test_recording_names_checked(self):
+        for fn in (clips.finish_command, clips.cleanup_command, lambda n: clips.record_command(n, True)):
+            for bad in ("rec-1", "rec-20261020-201950; rm -rf ~", "../rec-20261020-201950", "*"):
+                with self.subTest(bad=bad), self.assertRaises(ValueError):
+                    fn(bad)
+
+
+class Sessions(unittest.TestCase):
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+
+    def test_chunks_in_number_order_whatever_the_padding(self):
+        s = self.dir / "s"
+        write(s / "init-stream0.m4s")
+        for c in (10, 2, 1, 100, 9):
+            write(s / f"chunk-stream0-{c}.m4s")
+        write(s / "chunk-stream0-00003.m4s")
+        got = clips.read_session(s)
+        self.assertEqual([os.path.basename(p) for p in got[0]],
+                         ["init-stream0.m4s", "chunk-stream0-1.m4s", "chunk-stream0-2.m4s", "chunk-stream0-00003.m4s",
+                          "chunk-stream0-9.m4s", "chunk-stream0-10.m4s", "chunk-stream0-100.m4s"])
+        self.assertEqual(clips.chunk_gaps(got[0]), 100 - 6)
+
+    def test_unplayable_streams_and_strangers_left_out(self):
+        s = self.dir / "s"
+        session(s, streams=(0,), chunks=2)
+        write(s / "init-stream1.m4s")                 # no chunks
+        write(s / "chunk-stream2-00001.m4s")          # no init
+        write(s / "chunk-stream0-00001.m4s.part")     # not a chunk
+        write(s / "thumbnail.jpg")
+        (s / "chunk-stream0-00009.m4s").mkdir()       # a folder, not a file
+        if POSIX:
+            os.symlink("/etc/passwd", s / "chunk-stream0-00005.m4s")  # links aren't followed
+        got = clips.read_session(s)
+        self.assertEqual(list(got), [0])
+        self.assertEqual(len(got[0]), 3)
+
+    def test_manifest_duration(self):
+        for text, want in (('mediaPresentationDuration="PT1M23.4S"', 83.4), ('mediaPresentationDuration="PT2H"', 7200),
+                           ('mediaPresentationDuration="PT0H3M0.000S"', 180), ('mediaPresentationDuration="P1DT1S"', 86401),
+                           ('mediaPresentationDuration="PT"', None), ('nothing here', None), (None, None)):
+            self.assertEqual(clips.mpd_duration(text), want, text)
+
+    def test_listing_a_fixture_tree(self):
+        ud = self.dir / "userdata"
+        gr = ud / "123" / "gamerecordings"
+        session(gr / "clips" / "clip_620_20261020_202134" / "video" / "bg_620_20261020_201950", chunks=40,
+                mpd='<MPD mediaPresentationDuration="PT1M20.0S">')
+        write(gr / "clips" / "clip_620_20261020_202134" / "thumbnail.jpg")
+        session(gr / "video" / "bg_1172470_20261021_090000", streams=(0,), chunks=2)
+        session(gr / "video" / "odd-name", chunks=1)                   # no stamp: time from the files
+        (gr / "video" / "empty").mkdir()
+        session(gr / "video" / ".hidden", chunks=1)                    # not a name an id can carry
+        session(gr / "timelines" / "x", chunks=1)                      # not clips/ or video/
+        session(ud / "notanaccount" / "gamerecordings" / "video" / "bg_1_20260101_000000", chunks=1)
+        session(gr / "video" / "a" / "b" / "c" / "d" / "e", chunks=1)  # deeper than ids go
+        if POSIX:
+            os.symlink(gr, gr / "video" / "loop")                      # links aren't followed
+        for f in (gr / "video" / "odd-name").iterdir():
+            os.utime(f, (1e9, 1e9))  # 2001: older than the others
+        got = clips.list_recordings(ud)
+        self.assertEqual([c["id"] for c in got], ["123/video/bg_1172470_20261021_090000",
+                                                  "123/clips/clip_620_20261020_202134/video/bg_620_20261020_201950",
+                                                  "123/video/odd-name"])  # newest first
+        self.assertEqual(got[-1]["time"], 1e9)
+        by = {c["id"]: c for c in got}
+        clip = by["123/clips/clip_620_20261020_202134/video/bg_620_20261020_201950"]
+        self.assertEqual((clip["kind"], clip["appid"], clip["streams"], clip["chunks"], clip["gaps"], clip["duration"]),
+                         ("clip", "620", 2, 80, 0, 80.0))
+        self.assertEqual(clip["file"], "clip_620_20261020_202134.mp4")
+        self.assertEqual(clip["time"], time.mktime((2026, 10, 20, 20, 21, 34, 0, 0, -1)))
+        self.assertEqual(clip["size"], sum(f.stat().st_size for f in
+                                           (gr / "clips" / "clip_620_20261020_202134" / "video" / "bg_620_20261020_201950").iterdir()
+                                           if f.suffix == ".m4s"))
+        bg = by["123/video/bg_1172470_20261021_090000"]
+        self.assertEqual((bg["kind"], bg["appid"], bg["streams"], bg["duration"]), ("background", "1172470", 1, None))
+        self.assertIsNone(by["123/video/odd-name"]["appid"])
+        # How long since Steam last wrote to it: auto-sync waits for a clip still being recorded.
+        self.assertLess(clip["idle"], 60)
+        self.assertGreater(by["123/video/odd-name"]["idle"], 10**8)
+        self.assertEqual(clips.list_recordings(self.dir / "missing"), [])
+
+    def test_listing_marks_what_is_already_here(self):
+        here = self.dir / "here"
+        write(here / "clip_620_20261020_202134.mp4")
+        frame = lambda args, timeout: {"clips": [{"id": "1/clips/clip_620_20261020_202134/video/bg"},
+                                                 {"id": "1/video/bg_620_20261020_201950"}]}
+        got = clips.list_clips(frame, folder=here)
+        self.assertEqual([c["saved"] for c in got["clips"]], [True, False])
+        self.assertEqual(got["folder"], str(here))
+
+
+class Export(unittest.TestCase):
+    """The Frame's half of an export, against a fixture tree, with ffmpeg stood in."""
+
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+        self.ud = self.dir / "home" / clips.STEAM_USERDATA
+        self.home = self.dir / "home"
+        self.cid = "123/clips/clip_620_20261020_202134/video/bg_620_20261020_201950"
+        session(self.ud / "123" / "gamerecordings" / "clips" / "clip_620_20261020_202134" / "video" /
+                "bg_620_20261020_201950", chunks=12)
+
+    def fake_ffmpeg(self, seen, rc=0):
+        def run(cmd, **kw):
+            ins = [cmd[i + 1] for i, a in enumerate(cmd) if a == "-i"]
+            seen.append({"cmd": cmd, "inputs": {Path(i).name: Path(i).read_bytes() for i in ins}})
+            if rc == 0:
+                Path(cmd[-1]).write_bytes(b"mp4")
+            return subprocess.CompletedProcess(cmd, rc, "", "Invalid data found" if rc else "")
+        return run
+
+    def test_streams_stitched_in_order_and_copied_not_reencoded(self):
+        seen = []
+        with mock.patch.object(clips.subprocess, "run", self.fake_ffmpeg(seen)):
+            got = clips.export(self.ud, self.cid, home=self.home)
+        self.assertRegex(got["path"], clips.EXPORT_PATH)
+        self.assertTrue(got["path"].endswith("/clip_620_20261020_202134.mp4"))
+        self.assertEqual(got["size"], 3)
+        cmd = seen[0]["cmd"]
+        self.assertEqual(cmd[cmd.index("-c") + 1], "copy")
+        self.assertEqual([cmd[i + 1] for i, a in enumerate(cmd) if a == "-map"], ["0", "1"])
+        for n in (0, 1):
+            self.assertEqual(seen[0]["inputs"][f"stream{n}.mp4"],
+                             f"init{n};".encode() + b"".join(f"s{n}c{c};".encode() for c in range(1, 13)))
+        out = self.home / got["path"]
+        self.assertEqual(sorted(p.name for p in out.parent.iterdir()), [out.name])  # stream files gone
+
+    def test_failed_join_leaves_nothing_behind(self):
+        with mock.patch.object(clips.subprocess, "run", self.fake_ffmpeg([], rc=1)):
+            with self.assertRaisesRegex(clips.ClipError, "Invalid data"):
+                clips.export(self.ud, self.cid, home=self.home)
+        self.assertEqual(list((self.home / clips.WORK).glob("export-*")), [])
+
+    def test_bad_or_missing_ids(self):
+        with self.assertRaises(ValueError):
+            clips.export(self.ud, "123/video/../../../../etc", home=self.home)
+        with self.assertRaises(ClipErrorOrOSError):
+            clips.export(self.ud, "123/video/nothing_here", home=self.home)
+
+    @unittest.skipUnless(POSIX, "symlinks")
+    def test_a_linked_account_cannot_reach_outside_userdata(self):
+        outside = session(self.dir / "elsewhere" / "gamerecordings" / "video" / "bg_1_20260101_000000", chunks=1)
+        os.symlink(self.dir / "elsewhere", self.ud / "456")
+        self.assertIsNotNone(outside)
+        with self.assertRaises(ValueError):
+            clips.export(self.ud, "456/video/bg_1_20260101_000000", home=self.home)
+
+    def test_no_space_on_the_frame(self):
+        full = mock.Mock(free=10)
+        with mock.patch.object(clips.shutil, "disk_usage", return_value=full):
+            with self.assertRaisesRegex(clips.ClipError, "Not enough free space on the Frame"):
+                clips.export(self.ud, self.cid, home=self.home)
+
+    def test_old_exports_swept(self):
+        work = self.home / clips.WORK
+        old, new = work / "export-aaaaaaaaaaaaaaaa", work / "export-bbbbbbbbbbbbbbbb"
+        write(old / "x.mp4"), write(new / "y.mp4")
+        os.utime(old, (time.time() - 7 * 3600,) * 2)
+        with mock.patch.object(clips.subprocess, "run", self.fake_ffmpeg([])):
+            clips.export(self.ud, self.cid, home=self.home)
+        self.assertFalse(old.exists())
+        self.assertTrue(new.exists())
+
+    def test_main_prints_json(self):
+        with mock.patch.object(clips.Path, "home", return_value=self.home), \
+                mock.patch("sys.stdout", new_callable=lambda: __import__("io").StringIO()) as out:
+            self.assertEqual(clips.main(["list"]), 0)
+            self.assertEqual(json.loads(out.getvalue())["clips"][0]["id"], self.cid)
+        with mock.patch("sys.stdout", new_callable=lambda: __import__("io").StringIO()) as out:
+            self.assertEqual(clips.main(["export", "../../x"]), 1)
+            self.assertEqual(json.loads(out.getvalue()), {"error": "bad clip id"})
+
+
+ClipErrorOrOSError = (clips.ClipError, OSError)
+
+
+class ComputerSide(unittest.TestCase):
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+
+    def test_export_copies_then_deletes_on_the_frame(self):
+        path = f"{clips.WORK}/export-0123456789abcdef/clip_620.mp4"
+        calls = []
+        frame = lambda args, timeout: calls.append(("frame", args)) or {"path": path, "size": 3}
+        run = lambda cmd, timeout: calls.append(("run", cmd))
+        fetch = lambda remote, local: calls.append(("fetch", remote)) or Path(local).write_bytes(b"mp4")
+        got = clips.export_clip("1/clips/clip_620/video/bg", frame, run, fetch, folder=self.dir)
+        self.assertEqual(got["message"], "Saved clip_620.mp4 to ~/Videos/SteamFrame")
+        self.assertEqual((self.dir / "clip_620.mp4").read_bytes(), b"mp4")
+        self.assertEqual([c[0] for c in calls], ["frame", "fetch", "run"])
+        self.assertEqual(calls[2][1], clips.remove_command(path))
+        self.assertEqual([p.name for p in self.dir.iterdir()], ["clip_620.mp4"])
+
+    def test_failed_copy_leaves_no_partial_file_and_still_cleans_up(self):
+        path = f"{clips.WORK}/export-0123456789abcdef/clip_620.mp4"
+        ran = []
+
+        def fetch(remote, local):
+            Path(local).write_bytes(b"half")
+            raise RuntimeError("connection lost")
+        with self.assertRaisesRegex(RuntimeError, "connection lost"):
+            clips.export_clip("1/clips/clip_620/video/bg", lambda a, t: {"path": path, "size": 4},
+                              lambda cmd, timeout: ran.append(cmd), fetch, folder=self.dir)
+        self.assertEqual(list(self.dir.iterdir()), [])
+        self.assertEqual(ran, [clips.remove_command(path)])
+
+    def test_bad_id_never_reaches_the_frame(self):
+        never = mock.Mock(side_effect=AssertionError("reached the Frame"))
+        with self.assertRaises(ValueError):
+            clips.export_clip("1/video/../../.ssh", never, never, never, folder=self.dir)
+
+    def test_unexpected_path_from_the_frame_refused(self):
+        never = mock.Mock(side_effect=AssertionError("deleted or copied"))
+        with self.assertRaises(ValueError):
+            clips.export_clip("1/video/bg", lambda a, t: {"path": ".ssh/id_ed25519", "size": 1}, never, never,
+                              folder=self.dir)
+
+
+class Commands(unittest.TestCase):
+    def test_record_command_with_and_without_sound(self):
+        with_sound = shlex.split(clips.record_command("rec-20261020-201950", True))
+        self.assertEqual(with_sound[:2], ["bash", "-c"])
+        script = with_sound[2]
+        self.assertIn(f"-f v4l2 -video_size 1920x1080 -i {clips.STREAM_DEVICE}", script)
+        self.assertIn("-c:v libx264", script)
+        self.assertNotIn("v4l2m2m", script)  # the hardware encoder crashes ffmpeg
+        self.assertIn(f"-f pulse -i {clips.AUDIO_SOURCE}", script)
+        self.assertIn("-map 1:a:0", script)
+        self.assertIn("-c:a aac", script)
+        self.assertIn(f"-t {clips.MAX_SECONDS} ", script)
+        self.assertIn('"$d/rec-20261020-201950.mkv"', script)
+        self.assertEqual(script.count("-use_wallclock_as_timestamps 1"), 2)
+        quiet = shlex.split(clips.record_command("rec-20261020-201950", False))[2]
+        self.assertNotIn("pulse", quiet)
+        self.assertNotIn("-c:a", quiet)
+        self.assertEqual(quiet.count("-use_wallclock_as_timestamps 1"), 1)
+        with self.assertRaises(ValueError):
+            clips.record_command("rec-20261020-201950", True, max_seconds=clips.MAX_SECONDS + 1)
+
+    def test_probe_checks_device_space_and_sound(self):
+        probe = clips.probe_command()
+        self.assertIn(f"[ -e {clips.STREAM_DEVICE} ]", probe)
+        self.assertIn(f"-ge {clips.NEED_KB} ]", probe)
+        self.assertIn(f"timeout 5 ffmpeg -hide_banner -loglevel error -nostdin -f pulse -i {clips.AUDIO_SOURCE}", probe)
+        self.assertIn("echo audio=1; else echo audio=0", probe)
+        self.assertIn(f'd="$HOME/{clips.WORK}"', probe)
+
+    def test_finish_remuxes_without_reencoding(self):
+        cmd = clips.finish_command("rec-20261020-201950")
+        self.assertIn("-i rec-20261020-201950.mkv -map 0 -c copy -movflags +faststart rec-20261020-201950.mp4", cmd)
+        self.assertNotIn("libx264", cmd)
+        self.assertEqual(clips.cleanup_command("rec-20261020-201950"), f'rm -f "$HOME/{clips.WORK}/rec-20261020-201950".*')
+
+    def test_stitch_command(self):
+        self.assertEqual(clips.stitch_command(["a.mp4", "b.mp4"], "out.mp4"),
+                         ["ffmpeg", "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", "a.mp4", "-i", "b.mp4",
+                          "-map", "0", "-map", "1", "-c", "copy", "-movflags", "+faststart", "out.mp4"])
+
+
+# A stand-in for ffmpeg on the Frame: records how it was run, writes its output file,
+# and finishes the file when asked to stop (SIGTERM), as ffmpeg does. FAKE_FFMPEG_RUN
+# makes the recording end by itself after that many seconds (the time limit).
+FAKE_FFMPEG = r'''#!/usr/bin/env python3
+import json, os, signal, sys, time
+home = os.environ["HOME"]
+with open(os.path.join(home, "ffmpeg-calls.jsonl"), "a") as f:
+    f.write(json.dumps(sys.argv[1:]) + "\n")
+out = sys.argv[-1]
+if "-c" in sys.argv and sys.argv[sys.argv.index("-c") + 1] == "copy":   # the remux after a recording
+    src = sys.argv[sys.argv.index("-i") + 1]
+    open(out, "wb").write(open(src, "rb").read() + b"+mp4")
+    sys.exit(0)
+stop = []
+signal.signal(signal.SIGTERM, lambda *a: stop.append("TERM"))
+f = open(out, "wb")
+f.write(b"v"); f.flush()
+with open(os.path.join(home, "ffmpeg.pid.tmp"), "w") as p:
+    p.write(str(os.getpid()))
+os.replace(os.path.join(home, "ffmpeg.pid.tmp"), os.path.join(home, "ffmpeg.pid"))
+end = time.time() + float(os.environ.get("FAKE_FFMPEG_RUN", "60"))
+while not stop and time.time() < end:
+    f.write(b"v"); f.flush(); time.sleep(0.05)
+f.close()
+open(os.path.join(home, "ffmpeg-ended"), "w").write(stop[0] if stop else "limit")
+sys.exit(255 if stop else 0)
+'''
+
+
+@unittest.skipUnless(POSIX, "the recording's shell is bash on the Frame")
+class Recording(unittest.TestCase):
+    """The Recorder with the real record/finish/cleanup shell, run locally under bash."""
+
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+        self.frame = self.dir / "frame"           # the Frame's home
+        (self.frame / clips.WORK).mkdir(parents=True)
+        bin_dir = self.dir / "bin"
+        write(bin_dir / "ffmpeg", FAKE_FFMPEG.encode()).chmod(0o755)
+        self.env = {**os.environ, "HOME": str(self.frame), "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}"}
+        self.here = self.dir / "Videos"
+        self.channels, self.released, self.ran = [], [], []
+        self.audio = "audio=1"
+
+    def open_channel(self, command, stderr):
+        proc = subprocess.Popen(shlex.split(command), stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr,
+                                env=self.env)
+        self.channels.append(proc)
+        self.addCleanup(lambda: proc.poll() is None and proc.kill())
+        return proc
+
+    def run_cmd(self, command, timeout):
+        self.ran.append(command)
+        if command == clips.probe_command():
+            return self.audio + "\n"  # needs /dev/video99, so answered here
+        r = subprocess.run(["bash", "-c", command], capture_output=True, text=True, env=self.env, timeout=timeout)
+        if r.returncode:
+            raise RuntimeError(r.stderr.strip() or f"exit {r.returncode}")
+        return r.stdout
+
+    def fetch(self, remote, local):
+        shutil.copyfile(self.frame / remote, local)
+
+    def recorder(self):
+        rec = clips.Recorder(self.open_channel, self.run_cmd, self.fetch,
+                             lambda fn: threading.Thread(target=fn, daemon=True).start(),
+                             release=self.released.append, folder=self.here)
+        start = rec.start
+
+        def started():
+            # "started" means ffmpeg was launched; wait until it's running, as it would be by a person's Stop.
+            pid = self.frame / "ffmpeg.pid"
+            for f in (pid, self.frame / "ffmpeg-ended"):
+                f.unlink(missing_ok=True)
+            got = start()
+            for _ in range(200):
+                if pid.exists() or (self.frame / "ffmpeg-ended").exists():
+                    break
+                time.sleep(0.02)
+            return got
+        rec.start = started
+        return rec
+
+    def wait_for(self, rec, states, timeout=20):
+        end = time.time() + timeout
+        while time.time() < end:
+            s = rec.status()
+            if s["state"] in states:
+                return s
+            time.sleep(0.05)
+        self.fail(f"still {rec.status()}")
+
+    def ffmpeg_calls(self):
+        return [json.loads(line) for line in (self.frame / "ffmpeg-calls.jsonl").read_text().splitlines()]
+
+    def test_stop_finishes_the_file_and_copies_it_here(self):
+        rec = self.recorder()
+        started = rec.start()
+        self.assertEqual((started["state"], started["audio"], started["message"]), ("recording", True, "Recording"))
+        self.assertIn("pulse", self.ffmpeg_calls()[0])
+        time.sleep(0.3)
+        self.assertEqual(rec.stop()["state"], "stopping")
+        done = self.wait_for(rec, ("saved", "failed"))
+        self.assertEqual(done["state"], "saved", done)
+        self.assertEqual((self.frame / "ffmpeg-ended").read_text(), "TERM")  # asked to finish, not killed
+        saved = Path(done["file"])
+        self.assertEqual(saved.parent, self.here)
+        self.assertRegex(saved.name, r"^rec-\d{8}-\d{6}\.mp4$")
+        self.assertTrue(saved.read_bytes().endswith(b"+mp4"))
+        self.assertEqual([p.name for p in self.here.iterdir()], [saved.name])          # no .incoming- left
+        self.assertEqual(list((self.frame / clips.WORK).iterdir()), [])                 # cleaned on the Frame
+        self.assertIsNotNone(self.channels[0].poll())                                   # the channel has gone
+        self.assertEqual(self.released, self.channels)
+        self.assertEqual(self.ran[-1], clips.cleanup_command(saved.stem))
+
+    def test_channel_closing_stops_ffmpeg_on_the_frame(self):
+        # The computer's ssh going away closes the channel just as Stop does.
+        rec = self.recorder()
+        rec.start()
+        pid = int((self.frame / "ffmpeg.pid").read_text())
+        self.channels[0].stdin.close()
+        self.wait_for(rec, ("saved", "failed"))
+        self.assertEqual((self.frame / "ffmpeg-ended").read_text(), "TERM")
+        with self.assertRaises(ProcessLookupError):
+            for _ in range(100):
+                os.kill(pid, 0)
+                time.sleep(0.05)
+
+    def test_time_limit_saves_on_its_own(self):
+        self.env["FAKE_FFMPEG_RUN"] = "0.3"
+        rec = self.recorder()
+        rec.start()
+        done = self.wait_for(rec, ("saved", "failed"))
+        self.assertEqual(done["state"], "saved", done)
+        self.assertEqual((self.frame / "ffmpeg-ended").read_text(), "limit")
+        with self.assertRaisesRegex(clips.ClipError, "Not recording"):
+            rec.stop()
+
+    def test_no_sound_records_video_and_says_so(self):
+        self.audio = "audio=0"
+        rec = self.recorder()
+        started = rec.start()
+        self.assertFalse(started["audio"])
+        self.assertIn("without sound", started["message"])
+        self.assertNotIn("pulse", self.ffmpeg_calls()[0])
+        rec.stop()
+        done = self.wait_for(rec, ("saved", "failed"))
+        self.assertIn("(no sound)", done["message"])
+
+    def test_one_at_a_time(self):
+        rec = self.recorder()
+        with self.assertRaisesRegex(clips.ClipError, "Not recording"):
+            rec.stop()
+        rec.start()
+        with self.assertRaises(clips.ClipError) as e:
+            rec.start()
+        self.assertEqual(e.exception.status, 409)
+        rec.stop()
+        self.wait_for(rec, ("saved",))
+        rec.start()  # a new one once the last is saved
+        rec.stop()
+        self.wait_for(rec, ("saved",))
+
+    def test_failed_start_reports_why(self):
+        rec = clips.Recorder(lambda cmd, err: subprocess.Popen(["bash", "-c", "echo 'no v4l2 here' >&2; exit 1"],
+                                                               stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=err),
+                             lambda cmd, t: "audio=1", self.fetch, lambda fn: fn(), release=self.released.append,
+                             folder=self.here)
+        with self.assertRaisesRegex(clips.ClipError, "no v4l2 here"):
+            rec.start()
+        self.assertEqual(rec.status()["state"], "failed")
+        self.assertEqual(len(self.released), 1)
+
+    def test_failed_probe_reports_why(self):
+        def run(cmd, timeout):
+            raise clips.ClipError("No headset view device (/dev/video99). Is SteamVR running?")
+        rec = clips.Recorder(mock.Mock(side_effect=AssertionError("recorded anyway")), run, self.fetch,
+                             lambda fn: fn(), folder=self.here)
+        with self.assertRaisesRegex(clips.ClipError, "Is SteamVR running"):
+            rec.start()
+        self.assertEqual(rec.status()["state"], "failed")
+
+    def test_empty_recording_is_an_error_not_a_file(self):
+        self.env["FAKE_FFMPEG_RUN"] = "0"
+        rec = self.recorder()
+        with mock.patch.object(clips, "finish_command", lambda name: f"echo 'The recording is empty' >&2; exit 1"):
+            rec.start()
+            done = self.wait_for(rec, ("saved", "failed"))
+        self.assertEqual(done["state"], "failed")
+        self.assertIn("The recording is empty", done["error"])
+        self.assertFalse(self.here.exists() and any(self.here.iterdir()))
+        self.assertEqual(list((self.frame / clips.WORK).iterdir()), [])
+
+
+@unittest.skipUnless(shutil.which("ffmpeg") and shutil.which("ffprobe"), "needs ffmpeg and ffprobe")
+class RealFfmpeg(unittest.TestCase):
+    """A 65 s recording in Steam's DASH naming (ffmpeg's own dash muxer names files the same
+    way), stitched by the real ffmpeg: longer than the 60 s Steam's own export manages."""
+
+    def test_export_of_a_long_recording(self):
+        d = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+        ud = d / "home" / clips.STEAM_USERDATA
+        folder = ud / "123" / "gamerecordings" / "video" / "bg_620_20261020_201950"
+        folder.mkdir(parents=True)
+        r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=size=64x64:rate=10",
+                            "-f", "lavfi", "-i", "sine=frequency=440:sample_rate=8000", "-t", "65",
+                            "-c:v", "libx264", "-preset", "ultrafast", "-g", "20", "-c:a", "aac",
+                            "-seg_duration", "2", "-use_template", "1", "-use_timeline", "0",
+                            "-f", "dash", str(folder / "session.mpd")], capture_output=True, text=True)
+        if r.returncode != 0 or not (folder / "chunk-stream0-00001.m4s").exists():
+            self.skipTest("this ffmpeg can't write DASH with libx264: " + r.stderr[-300:])
+        listed = clips.list_recordings(ud)
+        self.assertEqual(len(listed), 1)
+        self.assertGreater(listed[0]["chunks"], 30)
+        got = clips.export(ud, listed[0]["id"], home=d / "home")
+        out = d / "home" / got["path"]
+        probe = json.loads(subprocess.run(["ffprobe", "-v", "error", "-show_streams", "-show_format", "-of", "json", str(out)],
+                                          capture_output=True, text=True, check=True).stdout)
+        self.assertEqual(sorted(s["codec_type"] for s in probe["streams"]), ["audio", "video"])
+        self.assertGreater(float(probe["format"]["duration"]), 64)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_comfort_ui.py

@@ -56,6 +56,48 @@ const log = ()=>{}, toast = ()=>{};
   assert.equal($('sessionMinutes').disabled,false);
   assert.equal($('sessionCancel').disabled,true);
 })().catch(e=>{console.error(e);process.exitCode=1;});
+'''
+        result = subprocess.run(['node', '-e', setup + code + checks], capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stderr)
+
+    def test_a_finished_session_leaves_the_defaults(self):
+        """A one-minute test session that has ended mustn't fill the form with 1 / 0 / 0."""
+        page = (ROOT / 'ui/index.html').read_text(encoding='utf-8')
+        code = page[page.index('let comfortBusy ='):page.index('async function pollComfort()')]
+        setup = r'''
+const assert = require('node:assert/strict');
+const elements = new Map();
+const $ = id => {
+  // The form's own defaults, as in the page's HTML.
+  const value = {sessionMinutes:'30', breakMinutes:'20', stillMinutes:'30'}[id] || '';
+  if (!elements.has(id)) elements.set(id, {textContent:'', hidden:true, disabled:false, value, defaultValue:value,
+    checked:true, defaultChecked:true, type: /Alert$/.test(id) ? 'checkbox' : 'number'});
+  return elements.get(id);
+};
+const window = {frameApp:{notify:async()=>{}}};
+const log = ()=>{}, toast = ()=>{};
+'''
+        checks = r'''
+renderComfort({id:'old', active:false, time:100, options:{minutes:1,breakMinutes:0,stillMinutes:0,batteryAlert:false,heatAlert:false},
+  events:[{id:'old:1',kind:'finished',time:90,message:'Session ended'}]});
+assert.equal($('sessionMinutes').value, '30');
+assert.equal($('breakMinutes').value, '20');
+assert.equal($('batteryAlert').checked, true);
+assert.match($('comfortEvents').textContent, /Session ended/);
+assert.notEqual($('comfortEvents').textContent, 'Session ended');  // it carries a time
+renderComfort({id:'new', active:true, time:200, remaining:600, options:{minutes:45,breakMinutes:15,stillMinutes:20,batteryAlert:true,heatAlert:false}, events:[]});
+assert.equal($('sessionMinutes').value, 45);  // a running session shows its own settings
+assert.equal($('heatAlert').checked, false);
+// The page stays open while that session ends: the next one starts from the defaults again.
+renderComfort({id:'new', active:false, time:900, options:{minutes:45,breakMinutes:15,stillMinutes:20,batteryAlert:true,heatAlert:false},
+  events:[{id:'new:1',kind:'finished',time:899,message:'Session ended'}]});
+assert.equal($('sessionMinutes').value, '30');
+assert.equal($('breakMinutes').value, '20');
+assert.equal($('heatAlert').checked, true);
+renderComfort({id:'new', active:false, time:905, options:{minutes:45}, events:[]});
+$('sessionMinutes').value = '50';  // what's typed for the next session
+renderComfort({id:'new', active:false, time:910, options:{minutes:45}, events:[]});
+assert.equal($('sessionMinutes').value, '50');  // later polls leave it alone
 '''
         result = subprocess.run(['node', '-e', setup + code + checks], capture_output=True, text=True)
         self.assertEqual(result.returncode, 0, result.stderr)

tests/test_control_center.py

@@ -63,6 +63,20 @@ 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,29 @@ class Pins(Base):
 
 
 class Registry(Base):
+    def test_replaced_registry_is_read_even_when_timestamp_and_size_match(self):
+        d = self.reg.add_device('frame', name='First')
+        before = self.reg.path.stat()
+        other = fd.Registry(self.reg.path)
+        other.update_device(d['id'], name='Other')
+        os.utime(self.reg.path, ns=(before.st_atime_ns, before.st_mtime_ns))
+        self.assertEqual(self.reg.path.stat().st_size, before.st_size)
+        self.assertEqual(self.reg.get(d['id'])['name'], 'Other')
+
+    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_frame_android_library.py

@@ -141,6 +141,9 @@ def wait_for_idle_resolvers(timeout=10):
 class ArtworkTests(unittest.TestCase):
     def setUp(self):
         wait_for_idle_resolvers()
+        from apk_sources import _images
+        _images._dns.clear()  # each test answers lookups its own way
+        self.addCleanup(_images._dns.clear)
 
     def test_source_inputs_and_url(self):
         from apk_sources import _images

tests/test_ios_contracts.py

@@ -0,0 +1,175 @@
+"""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_page_scripts.py

@@ -0,0 +1,141 @@
+"""The page's inline scripts share one global scope, so a second top-level function or
+variable with a name already used replaces the first everywhere, silently."""
+import html.parser
+import json
+import pathlib
+import shutil
+import subprocess
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+# Compiles the scripts as one strict-mode block. There, functions are block scoped like let
+# and const, so V8 itself rejects a name declared twice in the shared scope (however it's
+# indented or declared: function, class, let, const, destructuring), while helpers with the
+# same name inside different functions stay legal. var is the exception (declaring one twice
+# is allowed), so the page doesn't use var at all: Node's own copy of the acorn parser finds
+# real var declarations, not the word in comments, strings or CSS var().
+DUPLICATES = r'''
+const vm = require('vm');
+const scripts = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+try { new vm.Script('"use strict"; {\n' + scripts.join('\n;\n') + '\n}'); console.log('ok'); }
+catch (e) { console.log(e.message); }
+'''
+VARS = r'''
+const scripts = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+let acorn, walk;
+try {
+  acorn = require('internal/deps/acorn/acorn/dist/acorn');
+  walk = require('internal/deps/acorn/acorn-walk/dist/walk');
+} catch { console.log('no parser'); process.exit(0); }
+for (const code of scripts) {
+  let found = null;
+  try {
+    walk.simple(acorn.parse(code, { ecmaVersion: 'latest' }), {
+      VariableDeclaration(n) { if (n.kind === 'var' && !found) found = code.slice(n.start, n.end).slice(0, 40); },
+    });
+  } catch (e) { console.log(e.message); process.exit(0); }
+  if (found) { console.log('declares with var: ' + found); process.exit(0); }
+}
+console.log('ok');
+'''
+
+
+def node(script, scripts, *flags):
+    r = subprocess.run(['node', *flags, '-e', script], input=json.dumps(scripts), capture_output=True, text=True)
+    return r.stdout.strip() or r.stderr.strip()
+
+
+def check(scripts):
+    """'ok', or V8's message for the first name declared twice."""
+    return node(DUPLICATES, scripts)
+
+
+def check_vars(scripts):
+    """'ok', or the first var declaration. Skips where Node doesn't include acorn."""
+    out = node(VARS, scripts, '--expose-internals')
+    if out == 'no parser':
+        raise unittest.SkipTest("this Node doesn't include acorn")
+    return out
+
+
+class ClassicScripts(html.parser.HTMLParser):
+    """The page's inline classic scripts: no src, and no type other than a JavaScript one (a
+    module has its own scope, and JSON data isn't code). The types a browser runs as script:
+    https://mimesniff.spec.whatwg.org/#javascript-mime-type"""
+    JS = {'', 'application/ecmascript', 'application/javascript', 'application/x-ecmascript',
+          'application/x-javascript', 'text/ecmascript', 'text/javascript', 'text/javascript1.0',
+          'text/javascript1.1', 'text/javascript1.2', 'text/javascript1.3', 'text/javascript1.4',
+          'text/javascript1.5', 'text/jscript', 'text/livescript', 'text/x-ecmascript', 'text/x-javascript'}
+
+    def __init__(self):
+        super().__init__()
+        self.scripts, self.current = [], None
+
+    def handle_starttag(self, tag, attrs):
+        if tag == 'script':
+            a = dict(attrs)
+            inline = 'src' not in a and (a.get('type') or '').strip().lower() in self.JS
+            self.current = [] if inline else None
+
+    def handle_data(self, data):
+        if self.current is not None:
+            self.current.append(data)
+
+    def handle_endtag(self, tag):
+        if tag == 'script' and self.current is not None:
+            self.scripts.append(''.join(self.current))
+        if tag == 'script':
+            self.current = None
+
+
+def classic_scripts(page):
+    p = ClassicScripts()
+    p.feed(page)
+    return p.scripts
+
+
+@unittest.skipUnless(shutil.which('node'), 'Node parses the page scripts')
+class PageScripts(unittest.TestCase):
+    def test_no_top_level_name_is_declared_twice(self):
+        scripts = classic_scripts((ROOT / 'ui/index.html').read_text(encoding='utf-8'))
+        self.assertGreaterEqual(len(scripts), 2)
+        self.assertEqual(check(scripts), 'ok')
+
+    def test_the_page_declares_nothing_with_var(self):
+        scripts = classic_scripts((ROOT / 'ui/index.html').read_text(encoding='utf-8'))
+        self.assertEqual(check_vars(scripts), 'ok')
+
+    def test_the_check_finds_what_it_should(self):
+        twice = {
+            'indented function': ['function loadPanels() {}', '  async function loadPanels() {}'],
+            'class': ['class Panel {}', 'class Panel {}'],
+            'destructured': ['const { a, b } = {};', 'let [b] = [];'],
+            'later declarator': ['let x = 1;', 'const y = 2, x = 3;'],
+            'function and const': ['function f() {}', 'const f = 1;'],
+        }
+        for what, scripts in twice.items():
+            with self.subTest(what):
+                self.assertIn('already been declared', check(scripts))
+        helpers = ['function a() { function help() {} }', 'function b() { const help = 1; }']
+        self.assertEqual(check(helpers), 'ok')
+
+    def test_the_var_check_finds_what_it_should(self):
+        # var: legal to declare twice, so not allowed at all; however it's written.
+        for code in ['var x = 1;', 'var/*c*/x = 1;', 'var {x} = {x: 1};', 'function f() { var y; }']:
+            with self.subTest(code):
+                self.assertIn('declares with var', check_vars([code]))
+        # The word var elsewhere is fine.
+        text = ['// var x\nconst a = "var y", b = `var ${a}`, c = "color: var(--blue)", d = {}.var;']
+        self.assertEqual(check_vars(text), 'ok')
+
+    def test_only_inline_classic_scripts_are_checked(self):
+        page = ('<script>let a;</script><script type="module">export const m = 1;</script>'
+                '<script type="application/json">{"b": 1}</script><script src = "x.js"></script>'
+                '<script data-src="y" type="text/javascript">let c;</script>'
+                '<script type="text/ecmascript">let d;</script><script type=" Application/X-JavaScript ">let e;</script>')
+        self.assertEqual(classic_scripts(page), ['let a;', 'let c;', 'let d;', 'let e;'])
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_page_startup.py

@@ -0,0 +1,58 @@
+"""The page calls showPage() while its first script is still running, before names declared
+later (in that script or the second one) exist. Touching one of them there throws, and the
+rest of the page's setup never runs: opening Frame Control at #games did exactly that."""
+import json
+import pathlib
+import re
+import shutil
+import subprocess
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+STUBS = ['$', 'toggleLive', 'scrollToY', 'scroller', 'loadMacView', 'loadPanels', 'loadPanelSwitcher', 'loadTitles', 'showAndroidTab',
+         'loadAndroid', 'loadDisplays', 'setGameSource', 'requestAnimationFrame']
+
+RUN = r'''
+const vm = require('vm');
+const {code, hashes} = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+const failures = [];
+for (const hash of hashes) {
+  const context = vm.createContext({
+    location: {hash}, document: {querySelectorAll: () => [], title: ''}, live: false,
+  });
+  try { vm.runInContext(code, context); }
+  catch (e) { failures.push(`${hash}: ${e.message}`); }
+}
+console.log(JSON.stringify(failures));
+'''
+
+
+@unittest.skipUnless(shutil.which('node'), 'Node runs the page code')
+class PageStartup(unittest.TestCase):
+    def test_opening_any_page_or_section_at_startup_runs(self):
+        page = (ROOT / 'ui/index.html').read_text(encoding='utf-8')
+        first, second = re.findall(r'<script>(.*?)</script>', page, re.S)[:2]
+        # The routing tables and the workspace helpers showPage uses, up to showPage itself.
+        start = first.index('function showPage(')
+        tables = first[first.index('const PAGES ='):start]
+        show = first[start:first.index('\n}\n', start) + 3]
+        # Everything declared after the startup call is still uninitialised when it runs.
+        call = re.search(r'^showPage\(\);', first, re.M).end()
+        later = re.findall(r'^(?:const|let)\s+(\w+)', first[call:] + second, re.M)
+        later = [n for n in dict.fromkeys(later) if n not in STUBS and n not in ('PAGES', 'SECTION_PAGE', 'page')]
+        self.assertIn('link', later)  # the name that broke #games
+        stubs = ''.join(f'function {n}() {{ return {{ classList: {{ toggle() {{}} }}, scrollIntoView() {{}} }}; }}\n'
+                        for n in STUBS if n != '$')
+        node = '{ classList: { toggle() {} }, scrollIntoView() {}, append() {}, prepend() {}, setAttribute() {}, removeAttribute() {} }'
+        code = (f'const $ = id => id === "nowhere" ? null : {node};\nconst gm = {{src: "owned"}};\n' + stubs + tables + show +
+                'showPage();\n' + ''.join(f'let {n};\n' for n in later))
+        hashes = ['', '#home', '#games', '#android', '#tools', '#settings', '#devices', '#control', '#nowhere']
+        hashes += ['#' + k for k in re.findall(r'(\w+): ?"', tables[:tables.index('const workspace')])]
+        r = subprocess.run(['node', '-e', RUN], input=json.dumps({'code': code, 'hashes': hashes}),
+                           capture_output=True, text=True)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertEqual(json.loads(r.stdout), [])
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_pulse.py

@@ -1,472 +0,0 @@
-"""Eye-camera pulse estimate and the heart-rate comparison tool; no headset needed."""
-import importlib.util
-import io
-import json
-import math
-import os
-from pathlib import Path
-import random
-import socket
-import struct
-import sys
-import tempfile
-import unittest
-import zipfile
-from unittest.mock import patch
-
-ROOT = Path(__file__).resolve().parents[1]
-
-
-def load(name, path):
-    spec = importlib.util.spec_from_file_location(name, ROOT / path)
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-pulse = load("pulse", "frame/tracking/pulse.py")
-check = load("heart_check", "scripts/heart-check.py")
-
-
-def synthetic(bpm, pulsing, seconds=40, fps=30, patches=48, noise=0.004, seed=7):
-    """Patch brightness with a faint pulse in `pulsing` patches, plus sensor
-    noise, slow drift, blinks in some patches and eye movement in others."""
-    rng = random.Random(seed)
-    times = [i / fps for i in range(seconds * fps)]
-    values = {}
-    for k in range(patches):
-        base, amplitude, trace = 40 + k, 0.003 if k < pulsing else 0.0, []
-        for t in times:
-            v = base * (1 + amplitude * math.sin(2 * math.pi * bpm / 60 * t)
-                        + noise * rng.gauss(0, 1) + 0.02 * math.sin(0.1 * t + k))
-            if k % 8 == 7 and int(t * 10) % 47 == 0:
-                v *= 0.5   # blink
-            if k % 8 == 6 and int(t * 10) % 23 == 0:
-                v *= 1.3   # frequent eye movement
-            trace.append(v)
-        values[k] = trace
-    return times, values
-
-
-class Estimate(unittest.TestCase):
-    def test_finds_pulse(self):
-        for bpm in (58, 72, 115):
-            with self.subTest(bpm=bpm):
-                result = pulse.estimate(*synthetic(bpm, 16))
-                self.assertAlmostEqual(result["bpm"], bpm, delta=1.5)
-                self.assertTrue(pulse.reliable(result))
-                self.assertTrue(all(abs(b - bpm) <= 2 for _, b in result["series"]))
-
-    def test_noise_and_blinks_are_not_a_pulse(self):
-        result = pulse.estimate(*synthetic(72, 0))
-        self.assertFalse(pulse.reliable(result))
-
-    def test_frequent_spike_patches_are_dropped(self):
-        times, values = synthetic(72, 16)
-        result = pulse.estimate(times, values)
-        self.assertLess(result["usable"], len(values))
-
-    def test_needs_enough_frames(self):
-        with self.assertRaises(ValueError):
-            pulse.estimate(*synthetic(72, 16, seconds=5))
-        times, values = synthetic(72, 16)
-        with self.assertRaises(ValueError):
-            pulse.estimate(times, {k: [0.0] * len(times) for k in values})  # all dark
-
-    def test_series_times(self):
-        times, values = synthetic(72, 16, seconds=20)
-        series = pulse.estimate(times, values)["series"]
-        self.assertAlmostEqual(series[0][0], pulse.WINDOW, delta=0.1)
-        self.assertEqual(len(series), 20 - int(pulse.WINDOW) + 1)
-
-    def test_flat_patches_do_not_rank_first(self):
-        times, values = synthetic(72, 16)
-        values["flat"] = [100.0] * len(times)
-        result = pulse.estimate(times, values)
-        self.assertAlmostEqual(result["bpm"], 72, delta=1.5)
-        self.assertEqual(pulse.snr([(60.0, 0.0), (61.0, 0.0)], 60), 0.0)
-
-    def test_analyse_uses_nearest_frame(self):
-        times, values = synthetic(72, 4, patches=4, seconds=10)
-        # Right-eye frames 1 ms before each left frame: nearest is that frame.
-        frames = [(t, "left", [values[k][i] for k in range(4)]) for i, t in enumerate(times)]
-        frames += [(t - 0.001, "right", [float(i)] * 4) for i, t in enumerate(times)]
-        seen = {}
-        original = pulse.estimate
-        with patch.object(pulse, "estimate", lambda t, p: seen.update(p) or original(t, p)):
-            pulse.analyse(frames)
-        self.assertEqual(seen["right0"][:5], [0.0, 0.0, 1.0, 1.0, 2.0])
-
-    def test_fft_matches_dft(self):
-        signal = [math.sin(i) + (i % 3) for i in range(16)]
-        fast = pulse.fft(signal)
-        for k in range(16):
-            slow = sum(signal[n] * complex(math.cos(2 * math.pi * k * n / 16), -math.sin(2 * math.pi * k * n / 16))
-                       for n in range(16))
-            self.assertAlmostEqual(abs(fast[k] - slow), 0, places=9)
-
-    def test_grid_means(self):
-        # 4 × 4 image in RGB with padding: left half 10, right half 30 (channel 0).
-        width, height, channels, stride = 4, 4, 3, 16
-        pixels = bytearray(stride * height)
-        for y in range(height):
-            for x in range(width):
-                pixels[y * stride + x * channels] = 10 if x < 2 else 30
-                pixels[y * stride + x * channels + 1] = 255  # other channels ignored
-        self.assertEqual(pulse.grid_means(bytes(pixels), width, height, stride, channels, grid=2),
-                         [10, 30, 10, 30])
-
-    def test_analyse_combines_both_eyes(self):
-        times, values = synthetic(80, 16, patches=16)
-        frames = []
-        for i, t in enumerate(times):
-            frames.append((t, "left", [values[k][i] for k in range(16)]))
-            frames.append((t + 0.001, "right", [values[k][i] for k in range(16)]))
-        result = pulse.analyse(frames)
-        self.assertAlmostEqual(result["bpm"], 80, delta=1.5)
-        self.assertEqual(result["usable"] % 2, 0)
-
-
-class FakeCaptureTool:
-    """Stands in for `eyetracking --calib`: writes PNG names over a few polls."""
-    def __init__(self, directory, frames=6, fail=False):
-        self.directory, self.frames, self.fail = Path(directory), frames, fail
-        self.polls = 0
-        self.returncode = None
-        self.stdout = None
-        self.announce = None  # a different directory to report, if set
-
-    def __call__(self, command, cwd, stdout, stderr):
-        self.command = command
-        self.stdout = stdout
-        if self.fail:
-            stdout.write("Failed to initialize cameras\n")
-            stdout.flush()
-            self.returncode = 1
-            return self
-        # Real output is block-buffered until exit, so nothing is printed here.
-        stdout.flush()
-        self.directory.mkdir()
-        return self
-
-    def poll(self):
-        if self.returncode is not None:
-            return self.returncode
-        if self.polls < self.frames:
-            for eye in ("left", "right"):
-                (self.directory / f"{eye}_{self.polls}.png").write_bytes(b"png")
-            self.polls += 1
-            return None
-        meta = {"frames": [{eye: {"fname": str(self.directory / f"{eye}_{i}.png"), "frameNum": i + 10,
-                                  "tsMono": 100 + i / 90, "valid": i != 2} for eye in ("left", "right")}
-                           for i in range(self.frames)]}
-        (self.directory / "meta.json").write_text(json.dumps(meta))
-        # The real tool's buffered output only appears once it exits.
-        self.stdout.write(f"Writing capture to: {self.announce or self.directory}\nCaptured images\n")
-        self.stdout.flush()
-        self.returncode = 0
-        return 0
-
-    def terminate(self):
-        raise AssertionError("the capture tool must never be signalled")
-
-    kill = terminate
-
-    def wait(self, timeout=None):
-        return self.returncode
-
-
-class WornCheck(unittest.TestCase):
-    def sensor(self, name, raw):
-        root = Path(self.enterContext(tempfile.TemporaryDirectory()))
-        device = root / "iio:device2"
-        device.mkdir()
-        (device / "name").write_text(name + "\n")
-        (device / "in_proximity_raw").write_text(raw + "\n")
-        return root
-
-    def test_reads_the_proximity_sensor(self):
-        self.assertEqual(pulse.proximity(self.sensor("vcnl4000", "3.250000000")), 3.25)
-
-    def test_unreadable_sensor_does_not_block(self):
-        self.assertIsNone(pulse.proximity(self.sensor("other", "9")))
-        self.assertIsNone(pulse.proximity(self.sensor("vcnl4000", "junk")))
-        self.assertIsNone(pulse.proximity(Path("/nonexistent")))
-        self.assertTrue(pulse.worn(None))
-
-    def test_low_reading_means_unworn(self):
-        self.assertFalse(pulse.worn(3.1))
-        self.assertTrue(pulse.worn(pulse.WORN_MIN))
-
-
-class CaptureLifecycle(unittest.TestCase):
-    def setUp(self):
-        self.root = Path(tempfile.mkdtemp())
-        self.directory = self.root / "etcalib_test"
-        (self.root / "etcalib_older").mkdir()  # an earlier capture is not ours
-        self.loaded = []
-
-    def tearDown(self):
-        import shutil
-        shutil.rmtree(self.root, ignore_errors=True)
-
-    def loader(self, path):
-        self.loaded.append(Path(path).name)
-        self.assertTrue(Path(path).exists())
-        return [float(len(self.loaded))]
-
-    def capture(self, tool):
-        class TestCapture(pulse.Capture):
-            # A temporary directory stands in for /tmp/etcalib_*.
-            PREFIX = str(self.root / "etcalib_")
-        capture = TestCapture(20, runner=tool, loader=self.loader, workers=0)
-        with patch.object(pulse.time, "sleep", lambda s: None):
-            return capture, capture.run()
-
-    def test_reduces_deletes_and_joins_metadata(self):
-        tool = FakeCaptureTool(self.directory)
-        capture, frames = self.capture(tool)
-        self.assertEqual(sorted(self.loaded), sorted(f"{e}_{i}.png" for e in ("left", "right") for i in range(6)))
-        self.assertFalse(self.directory.exists())  # images and metadata removed
-        self.assertTrue((self.root / "etcalib_older").exists())
-        self.assertEqual(len(frames), 10)          # frame 2 invalid in both eyes
-        self.assertEqual(tool.command[-2:], ["--calib", "20"])
-        self.assertTrue(all(isinstance(t, float) and eye in ("left", "right") for t, eye, _ in frames))
-
-    def test_camera_failure(self):
-        tool = FakeCaptureTool(self.directory, fail=True)
-        with self.assertRaises(RuntimeError) as raised:
-            self.capture(tool)
-        self.assertIn("cameras unavailable", str(raised.exception))
-
-    def test_backlog_abandons_capture_and_removes_images(self):
-        class Stalled(FakeCaptureTool):
-            def poll(self):
-                if self.polls > 8:
-                    self.returncode = 0  # the bounded run ends by itself
-                    return 0
-                for i in range(20):
-                    for eye in ("left", "right"):
-                        (self.directory / f"{eye}_{self.polls * 20 + i}.png").write_bytes(b"png")
-                self.polls += 1
-                return None
-        tool = Stalled(self.directory)
-        class TestCapture(pulse.Capture):
-            PREFIX = str(self.root / "etcalib_")
-            MAX_BACKLOG = 50
-        capture = TestCapture(20, runner=tool, loader=self.loader, workers=0)
-        capture.reduce = lambda final=False, original=capture.reduce: (
-            original(final) if tool.polls > 3 else None)  # reduction stalls
-        with patch.object(pulse.time, "sleep", lambda s: None), self.assertRaises(RuntimeError) as raised:
-            capture.run()
-        self.assertIn("fell behind", str(raised.exception))
-        self.assertEqual(tool.returncode, 0)         # left to end by itself, never signalled
-        self.assertFalse(self.directory.exists())    # no image left behind
-
-    def test_second_capture_directory_stops_and_removes_both(self):
-        foreign = self.root / "etcalib_foreign"
-        class Racing(FakeCaptureTool):
-            def poll(self):
-                if self.polls == 2:
-                    foreign.mkdir()
-                    (foreign / "left_0.png").write_bytes(b"png")
-                return super().poll()
-        tool = Racing(self.directory)
-        with self.assertRaises(RuntimeError) as raised:
-            self.capture(tool)
-        self.assertIn("another eye-camera capture", str(raised.exception))
-        self.assertFalse(self.directory.exists())
-        self.assertFalse(foreign.exists())  # no eye image outlives the run
-        self.assertTrue((self.root / "etcalib_older").exists())
-
-    def test_images_elsewhere_are_not_used_but_are_removed(self):
-        tool = FakeCaptureTool(self.directory)
-        tool.announce = self.root / "etcalib_reported"
-        tool.announce.mkdir()
-        (tool.announce / "left_0.png").write_bytes(b"png")
-        with self.assertRaises(RuntimeError) as raised:
-            self.capture(tool)
-        self.assertIn("somewhere else", str(raised.exception))
-        self.assertFalse(tool.announce.exists())
-        self.assertFalse(self.directory.exists())
-
-    def test_interrupt_during_cleanup_still_removes_images(self):
-        class Stubborn(FakeCaptureTool):
-            interrupts = 0
-            def poll(self):
-                if self.polls == 2 and self.interrupts < 2:
-                    self.interrupts += 1
-                    raise KeyboardInterrupt  # Ctrl-C mid-capture, and again while waiting
-                return super().poll()
-        tool = Stubborn(self.directory)
-        with self.assertRaises(KeyboardInterrupt):
-            self.capture(tool)
-        self.assertEqual(tool.returncode, 0)         # still let finish, never signalled
-        self.assertFalse(self.directory.exists())
-
-    def test_overrunning_tool_is_killed_as_a_last_resort(self):
-        class Hung(FakeCaptureTool):
-            killed = False
-            def poll(self):
-                (self.directory / "left_0.png").write_bytes(b"png")
-                return None if not self.killed else -9
-            def kill(self):
-                self.killed = True
-        tool = Hung(self.directory)
-        clock = iter(range(0, 10000, 20))
-        with patch.object(pulse.time, "monotonic", lambda: next(clock)), \
-                self.assertRaises(RuntimeError) as raised:
-            self.capture(tool)
-        self.assertIn("may need a reboot", str(raised.exception))
-        self.assertTrue(tool.killed)
-        self.assertFalse(self.directory.exists())
-
-    def test_cleanup_tries_every_directory(self):
-        capture = pulse.Capture(20)
-        capture.PREFIX = str(self.root / "etcalib_")
-        first, second = self.root / "etcalib_a", self.root / "etcalib_b"
-        for directory in (first, second):
-            directory.mkdir()
-            (directory / "left_0.png").write_bytes(b"png")
-        capture.new = {first, second}
-        real = pulse.shutil.rmtree
-        def flaky(path):
-            if Path(path) == first:
-                raise OSError("busy")
-            real(path)
-        with patch.object(pulse.shutil, "rmtree", flaky), self.assertRaises(RuntimeError) as raised:
-            capture.remove()
-        self.assertIn("etcalib_a", str(raised.exception))
-        self.assertFalse(second.exists())
-
-    def test_removes_a_directory_seen_only_at_the_end(self):
-        capture = pulse.Capture(20)
-        capture.PREFIX = str(self.root / "etcalib_")
-        capture.before = capture.candidates()
-        late = self.root / "etcalib_late"
-        late.mkdir()
-        (late / "left_0.png").write_bytes(b"png")
-        capture.remove()
-        self.assertFalse(late.exists())
-        self.assertTrue((self.root / "etcalib_older").exists())
-
-    def test_never_adopts_directories_without_a_baseline(self):
-        capture = pulse.Capture(20)
-        capture.PREFIX = str(self.root / "etcalib_")
-        capture.remove()
-        self.assertTrue((self.root / "etcalib_older").exists())
-
-    def test_only_removes_capture_directories(self):
-        capture = pulse.Capture(20)
-        capture.directory = self.root
-        capture.remove()
-        self.assertTrue(self.root.exists())
-
-
-class HeartCheck(unittest.TestCase):
-    def write(self, name, text):
-        path = Path(self.enterContext(tempfile.TemporaryDirectory())) / name
-        path.write_text(text)
-        return path
-
-    def test_osc_round_trip(self):
-        tracking = load("tracking", "frame/tracking/tracking.py")
-        self.assertEqual(check.parse_osc(tracking.osc_message("/avatar/parameters/HeartRate", [72])),
-                         ("/avatar/parameters/HeartRate", [72]))
-        address, values = check.parse_osc(tracking.osc_message("/x", [1.5, -2.0]))
-        self.assertEqual((address, values), ("/x", [1.5, -2.0]))
-        with self.assertRaises(ValueError):
-            check.parse_osc(b"/x\0\0,s\0\0abc\0")
-
-    def test_listen_records_readings(self):
-        tracking = load("tracking", "frame/tracking/tracking.py")
-        with tempfile.TemporaryDirectory() as directory:
-            out = Path(directory) / "ours.csv"
-            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
-                probe.bind(("127.0.0.1", 0))
-                port = probe.getsockname()[1]
-            import threading
-            def send():
-                import time
-                time.sleep(0.3)
-                with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sender:
-                    sender.sendto(tracking.osc_message(check.ADDRESS, [72]), ("127.0.0.1", port))
-                    sender.sendto(tracking.osc_message("/other", [1]), ("127.0.0.1", port))
-            threading.Thread(target=send).start()
-            shown = io.StringIO()
-            count = check.listen(port, check.ADDRESS, str(out), 1.5, stream=shown)
-            self.assertEqual(count, 1)
-            self.assertIn("72 bpm", shown.getvalue())
-            self.assertEqual(out.read_text().splitlines()[1].split(",")[1], "72")
-            self.assertEqual(out.stat().st_mode & 0o777, 0o600)
-
-    def test_compare_finds_lag_and_contact_loss(self):
-        reference = [(1000.0 + i, 60 + i, 6) for i in range(40)] + [(1040.0 + i, 150, 4) for i in range(5)]
-        ours = [(1002.0 + i, 60 + i) for i in range(40)]  # 2 s late, nothing during contact loss
-        ref = self.write("ref.csv", "unix_seconds,bpm,flags\n" + "".join(f"{t},{b},{f}\n" for t, b, f in reference))
-        mine = self.write("ours.csv", "unix_seconds,bpm\n" + "".join(f"{t},{b}\n" for t, b in ours))
-        result = check.compare(check.read_csv(mine), check.read_any(ref))
-        self.assertEqual(result["lag_seconds"], 2.0)
-        self.assertEqual(result["mean_abs_error"], 0)
-        self.assertEqual(result["shown_during_no_contact"], 0)
-        self.assertTrue(check.report(result, 5, stream=io.StringIO()))
-        # A stale reading sent during contact loss fails the check.
-        stale = check.read_csv(mine) + [(1043.0, 99)]
-        result = check.compare(stale, check.read_any(ref))
-        self.assertEqual(result["shown_during_no_contact"], 1)
-        self.assertFalse(check.report(result, 5, stream=io.StringIO()))
-
-    def test_compare_against_apple_health_export(self):
-        records = "".join(
-            f'<Record type="HKQuantityTypeIdentifierHeartRate" unit="count/min" '
-            f'startDate="2026-09-29 12:00:{s:02d} +1000" endDate="2026-09-29 12:00:{s:02d} +1000" value="{70 + s % 3}"/>'
-            for s in range(0, 60, 5))
-        other = '<Record type="HKQuantityTypeIdentifierStepCount" startDate="2026-09-29 12:00:00 +1000" value="9"/>'
-        xml = f'<?xml version="1.0"?><HealthData>{other}{records}</HealthData>'
-        with tempfile.TemporaryDirectory() as directory:
-            archive = Path(directory) / "export.zip"
-            with zipfile.ZipFile(archive, "w") as z:
-                z.writestr("apple_health_export/export.xml", xml)
-            start = check.parse_time("2026-09-29 12:00:00 +1000")
-            samples = check.read_any(archive, start - 60, start + 120)
-            self.assertEqual(len(samples), 12)
-            self.assertEqual(samples[0], (start, 70))
-            ours = [(start + i + 1.0, 71) for i in range(60)]
-            result = check.compare(ours, samples)
-            self.assertLessEqual(result["mean_abs_error"], 1)
-
-    def test_unusual_flags_and_missing_export(self):
-        path = self.write("ref.csv", "time,bpm,flags\n1000,70,6.0\n1001,71,yes\n1002,72,4\n")
-        self.assertEqual(check.read_csv(path), [(1000.0, 70), (1001.0, 71), (1002.0, None)])
-        with tempfile.TemporaryDirectory() as directory:
-            archive = Path(directory) / "other.zip"
-            with zipfile.ZipFile(archive, "w") as z:
-                z.writestr("notes.txt", "x")
-            with self.assertRaises(ValueError):
-                check.read_any(archive, 0, 1)
-
-    def test_compare_reports_bad_input_without_traceback(self):
-        good = self.write("ref.csv", "1000,70\n")
-        shown = io.StringIO()
-        with patch("sys.stdout", shown):
-            self.assertEqual(check.main(["compare", str(good.parent / "missing.csv"), str(good)]), 1)
-            self.assertEqual(check.main(["compare", str(self.write("ours.csv", "1000,inf\n1001,70\n")),
-                                         str(self.write("bad.xml", "<not closed"))]), 1)
-        self.assertEqual(shown.getvalue().count("Could not compare"), 2)
-
-    def test_health_records_with_non_finite_values_are_skipped(self):
-        record = '<Record type="HKQuantityTypeIdentifierHeartRate" startDate="2026-09-29 12:00:00 +1000" value="%s"/>'
-        path = self.write("export.xml", "<HealthData>" + record % "inf" + record % "72" + "</HealthData>")
-        start = check.parse_time("2026-09-29 12:00:00 +1000")
-        self.assertEqual(check.read_health(path, start - 1, start + 1), [(start, 72)])
-
-    def test_time_formats(self):
-        self.assertEqual(check.parse_time("1700000000.5"), 1700000000.5)
-        self.assertEqual(check.parse_time("2023-11-14T22:13:20Z"), 1700000000)
-        self.assertEqual(check.parse_time("2023-11-15 08:13:20 +1000"), 1700000000)
-        with self.assertRaises(ValueError):
-            check.parse_time("yesterday")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_server.py

@@ -88,6 +88,12 @@ 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"):
@@ -103,6 +109,10 @@ class ServerGuards(unittest.TestCase):
         self.assertEqual(self.request("GET", "/api/stream")[0], 403)
         self.assertEqual(self.request("GET", "/api/shots/image?id=1/250820/20260925225208_1.jpg")[0], 403)
         self.assertEqual(self.request("POST", "/api/launch", {"appid": "620"})[0], 403)
+        self.assertEqual(self.request("GET", "/api/record")[0], 403)
+        self.assertEqual(self.request("GET", "/api/clips")[0], 403)
+        self.assertEqual(self.request("POST", "/api/record", {"action": "start"})[0], 403)
+        self.assertEqual(self.request("POST", "/api/clips/export", {"id": "1/video/bg_620_20261020_201950"})[0], 403)
 
     def test_captures_are_not_cacheable(self):
         # Headset captures show everything on screen; nothing may cache them.
@@ -128,11 +138,24 @@ class ServerGuards(unittest.TestCase):
             ("/api/shots/save", {"ids": [1]}),
             ("/api/shots/save", {"ids": ["1/250820/../../.ssh/id_ed25519"]}),
             ("/api/shots/save", {"ids": ["1/250820/20260925225208_1.jpg; rm -rf ~"]}),
+            ("/api/record", {}),
+            ("/api/record", {"action": "explode"}),
+            ("/api/clips/export", {}),
+            ("/api/clips/export", {"id": 5}),
+            ("/api/clips/export", {"id": "1/video/../../../../.ssh"}),
+            ("/api/clips/export", {"id": "1/video/bg;rm -rf ~"}),
+            ("/api/clips/export", {"id": "../1/video/bg"}),
         ]
         for path, body in cases:
             status, payload = self.post(path, body)
             self.assertEqual(status, 400, f"{path} {body} -> {payload}")
 
+    def test_recorder_idle_until_started(self):
+        status, _, payload = self.request("GET", "/api/record", headers={"X-Frame-UI": "1"})
+        self.assertEqual((status, json.loads(payload)), (200, {"state": "idle"}))
+        status, payload = self.post("/api/record", {"action": "stop"})
+        self.assertEqual(status, 409, payload)
+
     def test_showing_a_shot_needs_it_saved_here(self):
         status, payload = self.post("/api/open", {"what": "shot", "id": "1/250820/19990101000000_1.jpg"})
         self.assertEqual(status, 404, payload)
@@ -524,6 +547,14 @@ class LocalMode(unittest.TestCase):
         self.assertEqual(status, 200, body)
         self.assertIsInstance(body["titles"], list)
 
+    def test_recordings_are_for_a_computer(self):
+        for method, path, body in (("GET", "/api/record", None), ("GET", "/api/clips", None),
+                                   ("POST", "/api/record", {"action": "start"}),
+                                   ("POST", "/api/clips/export", {"id": "1/video/bg_620_20261020_201950"})):
+            status, payload = self.request(method, path, body)
+            self.assertEqual(status, 400, (path, payload))
+            self.assertIn("computer", payload["error"])
+
     def test_open_is_for_the_app_and_power_needs_a_password(self):
         self.assertEqual(self.request("POST", "/api/open", {"what": "terminal"})[0], 400)
         status, body = self.request("POST", "/api/open", {"what": "reboot"})

tests/test_service_regressions.py

@@ -0,0 +1,762 @@
+"""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())
+                if os.name != 'nt':  # Windows has no execute bit to restore
+                    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_standalone_review.py

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

@@ -0,0 +1,360 @@
+"""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):
+        # Sixty milliseconds pass while a slot is busy. A still-running lookup
+        # gets only the remaining forty, regardless of the test host's load.
+        with patch.object(_images, '_resolvers') as slots, \
+                patch.object(_images.time, 'monotonic', side_effect=[100, 100.06]), \
+                patch.object(_images.threading, 'Thread') as worker:
+            slots.acquire.return_value = True
+            with self.assertRaises(SourceError):
+                _images._resolve('slow.example', 443, 0.1)
+            slots.acquire.assert_called_once_with(timeout=0.1)
+            self.assertAlmostEqual(worker.return_value.join.call_args.args[0], 0.04)
+
+    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_tracking.py

@@ -1,188 +0,0 @@
-"""Tracking protocols and fake-Frame BlueZ lifecycle; no headset or strap needed."""
-import importlib.util
-import math
-import os
-from pathlib import Path
-import socket
-import stat
-import struct
-import tempfile
-import unittest
-from unittest.mock import Mock, patch
-
-SPEC = importlib.util.spec_from_file_location("tracking", Path(__file__).resolve().parents[1] / "frame/tracking/tracking.py")
-t = importlib.util.module_from_spec(SPEC)
-SPEC.loader.exec_module(t)
-
-
-class Protocols(unittest.TestCase):
-    def test_hrs_formats(self):
-        self.assertEqual(t.heart_rate(b"\x00\x48"), 72)
-        self.assertEqual(t.heart_rate(b"\x01\x2c\x01"), 300)
-        self.assertEqual(t.heart_rate(b"\x1e\x48\x01\x00\x00\x04\x00\x04"), 72)
-        self.assertEqual(t.heart_rate(b"\x02\x48"), 72)  # contact not supported
-        self.assertIsNone(t.heart_rate(b"\x04\x48"))  # no contact
-        self.assertIsNone(t.heart_rate(b"\x00\x00"))
-
-    def test_hrs_malformed(self):
-        for packet in (b"", b"\x00", b"\x01\x48", b"\x08\x48\x00", b"\x10\x48",
-                       b"\x10\x48\x00", b"\x00\x48\x01", b"\xe0\x48"):
-            with self.subTest(packet=packet), self.assertRaises(ValueError):
-                t.heart_rate(packet)
-
-    def test_gaze_coordinates(self):
-        self.assertEqual(t.gaze_angles([0, 0, 0, 1]), (0, 0))
-        angle = math.radians(15)
-        pitch, yaw = t.gaze_angles([math.sin(angle), 0, 0, math.cos(angle)])
-        self.assertAlmostEqual(pitch, -30)  # OpenXR +X rotation looks up
-        self.assertAlmostEqual(yaw, 0)
-        pitch, yaw = t.gaze_angles([0, -math.sin(angle), 0, math.cos(angle)])
-        self.assertAlmostEqual(pitch, 0)
-        self.assertAlmostEqual(yaw, 30)  # right
-
-    def test_invalid_gaze(self):
-        for pose in ([0, 0, 0, 0], [math.nan, 0, 0, 1], [0, 0, 0], [0, 0, 0, math.inf]):
-            with self.assertRaises(ValueError):
-                t.gaze_angles(pose)
-
-    def test_osc_wire(self):
-        self.assertEqual(t.osc_message('/x', [72]), b'/x\0\0,i\0\0' + struct.pack('>i', 72))
-        self.assertEqual(t.osc_message('/x', [1.0, -2.0]), b'/x\0\0,ff\0' + struct.pack('>ff', 1, -2))
-        for address in ('x', '/x\0y', '/x y', '/x*'):
-            with self.assertRaises(ValueError):
-                t.osc_message(address, [1])
-
-    def test_default_never_opens_socket(self):
-        with patch.object(t.socket, 'socket') as create:
-            osc = t.Osc()
-            osc.send('/x', [72])
-            osc.close()
-            create.assert_not_called()
-
-    def test_only_configured_endpoint(self):
-        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as receiver:
-            receiver.bind(('127.0.0.1', 0))
-            receiver.settimeout(1)
-            osc = t.Osc(receiver.getsockname())
-            try:
-                osc.send('/tracking/eye/CenterPitchYaw', [0.0, 30.0])
-                self.assertEqual(receiver.recv(1024), t.osc_message('/tracking/eye/CenterPitchYaw', [0.0, 30.0]))
-            finally:
-                osc.close()
-
-    def test_endpoint_validation(self):
-        for endpoint in [('example.org', 9000), ('0.0.0.0', 9000), ('224.0.0.1', 9000), ('127.0.0.1', 0), ('::1', 65536)]:
-            with self.assertRaises(ValueError):
-                t.Osc(endpoint)
-
-    def test_heart_staleness_contact_and_log(self):
-        now = [0]
-        osc = Mock()
-        with tempfile.TemporaryDirectory() as directory:
-            path = Path(directory) / 'session.csv'
-            session = t.HeartSession(osc, '/hr', path, lambda: now[0])
-            self.assertIsNone(session.current())
-            session.notification(b'\x00\x48')
-            self.assertEqual(session.current(), 72)
-            osc.send.assert_called_once_with('/hr', [72])
-            now[0] = 6
-            self.assertIsNone(session.current())
-            session.notification(b'\x04\x48')
-            self.assertIsNone(session.current())
-            self.assertEqual(osc.send.call_count, 1)
-            session.close()
-            self.assertEqual(path.read_text().splitlines()[0], 'unix_seconds,bpm')
-            self.assertEqual(len(path.read_text().splitlines()), 2)
-            if os.name != 'nt':
-                self.assertEqual(stat.S_IMODE(path.stat().st_mode), 0o600)
-            with self.assertRaises(FileExistsError):
-                t.HeartSession(osc, '/hr', path)
-
-    def test_no_log_by_default(self):
-        with patch.object(t.os, 'open') as create:
-            session = t.HeartSession(Mock(), '/hr')
-            session.notification(b'\x00\x48')
-            session.close()
-            create.assert_not_called()
-
-
-class FakeBluez(unittest.TestCase):
-    def setUp(self):
-        self.device = '/org/bluez/hci0/dev_TEST'
-        self.service = self.device + '/service1'
-        self.char = self.service + '/char1'
-        self.objects = {
-            self.device: {t.DEVICE: {'Address': 'AA:BB:CC:DD:EE:FF', 'Connected': False, 'ServicesResolved': True}},
-            self.service: {t.SERVICE: {'UUID': t.HRS, 'Device': self.device}},
-            self.char: {t.CHARACTERISTIC: {'UUID': t.MEASUREMENT, 'Service': self.service, 'Flags': ['notify']}},
-        }
-        self.api = Mock()
-        self.api.GetManagedObjects.side_effect = lambda: self.objects
-        self.bus = Mock()
-        self.interface = Mock(return_value=self.api)
-        self.values = Mock()
-
-    def reader(self):
-        return t.BluezHeart(self.bus, self.interface, 'AA:BB:CC:DD:EE:FF', self.values)
-
-    def test_subscribe_receive_and_cleanup(self):
-        reader = self.reader()
-        self.api.Connect.assert_called_once()
-        self.assertTrue(reader.subscribe())
-        self.api.StartNotify.assert_called_once()
-        reader.changed(t.CHARACTERISTIC, {'Value': [0, 72]}, [], self.char)
-        self.values.assert_called_once_with([0, 72])
-        reader.changed(t.CHARACTERISTIC, {'Value': [0, 73]}, [], '/other/strap')
-        self.assertEqual(self.values.call_count, 1)
-        reader.close()
-        self.api.StopNotify.assert_called_once()
-        self.api.Disconnect.assert_called_once()
-        self.bus.add_signal_receiver.return_value.remove.assert_called_once()
-
-    def test_preserve_existing_connection(self):
-        self.objects[self.device][t.DEVICE]['Connected'] = True
-        reader = self.reader()
-        reader.subscribe()
-        reader.close()
-        self.api.Connect.assert_not_called()
-        self.api.Disconnect.assert_not_called()
-
-    def test_only_selected_device_service(self):
-        self.objects[self.service][t.SERVICE]['Device'] = '/other/device'
-        reader = self.reader()
-        try:
-            with self.assertRaises(RuntimeError):
-                reader.subscribe()
-        finally:
-            reader.close()
-        self.api.StartNotify.assert_not_called()
-
-    def test_wait_for_services(self):
-        self.objects[self.device][t.DEVICE]['ServicesResolved'] = False
-        reader = self.reader()
-        self.assertFalse(reader.subscribe())
-        reader.close()
-        self.api.StartNotify.assert_not_called()
-        self.api.StopNotify.assert_not_called()
-
-    def test_disconnect_notification(self):
-        reader = self.reader()
-        reader.changed(t.DEVICE, {'Connected': 0}, [], self.device)  # dbus.Boolean behaves as int
-        self.values.assert_called_once_with(None)
-        reader.close()
-
-    def test_failed_notify_cleans_connection(self):
-        reader = self.reader()
-        self.api.StartNotify.side_effect = RuntimeError('failure')
-        with self.assertRaises(RuntimeError):
-            reader.subscribe()
-        reader.close()
-        self.api.StopNotify.assert_not_called()
-        self.api.Disconnect.assert_called_once()
-
-    def test_unknown_device_does_not_connect_or_scan(self):
-        self.objects.clear()
-        with self.assertRaises(RuntimeError):
-            self.reader()
-        self.api.Connect.assert_not_called()
-        self.api.StartDiscovery.assert_not_called()

tests/test_typing_ui.py

@@ -0,0 +1,14 @@
+"""Type on the headset: entry points, the T key and the clipboard copy, without a browser or headset."""
+import shutil
+import subprocess
+import unittest
+from pathlib import Path
+
+
+@unittest.skipUnless(shutil.which('node'), 'Node exercises the page code')
+class TypingUi(unittest.TestCase):
+    def test_behavior(self):
+        root = Path(__file__).resolve().parents[1]
+        result = subprocess.run(['node', '--test', str(root / 'tests/typing_ui.cjs')],
+                                capture_output=True, text=True)
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

tests/test_ui_review.py

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

@@ -0,0 +1,14 @@
+"""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/test_webinstall.py

@@ -394,7 +394,7 @@ class ServerJobs(unittest.TestCase):
             places = s._tmp_places()
             self.assertEqual({p for _, p in places}, {s.WEB_TMP_PREFIX, s.frame_titles.TMP_PREFIX,
                                                       s.frame_android.TMP_PREFIX, s.frame_agent.TMP_PREFIX,
-                                                      s.apk_fdroid.TMP_PREFIX})
+                                                      s.apk_fdroid.TMP_PREFIX, s.ANDROID_BACKUP_TMP})
             for folder, prefix in places:
                 folder.mkdir(parents=True, exist_ok=True)
                 gone = tempfile.mkdtemp(prefix=f"{prefix}{dead.pid}-", dir=folder)

tests/typing_ui.cjs

@@ -0,0 +1,114 @@
+// Type on the headset: where people find it, the T key, and copying the headset's clipboard.
+// Production page code with only browser and transport boundaries replaced; no headset.
+const test=require('node:test');
+const assert=require('node:assert/strict');
+const cc=require('../ui/control-center.js');
+const {workspaceFixture,html}=require('./workspace_fixture.cjs');
+
+const between=(from,to)=>{const start=html.indexOf(from),end=html.indexOf(to,start);assert.ok(start>=0&&end>start,from);return html.slice(start,end);};
+const section=id=>between(`id="${id}"`,'</section>');
+
+test('Home, the Right now card and the Tools directory all name it Type on the headset',()=>{
+  const home=between('data-page="home"','data-page="capture"');
+  assert.match(home,/<a href="#pad" title="Type on the headset \(T\)"><span>Type on the headset<\/span><small>Keyboard, trackpad and clipboard<\/small>/);
+  assert.match(home,/<button data-go="pad" title="Type on the headset \(T\)">Type on the headset<\/button>/);
+  assert.match(between('id="toolDirectory"','<h2>Your Frame</h2>'),/href="#pad"[^>]*><span>Type on the headset<\/span>/);
+  assert.doesNotMatch(html,/Keyboard &(amp;)? trackpad<\/span>|Type on the Frame</);
+});
+test('the clipboard, both ways, lives beside the keyboard, not in Send to Frame',()=>{
+  const pad=section('pad');
+  for(const id of ['clipText','clipSend','clipMac','clipFrom'])assert.match(pad,new RegExp(`id="${id}"`),id);
+  assert.match(pad,/Text only, up to 1 MB/);
+  const transfer=section('transfer');
+  assert.doesNotMatch(transfer,/id="clip/);
+  assert.match(transfer,/<a href="#pad">Type on the headset<\/a>/);
+});
+test('the tool page is titled Type on the headset',()=>{
+  const f=workspaceFixture();
+  f.navigate('#pad');
+  assert.equal(f.activePage,'tools');assert.equal(f.el('pad').hidden,false);
+  assert.equal(f.el('toolTitle').textContent,'Type on the headset');
+  assert.equal(f.el('transfer').hidden,true);
+});
+
+function keyFixture() {
+  const f=workspaceFixture(),keys=[];let focused=0,started=0;
+  Object.assign(f.context,{pad:{state:'off'},padStart(){started++;},ctrl:{on:false},PAGES:['apps','games','tools','settings'],
+    history:{pushState(_,__,url){f.context.location.hash=url;}}});
+  f.context.document.addEventListener=(type,fn)=>{if(type==='keydown')keys.push(fn);};
+  f.context.document.querySelector=()=>null;
+  f.context.document.activeElement={tagName:'BODY'};
+  f.el('padType').focus=()=>{focused++;};
+  f.run(between('function showNow(','$("nowSend").onclick'));
+  f.run(between('document.addEventListener("keydown", e => {\n  if (e.metaKey || e.ctrlKey || e.altKey','// ---- after an APK install'));
+  const press=(key,extra={})=>{let prevented=false;keys.forEach(fn=>fn({key,preventDefault(){prevented=true;},...extra}));return prevented;};
+  return {f,press,get focused(){return focused;},get started(){return started;}};
+}
+test('T opens Type on the headset, turns the keyboard on and puts the cursor in its field',()=>{
+  const k=keyFixture();
+  k.f.navigate('#games');
+  assert.equal(k.press('t'),true,'the T must not also be typed into the field it focuses');
+  assert.equal(k.f.context.location.hash,'#pad');assert.equal(k.f.activePage,'tools');
+  assert.equal(k.started,1);assert.equal(k.focused,1);
+  k.f.context.pad.state='ready';k.press('T');assert.equal(k.started,1,'already on: not started again');
+});
+test('T stays out of the way of typing, shortcuts and keys going to the Frame',()=>{
+  const k=keyFixture();
+  k.f.navigate('#games');
+  k.press('t',{metaKey:true});k.press('t',{ctrlKey:true});k.press('t',{altKey:true});
+  k.f.context.document.activeElement={tagName:'INPUT'};k.press('t');
+  k.f.context.document.activeElement={tagName:'BODY'};k.f.context.document.querySelector=s=>s==='dialog[open]'?{}:null;k.press('t');
+  k.f.context.document.querySelector=()=>null;
+  k.f.context.ctrl.on=true;k.f.context.document.activeElement=k.f.el('viewer');k.press('t');
+  assert.equal(k.f.context.location.hash,'#games');assert.equal(k.started,0);
+  k.f.context.document.activeElement={tagName:'BODY'};k.press('3');assert.equal(k.f.context.location.hash,'#tools','number keys still switch pages');
+});
+test('Home’s button goes through the same path, showing the tool once before focusing it',()=>{
+  const f=workspaceFixture(),buttons=[{dataset:{go:'pad'}},{dataset:{go:'media'}}];let focusedVisible=null;
+  f.context.document.querySelectorAll=(q=>s=>s==='[data-go]'?buttons:q(s))(f.context.document.querySelectorAll);
+  Object.assign(f.context,{pad:{state:'error'},padStart(){f.calls.push(['padStart']);},history:{pushState(_,__,url){f.context.location.hash=url;}}});
+  f.el('padType').focus=()=>{focusedVisible=f.activePage==='tools'&&!f.el('pad').hidden;};
+  f.navigate('#home');f.run(between('function showNow(','$("nowSend").onclick'));
+  buttons[0].onclick();
+  assert.equal(focusedVisible,true);assert.equal(f.calls.filter(c=>c[0]==='padStart').length,1);
+  buttons[1].onclick();assert.equal(f.context.location.hash,'#media');
+});
+
+function copyFixture(frameApp) {
+  const calls=[],f=workspaceFixture();
+  Object.assign(f.context,{window:{frameApp},api:async(path,body)=>{calls.push(JSON.parse(JSON.stringify([path,body])));return body.read?{text:'héllo 🎧\n',message:'Copied 8 characters from the headset\'s clipboard'}:{message:'Copied to this computer'};}});
+  f.run(between('async function copyHeadsetClipboard()','$("clipFrom").onclick'));
+  return {f,calls};
+}
+test('in the app, the headset’s clipboard is read and the app writes it, text untouched',async()=>{
+  const written=[],{f,calls}=copyFixture({writeClipboard:async text=>{written.push(text);return true;}});
+  const result=await f.run('copyHeadsetClipboard()');
+  assert.deepEqual(calls,[['/api/clipboard',{read:true}]]);
+  assert.deepEqual(written,['héllo 🎧\n']);
+  assert.equal(result.message,'Copied 8 characters from the headset\'s clipboard');
+  assert.equal(result.text,undefined,'the text is not handed on to be logged or toasted');
+});
+test('in a browser, the server sets the clipboard of the computer it runs on',async()=>{
+  for(const frameApp of [undefined,{readClipboard(){}}]){
+    const {f,calls}=copyFixture(frameApp);
+    assert.equal((await f.run('copyHeadsetClipboard()')).message,'Copied to this computer');
+    assert.deepEqual(calls,[['/api/clipboard',{toComputer:true}]]);
+  }
+});
+test('a failed read writes nothing',async()=>{
+  const written=[],f=workspaceFixture();
+  Object.assign(f.context,{window:{frameApp:{writeClipboard:async t=>written.push(t)}},api:async()=>{throw new Error("The headset's clipboard is empty");}});
+  f.run(between('async function copyHeadsetClipboard()','$("clipFrom").onclick'));
+  await assert.rejects(f.run('copyHeadsetClipboard()'),/empty/);
+  assert.deepEqual(written,[]);
+});
+
+test('the Control Center finds Type on the headset by typing, keyboard and clipboard words',()=>{
+  const input=cc.catalog.find(item=>item.id==='input');
+  assert.equal(input.title,'Type on the headset');
+  assert.deepEqual(input.links[0],['#pad','Type on the headset']);
+  for(const query of ['type','typing','keyboard','clipboard','copy paste','kde connect'])
+    assert.ok(cc.matches(input,query,'all'),query);
+  const files=cc.catalog.find(item=>item.id==='files');
+  assert.ok(files.links.some(([href])=>href==='#pad'),'Send files points clipboard seekers to the right place');
+});

tests/ui_review.cjs

@@ -0,0 +1,116 @@
+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(){},resetClips(){},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

@@ -0,0 +1,335 @@
+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');
+});
+test('Home shortcuts show their tool before focusing it, so typing works on the first tap',()=>{
+  const f=workspaceFixture(),pad={state:'on'},buttons=[{dataset:{go:'pad'}}];let focusedVisible=null;
+  f.context.document.querySelectorAll=(q=>s=>s==='[data-go]'?buttons:q(s))(f.context.document.querySelectorAll);
+  Object.assign(f.context,{pad,padStart(){},history:{pushState(_,__,url){f.context.location.hash=url;}}});
+  f.el('padType').focus=()=>{focusedVisible=f.activePage==='tools'&&!f.el('pad').hidden;};
+  f.navigate('#home');
+  const start=html.indexOf('function showNow('),end=html.indexOf('$("nowSend").onclick',start);
+  let shows=0;f.run('const realShowPage=showPage;');f.context.showPage=()=>{shows++;f.run('realShowPage()');};
+  f.run(html.slice(start,end).replace(/showPage\(\)/g,'globalThis.showPage()'));buttons[0].onclick();
+  assert.equal(focusedVisible,true);assert.equal(shows,1);assert.equal(f.context.location.hash,'#pad');
+});
+test('a Home shortcut keeps the destination scroll and loads its tool once, with frames deferred',()=>{
+  const f=workspaceFixture(),frames=[],events=[],buttons=[{dataset:{go:'pad'}},{dataset:{go:'macview'}}];
+  // A hash assignment queues hashchange, which a browser may deliver before the next frame.
+  let hash=f.context.location.hash;
+  Object.defineProperty(f.context.location,'hash',{get:()=>hash,set(v){const next='#'+String(v).replace(/^#/,'');if(next!==hash){hash=next;events.push(()=>f.run('showPage({type:"hashchange"})'));}}});
+  const flush=()=>{while(events.length||frames.length)(events.length?events:frames).shift()();};
+  f.context.requestAnimationFrame=fn=>frames.push(fn);
+  f.context.document.querySelectorAll=(q=>s=>s==='[data-go]'?buttons:q(s))(f.context.document.querySelectorAll);
+  Object.assign(f.context,{pad:{state:'on'},padStart(){},history:{pushState(_,__,url){hash=url;}}});
+  f.el('padType').focus=()=>{};
+  f.navigate('#pad');flush();f.scroll(320);
+  f.navigate('#home');flush();f.scroll(150);
+  const start=html.indexOf('function showNow('),end=html.indexOf('$("nowSend").onclick',start);
+  f.run(html.slice(start,end));
+  buttons[0].onclick();flush();
+  assert.equal(f.context.window.scrollY,320);
+  f.navigate('#home');flush();f.calls.length=0;
+  buttons[1].onclick();flush();
+  assert.equal(f.calls.filter(c=>c[0]==='macview').length,1);
+});
+test('Cast keeps the Capture scroll and shows Capture once, with frames deferred',()=>{
+  const f=workspaceFixture(),frames=[],events=[];let shows=0;
+  let hash=f.context.location.hash;
+  Object.defineProperty(f.context.location,'hash',{get:()=>hash,set(v){const next='#'+String(v).replace(/^#/,'');if(next!==hash){hash=next;events.push(()=>f.run('showPage({type:"hashchange"})'));}}});
+  const flush=()=>{while(events.length||frames.length)(events.length?events:frames).shift()();};
+  f.context.requestAnimationFrame=fn=>frames.push(fn);
+  Object.assign(f.context,{history:{pushState(_,__,url){hash=url;}},setView(){},toggleLive(){}});
+  f.el('viewer').requestFullscreen=()=>Promise.resolve();
+  f.navigate('#capture');flush();f.scroll(320);
+  f.navigate('#home');flush();f.scroll(150);
+  const start=html.indexOf('function showNow('),end=html.indexOf('\n};\n',html.indexOf('$("castBtn").onclick'))+4;
+  f.run(html.slice(start,end).replace(/showPage\(\)/g,'(globalThis.__shows=(globalThis.__shows||0)+1,showPage())'));
+  f.el('castBtn').onclick();flush();
+  assert.equal(f.context.window.scrollY,320);assert.equal(f.run('globalThis.__shows'),1);assert.equal(hash,'#capture');
+});

tests/workspace_fixture.cjs

@@ -0,0 +1,39 @@
+// 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=node.parentNode=this;},prepend(node){node.parent=node.parentNode=this;},scrollIntoView(){calls.push(['section',id]);},
+      showModal(){this.open=true;},close(){this.open=false;},addEventListener(k,fn){listeners[id+'-'+k]=fn;}});
+    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,scroller:()=>({get scrollTop(){return win.scrollY;},scrollTo:o=>win.scrollTo(o)}),scrollToY:y=>win.scrollTo({top:y}),requestAnimationFrame:fn=>fn(),$:el,live:false,toggleLive(on){this.live=on;calls.push(['live',on]);},
+    loadAndroid(){calls.push(['android']);},closeDevPop(){},metaLib:{connected:false},renderMetaApps(){},
+    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/_categories.py

@@ -0,0 +1,116 @@
+"""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/_images.py

@@ -12,7 +12,9 @@ from urllib.parse import urljoin, urlsplit
 from apk_sources import SourceError, _credentials
 
 _lock = threading.Lock()
-_urls = OrderedDict()
+_urls = OrderedDict()  # token -> URL, oldest first
+_tokens = {}  # URL -> token
+MAX_TOKENS = 16384
 _cache = OrderedDict()
 MAX_IMAGE = 8 * 1024 * 1024
 MAX_CACHE = 64 * 1024 * 1024
@@ -31,24 +33,24 @@ def register(url):
     if not isinstance(url, str) or not valid_url(url):
         return None
     with _lock:
-        for token, known in _urls.items():
-            if known == url:
-                _urls.move_to_end(token)
-                return '/source-image/' + token
+        token = _tokens.get(url)
+        if token in _urls:
+            _urls.move_to_end(token)
+            return '/source-image/' + token
         token = secrets.token_urlsafe(24)
-        _urls[token] = url
-        while len(_urls) > 4096:
-            _urls.popitem(last=False)
+        _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)
     return '/source-image/' + token
 
 
-def artwork(entry):
+def artwork(entry, shots=12):
     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 [])[:12]) if path]}
+            'screenshots': [path for path in (register(u) for u in (images.get('screenshots') or [])[:min(shots, 12)]) if path]}
 
 
 def image_type(data):
@@ -71,12 +73,37 @@ 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.
-    if not _resolvers.acquire(blocking=False):
+    # 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))):
         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():

ui/apk_sources/fdroid.py

@@ -26,7 +26,7 @@ from frame_apk_sign import _der_parts, _cert_key, der
 from frame_catalog import _IndexReader, _reduce_index, _sha256
 
 KIND = 'fdroid'
-CACHE_VERSION = 2
+CACHE_VERSION = 3  # 3: categories
 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 = {}
@@ -474,6 +474,7 @@ 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
@@ -492,6 +493,7 @@ 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():
@@ -684,16 +686,39 @@ def set_enabled(source_id, enabled):
         _write(_storage(), settings)
 
 
-def search(source, query, limit=50):
+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)."""
     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)]
-    found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
+    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)
     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')

ui/apk_sources/search.py

@@ -15,7 +15,7 @@ import time
 import unicodedata
 
 import frame_host
-from apk_sources import SourceError, SourceLimited
+from apk_sources import SourceError, SourceLimited, _categories as categories
 
 _lock = threading.RLock()
 _running = {}
@@ -23,6 +23,7 @@ _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():
@@ -166,9 +167,11 @@ def verdict(entry):
     return {'label': 'Not yet checked on the Frame', 'tone': 'unknown'}
 
 
-def decorate(entry):
+def decorate(entry, shots=12):
+    """shots: screenshots to offer; a listing card shows three, the detail page all of them."""
     from apk_sources import _images
-    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry))
+    return dict(entry, fit=fit(entry), verdict=verdict(entry), artwork=_images.artwork(entry, shots),
+                **categories.classify(entry))
 
 
 def details(source_id, entry_id):
@@ -186,10 +189,12 @@ def offer_rank(entry):
             entry.get('trust') == 'official')
 
 
-def group(entries, query='', vr=None, installable=False):
+def group(entries, query='', vr=None, installable=False, category=None, phone=False):
     groups = {}
     for entry in entries:
-        entry = decorate(entry)
+        entry = decorate(entry, shots=3)
+        if not categories.matches(entry, category, phone):
+            continue
         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:
@@ -203,7 +208,7 @@ def group(entries, query='', vr=None, installable=False):
         offers.sort(key=offer_rank, reverse=True)
         best = offers[0]
         result.append({'name': best.get('name'), 'package': best.get('package'),
-                       'summary': best.get('summary'), 'offers': offers})
+                       'summary': best.get('summary'), 'category': best.get('category'), 'offers': offers})
     q = normalise(query)
 
     def browse(a):  # a headset store: VR first, then apps with artwork, newest first
@@ -223,10 +228,10 @@ def group(entries, query='', vr=None, installable=False):
     return result
 
 
-def _launch(module, source, query, limit):
+def _launch(module, source, query, limit, category=None, phone=False):
     """One search per source at a time; the newest different query runs next."""
     key = source['id']
-    task = {'event': threading.Event(), 'query': (query, limit), 'started': time.monotonic(),
+    task = {'event': threading.Event(), 'query': (query, limit, category or None, bool(phone)), 'started': time.monotonic(),
             'job': (module, source)}
     with _lock:
         old = _running.get(key)
@@ -245,13 +250,17 @@ def _launch(module, source, query, limit):
 
 def _start(key, task):
     module, source = task['job']
-    query, limit = task['query']
+    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)
 
     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) if e.get('free') is True]
+                               for e in module.search(source, query, limit=limit, **kwargs) if e.get('free') is True]
             task['stale'] = bool(getattr(module, 'stale', lambda s: False)(source))
         except Exception as e:
             task['error'] = str(e)
@@ -267,14 +276,20 @@ def _start(key, task):
     threading.Thread(target=run, daemon=True).start()
 
 
-def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50):
+def search(query='', vr=None, source=None, installable=False, timeout=TIMEOUT, limit=50, category=None, phone=False):
     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)) for m, s in chosen if not s.get('page_only')]
+    tasks = [(s, _launch(m, s, query, limit, category, phone)) 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']}
@@ -289,7 +304,8 @@ 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), 'sources': statuses, 'elsewhere': elsewhere}
+    return {'apps': group(entries, query, vr, installable, category, phone), 'sources': statuses, 'elsewhere': elsewhere,
+            'categories': [{'id': c, 'label': label} for c, label in categories.CATEGORIES]}
 
 
 def warm():
@@ -299,7 +315,35 @@ def warm():
     items, _ = registry()
     for m, s in items:
         if s['enabled'] and not s.get('page_only'):
-            _launch(m, s, '', 50)  # same as the first browse, so that search reuses it
+            _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
 
 
 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 href="/">Back to Frame Control</a></header>
+<header><h1>Frame Control · Assistant</h1><a id="back" href="/" referrerpolicy="no-referrer">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,6 +42,8 @@ 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'],['#apps','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'],['#linuxApps','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',
@@ -68,16 +68,16 @@
     {id:'sideload', category:'apps', icon:'game', title:'Sideloaded games', kind:'flow', label:'Existing controls',
       description:'Send a game folder, ZIP or executable. Frame Control selects Proton or the Linux runtime and adds a Steam library entry.',
       keywords:'windows exe zip linux devkit runtime shortcuts launch remove', links:[['#sideloaded','Manage titles'],['#transfer','Send a game']]},
-    {id:'files', category:'apps', icon:'files', title:'Files & clipboard', kind:'flow', label:'Existing controls',
-      description:'Send files to ~/Downloads, or send text to the Frame’s clipboard. Clipboard transfer needs the desktop panel open.',
-      keywords:'upload transfer downloads paste copy text sftp storage', links:[['#transfer','Send files & text']]},
+    {id:'files', category:'apps', icon:'files', title:'Send files', kind:'flow', label:'Existing controls',
+      description:'Send files to ~/Downloads, or a game to the Steam library. Clipboard text, both ways, is in Type on the headset.',
+      keywords:'upload transfer downloads sftp storage', links:[['#transfer','Send files'],['#pad','Clipboard']]},
     {id:'media', category:'apps', icon:'play', title:'Video & stereo photos', kind:'flow', label:'Preview feature',
       description:'Send and play H.264/H.265 video, SBS/OU photos or small splats with the built-in player. Choose a layout and theatre surround.',
       keywords:'movie photo sbs ou 3d splat gaussian theatre media player', links:[['#media','Open media player']],
       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:[['#apps','Manage Linux apps']]},
+      keywords:'flatpak firefox vlc remmina moonlight flathub install remove', links:[['#linuxApps','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']],
@@ -85,9 +85,11 @@
     {id:'remote', category:'network', icon:'display', title:'Remote access', kind:'flow', label:'Existing controls',
       description:'Open SSH, SFTP, Steam Link or remote desktop using the host’s existing tools. Developer Mode enables headset SSH and xrdp.',
       keywords:'terminal shell remote desktop rdp xrdp streaming steam link sftp', links:[['#power','Open remote tools']]},
-    {id:'input', category:'network', icon:'keyboard', title:'Keyboard & trackpad', kind:'flow', label:'Existing controls',
-      description:'Type and point in the Frame’s apps with KDE Connect, or use Control on the live panel view. First use sets up the input helper.',
-      keywords:'mouse pointer keyboard trackpad touch click kde input', links:[['#pad','Open keyboard & trackpad'],['#view','Panel control']]},
+    {id:'input', category:'network', icon:'keyboard', title:'Type on the headset', kind:'flow', label:'Existing controls',
+      description:'Type and point in the Frame’s apps with this computer’s keyboard and mouse, and copy text both ways between the clipboards. Press T anywhere to open it.',
+      keywords:'mouse pointer keyboard trackpad touch click kde connect input type typing text clipboard copy paste send',
+      links:[['#pad','Type on the headset'],['#view','Panel control']],
+      guidance:'The keyboard sets up KDE Connect on the Frame the first time. The clipboard needs the desktop panel open in the headset.'},
     {id:'mac', category:'network', icon:'display', title:'Mac in the headset', kind:'flow', label:'macOS only', platform:'mac',
       description:'Stream Mac screens or individual windows into headset panels. Choose quality and give each window its own display.',
       keywords:'macos mac window screen sharing stream quality sharp balanced light permissions', links:[['#macview','Configure Mac streaming']],

ui/frame_agent.py

@@ -90,6 +90,13 @@ 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']):
@@ -98,6 +105,7 @@ 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

@@ -187,6 +187,58 @@ 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 = []
@@ -541,16 +593,22 @@ 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 = False, None
+    ok, created, backed_up, library_started = False, None, False, False
     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'
@@ -564,6 +622,7 @@ 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}',
@@ -580,26 +639,72 @@ 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 FrameError:
+            except Exception:
                 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 FrameError:
+            except Exception:
                 pass
-        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.
+        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.
             try:
                 ssh(f'rm -f {d}/app.apk.part', timeout=30)
-            except FrameError:
+            except Exception:
                 pass
 
 
@@ -703,9 +808,36 @@ 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
-        m = _meta_or_fail(pkg)
         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))
         # Parse the APK on the Frame, transferring only its icon/label, not the APK.
         script = _apk_parser_script()
         script += f"info = sys.modules['frame_apk'].apk_info({(d + '/app.apk')!r})\n"
@@ -726,7 +858,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)
+                                   fill_only=fill_only and not created and not recovering)
         except Exception:
             if created:
                 try:
@@ -738,6 +870,14 @@ 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):

ui/frame_android_import.py

@@ -0,0 +1,145 @@
+"""Import a local Android backup: one APK and its matching expansion files."""
+import re
+import time
+from pathlib import Path
+
+import frame_android as android
+import frame_quest as quest
+
+OBB = re.compile(r'(main|patch)\.[0-9]+\.([A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+)\.obb')
+
+
+def inspect(paths, discover=False):
+    """Inspect selected files before installing anything. Desktop APK drops can find
+    sibling OBBs; browser uploads include only files explicitly selected by the user."""
+    if not isinstance(paths, list) or not paths or len(paths) > 100:
+        raise android.FrameError('Choose one game APK and its .obb game-data files together.')
+    files = []
+    for value in paths:
+        path = Path(value).expanduser().absolute()
+        if path.is_dir():
+            files.extend(p for p in sorted(path.iterdir()) if p.suffix.lower() in ('.apk', '.obb'))
+        else:
+            files.append(path)
+    files = list(dict.fromkeys(files))
+    if not files or len(files) > 100:
+        raise android.FrameError('No Android backup found. Choose a folder containing one APK and its game data.')
+    for path in files:
+        if path.suffix.lower() not in ('.apk', '.obb') or not path.is_file() or path.stat().st_size == 0:
+            raise android.FrameError(f'{path.name}: choose a nonempty APK or .obb game-data file.')
+    apks = [p for p in files if p.suffix.lower() == '.apk']
+    if len(apks) > 1:
+        raise android.FrameError('Choose one game at a time. Split APK backups are not supported by this importer.')
+    apk = apks[0] if apks else None
+    if apk:
+        info = android.apk_info(str(apk))
+        try:
+            android.check_installable(info)
+        except android.FrameError as error:
+            error.apk = {'package': info['package'], 'version_code': info.get('version_code'),
+                         'blocker': str(error)}
+            raise
+        checked = quest.inspect(info['package'], str(apk))
+        pkg = checked['package']
+        if discover and len(files) == 1:
+            files.extend(p for p in sorted(apk.parent.iterdir())
+                         if p not in files and OBB.fullmatch(p.name) and OBB.fullmatch(p.name)[2] == pkg)
+    else:
+        packages = {OBB.fullmatch(p.name)[2] for p in files if OBB.fullmatch(p.name)}
+        if len(packages) != 1:
+            raise android.FrameError('Choose the APK and game-data files for one game together.')
+        pkg = packages.pop()
+        if not android.PKG_RE.fullmatch(pkg):
+            raise android.FrameError('The game-data filename has an invalid Android package name.')
+        meta = android.read_meta(pkg)
+        if not meta:
+            raise android.FrameError('This game is not installed. Add its APK alongside these game-data files.')
+        checked = {k: meta.get(k) for k in ('package', 'label', 'version', 'version_code')}
+        checked['version_code'] = quest._installed_code(pkg, meta)
+        if checked['version_code'] is None:
+            raise android.FrameError('Add the matching APK so Frame Control can check which game version this data belongs to.')
+        checked['warnings'] = []
+    obb = [p for p in files if p.suffix.lower() == '.obb']
+    if len(obb) > 99:
+        raise android.FrameError('Choose one APK and at most 99 game-data files.')
+    if obb and checked['version_code'] is None:
+        raise android.FrameError('The APK has no readable version code, so its game-data target cannot be checked.')
+    names = set()
+    for path in obb:
+        match = OBB.fullmatch(path.name)
+        if not match or match[2] != pkg:
+            raise android.FrameError(f'{path.name} does not belong to {checked["label"]}. Choose matching game data.')
+        if not path.is_file() or not path.stat().st_size or path.name in names:
+            raise android.FrameError(f'{path.name}: game-data files must be nonempty and have unique names.')
+        names.add(path.name)
+    return {'apk': apk, 'obb': obb, 'checked': checked,
+            'signatures': {str(p): (p.stat().st_size, p.stat().st_mtime_ns) for p in [*apks, *obb]}}
+
+
+def public(plan):
+    checked = plan['checked']
+    return {**checked, 'apk': plan['apk'].name if plan['apk'] else None,
+            'obb': [{'name': p.name, 'size': p.stat().st_size} for p in plan['obb']],
+            'size': sum(size for size, _ in plan['signatures'].values())}
+
+
+def install(plan, display='auto', progress=None):
+    """The explicit Import button authorizes starting the game to add its data.
+    Reuse the Quest import's instance/version checks, verified transfer and close."""
+    report = progress or (lambda *_: None)
+    if display not in ('auto', 'flat', 'vr'):
+        raise android.FrameError('Invalid Android display mode.')
+    for path, signature in plan['signatures'].items():
+        p = Path(path)
+        if not p.is_file() or (p.stat().st_size, p.stat().st_mtime_ns) != signature:
+            raise android.FrameError('The backup changed after it was read. Choose the files again.')
+    checked = plan['checked']
+    pkg, label = checked['package'], checked['label']
+    with android._install_lock:
+        if plan['apk']:
+            if quest._running(pkg):
+                raise android.FrameError(f'Close {label} on the Frame, then try importing again.')
+            quest._check_downgrade(android.read_meta(pkg), checked, False)
+            report('Installing the game app', 15)
+            meta = android.install(str(plan['apk']), source=plan['apk'].name,
+                                   flatscreen=None if display == 'auto' else display == 'flat')
+        else:
+            meta = android._meta_or_fail(pkg)
+        if not plan['obb']:
+            report('Done', 100)
+            warnings = list(checked['warnings']) + list(meta.get('vr_issues') or [])
+            return {'message': f'Installed {label}. Open it from your Steam library.', 'app': meta,
+                    'needs_game_data': False, 'warnings': warnings}
+        try:
+            if not quest._running(pkg):
+                report('Starting the game to add its data', 55)
+                android.launch(pkg)
+                deadline = time.monotonic() + 90
+                while not quest._running(pkg):
+                    if time.monotonic() >= deadline:
+                        raise android.FrameError('The game did not start. Check that Steam is open on the Frame.')
+                    time.sleep(2)
+            report('Preparing Android for game data', 65)
+            quest._wait_ready(meta)
+            # Android can be booted before Lepton has installed the APK.
+            deadline = time.monotonic() + 90
+            while True:
+                try:
+                    quest._check_android_package(meta, checked['version_code'])
+                    break
+                except quest.QuestError:
+                    if time.monotonic() >= deadline:
+                        raise
+                    time.sleep(2)
+            result = quest.add_game_data(pkg, checked, plan['obb'], None, report,
+                                         checked['warnings'], source='your backup')
+            if result['closed']:
+                result['message'] = (f'Imported {label} and {len(plan["obb"])} game-data '
+                                     f'file{"s" if len(plan["obb"]) != 1 else ""}. '
+                                     'Ready to open from your Steam library.')
+            return result
+        except Exception as error:
+            closed, why = quest._close(pkg)
+            detail = ('The game is closed.' if closed else f'Close the game on the Frame ({why}).')
+            raise android.FrameError(f'{label} is installed, but its game-data setup did not finish: {error}. '
+                                     f'{detail} Import the same backup again to retry.') from error

ui/frame_autosync.py

@@ -0,0 +1,285 @@
+"""Copy new screenshots and Steam clips from the headset to this computer on their own.
+
+Off until it's turned on in Settings. Then a worker in the server looks about once a
+minute, while a headset is connected and nothing else is running on it, and copies
+what's new with the same code as Save and Export: screenshots to ~/Pictures/SteamFrame,
+saved Steam clips to ~/Videos/SteamFrame.
+
+- Only what's newer than the moment it was turned on, so turning it on doesn't copy
+  the whole back-catalogue; Copy everything now does that, once.
+- What it has copied is remembered per headset (auto-sync.json in the app's data
+  folder), so a file deleted from this computer isn't copied again.
+- A clip Steam is still writing (a chunk changed in the last SETTLE seconds) waits
+  for the next look. Steam's background recording is never copied: it's a rolling
+  buffer, not something anyone chose to keep.
+- When this computer runs out of space it pauses and says so, until Resume.
+- When the headset can't be reached it waits longer each time, up to MAX_BACKOFF.
+
+The server supplies how to reach the headset, so this can be tested without one:
+  list_shots() -> {"shots": [{"id", "time", "saved"}...]}
+  save_shots(device, ids) copies those screenshots here
+  list_clips() -> {"clips": [{"id", "kind", "time", "idle", "saved"}...]}
+  export_clip(device, id) exports one clip here
+  device() -> the connected headset's id, or None
+  busy() -> True while other work runs on the headset (installs, jobs, a recording)
+  offline(error) -> a plain message if the error means the headset couldn't be reached
+"""
+import errno
+import json
+import os
+import shutil
+import threading
+import time
+from pathlib import Path
+
+import frame_host
+
+INTERVAL = 60  # seconds between looks
+BUSY_WAIT = 15  # something else is running: look again soon
+MAX_BACKOFF = 15 * 60  # the longest wait while the headset can't be reached
+SETTLE = 30  # a clip written to within this many seconds is still being recorded
+MIN_FREE = 512 * 1024**2  # pause below this much free space on this computer
+KEEP = 5000  # copied ids remembered per headset and kind
+BATCH = 100  # screenshots per copy
+TRIES = 3  # an item that fails this often is left until the app restarts
+KINDS = ("shots", "clips")
+
+
+class DiskFull(Exception):
+    pass
+
+
+def free_space(folder):
+    """Free bytes on the disk `folder` is (or will be) on."""
+    p = Path(folder)
+    while not p.exists() and p != p.parent:
+        p = p.parent
+    return shutil.disk_usage(p).free
+
+
+def disk_full(error):
+    """Whether an error means this computer ran out of space (not the headset)."""
+    if isinstance(error, OSError) and error.errno == errno.ENOSPC:
+        return True
+    text = str(error)
+    return "No space left on device" in text or "free space on this computer" in text
+
+
+def _defaults():
+    return {"screenshots": False, "clips": False, "since": None, "synced": {}, "paused": None,
+            "checked": None, "copied": 0, "copied_time": None, "error": None, "waiting": 0}
+
+
+class AutoSync:
+    def __init__(self, list_shots, save_shots, list_clips, export_clip, device, busy, offline=lambda e: None,
+                 shots_folder=None, clips_folder=None, path=None, clock=time.time, space=free_space):
+        self.list_shots, self.save_shots = list_shots, save_shots
+        self.list_clips, self.export_clip = list_clips, export_clip
+        self.device, self.busy, self.offline = device, busy, offline
+        self.shots_folder = Path(shots_folder or Path.home() / "Pictures" / "SteamFrame")
+        self.clips_folder = Path(clips_folder or Path.home() / "Videos" / "SteamFrame")
+        self.path = Path(path or frame_host.data_dir("auto-sync.json"))
+        self.clock, self.space = clock, space
+        self._lock = threading.RLock()
+        self._wake = threading.Event()
+        self._all = False  # Copy everything now, waiting for the next pass
+        self._running = False
+        self._backoff = 0
+        self._tries = {}  # (device, id) -> failed attempts this run
+        self._errors = []  # this pass's, for the page
+        self._s = self._load()
+
+    # ---- settings and what the page shows ----
+    def _load(self):
+        s = _defaults()
+        try:
+            saved = json.loads(self.path.read_text())
+            if isinstance(saved, dict):
+                s.update({k: v for k, v in saved.items() if k in s})
+        except (OSError, ValueError):
+            pass
+        s["screenshots"], s["clips"] = bool(s["screenshots"]), bool(s["clips"])
+        if not isinstance(s["synced"], dict):
+            s["synced"] = {}
+        return s
+
+    def _save(self):
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self.path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(self._s, indent=1))
+            os.replace(tmp, self.path)
+        except OSError:
+            pass  # the settings still apply until the app restarts
+
+    def enabled(self):
+        with self._lock:
+            return self._s["screenshots"] or self._s["clips"]
+
+    def state(self):
+        with self._lock:
+            s = self._s
+            return {k: s[k] for k in ("screenshots", "clips", "since", "paused", "checked", "copied",
+                                      "copied_time", "error", "waiting")} | {
+                "pending": self._all, "running": self._running,
+                "folders": {"shots": str(self.shots_folder), "clips": str(self.clips_folder)}}
+
+    def update(self, changes):
+        """{"screenshots": bool, "clips": bool}: turning it on starts the watermark now."""
+        with self._lock:
+            was = self.enabled()
+            for key in ("screenshots", "clips"):
+                if key in changes:
+                    self._s[key] = bool(changes[key])
+            if self.enabled() and (not was or self._s["since"] is None):
+                self._s["since"] = self.clock()
+            if not self.enabled():
+                self._s["error"], self._s["waiting"] = None, 0
+            self._save()
+        self._wake.set()
+        return self.state()
+
+    def copy_all(self):
+        """Copy everything on the headset that isn't on this computer, once (also resumes)."""
+        with self._lock:
+            self._all, self._s["paused"] = True, None
+            self._save()
+        self._wake.set()
+        return self.state()
+
+    def resume(self):
+        with self._lock:
+            self._s["paused"], self._s["error"] = None, None
+            self._save()
+        self._backoff = 0
+        self._wake.set()
+        return self.state()
+
+    # ---- the worker ----
+    def run(self, stop):
+        """Until `stop` (a threading.Event) is set."""
+        while not stop.is_set():
+            delay = self.tick()
+            self._wake.wait(delay)
+            self._wake.clear()
+
+    def tick(self):
+        """One look. -> seconds until the next."""
+        with self._lock:
+            want_all = self._all
+            shots = self._s["screenshots"] or want_all
+            clips = self._s["clips"] or want_all
+            if not (shots or clips) or self._s["paused"]:
+                return INTERVAL
+            since = None if want_all else self._s["since"] or 0
+        device = self.device()
+        if not device:
+            return INTERVAL  # nothing connected: nothing to ask
+        if self.busy():
+            return BUSY_WAIT
+        with self._lock:
+            self._running = True
+        self._errors = []
+        try:
+            copied, waiting, done = self._pass(device, shots, clips, since)
+        except DiskFull as e:
+            with self._lock:
+                self._s.update(paused=str(e), error=str(e))
+                self._save()
+            return INTERVAL
+        except Exception as e:
+            friendly = self.offline(e)
+            self._backoff = min(max(self._backoff * 2, INTERVAL * 2), MAX_BACKOFF)
+            with self._lock:
+                self._s["error"] = friendly or str(e)
+                self._save()
+            return self._backoff
+        finally:
+            with self._lock:
+                self._running = False
+        self._backoff = 0
+        with self._lock:
+            if copied:
+                self._s.update(copied=copied, copied_time=self.clock())
+            self._s.update(checked=self.clock(), waiting=waiting)
+            if done:
+                self._s["error"] = self._errors[0] if self._errors else None
+                if want_all:
+                    self._all = False
+            self._save()
+        return INTERVAL if done else BUSY_WAIT
+
+    def _synced(self, device, kind):
+        with self._lock:
+            return set(self._s["synced"].get(device, {}).get(kind, []))
+
+    def _mark(self, device, kind, ids):
+        with self._lock:
+            per = self._s["synced"].setdefault(device, {})
+            have = per.get(kind, [])
+            new = [i for i in ids if i not in set(have)]
+            if new:
+                per[kind] = (have + new)[-KEEP:]
+                self._save()
+
+    def _room(self, folder):
+        if self.space(folder) < MIN_FREE:
+            raise DiskFull(f"Paused: this computer is nearly out of space ({folder} has under "
+                           f"{MIN_FREE // 1024**2} MB free). Free some space, then press Resume.")
+
+    def _failed(self, device, item, error):
+        if disk_full(error):
+            raise DiskFull("Paused: this computer ran out of space while copying. Free some space, "
+                           "then press Resume.")
+        if self.offline(error):
+            raise error
+        key = (device, item)
+        self._tries[key] = self._tries.get(key, 0) + 1
+        self._errors.append(f"Couldn't copy {item.rsplit('/', 1)[-1]}: {error}")
+
+    def _pass(self, device, shots, clips, since):
+        """-> (copied, clips still being written, finished without stopping for other work)."""
+        copied = waiting = 0
+        if shots:
+            listing = self.list_shots()["shots"]
+            done = self._synced(device, "shots")
+            self._mark(device, "shots", [s["id"] for s in listing if s.get("saved")])
+            todo = [s["id"] for s in sorted(listing, key=lambda s: s["time"])
+                    if not s.get("saved") and (since is None or (s["time"] >= since and s["id"] not in done))
+                    and self._tries.get((device, s["id"]), 0) < TRIES]
+            for i in range(0, len(todo), BATCH):
+                if self.busy():
+                    return copied, waiting, False
+                self._room(self.shots_folder)
+                batch = todo[i:i + BATCH]
+                try:
+                    self.save_shots(device, batch)
+                except Exception as e:
+                    for item in batch:
+                        self._failed(device, item, e)
+                    continue
+                self._mark(device, "shots", batch)
+                copied += len(batch)
+        if clips:
+            listing = [c for c in self.list_clips()["clips"] if c.get("kind") == "clip"]
+            done = self._synced(device, "clips")
+            self._mark(device, "clips", [c["id"] for c in listing if c.get("saved")])
+            for c in sorted(listing, key=lambda c: c["time"]):
+                if c.get("saved") or self._tries.get((device, c["id"]), 0) >= TRIES:
+                    continue
+                if since is not None and (c["time"] < since or c["id"] in done):
+                    continue
+                if c.get("idle") is None or c["idle"] < SETTLE:
+                    waiting += 1  # still being written: copied on a later look
+                    continue
+                if self.busy():
+                    return copied, waiting, False
+                self._room(self.clips_folder)
+                try:
+                    self.export_clip(device, c["id"])
+                except Exception as e:
+                    self._failed(device, c["id"], e)
+                    continue
+                self._mark(device, "clips", [c["id"]])
+                copied += 1
+        return copied, waiting, True

ui/frame_clips.py

@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""Video from the headset: recordings of what it shows, with its sound, and Steam's own clips.
+
+Two halves share this file.
+
+On the computer, server.py builds the shell commands below, runs them over SSH and
+copies the finished .mp4 to ~/Videos/SteamFrame (Recorder does a recording from Start
+to the copy; export_clip does a Steam clip). Nothing here needs ffmpeg on the computer.
+
+On the Frame, this file runs as `python3 - list` or `python3 - export ID` (sent on
+stdin, like frame_steam.py, so stdlib only): it lists Steam's game recordings and
+stitches one into a single .mp4 with SteamOS's ffmpeg, copying the streams as they are.
+It prints one JSON object, or {"error": ...}.
+
+Steam's game recording keeps DASH segments, one folder per recording session:
+
+    ~/.local/share/Steam/userdata/<account>/gamerecordings/
+        video/bg_<appid>_<YYYYMMDD>_<HHMMSS>/            background recording
+        clips/clip_<appid>_<YYYYMMDD>_<HHMMSS>/video/bg_<appid>_<...>/   a saved clip
+            session.mpd
+            init-stream0.m4s  chunk-stream0-00001.m4s  chunk-stream0-00002.m4s ...
+            init-stream1.m4s  chunk-stream1-00001.m4s ...
+
+Each stream's init segment followed by its chunks, in order, is a fragmented MP4 of
+that stream. The folder names are as users and Steam's own files describe them; the
+listing doesn't depend on them: any folder under clips/ or video/ (up to four levels)
+holding init-stream*.m4s counts as a session.
+"""
+import json
+import os
+import re
+import secrets
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+# ---- where things go ---------------------------------------------------------
+
+VIDEOS_DIR = Path.home() / "Videos" / "SteamFrame"  # on the computer, beside ~/Pictures/SteamFrame
+# On the Frame, relative to its home: recordings in progress and stitched exports.
+# Not /tmp: it's a RAM disk there, and a recording can be over a gigabyte.
+WORK = ".cache/frame-control/video"
+
+# ---- recording what the headset shows ------------------------------------------
+#
+# The same picture the live view streams: SteamVR's copy of the headset view in the
+# v4l2loopback device, encoded with x264 (the hardware encoder crashes ffmpeg). The
+# sound is the monitor of PipeWire's default output, read through its PulseAudio
+# server: SteamOS's ffmpeg has the pulse device (the media player writes to it, see
+# docs/vr-video.md). If it can't be read, the recording goes ahead without sound and
+# says so. Both inputs are stamped with the wall clock: the camera device and the
+# audio server would otherwise count from different clocks.
+
+STREAM_DEVICE = "/dev/video99"
+AUDIO_SOURCE = "@DEFAULT_MONITOR@"  # PulseAudio's name for the default output's monitor
+MAX_SECONDS = 20 * 60
+FPS = 30
+VIDEO_RATE = 8  # Mbit/s at 1080p
+AUDIO_RATE = 160  # kbit/s AAC
+# Room for a full-length recording twice over (the .mkv, then the .mp4 made from it).
+NEED_KB = (VIDEO_RATE * 1000 + AUDIO_RATE) * MAX_SECONDS // 8 * 2 + 512 * 1024
+REC_NAME = re.compile(r"rec-\d{8}-\d{6}")
+
+
+class ClipError(Exception):
+    def __init__(self, message, status=502):
+        super().__init__(message)
+        self.status = status
+
+
+def recording_name(now=None):
+    return time.strftime("rec-%Y%m%d-%H%M%S", time.localtime(now))
+
+
+def probe_command():
+    """Checks before a recording, run on the Frame: prints audio=1 or audio=0.
+
+    One recording runs at a time, so anything left in the folder is from one that was
+    cut off (the app quit, or the copy failed); it's removed to free the space."""
+    return (f"set -u; export XDG_RUNTIME_DIR=${{XDG_RUNTIME_DIR:-/run/user/$(id -u)}}; "
+            f"[ -e {STREAM_DEVICE} ] || {{ echo 'No headset view device ({STREAM_DEVICE}). Is SteamVR running?' >&2; exit 3; }}; "
+            f"command -v ffmpeg >/dev/null || {{ echo 'ffmpeg is missing on the Frame' >&2; exit 3; }}; "
+            f"d=\"$HOME/{WORK}\"; mkdir -p \"$d\" && rm -f \"$d\"/rec-*; "
+            f"free=$(df -Pk \"$d\" | awk 'NR==2 {{print $4}}'); "
+            f"[ \"${{free:-0}}\" -ge {NEED_KB} ] || {{ echo 'Not enough free space on the Frame to record: "
+            f"it needs {NEED_KB // 1024 // 1024 + 1} GB' >&2; exit 4; }}; "
+            f"if timeout 5 ffmpeg -hide_banner -loglevel error -nostdin -f pulse -i {AUDIO_SOURCE} -t 0.2 -f null - "
+            f">/dev/null 2>&1; then echo audio=1; else echo audio=0; fi")
+
+
+def record_command(name, audio, max_seconds=MAX_SECONDS):
+    """The recording, run on the Frame through `bash -c`.
+
+    ffmpeg runs in the background while the shell watches its stdin, which is the SSH
+    channel: when that closes (Stop closed it, or the computer's ssh went away) the
+    shell sends ffmpeg SIGTERM, which makes it finish the file properly (as q or
+    Ctrl-C would; SIGINT itself is ignored by a background job of a script). A recording
+    that ends by itself (the time limit, an error) ends the wait too. The shell prints
+    "started" once ffmpeg is running and "exit N" when it has gone."""
+    if not REC_NAME.fullmatch(name):
+        raise ValueError(f"bad recording name {name!r}")
+    if not 1 <= max_seconds <= MAX_SECONDS:
+        raise ValueError("max_seconds out of range")
+    clock = "-thread_queue_size 1024 -use_wallclock_as_timestamps 1"
+    inputs = f"{clock} -f v4l2 -video_size 1920x1080 -i {STREAM_DEVICE}"
+    maps = "-map 0:v:0"
+    codecs = (f"-vf fps={FPS},scale=-2:1080,format=yuv420p -c:v libx264 -preset ultrafast "
+              f"-b:v {VIDEO_RATE}M -maxrate {VIDEO_RATE}M -bufsize {VIDEO_RATE * 2}M -g {FPS * 2}")
+    if audio:
+        inputs += f" {clock} -f pulse -i {AUDIO_SOURCE}"
+        maps += " -map 1:a:0"
+        codecs += f" -af aresample=async=1 -c:a aac -b:a {AUDIO_RATE}k"
+    script = (f"export XDG_RUNTIME_DIR=${{XDG_RUNTIME_DIR:-/run/user/$(id -u)}}; d=\"$HOME/{WORK}\"; "
+              f"ffmpeg -hide_banner -loglevel error -nostdin -y {inputs} {maps} {codecs} -t {max_seconds} "
+              f"\"$d/{name}.mkv\" </dev/null >/dev/null 2>\"$d/{name}.log\" & p=$!; "
+              f"echo started; "
+              f"while kill -0 $p 2>/dev/null; do read -r -t 1 _; r=$?; [ $r -eq 0 ] || [ $r -gt 128 ] || break; done; "
+              f"kill $p 2>/dev/null; wait $p; echo \"exit $?\"")
+    return "bash -c " + shlex.quote(script)
+
+
+def finish_command(name):
+    """After the recording: make the .mp4 the computer gets (no re-encode), on the Frame."""
+    if not REC_NAME.fullmatch(name):
+        raise ValueError(f"bad recording name {name!r}")
+    return (f"cd \"$HOME/{WORK}\" || exit 1; "
+            f"[ -s {name}.mkv ] || {{ tail -c 2000 {name}.log >&2 2>/dev/null; echo 'The recording is empty' >&2; exit 1; }}; "
+            f"ffmpeg -hide_banner -loglevel error -nostdin -y -i {name}.mkv -map 0 -c copy -movflags +faststart {name}.mp4 "
+            f"&& rm -f {name}.mkv && wc -c < {name}.mp4")
+
+
+def cleanup_command(name):
+    if not REC_NAME.fullmatch(name):
+        raise ValueError(f"bad recording name {name!r}")
+    return f"rm -f \"$HOME/{WORK}/{name}\".*"
+
+
+class Recorder:
+    """One recording at a time, from Start to the .mp4 on this computer.
+
+    The server supplies how to reach the Frame, so this can be tested without one:
+      open_channel(command, stderr) -> Popen of `command` on the Frame, stdin and stdout pipes
+      run(command, timeout) -> its stdout; raises on failure
+      fetch(remote, local) copies a file from the Frame (a path relative to its home)
+      start_thread(fn) starts fn in a thread that counts as headset work
+      release(proc) forgets a channel once it has closed
+    """
+
+    def __init__(self, open_channel, run, fetch, start_thread, release=lambda proc: None, folder=None):
+        self.open_channel, self.run, self.fetch = open_channel, run, fetch
+        self.start_thread, self.release = start_thread, release
+        self.folder = Path(folder) if folder else VIDEOS_DIR
+        self._lock = threading.Lock()
+        self._state = {"state": "idle"}
+        self._proc = None
+
+    def status(self):
+        with self._lock:
+            s = dict(self._state)
+        if s["state"] == "recording":
+            s["elapsed"] = round(time.time() - s["started"], 1)
+        return s
+
+    def start(self):
+        with self._lock:
+            if self._state["state"] in ("starting", "recording", "stopping", "saving"):
+                raise ClipError("Already recording, or still saving the last recording", 409)
+            self._state = {"state": "starting"}
+        try:
+            out = self.run(probe_command(), 30)
+            audio = "audio=1" in out
+            name = recording_name()
+            errors = tempfile.TemporaryFile()
+            proc = self.open_channel(record_command(name, audio), errors)
+            lines = _line_reader(proc.stdout)
+            first = _next_line(lines, 20)
+            if first != "started":
+                _end(proc)
+                errors.seek(0)
+                err = errors.read().decode(errors="replace").strip()
+                errors.close()
+                self.release(proc)
+                raise ClipError(err or "The Frame didn't start recording")
+        except BaseException as e:
+            with self._lock:
+                self._state = {"state": "failed", "error": str(e)}
+            raise
+        with self._lock:
+            self._proc = proc
+            self._state = {"state": "recording", "name": name, "audio": audio, "started": time.time(),
+                           "limit": MAX_SECONDS}
+        try:
+            self.start_thread(lambda: self._watch(proc, name, audio, lines, errors))
+        except BaseException:
+            _end(proc)
+            self.release(proc)
+            with self._lock:
+                self._state, self._proc = {"state": "failed", "error": "Couldn't follow the recording"}, None
+            raise
+        return dict(self.status(), message="Recording" + ("" if audio else
+                    " without sound: the Frame's audio couldn't be read"))
+
+    def stop(self):
+        """Ends the recording; the copy to this computer carries on in the background."""
+        with self._lock:
+            if self._state["state"] != "recording":
+                raise ClipError("Not recording", 409)
+            self._state = dict(self._state, state="stopping")
+            proc = self._proc
+        _close(proc.stdin)  # the shell on the Frame sees EOF and stops ffmpeg
+        return {"state": "stopping", "message": "Stopping the recording…"}
+
+    def _watch(self, proc, name, audio, lines, errors):
+        # Waits for ffmpeg to finish: after Stop, or at the time limit (a margin
+        # past it, so a stuck channel can't hold the recording open forever).
+        deadline = time.time() + MAX_SECONDS + 60
+        while True:
+            stopping = self.status()["state"] == "stopping"
+            line = _next_line(lines, 30 if stopping else 5)
+            if line is None or line.startswith("exit "):
+                break  # ffmpeg has gone and the file is finished
+            if line == "" and (stopping or time.time() > deadline):
+                break  # no answer within 30 s of Stop, or well past the limit: close the channel
+        _end(proc)
+        errors.close()
+        self.release(proc)
+        with self._lock:
+            self._proc = None
+            seconds = round(time.time() - self._state["started"])
+            self._state = dict(self._state, state="saving")
+        try:
+            self.save(name)
+            msg = f"Saved {name}.mp4 to ~/Videos/SteamFrame" + ("" if audio else " (no sound)")
+            state = {"state": "saved", "file": str(self.folder / f"{name}.mp4"), "audio": audio,
+                     "seconds": seconds, "message": msg}
+        except Exception as e:
+            state = {"state": "failed", "error": f"Couldn't save the recording: {e}"}
+        finally:
+            try:
+                self.run(cleanup_command(name), 20)
+            except Exception:
+                pass  # the next recording's checks remove it
+        with self._lock:
+            self._state = state
+
+    def save(self, name):
+        """Make the .mp4 on the Frame and copy it here, never leaving a partial file in the folder."""
+        out = self.run(finish_command(name), 600)
+        size = int(out.strip().splitlines()[-1]) if out.strip() else 0
+        _make_room(self.folder, size)
+        incoming = Path(tempfile.mkdtemp(prefix=".incoming-", dir=self.folder))
+        try:
+            self.fetch(f"{WORK}/{name}.mp4", incoming / f"{name}.mp4")
+            os.replace(incoming / f"{name}.mp4", self.folder / f"{name}.mp4")
+        finally:
+            shutil.rmtree(incoming, ignore_errors=True)
+
+
+def _make_room(folder, size):
+    folder.mkdir(parents=True, exist_ok=True)
+    free = shutil.disk_usage(folder).free
+    if size and free < size + 256 * 1024**2:
+        raise ClipError(f"Not enough free space on this computer: it needs {size // 1024**2 + 256} MB", 507)
+
+
+def _close(f):
+    try:
+        f.close()
+    except OSError:
+        pass
+
+
+def _end(proc):
+    """Close our end of the channel and make sure the local ssh has gone."""
+    _close(proc.stdin)
+    try:
+        proc.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+    _close(proc.stdout)
+
+
+def _line_reader(pipe):
+    """Lines from a pipe via a thread (select() can't wait on pipes on Windows); None at EOF."""
+    import queue
+    lines = queue.Queue()
+
+    def pump():
+        try:
+            for raw in iter(pipe.readline, b""):
+                lines.put(raw.decode(errors="replace").strip())
+        except (OSError, ValueError):
+            pass
+        lines.put(None)
+
+    threading.Thread(target=pump, daemon=True).start()
+    return lines
+
+
+def _next_line(lines, timeout):
+    """The next line, None at EOF, or "" after `timeout` seconds of silence."""
+    import queue
+    try:
+        return lines.get(timeout=timeout)
+    except queue.Empty:
+        return ""
+
+
+# ---- Steam's game recordings ---------------------------------------------------
+
+STEAM_USERDATA = ".local/share/Steam/userdata"
+KINDS = {"clips": "clip", "video": "background"}
+MAX_DEPTH = 4  # folders below clips/ or video/
+PART = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,99}")  # no leading dot, so never "." or ".."
+INIT = re.compile(r"init-stream(\d{1,3})\.m4s")
+CHUNK = re.compile(r"chunk-stream(\d{1,3})-(\d{1,9})\.m4s")
+STAMP = re.compile(r"(?:^|_)(\d{1,10})_(\d{8})_(\d{6})$")
+EXPORT_PATH = re.compile(re.escape(WORK) + r"/export-[0-9a-f]{16}/[A-Za-z0-9_][A-Za-z0-9_.-]{0,99}\.mp4")
+
+
+def parse_id(clip_id):
+    """A recording's id, "<account>/<clips|video>/<folder>[/<folder>...]", as path parts.
+
+    Checked before it goes near a path or a shell: plain names only, no "." or "..",
+    at most MAX_DEPTH folders. Raises ValueError."""
+    parts = clip_id.split("/") if isinstance(clip_id, str) and len(clip_id) <= 600 else []
+    if (len(parts) < 3 or len(parts) > 2 + MAX_DEPTH or not re.fullmatch(r"\d{1,12}", parts[0])
+            or parts[1] not in KINDS or not all(PART.fullmatch(p) for p in parts[2:])):
+        raise ValueError("bad clip id")
+    return parts
+
+
+def export_name(clip_id):
+    """The .mp4's name on the computer: the clip's (or background session's) own folder name."""
+    return parse_id(clip_id)[2] + ".mp4"
+
+
+def read_session(folder):
+    """{stream number: [init, chunk, chunk...]} for one session folder, chunks in number
+    order. A stream without its init segment or without chunks can't be played, so it's left out."""
+    inits, chunks = {}, {}
+    for entry in os.scandir(folder):
+        if not entry.is_file(follow_symlinks=False):
+            continue
+        m = INIT.fullmatch(entry.name)
+        if m:
+            inits[int(m[1])] = entry.path
+            continue
+        m = CHUNK.fullmatch(entry.name)
+        if m:
+            chunks.setdefault(int(m[1]), []).append((int(m[2]), entry.path))
+    return {n: [inits[n], *(p for _, p in sorted(chunks[n]))] for n in sorted(inits) if chunks.get(n)}
+
+
+def chunk_gaps(files):
+    """How many chunk numbers are missing between the first and last (Steam deleted or lost them)."""
+    nums = sorted(int(CHUNK.fullmatch(os.path.basename(f))[2]) for f in files[1:])
+    return nums[-1] - nums[0] + 1 - len(nums) if nums else 0
+
+
+def mpd_duration(text):
+    """Seconds from the manifest's mediaPresentationDuration ("PT1M23.4S"), or None."""
+    m = re.search(r'mediaPresentationDuration="P(?:(\d+)D)?T?(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?"', text or "")
+    if not m or not any(m.groups()):
+        return None
+    d, h, mi, s = m.groups()
+    try:
+        return int(d or 0) * 86400 + int(h or 0) * 3600 + int(mi or 0) * 60 + float(s or 0)
+    except ValueError:
+        return None
+
+
+def _sessions(base, depth=0):
+    """Folders under base (clips/ or video/) that hold init segments, without following links."""
+    try:
+        entries = list(os.scandir(base))
+    except OSError:
+        return
+    if any(e.is_file(follow_symlinks=False) and INIT.fullmatch(e.name) for e in entries):
+        yield base
+        return
+    if depth < MAX_DEPTH:
+        for e in sorted(entries, key=lambda e: e.name):
+            if e.is_dir(follow_symlinks=False) and PART.fullmatch(e.name):
+                yield from _sessions(e.path, depth + 1)
+
+
+def describe(userdata, clip_id):
+    """What the list shows about one recording, or None if it holds nothing playable."""
+    parts = parse_id(clip_id)
+    folder = os.path.join(userdata, parts[0], "gamerecordings", *parts[1:])
+    streams = read_session(folder)
+    if not streams:
+        return None
+    files = [f for s in streams.values() for f in s]
+    stats = [os.stat(f) for f in files]
+    duration = None
+    for mpd in sorted(p for p in os.listdir(folder) if p.endswith(".mpd")):
+        try:
+            duration = mpd_duration(Path(folder, mpd).read_text(errors="replace")[:20000])
+        except OSError:
+            pass
+        if duration is not None:
+            break
+    newest = max(s.st_mtime for s in stats)
+    appid, when = None, newest
+    for p in parts[2:]:
+        m = STAMP.search(p)
+        if m:
+            appid = m[1]
+            try:
+                when = time.mktime(time.strptime(m[2] + m[3], "%Y%m%d%H%M%S"))
+            except ValueError:
+                pass
+            break
+    return {"id": clip_id, "kind": KINDS[parts[1]], "appid": appid, "time": when,
+            "size": sum(s.st_size for s in stats), "streams": len(streams),
+            "chunks": sum(len(s) - 1 for s in streams.values()),
+            "gaps": sum(chunk_gaps(s) for s in streams.values()), "duration": duration,
+            "file": export_name(clip_id),
+            # Seconds since Steam last wrote to it, by the Frame's clock: still recording if small.
+            "idle": round(max(0.0, time.time() - newest), 1)}
+
+
+def list_recordings(userdata):
+    """Every Steam recording session on this Frame, newest first (runs on the Frame)."""
+    found = []
+    try:
+        accounts = sorted(e.name for e in os.scandir(userdata) if e.is_dir(follow_symlinks=False)
+                          and re.fullmatch(r"\d{1,12}", e.name))
+    except OSError:
+        return []
+    for account in accounts:
+        root = os.path.join(userdata, account, "gamerecordings")
+        for kind in KINDS:
+            for folder in _sessions(os.path.join(root, kind)):
+                clip_id = "/".join([account, *os.path.relpath(folder, root).split(os.sep)])
+                try:
+                    info = describe(userdata, clip_id)
+                except (OSError, ValueError):
+                    continue  # changed while we looked, or a name we don't take
+                if info:
+                    found.append(info)
+    found.sort(key=lambda c: c["time"], reverse=True)
+    return found
+
+
+def stitch_command(inputs, out):
+    """ffmpeg that puts each stream file in one .mp4, copying the streams as they are."""
+    cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-nostdin", "-y"]
+    for f in inputs:
+        cmd += ["-i", str(f)]
+    for i in range(len(inputs)):
+        cmd += ["-map", str(i)]
+    return cmd + ["-c", "copy", "-movflags", "+faststart", str(out)]
+
+
+def export(userdata, clip_id, home=None):
+    """Stitch one recording into an .mp4 under WORK (runs on the Frame). -> its path
+    relative to home and its size. The computer copies it, then deletes it with
+    remove_command."""
+    home = Path(home or Path.home())
+    parts = parse_id(clip_id)
+    folder = Path(userdata, parts[0], "gamerecordings", *parts[1:])
+    real = os.path.realpath(folder)
+    if os.path.commonpath([real, os.path.realpath(userdata)]) != os.path.realpath(userdata):
+        raise ValueError("bad clip id")
+    streams = read_session(real)
+    if not streams:
+        raise ClipError("That recording has no complete streams on the Frame", 404)
+    size = sum(os.path.getsize(f) for s in streams.values() for f in s)
+    work = home / WORK
+    work.mkdir(parents=True, exist_ok=True)
+    _sweep(work)
+    # The stream files and the .mp4 made from them are each about the recording's size.
+    if shutil.disk_usage(work).free < size * 2 + 64 * 1024**2:
+        raise ClipError(f"Not enough free space on the Frame to export it: it needs {(size * 2) // 1024**2 + 64} MB", 507)
+    out_dir = work / f"export-{secrets.token_hex(8)}"
+    out_dir.mkdir()
+    try:
+        inputs = []
+        for n, files in streams.items():
+            path = out_dir / f"stream{n}.mp4"
+            with open(path, "wb") as dst:
+                for f in files:
+                    with open(f, "rb") as src:
+                        shutil.copyfileobj(src, dst, 1 << 20)
+            inputs.append(path)
+        out = out_dir / export_name(clip_id)
+        r = subprocess.run(stitch_command(inputs, out), capture_output=True, text=True, errors="replace", timeout=1800)
+        if r.returncode != 0 or not out.exists():
+            raise ClipError("ffmpeg couldn't join the recording: " + (r.stderr.strip()[-1500:] or f"exit {r.returncode}"))
+        for f in inputs:
+            f.unlink()
+    except BaseException:
+        shutil.rmtree(out_dir, ignore_errors=True)
+        raise
+    return {"path": out.relative_to(home).as_posix(), "size": out.stat().st_size}
+
+
+def _sweep(work, older=6 * 3600):
+    """Exports left behind by a copy that never finished."""
+    for d in work.glob("export-*"):
+        try:
+            if time.time() - d.stat().st_mtime > older:
+                shutil.rmtree(d, ignore_errors=True)
+        except OSError:
+            pass
+
+
+def remove_command(path):
+    """Delete an export on the Frame once it's been copied (path as export returned it)."""
+    if not EXPORT_PATH.fullmatch(path or ""):
+        raise ValueError(f"unexpected export path {path!r}")
+    return f"rm -rf \"$HOME\"/{shlex.quote(path.rsplit('/', 1)[0])}"
+
+
+# ---- the computer's side of Steam clips -------------------------------------------
+#
+# run_frame(args, timeout) runs this file on the Frame with `args` and returns its JSON;
+# run(command, timeout) and fetch(remote, local) as for Recorder.
+
+def list_clips(run_frame, folder=None):
+    """Steam's recordings on the Frame, each marked saved if its .mp4 is already here."""
+    folder = Path(folder) if folder else VIDEOS_DIR
+    clips = run_frame(["list"], 60)["clips"]
+    for c in clips:
+        c["saved"] = (folder / export_name(c["id"])).exists()
+    return {"clips": clips, "folder": str(folder)}
+
+
+def export_clip(clip_id, run_frame, run, fetch, folder=None):
+    """Stitch a Steam recording on the Frame and copy the .mp4 here. -> {"message", "file"}."""
+    folder = Path(folder) if folder else VIDEOS_DIR
+    name = export_name(clip_id)  # checks the id before anything reaches the Frame
+    made = run_frame(["export", clip_id], 1900)
+    path = made.get("path")
+    remove = remove_command(path)  # refuses a path that isn't one of our exports
+    try:
+        _make_room(folder, int(made.get("size") or 0))
+        incoming = Path(tempfile.mkdtemp(prefix=".incoming-", dir=folder))
+        try:
+            fetch(path, incoming / name)
+            os.replace(incoming / name, folder / name)
+        finally:
+            shutil.rmtree(incoming, ignore_errors=True)
+    finally:
+        try:
+            run(remove, 30)
+        except Exception:
+            pass  # the next export sweeps it
+    return {"message": f"Saved {name} to ~/Videos/SteamFrame", "file": str(folder / name)}
+
+
+# ---- on the Frame -----------------------------------------------------------------
+
+def main(argv):
+    userdata = Path.home() / STEAM_USERDATA
+    try:
+        if argv[:1] == ["list"]:
+            result = {"clips": list_recordings(userdata)}
+        elif len(argv) == 2 and argv[0] == "export":
+            result = export(userdata, argv[1])
+        else:
+            result = {"error": "usage: frame_clips.py list | export ID"}
+    except (ClipError, ValueError, OSError, subprocess.TimeoutExpired) as e:
+        result = {"error": str(e)}
+    print(json.dumps(result))
+    return 1 if "error" in result else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

ui/frame_devices.py

@@ -558,15 +558,21 @@ class Registry:
         self.config = Path(config) if config else None  # None: ssh_config() at call time
         self.lock = threading.RLock()
         self._depth = 0  # nested _changing() calls
-        self._mtime = None  # devices.json as last loaded or saved
+        self._stamp = None  # devices.json as last loaded or saved
         self.data = {"version": VERSION, "active": None, "devices": [], "networks": {}}
         self.load()
 
     # -- storage --
+    def _file_stamp(self):
+        stat = self.path.stat()
+        # Saves atomically replace the file. Fast consecutive saves can have the
+        # same timestamp and size; its identity still changes in that case.
+        return stat.st_dev, stat.st_ino, stat.st_mtime_ns, stat.st_size
+
     def load(self):
         with self.lock:
             try:
-                self._mtime = self.path.stat().st_mtime_ns
+                self._stamp = self._file_stamp()
                 data = json.loads(self.path.read_text(encoding="utf-8"))
             except (OSError, ValueError):
                 return
@@ -607,14 +613,14 @@ class Registry:
             tmp = self.path.with_name(self.path.name + ".tmp")
             tmp.write_text(json.dumps(self.data, indent=1), encoding="utf-8")
             os.replace(tmp, self.path)
-            self._mtime = self.path.stat().st_mtime_ns
+            self._stamp = self._file_stamp()
 
     def _refresh(self):
         """Pick up what another Frame Control server saved (the app and a standalone
         server can share devices.json)."""
         with self.lock:
             try:
-                if self.path.stat().st_mtime_ns != self._mtime:
+                if self._file_stamp() != self._stamp:
                     self.load()
             except OSError:
                 pass
@@ -740,7 +746,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 +756,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)