Merge main and preserve tracking and Windows test guidance

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

README.md

@@ -189,7 +189,7 @@ entry to `~/.ssh/config` and keys at `~/.ssh/id_ed25519_frame` and
 
 This is a first public test, so reports are really useful, especially from
 Windows and Linux. The quickest way is **Report a problem** in the app (the
-speech-bubble button at the top, or **Help → Report a Problem…**). It adds
+warning-sign 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,6 +223,7 @@ 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 |

docs/agents.md

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

docs/apk-repos.md

@@ -135,88 +135,6 @@ is an error rather than a reason to fall back to `index-v1.jar`. `entry.jar`
 must be signed with SHA-2 (SHA-1 is still accepted for legacy `index-v1.jar`).
 Removing a repository clears its state.
 
-## My itch.io purchases
-
-The store can also install the Android (Quest) builds of games you **own** on
-itch.io: bought, claimed free, from a bundle or a gift. It is opt-in. In the
-store, open the sources dialog and use **My itch.io purchases**: create an API
-key on itch.io (account settings › API keys) and paste it there. Frame Control
-checks it with itch.io (`GET /profile`) before saving it; a wrong or revoked key
-is reported and nothing is saved. Once connected, a source called
-**itch.io (my purchases)** appears, and its games are marked **Owned on
-itch.io** instead of Free. **Disconnect itch.io** deletes the key file.
-
-How it works, using the documented
-[server-side API](https://itch.io/docs/api/serverside) with
-`Authorization: Bearer <key>`:
-
-- `GET https://api.itch.io/profile/owned-keys` lists your download keys, page by
-  page until an empty page (500 per page, at most 40 pages). Games whose
-  `traits` don't include `p_android` are left out; one entry per game, with the
-  newest key.
-- Opening a game asks `GET /games/<game_id>/uploads?download_key_id=<key id>`
-  for its files. Android uploads are those marked `p_android` (in `traits`, or
-  as a `p_android`/`platforms.android` flag) or named `.apk`. `.apk` files come
-  first, then full games before demos, newest first. Soundtracks, pre-orders and
-  externally hosted files are skipped.
-- Installing asks `GET /uploads/<upload_id>/download?download_key_id=<key id>`.
-  The answer accepted is a redirect to itch.io's storage host, a JSON body
-  with a `url` field naming it, or the file itself. Frame Control follows the
-  first two without the key, to HTTPS on port 443 only, and only to host names
-  whose every address is public. For IPv4 that means outside every special
-  block (`0/8`, `10/8`, `100.64/10`, `127/8`, `169.254/16`, `172.16/12`,
-  `192.0.0/24`, `192.0.2/24`, `192.88.99/24`, `192.168/16`, `198.18/15`,
-  `198.51.100/24`, `203.0.113/24`, `224/4`, `240/4`), however written. IPv6 is
-  an allow-list: global unicast (`2000::/3`) only, minus 6to4, Teredo,
-  documentation, ORCHID and benchmarking blocks, so mapped or NAT64 IPv4,
-  site-local, unique-local and the rest are all refused. It connects only to
-  the addresses it checked, trying each in turn within one 20-second budget
-  for connecting and the TLS handshake, and checks again on each further
-  redirect. A storage URL, first or after any redirect, that contains the API
-  key (or 8+ characters of it, in any case, plain or percent-encoded) or an
-  `api_key` parameter is refused before it is looked up, so the key never
-  reaches the storage server. The APK then takes
-  the normal install path, with the same ABI, OpenXR layer and Meta-services
-  checks and warnings as any other store download.
-
-The key is stored in `frame_host.data_dir('itch-account.json')`
-(`~/Library/Application Support/Frame Control/itch-account.json` on macOS),
-written through a new 0600 temporary file and moved into place. It is only
-sent to `https://api.itch.io`, in the `Authorization` header, never in a URL;
-Frame Control does not follow api.itch.io's redirects with it. The key, or any
-part of it from 8 characters, never appears in the page, API responses, errors
-or logs; the page clears the field as soon as it is sent. A disconnect made
-while a key is still being checked wins: that key is not saved.
-Owned-game lists are kept in memory for ten minutes and never written to the
-disk cache.
-
-When api.itch.io answers 401 or 403, Frame Control asks `GET /profile` with the
-same key. If that is refused too (or itch.io says "invalid key"), the key is
-deleted and the store says to connect again; otherwise only that game or
-download is refused, and the key stays. Rate limits (429) and network errors
-only fail that source's results, with a readable message. A storage host's
-refusal is reported as a download error, not as a rate limit.
-
-### What is verified and what isn't
-
-Not tested against a live itch.io account at all: everything below was tested
-with recorded and hand-made responses (`tests/test_itch_purchases.py`) only.
-
-| Part | Status |
-|---|---|
-| Bearer key, `GET /profile`, `/profile/owned-keys` paging and its fields, the `errors` array | Documented in the public reference (checked 2026-10-13) |
-| `GET /games/<id>/uploads` and `download_key_id` | Not in the public reference; paths and parameter from itch.io's app client, [go-itchio](https://github.com/itchio/go-itchio) |
-| Upload fields (`filename`, `display_name`, `size`, `storage`, `type`, `traits`, `updated_at`, `demo`, `preorder`) | Assumed from go-itchio and the API's snake_case convention |
-| The `p_android` trait, on games and uploads | Assumed from itch.io's `p_windows`/`p_linux`/`p_osx` naming |
-| What `/uploads/<id>/download` returns | Unknown: go-itchio only builds the URL and hands it to a downloader, so a redirect, a JSON `url` and the file are all accepted |
-| Whether that endpoint accepts the key as a Bearer header | Unknown: go-itchio puts it in the query string, which Frame Control refuses to do |
-| itch.io's storage host names and addresses | Unknown; any public HTTPS host is allowed |
-
-Limits: a game whose page doesn't mark Android, or whose Android build is
-inside a `.zip`, won't install. Android builds have no version codes on
-itch.io, so only the newest upload can be installed. Owning a game doesn't make
-it run on the Frame: Quest builds that need Meta's platform services won't.
-
 ## Publish your own repository
 
 Only publish free APKs you own or have the developer's permission to distribute.

docs/apk-sources.md

@@ -73,8 +73,6 @@ does not suppress the other at the aggregator level. Queries filter the current
 feed window locally: this is not an exhaustive historical itch search. Only
 explicit zero-price Android entries are returned. Covers are exposed in
 `images`; absent screenshots, APK version, ABI and minimum SDK stay unknown.
-Games the user owns on itch.io are a separate, opt-in source that downloads
-through their own API key: see [My itch.io purchases](apk-repos.md#my-itchio-purchases).
 Curated GitHub entries include publisher artwork and plain-language summaries.
 Repository image URLs are pinned to inspected commits. Open Brush screenshots
 come from its README-linked Steam listing; SuperTux uses the upstream gameplay

docs/devices.md

@@ -3,9 +3,8 @@
 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. 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.
+tab (key 5) lists them, and the connection pill in the header shows what the
+app is doing to reach the one in use, step by step, as it happens.
 
 The code is in three modules, all stdlib-only Python on your computer:
 
@@ -58,7 +57,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, or in the pill's dialog) breaks ties. The best-ranked address that answers
+Your order on the Devices tab breaks ties. The best-ranked address that answers
 wins; one that answers first waits up to 0.35 s for a better-ranked one that is
 still trying. If SSH to the winner fails in a way another address could fix
 (a different device answered there, or the link dropped), the next one that
@@ -73,16 +72,6 @@ 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/family-comfort.md

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

docs/frame-control.md

@@ -17,21 +17,15 @@ python3 ui/server.py         # anywhere: then open http://127.0.0.1:47810
 
 ## Features
 
-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. 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
+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
 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.
@@ -245,5 +239,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. Settings → Open assistant settings opens the page; the linked guide
+operate the headset. Tools → Open assistant opens the page; the linked guide
 covers putting it in a Chromium panel on the Frame.

docs/how-the-frame-works.md

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

@@ -114,8 +114,8 @@ don't.
 
 ## Family and comfort
 
-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
+The shared Home card sets session limits, breaks and check-ins, and offers
+**Cast headset view**. **Enable / test notifications** requests iOS notification
 permission and sends a local test. These are local notifications, not APNs push;
 iOS background suspension can interrupt phone alerts. The headset timer still
 runs. See [the behavior and verification limits](family-comfort.md).

docs/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 performance (unfold it) → Open HUD in
+- **Our performance HUD:** Home → VR comfort and performance → Open HUD in
   headset creates its own gamescope panel using built-in tools. It needs no
   third-party overlay app. [Metrics and verification](vr-utilities.md).
 

docs/privacy.md

@@ -132,8 +132,8 @@ runs.
 
 ## Report a problem
 
-**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
+**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
 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

docs/sidequest.md

@@ -65,8 +65,6 @@ 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;

docs/testing.md

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

@@ -0,0 +1,329 @@
+# 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 **Settings → Library artwork**, or
+Set the optional free key in Frame Control's **Library artwork settings**, or
 `STEAMGRIDDB_API_KEY` (`FRAME_STEAMGRIDDB_API_KEY` also works). Environment
 settings override the saved key. Without a key there are no provider calls or
 warnings. Saved keys stay in host app data, mode 0600 on POSIX, and are never

docs/vr-utilities.md

@@ -11,7 +11,7 @@ checks below. The PR stays draft.
 
 ## Our performance HUD
 
-On **Home → VR performance** (folded until you open it), the app shows a timestamped sample
+On **Home → VR comfort and performance**, the app shows a timestamped sample
 with each status refresh (30 seconds, or Refresh). **Open HUD in headset**
 starts our text HUD as a gamescope panel, refreshed every two seconds. In the
 SteamVR dashboard, select **Frame Control HUD**, then Float in World or dock
@@ -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`. In the headset HUD only: the app shows them once, in the battery menu at the top. |
+| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. |
 
 OpenVR uses background application mode, which does not start SteamVR or keep
 it running. This mode also returned live timing in a read-only device probe.

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 player** (or **Play a video or photo** on Home), send a file, choose its layout and press
+In **Tools → Media in the headset**, 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

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

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

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

scripts/heart-check.py

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

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

@@ -0,0 +1,60 @@
+#!/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/control_center.cjs

@@ -64,7 +64,7 @@ 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(){},closeDevPop(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
+      resetShots(){},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 = {};
@@ -443,20 +443,20 @@ test('every linked workflow selects its real page and section, preserving shortc
   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','settings'].map(page=>({dataset:{page},classList:{toggle(key,on){if(on)activePage=page;}}}));
+  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,classList:{toggle(){}},scrollIntoView(){scrolled=id;}});
+      if(!sections.has(id))sections.set(id,{hidden:false,scrollIntoView(){scrolled=id;}});
       return sections.get(id);
-    },live:false,toggleLive(){},scrollToY(){},loadMacView(){},loadPanelSwitcher(){}};
+    },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)+'\n'+html.match(/^PAGES\.push\([^\n]+/m)[0],context);
+  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:'settings',privacy:'settings',panels:'tools',macview:'tools',devices:'devices'};
+    power:'tools',transfer:'tools',media:'tools',apps:'tools',artworkSettings:'tools',privacy:'tools',panels:'tools',macview:'tools',devices:'devices'};
   for(const item of cc.catalog) for(const [href] of item.links||[]) {
     if(!href.startsWith('#')||href==='#connection')continue;
     const id=href.slice(1);assert.ok(ids.has(id)||['android','devices'].includes(id),href);
@@ -468,5 +468,4 @@ test('every linked workflow selects its real page and section, preserving shortc
   }
   assert.equal(vm.runInContext('PAGES[4]',context),'devices');
   assert.equal(vm.runInContext('PAGES[5]',context),'control');
-  assert.equal(vm.runInContext('PAGES[6]',context),'settings');
 });

tests/fixtures/itch_account/README.md

@@ -1,5 +0,0 @@
-Hand-made itch.io API responses for tests/test_itch_purchases.py; no real account or
-network was used. owned-keys-*.json follow the documented /profile/owned-keys sample
-(https://itch.io/docs/api/serverside). uploads.json follows the shape the itch.io app's
-client library (github.com/itchio/go-itchio) reads from /games/ID/uploads, with the
-`traits` array it handles; `p_android` there is assumed, not documented.

tests/fixtures/itch_account/owned-keys-1.json

@@ -1,22 +0,0 @@
-{
- "page": 1,
- "per_page": 500,
- "owned_keys": [
-  {"id": 9001, "game_id": 341190, "purchase_id": 3923754, "downloads": 6,
-   "created_at": "2026-03-10T23:46:36Z", "updated_at": "2026-03-10T23:46:36Z",
-   "game": {"id": 341190, "title": "Orbit Garden VR", "url": "https://maker.itch.io/orbit-garden",
-            "cover_url": "https://img.itch.zone/aW1nLzE2OTA3NTIuanBn/315x250%23c/Ihj7Wa.jpg",
-            "short_text": "Grow plants in zero gravity.", "type": "default", "classification": "game",
-            "min_price": 1299, "traits": ["p_windows", "p_android", "can_be_bought"],
-            "created_at": "2025-12-04T16:18:04Z", "published_at": "2026-01-03T17:28:47Z",
-            "user": {"id": 46531, "username": "maker", "display_name": "Maker Studio",
-                     "url": "https://maker.itch.io"}}},
-  {"id": 9002, "game_id": 3, "purchase_id": null, "downloads": 0,
-   "created_at": "2026-02-01T10:00:00Z", "updated_at": "2026-02-01T10:00:00Z",
-   "game": {"id": 3, "title": "Desk Only", "url": "https://leafo.itch.io/x-moon",
-            "cover_url": "https://img.itch.zone/aW1hZ2UvMy8xODM3LnBuZw==/315x250%23/y2uYQI.png",
-            "type": "default", "classification": "game", "min_price": 0,
-            "traits": ["p_windows", "p_linux", "p_osx"], "published_at": "2013-03-03T23:02:14Z",
-            "user": {"id": 1, "username": "leafo", "display_name": "leafo", "url": "https://leafo.itch.io"}}}
- ]
-}

tests/fixtures/itch_account/owned-keys-2.json

@@ -1,19 +0,0 @@
-{
- "page": 2,
- "per_page": 500,
- "owned_keys": [
-  {"id": 8001, "game_id": 341190, "purchase_id": null, "downloads": 1,
-   "created_at": "2025-06-01T10:00:00Z", "updated_at": "2025-06-01T10:00:00Z",
-   "game": {"id": 341190, "title": "Orbit Garden VR", "url": "https://maker.itch.io/orbit-garden",
-            "type": "default", "classification": "game", "min_price": 1299,
-            "traits": ["p_windows", "p_android", "can_be_bought"],
-            "user": {"id": 46531, "username": "maker", "display_name": "Maker Studio"}}},
-  {"id": 8002, "game_id": 77, "purchase_id": null, "downloads": 2,
-   "created_at": "2025-05-01T10:00:00Z", "updated_at": "2025-05-01T10:00:00Z",
-   "game": {"id": 77, "title": "Free Quest Toy", "url": "https://toys.itch.io/quest-toy",
-            "cover_url": "http://img.example/not-itch.png",
-            "type": "default", "classification": "game", "min_price": 0,
-            "traits": ["p_android"], "published_at": "2025-04-01T00:00:00Z",
-            "user": {"id": 5, "username": "toys"}}}
- ]
-}

tests/fixtures/itch_account/uploads.json

@@ -1,28 +0,0 @@
-{
- "uploads": [
-  {"id": 501, "game_id": 341190, "filename": "OrbitGarden-win64.zip", "display_name": "Windows",
-   "size": 734003200, "storage": "hosted", "type": "default", "traits": ["p_windows"],
-   "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-04-02T10:00:00Z"},
-  {"id": 502, "game_id": 341190, "filename": "OrbitGarden-Quest-old.apk", "display_name": "Quest 1.0",
-   "size": 104857600, "storage": "hosted", "type": "default", "traits": ["p_android"],
-   "created_at": "2026-01-01T10:00:00Z", "updated_at": "2026-01-05T10:00:00Z"},
-  {"id": 503, "game_id": 341190, "filename": "OrbitGarden-Quest.apk", "display_name": "Quest 1.2",
-   "size": 115343360, "storage": "hosted", "type": "default", "traits": ["p_android"],
-   "created_at": "2026-04-01T10:00:00Z", "updated_at": "2026-04-03T10:00:00Z"},
-  {"id": 504, "game_id": 341190, "filename": "OrbitGarden-demo.apk", "display_name": "Quest demo",
-   "size": 52428800, "storage": "hosted", "type": "default", "traits": ["p_android", "demo"],
-   "created_at": "2026-05-01T10:00:00Z", "updated_at": "2026-05-01T10:00:00Z"},
-  {"id": 505, "game_id": 341190, "filename": "OrbitGarden-android-bundle.zip", "display_name": "Android (zip)",
-   "size": 120000000, "storage": "hosted", "type": "default", "traits": ["p_android"],
-   "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z"},
-  {"id": 506, "game_id": 341190, "filename": "Soundtrack.apk", "display_name": "Soundtrack",
-   "size": 1000, "storage": "hosted", "type": "soundtrack", "traits": [],
-   "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z"},
-  {"id": 507, "game_id": 341190, "filename": "mirror.apk", "display_name": "Mirror",
-   "size": 1000, "storage": "external", "host": "example.com", "type": "default", "traits": ["p_android"],
-   "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z"},
-  {"id": 508, "game_id": 341190, "filename": "OrbitGarden-mac.dmg", "display_name": "macOS",
-   "size": 1000, "storage": "hosted", "type": "default", "traits": ["p_osx"],
-   "created_at": "2026-06-01T10:00:00Z", "updated_at": "2026-06-01T10:00:00Z"}
- ]
-}

tests/page/store_detail.mjs

@@ -19,8 +19,8 @@ function grab(name) {
   fail(`unbalanced ${name}`);
 }
 const names = ["esc", "storeName", "storeHue", "storeInitial", "storeText", "storeOpenSource", "sourcePage", "storeImage",
-               "GLYPH_VR", "GLYPH_APP", "RUNS", "storeRuns", "storeKind", "storeArt", "storeIcon", "sourceMark", "storePrice", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
-               "updateInstall", "openStoreApp", "loadOfferDetails", "installStoreApp"];
+               "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
+               "updateInstall", "openStoreApp", "loadOfferDetails"];
 const code = names.map(grab).join("");
 
 // A fake page: elements by id. The install panel's elements exist only while
@@ -34,10 +34,8 @@ function page(api = async () => ({})) {
   const document = { activeElement: null, querySelector: () => null };
   const console = { error() {} };
   const calls = [];
-  const fns = new Function("$", "sourceState", "document", "console", "api", "runJob", "loadAndroid", "act", "window", code + "; return { renderAppDetail, openStoreApp };")(
-    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); },
-    async (title, key, work) => work(), () => {}, async (title, work) => work(),
-    { open() { fail("an in-app installation opened an external page"); } });
+  const fns = new Function("$", "sourceState", "document", "console", "api", code + "; return { renderAppDetail, openStoreApp };")(
+    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); });
   return { els, sourceState, calls, ...fns };
 }
 
@@ -56,17 +54,6 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
   if (html.includes('role="alert"')) fail("a good listing showed the error state");
 }
 
-// A game the user owns on itch.io says so instead of "Free".
-{
-  const p = page();
-  p.sourceState.detail = { app: { name: "Orbit Garden", offers: [{ ...offer, source: "itch-owned", source_name: "itch.io (my purchases)",
-                                                                    owned: true, owned_label: "Owned on itch.io", free: false }] }, choice: 0 };
-  if (p.renderAppDetail() !== true) fail("an owned listing reported a render failure");
-  const html = p.els.detailBody.innerHTML;
-  if (!html.includes('<div class="detail-price">Owned on itch.io</div>')) fail("owned listing has no Owned on itch.io label");
-  if (html.includes("No purchase needed")) fail("owned listing claims no purchase is needed");
-}
-
 // A listing that can't render (no offer to show) gets a clear message, not an empty dialog.
 {
   const p = page();
@@ -81,7 +68,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, true);
+  await p.openStoreApp(0);
   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");
 }
@@ -103,18 +90,4 @@ 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/test_comfort_ui.py

@@ -56,48 +56,6 @@ 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_devices.py

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

tests/test_itch_purchases.py

@@ -1,862 +0,0 @@
-"""My itch.io purchases: the account key, owned games and their Android downloads.
-
-Offline: a fake HTTPS layer under urllib's real opener (so redirects and header
-handling are the real ones) serves the recorded JSON in fixtures/itch_account.
-"""
-import sandbox  # noqa: F401  (first: keeps tests off real data and services)
-import contextlib, email.message, http.client, io, ipaddress, json, os, socket, sys, tempfile, threading, time
-import unittest
-import urllib.error, urllib.parse, urllib.request, zipfile
-from pathlib import Path
-from unittest.mock import patch
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
-from apk_sources import SourceError, SourceLimited, _itch_account as account, _web, itch, search
-import server
-
-FIX = Path(__file__).parent / 'fixtures' / 'itch_account'
-KEY = 'TESTKEYabcdefghijklmnopqrstuvwxyz0123456789'
-OTHER = 'OTHERKEY0123456789abcdefghijklmnopqrstuv'
-
-
-def apk_bytes():
-    out = io.BytesIO()
-    with zipfile.ZipFile(out, 'w') as z:
-        z.writestr('AndroidManifest.xml', b'\x03\x00\x08\x00')
-        z.writestr('classes.dex', b'dex\n035\x00')
-    return out.getvalue()
-
-
-class Reply(io.BytesIO):
-    """Just enough of http.client.HTTPResponse for urllib's handlers."""
-
-    def __init__(self, url, code=200, body=b'', headers=None):
-        super().__init__(body if isinstance(body, bytes) else json.dumps(body).encode())
-        self.url, self.code, self.status, self.msg, self.reason = url, code, code, 'fake', 'fake'
-        self.headers = email.message.Message()
-        for k, v in (headers or {}).items():
-            self.headers[k] = v
-
-    def info(self):
-        return self.headers
-
-    def geturl(self):
-        return self.url
-
-    def getcode(self):
-        return self.code
-
-    def getheader(self, name, default=None):
-        return self.headers.get(name, default)
-
-
-class FakeConnection:
-    """_web._connect's http.client connection, answered from the same routes."""
-
-    def __init__(self, web, host):
-        self.web, self.host, self.reply = web, host, None
-
-    def request(self, method, path, headers=None):
-        req = urllib.request.Request('https://' + self.host + path, headers=headers or {})
-        self.reply = self.web(None, req)
-
-    def getresponse(self):
-        return self.reply
-
-    def close(self):
-        pass
-
-
-# What the fake resolver answers: the storage host is public; the rest are traps.
-ADDRESSES = {'storage.itch-cdn.example': '151.101.1.1', 'other-cdn.example': '151.101.2.2',
-             'localhost.': '127.0.0.1', 'frame.local': '192.168.1.20', '127.0.0x0.1': '127.0.0.1',
-             'intranet.example': '10.0.0.5', 'mapped.example': '::ffff:127.0.0.1', 'cgnat.example': '100.64.0.1',
-             'mixed.example': ('151.101.1.1', '10.0.0.5'), 'dual.example': ('2a04:4e42::81', '151.101.1.1'),
-             'nat64.example': '64:ff9b:1::a00:1', 'sitelocal.example': 'fec0::1',
-             'many.example': tuple('151.101.%d.1' % n for n in range(1, 9))}
-REAL_CONNECT = _web._connect
-
-
-class FakeItch:
-    """Routes https requests by host and path; records every request with its headers."""
-
-    def __init__(self):
-        self.calls, self.routes = [], {}
-
-    def route(self, host_path, reply):
-        self.routes[host_path] = reply
-
-    def __call__(self, handler, req):
-        url = urllib.parse.urlsplit(req.full_url)
-        headers = {k.lower(): v for k, v in req.header_items()}
-        self.calls.append((req.full_url, headers))
-        reply = self.routes.get(url.hostname + url.path)
-        if reply is None:
-            return Reply(req.full_url, 404, {'errors': ['not found']})
-        if callable(reply):
-            reply = reply(req, urllib.parse.parse_qs(url.query))
-        if isinstance(reply, Exception):
-            raise reply
-        if isinstance(reply, Reply):
-            return reply
-        return Reply(req.full_url, 200, reply)
-
-    def urls(self, host_path):
-        return [u for u, _ in self.calls if urllib.parse.urlsplit(u).hostname + urllib.parse.urlsplit(u).path == host_path]
-
-
-def owned_pages(req, query):
-    page = query['page'][0]
-    return {'1': json.loads((FIX / 'owned-keys-1.json').read_text()),
-            '2': json.loads((FIX / 'owned-keys-2.json').read_text())}.get(page, {'page': int(page), 'owned_keys': []})
-
-
-class ItchPurchases(unittest.TestCase):
-    def setUp(self):
-        self.tmp = tempfile.TemporaryDirectory()
-        self.addCleanup(self.tmp.cleanup)
-        root = Path(self.tmp.name)
-        for target, value in [(account.frame_host, 'data_dir'), (search.frame_host, 'data_dir')]:
-            p = patch.object(target, value, lambda *parts: root.joinpath('data', *parts))
-            p.start()
-            self.addCleanup(p.stop)
-        (root / 'cache').mkdir()
-        for p in (patch.object(_web, 'cache', return_value=str(root / 'cache')),
-                  patch.object(_web.frame_host, 'cache_dir', lambda *parts: root.joinpath('cache', *parts))):
-            p.start()
-            self.addCleanup(p.stop)
-        self.web = FakeItch()
-        self.web.route('api.itch.io/profile', {'user': {'username': 'player', 'id': 1}})
-        self.web.route('api.itch.io/profile/owned-keys', owned_pages)
-        self.web.route('api.itch.io/games/341190/uploads', json.loads((FIX / 'uploads.json').read_text()))
-        p = patch('urllib.request.HTTPSHandler.https_open', autospec=True, side_effect=self.web)
-        p.start()
-        self.addCleanup(p.stop)
-        p = patch('urllib.request.HTTPHandler.http_open', side_effect=AssertionError('plain HTTP in test'))
-        p.start()
-        self.addCleanup(p.stop)
-        real_lookup = _web.socket.getaddrinfo
-
-        def lookup(host, port, *args, **kwargs):
-            if host not in ADDRESSES:
-                try:
-                    ipaddress.ip_address(host)  # IP literals (and the in-process test server) need no DNS
-                    return real_lookup(host, port, *args, **kwargs)
-                except ValueError:
-                    pass
-                if host == 'localhost':
-                    return real_lookup(host, port, *args, **kwargs)
-                raise _web.socket.gaierror('unknown test host ' + host)
-            found = ADDRESSES[host]
-            return [(10 if ':' in a else 2, 1, 6, '', (a, port)) for a in ([found] if isinstance(found, str) else found)]
-        self.connected, self.unreachable = [], set()
-
-        def connect(host, address, timeout, deadline):
-            self.connected.append((host, address))
-            if address[0] in self.unreachable:
-                raise OSError('Network is unreachable')
-            self.assertLessEqual(deadline - time.monotonic(), _web.CONNECT_BUDGET)
-            return FakeConnection(self.web, host)
-        for p in (patch.object(_web.socket, 'getaddrinfo', lookup), patch.object(_web, '_connect', connect)):
-            p.start()
-            self.addCleanup(p.stop)
-        account._forget()
-        self.addCleanup(account._forget)
-        _web._limited.clear()
-        self.addCleanup(_web._limited.clear)
-        search._status.clear()
-
-    def owned_source(self):
-        return next(s for s in itch.sources() if s['id'] == itch.OWNED)
-
-    def connect(self):
-        self.assertTrue(account.connect(KEY)['itch']['connected'])
-
-    # -- the key ---------------------------------------------------------------
-
-    def test_connect_checks_the_key_then_saves_it_0600(self):
-        result = account.connect('  ' + KEY + '\n')
-        self.assertEqual(result['message'], 'Connected to itch.io as player')
-        self.assertEqual(result['itch'], {'connected': True, 'username': 'player'})
-        self.assertNotIn(KEY, json.dumps(result))
-        url, headers = self.web.calls[0]
-        self.assertEqual(url, 'https://api.itch.io/profile')
-        self.assertEqual(headers['authorization'], 'Bearer ' + KEY)
-        self.assertEqual(json.loads(account.path().read_text())['key'], KEY)
-        if os.name == 'posix':
-            self.assertEqual(os.stat(account.path()).st_mode & 0o777, 0o600)
-        self.assertEqual([p.name for p in account.path().parent.iterdir()], ['itch-account.json'])  # no .tmp left
-        self.assertNotIn(KEY, json.dumps(account.status()))
-
-    def test_reconnecting_rewrites_the_file_0600_even_if_it_was_wider(self):
-        self.connect()
-        os.chmod(account.path(), 0o644)
-        account.connect(OTHER)
-        self.assertEqual(json.loads(account.path().read_text())['key'], OTHER)
-        if os.name == 'posix':
-            self.assertEqual(os.stat(account.path()).st_mode & 0o777, 0o600)
-
-    def test_bad_or_revoked_key_stays_disconnected(self):
-        for reply in (Reply('https://api.itch.io/profile', 401, {'errors': ['invalid key']}),
-                      Reply('https://api.itch.io/profile', 403, b'Forbidden'),
-                      {'errors': ['invalid key']}):
-            self.web.route('api.itch.io/profile', reply)
-            with self.assertRaisesRegex(account.BadKey, 'did not accept the API key') as caught:
-                account.connect(KEY)
-            self.assertNotIn(KEY, str(caught.exception))
-            self.assertFalse(account.path().exists())
-            self.assertEqual(account.status(), {'connected': False, 'username': None})
-            self.assertEqual([s['id'] for s in itch.sources()], ['itch', 'itch-quest'])
-        with self.assertRaisesRegex(account.BadKey, 'does not look like'):
-            account.connect('short')
-        with self.assertRaisesRegex(account.BadKey, 'does not look like'):
-            account.connect(KEY + '\r\nX-Injected: 1')
-        self.assertEqual(len(self.web.calls), 3)  # malformed keys never reach itch.io
-
-    def test_a_refused_request_with_a_working_key_keeps_the_key(self):
-        self.connect()
-        self.web.route('api.itch.io/games/341190/uploads', Reply('https://api.itch.io/games/341190/uploads', 403, b''))
-        with self.assertRaisesRegex(SourceError, r'refused this request \(HTTP 403\)') as caught:
-            itch.details(self.owned_source(), '341190')
-        self.assertNotIsInstance(caught.exception, account.BadKey)
-        self.assertTrue(account.connected())
-
-    def test_a_key_revoked_later_is_removed_with_a_clear_message(self):
-        self.connect()
-        self.web.route('api.itch.io/profile/owned-keys', Reply('https://api.itch.io/profile/owned-keys', 401, b''))
-        self.web.route('api.itch.io/profile', Reply('https://api.itch.io/profile', 401, b''))
-        with self.assertRaisesRegex(account.BadKey, 'no longer accepts the saved API key'):
-            itch.search(self.owned_source(), '')
-        self.assertFalse(account.path().exists())
-        self.assertNotIn(itch.OWNED, [s['id'] for s in itch.sources()])
-
-    def test_disconnect_deletes_the_key_file(self):
-        self.connect()
-        self.assertIn(itch.OWNED, [s['id'] for s in itch.sources()])
-        result = account.disconnect()
-        self.assertFalse(account.path().exists())
-        self.assertEqual(result['itch'], {'connected': False, 'username': None})
-        self.assertNotIn(itch.OWNED, [s['id'] for s in itch.sources()])
-        with self.assertRaisesRegex(SourceError, 'Connect your itch.io account first'):
-            account.owned_keys()
-        account.disconnect()  # already gone: fine
-
-    # -- owned games -------------------------------------------------------------
-
-    def test_owned_keys_follow_pages_until_an_empty_one(self):
-        self.connect()
-        keys = account.owned_keys()
-        self.assertEqual([k['id'] for k in keys], [9001, 9002, 8001, 8002])
-        pages = self.web.urls('api.itch.io/profile/owned-keys')
-        self.assertEqual([urllib.parse.parse_qs(urllib.parse.urlsplit(u).query) for u in pages],
-                         [{'page': [str(n)], 'per_page': ['500']} for n in (1, 2, 3)])
-        self.assertTrue(all('Bearer ' + KEY == h['authorization'] for _, h in self.web.calls))
-        self.assertTrue(all(KEY not in u for u, _ in self.web.calls))
-        account.owned_keys()  # cached in memory, not on disk
-        self.assertEqual(len(self.web.urls('api.itch.io/profile/owned-keys')), 3)
-        self.assertFalse(any(KEY in p.read_text(errors='ignore') or b'Orbit' in p.read_bytes()
-                             for p in Path(_web.cache()).iterdir()))
-
-    def test_page_cap_stops_a_server_that_never_ends(self):
-        self.connect()
-        self.web.route('api.itch.io/profile/owned-keys', lambda req, q: {'owned_keys': [{'id': int(q['page'][0])}]})
-        with patch.object(account, 'PAGES', 3):
-            self.assertEqual(len(account.owned_keys()), 3)
-
-    def test_search_lists_owned_android_games_labelled(self):
-        self.connect()
-        entries = itch.search(self.owned_source(), '')
-        self.assertEqual([(e['id'], e['name']) for e in entries], [('341190', 'Orbit Garden VR'), ('77', 'Free Quest Toy')])
-        orbit, toy = entries
-        self.assertEqual(orbit['download_key_id'], 9001)  # the newest key for a game owned twice
-        self.assertTrue(orbit['owned'])
-        self.assertEqual(orbit['owned_label'], 'Owned on itch.io')
-        self.assertFalse(orbit['free'])
-        self.assertTrue(toy['free'])
-        self.assertIsNone(toy['icon'])  # not an itch.io image host
-        self.assertEqual(orbit['page'], 'https://maker.itch.io/orbit-garden')
-        self.assertEqual(itch.search(self.owned_source(), 'zero gravity')[0]['id'], '341190')
-        # Through the store's search, owned (paid) games pass the free-only filter.
-        result = search.search('orbit', source=itch.OWNED)
-        self.assertEqual(result['sources'][0]['status'], 'ok')
-        offer = result['apps'][0]['offers'][0]
-        self.assertEqual((offer['source'], offer['source_name'], offer['owned_label']),
-                         (itch.OWNED, 'itch.io (my purchases)', 'Owned on itch.io'))
-        self.assertNotIn(KEY, json.dumps(result))
-
-    def test_owned_games_show_under_either_vr_choice(self):
-        # itch.io doesn't say which purchases are VR, so neither filter hides them; other
-        # games of unknown kind still count as flat.
-        self.connect()
-        both = ['Free Quest Toy', 'Orbit Garden VR']
-        for vr in (True, False):
-            names = sorted(a['name'] for a in search.search('', vr=vr, source=itch.OWNED)['apps'])
-            self.assertEqual(names, both)
-        flat = {'source': 'x', 'id': '1', 'name': 'Flat', 'summary': '', 'vr': None}
-        self.assertEqual(search.group([flat], vr=True), [])
-        self.assertEqual(len(search.group([flat], vr=False)), 1)
-        self.assertEqual(search.group([dict(flat, owned=True, vr=False)], vr=True), [])
-
-    def test_only_the_account_source_may_mark_paid_games_owned(self):
-        entry = {'free': False, 'owned': True}
-        self.assertFalse(search.obtainable({'id': 'fdroid'}, entry))
-        self.assertTrue(search.obtainable({'id': itch.OWNED, 'owned': True}, entry))
-        self.assertTrue(search.obtainable({'id': 'fdroid'}, {'free': True}))
-
-    def test_android_upload_selection(self):
-        uploads = json.loads((FIX / 'uploads.json').read_text())['uploads']
-        # .apk files before other Android files, full games before demos, newest first; never
-        # soundtracks, externally hosted files or other platforms.
-        self.assertEqual([u['id'] for u in account.android_uploads(uploads)], [503, 502, 504, 505])
-        self.assertTrue(account.is_android({'filename': 'Game.APK'}))
-        self.assertTrue(account.is_android({'filename': 'game.zip', 'p_android': True}))
-        self.assertTrue(account.is_android({'filename': 'game.zip', 'platforms': {'android': 'all'}}))
-        self.assertFalse(account.is_android({'filename': 'game.zip', 'traits': ['p_windows']}))
-        self.assertEqual(account.android_uploads({'not': 'a list'}), [])
-
-    def test_details_offer_the_android_uploads(self):
-        self.connect()
-        entry = itch.details(self.owned_source(), '341190')
-        self.assertTrue(entry['downloadable'])
-        self.assertEqual([v['upload_id'] for v in entry['versions']], [503, 502, 504, 505])
-        self.assertEqual((entry['version'], entry['size'], entry['updated']), ('Quest 1.2', 115343360, '2026-04-03'))
-        self.assertTrue(entry['versions'][2]['demo'])
-        url = self.web.urls('api.itch.io/games/341190/uploads')[0]
-        self.assertEqual(url, 'https://api.itch.io/games/341190/uploads?download_key_id=9001')
-        with self.assertRaisesRegex(SourceError, 'not among'):
-            itch.details(self.owned_source(), '3')  # owned, but not for Android
-        self.web.route('api.itch.io/games/77/uploads', {'uploads': []})
-        self.assertFalse(itch.details(self.owned_source(), '77')['downloadable'])
-        with self.assertRaisesRegex(SourceError, 'no Android download'):
-            itch.download(self.owned_source(), '77')
-
-    def test_download_url_building(self):
-        self.assertEqual(account.download_url(503, 9001),
-                         'https://api.itch.io/uploads/503/download?download_key_id=9001')
-        for bad in [(0, 1), (1, None), ('5', 1), (True, 1), (-2, 1)]:
-            with self.assertRaises(SourceError):
-                account.download_url(*bad)
-
-    # -- downloads -----------------------------------------------------------------
-
-    def storage(self, location='https://storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk?sig=abc'):
-        self.web.route('api.itch.io/uploads/503/download',
-                       Reply('https://api.itch.io/uploads/503/download', 302, b'', {'Location': location}))
-        self.web.route('storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk', Reply(location, 200, apk_bytes()))
-
-    def test_download_sends_the_key_to_itch_only_and_strips_it_on_redirect(self):
-        self.connect()
-        self.storage()
-        result = itch.download(self.owned_source(), '341190')
-        self.assertTrue(os.path.isfile(result['apk']))
-        self.assertFalse(result['verified'])
-        api, cdn = self.web.calls[-2:]
-        self.assertEqual(api[0], 'https://api.itch.io/uploads/503/download?download_key_id=9001')
-        self.assertEqual(api[1]['authorization'], 'Bearer ' + KEY)
-        self.assertTrue(cdn[0].startswith('https://storage.itch-cdn.example/'))
-        self.assertNotIn('authorization', cdn[1])
-        # Connected to the address that was checked, not to a fresh lookup.
-        self.assertEqual(self.connected, [('storage.itch-cdn.example', ('151.101.1.1', 443))])
-        self.assertTrue(all(KEY not in u for u, _ in self.web.calls))
-        with self.assertRaisesRegex(SourceError, 'version codes'):
-            itch.download(self.owned_source(), '341190', version_code=3)
-
-    def test_download_also_accepts_a_json_url_or_the_file_itself(self):
-        self.connect()
-        self.storage()
-        location = 'https://storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk?sig=abc'
-        self.web.route('api.itch.io/uploads/503/download',
-                       Reply('https://api.itch.io/uploads/503/download', 200, {'url': location},
-                             {'Content-Type': 'application/json'}))
-        self.assertTrue(os.path.isfile(itch.download(self.owned_source(), '341190')['apk']))
-        self.assertNotIn('authorization', self.web.calls[-1][1])
-        self.web.route('api.itch.io/uploads/503/download',
-                       Reply('https://api.itch.io/uploads/503/download', 200, apk_bytes(),
-                             {'Content-Type': 'application/octet-stream'}))
-        self.connected.clear()
-        self.assertTrue(os.path.isfile(itch.download(self.owned_source(), '341190')['apk']))
-        self.assertEqual(self.connected, [])  # api.itch.io served it; no storage host involved
-        self.web.route('api.itch.io/uploads/503/download',
-                       Reply('https://api.itch.io/uploads/503/download', 200, {'nothing': 1},
-                             {'Content-Type': 'application/json'}))
-        with self.assertRaisesRegex(SourceError, 'did not say where'):
-            itch.download(self.owned_source(), '341190')
-
-    def test_storage_redirects_are_checked_on_every_hop(self):
-        self.connect()
-        self.storage('https://other-cdn.example/hop')
-        self.web.route('other-cdn.example/hop', Reply('https://other-cdn.example/hop', 302, b'',
-                                                      {'Location': 'https://storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk'}))
-        self.assertTrue(os.path.isfile(itch.download(self.owned_source(), '341190')['apk']))
-        self.assertEqual([h for h, _ in self.connected], ['other-cdn.example', 'storage.itch-cdn.example'])
-        self.web.route('other-cdn.example/hop', Reply('https://other-cdn.example/hop', 302, b'',
-                                                      {'Location': 'https://intranet.example/a.apk'}))
-        with self.assertRaisesRegex(SourceError, 'private network address'):
-            itch.download(self.owned_source(), '341190')
-
-    def test_redirects_to_plain_http_or_private_addresses_are_refused(self):
-        self.connect()
-        for location in ('http://storage.itch-cdn.example/a.apk', 'https://user:pw@cdn.example/a.apk',
-                         'https://cdn.example:8443/a.apk'):
-            self.storage(location)
-            with self.assertRaisesRegex(SourceError, 'unexpected download URL'):
-                itch.download(self.owned_source(), '341190')
-        for location in ('https://localhost./a.apk', 'https://frame.local/a.apk', 'https://127.0.0x0.1/a.apk',
-                         'https://intranet.example/a.apk', 'https://mapped.example/a.apk',
-                         'https://cgnat.example/a.apk', 'https://mixed.example/a.apk',
-                         'https://127.0.0.1/a.apk', 'https://[::1]/a.apk', 'https://169.254.169.254/a.apk',
-                         'https://nat64.example/a.apk', 'https://[4000::1]/a.apk', 'https://[64:ff9b:1::a00:1]/a.apk',
-                         'https://[fec0::1]/a.apk', 'https://sitelocal.example/a.apk'):
-            self.storage(location)
-            with self.assertRaisesRegex(SourceError, 'private network address'):
-                itch.download(self.owned_source(), '341190')
-        self.assertEqual(self.connected, [])
-        self.assertEqual({urllib.parse.urlsplit(u).hostname for u, _ in self.web.calls}, {'api.itch.io'})
-
-    def test_public_address_rules(self):
-        for ip in ('151.101.1.1', '8.8.8.8', '2a04:4e42::81', '2001:4860:4860::8888'):
-            self.assertTrue(_web.public_address(ip), ip)
-        for ip in ('127.0.0.1', '10.1.2.3', '172.16.0.1', '192.168.0.1', '169.254.169.254', '100.64.0.1',
-                   '0.0.0.0', '224.0.0.1', '255.255.255.255', '240.0.0.1', '::1', '::', 'fe80::1%en0', 'fc00::1',
-                   'ff02::1', 'not an ip',
-                   '192.0.0.8', '192.0.0.11', '192.0.0.255', '192.0.0.170', '192.0.0.9', '192.0.0.1',  # 3.9: global
-                   '192.0.2.1', '192.88.99.1', '198.18.0.1', '198.19.255.255', '198.51.100.7', '203.0.113.9',
-                   '0.1.2.3', '10.255.255.255', '172.31.0.1', '239.1.1.1', '254.0.0.1',
-                   '4000::1', '100::1', 'f000::1',  # reserved: Python 3.9's is_global says True for 4000::1
-                   '::ffff:10.0.0.1', '::ffff:127.0.0.1', '::ffff:8.8.8.8',  # IPv4-mapped
-                   '::a00:1', '::8.8.8.8',  # IPv4-compatible
-                   '64:ff9b::a00:1', '64:ff9b::808:808',  # NAT64 well-known prefix
-                   '64:ff9b:1::a00:1', '64:ff9b:1::808:808',  # NAT64 local-use: 3.9's is_global says True
-                   '2002:a00:1::1', '2002:808:808::1',  # 6to4
-                   '2001:0:4136:e378:8000:63bf:3fff:fdd2',  # Teredo
-                   'fec0::1', 'feff::1',  # site-local: Python 3.9's is_global says True
-                   'fc00::1', 'fd12:3456::1', 'fe80::1', 'ff00::1', 'ff0e::1', '8000::1', 'c000::1',
-                   '2001:db8::1', '3fff::1',  # documentation
-                   '2001:10::1', '2001:20::1', '2001:2::1'):  # ORCHID, ORCHIDv2, benchmarking
-            self.assertFalse(_web.public_address(ip), ip)
-        self.assertEqual(_web.resolve_public('storage.itch-cdn.example'), [('151.101.1.1', 443)])
-        self.assertEqual(_web.resolve_public('dual.example'), [('2a04:4e42::81', 443), ('151.101.1.1', 443)])
-
-    def test_a_storage_url_carrying_the_key_is_refused(self):
-        self.connect()
-        for location in ('https://storage.itch-cdn.example/a.apk?api_key=' + KEY,
-                         'https://storage.itch-cdn.example/a.apk?API_KEY=someone-elses',
-                         'https://storage.itch-cdn.example/a.apk?apikey=x',
-                         'https://storage.itch-cdn.example/' + KEY + '/a.apk',
-                         'https://storage.itch-cdn.example/a.apk#' + KEY[:10],
-                         'https://storage.itch-cdn.example/a.apk?x=' + urllib.parse.quote('%' + KEY),
-                         'https://' + KEY.lower() + '.itch-cdn.example/a.apk'):
-            self.storage(location)
-            with self.assertRaisesRegex(SourceError, 'carrying your API key; refused') as caught:
-                itch.download(self.owned_source(), '341190')
-            self.assertNotIn(KEY.lower(), str(caught.exception).lower())
-        self.web.route('api.itch.io/uploads/503/download',
-                       Reply('https://api.itch.io/uploads/503/download', 200,
-                             {'url': 'https://storage.itch-cdn.example/a.apk?api_key=' + KEY},
-                             {'Content-Type': 'application/json'}))
-        with self.assertRaisesRegex(SourceError, 'carrying your API key; refused'):
-            itch.download(self.owned_source(), '341190')
-        self.assertEqual(self.connected, [])
-        # A storage URL's own signature or token parameters are fine.
-        self.storage('https://storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk?token=abc&Signature=x')
-        self.assertTrue(os.path.isfile(itch.download(self.owned_source(), '341190')['apk']))
-
-    def test_a_later_redirect_carrying_the_key_is_refused_before_connecting(self):
-        self.connect()
-        bad = 'https://storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk?api_key=' + KEY
-        for hops in (['https://other-cdn.example/hop1'],  # 2nd hop carries the key
-                     ['https://other-cdn.example/hop1', 'https://other-cdn.example/hop2']):  # 3rd hop
-            self.connected.clear()
-            self.storage(hops[0])
-            for here, there in zip(hops, hops[1:] + [bad]):
-                path = urllib.parse.urlsplit(here).path
-                self.web.route('other-cdn.example' + path, Reply(here, 302, b'', {'Location': there}))
-            with self.assertRaisesRegex(SourceError, 'carrying your API key; refused') as caught:
-                itch.download(self.owned_source(), '341190')
-            self.assertNotIn(KEY, str(caught.exception))
-            self.assertEqual([h for h, _ in self.connected], ['other-cdn.example'] * len(hops))
-            self.assertFalse(any(KEY in u for u, _ in self.web.calls))
-        # The check runs on every hop before the name is even looked up.
-        seen = []
-        with patch.object(_web, 'resolve_public', side_effect=AssertionError('looked up')):
-            with self.assertRaisesRegex(SourceError, 'no thanks'):
-                _web.public_apk('https://storage.itch-cdn.example/a.apk', 'itch.io',
-                                check=lambda u: seen.append(u) or (_ for _ in ()).throw(SourceError('no thanks')))
-        self.assertEqual(seen, ['https://storage.itch-cdn.example/a.apk'])
-
-    def test_a_partial_match_before_the_key_cannot_hide_its_start(self):
-        key = 'abcdefghABCDEFGHi1234567890'
-        for text in (key[:8].upper() + key.upper(), key[:9] + key, 'xx' + key[:8] + key + 'yy'):
-            out = account._clean(text, key)
-            self.assertNotIn('1234567890', out, (text, out))
-        import time
-        t0 = time.monotonic(); account._clean(('abcdefgh' * 12500)[:100000], key)
-        self.assertLess(time.monotonic() - t0, 2.0)
-
-    def test_redaction_catches_every_spelling_of_the_key(self):
-        hexed = ''.join('%%%02X' % ord(c) for c in KEY)
-        for spelling in (KEY, KEY.lower(), KEY.upper(), hexed, hexed.lower(),
-                         KEY[:5] + hexed[15:30] + KEY[10:],  # partly encoded
-                         KEY[:9], hexed[:30].lower(),  # starts of it, 8+ characters
-                         ''.join('%%%02x' % ord(c) for c in KEY.lower()),  # encoded after a case change
-                         ''.join('%%%02X' % ord(c) for c in KEY.swapcase()),
-                         '%%%02x' % ord(KEY[0].swapcase()) + KEY[1:]):  # one encoded, recased letter
-            cleaned = account._clean('before ' + spelling + ' after', KEY)
-            self.assertEqual(cleaned, 'before [API key] after', spelling)
-        double = ''.join('%%25%02X' % ord(c) for c in KEY)  # percent-encoded twice
-        for spelling in (double, double.lower(), double.upper(), double[:5 * 9],  # full, hex recased, 9-char start
-                         ''.join('%%25%02x' % ord(c) for c in KEY.lower()),  # the key recased, then double-encoded
-                         KEY[:4] + double[20:45] + hexed[27:33] + KEY[11:]):  # literal, double and single mixed
-            self.assertEqual(account._clean('before ' + spelling + ' after', KEY), 'before [API key] after', spelling)
-        self.assertEqual(account._clean(double[:5 * 7], KEY), double[:5 * 7])  # 7 characters: kept
-        self.assertTrue(account._carries_key('https://cdn.example/a?x=' + double, KEY))
-        self.assertTrue(account._carries_key('https://cdn.example/' + double[:5 * 8].lower() + '/a', KEY))
-        self.assertEqual(account._clean('TESTKEY is short', KEY), 'TESTKEY is short')  # 7 characters: kept
-        self.assertEqual(account._clean(KEY + KEY.lower(), KEY), '[API key][API key]')
-        for url in ('https://cdn.example/a?x=' + hexed, 'https://cdn.example/a?x=' + hexed.lower(),
-                    'https://cdn.example/' + KEY.upper() + '/a', 'https://cdn.example/a?x=' + urllib.parse.quote_plus(KEY)):
-            self.assertTrue(account._carries_key(url, KEY), url)
-        self.assertFalse(account._carries_key('https://cdn.example/a?token=abc&Signature=x', KEY))
-        # Storage errors carrying an encoded or lowercased key lose it, keeping their kind.
-        self.connect()
-        self.storage()
-        with patch.object(_web, 'public_apk', side_effect=SourceLimited('slow ' + hexed.lower(), 42)):
-            with self.assertRaises(SourceLimited) as caught:
-                itch.download(self.owned_source(), '341190')
-        self.assertEqual((str(caught.exception), caught.exception.retry_after), ('slow [API key]', 42))
-        with patch.object(_web, 'public_apk', side_effect=SourceError('host ' + KEY.lower() + '.cdn')):
-            with self.assertRaisesRegex(SourceError, r'^host \[API key\]\.cdn$'):
-                itch.download(self.owned_source(), '341190')
-
-    def test_storage_errors_lose_the_key_but_keep_their_kind(self):
-        self.connect()
-        self.storage()
-        with patch.object(_web, 'public_apk', side_effect=SourceLimited('slow down ' + KEY, 90)):
-            with self.assertRaises(SourceLimited) as caught:
-                itch.download(self.owned_source(), '341190')
-        self.assertEqual((str(caught.exception), caught.exception.retry_after), ('slow down [API key]', 90))
-        with patch.object(_web, 'public_apk', side_effect=SourceError('Could not find the download server ' + KEY)):
-            with self.assertRaisesRegex(SourceError, r'^Could not find the download server \[API key\]$') as caught:
-                itch.download(self.owned_source(), '341190')
-        self.assertIsNone(caught.exception.__cause__)
-        self.assertTrue(caught.exception.__suppress_context__)
-
-    def test_broken_http_responses_are_readable_and_lose_the_key(self):
-        self.connect()
-
-        class Truncated(Reply):
-            def read(self, *args):
-                raise http.client.IncompleteRead(b'{"owned_keys": [' + KEY.encode(), 1000)
-        cases = [http.client.BadStatusLine('HTTP/1.1 ' + KEY + ' oops'),
-                 lambda req, q: Truncated(req.full_url, 200, b''),
-                 http.client.RemoteDisconnected('closed after ' + KEY)]
-        for case in cases:
-            account._forget()
-            self.web.route('api.itch.io/profile/owned-keys', case)
-            with self.assertRaisesRegex(SourceError, '^Could not reach itch.io: ') as caught:
-                account.owned_keys()
-            self.assertNotIn(KEY, str(caught.exception))
-            self.assertIsNone(caught.exception.__cause__)
-            self.assertTrue(caught.exception.__suppress_context__)
-            self.assertTrue(account.connected())
-        # The same on the download request, for each kind of answer it reads.
-        for case in (http.client.BadStatusLine('HTTP/1.1 ' + KEY),
-                     lambda req, q: Truncated(req.full_url, 200, b'', {'Content-Type': 'application/json'}),
-                     lambda req, q: Truncated(req.full_url, 200, b'', {'Content-Type': 'application/octet-stream'})):
-            self.web.route('api.itch.io/uploads/503/download', case)
-            with self.assertRaises(SourceError) as caught:
-                account.download(503, 9001)
-            self.assertNotIn(KEY, str(caught.exception))
-            self.assertRegex(str(caught.exception), '^Could not (reach itch.io|download APK): ')
-
-    def test_connecting_shares_one_deadline_across_addresses(self):
-        clock, deadlines = [1000.0], []
-
-        def slow(host, address, timeout, deadline):
-            deadlines.append(deadline)
-            clock[0] += 7  # each address hangs for 7 s before failing
-            raise socket.timeout('timed out')
-        with patch.object(_web.time, 'monotonic', lambda: clock[0]), patch.object(_web, '_connect', slow):
-            with self.assertRaises(OSError):
-                _web._public_connection('many.example', 60)
-        self.assertEqual(len(set(deadlines)), 1)  # one deadline for every attempt
-        self.assertEqual(deadlines[0], 1000.0 + _web.CONNECT_BUDGET)
-        self.assertEqual(len(deadlines), 3)  # 8 addresses, but only 21 s of trying, not 56
-        self.assertLessEqual(clock[0] - 1000.0, _web.CONNECT_BUDGET + 7)
-        deadlines.clear()
-        clock[0] = 1000.0
-        with patch.object(_web.time, 'monotonic', lambda: clock[0]), patch.object(_web, '_connect', slow):
-            with self.assertRaises(OSError):
-                _web._public_connection('many.example', 5)  # the caller's shorter timeout wins
-        self.assertEqual(deadlines, [1005.0])
-
-    def test_a_stalled_handshake_stops_at_the_deadline(self):
-        # A local server that accepts and then says nothing: the TLS handshake never completes.
-        server = socket.socket()
-        server.bind(('127.0.0.1', 0))
-        server.listen(1)
-        self.addCleanup(server.close)
-        timeouts = []
-        real_settimeout = socket.socket.settimeout
-
-        def settimeout(sock, value):
-            timeouts.append(value)
-            return real_settimeout(sock, value)
-        start = time.monotonic()
-        # No thread is left behind to shut the connection later: the deadline is only socket timeouts.
-        with patch.object(_web.threading, 'Timer', side_effect=AssertionError('watchdog thread')), \
-                patch.object(socket.socket, 'settimeout', settimeout):
-            with self.assertRaises(OSError):
-                REAL_CONNECT('storage.itch-cdn.example', server.getsockname(), 60, start + 0.5)
-        self.assertLess(time.monotonic() - start, 3)
-        self.assertTrue(timeouts and all(0 < t <= 0.5 for t in timeouts), timeouts)  # what's left, each step
-        with patch.object(_web.socket, 'create_connection', side_effect=AssertionError('connected')):
-            with self.assertRaises(socket.timeout):  # a deadline already gone: no connection attempt at all
-                REAL_CONNECT('storage.itch-cdn.example', server.getsockname(), 60, time.monotonic() - 1)
-
-    def test_an_unreachable_address_falls_back_to_the_next_checked_one(self):
-        self.connect()
-        self.storage('https://dual.example/upload/503/OrbitGarden-Quest.apk')
-        self.web.route('dual.example/upload/503/OrbitGarden-Quest.apk', Reply('https://dual.example/', 200, apk_bytes()))
-        self.unreachable.add('2a04:4e42::81')
-        self.assertTrue(os.path.isfile(itch.download(self.owned_source(), '341190')['apk']))
-        self.assertEqual(self.connected, [('dual.example', ('2a04:4e42::81', 443)), ('dual.example', ('151.101.1.1', 443))])
-        self.unreachable.add('151.101.1.1')
-        with self.assertRaisesRegex(SourceError, '^Could not download APK: Network is unreachable$'):
-            itch.download(self.owned_source(), '341190')
-
-    def test_storage_refusals_are_download_errors_not_rate_limits(self):
-        self.connect()
-        self.storage()
-        self.web.route('storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk',
-                       Reply('https://storage.itch-cdn.example/x', 403, b'denied'))
-        with self.assertRaisesRegex(SourceError, r"itch.io's download server refused the file \(HTTP 403\)") as caught:
-            itch.download(self.owned_source(), '341190')
-        self.assertNotIsInstance(caught.exception, SourceLimited)
-        self.assertTrue(account.connected())
-        self.assertEqual(_web.wait_time('https://api.itch.io/'), 0)
-        self.web.route('storage.itch-cdn.example/upload/503/OrbitGarden-Quest.apk',
-                       Reply('https://storage.itch-cdn.example/x', 429, b'', {'Retry-After': '60'}))
-        with self.assertRaises(SourceLimited):
-            itch.download(self.owned_source(), '341190')
-
-    def test_a_key_revoked_after_details_were_cached_is_removed_at_download(self):
-        self.connect()
-        itch.details(self.owned_source(), '341190')  # uploads and owned keys now cached
-        for code in (401, 403):
-            self.connect()
-            self.web.route('api.itch.io/uploads/503/download', Reply('https://api.itch.io/uploads/503/download', code, b''))
-            self.web.route('api.itch.io/profile', Reply('https://api.itch.io/profile', code, b''))
-            with self.assertRaisesRegex(account.BadKey, 'no longer accepts the saved API key'):
-                account.download(503, 9001)
-            self.assertFalse(account.path().exists())
-            self.web.route('api.itch.io/profile', {'user': {'username': 'player'}})
-        # The key still works, only this download is refused: keep the key, say so.
-        self.connect()
-        self.web.route('api.itch.io/uploads/503/download', Reply('https://api.itch.io/uploads/503/download', 403, b''))
-        with self.assertRaisesRegex(SourceError, r'refused this request \(HTTP 403\)') as caught:
-            account.download(503, 9001)
-        self.assertNotIsInstance(caught.exception, (account.BadKey, SourceLimited))
-        self.assertTrue(account.connected())
-
-    def test_a_disconnect_during_the_key_check_wins(self):
-        checking, release = threading.Event(), threading.Event()
-
-        def slow_profile(req, query):
-            checking.set()
-            release.wait(5)
-            return {'user': {'username': 'player'}}
-        self.web.route('api.itch.io/profile', slow_profile)
-        outcome = {}
-
-        def run():
-            try:
-                outcome['result'] = account.connect(KEY)
-            except SourceError as e:
-                outcome['error'] = e
-        worker = threading.Thread(target=run)
-        worker.start()
-        self.assertTrue(checking.wait(5))
-        account.disconnect()
-        release.set()
-        worker.join(5)
-        self.assertRegex(str(outcome.get('error')), 'changed while the key was being checked; nothing was saved')
-        self.assertFalse(account.path().exists())
-        self.assertFalse(account.connected())
-
-    def test_an_old_refusal_does_not_undo_a_reconnect_with_the_same_key(self):
-        self.connect()
-        listing, release, profile_ok = threading.Event(), threading.Event(), [True]
-
-        def slow_owned(req, query):
-            listing.set()
-            release.wait(5)
-            return Reply(req.full_url, 401, b'')
-        self.web.route('api.itch.io/profile/owned-keys', slow_owned)
-        self.web.route('api.itch.io/profile', lambda req, q: {'user': {'username': 'player'}} if profile_ok[0]
-                       else Reply(req.full_url, 401, b''))
-        outcome = {}
-
-        def run():
-            try:
-                account.owned_keys()
-            except SourceError as e:
-                outcome['error'] = e
-        worker = threading.Thread(target=run)
-        worker.start()
-        self.assertTrue(listing.wait(5))
-        account.disconnect()
-        account.connect(KEY)  # same key, connected again while the old listing waits
-        profile_ok[0] = False  # the old listing's confirmation now sees a refusal
-        release.set()
-        worker.join(5)
-        self.assertIsInstance(outcome.get('error'), account.BadKey)
-        self.assertTrue(account.path().exists())  # the fresh connection survives
-        self.assertEqual(json.loads(account.path().read_text())['key'], KEY)
-
-    def test_redacted_text_is_not_mistaken_for_a_key_error(self):
-        self.connect()
-        before = len(self.web.urls('api.itch.io/profile'))
-        self.web.route('api.itch.io/profile/owned-keys', {'errors': ['Invalid request: ' + KEY]})
-        with self.assertRaisesRegex(SourceError, r'^itch.io: Invalid request: \[API key\]$') as caught:
-            account.owned_keys()
-        self.assertNotIsInstance(caught.exception, account.BadKey)
-        self.assertTrue(account.connected())
-        self.assertEqual(len(self.web.urls('api.itch.io/profile')), before)  # not even a key check needed
-
-    def test_an_invalid_key_error_elsewhere_is_confirmed_before_deleting(self):
-        self.connect()
-        self.web.route('api.itch.io/profile/owned-keys', {'errors': ['invalid key']})
-        with self.assertRaisesRegex(SourceError, '^itch.io: invalid key$') as caught:
-            account.owned_keys()  # /profile still accepts the key: keep it
-        self.assertNotIsInstance(caught.exception, account.BadKey)
-        self.assertTrue(account.connected())
-        account._forget()
-        self.web.route('api.itch.io/profile', {'errors': ['invalid key']})
-        with self.assertRaisesRegex(account.BadKey, 'no longer accepts'):
-            account.owned_keys()
-        self.assertFalse(account.connected())
-
-    def test_concurrent_connects_never_share_a_temporary_file(self):
-        made = []
-        real = account.tempfile.mkstemp
-
-        def mkstemp(*args, **kwargs):
-            fd, name = real(*args, **kwargs)
-            made.append(name)
-            if os.name == 'posix':
-                self.assertEqual(os.stat(name).st_mode & 0o777, 0o600)
-            return fd, name
-        with patch.object(account.tempfile, 'mkstemp', mkstemp):
-            workers = [threading.Thread(target=lambda k=k: self.swallow(account.connect, k)) for k in (KEY, OTHER) * 3]
-            for w in workers:
-                w.start()
-            for w in workers:
-                w.join(5)
-        self.assertEqual(len(made), len(set(made)))
-        self.assertIn(json.loads(account.path().read_text())['key'], (KEY, OTHER))
-        self.assertEqual([p.name for p in account.path().parent.iterdir()], ['itch-account.json'])
-
-    @staticmethod
-    def swallow(fn, *args):
-        try:
-            fn(*args)
-        except SourceError:
-            pass  # a connect overtaken by another one refuses to save: fine here
-
-    def test_existing_hosts_still_strip_authorization_on_redirect(self):
-        req = urllib.request.Request('https://api.github.com/a', headers={'Authorization': 'Bearer x'})
-        nxt = _web.Redirect(('api.github.com',)).redirect_request(req, None, 302, 'Found', {}, 'https://api.github.com/b')
-        self.assertFalse(nxt.has_header('Authorization'))
-        with self.assertRaises(SourceError):
-            _web.Redirect(('api.github.com',)).redirect_request(req, None, 302, 'Found', {}, 'https://evil.example/b')
-
-    def test_install_uses_the_normal_apk_install_path(self):
-        import frame_android
-        self.connect()
-        self.storage()
-        calls = []
-
-        def install(apk_path, flatscreen=None, name=None, source=None, icon_png=None, xr_compat=None, artwork=None):
-            with zipfile.ZipFile(apk_path) as z:
-                self.assertIn('AndroidManifest.xml', z.namelist())
-            calls.append((name, source))
-            return {'package': 'com.maker.orbit', 'message': 'Installed'}
-        with patch.object(frame_android, 'install', install):
-            result = search.install(itch.OWNED, '341190')
-        self.assertEqual(calls, [('Orbit Garden VR', 'itch.io (my purchases)')])
-        self.assertEqual(result['package'], 'com.maker.orbit')
-
-    # -- errors never carry the key ------------------------------------------------
-
-    def test_errors_are_readable_and_never_contain_the_key(self):
-        self.connect()
-        cases = [
-            (Reply('https://api.itch.io/profile/owned-keys', 429, b'', {'Retry-After': '120'}),
-             SourceLimited, '^itch.io is limiting requests; try again in 2 minutes$'),
-            (Reply('https://api.itch.io/profile/owned-keys', 503, b''), SourceError, 'HTTP error 503; try again later'),
-            (urllib.error.URLError('connect to api.itch.io with ' + KEY + ' failed'), SourceError,
-             r'^Could not reach itch.io: connect to api.itch.io with \[API key\] failed$'),
-            (OSError('timed out'), SourceError, '^Could not reach itch.io: timed out$'),
-            (Reply('https://api.itch.io/profile/owned-keys', 200, b'<html>'), SourceError, 'invalid response'),
-            ({'errors': ['echo ' + KEY]}, SourceError, r'^itch.io: echo \[API key\]$'),
-            # The key straddles the 200-character cut: no piece of it may survive.
-            ({'errors': ['x' * 180, KEY]}, SourceError, r'^itch.io: x{180}; \[API key\]$'),
-            ({'errors': ['x' * 190 + KEY]}, SourceError, r'^itch.io: x{190}\[API key\]$'),
-        ]
-        self.assertEqual(account._clean('cut at ' + KEY[:9], KEY), 'cut at [API key]')  # a truncated key's start
-        stderr = io.StringIO()
-        with contextlib.redirect_stderr(stderr):
-            for reply, kind, message in cases:
-                account._forget()
-                _web._limited.clear()
-                self.web.route('api.itch.io/profile/owned-keys', reply)
-                with self.assertRaisesRegex(kind, message) as caught:
-                    account.owned_keys()
-                self.assertNotIn(KEY, str(caught.exception))
-                self.assertIsNone(caught.exception.__cause__)
-                self.assertTrue(account.connected())  # not the key's fault: stays connected
-            # The store's search reports the failure as a non-fatal source status.
-            account._forget()
-            result = search.search('', source=itch.OWNED)
-        self.assertEqual(result['sources'][0]['status'], 'error')
-        self.assertNotIn(KEY, json.dumps(result) + stderr.getvalue())
-
-    def test_server_api_connects_and_never_echoes_the_key(self):
-        httpd = server.ThreadingHTTPServer(('127.0.0.1', 0), server.Handler)
-        threading.Thread(target=httpd.serve_forever, daemon=True).start()
-        self.addCleanup(httpd.server_close)
-        self.addCleanup(httpd.shutdown)
-
-        def request(method, path, body=None):
-            c = http.client.HTTPConnection('127.0.0.1', httpd.server_port)
-            c.request(method, path, json.dumps(body) if body is not None else None,
-                      {'X-Frame-UI': '1', 'Content-Type': 'application/json'})
-            r = c.getresponse()
-            out = r.status, r.read().decode()
-            c.close()
-            return out
-        stderr = io.StringIO()
-        with contextlib.redirect_stderr(stderr):
-            self.web.route('api.itch.io/profile', Reply('https://api.itch.io/profile', 401, b''))
-            bad = request('POST', '/api/sources', {'action': 'itch-connect', 'key': KEY})
-            self.web.route('api.itch.io/profile', {'user': {'username': 'player'}})
-            good = request('POST', '/api/sources', {'action': 'itch-connect', 'key': KEY})
-            listed = request('GET', '/api/sources')
-            empty = request('POST', '/api/sources', {'action': 'itch-connect', 'key': ' '})
-            gone = request('POST', '/api/sources', {'action': 'itch-disconnect'})
-        self.assertEqual(bad[0], 400)
-        self.assertIn('did not accept the API key', json.loads(bad[1])['error'])
-        self.assertEqual(good[0], 200)
-        self.assertEqual(json.loads(good[1])['itch'], {'connected': True, 'username': 'player'})
-        self.assertEqual(json.loads(listed[1])['itch'], {'connected': True, 'username': 'player'})
-        self.assertIn(itch.OWNED, [s['id'] for s in json.loads(listed[1])['sources']])
-        self.assertEqual(empty[0], 400)
-        self.assertEqual(json.loads(gone[1])['itch'], {'connected': False, 'username': None})
-        self.assertFalse(account.path().exists())
-        for text in (bad[1], good[1], listed[1], empty[1], gone[1], stderr.getvalue()):
-            self.assertNotIn(KEY, text)
-
-
-if __name__ == '__main__':
-    unittest.main()

tests/test_link.py

@@ -897,47 +897,6 @@ 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,19 +56,18 @@ 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_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.
+    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.
         self.run_page(r'''
   link.s = changed;
   renderPill();
-  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));
+  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.');
   // 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>Offline<\/span>/);
-  assert.ok($('conn').title.includes('Something.'));
+  assert.match($('conn').innerHTML, /<span>Checking the headset&#39;s identity failed<\/span>/);
 ''')
 
     def test_the_banner_never_doubles_a_full_stop(self):

tests/test_page_scripts.py

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

@@ -1,55 +0,0 @@
-"""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', 'loadMacView', 'loadPanels', 'loadPanelSwitcher', 'loadTitles', 'showAndroidTab']
-
-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]
-        tables = first[first.index('const PAGES ='):first.index('let page =')]
-        start = first.index('function showPage(')
-        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 != '$')
-        code = ('const $ = id => id === "nowhere" ? null : { classList: { toggle() {} }, scrollIntoView() {} };\n' + stubs + tables + 'let page = "home";\n' + 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)]
-        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

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

@@ -0,0 +1,188 @@
+"""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()

ui/apk_sources/__init__.py

@@ -32,9 +32,7 @@ Entry dict (missing facts are None, never guessed)
 Rules
 -----
 - Only sources that distribute APKs with the developer's consent: free listings,
-  never paid apps re-hosted, no licence or entitlement workarounds. The one paid
-  exception is a store's own download of a game the user bought there: a source
-  marked 'owned': True whose entries carry 'owned': True (itch.io purchases).
+  never paid apps re-hosted, no licence or entitlement workarounds.
 - Honour each site's terms and robots rules; if automated download isn't allowed,
   return entries with 'downloadable': False and a 'page' link instead.
 - Cache indexes under frame_host.cache_dir('apk-sources'); send a clear

ui/apk_sources/_itch_account.py

@@ -1,394 +0,0 @@
-"""The user's own itch.io account: an API key, the games it owns and their Android uploads.
-
-Opt-in (store > sources > Connect itch.io). The key is kept in
-frame_host.data_dir('itch-account.json') with mode 0600 and is only ever sent to
-https://api.itch.io, in an Authorization header. Downloads end on itch.io's storage
-host, fetched without the key from a checked public address (_web.public_apk).
-The key never goes into a URL, an error, a log line or an API response. Owned-key
-listings stay in memory, never in the disk cache.
-API: https://itch.io/docs/api/serverside. See docs/apk-repos.md.
-"""
-import hashlib, http.client, json, os, re, tempfile, threading, time, urllib.error, urllib.parse, urllib.request, zipfile
-
-import frame_host
-from . import SourceError, SourceLimited, _web
-
-API = 'https://api.itch.io'
-HOSTS = ('api.itch.io',)
-NAME = 'itch.io'
-TTL = 600  # owned keys and uploads are re-read after ten minutes
-PER_PAGE = 500  # the documented maximum for /profile/owned-keys
-PAGES = 40  # stop after 20,000 owned keys
-KEY = re.compile(r'[A-Za-z0-9_.-]{16,256}')
-BAD_KEY = ('itch.io did not accept the API key. Create one in itch.io settings > '
-           'API keys and connect again')
-REVOKED = ('itch.io no longer accepts the saved API key, so it was removed. '
-           'Create a new one in itch.io settings > API keys and connect again')
-REDIRECTS = (301, 302, 303, 307, 308)
-# Everything a connection or response can raise. http.client's errors (IncompleteRead,
-# BadStatusLine...) are not OSErrors, and BadStatusLine repeats what the server sent.
-NETWORK = (OSError, ValueError, http.client.HTTPException)
-_lock = threading.Lock()  # the cache
-_cache = {}  # (generation, key digest, what) -> (time, value)
-_account = threading.Lock()  # saving and deleting the key file
-_generation = [0]  # bumped by every save and delete: a connect that started earlier doesn't save
-
-
-class BadKey(SourceError):
-    """itch.io refused the key: wrong, revoked or deleted."""
-
-
-def path():
-    return frame_host.data_dir('itch-account.json')
-
-
-def _load():
-    try:
-        data = json.loads(path().read_text())
-    except (OSError, ValueError):
-        return None
-    if not isinstance(data, dict) or not isinstance(data.get('key'), str) or not KEY.fullmatch(data['key']):
-        return None
-    return data
-
-
-def status():
-    """{'connected', 'username'}: what the page may know. Never the key; no network."""
-    data = _load()
-    return {'connected': bool(data), 'username': data.get('username') if data else None}
-
-
-def connected():
-    return _load() is not None
-
-
-def _key():
-    data = _load()
-    if not data:
-        raise SourceError('Connect your itch.io account first (store > sources > Connect itch.io)')
-    return data['key']
-
-
-def _save(key, username):
-    """Write the key file through a fresh 0600 temporary file (mkstemp), then move it into place."""
-    target = path()
-    target.parent.mkdir(parents=True, exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=str(target.parent), prefix='.itch-account-', suffix='.tmp')
-    try:
-        with os.fdopen(fd, 'w') as f:
-            os.chmod(tmp, 0o600)  # mkstemp already does on POSIX; say so for every platform
-            json.dump({'key': key, 'username': username}, f)
-        os.replace(tmp, str(target))
-    finally:
-        if os.path.exists(tmp):
-            os.remove(tmp)
-
-
-def _forget():
-    with _lock:
-        _cache.clear()
-
-
-def _clean(message, key):
-    """message without the key, or any start of it (8+ characters, as truncation leaves), in
-    any letter case, with any of its characters written literally, percent-encoded (%4B or
-    %4b) or percent-encoded twice (%254B, %254b). The only redaction used here: every message
-    that might hold the key goes through it. (The key's characters are letters, digits and
-    _.-, so +/space encoding can't change it.)"""
-    if not key:
-        return message
-    # Each character: itself, or the percent-encoding (once or twice) of either of its letter cases.
-    tokens = ['(?:%s)' % '|'.join([re.escape(c)] + ['%%(?:25)?%02x' % ord(v) for v in sorted({c.lower(), c.upper()})])
-              for c in key]
-    start, rest = re.compile(''.join(tokens[:8]), re.I), [re.compile(t, re.I) for t in tokens[8:]]
-    spans, pos = [], 0
-    while True:
-        found = start.search(message, pos)
-        if not found:
-            break
-        end = found.end()
-        for token in rest:  # as much more of the key as follows
-            more = token.match(message, end)
-            if not more:
-                break
-            end = more.end()
-        spans.append((found.start(), end))
-        # Look again from the next character, not the end: a partial match just before the
-        # real key can overlap its start. Overlapping spans merge below.
-        pos = found.start() + 1
-    out, pos = [], 0
-    for a, b in spans:  # in order of start; only overlapping spans merge
-        if out and a < pos:
-            pos = max(pos, b)
-            continue
-        out += [message[pos:a], '[API key]']
-        pos = b
-    return ''.join(out) + message[pos:]
-
-
-class _Stay(urllib.request.HTTPRedirectHandler):
-    """Don't follow: the caller decides where a redirect may go, and never sends the key there."""
-
-    def redirect_request(self, req, fp, code, msg, headers, newurl):
-        return None
-
-
-def _open(url, key, accept='application/json'):
-    """GET url on api.itch.io with the key. Redirects come back as HTTPError 30x."""
-    _web.checked_url(url, HOSTS)
-    wait = _web.wait_time(url)
-    if wait:
-        raise _web.limited_error(NAME, wait)
-    return urllib.request.build_opener(_Stay()).open(urllib.request.Request(
-        url, headers={'User-Agent': _web.UA, 'Authorization': 'Bearer ' + key, 'Accept': accept}), timeout=60)
-
-
-def _refused(code, key, api_path, message=None):
-    """A refusal that may be about the key (401/403, or an "invalid key" error): BadKey only
-    once /profile confirms the key itself is refused; otherwise it's this request (a game or
-    upload this purchase doesn't cover), and the key stays."""
-    if api_path != '/profile':
-        _get('/profile', key)  # raises BadKey if the key is the problem
-        raise SourceError(message or 'itch.io refused this request (HTTP %d); your purchase may not include it' % code)
-    raise BadKey(BAD_KEY)
-
-
-def _network_error(e, key):
-    reason = getattr(e, 'reason', None) or e
-    return SourceError(_clean('Could not reach itch.io: ' + str(reason), key))
-
-
-BAD_KEY_TEXT = re.compile(r'\b(invalid|revoked|expired)\b.*\bkey\b|\bkey\b.*\b(invalid|revoked|expired)\b', re.I)
-
-
-def _checked(raw, key, api_path):
-    """Decoded JSON object from api.itch.io, or SourceError/BadKey from its errors array."""
-    if len(raw) > 8 * 1024 * 1024:
-        raise SourceError('itch.io response is too large')
-    try:
-        data = json.loads(raw)
-    except ValueError:
-        raise SourceError('itch.io returned an invalid response') from None
-    if not isinstance(data, dict):
-        raise SourceError('itch.io returned an invalid response')
-    errors = data.get('errors')
-    if errors:  # documented: errors is an array of strings
-        messages = [str(m) for m in errors if isinstance(m, (str, int))]
-        # Judged on itch.io's own words: redacted text says "[API key]", which would look like a key error.
-        about_key = any(BAD_KEY_TEXT.search(m) and 'download key' not in m.lower() for m in messages)
-        # Each message loses the key before joining and shortening, so no part of it survives the cut.
-        text = _clean('; '.join(_clean(m, key) for m in messages)[:200], key)
-        if about_key:
-            _refused(None, key, api_path, 'itch.io: ' + text)
-        raise SourceError('itch.io: ' + (text or 'request refused'))
-    return data
-
-
-def _get(api_path, key, params=None):
-    """JSON from api.itch.io; SourceError with a readable message (never the key) on failure."""
-    url = API + api_path + ('?' + urllib.parse.urlencode(params) if params else '')
-    try:
-        with _open(url, key) as r:
-            raw = r.read(8 * 1024 * 1024 + 1)
-    except urllib.error.HTTPError as e:
-        e.close()
-        if e.code == 429:
-            raise _web.limited_error(NAME, _web.throttle(url, e.headers)) from None
-        if e.code in (401, 403):
-            _refused(e.code, key, api_path)
-        raise SourceError('itch.io returned HTTP error %d; try again later' % e.code) from None
-    except SourceError:
-        raise
-    except NETWORK as e:
-        raise _network_error(e, key) from None
-    return _checked(raw, key, api_path)
-
-
-def _cached(key, what, load):
-    slot = (_generation[0], hashlib.sha256(key.encode()).hexdigest(), what)
-    with _lock:
-        hit = _cache.get(slot)
-    if hit and time.time() - hit[0] < TTL:
-        return hit[1]
-    value = load()
-    with _lock:
-        _cache[slot] = (time.time(), value)
-    return value
-
-
-def _use(call):
-    """Run call(key); a key itch.io now refuses is removed, so the account shows disconnected."""
-    with _account:  # the key and the connection it belongs to, read together
-        key, generation = _key(), _generation[0]
-    try:
-        return call(key)
-    except BadKey:
-        with _account:
-            # Only the connection this call started with: a reconnect meanwhile (even with
-            # the same key) has been checked since, and is not undone by this older verdict.
-            if _generation[0] == generation and (_load() or {}).get('key') == key:
-                _delete()
-        raise BadKey(REVOKED) from None
-
-
-def connect(key):
-    """Check key with itch.io (GET /profile), then save it. A refused key is never saved, and
-    nor is one whose check finished after a disconnect or another connect."""
-    key = (key or '').strip() if isinstance(key, str) else ''
-    if not KEY.fullmatch(key):
-        raise BadKey('That does not look like an itch.io API key. Copy it from itch.io settings > API keys')
-    with _account:
-        started = _generation[0]
-    user = _get('/profile', key).get('user')  # the network, outside the lock
-    if not isinstance(user, dict):
-        raise SourceError('itch.io returned an invalid profile')
-    username = user.get('username') if isinstance(user.get('username'), str) else None
-    with _account:
-        if _generation[0] != started:
-            raise SourceError('The itch.io connection changed while the key was being checked; '
-                              'nothing was saved. Try again')
-        _generation[0] += 1
-        _save(key, username)
-    _forget()
-    return {'message': 'Connected to itch.io' + (' as ' + username if username else ''), 'itch': status()}
-
-
-def _delete():
-    """Remove the key file; call with _account held."""
-    _generation[0] += 1
-    try:
-        os.remove(str(path()))
-    except FileNotFoundError:
-        pass
-    _forget()
-
-
-def disconnect():
-    with _account:
-        _delete()
-    return {'message': 'Disconnected from itch.io; the API key was deleted from this computer', 'itch': status()}
-
-
-def owned_keys():
-    """Every download key the account owns, newest first (GET /profile/owned-keys, all pages)."""
-    def load(key):
-        keys = []
-        for page in range(1, PAGES + 1):
-            batch = _get('/profile/owned-keys', key, {'page': page, 'per_page': PER_PAGE}).get('owned_keys')
-            # Documented: a page can hold fewer than per_page even when more follow; an empty one ends it.
-            if not batch or not isinstance(batch, list):
-                break
-            keys.extend(k for k in batch if isinstance(k, dict))
-        return keys
-    return _use(lambda key: _cached(key, 'owned', lambda: load(key)))
-
-
-def _number(value):
-    return value if type(value) is int and value > 0 else None
-
-
-def is_android(upload):
-    """An upload marked for Android, or an .apk file. The marker's field name is not in the
-    public reference: itch.io's traits use p_<platform> (p_windows...), so p_android is assumed."""
-    traits = upload.get('traits') if isinstance(upload.get('traits'), list) else []
-    platforms = upload.get('platforms') if isinstance(upload.get('platforms'), dict) else {}
-    filename = str(upload.get('filename') or '').lower()
-    return 'p_android' in traits or upload.get('p_android') is True or 'android' in platforms \
-        or filename.endswith('.apk')
-
-
-def android_uploads(uploads):
-    """Installable Android uploads, best first: .apk files, then full games, then newest."""
-    chosen = []
-    for u in uploads if isinstance(uploads, list) else []:
-        if not isinstance(u, dict) or not _number(u.get('id')) or not is_android(u):
-            continue
-        traits = u.get('traits') if isinstance(u.get('traits'), list) else []
-        if u.get('type') not in (None, 'default') or u.get('preorder') is True or 'preorder' in traits:
-            continue  # soundtracks, books, placeholders
-        if u.get('storage') == 'external':
-            continue  # hosted on another site: not something itch.io can hand us
-        chosen.append(u)
-    chosen.sort(key=lambda u: str(u.get('updated_at') or u.get('created_at') or ''), reverse=True)
-    chosen.sort(key=lambda u: (not str(u.get('filename') or '').lower().endswith('.apk'),
-                               u.get('demo') is True or 'demo' in (u.get('traits') or [])))
-    return chosen
-
-
-def uploads(game_id, download_key_id):
-    """The game's uploads this download key may fetch (GET /games/ID/uploads)."""
-    game_id, download_key_id = _number(game_id), _number(download_key_id)
-    if not game_id or not download_key_id:
-        raise SourceError('Invalid itch.io game')
-    return _use(lambda key: _cached(key, ('uploads', game_id, download_key_id), lambda: _get(
-        '/games/%d/uploads' % game_id, key, {'download_key_id': download_key_id}).get('uploads') or []))
-
-
-def download_url(upload_id, download_key_id):
-    upload_id, download_key_id = _number(upload_id), _number(download_key_id)
-    if not upload_id or not download_key_id:
-        raise SourceError('Invalid itch.io upload')
-    return API + '/uploads/%d/download?' % upload_id + urllib.parse.urlencode({'download_key_id': download_key_id})
-
-
-def _fetch(url, key):
-    """Ask api.itch.io for the file. Not checked against a live account, so this accepts each
-    plausible answer: a redirect to storage, JSON naming the storage URL, or the file itself."""
-    try:
-        r = _open(url, key, 'application/vnd.android.package-archive, application/json;q=0.5, */*;q=0.1')
-    except urllib.error.HTTPError as e:
-        e.close()
-        if e.code in REDIRECTS:
-            target = e.headers.get('Location')
-        elif e.code == 429:
-            raise _web.limited_error(NAME, _web.throttle(url, e.headers)) from None
-        elif e.code in (401, 403):
-            _refused(e.code, key, '/uploads')
-        else:
-            raise SourceError('itch.io returned HTTP error %d for the download; try again later' % e.code) from None
-    except SourceError:
-        raise
-    except NETWORK as e:
-        raise _network_error(e, key) from None
-    else:
-        with r:
-            if 'json' not in (r.headers.get('Content-Type') or '').lower():
-                try:
-                    return _web.save_apk(r)  # served by api.itch.io itself
-                except NETWORK + (zipfile.BadZipFile,) as e:
-                    raise SourceError(_clean('Could not download APK: ' + str(e), key)) from None
-            try:
-                raw = r.read(1024 * 1024 + 1)
-            except NETWORK as e:
-                raise _network_error(e, key) from None
-        target = _checked(raw, key, '/uploads').get('url')
-    if not isinstance(target, str) or not target:
-        raise SourceError('itch.io did not say where to download the file')
-    def refuse(hop):  # on the first URL and on every redirect after it, before any lookup
-        if _carries_key(hop, key):
-            raise SourceError('itch.io pointed the download at a URL carrying your API key; refused, '
-                              'so the key is not sent to the storage server')
-    try:
-        return _web.public_apk(urllib.parse.urljoin(url, target), NAME, check=refuse)  # no key sent
-    except SourceLimited as e:
-        raise SourceLimited(_clean(str(e), key), e.retry_after) from None
-    except SourceError as e:
-        raise type(e)(_clean(str(e), key)) from None
-
-
-def _carries_key(url, key):
-    """True if url holds the key (or 8+ characters of its start), however cased or encoded, or
-    an itch.io API-key parameter: go-itchio puts the key in ?api_key=, and storage must never
-    get it. Other parameters (signatures, tokens) are the storage URL's own and are kept."""
-    for form in (url, urllib.parse.unquote(url), urllib.parse.unquote_plus(url)):
-        if _clean(form, key) != form:
-            return True
-    names = {name.lower() for name, _ in urllib.parse.parse_qsl(urllib.parse.urlsplit(url).query,
-                                                                  keep_blank_values=True)}
-    return bool(names & {'api_key', 'apikey', 'api-key'})
-
-
-def download(upload_id, download_key_id):
-    """The APK: the key goes to api.itch.io only, never to the storage host."""
-    url = download_url(upload_id, download_key_id)
-    return _use(lambda key: _fetch(url, key))

ui/apk_sources/_web.py

@@ -1,6 +1,5 @@
 """Small HTTPS cache and APK downloader for public publisher sources."""
-import hashlib, http.client, ipaddress, os, shutil, socket, ssl, tempfile, threading, time
-import urllib.error, urllib.parse, urllib.request, zipfile
+import hashlib, os, shutil, tempfile, threading, time, urllib.error, urllib.parse, urllib.request, zipfile
 from email.utils import parsedate_to_datetime
 
 import frame_host
@@ -212,16 +211,19 @@ def read(url, hosts, headers=None, ttl=3600, name=None, hint='', auth=None):
         raise SourceError('Could not read source: ' + str(e)) from e
 
 
-def save_apk(response, digest=None):
-    """Stream response (anything with read(n)) into the cache as a checked APK."""
+def apk(url, hosts, digest=None, name=None):
     tmp = None
+    name = name or _host(url)
+    wait = wait_time(url)
+    if wait:
+        raise limited_error(name, wait)
     try:
         fd, tmp = tempfile.mkstemp(dir=cache(), suffix='.part')
         h = hashlib.sha256()
-        with os.fdopen(fd, 'wb') as f:
+        with os.fdopen(fd, 'wb') as f, open_url(url, hosts) as r:
             size = 0
             while True:
-                chunk = response.read(1 << 20)
+                chunk = r.read(1 << 20)
                 if not chunk:
                     break
                 size += len(chunk)
@@ -238,162 +240,12 @@ def save_apk(response, digest=None):
         path = os.path.join(cache(), actual + '.apk')
         os.replace(tmp, path)
         return {'apk': path, 'obb': [], 'sha256': actual, 'verified': bool(digest)}
-    finally:
-        if tmp and os.path.exists(tmp):
-            os.remove(tmp)
-
-
-def apk(url, hosts, digest=None, name=None):
-    name = name or _host(url)
-    wait = wait_time(url)
-    if wait:
-        raise limited_error(name, wait)
-    try:
-        with open_url(url, hosts) as r:
-            return save_apk(r, digest)
     except urllib.error.HTTPError as e:
         if e.code in (403, 429):
             raise limited_error(name, throttle(url, e.headers)) from e
         raise SourceError('Could not download APK: HTTP error ' + str(e.code)) from e
     except (OSError, ValueError, zipfile.BadZipFile) as e:
         raise SourceError('Could not download APK: ' + str(e)) from e
-
-
-# IPv6 is an allow-list: only global unicast (2000::/3), which rules out everything else at
-# once (loopback, unspecified, mapped/compatible IPv4, NAT64 64:ff9b::, site-local fec0::,
-# unique-local fc00::, link-local, multicast, reserved). Inside it, these special blocks are
-# refused too: 6to4 and Teredo carry IPv4 that may be private; the rest aren't the internet.
-_GLOBAL6 = ipaddress.ip_network('2000::/3')
-_SPECIAL6 = tuple(ipaddress.ip_network(n) for n in (
-    '2001::/32',      # Teredo
-    '2001:2::/48',    # benchmarking
-    '2001:10::/28',   # ORCHID
-    '2001:20::/28',   # ORCHIDv2
-    '2001:db8::/32',  # documentation
-    '2002::/16',      # 6to4
-    '3fff::/20'))     # documentation (2024)
-# IPv4 blocks that are never the public internet, listed in full rather than trusting
-# is_global (Python 3.9 calls 192.0.0.8, .11 and .255 global).
-_SPECIAL4 = tuple(ipaddress.ip_network(n) for n in (
-    '0.0.0.0/8', '10.0.0.0/8', '100.64.0.0/10', '127.0.0.0/8', '169.254.0.0/16', '172.16.0.0/12',
-    '192.0.0.0/24', '192.0.2.0/24', '192.88.99.0/24', '192.168.0.0/16', '198.18.0.0/15',
-    '198.51.100.0/24', '203.0.113.0/24', '224.0.0.0/4', '240.0.0.0/4', '255.255.255.255/32'))
-
-
-def public_address(ip):
-    """True for an address on the public internet: never loopback, private, link-local,
-    site-local, shared (CGNAT), reserved, unspecified or multicast, nor an IPv6 wrapper
-    around IPv4. Python 3.9's is_global alone lets several of these through."""
-    try:
-        a = ipaddress.ip_address(ip.split('%', 1)[0])
-    except ValueError:
-        return False
-    if a.version == 6 and (a not in _GLOBAL6 or any(a in n for n in _SPECIAL6)):
-        return False
-    if a.version == 4 and any(a in n for n in _SPECIAL4):
-        return False
-    return a.is_global and not (a.is_reserved or a.is_private or a.is_loopback or a.is_link_local
-                                or a.is_multicast or a.is_unspecified)
-
-
-def resolve_public(host):
-    """host's addresses for port 443, if every address it has is public; else SourceError."""
-    try:
-        addresses = socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM)
-    except (OSError, UnicodeError) as e:
-        raise SourceError('Could not find the download server ' + host) from e
-    if not addresses or not all(public_address(a[4][0]) for a in addresses):
-        raise SourceError('The download server is on a private network address; refused')
-    found = []
-    for a in addresses:
-        if a[4][:2] not in found:
-            found.append(a[4][:2])
-    return found
-
-
-CONNECT_BUDGET = 20  # seconds for connecting, all addresses and TLS handshakes together
-
-
-def _public_connection(host, timeout, budget=CONNECT_BUDGET):
-    """A verified TLS connection to host:443, made to an address checked to be public.
-
-    Each checked address is tried in turn, all within one deadline (budget, or timeout if
-    shorter) covering both connecting and the handshake. The one connected to is always one
-    that was checked, so a second lookup can't swap in another. timeout is for reads after."""
-    deadline = time.monotonic() + min(budget, timeout)
-    error = None
-    for address in resolve_public(host):
-        if time.monotonic() >= deadline:
-            break
-        try:
-            return _connect(host, address, timeout, deadline)
-        except OSError as e:  # unreachable, refused, or its TLS failed: try the next one
-            error = e
-    raise error or socket.timeout('Timed out connecting to ' + host)
-
-
-def _connect(host, address, timeout, deadline):
-    """TLS to exactly address, verified as host, connected and handshaken before deadline
-    (a time.monotonic() value); reads then get timeout seconds each."""
-    def remaining():
-        left = deadline - time.monotonic()
-        if left <= 0:
-            raise socket.timeout('Timed out connecting to ' + host)
-        return left
-    sock = socket.create_connection(address, timeout=remaining())
-    try:
-        # Each step gets what is left of the deadline as its socket timeout. A handshake
-        # read as several receives could in theory run past it by one timeout; no thread
-        # is kept to cut it short, as one could fire after the connection was handed over.
-        sock.settimeout(remaining())
-        sock = ssl.create_default_context().wrap_socket(sock, server_hostname=host,
-                                                        do_handshake_on_connect=False)
-        sock.settimeout(remaining())
-        sock.do_handshake()
-        sock.settimeout(timeout)
-    except BaseException:
-        sock.close()
-        raise
-    conn = http.client.HTTPConnection(host, 443, timeout=timeout)
-    conn.sock = sock
-    return conn
-
-
-def public_apk(url, name, redirects=3, timeout=60, check=None):
-    """Download an APK from a public HTTPS host that no source lists in advance (itch.io's
-    storage). No credentials are sent. Every hop, redirects included, is re-checked, and
-    check(url), if given, runs on each hop before any lookup or connection (it raises)."""
-    for _ in range(redirects + 1):
-        if check:
-            check(url)
-        try:
-            p = urllib.parse.urlsplit(url)
-            port = p.port
-        except (ValueError, TypeError) as e:
-            raise SourceError(name + ' returned an invalid download URL') from e
-        if p.scheme != 'https' or not p.hostname or p.username or p.password or port not in (None, 443):
-            raise SourceError(name + ' returned an unexpected download URL')
-        wait = wait_time(url)
-        if wait:
-            raise limited_error(name, wait)
-        try:
-            conn = _public_connection(p.hostname, timeout)
-        except OSError as e:
-            raise SourceError('Could not download APK: ' + str(e)) from e
-        try:
-            conn.request('GET', (p.path or '/') + ('?' + p.query if p.query else ''), headers={'User-Agent': UA})
-            r = conn.getresponse()
-            if r.status in (301, 302, 303, 307, 308):
-                url = urllib.parse.urljoin(url, r.getheader('Location') or '')
-                continue
-            if r.status == 429:
-                raise limited_error(name, throttle(url, r.headers))
-            if r.status != 200:
-                raise SourceError("%s's download server refused the file (HTTP %d); try again later"
-                                  % (name, r.status))
-            return save_apk(r)
-        except (OSError, ValueError, http.client.HTTPException, zipfile.BadZipFile) as e:
-            raise SourceError('Could not download APK: ' + str(e)) from e
-        finally:
-            conn.close()
-    raise SourceError(name + ' redirected the download too many times')
+    finally:
+        if tmp and os.path.exists(tmp):
+            os.remove(tmp)

ui/apk_sources/itch.py

@@ -1,35 +1,17 @@
-"""Free Android VR RSS listings, plus the Android builds of games the user owns.
-
-The free feeds' download pages stay in the publisher's UI. Owned games appear only
-after the user connects their itch.io account with an API key (_itch_account.py);
-they download through itch.io's own API, with the download key of that purchase.
-"""
+"""Free Android VR RSS listings. Download pages stay in the publisher's UI."""
 import html, re, urllib.parse, xml.etree.ElementTree as ET
 from email.utils import parsedate_to_datetime
 
-from . import SourceError, _itch_account, _web
+from . import SourceError, _web
 
 KIND = 'itch'
 FEEDS = ('openxr', 'oculus-quest')
-OWNED = 'itch-owned'
-OWNED_LABEL = 'Owned on itch.io'
 
 
 def sources():
-    found = [{'id': KIND if tag == 'openxr' else 'itch-quest', 'kind': KIND,
-              'name': 'itch.io (' + tag + ')', 'url': 'https://itch.io', 'tag': tag,
-              'builtin': True, 'enabled': True, 'trust': 'community'} for tag in FEEDS]
-    if _itch_account.connected():
-        found.append({'id': OWNED, 'kind': KIND, 'name': 'itch.io (my purchases)',
-                      'url': 'https://itch.io/my-purchases', 'owned': True,
-                      'description': 'Android builds of games you own on itch.io',
-                      'builtin': True, 'enabled': True, 'trust': 'user'})
-    return found
-
-
-def _itch_page(url):
-    p = urllib.parse.urlsplit(url if isinstance(url, str) else '')
-    return p.scheme == 'https' and (p.hostname or '').endswith('.itch.io') and not p.username and ':' not in p.netloc
+    return [{'id': KIND if tag == 'openxr' else 'itch-quest', 'kind': KIND,
+             'name': 'itch.io (' + tag + ')', 'url': 'https://itch.io', 'tag': tag,
+             'builtin': True, 'enabled': True, 'trust': 'community'} for tag in FEEDS]
 
 
 def _parse(source, data):
@@ -40,7 +22,8 @@ def _parse(source, data):
     entries = []
     for item in root.findall('./channel/item'):
         page = item.findtext('link') or ''
-        if not _itch_page(page):
+        p = urllib.parse.urlsplit(page)
+        if p.scheme != 'https' or not (p.hostname or '').endswith('.itch.io') or p.username or ':' in p.netloc:
             continue
         if item.findtext('price') != '$0.00' or item.findtext('platforms/android') != 'yes':
             continue
@@ -62,81 +45,23 @@ def _parse(source, data):
     return entries
 
 
-def _owned_entry(source, key):
-    """Entry for one owned download key, or None if its game isn't for Android."""
-    game = key.get('game') if isinstance(key.get('game'), dict) else {}
-    game_id = key.get('game_id') or game.get('id')
-    if type(game_id) is not int or type(key.get('id')) is not int:
-        return None
-    traits = game.get('traits')
-    if isinstance(traits, list) and 'p_android' not in traits:
-        return None  # the game's page offers no Android download
-    cover = game.get('cover_url') if isinstance(game.get('cover_url'), str) else None
-    if cover and not cover.startswith('https://img.itch.zone/'):
-        cover = None
-    user = game.get('user') if isinstance(game.get('user'), dict) else {}
-    price = game.get('min_price')
-    return {'source': source['id'], 'id': str(game_id), 'package': None,
-            'name': str(game.get('title') or 'itch.io game ' + str(game_id)),
-            'summary': str(game.get('short_text') or OWNED_LABEL),
-            'developer': user.get('display_name') or user.get('username'),
-            'icon': cover, 'images': {'icon': cover, 'banner': cover, 'screenshots': []},
-            'page': game['url'] if _itch_page(game.get('url')) else None,
-            'version': None, 'version_code': None, 'min_sdk': None, 'abis': None,
-            'vr': None, 'size': None, 'free': price == 0 if type(price) is int else None,
-            'owned': True, 'owned_label': OWNED_LABEL, 'license': None,
-            'updated': str(game.get('published_at') or '')[:10] or None,
-            'downloadable': None, 'download_key_id': key['id']}
-
-
-def _owned(source):
-    entries = {}
-    for key in _itch_account.owned_keys():
-        entry = _owned_entry(source, key)
-        if entry:
-            entries.setdefault(entry['id'], entry)  # keys come newest first; one entry per game
-    return entries
-
-
 def search(source, query, limit=50):
     limit = max(0, min(int(limit), 100))
     if not limit:
         return []
-    if source.get('owned'):
-        entries = _owned(source)
-    else:
-        entries = {}
-        tag = source.get('tag', 'openxr')
-        if tag not in FEEDS:
-            raise SourceError('Unsupported itch.io feed')
-        url = 'https://itch.io/games/free/platform-android/tag-' + tag + '.xml'
-        for entry in _parse(source, _web.read(url, ('itch.io',), name='itch.io')):
-            entries.setdefault(entry['id'], entry)
+    entries = {}
+    tag = source.get('tag', 'openxr')
+    if tag not in FEEDS:
+        raise SourceError('Unsupported itch.io feed')
+    url = 'https://itch.io/games/free/platform-android/tag-' + tag + '.xml'
+    for entry in _parse(source, _web.read(url, ('itch.io',), name='itch.io')):
+        entries.setdefault(entry['id'], entry)
     words = query.lower().split()
     return [e for e in entries.values() if all(w in (e['name'] + ' ' + e['summary']).lower()
                                                for w in words)][:limit]
 
 
-def _owned_details(source, entry_id):
-    entry = _owned(source).get(str(entry_id))
-    if not entry:
-        raise SourceError('This game is not among the Android games you own on itch.io')
-    uploads = _itch_account.uploads(int(entry['id']), entry['download_key_id'])
-    versions = [{'version': str(u.get('display_name') or u.get('filename') or u['id']), 'version_code': None,
-                 'upload_id': u['id'], 'name': u.get('filename'), 'min_sdk': None,
-                 'demo': u.get('demo') is True or 'demo' in (u.get('traits') or []),
-                 'size': u.get('size') if type(u.get('size')) is int else None,
-                 'updated': str(u.get('updated_at') or u.get('created_at') or '')[:10] or None}
-                for u in _itch_account.android_uploads(uploads)]
-    entry = dict(entry, versions=versions, downloadable=bool(versions))
-    if versions:
-        entry.update({k: versions[0][k] for k in ('version', 'size', 'updated')})
-    return entry
-
-
 def details(source, entry_id):
-    if source.get('owned'):
-        return _owned_details(source, entry_id)
     entry = next((e for e in search(source, '', 100) if e['id'] == entry_id), None)
     if not entry:
         raise SourceError('Game is not in the current free Android VR feed; open its publisher page')
@@ -144,11 +69,4 @@ def details(source, entry_id):
 
 
 def download(source, entry_id, version_code=None):
-    if not source.get('owned'):
-        raise SourceError('Open the itch.io publisher page to download; automated download pages are disallowed by robots rules')
-    if version_code is not None:
-        raise SourceError('itch.io does not publish Android version codes; download the latest upload')
-    entry = _owned_details(source, entry_id)
-    if not entry['versions']:
-        raise SourceError('This game has no Android download on itch.io')
-    return _itch_account.download(entry['versions'][0]['upload_id'], entry['download_key_id'])
+    raise SourceError('Open the itch.io publisher page to download; automated download pages are disallowed by robots rules')

ui/apk_sources/search.py

@@ -190,10 +190,7 @@ def group(entries, query='', vr=None, installable=False):
     groups = {}
     for entry in entries:
         entry = decorate(entry)
-        # Unknown counts as flat, except the user's own purchases (itch.io doesn't say which are
-        # VR): those show under either choice rather than vanish from one.
-        if vr is not None and (entry.get('vr') is True) != vr \
-                and not (entry.get('owned') is True and entry.get('vr') is None):
+        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:
             continue
@@ -226,11 +223,6 @@ def group(entries, query='', vr=None, installable=False):
     return result
 
 
-def obtainable(source, entry):
-    """Free, or a game the user owns, listed by their own account's source (itch.io purchases)."""
-    return entry.get('free') is True or (source.get('owned') is True and entry.get('owned') is True)
-
-
 def _launch(module, source, query, limit):
     """One search per source at a time; the newest different query runs next."""
     key = source['id']
@@ -259,7 +251,7 @@ def _start(key, task):
         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 obtainable(source, e)]
+                               for e in module.search(source, query, limit=limit) if e.get('free') is True]
             task['stale'] = bool(getattr(module, 'stale', lambda s: False)(source))
         except Exception as e:
             task['error'] = str(e)
@@ -316,7 +308,7 @@ def install(source_id, entry_id, version_code=None, progress=None):
     if not source['enabled']:
         raise SourceError('This source is disabled')
     entry = module.details(source, entry_id)
-    if not obtainable(source, entry) or entry.get('downloadable') is not True:
+    if entry.get('free') is not True or entry.get('downloadable') is not True:
         raise SourceError('This app must be obtained from its developer page')
     if progress:
         progress('Downloading', None)

ui/frame_devices.py

@@ -740,9 +740,7 @@ 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="", 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."""
+    def add_address(self, device_id, host, kind=None, label=""):
         with self._changing():
             d = self._find(device_id)
             a = new_address(host, kind, label)
@@ -750,7 +748,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"].insert(0 if first else len(d["addresses"]), a)
+            d["addresses"].append(a)
             self.save()
             return copy.deepcopy(a)
 

ui/frame_link.py

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

ui/server.py

@@ -46,7 +46,6 @@ import frame_assistant  # noqa: E402
 import frame_android  # noqa: E402
 from apk_sources import search as apk_search, SourceError  # noqa: E402
 from apk_sources import fdroid as apk_fdroid  # noqa: E402
-from apk_sources import _itch_account as itch_account  # noqa: E402
 import frame_apk_versions  # noqa: E402
 import frame_catalog  # noqa: E402
 import frame_devices  # noqa: E402
@@ -2494,13 +2493,6 @@ def source_manage(body):
         if action == 'remove':
             apk_search.manage_repo('remove_repo', source_id=source_text(body, 'source'))
             return {'message': 'Repository removed'}
-        if action == 'itch-connect':  # the key is checked with itch.io, saved 0600, never echoed
-            key = body.get('key')
-            if not isinstance(key, str) or not key.strip() or len(key) > 300:
-                raise Failure('Paste your itch.io API key', 400)
-            return itch_account.connect(key)
-        if action == 'itch-disconnect':
-            return itch_account.disconnect()
         raise Failure('Unknown source action', 400)
     except SourceError as e:
         raise Failure(str(e), 400)
@@ -2725,7 +2717,7 @@ class Handler(BaseHTTPRequestHandler):
                 except SourceError as e:
                     raise Failure(str(e), 400)
             elif path == "/api/sources":
-                self.send_json({"sources": apk_search.sources(), "itch": itch_account.status()})
+                self.send_json({"sources": apk_search.sources()})
             elif path == "/api/search":
                 self.send_json(source_search(url.query))
             elif path == "/api/apk-versions":