fix(ui): reconcile PR 97 with current main

Make the Android store look and read like the rest of the app

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

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

README.md

@@ -189,7 +189,7 @@ entry to `~/.ssh/config` and keys at `~/.ssh/id_ed25519_frame` and
 
 This is a first public test, so reports are really useful, especially from
 Windows and Linux. The quickest way is **Report a problem** in the app (the
-warning-sign button at the top, or **Help → Report a Problem…**). It adds
+speech-bubble button at the top, or **Help → Report a Problem…**). It adds
 diagnostics with personal details removed, shows you exactly what's included,
 and sends it privately to the maintainer; nothing is published. Without the app,
 use the [feedback form](https://frame-control.pages.dev/feedback/). Please include:
@@ -223,7 +223,6 @@ Frame's software fits together, all checked against a real headset and labelled
 | [SSH](docs/ssh.md) · [Streaming](docs/streaming.md) · [Files](docs/file-transfer.md) · [Panels](docs/panels.md) · [Tailscale](docs/tailscale.md) | Topic notes |
 | [Frame Control for iPhone](docs/iphone.md) | The iPhone and iPad app, how it runs the server on the Frame, pairing |
 | [Recovery and OS images](docs/recovery-and-images.md) | Where to download the Frame's OS, what's inside, testing without the headset |
-| [Eye tracking and heart rate](docs/tracking.md) | Our OpenXR → OSC bridge, BlueZ heart-rate panel and optional local session log; SlimeVR feasibility notes |
 | [AI agents and assistant](docs/agents.md) | Key-free MCP tools, human approvals, and an opt-in assistant panel |
 | [Testing](docs/testing.md) | Unit tests, end-to-end tests against a fake Frame in Docker, the headset smoke test and a Windows test VM |
 | [Open questions](docs/open-questions.md) | What's still unchecked |

docs/agents.md

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

docs/apks.md

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

docs/devices.md

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

docs/family-comfort.md

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

docs/frame-control.md

@@ -17,15 +17,21 @@ python3 ui/server.py         # anywhere: then open http://127.0.0.1:47810
 
 ## Features
 
-The window has six tabs: **Home** (headset view, status, screenshots),
-**Games** (installed games, sideloaded titles, getting games), **Android** (apps,
-the catalogue, display settings, reports), **Tools** (sending files and text,
-Flatpaks, remote and power), **Devices** (your headsets and their addresses),
-and **Control** (the searchable Control Center, metrics, supported settings and
-headset guidance). Keys 1–6 switch between them. Files can be dropped anywhere in the window. A
-connection pill in the header always shows which headset, which network this
-computer is on, the address in use or being tried, and each step of connecting
-as it happens; click it for the whole timeline. When the Frame can't be
+The window has six tabs: **Home** (what the headset's doing and what you'd do
+next, the headset view, screenshots, family and comfort, the keyboard and
+trackpad, and VR performance, folded away), **Games** (installed games,
+sideloaded titles, getting games), **Android** (apps, the catalogue, display
+settings, reports), **Tools** (in the headset: your computer's windows, the media
+player and the panel switcher; then sending files and text, Flatpaks, remote and
+power), **Devices** (your headsets and their addresses), and **Control** (the
+searchable Control Center, metrics, supported settings and headset guidance).
+Keys 1–6 switch between them. The gear in the header (key 7) opens **Settings**:
+privacy and updates, library artwork and the assistant. The battery chip opens
+the headset's details: storage, memory, temperature, Wi-Fi, uptime and SteamOS
+build. Files can be dropped anywhere in the window. A
+connection pill in the header always shows which headset and whether it's
+connected, and how (Tailscale, or the network's name). Click it to add, edit or
+reorder the headset's addresses, or to see each step of connecting. When the Frame can't be
 reached, a banner says why in plain words, what was tried, and counts down to
 the next try, filling everything in once it answers. Flatpak and Android installs run in the background; the bottom bar
 counts them while they run.
@@ -133,7 +139,7 @@ rejects invalid types, out-of-range levels and invalid mute states before SSH.
 Other settings link to the existing forms and their validation, progress,
 confirmations and reset behavior: per-instance Android resolution/density/text,
 comfort sessions and alerts, media layouts, Mac streaming quality, privacy,
-sources and artwork. Android display links reveal **On your Frame** before
+sources and artwork. Android display links reveal the **Library** before
 scrolling to the form. Mac streaming remains searchable on all platforms, with
 its action shown only when the server is on macOS.
 
@@ -239,5 +245,5 @@ Control implementations. MCP wraps this HTTP API without API keys. Changes
 require a separate user approval; power also retains its password prompt. The
 assistant uses a user-chosen endpoint and sends nothing until the user opts in
 for a message. Screenshot context is separately opt-in. Model replies cannot
-operate the headset. Tools → Open assistant opens the page; the linked guide
+operate the headset. Settings → Open assistant settings opens the page; the linked guide
 covers putting it in a Chromium panel on the Frame.

docs/how-the-frame-works.md

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

docs/iphone.md

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

docs/panels.md

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

docs/privacy.md

@@ -132,8 +132,8 @@ runs.
 
 ## Report a problem
 
-**Report a problem** is the warning-sign button in the header, also in the
-Privacy panel and under **Help → Report a Problem…**. It sends the report
+**Report a problem** is the speech-bubble button in the header, also in the
+Settings page (**Privacy & updates**) and under **Help → Report a Problem…**. It sends the report
 privately to Frame Control's PostHog project as a `problem_report` event, the
 same way as the analytics above, so only the maintainer can read it and
 nothing is published. It works whatever the analytics settings are, because

docs/scripts.md

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

docs/sidequest.md

@@ -65,6 +65,8 @@ flow, not evidence of an anonymous download API. It is not implemented here.
 - `search()` raises a user-readable `SourceError` with the browse URL (zero
   limit returns no rows). It does not invent app results or report a false
   “no matching games”. The aggregate search UI should surface this source error.
+  In the app, Discover doesn't link to it; the **Sources** dialog lists SideQuest
+  with a link to its website instead of an on/off switch.
 - `details()` accepts a numeric listing id and returns its canonical page link,
   `downloadable: False`, empty versions/tags/headsets and the `images` shape
   `{icon: None, banner: None, screenshots: []}`. Name is explicitly a listing id;

docs/testing.md

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

docs/tracking.md

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

docs/vr-apks.md

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

docs/vr-utilities.md

@@ -11,7 +11,7 @@ checks below. The PR stays draft.
 
 ## Our performance HUD
 
-On **Home → VR comfort and performance**, the app shows a timestamped sample
+On **Home → VR performance** (folded until you open it), the app shows a timestamped sample
 with each status refresh (30 seconds, or Refresh). **Open HUD in headset**
 starts our text HUD as a gamescope panel, refreshed every two seconds. In the
 SteamVR dashboard, select **Frame Control HUD**, then Float in World or dock
@@ -26,7 +26,7 @@ it twice reuses the existing process.
 | Compositor CPU | OpenVR compositor render CPU milliseconds, not game CPU time. |
 | System CPU | `/proc/stat` busy-time delta across the sample, with guest time counted once and iowait treated as idle. |
 | GPU clock | `3d00000.gpu/cur_freq`, converted from Hz to MHz; frequency is not load. |
-| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. |
+| Hottest sensor / battery | Existing thermal-zone and battery sysfs reads from `frame_status.py`. In the headset HUD only: the app shows them once, in the battery menu at the top. |
 
 OpenVR uses background application mode, which does not start SteamVR or keep
 it running. This mode also returned live timing in a read-only device probe.

docs/vr-video.md

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

frame/tracking/gaze.c

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

frame/tracking/pulse.py

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

frame/tracking/tracking.py

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

ios/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/*", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
+PATTERNS = ["ui/*.py", "ui/*.html", "ui/*.js", "ui/*.css", "ui/local-bin/*", "ui/apk_sources/*.py", "ui/apk_sources/*.json", "scripts/*.sh", "frame/android/*.sh", "frame/android/*.py",
             "frame/devkit-utils/**/*", "apk-catalog/*.py", "apk-catalog/pins.json", "apk-catalog/site/apps.js",
             "frame/kdeconnect/packages.json", "frame/kdeconnect/NOTICE.md", "frame/kdeconnect/LICENSES/*/*",
             "frame/kdeconnect/packages/*.pkg.tar.zst", "LICENSE", "THIRD_PARTY_NOTICES.md"]

scripts/heart-check.py

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

scripts/heart-test-strap.swift

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

scripts/store-on-frame.sh

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

scripts/tracking-on-frame.py

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

tests/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(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
+      resetShots(){},closeDevPop(){},loadDevices(){},renderDevices(){},renderTests(){},reloadAll(){},checkContactPrompt(){}});
     vm.runInContext(`const UI_KEY = 'test-only';
       const link = {s:null,device:'frame-a',phase:'connected',rev:0,net:null};
       const disp = {}, gm = {seq:0}, cat = {}, wi = {};
@@ -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'].map(page=>({dataset:{page},classList:{toggle(key,on){if(on)activePage=page;}}}));
+  const nodes=['home','games','android','tools','devices','control','settings'].map(page=>({dataset:{page},classList:{toggle(key,on){if(on)activePage=page;}}}));
   const sections=new Map();
   const context={location:{hash:'#control'},document:{querySelectorAll:s=>s==='.page'?nodes:[],title:''},
     window:{scrollTo(){}},$:id=>{
       if(!ids.has(id))return null;
-      if(!sections.has(id))sections.set(id,{hidden:false,scrollIntoView(){scrolled=id;}});
+      if(!sections.has(id))sections.set(id,{hidden:false,classList:{toggle(){}},scrollIntoView(){scrolled=id;}});
       return sections.get(id);
-    },live:false,toggleLive(){},loadMacView(){},loadPanelSwitcher(){}};
+    },live:false,toggleLive(){},scrollToY(){},loadMacView(){},loadPanelSwitcher(){}};
   const androidStart=html.indexOf('function showAndroidTab(');
   const androidEnd=html.indexOf("document.querySelectorAll('[data-store-tab]').forEach(button => button.onclick",androidStart);
-  vm.createContext(context);vm.runInContext(html.slice(androidStart,androidEnd)+html.slice(start,end)+'\nPAGES.push("devices", "control");',context);
+  vm.createContext(context);vm.runInContext(html.slice(androidStart,androidEnd)+html.slice(start,end)+'\n'+html.match(/^PAGES\.push\([^\n]+/m)[0],context);
   vm.runInContext('showPage()',context);assert.equal(activePage,'control');
   const expected={view:'home',shots:'home',vrTools:'home',comfort:'home',pad:'home',library:'games',getgames:'games',sideloaded:'games',android:'android',display:'android',androidLibrary:'android',appStore:'android',
-    power:'tools',transfer:'tools',media:'tools',apps:'tools',artworkSettings:'tools',privacy:'tools',panels:'tools',macview:'tools',devices:'devices'};
+    power:'tools',transfer:'tools',media:'tools',apps:'tools',artworkSettings:'settings',privacy:'settings',panels:'tools',macview:'tools',devices:'devices'};
   for(const item of cc.catalog) for(const [href] of item.links||[]) {
     if(!href.startsWith('#')||href==='#connection')continue;
     const id=href.slice(1);assert.ok(ids.has(id)||['android','devices'].includes(id),href);
@@ -468,4 +468,5 @@ 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",
-               "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
-               "updateInstall", "openStoreApp", "loadOfferDetails"];
+               "GLYPH_VR", "GLYPH_APP", "RUNS", "storeRuns", "storeKind", "storeArt", "storeIcon", "sourceMark", "currentOffer", "detailBadges", "renderAppDetail", "renderAppDetailBody",
+               "updateInstall", "openStoreApp", "loadOfferDetails", "installStoreApp"];
 const code = names.map(grab).join("");
 
 // A fake page: elements by id. The install panel's elements exist only while
@@ -34,8 +34,10 @@ function page(api = async () => ({})) {
   const document = { activeElement: null, querySelector: () => null };
   const console = { error() {} };
   const calls = [];
-  const fns = new Function("$", "sourceState", "document", "console", "api", code + "; return { renderAppDetail, openStoreApp };")(
-    $, sourceState, document, console, (...a) => { calls.push(a); return api(...a); });
+  const fns = new Function("$", "sourceState", "document", "console", "api", "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"); } });
   return { els, sourceState, calls, ...fns };
 }
 
@@ -68,7 +70,7 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
 {
   const p = page(async () => { throw new Error("offline"); });
   p.sourceState.apps = [{ name: "Broken", offers: [] }];
-  await p.openStoreApp(0);
+  await p.openStoreApp(0, true);
   if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes('role="alert"')) fail("broken listing didn't open with the error");
   if (p.calls.length) fail("asked for details of a listing that couldn't render");
 }
@@ -90,4 +92,18 @@ const offer = { source: "fdroid", id: "org.example.brush", source_name: "F-Droid
   if (!p.els.detailBody.innerHTML.includes('id="detailTitle">Open Brush<')) fail("page lost after a failed details request");
   if (!p.els.detailInstallNote.textContent.includes("couldn't be refreshed")) fail("no note after a failed details request");
 }
+// The featured Install starts a new or failed job, while a job already running or
+// installed opens its details without another install or a launch command.
+for (const [job, expected] of [[null, 1], [{ done: false }, 0],
+    [{ done: true, result: { package: offer.package } }, 0], [{ done: true, error: "offline" }, 1]]) {
+  const p = page(async path => path === "/api/sources/install" ? { package: offer.package } : {});
+  p.sourceState.apps = [{ name: "Open Brush", offers: [{ ...offer }] }];
+  if (job) p.sourceState.jobs.set(`${offer.source}:${offer.id}`, job);
+  await p.openStoreApp(0, true);
+  if (!p.els.appDetail.open || !p.els.detailBody.innerHTML.includes('id="detailInstall"')) fail("hero installation didn't open details");
+  const installs = p.calls.filter(([path]) => path === "/api/sources/install");
+  if (installs.length !== expected) fail(`expected ${expected} installation requests, got ${installs.length}`);
+  if (installs.some(([, body]) => body.source !== offer.source || body.id !== offer.id)) fail("installed a different offer");
+  if (p.calls.some(([path]) => path === "/api/android")) fail("hero Install launched an already installed app");
+}
 console.log("ok");

tests/test_apk_artwork.py

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

tests/test_apk_search.py

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

tests/test_comfort_ui.py

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

tests/test_control_center.py

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

tests/test_devices.py

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

tests/test_frame_android_library.py

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

tests/test_link.py

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

tests/test_link_ui.py

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

tests/test_page_scripts.py

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

tests/test_page_startup.py

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

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

tests/test_server.py

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

tests/test_store_categories.py

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

tests/test_tracking.py

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

ui/apk_sources/_categories.py

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

ui/apk_sources/_images.py

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

ui/apk_sources/fdroid.py

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

ui/apk_sources/search.py

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

ui/frame_devices.py

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

ui/frame_link.py

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

ui/server.py

@@ -2429,11 +2429,14 @@ def source_search(query):
     q = args.get('q', [''])[0]
     vr = args.get('vr', [''])[0]
     installable = args.get('installable', [''])[0]
-    if len(q) > 500 or vr not in ('', 'true', 'false', '1', '0') or installable not in ('', 'true', 'false', '1', '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):
         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'))
+                                 source=args.get('source', [None])[0], installable=installable in ('true', '1'),
+                                 category=category or None, phone=phone in ('true', '1'))
     except SourceError as e:
         raise Failure(str(e), 400)
 
@@ -2677,6 +2680,9 @@ 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":
@@ -2726,7 +2732,12 @@ class Handler(BaseHTTPRequestHandler):
                 ensure_master()
                 apps = frame_android.list_apps()
                 backfill_art(apps=apps)
-                self.send_json({"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]})
             elif path == "/api/quest":
                 self.send_json(quest_status(url.query))
             elif path == "/api/meta":

ui/store.html

@@ -0,0 +1,489 @@
+<!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>