Merge main and preserve tracking and Windows test guidance

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

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

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

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

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

docs/devices.md

@@ -3,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.
@@ -139,7 +133,7 @@ rejects invalid types, out-of-range levels and invalid mute states before SSH.
 Other settings link to the existing forms and their validation, progress,
 confirmations and reset behavior: per-instance Android resolution/density/text,
 comfort sessions and alerts, media layouts, Mac streaming quality, privacy,
-sources and artwork. Android display links reveal the **Library** before
+sources and artwork. Android display links reveal **On your Frame** before
 scrolling to the form. Mac streaming remains searchable on all platforms, with
 its action shown only when the server is on macOS.
 
@@ -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/scripts.md

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

docs/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())

ios/scripts/make_frame_bundle.py

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

scripts/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/store-on-frame.sh

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

scripts/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/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", "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 };
 }
 
@@ -70,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");
 }
@@ -92,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_apk_artwork.py

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

tests/test_apk_search.py

@@ -122,7 +122,7 @@ class SearchTests(SettingsTest):
                     break
                 time.sleep(.01)
             self.assertTrue(arrived[1]['event'].wait(2))
-        self.assertEqual(arrived[1]['query'][:2], ('second', 50))
+        self.assertEqual(arrived[1]['query'], ('second', 50))
 
     def test_set_enabled_does_not_hold_search_lock_in_source(self):
         free = []

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

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

tests/test_devices.py

@@ -323,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_frame_android_library.py

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

tests/test_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_server.py

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

tests/test_store_categories.py

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

tests/test_tracking.py

@@ -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/_categories.py

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

ui/apk_sources/_images.py

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

ui/apk_sources/fdroid.py

@@ -26,7 +26,7 @@ from frame_apk_sign import _der_parts, _cert_key, der
 from frame_catalog import _IndexReader, _reduce_index, _sha256
 
 KIND = 'fdroid'
-CACHE_VERSION = 3  # 3: categories
+CACHE_VERSION = 2
 TMP_PREFIX = '.download-'  # in the cache folder, then the server's PID, so server.sweep_tmp can clear a stopped run's
 _LOCK = threading.RLock()  # settings only; never held while downloading
 _load_locks = {}
@@ -474,7 +474,6 @@ def _reduce(path, source):
                     name=_text(meta.get('name')) or pkg, summary=_summary(meta.get('summary')),
                     icon=images['icon'], images=images, developer=_text(meta.get('authorName')) or None,
                     page=meta.get('webSite') or source['url'], vr=None, free=True,
-                    categories=[c for c in meta.get('categories') or [] if isinstance(c, str)][:8],
                     license=meta.get('license'), downloadable=bool(latest.get('sha256')),
                     versions=versions, **{k: latest[k] for k in ('version', 'version_code', 'min_sdk', 'abis', 'size', 'updated')})
     return result
@@ -493,7 +492,6 @@ def _v1(content, path):
         localized = app.get('localized', {})
         meta = {k: _text({locale: fields[k] for locale, fields in localized.items() if fields.get(k)}) or app.get(k)
                 for k in ('name', 'summary', 'license', 'webSite', 'authorName')}
-        meta['categories'] = app.get('categories') or []
         for field in ('icon', 'featureGraphic', 'phoneScreenshots', 'sevenInchScreenshots'):
             images = {}
             for locale, fields in localized.items():
@@ -686,39 +684,16 @@ def set_enabled(source_id, enabled):
         _write(_storage(), settings)
 
 
-def _showcase(a):
-    """Browse order without a query: apps with real artwork first, then the most recently updated."""
-    images = a.get('images') or {}
-    return (not images.get('banner'), not images.get('screenshots'), not images.get('icon'),
-            ''.join(chr(0x10ffff - ord(c)) for c in str(a.get('updated') or '')))
-
-
-def search(source, query, limit=50, keep=None):
-    """keep: optional filter applied before the limit (the store's category browse)."""
+def search(source, query, limit=50):
     if not source.get('enabled', True):
         return []
     apps, _ = _load(source)
     words = query.casefold().split()
-    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)
-             and (keep is None or keep(a))]
-    if words:
-        found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
-    else:
-        found.sort(key=_showcase)
+    found = [a for a in apps.values() if all(w in (a['id'] + ' ' + a['name'] + ' ' + a['summary']).casefold() for w in words)]
+    found.sort(key=lambda a: (a['id'].casefold() != query.casefold(), a['name'].casefold()))
     return [{k: v for k, v in a.items() if k != 'versions'} for a in found[:max(0, limit)]]
 
 
-def lookup(source, packages):
-    """Entries for these packages from the saved index only (never downloads); missing ones are left out."""
-    if not source.get('enabled', True):
-        return {}
-    found = _cached(source, frame_host.cache_dir('apk-sources', source['id'] + '.json'))
-    if not found:
-        return {}
-    apps = found[0]
-    return {p: {k: v for k, v in apps[p].items() if k != 'versions'} for p in packages if p in apps}
-
-
 def details(source, entry_id):
     if not source.get('enabled', True):
         raise SourceError('repository is disabled')

ui/apk_sources/search.py

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

ui/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

@@ -2429,14 +2429,11 @@ def source_search(query):
     q = args.get('q', [''])[0]
     vr = args.get('vr', [''])[0]
     installable = args.get('installable', [''])[0]
-    category, phone = args.get('category', [''])[0], args.get('phone', [''])[0]
-    if (len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0')
-            or phone not in ('', 'true', 'false', '1', '0') or len(category) > 40):
+    if len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '0'):
         raise Failure('Invalid search filters', 400)
     try:
         return apk_search.search(q, vr=None if not vr else vr in ('true', '1'),
-                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'),
-                                 category=category or None, phone=phone in ('true', '1'))
+                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'))
     except SourceError as e:
         raise Failure(str(e), 400)
 
@@ -2680,9 +2677,6 @@ class Handler(BaseHTTPRequestHandler):
         try:
             if path in ("/", "/index.html"):
                 self.send_bytes((HERE / "index.html").read_bytes(), "text/html; charset=utf-8")
-            elif path == "/store":
-                # The Android store as a headset panel (scripts/store-on-frame.sh).
-                self.send_bytes((HERE / "store.html").read_bytes(), "text/html; charset=utf-8")
             elif path == "/api/settings/artwork":
                 self.send_json(frame_steamgriddb.settings())
             elif path == "/artwork-settings.js":
@@ -2732,12 +2726,7 @@ class Handler(BaseHTTPRequestHandler):
                 ensure_master()
                 apps = frame_android.list_apps()
                 backfill_art(apps=apps)
-                try:  # store artwork for the library's cards, from saved indexes only
-                    art = apk_search.artwork_for(apps)
-                except Exception:
-                    art = {}
-                self.send_json({"apps": [dict(a, store_art=art[a['package']]) if a.get('package') in art else a
-                                         for a in apps]})
+                self.send_json({"apps": apps})
             elif path == "/api/quest":
                 self.send_json(quest_status(url.query))
             elif path == "/api/meta":

ui/store.html

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