Merge pin-combo-fix: Display Settings pins the chosen screen and keeps its rows in place

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

README.md

@@ -35,7 +35,7 @@ You need a Steam Frame with an internet connection, a keyboard (Bluetooth, or th
 
    It asks which version you want: stable (the `main` branch, tested releases) or experimental (the `experimental` branch, the newest features, less tested). Then it clones the repo into `~/frametop` and runs `install.sh`. To choose without the question, add `-s -- --stable` or `-s -- --experimental` after `bash`. By hand, the same is `git clone https://github.com/Frametop/frametop.git ~/frametop`, then `cd ~/frametop` and `./install.sh` (add `--branch experimental` to the clone for experimental).
 
-   The third and fourth choices, stable release and experimental release, download Frametop already built (`Frametop.zip`, about 1.4 GB, from the [releases](https://github.com/Frametop/frametop/releases)) and install it without compiling anything. `-s -- --release` picks the stable release without the question, and `-s -- --release --experimental` the experimental one.
+   The third and fourth choices, stable release and experimental release, download Frametop already built (`Frametop.zip`, about 1.2 GB, from the [releases](https://github.com/Frametop/frametop/releases)) and install it without compiling anything. `-s -- --release` picks the stable release without the question, and `-s -- --release --experimental` the experimental one.
 
    The installer sets up distrobox in your home folder (the system files aren't touched), a Fedora build container, and everything else. The first run downloads 1–2 GB. It asks along the way whether to install each optional part: voice dictation (yes by default; it downloads about 320 MB of speech models), hand tracking (experimental, yes by default), in a release the [Hand Recorder](https://frametop.github.io/frametop/hand-recorder) (yes by default; it records your hands for Frametop's open hand dataset), gaze mode (experimental, yes by default), our own eye tracker for it (yes by default), in a release the Eye Recorder (yes by default, with our eye tracker; it records your eyes for Frametop's eye tracking dataset), and the Bluetooth fixes, then whether to restart SteamVR. The stable version asks only about gaze mode, the eye tracker, and the Bluetooth fixes. Hand tracking, the Hand Recorder, the eye tracker, and the Bluetooth fixes need your `sudo` password; if you've never set one, run `passwd` first, or skip them for now. SteamVR has to restart once at the end, which closes everything open in VR, including the terminal. Rebooting the headset works too.
 

display-settings/main.qml

@@ -868,15 +868,21 @@ Kirigami.ApplicationWindow {
 
                     Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Screens shown" }
 
+                    // Counts as models, here and in Pinned screens: a new list rebuilds the rows, and
+                    // FormLayout puts rebuilt rows after the ones below (a report: pinning a screen
+                    // moved the wrist slider and All screens up between Screen 2 and Screen 3).
                     Repeater {
-                        model: backend.screensShown
+                        model: backend.screensShown.length
                         delegate: Controls.Switch {
-                            required property var modelData
+                            id: shownSwitch
                             required property int index
                             Kirigami.FormData.label: "Screen " + (index + 1) + ":"
-                            text: modelData ? "Shown" : "Hidden"
-                            checked: modelData
-                            onToggled: backend.setScreenShown(index, checked)
+                            text: checked ? "Shown" : "Hidden"
+                            checked: backend.screensShown[index]
+                            onToggled: {
+                                backend.setScreenShown(shownSwitch.index, checked)
+                                checked = Qt.binding(() => backend.screensShown[shownSwitch.index])
+                            }
                         }
                     }
                     Controls.Label {
@@ -890,10 +896,11 @@ Kirigami.ApplicationWindow {
                     Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Pinned screens" }
 
                     Repeater {
-                        model: backend.pins
+                        model: backend.pins.length
                         delegate: Controls.ComboBox {
-                            required property var modelData
+                            id: pinBox
                             required property int index
+                            readonly property int pinIndex: Math.max(0, ["none", "left", "right", "head"].indexOf(backend.pins[index]))
                             Kirigami.FormData.label: "Screen " + (index + 1) + ":"
                             model: [
                                 { text: "In the room", value: "none" },
@@ -903,8 +910,13 @@ Kirigami.ApplicationWindow {
                             ]
                             textRole: "text"
                             valueRole: "value"
-                            currentIndex: Math.max(0, ["none", "left", "right", "head"].indexOf(modelData))
-                            onActivated: backend.pin(String(index + 1), currentValue)
+                            currentIndex: pinIndex
+                            // pinBox.index: activated's own argument is also called index (the
+                            // chosen row), so a bare index sent "On your head" to screen 4.
+                            onActivated: {
+                                backend.pin(String(pinBox.index + 1), currentValue)
+                                currentIndex = Qt.binding(() => pinBox.pinIndex)  // what ft-screens has, if the pin failed
+                            }
                         }
                     }
                     RowLayout {

docs/design.md

@@ -144,7 +144,7 @@ A few overlays need special handling:
 
 Head follow is experimental and off by default. It works, but it's only lightly tested, and the feel is mostly a matter of its settings; polishing it is left open. With it on (`POINTER_FOLLOW=1`, or a mouse button mapped to Head follow on/off), the cursor rides on a reference direction, where you were facing when your head last settled, and keeps its offset from it. The mouse can put the cursor anywhere up to `POINTER_FOLLOW_REACH` (70 degrees) from the reference, a corner of your view included. While your head stays within `POINTER_LEASH_DEG` of the reference, nothing moves on its own. Once your head has been past the leash for `POINTER_LEASH_DELAY` (0.2 s, so a glance out and back doesn't count), the reference eases to where you're facing (time constant `POINTER_LEASH_RETURN`, 0.2 s), never falling further behind than the leash, and the cursor ends up back where it was in your view. Then it waits for the leash again. Two earlier versions didn't work out. Moving the reference only while your head pulled at the end of the leash left it up to the leash off after you turned back, and getting it centred again meant overshooting with your head. Easing it toward your facing all the time moved the cursor on every small head movement. A leash of 0 makes the reference your facing direction, so the cursor is locked to your view, and mouse movement shifts it within the view. Head roll is ignored, so tilting your head doesn't swing the cursor around. While the left button is held the cursor stays put in the room, so your head can't nudge a click or a drag. When you let go, it carries on from where it is instead of jumping.
 
-Gaze mode is experimental and off by default (`POINTER_GAZE=1`, the Gaze page of Frametop Input Settings, `gaze/ft-gazectl on`, or a mouse button or key combination mapped to Gaze pointer on/off). It's MAGIC pointing (Zhai, Morimoto and Ihde, 1999): the pointer goes where you look, and the mouse does the last bit. The gaze service (`gaze/ft-gazed`) sends the helper the corrected gaze at 90 Hz (from one eye while the tracker has lost the other), and while the gaze has the pointer, the cursor ray is that gaze from the eye. The pointer is aimed at the gaze each frame, not steered toward it, so nothing can pile up. An earlier try in the gaze probe steered the pointer with relative moves, and lost it when the pointer went idle or a controller had the laser. By default (`POINTER_GAZE_MOUSE_MOVE=held`, the Gaze page's Mouse movement switch) moving the mouse does nothing while the gaze has the pointer: it moves the pointer only while a button is held, as a correction. A bumped or drifting mouse can't pull the pointer off what you're looking at, and every mouse move is a correction, so the lessons aren't polluted by mouse moves to somewhere else (they used to be kept out by an 8 degree limit, which also dropped real corrections when the tracker was further off). With the gaze stale for a second, in a game, or with the headset off, the mouse moves the pointer as usual; with `free`, moving the mouse takes the pointer from the gaze. A left press while the gaze has the pointer isn't sent at once: the pointer stops where the gaze put it, you drag it onto what you meant with the button still down (panels only see it hover), and the release clicks there. Clicking at once clicked wherever the gaze was, often the wrong thing, before you could correct it. The drag is the correction. Snapping the pointer onto buttons and links is deferred: the session now starts an AT-SPI registry, but apps still need to expose useful accessibility trees (and may need restarting), and it makes Chromium and Electron apps use more CPU. A press held still for `POINTER_GAZE_HOLD` (0.5 s) becomes a real press, so drags still work: hold, then move. The right button works the same way, with the right click on the release, and pressing it while the left press is held back starts a drag where the pointer is, like Meta+J then Meta+K. That drag lasts while either button (or key) is held, so a second right press, or a second Meta+K, is free to pan and tilt the panel being dragged; with the keyboard, the head turns it. Outside games the pointer then stays: the mouse going idle doesn't release it. A moving controller still releases it, as without gaze. Gaze mode is a mouse and keyboard feature: Steam reads the Frame controllers itself, outside SteamVR's bindings, so controller clicks at the gaze kept knocking SteamVR out of laser mode (see `docs/gaze-controllers.md`). Keyboard clicks (Meta+J, Meta+K) hold the dot still in your view while the keys are down, so the head, not the mouse, does the last bit; a quick tap clicks where the dot was at the press, since the head moves as you hit the keys. The relay hides Meta from the desktop as soon as such a combination fires, because KWin takes Meta with a mouse button as a window move or resize, which swallowed the clicks. The dot shows all the time by default. With `POINTER_GAZE_DOT=moving` it shows only while the mouse moves it (`POINTER_GAZE_SHOW`), while a press is held, and as a pulse for each click; otherwise it's transparent, so the laser still lands on it. Looking more than `POINTER_GAZE_RETAKE` (5 degrees) away from it, with the mouse still, gives it back, so small eye movements around the pointer don't pull it off what you're doing. A mouse nudge before a click whose correction is within `POINTER_GAZE_NUDGE_MAX` (55 degrees, half of what the headset shows across) is sent to the gaze service as a lesson: you were looking at where you clicked when the mouse took over, so the nudge is the eye tracker's error there. Using it is what calibrates it. A one-dot check in a panel fixed to the headset tops that up when the headset goes on, when our tracker thinks it moved, and when a correction is past that limit (the tracker is far off, so a click there isn't trusted as a lesson), and the full calibration and the headset fit check run in the same panel, so everything a user does to calibrate happens in one place in the headset; the gaze probe, a fullscreen GTK app, is the development tool. The limit was 8 degrees, which dropped every correction while our tracker was 12 off. Its dots sit at known directions from the headset, so the panel needs no screen geometry. The quick check's dot takes the gaze once it has held still, so what the tracker says doesn't have to be close for the capture to work. The full calibration's and the five-dot check's dots wait for a click while you look at the dot (a left click or Meta+J), because a steady gaze isn't always on the dot, and take the gaze held still up to the click; a rightLine truncated
+Gaze mode is experimental and off by default (`POINTER_GAZE=1`, the Gaze page of Frametop Input Settings, `gaze/ft-gazectl on`, or a mouse button or key combination mapped to Gaze pointer on/off). It's MAGIC pointing (Zhai, Morimoto and Ihde, 1999): the pointer goes where you look, and the mouse does the last bit. The gaze service (`gaze/ft-gazed`) sends the helper the corrected gaze at 90 Hz (from one eye while the tracker has lost the other), and while the gaze has the pointer, the cursor ray is that gaze from the eye. The pointer is aimed at the gaze each frame, not steered toward it, so nothing can pile up. An earlier try in the gaze probe steered the pointer with relative moves, and lost it when the pointer went idle or a controller had the laser. By default (`POINTER_GAZE_MOUSE_MOVE=held`, the Gaze page's Mouse movement switch) moving the mouse does nothing while the gaze has the pointer: it moves the pointer only while a button is held, as a correction. A bumped or drifting mouse can't pull the pointer off what you're looking at, and every mouse move is a correction, so the lessons aren't polluted by mouse moves to somewhere else (they used to be kept out by an 8 degree limit, which also dropped real corrections when the tracker was further off). With the gaze stale for a second, in a game, or with the headset off, the mouse moves the pointer as usual; with `free`, moving the mouse takes the pointer from the gaze. A left press while the gaze has the pointer isn't sent at once: the pointer stops where the gaze put it, you drag it onto what you meant with the button still down (panels only see it hover), and the release clicks there. Clicking at once clicked wherever the gaze was, often the wrong thing, before you could correct it. The drag is the correction. Snapping the pointer onto buttons and links is deferred: the session now starts an AT-SPI registry, but apps still need to expose useful accessibility trees (and may need restarting), and it makes Chromium and Electron apps use more CPU. A press held still for `POINTER_GAZE_HOLD` (0.5 s) becomes a real press, so drags still work: hold, then move. The right button works the same way, with the right click on the release, and pressing it while the left press is held back starts a drag where the pointer is, like Meta+J then Meta+K. That drag lasts while either button (or key) is held, so a second right press, or a second Meta+K, is free to pan and tilt the panel being dragged; with the keyboard, the head turns it. Outside games the pointer then stays: the mouse going idle doesn't release it. A moving controller still releases it, as without gaze. Gaze mode is a mouse and keyboard feature: Steam reads the Frame controllers itself, outside SteamVR's bindings, so controller clicks at the gaze kept knocking SteamVR out of laser mode (see `docs/gaze-controllers.md`). Keyboard clicks (Meta+J, Meta+K) hold the dot still in your view while the keys are down, so the head, not the mouse, does the last bit; a quick tap clicks where the dot was at the press, since the head moves as you hit the keys. The relay hides Meta from the desktop as soon as such a combination fires, because KWin takes Meta with a mouse button as a window move or resize, which swallowed the clicks. The dot shows all the time by default. With `POINTER_GAZE_DOT=moving` it shows only while the mouse moves it (`POINTER_GAZE_SHOW`), while a press is held, and as a pulse for each click; otherwise it's transparent, so the laser still lands on it. Looking more than `POINTER_GAZE_RETAKE` (5 degrees) away from it, with the mouse still, gives it back, so small eye movements around the pointer don't pull it off what you're doing. A mouse nudge before a click whose correction is within `POINTER_GAZE_NUDGE_MAX` (55 degrees, half of what the headset shows across) is sent to the gaze service as a lesson: you were looking at where you clicked when the mouse took over, so the nudge is the eye tracker's error there. Using it is what calibrates it. A one-dot check in a panel fixed to the headset tops that up when the headset goes on, when our tracker thinks it moved, and when a correction is past that limit (the tracker is far off, so a click there isn't trusted as a lesson), and the full calibration and the headset fit check run in the same panel, so everything a user does to calibrate happens in one place in the headset; the gaze probe, a fullscreen GTK app, is the development tool. The limit was 8 degrees, which dropped every correction while our tracker was 12 off. Its dots sit at known directions from the headset, so the panel needs no screen geometry. The quick check's dot takes the gaze once it has held still, so what the tracker says doesn't have to be close for the capture to work. The full calibration's and the five-dot check's dots wait for a click while you look at the dot (a left click, Enter, an index pinch or Meta+J), because a steady gaze isn't always on the dot, and take the gaze held still uLine truncated
 
 Replacing a loaded driver's files, as re-running the installer used to do, leaves SteamVR honoring the virtual controller's hand role but not its laser claim: the dashboard pointer stays unassigned until SteamVR restarts. The driver installer now leaves an unchanged driver in place.
 

docs/reference.md

@@ -137,7 +137,7 @@ pointer/driver/install.sh probe     # devices, hand roles, activity, charging, w
 pointer/probe/build.sh              # probes: vrprobe, lasertest (who has the laser), ctlnoise (controller noise)
 ```
 
-The pointer settings are in `~/.config/frametop.conf`: `POINTER_SENSITIVITY`, `POINTER_IDLE`, `POINTER_WAKE_COUNTS`, `POINTER_CONTROLLER_PICKUP`, `POINTER_DISTANCE`, `POINTER_CURSOR_DEG`, `POINTER_ORIGIN_FRACTION`, `POINTER_ORIGIN_MARGIN`, `POINTER_SCENE_RADIUS`, `POINTER_EDGE_REACH`, `POINTER_LASER_WIDTH`, `POINTER_IGNORE`, the head follow settings `POINTER_FOLLOW`, `POINTER_LEASH_DEG`, `POINTER_LEASH_DELAY`, `POINTER_LEASH_RETURN`, and `POINTER_FOLLOW_REACH`, and the gaze mode settings `POINTER_GAZE`, `POINTER_GAZE_RETAKE`, `POINTER_GAZE_NUDGE_MAX`, `POINTER_GAZE_HOLD`, `POINTER_GAZE_CONTROL_HOLD`, `POINTER_GAZE_DOT`, `POINTER_GAZE_SHOW`, `POINTER_GAZE_MOUSE`, `POINTER_GAZE_MOUSE_MOVE`, and the keyboard clicks' `POINTER_HEAD_DEADZONE` and `POINTER_KEY_TAP`, and the gaze service's `GAZE_TRACKER` (`auto`, the default: our own eye tracker when it's installed, else SteamVR's; or `own` or `steam`), `GAZE_EYE` (the eye bias), and `GAZE_FIT_WATCH` (the put-on check and the slip note, off by default: [gaze/README.md](../gaze/README.md), "Headset fit"). The example config explains each. Frametop Input Settings changes them live; after editing the file by hand, restart the relay or the helper (the gaze service reads its three again when the file changes).
+The pointer settings are in `~/.config/frametop.conf`: `POINTER_SENSITIVITY`, `POINTER_IDLE`, `POINTER_WAKE_COUNTS`, `POINTER_CONTROLLER_PICKUP`, `POINTER_DISTANCE`, `POINTER_CURSOR_DEG`, `POINTER_ORIGIN_FRACTION`, `POINTER_ORIGIN_MARGIN`, `POINTER_SCENE_RADIUS`, `POINTER_EDGE_REACH`, `POINTER_LASER_WIDTH`, `POINTER_IGNORE`, the head follow settings `POINTER_FOLLOW`, `POINTER_LEASH_DEG`, `POINTER_LEASH_DELAY`, `POINTER_LEASH_RETURN`, and `POINTER_FOLLOW_REACH`, and the gaze mode settings `POINTER_GAZE`, `POINTER_GAZE_RETAKE`, `POINTER_GAZE_NUDGE_MAX`, `POINTER_GAZE_HOLD`, `POINTER_GAZE_CONTROL_HOLD`, `POINTER_GAZE_DOT`, `POINTER_GAZE_SHOW`, `POINTER_GAZE_MOUSE`, `POINTER_GAZE_MOUSE_MOVE`, and the keyboard clicks' `POINTER_HEAD_DEADZONE` and `POINTER_KEY_TAP`, and the gaze service's `GAZE_TRACKER` (`auto`, the default: our own eye tracker when it's installed, else SteamVR's; or `own` or `steam`), `GAZE_EYE` (the eye bias), `GAZE_FIT_WATCH` (the put-on check and the slip note, off by default: [gaze/README.md](../gaze/README.md), "Headset fit"), and `GAZE_FUSION` (our tracker's gaze mixed with SteamVR's, off by default: [gaze/README.md](../gaze/README.md), "Gaze pointer"), and our eye tracker's `EYES_SIZE_GUARD` (`both`, the default, `long`, or `off`: [gaze/README.md](../gaze/README.md), "Our own eye tracker"). The example config explains each. Frametop Input Settings changes them live; after editing the file by hand, restart the relay or the helper (the gaze service reads its four again when the file changes; ft-eyes reads `EYES_SIZE_GUARD` when it starts).
 
 ## Frametop Input Settings
 
@@ -191,11 +191,12 @@ The layout is stored relative to your head when it's applied. `/run/user/<uid>/f
 
 ## Frametop Remote Displays
 
-Other computers' monitors as Frametop screens (ft-screens only), streamed from Vibepollo or Sunshine with Moonlight's protocol. Frametop Remote Displays (`remote-displays/`, also opened by the Remote displays button on Display Settings' Screens page) finds Vibepollo and Sunshine computers on the network, signs in to one with its Web UI login (it keeps a narrow API token, not the password, and pins the host's certificate), shows whether it answers, and adds its displays: its monitors, or a virtual one at any size. A computer with a Steam Link dongle on the Frame's hotspot streams over it (Connection: auto, network or dongle only); the others use the network. Each display has a Connected switch (and the host one for all of its displays), Shown, its stream's resolution, frame rate and bitrate, and its width in VR. On Windows, a monitor switches to its stream's resolution while it streams (or its closest mode with the same shape), and back when the stream ends. That takes Frametop's build `frametop-2.0.0-2` or newer; `frametop-2.0.0-1` scaled the monitor's own resolution into the stream. A disconnected display keeps its settings, and within the same desktop run, its place. In VR each one is a panel with a screen's controls, and profiles keep where they are. See [remote-displays.md](remote-displays.md).
+Other computers' monitors as Frametop screens (ft-screens only), streamed from Vibepollo or Sunshine with Moonlight's protocol. Frametop Remote Displays (`remote-displays/`, also opened by the Remote displays button on Display Settings' Screens page) finds Vibepollo and Sunshine computers on the network, signs in to one with its Web UI login (it keeps a narrow API token, not the password, and pins the host's certificate), shows whether it answers, and adds its displays: its monitors, or a virtual one at any size. A computer with a Steam Link dongle on the Frame's hotspot streams over it (Connection: auto, network or dongle only); the others use the network. Each display has a Connected switch (and the host one for all of its displays), Shown, its stream's resolution, frame rate and bitrate, and its width in VR. On Windows, a monitor switches to its stream's resolution while it streams (or its closest mode with the same shape), and back when the stream ends. That takes Frametop's build `frametop-2.0.0-2` or newer; `frametop-2.0.0-1` scaled the monitor's own resolution into the stream. A Windows host with Frametop's build can also get the Frame's microphone (Send my microphone on its card, off by default): apps on the PC record it as "Microphone (Steam Streaming Microphone)" while its displays stream. A disconnected display keeps its settings, and within the same desktop run, its place. In VR each one is a panel with a screen's controls, and profiles keep where they are. See [remote-displays.md](remote-displays.md).
 
 ```
 layout/ft-layout remote list                 # the remote displays and their streams' state
 layout/ft-layout remote connect|disconnect ID...
+layout/ft-layout remote host NAME mic=on|off # send it the Frame's microphone (streams pick it up within 3 s)
 remote-displays/install.sh                   # its menu entry
 ```
 
@@ -308,7 +309,7 @@ In gaze mode the 3D mouse's pointer goes where you look, and the mouse or the ke
 - Meta+J left-clicks and Meta+K right-clicks where you look. A quick tap clicks where the dot was at the press. Hold instead, and the dot stays put in your view: turn your head until it's on what you meant, and let go to click there. Held still for `POINTER_GAZE_HOLD` (0.5 s), the press becomes a real one, and your head drags. Meta+K with Meta+J held presses where the dot is now, to drag from there, and a second Meta+K during that drag (a double Meta+K) pans and tilts what you're dragging while it's held.
 - The mouse's buttons work the same way, with the mouse steering instead of your head (`POINTER_GAZE_MOUSE=precision`, the default): the right button with the left held starts a drag, and a double right click pans and tilts what you're dragging. With `POINTER_GAZE_MOUSE_MOVE=held`, the default, the mouse only corrects: while the gaze has the pointer, moving it does nothing unless a button is held. `free` lets the mouse take the pointer any time. With the gaze stale for a second, in a game, or with the headset off, the mouse works as usual.
 - A correction before a click teaches the gaze service the tracker's error there. A correction bigger than `POINTER_GAZE_NUDGE_MAX` (55 degrees) isn't learned; it opens a quick check instead.
-- Calibration and checks run in a panel fixed to the headset (`gaze/panel/ft-gazepanel`, which the gaze service runs), from the Gaze page: Quick check is one dot, and also opens when you put the headset on. Calibrate is three rounds of dots, dark to bright; look at each dot and left click or press Meta+J to take it. Check headset fit shows, live, how well the tracker sees each eye. A right click or Meta+K closes the panel. Gaze mode on without a calibration opens Calibrate by itself, as soon as your eyes are seen. If gaze mode is on but can't follow your eyes yet (no calibration, the calibration can't open, the gaze service not running), the Gaze page says why under the Gaze pointer switch, and `gaze/ft-gazectl on` notes it.
+- Calibration and checks run in a panel fixed to the headset (`gaze/panel/ft-gazepanel`, which the gaze service runs), from the Gaze page: Quick check is one dot, and also opens when you put the headset on. Calibrate is three rounds of dots, dark to bright; look at each dot and left click, press Enter, pinch (index to thumb, with hand tracking) or press Meta+J to take it. Check headset fit shows, live, how well the tracker sees each eye. A right click or Meta+K closes the panel. Gaze mode on without a calibration opens Calibrate by itself, as soon as your eyes are seen. If gaze mode is on but can't follow your eyes yet (no calibration, the calibration can't open, the gaze service not running), the Gaze page says why under the Gaze pointer switch, and `gaze/ft-gazectl on` notes it.
 
 [gaze/README.md](../gaze/README.md) has the details, our own eye tracker, and the gaze probe, a development tool.
 

docs/remote-displays.md

@@ -476,6 +476,14 @@ The user decided remote displays are Frametop displays, with the same controls a
 - Disconnect, connect: the panel came back where it was, at its width. Connect in a new run with the headset off: placed from screen 1's anchor.
 - Windows rescales a window that moves between displays with different scaling, so the point you held moves on the window. A second drag from the same spot can land on the address bar instead of the title bar. That's Windows, not the routing.
 
+**The Frame's microphone on the host (2026-10-18):**
+- Send my microphone on a host's card (`"mic": true` in its layout entry, `ft-layout remote host NAME mic=on|off`, off by default) sends the Frame's microphone to it. The stream that plays the host's sound (the audio lock's holder) records PipeWire's default source, which on the Frame runs through echo cancelling, so a host gets it once however many displays stream. It reads the setting every 3 s, so switching needs no restart. Its 10 s report adds `mic N packets/s`.
+- Moonlight has no microphone. `stream/moonlight-mic.patch` adds `LiSendMicrophoneOpusData` to moonlight-common-c: packet type 0x3003 with `[sequence (2 bytes, big-endian), channel 1, flags 0]` then the Opus packet, the layout of Vibepollo's draft PR #169. It refuses (-1) when the control stream isn't encrypted, so the microphone never goes in the clear. Mono, 48 kHz, 20 ms packets, 64 kbit/s, Opus VOIP with in-band FEC.
+- ENet's throttle drops unreliable packets whenever round trips wobble. Over Wi-Fi beside three video streams it dropped 27% of them. The microphone now goes reliable, on ENet channel 0x07 of its own (moonlight-common-c uses 0x00-0x06, and 0x10 up for controllers), so a resent packet holds up only the microphone. Loss went to 0.
+- The host side is in our fork (`frametop/mic`, `src/frametop_mic*.cpp`). It takes the packets only on an encrypted control stream from a client allowed keyboard input, one client at a time (another waits and tries every 2 s). It decodes them on the control thread, hides up to 5 lost packets in a row (the last from FEC) and starts over after longer gaps, and plays them on a thread of its own. On Windows that's WASAPI into "Speakers (Steam Streaming Microphone)", which apps record as "Microphone (Steam Streaming Microphone)". The driver comes with Steam; the build installs `SteamStreamingMicrophone.inf` once if it's missing and puts the default devices back after. That capture endpoint adds +30 dB at Windows' default level (its range goes to +30), 32 times too loud, so the build plays that much quieter and follows the level when it changes.
+- On Linux the fork makes a "Frametop Microphone" source (`module-pipe-source`), but only when Sunshine runs as the desktop user. Vibepollo's packaged Linux service runs as its own user and reaches the desktop's sound only through its root session broker (`pactl`, `parec`), which has no operation for this. There it logs that once and does nothing. A broker operation would fix it, once a Linux host can test it.
+- Tested on the test PC with a 440 Hz test tone from the Frame instead of the microphone: every packet arrived encrypted, and a recorder on "Microphone (Steam Streaming Microphone)" heard the level sent (RMS 0.345 sent, 0.345 recorded), with no gaps. The Linux source was tested here on PipeWire. Not tested yet: a real voice in a real app, by ear, in the headset.
+
 **Still to do:**
 - A headset test of all of it in the live desktop:
   - the row above the screens;

docs/spotwatch.md

@@ -19,7 +19,7 @@ Spotwatch works while the Frametop desktop is running and Frametop isn't paused
 
 - Searching open windows by title, Frametop's own actions ("Reset layout"), and profiles (decision 4).
 - Moving the caret within the query. Typing and Backspace work at the end only.
-- A setting for its distance and size (`--distance` and `--width` on ft-spotpanel; 1 m and 0.56 m).
+- A setting for its distance and size (`--distance` and `--width` on ft-spotpanel; 0.75 m and 0.42 m, `spotwatch/reserve.h`).
 
 ## Decisions
 
@@ -28,7 +28,7 @@ These were settled with the user on 2026-10-10. The numbers may be cited in the
 | # | Question | Decision |
 |---|---|---|
 | 1 | The look | A rounded glass pill with a results card under it. The glass is faux, because SteamVR's overlays have alpha but no backdrop blur: a translucent dark tint, a soft sheen from the top, a bright rim fading down the edges, and a shadow outside. Real blur would mean reading the panels back every frame on the Frame's GPU |
-| 2 | Where it opens | Fixed in the room, centred where the head points (not the eye gaze), at 1 m, upright, tilted no more than 60° up or down. The card hangs below the pill, so the pill stays put as results change |
+| 2 | Where it opens | Fixed in the room, centred where the head points (not the eye gaze), at 0.75 m, upright, tilted no more than 60° up or down. The card hangs below the pill, so the pill stays put as results change. That spot is reserved (2026-10-17): the lazy susan's front slot stays at least 0.15 m behind it, and the search draws over any panel nearer than it |
 | 3 | An app with several windows | One row per app. Enter goes to its most recently active window, and Shift+Enter or a right click lists the others with the menu items |
 | 4 | What it searches | Apps and remote displays only. Hidden remote displays are left out, and disconnected ones show with Connect |
 | 5 | Disconnected remote displays | Enter connects the display (`ft-layout remote connect`), waits for its panel, then spins to it |

gaze/README.md

@@ -30,6 +30,7 @@ Gaze as an input method for the whole desktop, without replacing anything of Ste
   - **Eye tracker:** our own (Own tracker: see "Our own eye tracker" below) or SteamVR's. The default, `GAZE_TRACKER=auto`, is ours when it's installed (its frame grabber, and ft-eyes' Python in the gaze service's checkout), else SteamVR's, and it switches when ours is installed or removed; picking one on the Gaze page sets it for good. The gaze service runs ours while it's the one in use. It keeps its own calibration: with Own tracker chosen, Calibrate on the Gaze page calibrates it. The gaze pointer's settings (hand back, nudges, hold to drag, the dot) are the pointer helper's, so they're the same with either.
   - **Eye bias:** Auto, Left, or Right. The gaze combines both eyes, each calibrated on its own, because their errors partly cancel: on 306 clicks with our tracker, the eyes' sideways errors were correlated -0.37, and both together were 0.65 degrees off (median) against 0.96 for the left eye alone and 1.11 for the right. So Left or Right leans instead of choosing: that eye counts twice as much as the other (0.03 degrees worse there toward the better eye, 0.13 toward the worse). Auto weights each eye by the inverse square of how far off it was at your last 20 nudges, once each eye has 5, and evenly before that. Each eye's miss is measured before that nudge teaches anything, so each is a fresh test. The calibration's own fit isn't used for this: on SteamVR's test of 2026-09-29, the calibration dots said the left eye was the better one, and new spots said the right. Either eye carries the gaze alone while the other is closed or lost.
   - **One eye:** SteamOS 0.4's Track Dominant Eye Only (SteamVR's settings, General, with Show advanced settings on; `steamvr.eyeTrackingDominantEyeOnly` with `steamvr.dominantEye`) makes SteamVR's tracker ignore the other eye. With SteamVR's tracker, Frametop then goes by that eye alone: the calibration and the checks wait only for it, the gaze is that eye's own reading once it's calibrated (SteamVR's combined gaze before, which follows that eye then), and the fit check shows the other eye as not tracked. The service reads the setting again when SteamVR's settings file changes. Not yet tried in the headset: what SteamVR's shared memory says about the ignored eye wasn't measured.
+  - **Fusion** (`GAZE_FUSION=on` in `~/.config/frametop.conf`, off by default, not on the Gaze page yet): with our tracker, the gaze takes in SteamVR's too. SteamVR's is its two eyes averaged, corrected by an affine fit (offset, gain, and tilt) on the same dots as our calibration: Calibrate with Own tracker saves it in `~/.local/state/frametop/gaze/fusion.json`, and `gaze/bench/compare.py --fit-fusion` can make one from bench runs. While ours sees both eyes, the gaze is half ours and half SteamVR's. While ours has one eye or none, SteamVR's carries it alone, and without SteamVR's eyes (closed, lost, or its one-eye setting) it's ours. The two trackers' errors partly cancel. On the gaze bench's two head-locked runs of 2026-10-17 (25 presses), each fitted on the other presses: ours alone was 2.01 degrees off (median; 6.47 at the 90th percentile), SteamVR's eyes averaged 2.67 (5.72), SteamVR's corrected 1.78 (4.26), and the fusion 1.51 (3.10). Fitted on the other run only, the fusion was 1.41 (4.59). The fit holds only while SteamVR's tracker reads as it did at the calibration, and SteamVR starts its eye model over each time the headset goes on, so it stays off until benches across wears say it holds.
 
   With SteamVR, each eye is its own reading (set 2), corrected by its calibration from the probe (the Left eye and Right eye sources) plus what the pointer has taught that eye since. On that test, the two eyes each calibrated and averaged were 1.70 degrees off (median; mean 1.62) against 1.72 (mean 1.84) for SteamVR's combined gaze with its calibration. A calibration from before the probe had the eyes as sources, or `--source`, uses the older path. That path runs on SteamVR's combined gaze (mmap set 1), corrected as a whole. When the tracker loses one eye (its variance for that eye jumps from about 0.001 to 0.02), the gaze comes from the other eye instead: that eye's own reading (set 2) plus what it usually reads against the combined gaze, learned while both eyes are seen, in 10 degree cells of where it looks. Set 1 keeps going on one eye too, but it holds the lost eye's yaw where it was, so the gaze moves half as far sideways as your eyes do. On a recording, one eye alone came out a median 0.8 degrees from both eyes' gaze over a steady look, a little more jittery.
 
@@ -38,7 +39,7 @@ Gaze as an input method for the whole desktop, without replacing anything of Ste
 - **The mouse only corrects** (the default; the Gaze page's Mouse movement switch, `POINTER_GAZE_MOUSE_MOVE=held`): while the gaze has the pointer, moving the mouse does nothing. The buttons work like Meta+J and Meta+K: press and hold one and the pointer stops where you look; move the mouse onto what you meant and let go to click there (a left or a right click). Held still for half a second, a press is a real one (to drag). Once you've moved, the left button alone only clicks: press the right one while still holding the left to start a drag there; it lasts while either button is held. Press the right one again (a double right click, the left still held) to pan and tilt what you're dragging, as a right press does during any drag. A bumped or drifting mouse can't pull the pointer away, and every mouse move is a correction, so the tracker only learns from real ones. With the gaze stale for a second (the tracker stopped, eyes lost), in a game, or with the headset off, the mouse moves the pointer as usual. `free` (the switch off) lets the mouse take the pointer any time.
 - **Keyboard clicks** (Meta+J left, Meta+K right; other key combinations on the Keyboard page of Input Settings): tap to click where you look. A quick tap (let go within 0.25 s, `POINTER_KEY_TAP`) clicks where the dot was when you pressed, whatever your head did, and tells the gaze service it was right there. Hold instead, and the dot stays put in your view: turn your head until it sits on what you meant, and let go to click there (the correction is a lesson, as with the mouse, under the same limit: past `POINTER_GAZE_NUDGE_MAX` it opens the quick check instead). Hold still for half a second to press for real, then turn your head to drag. With Meta+J held, Meta+K presses where the dot is now, so you can correct first and then drag; the drag lasts while either key is held. Meta+K during a Meta+J drag (again, after starting it with Meta+K: a double Meta+K) pans and tilts what you're dragging while it's held: turn your head to turn it.
 - **Learning from nudges:** if the mouse took the pointer from the gaze and moved it (0.2 degrees or more, and the correction within `POINTER_GAZE_NUDGE_MAX`: 55 degrees by default, half of the 109 the headset shows across, and 1 to 110; the same limit for mouse, keyboard, and pinch clicks) before you clicked, or you dragged a held press that far, you were nudging it onto what you looked at. The helper sends that as a lesson, from the raw gaze when the mouse took over to where you clicked, and ft-gazed learns it. So using it is what calibrates it. The raw gaze is one ft-gazed sent, so it also finds when that look was, and what each eye read then. With SteamVR, each eye learns its own error. With our tracker, the look goes to it as a click, like the probe's, and it relearns how the headset sits on your face. After the headset was off, your first nudge and click there resets that (the quick check's dot does the same). A correction past `POINTER_GAZE_NUDGE_MAX` isn't learned: the helper asks ft-gazed for the quick check instead ("recheck", after its 2-minute cooldown). Tested on our tracker's 409 clicks since its Sep 29 calibration: a one-dot check set from any one of them put the next 2 minutes' clicks within 15 degrees (99% within 4.2) and the next 10 minutes' within 25 (the far ones after the headset moved), so the check gets back well under it. The limit used to be 8 degrees, and live on 2026-10-01 our tracker was 12 off after the headset went on, so every correction was dropped. One lesson moves the whole correction by only a third of what it measured (more near where it was taken), since in the first live test one 6 degree lesson moved everything and put the next target 7 degrees off. `ft-gazectl status` shows the lessons, and `ft-gazectl forget` drops them.
-- **Checks and calibration in the headset** (`gaze/gazecheck.py`, shown by `gaze/panel/ft-gazepanel`, a panel fixed to the headset that ft-gazed runs): a one-dot quick check opens when you put the headset on (SteamVR's tracker sees your eyes for 3 s after none for 3 s; its "HMD on" log line can't say, since it repeats every minute or so and can stay on for hours with nobody in the headset), when our tracker asks for a click (its "reseat", when the headset may sit differently), at most once every 2 minutes, and from Quick check on the Gaze page. Look at the dot: it takes your gaze once it has held still for 0.6 s (the steadiness counts, not where the tracker puts it, so it works however far off it is), or at once with a left click or Meta+J; a right click or Meta+K closes it, and ignoring it changes nothing. It also runs when a click's correction was past `POINTER_GAZE_NUDGE_MAX`. The dot is still and the ring fills in quarters, so the panel is drawn again only a few times per dot. If the first 3 lessons after it are still over 2 degrees off, five dots follow: the middle, and 12 degrees left and right and 9 up and down, in a see-through panel 40 degrees wide (the quick check's 16 degree square left four of them off the panel, unseen). The full calibration (Calibrate on the Gaze page, or by itself whenever gaze mode is on without one and your eyes are seen) is the probe's: three rounds, dark, medium and bright, of the middle and a ring around it, in a panel 64 degrees wide, with Frametop's screens hidden. Its dots (and the five-dot check's) wait for a click: look at the dot and left click or press Meta+J, and the gaze held still up to then is taken. A button mapped to gaze precision or gaze drag counts as the left click there (before 2026-10-09 the panel ignored it). Our tracker's first calibration has no gaze to go on, since ft-eyes maps pupils to a gaze only once it has a calibration: it opens once SteamVR's tracker sees an eye and ft-eyes answers, and a click takes the 0.6 s up to it, as long as ft-eyes saw each pupil held still then (before 2026-10-05 it waited for a gaze, so a fresh install could never calibrate ours). The dot's ring shows full while ft-eyes checks it; the service doesn't wait for that answer (before 2026-10-09 it did, up to 3 s a dot, so the pointer could come back over the panel, and a slow answer closed the calibration as if the headset came off). A dot that isn't taken says why, on an orange line over the instructions: with SteamVR's tracker, what dropped most of that look's samples (an eye lost, a blink, the two eyes disagreeing); with ours, its reply (an eye seen in too few frames, or moving). A dot gets two tries, then it's skipped. A calibration left with under two thirds of its dots fails and names the most common reason, as the Gaze page does after it. A click that has taken nothing after 1.5 s says what it waits for: the gaze to hold still, or an eye tracker that isn't sending. Capturing whenever the gaze held still sometimes took a look that wasn't on the dot. The panel draws into three shared buffers SteamVR imported once, as Frametop's keyboard does: uploading each picture anew (SetOverlayRaw) flickered, and in one live test left the headset showing an old picture. Quitting it while there's still no calibration turns gaze mode off; turning it on again reopens it. One that closes otherwise unfinished (ignored for 2 minutes, too few dots) opens again after the headset comes off and on. Why gaze mode, on, can't work yet goes in the service's status as `checks.problem`, which the Gaze page shows under the Gaze pointer switch. For our tracker a check is a click and the calibration is its own (calib-point per dot); for SteamVR's, a check is a lesson for each eye and the calibration replaces calibration.json, and the lessons start over. Checks go to `checks.jsonl`.
+- **Checks and calibration in the headset** (`gaze/gazecheck.py`, shown by `gaze/panel/ft-gazepanel`, a panel fixed to the headset that ft-gazed runs): a one-dot quick check opens when you put the headset on (SteamVR's tracker sees your eyes for 3 s after none for 3 s; its "HMD on" log line can't say, since it repeats every minute or so and can stay on for hours with nobody in the headset), when our tracker asks for a click (its "reseat", when the headset may sit differently), at most once every 2 minutes, and from Quick check on the Gaze page. Look at the dot: it takes your gaze once it has held still for 0.6 s (the steadiness counts, not where the tracker puts it, so it works however far off it is), or at once with a left click, Enter, an index pinch (with hand tracking) or Meta+J; a right click or Meta+K closes it, and ignoring it changes nothing. It also runs when a click's correction was past `POINTER_GAZE_NUDGE_MAX`. The dot is still and the ring fills in quarters, so the panel is drawn again only a few times per dot. If the first 3 lessons after it are still over 2 degrees off, five dots follow: the middle, and 12 degrees left and right and 9 up and down, in a see-through panel 40 degrees wide (the quick check's 16 degree square left four of them off the panel, unseen). The full calibration (Calibrate on the Gaze page, or by itself whenever gaze mode is on without one and your eyes are seen) is the probe's: three rounds, dark, medium and bright, of the middle and a ring around it, in a panel 64 degrees wide, with Frametop's screens hidden. Its dots (and the five-dot check's) wait for a click: look at the dot and left click, press Enter, pinch (index to thumb, with hand tracking) or press Meta+J, and the gaze held still up to then is taken. A button mapped to gaze precision or gaze drag counts as the left click there (before 2026-10-09 the panel ignored it). Enter works on a keyboard while typing goes to the desktop (the relay takes it while the panel is up, so it isn't typed; while typing goes to Steam, Steam sees it too). A pinch counts from its start, whether or not hand interaction is on, but not in a VR game, with the headset off, while typing, or at a controller. Our tracker's first calibration has no gaze to go on, since ft-eyes maps pupils to a gaze only once it has a calibration: it opens once SteamVR's tracker sees an eye and ft-eyes answers, and a click takes the 0.6 s up to it, as long as ft-eyes saw each pupil held still then (before 2026-10-05 it waited for a gaze, so a fresh install could never calibrate ours). The dot's ring shows full while ft-eyes checks it; the service doesn't wait for that answer (before 2026-10-09 it did, up to 3 s a dot, so the pointer could come back over the panel, and a slow answer closed the calibration as if the headset came off). A dot that isn't taken says why, on an orange line over the instructions: with SteamVR's tracker, what dropped most of that look's samples (an eye lost, a blink, the two eyes disagreeing); with ours, its reply (an eye seen in too few frames, or moving). A dot gets two tries, then it's skipped. A calibration left with under two thirds of its dots fails and names the most common reason, as the Gaze page does after it. A click that has taken nothing after 1.5 s says what it waits for: the gaze to hold still, or an eye tracker that isn't sending. Capturing whenever the gaze held still sometimes took a look that wasn't on the dot. The panel draws into three shared buffers SteamVR imported once, as Frametop's keyboard does: uploading each picture anew (SetOverlayRaw) flickered, and in one live test left the headset showing an old picture. Quitting it while there's still no calibration turns gaze mode off; turning it on again reopens it. One that closes otherwise unfinished (ignored for 2 minutes, too few dots) opens again after the headset comes off and on. Why gaze mode, on, can't work yet goes in the service's status as `checks.problem`, which the Gaze page shows under the Gaze pointer switch. For our tracker a check is a click and the calibration is its own (calib-point per dot); for SteamVR's, a check is a lesson for each eye and the calibration replaces calibration.json, and the lessons start over. Checks go to `checks.jsonl`.
 - Nothing writes to SteamVR, its eye tracker, or its files: ft-gaze maps the eye tracker's shared memory read-only. With no fresh gaze (a blink, the service stopped, the headset off), the pointer stays where it is, and the mouse works as always.
 - **Idle while the gaze isn't used:** ft-gaze and our own tracker run only while gaze mode is on and someone wears the headset (the pointer helper says both: SteamVR drops the headset's activity level as soon as it comes off), while a check or the calibration is open or asked for, or while the Gaze page of Frametop Input Settings is open (it renews a `wake` lease). 30 seconds after the last use they stop, and our frame grabber goes idle with our tracker. With our tracker, that saves over half a core: on 2026-10-02, with gaze mode off, ft-eyes took about 60% of a core, and ft-eyegrab, ft-gaze and ft-gazed 3 to 4% each. A check asked for while it idles starts the tracker and opens once it sends. When the gaze is used again, it takes a few seconds to come back, and our tracker's first click re-seats it, as after the headset was off: so the quick check opens when gaze mode comes on after the service idled, as it does when you put the headset on. `ft-gazectl status` says `"awake"`, and `"idle"` says why it isn't. A stand that covers the proximity sensor makes the headset seem worn, so with gaze mode on it doesn't idle there.
 
@@ -60,7 +61,7 @@ The tracker stops when the headset is off your head. SteamVR also calibrates gaz
 `gaze/tracker/` is an eye tracker of our own, because SteamVR's is about 1.5 degrees off after the best correction the gaze service can learn, and what's left is mostly look-to-look noise that no correction on top of its output can remove. Ours processes the eye cameras itself: 0.59 degrees (median) in its best live session against 0.83 for SteamVR's with the probe's correction, and after the headset was taken off and put back without recalibrating, 0.58 once your first clicks had taught it where the headset sat (`tracker/findings.md` has the measurements).
 
 - `ft-eyegrab` (C, root, the system service `frametop-eyegrab.service`) copies the eye-camera frames (512x400, 90 fps per eye, or 15 without `gaze/eye-rate.py on`) out of the DMA-BUFs SteamVR's `eyetracking` process holds into `/dev/shm/frametop-eyes-cams`, owned by you. It maps them read-only, and it only copies while someone touches `/dev/shm/frametop-eyes-want` (ft-eyes and the recorder do, every second). Otherwise it holds none of the tracker's buffers. Its unit keeps only the capabilities that needs (`CAP_SYS_PTRACE`, `CAP_DAC_READ_SEARCH`, `CAP_CHOWN`). `gaze/tracker/install.sh` builds it and installs it to `/etc/frametop` with sudo, which it asks for (`uninstall`, `status`, and `log` too). It also adds it to SteamOS's update keep list (`/etc/atomic-update.conf.d/frametop-eyegrab.conf`): an update deletes `/etc` files that list doesn't name, and without the grabber gaze mode falls back to SteamVR's tracker and its calibration. `scripts/doctor.sh` reports a grabber an update deleted.
-- `ft-eyes` (Python with numpy and OpenCV, in the dev container: `gaze/tracker/build.sh` puts the pinned `requirements.txt` in `gaze/tracker/build/venv`) finds each eye's pupil (dark threshold, closing, ellipse fit) and glint pair (`eyes_pupil.py`), and maps them to a gaze with a quadratic fit per eye (`eyes_model.py`). It follows the headset moving on your face with a per-eye shift, which your clicks teach, and uses the glints only to notice a sudden jump. It publishes the gaze in `/dev/shm/frametop-eyes-gaze` (ft-gaze's source `own`) and takes calibration dots and clicks on `@ft_eyes`. The gaze service runs it while Eye tracker is Own tracker, or while the probe uses it. State (the calibration, each eye's shift, the clicks) is in `~/.local/state/frametop/gaze/eyes/`. Instead of the pupil finder it can run an eye net (`eyes_net.py`): `EYES_MODEL` is `classic` (the default), `latest`, or a version from `gaze/tracker/models.json`, picked with its notes and benchmarks on Input Settings' Gaze page, which downloads it into `gaze/tracker/models/NAME` (`models/README.md`). Each net keeps its own calibration in `eyes/net-NAME/`.
+- `ft-eyes` (Python with numpy and OpenCV, in the dev container: `gaze/tracker/build.sh` puts the pinned `requirements.txt` in `gaze/tracker/build/venv`) finds each eye's pupil (dark threshold, closing, ellipse fit) and glint pair (`eyes_pupil.py`), and maps them to a gaze with a quadratic fit per eye (`eyes_model.py`). It follows the headset moving on your face with a per-eye shift, which your clicks teach, and uses the glints only to notice a sudden jump. A find much smaller than that eye's usual pupil (the median over the last 10 s) counts as not found, since it's usually a dark spot beside the pupil (`EYES_SIZE_GUARD`): with `both`, the default, under 0.75 of the other eye's ratio, so light shrinking both pupils gets through; with `long`, under 0.6 whatever the other eye does; `off` takes every find. On the bench runs of 2026-10-17, good finds were 0.84 of usual size or more 95% of the time, and the right camera's misfinds a median of 0.77. It publishes the gaze in `/dev/shm/frametop-eyes-gaze` (ft-gaze's source `own`) and takes calibration dots and clicks on `@ft_eyes`. The gaze service runs it while Eye tracker is Own tracker, or while the probe uses it. State (the calibration, each eye's shift, the clicks) is in `~/.local/state/frametop/gaze/eyes/`. Instead of the pupil finder it can run an eye net (`eyes_net.py`): `EYES_MODEL` is `classic` (the default), `latest`, or a version from `gaze/tracker/models.json`, picked with its notes and benchmarks on Input Settings' Gaze page, which downloads it into `gaze/tracker/models/NAME` (`models/README.md`). Each net keeps its own calibration in `eyes/net-NAME/`.
 - `lab/` has the tools for improving it on recordings. `ft-eyes-record NAME` (or `ft-eyes-session`, with SteamVR's gaze alongside) records the cameras. `ft-eyes-score` fits and scores on recordings against the probe's practice clicks. `ft-eyes-e2e` runs the whole live path on two recordings (calibrate on one, click through the other). `ft-eyes-replay` plays a recording into a scratch share. Heavy ones are meant for a PC: if you have `frame-job` (a personal tool, not in this repo), `gaze/tracker/.frame-job` sends them there. `lab/py` runs them with that Python (in the dev container on the Frame; on a PC, the same venv from `requirements.txt`, which frame-job's setup makes).
 
 Ground rules, for anyone changing it:
@@ -72,7 +73,7 @@ Ground rules, for anyone changing it:
 
 ## Headset fit
 
-Check headset fit on the Gaze page opens it in the headset panel: a card per eye (tracked or lost, the tracker's signal, how much of the last 10 s it was seen) and the hints, live while you adjust the headset. A left click or Meta+J runs the guided check (dots, then looks down, up, left and right), and a right click or Meta+K closes it. The probe's Headset fit mode (`ft-gazeprobe --mode fit`, for development) has the same check with maps: it shows, for each eye, whether the tracker has it, how open it is, and the tracker's confidence in it, and a map of where you looked coloured by how often it lost that eye there. Hints under the maps say which eye gets lost where, and what to try. Enter runs a guided check: dots around the screen, then looking down at the keyboard, up, left and right. R starts over. Adjust the headset while you watch it.
+Check headset fit on the Gaze page opens it in the headset panel: a card per eye (tracked or lost, the tracker's signal, how much of the last 10 s it was seen) and the hints, live while you adjust the headset. A left click, Enter, a pinch or Meta+J runs the guided check (dots, then looks down, up, left and right), and a right click or Meta+K closes it. The probe's Headset fit mode (`ft-gazeprobe --mode fit`, for development) has the same check with maps: it shows, for each eye, whether the tracker has it, how open it is, and the tracker's confidence in it, and a map of where you looked coloured by how often it lost that eye there. Hints under the maps say which eye gets lost where, and what to try. Enter runs a guided check: dots around the screen, then looking down at the keyboard, up, left and right. R starts over. Adjust the headset while you watch it.
 
 **The fit watch** (`GAZE_FIT_WATCH=1` in `~/.config/frametop.conf`; off by default until it's been tried in the headset). The fit check keeps a good fit as yours: when its coach (`gaze/fitcoach.py`, from ft-eyes' pupils and glints, with the shipped reference) last read it as good while you looked straight ahead, closing the check saves that reading to `~/.local/state/frametop/gaze/fit-baseline.json`, with the IPD setting. The eye recorder's fitment step saves it too. Then, with the fit watch on:
 - **Put-on check:** when the headset goes on, the quick check first holds its dot for up to 4 s while the coach reads the fit against your saved one. If it sits the same, the dot is taken as usual. If it moved (5 degrees of gaze or more), the panel widens and says which way to move the headset, and a changed IPD over that, live, until it's back ("Good: it's back where it was"); then the dot is taken. A click takes the dot as the headset sits, and after 30 s it's taken anyway. It needs our tracker installed (ft-eyes runs for it with either tracker in use), and without a saved fit it's the plain quick check.

gaze/bench/README.md

@@ -0,0 +1,101 @@
+# Gaze Bench
+
+A test bench for gaze tracking. It shows dots in the places gaze tracking finds hard (far out
+toward the edges and corners, long holds, light changes, a moving head, after the headset moved).
+You look at each one and press the headset's button. Every press is recorded with everything the
+trackers saw, so gaze techniques can be compared afterwards on the same looks (`compare.py`),
+including ones that didn't run live.
+
+The dots show on a panel in the headset, 64 degrees across, that moves with your head: a dot is
+always at the same direction from your head, wherever you face. So every run asks the same of the
+eyes, and you never have to turn your head to find a target. Your eyes do all the looking.
+
+## Use
+
+1. Put the headset on and open **Frametop Gaze Bench** from the app menu (`gaze/bench/install.sh`
+   adds it), or run `gaze/bench/ft-gazebench` from Frametop's desktop. A window opens; its
+   status lines say whether the headset panel, the headset button and the trackers are ready.
+   Gaze mode can be on or off: the bench keeps the trackers running itself.
+2. Pick a scenario. The panel shows what to do; press the button on the headset's right side
+   to begin.
+3. For each dot: look at it and press the button. The dot turns green and the next one shows.
+   Where you looked is the dot, so only press while you're on it.
+   Two presses take the last one back. Holding the button ends the scenario.
+   As in the gaze calibration, a left click, Enter or an index pinch (index to thumb, with hand
+   tracking) marks too, and a right click or Meta+K ends: while the panel shows, the bench claims
+   the pointer helper's calibration panel (`calpanel 1 ft_gazebench.PID`), so the helper sends
+   those here and hides the pointer. Those marks are recorded `"by": "helper"`, at the time the
+   helper's answer came in (a pinch's a frame or two after it began).
+   The window's keys do the same: Space marks, Backspace takes the last one back, S skips a
+   dot, Esc ends.
+4. At the end, the panel and the window say how far our tracker and SteamVR's were off. A press
+   (or a click, Enter or a pinch) closes the panel. Then run `compare.py` on the runs.
+
+| Scenario | What it tests |
+|---|---|
+| Warm-up | nine dots around the middle |
+| Edges | sixteen dots along the panel's edges and in its corners, 24 to 37 degrees out |
+| Hold at the edges | edge dots you look at for 3 s before pressing (the tracker loses an eye out there) |
+| Out from the middle | twenty-four dots on eight spokes, at a third, two thirds and all the way out |
+| Head moving | nine dots; keep looking while you turn or nod your head, press while it moves |
+| Light changes | dark, bright and grey backgrounds: pupil size |
+| Small steps | twenty dots, each 2 to 4 degrees from the last |
+| After a nudge | lift the headset and set it back, then nine dots: recovery |
+| Long session | sixty dots anywhere at your own pace, a few seconds apart, about six minutes: drift and stale corrections |
+
+Scenarios live in `scenarios.json` (the generators are described at its top).
+
+## Compare
+
+```
+scripts/in-box /opt/frametop/venv/bin/python gaze/bench/compare.py ~/.local/share/frametop/gaze/bench
+```
+
+Give it runs, or the folder they're in. For every press it prints how far each technique was from
+where you looked: overall, by scenario, by where the dot was (edge, corner, inside), by how far
+from straight ahead, and by the time since the last nudge. `--per-click` adds a line per press;
+`--json OUT` writes the records. The techniques are described at the top of `compare.py`: what
+ran live (our tracker, SteamVR's combined gaze and its two eyes averaged, a 70/30 mix, SteamVR's
+corrected by the presses), SteamVR's eyes corrected by the run's `fusion.json` (copied into
+`start/` when the run begins) and the fusion with ours, the same fitted on the run's other presses
+(`-loo`) or on the other runs only (`-xrun`), and replays of our classic tracker on its recorded
+finds with changed rules (no glint jump, a jump only when both eyes see it, no lessons past the
+calibrated range, learning from every press, bridging a lost eye, the size guard's two rules or
+none). `fusion-loo:REPLAY` fuses a replay with SteamVR's.
+`--fit-fusion OUT` fits SteamVR's correction on all the given runs' presses and saves it as a
+`fusion.json` the gaze service reads (`~/.local/state/frametop/gaze/fusion.json`). The replay of the live rules should land close to what our tracker published (the
+"replay vs live" line); the variants are only as trustworthy as that.
+
+Runs from before 2026-10-17 showed their targets on a Frametop screen, with clicks. `compare.py`
+still reads them: their truth comes from ft-gaze's screen hits, and they have a "pointer"
+technique (where the gaze pointer was).
+
+A long session's run (gaze.jsonl and own.jsonl) takes a while to replay: run it through
+`frame-job` when the headset is in use.
+
+## What a run records
+
+`~/.local/share/frametop/gaze/bench/<time>-<scenario>/` (`benchrec.py` describes every file):
+the dots and the presses, the panel's log of what the dot did and when it reached the eyes,
+the headset's pose 250 times a second, ft-gaze's samples of every source except SteamVR's input
+action (the one that costs vrserver anything), our tracker's per-frame pupil and glint finds,
+and our tracker's and the gaze service's calibration and state at the start. With **Record the
+eye cameras** on (the default), both eye cameras too, as the Eye Recorder records them: about
+1.2 GB a minute.
+
+Eye images identify a person. They stay on the headset: the bench uploads nothing, and the runs
+are yours to delete (the folder above).
+
+## Files
+
+| File | |
+|---|---|
+| `gazebench.py`, `bench.qml` | the app and its window (PySide6, in Frametop's container); it runs its own `ft-gazepanel` |
+| `benchrec.py` | the recording |
+| `scenarios.json` | the scenarios |
+| `compare.py` | the comparison (numpy, OpenCV) |
+| `ft-gazebench`, `ft-gazebench.desktop`, `install.sh` | the launcher and its menu entry |
+| `tests/` | `test_bench.py` (runs with stand-ins for ft-gaze, the panel, the button and the services), `test_compare.py` (a made-up run with known errors) |
+
+Tests: `scripts/in-box python3 gaze/bench/tests/test_bench.py`, and
+`scripts/in-box /opt/frametop/venv/bin/python gaze/bench/tests/test_compare.py`.

gaze/bench/bench.qml

@@ -0,0 +1,188 @@
+// Frametop Gaze Bench's window (gazebench.py), one page at a time: "menu" picks a scenario,
+// "run" follows it (its targets show on the headset's panel, not here), "done" shows how far the
+// trackers were off. The keys work as the headset button does.
+import QtQuick
+import QtQuick.Controls
+import QtQuick.Layouts
+import QtQuick.Window
+
+Window {
+    id: win
+    title: "Frametop Gaze Bench"
+    width: 960
+    height: 720
+    visible: true
+    color: "#262626"
+
+    readonly property color ink: "#eeeeee"
+    readonly property color dim: "#9a9a9a"
+
+    Shortcut { sequence: "Esc"; onActivated: bench.stop() }
+    Shortcut { sequence: "Backspace"; onActivated: bench.undo() }
+    Shortcut { sequence: "S"; enabled: bench.page === "run"; onActivated: bench.skip() }
+    Shortcut { sequences: ["Space", "Return", "Enter"]; enabled: bench.page !== "menu"; onActivated: bench.markKey() }
+
+    // --- menu
+
+    Item {
+        anchors.fill: parent
+        visible: bench.page === "menu"
+
+        ColumnLayout {
+            anchors.centerIn: parent
+            width: Math.min(parent.width - 60, 900)
+            spacing: 12
+
+            Label {
+                text: "Gaze Bench"
+                font.pixelSize: 30
+                color: win.ink
+            }
+            Label {
+                Layout.fillWidth: true
+                wrapMode: Text.Wrap
+                color: win.dim
+                font.pixelSize: 15
+                text: "Each scenario shows dots one at a time on a panel in front of you in the headset. "
+                    + "It moves with your head, so your eyes do all the looking. Look at the dot "
+                    + "and press the button on the headset's right side. Every look is recorded, so different "
+                    + "gaze techniques can be compared on the same looks afterwards."
+            }
+            Label {
+                Layout.fillWidth: true
+                visible: bench.notice !== ""
+                wrapMode: Text.Wrap
+                color: "#ffb347"
+                font.pixelSize: 15
+                text: bench.notice
+            }
+            GridLayout {
+                Layout.fillWidth: true
+                Layout.topMargin: 6
+                columns: 2
+                columnSpacing: 12
+                rowSpacing: 8
+                Repeater {
+                    model: bench.scenarios
+                    delegate: Button {
+                        required property var modelData
+                        Layout.fillWidth: true
+                        Layout.preferredWidth: 1
+                        implicitHeight: 64
+                        focusPolicy: Qt.NoFocus
+                        onClicked: bench.start(modelData.id)
+                        contentItem: ColumnLayout {
+                            spacing: 2
+                            Label {
+                                text: modelData.name + "  (" + modelData.count + ")"
+                                font.pixelSize: 16
+                                font.bold: true
+                            }
+                            Label {
+                                Layout.fillWidth: true
+                                text: modelData.about
+                                wrapMode: Text.Wrap
+                                maximumLineCount: 2
+                                elide: Text.ElideRight
+                                font.pixelSize: 12
+                                opacity: 0.8
+                            }
+                        }
+                    }
+                }
+            }
+            CheckBox {
+                text: "Record the eye cameras too (about 1.2 GB a minute; they stay on this headset)"
+                checked: bench.images
+                focusPolicy: Qt.NoFocus
+                onToggled: bench.images = checked
+            }
+            Label {
+                Layout.fillWidth: true
+                wrapMode: Text.Wrap
+                color: win.dim
+                font.pixelSize: 13
+                text: bench.status
+            }
+            RowLayout {
+                Layout.topMargin: 4
+                Label {
+                    Layout.fillWidth: true
+                    wrapMode: Text.Wrap
+                    color: win.dim
+                    font.pixelSize: 13
+                    text: "The headset button: press = marked, two presses = back one, hold = end. A left click, "
+                        + "Enter or an index pinch marks too; a right click ends. "
+                        + "Here: Space marks, Backspace goes back one, S skips, Esc ends."
+                }
+                Button { text: "Quit"; focusPolicy: Qt.NoFocus; onClicked: Qt.quit() }
+            }
+        }
+    }
+
+    // --- a run (the dots are on the headset's panel)
+
+    ColumnLayout {
+        anchors.centerIn: parent
+        width: Math.min(parent.width - 60, 760)
+        visible: bench.page === "run"
+        spacing: 14
+        Label {
+            Layout.fillWidth: true
+            wrapMode: Text.Wrap
+            text: bench.progress
+            color: win.ink
+            font.pixelSize: 22
+        }
+        Label {
+            Layout.fillWidth: true
+            wrapMode: Text.Wrap
+            text: bench.message
+            color: win.dim
+            font.pixelSize: 16
+        }
+        Label {
+            Layout.fillWidth: true
+            text: bench.last
+            color: win.ink
+            font.pixelSize: 16
+        }
+        Label {
+            Layout.fillWidth: true
+            wrapMode: Text.Wrap
+            color: win.dim
+            font.pixelSize: 13
+            text: "The headset button: press = marked, two presses = back one, hold = end. A left click, "
+                + "Enter or an index pinch marks too; a right click ends. "
+                + "Here: Space marks, Backspace goes back one, S skips, Esc ends."
+        }
+        RowLayout {
+            spacing: 10
+            Button { text: "Back one"; focusPolicy: Qt.NoFocus; onClicked: bench.undo() }
+            Button { text: "Skip"; focusPolicy: Qt.NoFocus; onClicked: bench.skip() }
+            Button { text: "End"; focusPolicy: Qt.NoFocus; onClicked: bench.stop() }
+        }
+    }
+
+    // --- done
+
+    ColumnLayout {
+        anchors.centerIn: parent
+        width: Math.min(parent.width - 60, 860)
+        visible: bench.page === "done"
+        spacing: 16
+        Label {
+            Layout.fillWidth: true
+            wrapMode: Text.Wrap
+            text: bench.summary
+            color: win.ink
+            font.pixelSize: 18
+            lineHeight: 1.3
+        }
+        RowLayout {
+            spacing: 12
+            Button { text: "Again"; focusPolicy: Qt.NoFocus; onClicked: bench.again() }
+            Button { text: "Scenarios"; focusPolicy: Qt.NoFocus; onClicked: bench.stop() }
+        }
+    }
+}

gaze/bench/benchrec.py

@@ -0,0 +1,348 @@
+"""Gaze bench recording (README.md): everything a run needs to replay gaze techniques later.
+
+A run is one scenario played once. Its folder, under BASE:
+  run.json          the scenario, the panel, the settings, and the gaze service's and our
+                    tracker's status at the start and the end
+  trials.jsonl      a line per target: where it was, when it showed, and when you marked it
+                    (gazebench.py's own record: "click" is the mark, by the button or a key)
+  targets.jsonl     the panel's record of what the dot did, with when each change reached the
+  poses.jsonl       eyes; the headset's pose 250 times a second; SteamVR's IPD setting
+  ipd.jsonl         (ft-gazepanel's log, gaze/panel/ft-gazepanel.cpp)
+  gaze.jsonl        ft-gaze's samples, every source but SteamVR's input action (the one that
+                    calls into vrserver): SteamVR's eyes (mmap1, mmap2, left, right), our
+                    tracker's published gaze (own), the head ray, and where each lands on
+                    Frametop's screens, in pixels, with pixels per degree there (ft-gaze.cpp)
+  own.jsonl         our tracker's finds, a line per eye-camera frame (ft-eyes "finds start"):
+                    pupil, ellipse, glints, and each eye's gaze as it published it
+  lessons.jsonl     the gaze service's lesson log (pointer-lessons.jsonl) over the run: each
+                    nudge the pointer sent, its raw gaze and the true direction
+  eyes-clicks.jsonl our tracker's clicks over the run (clicks.jsonl): what each nudge taught it
+  start/            copies of our tracker's calibration, its dots and its state (the shift
+                    clicks taught it), and the gaze service's calibration, lessons and fusion
+                    (gazed-fusion.json), as they were when the run started, so a replay starts
+                    where the live tracker did
+  images/           both eye cameras, zstd chunks (gaze/rec/eyerec.py), unless images are off
+
+Eye images identify a person: they stay on this headset (and the maintainer's own training
+machines). Nothing here uploads anything.
+"""
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+from collections import deque
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+GAZE = HERE.parent
+
+# ft-gaze: this tree's build (gaze/build.sh), else the installed release's (a worktree with no build)
+FT_GAZES = [Path(p) for p in (os.environ.get("FT_GAZE"), GAZE / "build" / "ft-gaze",
+                              Path.home() / ".local/share/frametop/releases/current/gaze/build/ft-gaze") if p]
+BASE = Path(os.environ.get("FT_BENCH_BASE", Path.home() / ".local/share/frametop/gaze/bench"))
+STATE = Path.home() / ".local/state/frametop/gaze"
+EYES_STATE = STATE / "eyes"
+LESSON_LOG = STATE / "pointer-lessons.jsonl"
+CONF = Path.home() / ".config/frametop.conf"
+CONF_KEYS = ("GAZE_", "POINTER_GAZE", "EYES_MODEL")
+SOURCES = "mmap1,mmap2,left,right,own"
+EYES_SOCK = os.environ.get("FT_BENCH_EYES_SOCKET", "ft_eyes")     # (the tests' stand-ins)
+GAZED_SOCK = os.environ.get("FT_BENCH_GAZED_SOCKET", "ft_gazed")
+RECENT = 3.0        # s of parsed samples kept for the app's quick scores
+RESTART = 3.0       # s before ft-gaze is started again after it stopped (SteamVR restarted)
+KEEPALIVE = 2.0     # s between checks that our tracker is still logging finds
+LOG_SLACK = 3.0     # s either side of the run when copying the lesson logs
+
+
+def raw_now():
+    return time.clock_gettime(time.CLOCK_MONOTONIC_RAW)
+
+
+class Sock:
+    """A datagram client for one of the gaze services' abstract sockets (@ft_eyes, @ft_gazed)."""
+
+    def __init__(self, name):
+        self.name = "\0" + name
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_CLOEXEC)
+        self.sock.bind("")
+
+    def ask(self, text, timeout=0.5):
+        """Send, and the reply (text) or None."""
+        self.sock.setblocking(False)
+        while True:  # drop late replies to earlier questions
+            try:
+                self.sock.recv(65536)
+            except OSError:
+                break
+        try:
+            self.sock.sendto(text.encode(), self.name)
+            self.sock.settimeout(timeout)
+            return self.sock.recv(1 << 20).decode(errors="replace")
+        except OSError:
+            return None
+
+    def json(self, text, timeout=0.5):
+        r = self.ask(text, timeout)
+        try:
+            return json.loads(r) if r else None
+        except ValueError:
+            return None
+
+    def close(self):
+        self.sock.close()
+
+
+class GazeStream:
+    """ft-gaze, for the app's life (it takes a moment to connect to SteamVR and the screens), and
+    again RESTART seconds after it stops: it quits when SteamVR does. Its lines go to the current
+    run's gaze.jsonl while one records, and the last RECENT seconds are kept parsed for the app's
+    quick scores and status."""
+
+    def __init__(self, prog=None, log=print):
+        self.prog = Path(prog) if prog else next((p for p in FT_GAZES if p.exists()), FT_GAZES[0])
+        self.log = log
+        self.proc = None
+        self.out = None
+        self.lock = threading.Lock()
+        self.recent = deque()
+        self.lines = 0
+        self.error = None
+        self.restarts = 0
+        self.stopping = threading.Event()
+        self.reader = None
+
+    def start(self):
+        if not self.prog.exists():
+            self.error = f"{self.prog} isn't built (gaze/build.sh)"
+            return self
+        self.reader = threading.Thread(target=self._run, name="ft-gaze", daemon=True)
+        self.reader.start()
+        return self
+
+    def _run(self):
+        while True:
+            with self.lock:
+                if self.stopping.is_set():
+                    return
+                self.proc = subprocess.Popen([str(self.prog), "--watch-stdin", "--sources", SOURCES],
+                                             stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+            before = self.lines
+            self._read()
+            code = self.proc.wait()
+            self.proc.stdout.close()
+            try:
+                self.proc.stdin.close()
+            except OSError:
+                pass
+            if self.stopping.is_set():
+                return
+            self.error = f"ft-gaze stopped (exit {code}); starting it again"
+            if self.lines > before or not self.restarts:   # not every few seconds while SteamVR is down
+                self.log(self.error)
+            self.restarts += 1
+            self.stopping.wait(RESTART)
+
+    def _read(self):
+        for line in self.proc.stdout:
+            with self.lock:
+                if self.out:
+                    self.out.write(line)
+            self.lines += 1
+            try:
+                s = json.loads(line)
+            except ValueError:
+                continue
+            self.error = None
+            with self.lock:
+                self.recent.append(s)
+                while self.recent and self.recent[0].get("t", 0) < s.get("t", 0) - RECENT:
+                    self.recent.popleft()
+
+    def to(self, path):
+        """Write the samples to path from now on (None: stop writing)."""
+        with self.lock:
+            if self.out:
+                self.out.close()
+            self.out = open(path, "ab") if path else None
+
+    def window(self, t0, t1):
+        with self.lock:
+            return [s for s in self.recent if t0 <= s.get("t", 0) <= t1]
+
+    def latest(self):
+        with self.lock:
+            return self.recent[-1] if self.recent else None
+
+    def stop(self):
+        self.to(None)
+        with self.lock:
+            self.stopping.set()
+            proc = self.proc
+        if proc:
+            try:
+                proc.stdin.close()
+            except OSError:
+                pass
+            try:
+                proc.wait(3)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+        if self.reader:
+            self.reader.join(2)
+
+
+def conf_lines():
+    try:
+        return [l for l in CONF.read_text().splitlines() if l.startswith(CONF_KEYS)]
+    except OSError:
+        return []
+
+
+def eyes_state_dir(status):
+    """Our tracker's state folder for the model it runs (ft-eyes: net-NAME/ for a net)."""
+    model = (status or {}).get("model")
+    if model:
+        try:
+            name = json.loads((Path(model) / "model.json").read_text())["name"]
+        except (OSError, ValueError, KeyError):
+            name = Path(model).name
+        return EYES_STATE / ("net-" + str(name))
+    return EYES_STATE
+
+
+def last_time(path, before):
+    """The latest "time" (wall clock) in a JSON lines log before `before`, or None: the last nudge
+    before a run, for compare.py's time since the last nudge."""
+    last = None
+    try:
+        with open(path) as f:
+            for line in f:
+                try:
+                    tm = json.loads(line).get("time")
+                except ValueError:
+                    continue
+                if tm is not None and tm < before and "refused" not in line:
+                    last = tm if last is None else max(last, tm)
+    except OSError:
+        pass
+    return last
+
+
+def copy_rows(src, dst, t0, t1):
+    """The JSON lines of src whose "time" (wall clock) is within [t0, t1], appended to dst."""
+    n = 0
+    try:
+        with open(src) as f, open(dst, "a") as out:
+            for line in f:
+                try:
+                    tm = json.loads(line).get("time", 0)
+                except ValueError:
+                    continue
+                if t0 <= tm <= t1:
+                    out.write(line if line.endswith("\n") else line + "\n")
+                    n += 1
+    except OSError:
+        pass
+    return n
+
+
+class Run:
+    """One scenario played once: its folder, and what records into it (see the top)."""
+
+    def __init__(self, scenario, gaze, images=True, base=BASE, log=print, info=None):
+        self.scenario, self.gaze, self.images, self.log = scenario, gaze, images, log
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        self.dir = Path(base) / f"{stamp}-{scenario['id']}"
+        self.info = dict(info or {})
+        self.eyes = Sock(EYES_SOCK)
+        self.gazed = Sock(GAZED_SOCK)
+        self.writer = None
+        self.finds_on = False
+        self.checked = 0.0
+        self.trials = None
+
+    def status(self):
+        return {"eyes": self.eyes.json("status"), "gazed": self.gazed.json("status"), "t_raw": raw_now(),
+                "time": time.time()}
+
+    def start(self):
+        self.dir.mkdir(parents=True)
+        (self.dir / "start").mkdir()
+        st = self.status()
+        estate = eyes_state_dir(st["eyes"])
+        for name in ("calibration.json", "calibration-dots.jsonl", "state.json"):
+            if (estate / name).exists():
+                shutil.copy2(estate / name, self.dir / "start" / ("eyes-" + name))
+        for name in ("calibration.json", "pointer-lessons.json", "fusion.json"):
+            if (STATE / name).exists():
+                shutil.copy2(STATE / name, self.dir / "start" / ("gazed-" + name))
+        self.info.update(scenario=self.scenario, start=st, conf=conf_lines(), eyes_state=str(estate),
+                         images=self.images, sources=SOURCES, last_lesson=last_time(LESSON_LOG, st["time"]))
+        self.write_info()
+        self.trials = open(self.dir / "trials.jsonl", "a", buffering=1)
+        self.lines0 = self.gaze.lines
+        self.gaze.to(self.dir / "gaze.jsonl")
+        self.arm_finds()
+        if self.images:
+            try:
+                if str(GAZE / "rec") not in sys.path:
+                    sys.path.insert(0, str(GAZE / "rec"))
+                import eyerec
+                self.writer = eyerec.Writer(str(self.dir / "images"), log=self.log).start()
+                self.writer.record(True)
+            except Exception as e:  # no zstd, no share: record the rest
+                self.log(f"images: {e}")
+                self.writer = None
+                self.info["images_error"] = str(e)
+        return self
+
+    def arm_finds(self):
+        r = self.eyes.ask("finds start " + str(self.dir / "own.jsonl"))
+        self.finds_on = bool(r and r.startswith("ok"))
+        if not self.finds_on:
+            self.log(f"our tracker isn't logging finds ({r or 'no reply: is it running?'})")
+        return self.finds_on
+
+    def keepalive(self):
+        """Call now and then: our tracker may have restarted (or started), and dropped the log."""
+        if time.monotonic() - self.checked < KEEPALIVE:
+            return
+        self.checked = time.monotonic()
+        st = self.eyes.json("status")
+        if st is None:
+            self.finds_on = False
+        elif not self.finds_on:
+            self.arm_finds()
+
+    def trial(self, rec):
+        if self.trials:
+            self.trials.write(json.dumps(rec) + "\n")
+
+    def write_info(self):
+        tmp = self.dir / "run.json.tmp"
+        tmp.write_text(json.dumps(self.info, indent=1))
+        tmp.replace(self.dir / "run.json")
+
+    def stop(self, summary=None):
+        rows = self.eyes.ask("finds stop")
+        self.gaze.to(None)
+        if self.trials:
+            self.trials.close()
+            self.trials = None
+        if self.writer:
+            self.info["images_stats"] = self.writer.stop()
+        time.sleep(0.5)  # a nudge's lesson reaches the logs just after its click
+        st = self.status()
+        t0, t1 = self.info["start"]["time"] - LOG_SLACK, st["time"] + LOG_SLACK
+        n_lessons = copy_rows(LESSON_LOG, self.dir / "lessons.jsonl", t0, t1)
+        n_clicks = copy_rows(Path(self.info["eyes_state"]) / "clicks.jsonl", self.dir / "eyes-clicks.jsonl", t0, t1)
+        self.info.update(end=st, finds_rows=rows, lessons=n_lessons, eyes_clicks=n_clicks,
+                         gaze_lines=self.gaze.lines - self.lines0, summary=summary)
+        self.write_info()
+        self.eyes.close()
+        self.gazed.close()
+        return self.info

gaze/bench/compare.py

@@ -0,0 +1,670 @@
+#!/usr/bin/env python3
+"""Compare gaze techniques on gaze bench runs (README.md): how far each was from where you looked,
+at every click.
+
+  compare.py RUN [RUN...] [--per-click] [--json OUT] [--only a,b]
+
+RUN is a run's folder (benchrec.py), or a folder of them (all runs in it). A click is a mark:
+you looked at the target and pressed. Where you looked is the target, a head-relative direction
+on runs with the headset's panel (run.json "display": "panel", from 2026-10-17). The runs before
+showed targets on a Frametop screen: there it's the target's middle, or the click if it landed off
+the target, turned into a direction through ft-gaze's screen hits just before the click (the hit
+nearest that point, and its pixels per degree there: ft-gaze.cpp's HIT "j"). Each technique's
+gaze is its median over the same LOOK window (run.json), and its error the angle between the two.
+
+Techniques: what ran live, from gaze.jsonl:
+  own-live        our tracker's published gaze (ft-eyes, with its calibration and the shifts the
+                  nudges taught it)
+  steamvr         SteamVR's combined gaze (ft-gaze's mmap1, its own calibration)
+  steamvr-eyes    the mean of SteamVR's two eyes (left, right: set 2, no calibration of ours)
+  pointer         where the pointer was: a nudge's raw gaze (lessons.jsonl), else the click
+                  (screen runs only: on the panel there's no pointer)
+  fuse            70 % our tracker, 30 % SteamVR's eyes' mean (both live)
+  steamvr+clicks  SteamVR's, less the median error of the last SHIFT_KEEP clicks before
+With the fusion the run started with (start/gazed-fusion.json: gazecal.Fusion, fitted at our
+tracker's last calibration, or by --fit-fusion), what ft-gazed's GAZE_FUSION=on sends:
+  steamvr-affine  SteamVR's eyes' mean with its affine correction
+  steamvr-affine+clicks   ...plus the median of what the run's clicks before said was still off
+  fusion          per sample: ours (its eyes, weighted as ft-gazed does) mixed half and half with
+                  steamvr-affine where both our eyes are found, steamvr-affine alone where we
+                  have one, ours alone where SteamVR has no gaze; the look's median
+The same, fitted here on the other clicks (all runs given), for runs without one:
+  steamvr-affine-loo, fusion-loo     on every other click
+  ours-else-steam-loo                fusion-loo, but ours alone where both our eyes are found
+  steamvr-affine-xrun(+clicks), fusion-xrun(+clicks)   on the other runs' clicks only: a
+                  calibration from another sitting
+  fusion-loo:REPLAY   fusion-loo with our eyes from that replay (FUSE_REPLAYS, below), not
+                  live: a guard's worth with SteamVR covering the eyes it refuses
+Replays of our tracker on its finds (own.jsonl), from the calibration and the shift it had when
+the run started (start/), with ft-eyes' own rules (eyes_model.py), and nudges teaching it when
+they did live (lessons.jsonl):
+  own-replay      the live rules: check this against own-live (the "replay vs live" line)
+  no-jump         no glint jump: only clicks move the shift
+  both-jump       a glint jump counts only while both eyes see one
+  edge-guard      nudges past the calibration's dots (by EDGE_MARGIN) teach nothing
+  every-click     every click teaches it, not only the nudges
+  bridge          one eye lost: the other, plus how far it usually reads from the two together
+  guard-both      eyes_pupil.SizeGuard "both" over the finds (refused ones count as lost)
+  guard-long      SizeGuard "long"
+  no-guard        the finds the live SizeGuard refused (own.jsonl "guard": true) back in
+Each click is scored before anything it teaches. The breakdowns: by scenario, by where the target
+was (edge, corner or inside), by how far from straight ahead you looked, and by the time since
+the last nudge (run.json's last_lesson for the first).
+
+Needs numpy and (for the glint pairs) OpenCV: the tracker's Python, e.g.
+  scripts/in-box /opt/frametop/venv/bin/python gaze/bench/compare.py ~/.local/share/frametop/gaze/bench
+
+--fit-fusion OUT fits a gazecal.Fusion on all the clicks given (SteamVR's eyes' mean at each, and
+the target) and writes it to OUT, e.g. ~/.local/state/frametop/gaze/fusion.json for ft-gazed.
+"""
+import argparse
+import bisect
+import json
+import math
+import statistics
+import sys
+import time
+from collections import deque
+from pathlib import Path
+
+import numpy as np
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent / "tracker"))
+sys.path.insert(0, str(HERE.parent))
+import eyes_model  # noqa: E402
+from gazecal import EyeWeights, Fusion  # noqa: E402
+
+LOOK = (0.35, 0.05)       # s before a click: as gazebench.py, for runs that don't say
+CLICK_BEFORE = 0.3        # ft-eyes: a click's frames are the 300 ms before it
+CLICK_MIN = 5             # ...at least this many
+FRESH = 0.03              # ft-eyes: an eye counts toward the output this long after its frame
+GAP = 3.0                 # ft-eyes: frames stopping this long is the headset off (a re-seat)
+HISTORY = 12.0            # ft-eyes: seconds of pupil positions kept per eye
+LESSON_MATCH = 1.5        # s between a click and its nudge's lesson
+EDGE_MARGIN = 2.0         # degrees past the calibration's outermost dots for edge-guard
+BRIDGE_TAU = 2.0          # s: bridge's average of each eye against the two together
+FUSE = 0.7                # fuse: our tracker's share
+SHIFT_KEEP = eyes_model.SHIFT_KEEP
+LIVE = ("own-live", "steamvr", "steamvr-eyes", "pointer", "fuse", "steamvr+clicks",
+        "steamvr-affine", "steamvr-affine+clicks", "fusion")
+CROSS = ("steamvr-affine-loo", "fusion-loo", "ours-else-steam-loo",
+         "steamvr-affine-xrun", "steamvr-affine-xrun+clicks", "fusion-xrun", "fusion-xrun+clicks")
+FUSE_REPLAYS = ("own-replay", "guard-both", "guard-long")  # fusion-loo:NAME, with that replay's eyes
+REPLAYS = {  # name: Replay options
+    "own-replay": {},
+    "no-jump": {"jump": None},
+    "both-jump": {"jump": "both"},
+    "edge-guard": {"guard": True},
+    "every-click": {"teach": "every"},
+    "bridge": {"bridge": True},
+    "guard-both": {"size": "both"},
+    "guard-long": {"size": "long"},
+    "no-guard": {"size": "none"},
+}
+ECC_BINS = ((0, 10, "<10°"), (10, 20, "10-20°"), (20, 30, "20-30°"), (30, 999, "30°+"))
+SINCE_BINS = ((0, 30, "<30 s"), (30, 120, "30-120 s"), (120, math.inf, "120 s+"))
+
+
+def jsonl(path):
+    try:
+        with open(path) as f:
+            for line in f:
+                try:
+                    yield json.loads(line)
+                except ValueError:
+                    continue
+    except FileNotFoundError:
+        return
+
+
+def unit(hy, hp):
+    """ft-gaze's head-relative yaw (+left), pitch (+up), degrees, as a unit vector (-Z ahead)."""
+    y, p = math.radians(hy), math.radians(hp)
+    return np.array([-math.sin(y) * math.cos(p), math.sin(p), -math.cos(y) * math.cos(p)])
+
+
+def angle(a, b):
+    if a is None or b is None:
+        return None
+    return math.degrees(math.acos(max(-1.0, min(1.0, float(unit(*a) @ unit(*b))))))
+
+
+def median2(rows):
+    rows = [r for r in rows if r is not None]
+    if not rows:
+        return None
+    return (statistics.median(r[0] for r in rows), statistics.median(r[1] for r in rows))
+
+
+def rays(s):
+    """A sample's rays with screen hits: (yaw, pitch, hit), head-relative."""
+    head = s.get("head") or {}
+    if head.get("hit"):
+        yield 0.0, 0.0, head["hit"]
+    for name, src in (s.get("src") or {}).items():
+        if src.get("hit") and "hy" in src:
+            yield src["hy"], src["hp"], src["hit"]
+        for e, h in zip(src.get("eyes") or (), src.get("ehit") or ()):
+            if e and h:
+                yield e[0], e[1], h
+
+
+class Run:
+    def __init__(self, d):
+        self.dir = Path(d)
+        self.info = json.loads((self.dir / "run.json").read_text())
+        st = self.info["start"]
+        self.wall = st["time"] - st["t_raw"]          # wall clock = raw + this
+        self.look = tuple(self.info.get("look") or LOOK)
+        self.scenario = self.info["scenario"]["id"]
+        self.samples = sorted(jsonl(self.dir / "gaze.jsonl"), key=lambda s: s.get("t", 0))
+        self.ts = [s.get("t", 0) for s in self.samples]
+        self.notes = []
+        self.replay_eyes = {}   # replay name: (times, [(left, right) eyes' gazes]) (replays())
+        self.lessons = sorted((r for r in jsonl(self.dir / "lessons.jsonl") if "refused" not in r),
+                              key=lambda r: r["time"])
+        self.panel = self.info.get("display") == "panel"
+        if self.panel:   # the targets' directions are in trials.jsonl
+            self.screen, self.sx, self.sy = None, 1.0, 1.0
+            self.trials = self.load_trials()
+            return
+        votes = {}
+        for s in self.samples:
+            hit = (s.get("head") or {}).get("hit")
+            if hit:
+                votes[hit["s"]] = votes.get(hit["s"], 0) + 1
+        self.screen = max(votes, key=votes.get) if votes else None
+        # ft-screens' pixels per window pixel: its size over the window's (gazebench.Bench.scale)
+        win, size = self.info.get("screen") or {}, (self.info.get("screens") or {}).get(str(self.screen))
+        if size and win.get("w") and win.get("h"):
+            self.sx, self.sy = size[0] / win["w"], size[1] / win["h"]
+        else:
+            self.sx = self.sy = win.get("dpr") or 1.0
+            self.notes.append("no screen sizes in run.json (a run before 2026-10-17): window pixels at Qt's "
+                              "pixel ratio, wrong where it isn't the desktop's scale")
+        self.trials = self.load_trials()
+
+    def load_trials(self):
+        """The trials that stand: the last click on each target, unless taken back or skipped. On a
+        screen run, each with the nudge's lesson that came with its click, if there was one."""
+        by_i = {}
+        for r in jsonl(self.dir / "trials.jsonl"):
+            if r.get("kind") == "trial":
+                by_i[r["i"]] = r
+            elif r.get("kind") == "undo":
+                by_i.pop(r["i"], None)
+        out = []
+        used = set()
+        for r in sorted(by_i.values(), key=lambda r: r["click"]["t"]):
+            if r.get("skipped") or "truth" not in r:
+                continue
+            r = dict(r)
+            if self.panel:
+                out.append(r)
+                continue
+            wall = r["click"]["t"] + self.wall
+            best = None
+            for k, ls in enumerate(self.lessons):
+                if k not in used and abs(ls["time"] - wall) <= LESSON_MATCH and (
+                        best is None or abs(ls["time"] - wall) < abs(self.lessons[best]["time"] - wall)):
+                    best = k
+            if best is not None:
+                used.add(best)
+                r["lesson"] = self.lessons[best]
+            out.append(r)
+        return out
+
+    def window(self, t0, t1):
+        return self.samples[bisect.bisect_left(self.ts, t0):bisect.bisect_right(self.ts, t1)]
+
+    def look_window(self, r):
+        """The click's look: before the press for a nudge (the lesson's look_t), else before the click."""
+        ls = r.get("lesson")
+        if ls and ls.get("look_t") is not None:
+            return ls["look_t"] - (self.look[0] - self.look[1]), ls["look_t"]
+        t = r["click"]["t"]
+        return t - self.look[0], t - self.look[1]
+
+    def direction(self, samples, px, py):
+        """Head-relative (yaw, pitch) of a point on the bench's screen (ft-screens' pixels): per
+        sample, from the hit nearest it, through that hit's pixels per degree; the median."""
+        out = []
+        for s in samples:
+            best = None
+            for hy, hp, h in rays(s):
+                if h.get("s") != self.screen or not h.get("j"):
+                    continue
+                d = math.hypot(h["x"] - px, h["y"] - py)
+                if best is None or d < best[0]:
+                    best = (d, hy, hp, h)
+            if best is None:
+                continue
+            _, hy, hp, h = best
+            j = h["j"]  # [dx/dhy, dy/dhy, dx/dhp, dy/dhp]
+            det = j[0] * j[3] - j[2] * j[1]
+            if abs(det) < 1e-9:
+                continue
+            ex, ey = px - h["x"], py - h["y"]
+            out.append((hy + (j[3] * ex - j[2] * ey) / det, hp + (-j[1] * ex + j[0] * ey) / det))
+        return median2(out)
+
+    def truth(self, r):
+        if "yaw" in r["truth"]:   # the panel's target
+            return r["truth"]["yaw"], r["truth"]["pitch"]
+        t0, t1 = self.look_window(r)
+        return self.direction(self.window(t0, t1), r["truth"]["x"] * self.sx, r["truth"]["y"] * self.sy)
+
+    def source(self, name, t0, t1):
+        rows = []
+        for s in self.window(t0, t1):
+            src = (s.get("src") or {}).get(name) or {}
+            if "hy" in src:
+                rows.append((src["hy"], src["hp"]))
+        return median2(rows)
+
+    def frames(self, size=None):
+        """Our tracker's finds, in time order: (t, cam, x, y, glint pair midpoint or None, gaze).
+        size: None, the live rules (the finds its SizeGuard refused are out); "none", those back
+        in; or a SizeGuard rule, run here over all of them instead."""
+        import eyes_pupil  # OpenCV
+        rows = sorted((r for r in jsonl(self.dir / "own.jsonl") if not r.get("lost") and "x" in r),
+                      key=lambda r: (r["t"], r["cam"]))
+        guard = eyes_pupil.SizeGuard(size) if size not in (None, "none") else None
+        out = []
+        for r in rows:
+            if size is None and r.get("guard"):
+                continue
+            if guard and not guard.keep(r["cam"], r["t"], r["a"]):
+                continue
+            pair = eyes_pupil.glint_pair({"x": r["x"], "y": r["y"], "glints": r.get("glints") or []})
+            out.append((r["t"], r["cam"], r["x"], r["y"], eyes_model.pair_mid(pair) if pair else None, r.get("gaze")))
+        return out
+
+    def fusion_inputs(self, t0, t1, replay=None):
+        """Per sample over [t0, t1]: (our eyes [left, right], SteamVR's left, right), for fusions.
+        Our eyes as published, or as a replay had them then (its newest output, if FRESH)."""
+        out = []
+        if replay:
+            rt, re = self.replay_eyes[replay]
+        for s in self.window(t0, t1):
+            src = s.get("src") or {}
+            if replay:
+                k = bisect.bisect_right(rt, s.get("t", 0)) - 1
+                eyes = list(re[k]) if k >= 0 and s.get("t", 0) - rt[k] < FRESH else [None, None]
+            else:
+                eyes = [tuple(e) if e else None for e in ((src.get("own") or {}).get("eyes") or [None, None])]
+            lr = [(src[n]["hy"], src[n]["hp"]) if "hy" in (src.get(n) or {}) else None for n in ("left", "right")]
+            out.append((eyes, lr[0], lr[1]))
+        return out
+
+
+class Replay:
+    """ft-eyes' classic tracker (Eye.feed, Tracker.command "click", the output loop) over a run's
+    finds, with variations."""
+
+    def __init__(self, run, frames, cal, shifts, status, clicks, jump="each", guard=False, bridge=False, box=None):
+        self.run, self.frames, self.cal = run, frames, cal
+        self.clicks = sorted(clicks, key=lambda c: c[0])  # (apply at, look t, (yaw, pitch))
+        self.jump, self.guard, self.bridge, self.box = jump, guard, bridge, box
+        self.shift = {}
+        for e in (0, 1):
+            sh = eyes_model.Shift.from_json(shifts[e]) if e in shifts else eyes_model.Shift()
+            st = ((status or {}).get("eyes") or {}).get(("right", "left")[e]) or {}
+            sh.reseated = bool(st.get("reseat", e not in shifts))
+            if st.get("jump") and jump is not None:
+                sh.jump = np.asarray(st.get("jump_px", (0, 0)), float)
+            self.shift[e] = sh
+        self.slip = {e: eyes_model.SlipTracker(cal, e, window=eyes_model.JUMP_WINDOW) for e in (0, 1)}
+        self.history = {0: deque(), 1: deque()}
+        self.gaze = {0: None, 1: None}
+        self.last_t = {0: None, 1: None}
+        self.off = {0: None, 1: None}
+        self.taught = self.skipped = 0
+        self.out_e = []   # with each output: the eyes' gazes in it, (left, right)
+
+    def value(self, e):
+        sh = self.shift[e]
+        if self.jump == "both" and not all(np.any(self.shift[o].jump) for o in (0, 1)):
+            return sh.base
+        return sh.value
+
+    def click(self, t, truth):
+        if self.guard and self.box and not (self.box[0] - EDGE_MARGIN <= truth[0] <= self.box[1] + EDGE_MARGIN
+                                            and self.box[2] - EDGE_MARGIN <= truth[1] <= self.box[3] + EDGE_MARGIN):
+            self.skipped += 1
+            return
+        both = all(np.any(self.shift[o].jump) for o in (0, 1))
+        for e in (0, 1):
+            rows = [h for h in self.history[e] if t - CLICK_BEFORE <= h[0] <= t]
+            if len(rows) < CLICK_MIN or not self.cal.has("where", e):
+                continue
+            pupil = np.median(np.array([h[1:3] for h in rows]), axis=0)
+            d = self.cal.click_shift(e, pupil, truth)
+            sh = self.shift[e]
+            # A jump in force (both-jump: in both eyes) means the headset moved: the older clicks are stale
+            if (both if self.jump == "both" else np.any(sh.jump)) or sh.reseated:
+                sh.meas, sh.reseated = [], False
+            sh.meas = (sh.meas + [np.asarray(d, float)])[-SHIFT_KEEP:]
+            sh.base = np.median(sh.meas, axis=0)
+            sh.jump, sh.held = np.zeros(2), None
+            if self.slip[e].value is not None:
+                sh.ref = np.asarray(self.slip[e].value, float)
+        self.taught += 1
+
+    def __call__(self):
+        """The output, (times, yaw, pitch) arrays, one per frame that changed it."""
+        out_t, out_g = [], []
+        ci = 0
+        last_out = None
+        for t, e, x, y, mid, _ in self.frames:
+            while ci < len(self.clicks) and self.clicks[ci][0] <= t:
+                self.click(*self.clicks[ci][1:])
+                ci += 1
+            if self.last_t[e] is not None and t - self.last_t[e] > GAP:
+                self.shift[e].reseat()
+            self.last_t[e] = t
+            h = self.history[e]
+            h.append((t, x, y))
+            while h[0][0] < t - HISTORY:
+                h.popleft()
+            if not self.cal.has("pupil", e):
+                continue
+            if mid is not None:
+                self.slip[e].add(t, (x, y), mid)
+            if self.jump is not None:
+                self.shift[e].glint(self.slip[e].get(t), t)
+            g = self.cal.gaze(e, x, y, self.value(e))
+            self.gaze[e] = (t, float(g[0]), float(g[1]))
+            latest = max(v[0] for v in self.gaze.values() if v)
+            use = {k: v[1:] for k, v in self.gaze.items() if v and latest - v[0] < FRESH}
+            out = self.cal.combine(use)
+            if self.bridge:
+                if len(use) == 2:
+                    a = 1.0 if last_out is None else 1 - math.exp(-(t - last_out) / BRIDGE_TAU)
+                    for k, v in use.items():
+                        d = np.asarray(out) - np.asarray(v)
+                        self.off[k] = d if self.off[k] is None else self.off[k] + a * (d - self.off[k])
+                elif len(use) == 1:
+                    (k, v), = use.items()
+                    if self.off[k] is not None:
+                        out = np.asarray(v) + self.off[k]
+            last_out = t
+            out_t.append(latest)
+            out_g.append((float(out[0]), float(out[1])))
+            self.out_e.append(tuple(None if k not in use else (float(use[k][0]), float(use[k][1])) for k in (1, 0)))
+        return out_t, out_g
+
+
+def calibration_box(run, cal):
+    """The calibration's dots' extent (yaw min, max, pitch min, max), from calibration-dots.jsonl."""
+    made = cal.info.get("made")
+    pts = [r["truth"] for r in jsonl(run.dir / "start" / "eyes-calibration-dots.jsonl") if r.get("made") == made]
+    if len(pts) < 4:
+        return (-20.0, 20.0, -20.0, 20.0)
+    return (min(p[0] for p in pts), max(p[0] for p in pts), min(p[1] for p in pts), max(p[1] for p in pts))
+
+
+def replays(run, truths, only):
+    """{name: function(t0, t1) -> (yaw, pitch) or None} for the replays, or {} with a note."""
+    want = [n for n in REPLAYS if not only or n in only]
+    if not want:
+        return {}
+    status = (run.info["start"] or {}).get("eyes")
+    if status is None:
+        run.notes.append("our tracker wasn't running at the start: no replays")
+        return {}
+    if status.get("feature", "pupil") != "pupil":
+        run.notes.append(f"our tracker ran {status.get('feature')}: replays are of the classic tracker only")
+        return {}
+    calp = run.dir / "start" / "eyes-calibration.json"
+    if not calp.exists():
+        run.notes.append("no calibration in start/: no replays")
+        return {}
+    cal = eyes_model.Calibration.load(calp)
+    shifts = {}
+    try:
+        st = json.loads((run.dir / "start" / "eyes-state.json").read_text())
+        if st.get("calibration") == cal.info.get("made"):
+            shifts = {int(k): v for k, v in st.get("shift", {}).items()}
+    except (OSError, ValueError):
+        pass
+    frames = {}
+    if not run.frames():
+        run.notes.append("no finds in own.jsonl: no replays")
+        return {}
+    nudges = [(ls["time"] - run.wall, ls["look_t"], tuple(ls["true"])) for ls in run.lessons
+              if ls.get("kind") == "own" and ls.get("look_t") is not None]
+    every = [(r["click"]["t"], r["click"]["t"] - run.look[1], truths[id(r)]) for r in run.trials
+             if truths.get(id(r)) is not None]
+    box = calibration_box(run, cal)
+    out = {}
+    for name in want:
+        opt = dict(REPLAYS[name])
+        teach = every if opt.pop("teach", None) == "every" else nudges
+        size = opt.pop("size", None)
+        if size not in frames:
+            frames[size] = run.frames(size)
+        replay = Replay(run, frames[size], cal, shifts, status, teach, box=box, **opt)
+        t, g = replay()
+        run.replay_eyes[name] = (t, replay.out_e)
+
+        def look(t0, t1, t=t, g=g):
+            return median2(g[bisect.bisect_left(t, t0):bisect.bisect_right(t, t1)])
+        out[name] = look
+    return out
+
+
+def fuse_look(inputs, weights, fusion, share=None, clicks=False):
+    """Fusion.combine per sample (fusion_inputs), ours combined as ft-gazed does; the look's median."""
+    out = []
+    for eyes, left, right in inputs:
+        own = weights.combine(eyes)
+        out.append(fusion.combine(own, sum(e is not None for e in eyes), fusion.steam_gaze(left, right, clicks), share))
+    return median2(out)
+
+
+def own_weights(run):
+    """ft-gazed's weights for our tracker's eyes when the run started (its lessons' misses)."""
+    try:
+        misses = json.loads((run.dir / "start" / "gazed-pointer-lessons.json").read_text())["misses"]["own"]
+    except (OSError, ValueError, KeyError, TypeError):
+        misses = None
+    return EyeWeights(((run.info["start"] or {}).get("gazed") or {}).get("eye_bias", "auto"), misses)
+
+
+def score(run, only=None):
+    """A record per click: where it was, and each technique's error (degrees, or None)."""
+    truths = {id(r): run.truth(r) for r in run.trials}
+    rep = replays(run, truths, only)
+    last_lesson = run.info.get("last_lesson")
+    weights = own_weights(run)
+    fusion = Fusion.load(run.dir / "start" / "gazed-fusion.json")
+    if fusion and not fusion.ready():
+        fusion = None
+    if fusion:
+        fusion.wear = run.dir.name
+    recs, steam_offsets = [], []
+    for r in run.trials:
+        truth = truths[id(r)]
+        t0, t1 = run.look_window(r)
+        own, steam = run.source("own", t0, t1), run.source("mmap1", t0, t1)
+        left, right = run.source("left", t0, t1), run.source("right", t0, t1)
+        mean = Fusion.mean(left, right)
+        inputs = run.fusion_inputs(t0, t1)
+        g = {"own-live": own, "steamvr": steam, "steamvr-eyes": mean}
+        ls = r.get("lesson")
+        if ls:
+            g["pointer"] = tuple(ls["raw"])
+        elif not run.panel:
+            c = r["click"]
+            g["pointer"] = run.direction(run.window(t0, t1), c["x"] * run.sx, c["y"] * run.sy)
+        g["fuse"] = (tuple(FUSE * a + (1 - FUSE) * b for a, b in zip(own, mean)) if own and mean else None)
+        if fusion:
+            g["steamvr-affine"] = fusion.steam_gaze(left, right, clicks=False)
+            g["steamvr-affine+clicks"] = fusion.steam_gaze(left, right)
+            g["fusion"] = fuse_look(inputs, weights, fusion)
+            if truth:
+                fusion.click(left, right, *truth)
+        if steam and steam_offsets:
+            keep = steam_offsets[-SHIFT_KEEP:]
+            g["steamvr+clicks"] = (steam[0] + statistics.median(o[0] for o in keep),
+                                   steam[1] + statistics.median(o[1] for o in keep))
+        else:
+            g["steamvr+clicks"] = steam
+        if steam and truth:
+            steam_offsets.append((truth[0] - steam[0], truth[1] - steam[1]))
+        for name, look in rep.items():
+            g[name] = look(t0, t1)
+        wall = r["click"]["t"] + run.wall
+        before = [ls_["time"] for ls_ in run.lessons if ls_["time"] < wall - LESSON_MATCH]
+        last = before[-1] if before else last_lesson
+        u, v = r["u"], r["v"]
+        edges = sum(1 for w in (u, v) if w in (0.0, 1.0))
+        rec = {"run": run.dir.name, "scenario": run.scenario, "i": r["i"], "u": u, "v": v,
+               "where": ("corner" if edges == 2 else "edge" if edges else "inside"),
+               "truth": truth, "ecc": math.hypot(*truth) if truth else None,
+               "since": None if last is None else wall - last, "nudged": bool(ls),
+               "err": {k: angle(val, truth) for k, val in g.items() if not only or k in only},
+               "_fz": {"left": left, "right": right, "mean": mean, "inputs": inputs, "weights": weights,
+                       "replays": {n: run.fusion_inputs(t0, t1, n) for n in FUSE_REPLAYS if n in run.replay_eyes}}}
+        if ls:
+            c = r["click"]
+            cd = run.direction(run.window(t0, t1), c["x"] * run.sx, c["y"] * run.sy)
+            rec["check"] = angle(cd, tuple(ls["true"]))
+        if g.get("own-replay") and own:
+            rec["replay_vs_live"] = angle(g["own-replay"], own)
+        recs.append(rec)
+    return recs
+
+
+def cross(recs, only=None):
+    """CROSS: SteamVR's affine and the fusion fitted on the other clicks (every other one: -loo;
+    the other runs' only: -xrun), each record's errors with them."""
+    want = [n for n in CROSS if not only or n in only]
+    have = [r for r in recs if r["truth"] and r["_fz"]["mean"]]
+    if not want or not have:
+        return
+    pts = {id(r): (*r["_fz"]["mean"], *r["truth"]) for r in have}
+    xrun = {}
+    for name in dict.fromkeys(r["run"] for r in recs):
+        xrun[name] = Fusion()
+        xrun[name].fit([pts[id(r)] for r in have if r["run"] != name])
+        xrun[name].wear = name
+    for r in recs:
+        fz, g = r["_fz"], {}
+        loo = Fusion()
+        loo.fit([pts[id(q)] for q in have if q is not r])
+        if loo.ready():
+            g["steamvr-affine-loo"] = loo.steam_gaze(fz["left"], fz["right"])
+            g["fusion-loo"] = fuse_look(fz["inputs"], fz["weights"], loo)
+            g["ours-else-steam-loo"] = fuse_look(fz["inputs"], fz["weights"], loo, share=1.0)
+            for name, inputs in fz["replays"].items():
+                g[f"fusion-loo:{name}"] = fuse_look(inputs, fz["weights"], loo)
+        x = xrun[r["run"]]
+        if x.ready():
+            g["steamvr-affine-xrun"] = x.steam_gaze(fz["left"], fz["right"], clicks=False)
+            g["steamvr-affine-xrun+clicks"] = x.steam_gaze(fz["left"], fz["right"])
+            g["fusion-xrun"] = fuse_look(fz["inputs"], fz["weights"], x)
+            g["fusion-xrun+clicks"] = fuse_look(fz["inputs"], fz["weights"], x, clicks=True)
+            if r["truth"]:
+                x.click(fz["left"], fz["right"], *r["truth"])
+        for k, v in g.items():
+            if not only or k in only:
+                r["err"][k] = angle(v, r["truth"])
+
+
+def fit_fusion(recs, out, runs):
+    """A Fusion fitted on all the clicks, written to out."""
+    pts = [(*r["_fz"]["mean"], *r["truth"]) for r in recs if r["truth"] and r["_fz"]["mean"]]
+    f = Fusion()
+    f.fit(pts, {"how": "bench", "runs": runs, "made": time.strftime("%Y-%m-%d %H:%M:%S")})
+    if not f.ready():
+        sys.exit(f"--fit-fusion: only {len(pts)} clicks with SteamVR's two eyes (need {Fusion.MIN})")
+    f.save(out)
+    print(f"\nfusion fitted on {len(pts)} clicks from {len(runs)} runs (SteamVR's affine leaves "
+          f"{statistics.median(f.misses()):.2f}° at the median on them): {out}")
+
+
+def bin_of(value, bins):
+    if value is None:
+        return "none" if bins is SINCE_BINS else "?"
+    return next((name for lo, hi, name in bins if lo <= value < hi), "?")
+
+
+def table(title, recs, key, names):
+    groups = {}
+    for r in recs:
+        groups.setdefault(key(r), []).append(r)
+    cols = list(groups)
+    if not cols:
+        return
+    w = max(len(n) for n in names) + 2
+    print(f"\n{title}: median degrees off (clicks)")
+    print(" " * w + "".join(f"{c:>13}" for c in cols))
+    for n in names:
+        cells = []
+        for c in cols:
+            errs = sorted(e for e in (r["err"].get(n) for r in groups[c]) if e is not None)
+            cells.append(f"{statistics.median(errs):6.2f} ({len(errs):3d})" if errs else f"{'-':>12}")
+        print(f"{n:<{w}}" + "".join(f"{x:>13}" for x in cells))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("runs", nargs="+", help="run folders, or folders of them")
+    ap.add_argument("--per-click", action="store_true", help="a line per click")
+    ap.add_argument("--json", help="write the per-click records here")
+    ap.add_argument("--only", help="comma-separated techniques")
+    ap.add_argument("--fit-fusion", metavar="OUT", help="fit a gazecal.Fusion on all the clicks, write it here")
+    a = ap.parse_args()
+    only = set(a.only.split(",")) if a.only else None
+    dirs = []
+    for p in map(Path, a.runs):
+        dirs += [p] if (p / "run.json").exists() else sorted(q.parent for q in p.glob("*/run.json"))
+    recs = []
+    for d in dirs:
+        run = Run(d)
+        got = score(run, only)
+        recs += got
+        print(f"{d.name}: {len(got)} clicks, {sum(r['nudged'] for r in got)} nudged"
+              + "".join(f"; {n}" for n in run.notes))
+    if not recs:
+        sys.exit("no clicks")
+    cross(recs, only)
+    names = [n for n in LIVE + CROSS + tuple(f"fusion-loo:{n}" for n in FUSE_REPLAYS) + tuple(REPLAYS)
+             if any(r["err"].get(n) is not None for r in recs)]
+    print()
+    w = max(len(n) for n in names) + 2
+    print(f"{'':<{w}}{'median':>8}{'p90':>8}{'mean':>8}{'n':>6}")
+    for n in names:
+        errs = sorted(e for e in (r["err"].get(n) for r in recs) if e is not None)
+        p90 = errs[min(len(errs) - 1, int(0.9 * len(errs)))]
+        print(f"{n:<{w}}{statistics.median(errs):8.2f}{p90:8.2f}{statistics.fmean(errs):8.2f}{len(errs):6d}")
+    apart = sorted(r["replay_vs_live"] for r in recs if r.get("replay_vs_live") is not None)
+    if apart:
+        p90 = apart[min(len(apart) - 1, int(0.9 * len(apart)))]
+        print(f"\nreplay vs live: our tracker's replay is {statistics.median(apart):.2f}° from what it published, "
+              f"at the median ({p90:.2f}° p90, {len(apart)} clicks); the replays are only as good as this")
+    checks = [r["check"] for r in recs if r.get("check") is not None]
+    if checks:
+        print(f"screen to direction vs the pointer's own: {statistics.median(checks):.2f}° apart at the median "
+              f"({len(checks)} nudges)")
+    table("By scenario", recs, lambda r: r["scenario"], names)
+    table("By where the target was", recs, lambda r: r["where"], names)
+    table("By how far from straight ahead", recs, lambda r: bin_of(r["ecc"], ECC_BINS), names)
+    table("By time since the last nudge", recs, lambda r: bin_of(r["since"], SINCE_BINS), names)
+    if a.per_click:
+        print()
+        for r in recs:
+            print(f"{r['run']} #{r['i']:<3} {r['where']:<6} ecc {r['ecc'] or 0:5.1f}°"
+                  + (" nudged" if r["nudged"] else "       ")
+                  + "".join(f"  {n} {r['err'][n]:.2f}" for n in names if r["err"].get(n) is not None))
+    if a.fit_fusion:
+        fit_fusion(recs, a.fit_fusion, [d.name for d in dirs])
+    if a.json:
+        Path(a.json).write_text(json.dumps([{k: v for k, v in r.items() if k != "_fz"} for r in recs], indent=1))
+
+
+if __name__ == "__main__":
+    main()

gaze/bench/ft-gazebench

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Launch the Frametop Gaze Bench from a Plasma session on the Frame host (its app menu entry,
+# gaze/bench/install.sh), as the eye recorder's gaze/rec/ft-eyerec: the app runs in Frametop's
+# container (PySide6), on the session's Wayland socket and bus; podman gets the real
+# XDG_RUNTIME_DIR and user bus.
+# Options go to gazebench.py: --base DIR (where runs go), --no-images, --no-button.
+here=$(cd "$(dirname "$(readlink -f "$0")")" && pwd)
+wl=${WAYLAND_DISPLAY:-wayland-0}
+case $wl in /*) ;; *) wl="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/$wl" ;; esac
+session_bus=${DBUS_SESSION_BUS_ADDRESS:-}
+export XDG_RUNTIME_DIR=/run/user/$(id -u)
+export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
+cd "$HOME" || exit 1
+exec "$here/../../scripts/in-box" env PATH="/opt/frametop/venv/bin:/opt/frametop/bin:$PATH:/usr/sbin:/sbin" \
+  WAYLAND_DISPLAY="$wl" DISPLAY="${DISPLAY:-}" \
+  XAUTHORITY="${XAUTHORITY:-}" DBUS_SESSION_BUS_ADDRESS="$session_bus" \
+  QT_QPA_PLATFORM="wayland;xcb" ${FT_GAZE:+FT_GAZE="$FT_GAZE"} ${FT_BENCH_BASE:+FT_BENCH_BASE="$FT_BENCH_BASE"} \
+  python3 "$here/gazebench.py" "$@"

gaze/bench/ft-gazebench.desktop

@@ -0,0 +1,9 @@
+[Desktop Entry]
+Type=Application
+Name=Frametop Gaze Bench
+GenericName=Test gaze tracking on hard targets
+Comment=Look at dots in hard places on a panel in the headset and press its button, to compare gaze techniques
+Exec=@REPO@/gaze/bench/ft-gazebench
+Icon=view-visible
+Categories=Utility;
+Keywords=eyes;eye tracking;gaze;test;bench;frametop;

gaze/bench/gazebench.py

@@ -0,0 +1,851 @@
+#!/usr/bin/env python3
+"""Frametop Gaze Bench: targets in hard places for gaze tracking, and a recording of every look
+at them, so gaze techniques can be compared on the same looks afterwards (README.md).
+
+The targets show on a panel fixed to the headset, our own ft-gazepanel in the eye recorder's
+mode (gaze/rec/session.py): wherever the head turns, a target stays at the same direction from
+it, so every run asks the same of the eyes. Pick a scenario (scenarios.json) in the window; the
+panel shows one dot at a time. Look at the dot and press the button on the headset's right side:
+where you looked is the dot. Two presses take the last one back, a hold ends the scenario. The
+window's keys do the same: Space marks, Backspace takes back, S skips, Esc ends. As in Frametop's
+gaze calibration, a left click, Enter, an index pinch (hand tracking) or Meta+J marks too, and a
+right click or Meta+K ends: the bench claims the pointer helper's calibration panel while its
+panel shows (pointer/helper/calpanel.h), so the helper answers those here and hides the pointer.
+
+Each scenario played is a run, recorded by benchrec.py into BASE/<time>-<scenario>/, with the
+panel's own log of what the dot did and when it reached the eyes, and the headset's pose. After
+each mark the window works out how far our tracker and SteamVR were off (their median over the
+LOOK before the press) for the summary; compare.py replays every technique on the recording.
+
+Runs in Frametop's container (PySide6), launched by ft-gazebench. --base DIR, --no-images.
+"""
+import argparse
+import json
+import math
+import os
+import random
+import signal
+import socket
+import statistics
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+from PySide6.QtCore import Property, QObject, QSocketNotifier, QTimer, QUrl, Signal, Slot
+from PySide6.QtGui import QGuiApplication
+from PySide6.QtQml import QQmlApplicationEngine
+from PySide6.QtQuickControls2 import QQuickStyle
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+GAZE = os.path.dirname(HERE)
+REPO = os.path.dirname(GAZE)
+sys.path.insert(0, HERE)
+sys.path.insert(0, REPO)
+import benchrec  # noqa: E402
+from recorder.button import ButtonReader, find_button, read_input_devices  # noqa: E402
+from recorder.common import in_container  # noqa: E402
+
+PANEL_DEG, PANEL_ASPECT = 64.0, 0.75   # ft-gazepanel's rec panel (kFullDeg, 4:3), as gaze/rec/session.py
+MARGIN = 1.5            # degrees from the panel's edge to a target at 0 or 1, measured in the panel's plane
+                        # from straight ahead: about 1.1 out at the edges, where the dot's ring (0.75
+                        # out from its middle) still fits
+PANEL_SOCK = os.environ.get("FT_BENCH_PANEL_SOCKET", "ft_benchpanel")   # (the tests' stand-in)
+PANEL_OVERLAY = "frametop.benchpanel"
+HELPER_SOCK = os.environ.get("FT_BENCH_HELPER_SOCKET", "ft_pointer_helper")   # (the tests' stand-in)
+CLAIM_EVERY = 1.0       # s between claims of the helper's calibration panel (it lets one go after 3 s)
+PANELS = [Path(p) for p in (os.environ.get("FT_GAZEPANEL"), os.path.join(GAZE, "build", "ft-gazepanel"),
+                            Path.home() / ".local/share/frametop/releases/current/gaze/build/ft-gazepanel") if p]
+IN_BOX = os.path.join(REPO, "scripts", "in-box")
+PANEL_WAIT = 20.0       # s for a new panel to answer (SteamVR's overlays can take a while)
+LOOK = (0.4, 0.1)       # s before a press: the gaze samples a mark takes. It ends a little before the
+                        # press (a click's was 0.05 s): the push on the headset's side comes before it
+DONE_S = 0.25           # s a dot marked from the window's keys shows done before the next (the
+                        # button's shows done from its down, a double-press time before)
+WAKE = 60               # s: the gaze service's wake lease while a run records (Input Settings' Gaze
+                        # page does the same), so the trackers run whether gaze mode is on or not
+# SteamVR's is the mean of its two eyes (set 2's left and right): on the 2026-10-17 runs it was
+# nearer than its combined gaze (mmap1), and it's what ft-gazed's fusion corrects.
+QUICK_SOURCES = (("own", "Our tracker"), ("steam-eyes", "SteamVR"))
+
+
+def quick_gaze(src, key):
+    """A sample's (yaw, pitch) for a QUICK_SOURCES key, or None."""
+    if key == "steam-eyes":
+        left, right = src.get("left") or {}, src.get("right") or {}
+        if "hy" in left and "hy" in right:
+            return (left["hy"] + right["hy"]) / 2, (left["hp"] + right["hp"]) / 2
+        return None
+    g = src.get(key) or {}
+    return (g["hy"], g["hp"]) if "hy" in g and g.get("ok", 1) != 0 else None
+KEYS_START = "Press the button, click, Enter or pinch to start. Hold the button or right click to end."
+KEYS_END = "Press the button, click, Enter or pinch to close this."
+
+
+def boxed(argv):
+    """A program built in the dev container: run it there (scripts/in-box from the host)."""
+    return list(argv) if in_container() or not os.path.exists(IN_BOX) else [IN_BOX] + list(argv)
+
+
+def margins(margin=MARGIN):
+    """MARGIN as fractions of the panel across and down."""
+    half = math.tan(math.radians(PANEL_DEG / 2))
+    m = math.tan(math.radians(margin)) / (2 * half)
+    return m, m / PANEL_ASPECT
+
+
+def panel_direction(u, v, margin=MARGIN):
+    """The head-relative direction (yaw +left, pitch +up, degrees) of a target u across and v down
+    the panel, 0 and 1 being margin degrees in from its edges: ft-gazepanel's ToPixel backwards."""
+    half = math.tan(math.radians(PANEL_DEG / 2))
+    mx, my = margins(margin)
+    x, y = mx + u * (1 - 2 * mx), my + v * (1 - 2 * my)
+    yaw = math.atan((0.5 - x) * 2 * half)
+    pitch = math.atan((0.5 - y) * 2 * half * PANEL_ASPECT * math.cos(yaw))
+    return math.degrees(yaw), math.degrees(pitch)
+
+
+def panel_place(yaw, pitch, margin=MARGIN):
+    """panel_direction backwards: u, v for a direction."""
+    half = math.tan(math.radians(PANEL_DEG / 2))
+    mx, my = margins(margin)
+    y_r = math.radians(yaw)
+    x = 0.5 - math.tan(y_r) / (2 * half)
+    y = 0.5 - math.tan(math.radians(pitch)) / math.cos(y_r) / (2 * half) / PANEL_ASPECT
+    return (x - mx) / (1 - 2 * mx), (y - my) / (1 - 2 * my)
+
+
+def unit(yaw, pitch):
+    """ft-gaze's head-relative yaw (+left), pitch (+up), degrees, as a unit vector (-Z ahead)."""
+    y, p = math.radians(yaw), math.radians(pitch)
+    return (-math.sin(y) * math.cos(p), math.sin(p), -math.cos(y) * math.cos(p))
+
+
+def angle(a, b):
+    """Degrees between two (yaw, pitch) directions."""
+    d = sum(x * y for x, y in zip(unit(*a), unit(*b)))
+    return math.degrees(math.acos(max(-1.0, min(1.0, d))))
+
+
+def make_trials(sc, rng):
+    """The scenario's targets, in order: dicts with u, v (fractions of the panel across and down,
+    panel_direction), and maybe bg (the panel's brightness, 0 to 1) and dwell (s)."""
+    spec = sc["targets"]
+    pts = []
+    if "grid" in spec:
+        cols, rows = spec["grid"]
+        lo, hi = spec.get("span", (0.2, 0.8))
+        at = lambda k, n: lo + (hi - lo) * k / (n - 1) if n > 1 else 0.5  # noqa: E731
+        pts = [{"u": at(i, cols), "v": at(j, rows)} for j in range(rows) for i in range(cols)]
+    elif "edges" in spec:
+        n = spec["edges"]
+        seen = []
+        for k in range(n):
+            t = k / (n - 1)
+            for p in ((t, 0.0), (t, 1.0), (0.0, t), (1.0, t)):
+                if p not in seen:
+                    seen.append(p)
+        pts = [{"u": u, "v": v} for u, v in seen]
+    elif "rays" in spec:
+        dirs = spec.get("dirs", 8)
+        for f in spec["rays"]:
+            for k in range(dirs):
+                a = 2 * math.pi * k / dirs
+                c, s = math.cos(a), math.sin(a)
+                m = max(abs(c), abs(s))  # so 1 reaches the edge, or the corner on a diagonal
+                pts.append({"u": 0.5 + 0.5 * f * c / m, "v": 0.5 - 0.5 * f * s / m})
+    elif "random" in spec:
+        for _ in range(spec["random"]):
+            u, v = rng.random(), rng.random()
+            if rng.random() < spec.get("edge_share", 0.0):
+                if rng.random() < 0.5:
+                    u = float(round(u))
+                else:
+                    v = float(round(v))
+            pts.append({"u": u, "v": v})
+    elif "steps" in spec:
+        # A walk of small steps from the middle: each target lo to hi degrees from the last, within
+        # the box (degrees either side of straight ahead)
+        lo, hi = spec.get("size", (2.0, 4.0))
+        by, bp = spec.get("box", (12.0, 9.0))
+        at = (0.0, 0.0)
+        for _ in range(spec["steps"]):
+            for _ in range(100):
+                a, d = rng.uniform(0, 2 * math.pi), rng.uniform(lo, hi)
+                nxt = (at[0] + d * math.cos(a), at[1] + d * math.sin(a))
+                if abs(nxt[0]) <= by and abs(nxt[1]) <= bp:
+                    break
+            at = nxt
+            u, v = panel_place(*at)
+            pts.append({"u": u, "v": v})
+    if sc.get("shuffle"):
+        rng.shuffle(pts)
+    for i, p in enumerate(pts):
+        if sc.get("backgrounds"):
+            p["bg"] = sc["backgrounds"][i % len(sc["backgrounds"])]
+        if sc.get("dwell"):
+            p["dwell"] = sc["dwell"]
+    return pts
+
+
+def git_rev():
+    try:
+        return subprocess.run(["git", "-C", HERE, "describe", "--always", "--dirty"], capture_output=True,
+                              text=True, timeout=5).stdout.strip() or None
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+class Panel:
+    """Our own ft-gazepanel in its rec mode (as gaze/rec/session.py runs one): 64 degrees across,
+    fixed to the headset, a solid background and one dot. Commands go to its control socket
+    without waiting; it answers each one, in order, and the answers are read later (errors
+    logged), or waited for by ask()."""
+
+    def __init__(self, prog=None, log=print, no_vr=False):
+        self.prog = Path(prog) if prog else next((p for p in PANELS if p.exists()), PANELS[0])
+        self.log, self.no_vr = log, no_vr
+        self.proc = None
+        self.ready = False
+        self.error = None
+        self.sent = {}
+        self.pending = 0     # commands sent and not answered yet
+        self.lock = threading.Lock()
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_CLOEXEC)
+        self.sock.bind("")
+        self.sock.setblocking(False)
+
+    def start(self):
+        """Start it and wait for its answer: call from a thread (SteamVR can take a while)."""
+        self.ready, self.error = False, None
+        if not self.prog.exists():
+            self.error = f"{self.prog} isn't there: run gaze/build.sh in the dev container"
+            return False
+        argv = [str(self.prog), "--watch-stdin", "--socket", PANEL_SOCK, "--overlay", PANEL_OVERLAY]
+        try:
+            self.proc = subprocess.Popen(boxed(argv + (["--no-vr"] if self.no_vr else [])), stdin=subprocess.PIPE,
+                                         stdout=subprocess.DEVNULL, start_new_session=True)
+        except OSError as e:
+            self.error = f"can't start {self.prog.name}: {e}"
+            return False
+        self.log(f"started {self.prog} (pid {self.proc.pid})")
+        end = time.monotonic() + PANEL_WAIT
+        while time.monotonic() < end:
+            if self.ask("ping", 0.3):
+                self.ready = True
+                return True
+            if self.proc.poll() is not None:
+                self.error = f"{self.prog.name} exited ({self.proc.returncode}): is SteamVR running?"
+                return False
+        self.error = f"{self.prog.name} doesn't answer"
+        self.stop()
+        return False
+
+    def alive(self):
+        return self.ready and self.proc is not None and self.proc.poll() is None
+
+    def _got(self, r):
+        self.pending = max(0, self.pending - 1)
+        if r.startswith("error"):
+            self.log(f"panel: {r}")
+
+    def _drain(self):
+        while True:
+            try:
+                r = self.sock.recv(65536).decode(errors="replace")
+            except OSError:
+                return
+            self._got(r)
+
+    def cmd(self, text):
+        with self.lock:
+            self._drain()
+            try:
+                self.sock.sendto(text.encode(), "\0" + PANEL_SOCK)
+                self.pending += 1
+            except OSError:
+                pass
+
+    def ask(self, text, timeout=0.5):
+        """Send, and its answer (or None): the one after those of the commands still unanswered."""
+        with self.lock:
+            self._drain()
+            try:
+                self.sock.sendto(text.encode(), "\0" + PANEL_SOCK)
+            except OSError:
+                return None
+            self.pending += 1
+            end = time.monotonic() + timeout
+            while (left := end - time.monotonic()) > 0:
+                try:
+                    self.sock.settimeout(left)
+                    r = self.sock.recv(65536).decode(errors="replace")
+                except OSError:
+                    break
+                finally:
+                    self.sock.setblocking(False)
+                last = self.pending == 1
+                self._got(r)
+                if last:
+                    return r
+            self.pending = 0   # a lost answer: count afresh
+            return None
+
+    def set(self, key, text):
+        """Send only if it changes that part of the panel."""
+        if self.sent.get(key) != text:
+            self.sent[key] = text
+            self.cmd(text)
+
+    def show(self, bg):
+        self.cmd("show rec")   # an empty panel
+        self.sent = {}
+        self.set("bg", f"bg {bg:.3f}")
+
+    def lines(self, title="", text="", keys="", step=""):
+        for key, value in (("title", title), ("text", text), ("keys", keys), ("step", step)):
+            self.set(key, f"{key} {value}" if value else key)
+
+    def dot(self, yaw, pitch, state, progress=None):
+        self.set("dot", f"dot {yaw:.4f} {pitch:.4f} {state}" + ("" if progress is None else f" {progress:.2f}"))
+
+    def close(self):
+        self.sock.close()
+
+    def stop(self):
+        p, self.proc, self.ready = self.proc, None, False
+        if not p:
+            return
+        try:
+            p.stdin.close()   # --watch-stdin: it quits
+            p.wait(5)
+        except (OSError, subprocess.TimeoutExpired):
+            try:
+                os.killpg(p.pid, signal.SIGTERM)
+                p.wait(3)
+            except (OSError, subprocess.TimeoutExpired):
+                p.kill()
+        self.log(f"panel stopped (exit {p.returncode})")
+
+
+def text_line(text):
+    """One line for the panel's socket: its own line breaks are "|"."""
+    return " ".join(text.replace("\n", "|").split())
+
+
+class Bench(QObject):
+    changed = Signal()
+    statusChanged = Signal()
+    # The headset button's events, from its reader's thread: "down", "press", "double", "hold",
+    # and the raw time of the press they're about (its down)
+    button = Signal(str, float)
+
+    def __init__(self, scenarios, base, images, gaze_prog=None, panel_prog=None, panel_no_vr=False, button=None):
+        super().__init__()
+        self.all = scenarios
+        self.base = base
+        self._images = images
+        self._page = "menu"
+        self._status = "Looking for the gaze service..."
+        self._progress = self._message = self._summary = self._last = self._notice = ""
+        self.bg = float(scenarios.get("background", 0.15))
+        self.gaze = benchrec.GazeStream(prog=gaze_prog, log=self.log).start()
+        self.gazed = benchrec.Sock(benchrec.GAZED_SOCK)
+        self.panel = Panel(panel_prog, self.log, panel_no_vr)
+        self.panel_starting = None
+        self.run = self.sc = None
+        self.stopping = None       # the last run's stop (it copies the logs), for shutdown to wait for
+        self.trials, self.i, self.results = [], 0, []
+        # A run's phase: intro (its message, until a press), target (a dot to look at), marked (its
+        # done shows), gap (no dot, a scenario's gap), end (the summary on the panel, until a press)
+        self.phase = None
+        self.target = None         # the dot showing: (yaw, pitch)
+        self.shown_t = self.ready_t = None
+        self.flashed = False       # the button's down showed this dot done before its press came
+        self.next_at = None        # monotonic: when the marked or gap phase ends
+        self.rev = git_rev()
+        self.button.connect(self.on_button)
+        self.down_t = None         # the reader's thread: its last down's raw time
+        self.reader = None
+        path = find_button(read_input_devices()) if button is None else button
+        if path:
+            self.reader = ButtonReader(path, self._gesture, self.log, on_down=self._down).start()
+        self.button_path = path or None
+        # The pointer helper's calibration panel (see the top): claimed as @ft_gazebench.PID while
+        # a run or its summary shows; its answers ("calaccept", "calquit") come back there.
+        self.claim_name = f"ft_gazebench.{os.getpid()}"
+        self.claim_at = None       # monotonic: the last claim; None while not claiming
+        self.helper = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_NONBLOCK | socket.SOCK_CLOEXEC)
+        self.helper_note = None
+        try:
+            self.helper.bind("\0" + self.claim_name)
+            self.helper_note = QSocketNotifier(self.helper.fileno(), QSocketNotifier.Type.Read, self)
+            self.helper_note.activated.connect(self.from_helper)
+        except OSError as e:
+            self.log(f"pointer helper socket: {e} (clicks, Enter and pinches won't mark)")
+        self.timer = QTimer(self)
+        self.timer.timeout.connect(self.tick)
+        self.timer.start(50)
+        self.status_at = 0.0
+        self.wake_at = 0.0
+        self.status_busy = False
+        self.status_thread = None
+        self.start_panel()
+
+    def log(self, line):
+        print("ft-gazebench: " + line, file=sys.stderr, flush=True)
+
+    def start_panel(self):
+        if self.panel_starting and self.panel_starting.is_alive():
+            return
+        self.panel_starting = threading.Thread(target=self._start_panel, daemon=True)
+        self.panel_starting.start()
+
+    def _start_panel(self):
+        if not self.panel.start():
+            self.log(f"panel: {self.panel.error}")
+        self.refresh_status()
+
+    # --- properties for bench.qml
+
+    def _get(name):  # noqa: N805
+        return lambda self: getattr(self, name)
+
+    page = Property(str, _get("_page"), notify=changed)
+    progress = Property(str, _get("_progress"), notify=changed)
+    message = Property(str, _get("_message"), notify=changed)
+    summary = Property(str, _get("_summary"), notify=changed)
+    last = Property(str, _get("_last"), notify=changed)
+    notice = Property(str, _get("_notice"), notify=changed)
+    status = Property(str, _get("_status"), notify=statusChanged)
+
+    def _set_images(self, v):
+        self._images = bool(v)
+        self.changed.emit()
+
+    images = Property(bool, _get("_images"), _set_images, notify=changed)
+
+    @Property("QVariantList", constant=True)
+    def scenarios(self):
+        out = []
+        for sc in self.all["scenarios"]:
+            n = len(make_trials(sc, random.Random(0)))
+            out.append({"id": sc["id"], "name": sc["name"], "about": sc["about"], "count": n})
+        return out
+
+    # --- status (in a thread: the sockets wait for replies)
+
+    def refresh_status(self):
+        if self.status_busy:
+            return
+        self.status_busy = True
+        self.status_thread = threading.Thread(target=self._status_thread, daemon=True)
+        self.status_thread.start()
+
+    def _status_thread(self):
+        try:
+            self._status = self.status_text()
+        finally:
+            self.status_busy = False
+        self.statusChanged.emit()
+
+    def status_text(self):
+        lines = []
+        if self.panel.alive():
+            lines.append("Headset panel: ready")
+        elif self.panel_starting and self.panel_starting.is_alive():
+            lines.append("Headset panel: starting...")
+        else:
+            lines.append(f"Headset panel: not running ({self.panel.error or 'it stopped'}). Starting a scenario tries again.")
+        lines.append(f"Headset button: {self.button_path}" if self.button_path else
+                     "Headset button: not found. Click, press Enter or pinch, or use this window's keys (Space marks).")
+        g = self.gazed.json("status")
+        if g is None:
+            lines.append("The gaze service isn't answering (frametop-gaze.service).")
+        else:
+            tracker = "our tracker" if g.get("tracker") == "own" else "SteamVR's tracker"
+            checks = g.get("checks") or {}
+            lines.append(f"Gaze service: {tracker}" + ("; gaze mode is on (the bench doesn't need it)"
+                                                        if checks.get("gaze_mode") else ""))
+            if checks.get("headset_worn") is False:
+                lines.append("Nobody is wearing the headset.")
+            if g.get("tracker") == "own":
+                made = g.get("calibration_made")
+                lines.append(f"Our tracker: calibrated {made}" if made else "Our tracker: not calibrated yet")
+        s = self.gaze.latest()
+        if self.gaze.error:
+            lines.append(f"ft-gaze: {self.gaze.error}")
+        elif s is None or benchrec.raw_now() - s.get("t", 0) > 2:
+            lines.append("ft-gaze: no samples yet (is SteamVR running?)")
+        else:
+            src = s.get("src", {})
+            ok = [n for k, n in QUICK_SOURCES if quick_gaze(src, k)]
+            lines.append("Gaze now from: " + (", ".join(ok) or "nothing (eyes closed, or the headset off?)"))
+        lines.append("Eye images: " + ("recorded (they stay on this headset)" if self._images else "off"))
+        lines.append(f"Runs go to {self.base}")
+        return "\n".join(lines)
+
+    # --- the headset button (its thread: to the Qt thread through the signal)
+
+    def _down(self, t):
+        self.down_t = benchrec.raw_now() - (time.monotonic() - t)
+        self.button.emit("down", self.down_t)
+
+    def _gesture(self, gesture):
+        self.button.emit(gesture, self.down_t or benchrec.raw_now())
+
+    @Slot(str, float)
+    def on_button(self, what, t):
+        if not self.run and self.phase != "end":
+            return
+        if what == "down":
+            # Done at once, so the press feels taken; it counts when "press" comes (a double is undo)
+            if self.phase == "target" and self.ready_t is not None and t >= self.ready_t:
+                self.panel.dot(*self.target, "done")
+                self.flashed = True
+        elif what == "press":
+            if self.phase == "end":
+                self.close_panel()
+            elif self.phase == "intro":
+                self.begin()
+            else:
+                self.mark(t, "button")
+        elif what == "double":
+            self.undo()
+        elif what == "hold" and self.run:
+            self.log("headset button: hold (end)")
+            self.finish(early=True)
+
+    # --- the pointer helper's calibration panel: clicks, Enter and pinches
+
+    def claim(self):
+        """Claim the helper's panel while a run or its summary shows on ours, and let it go after."""
+        want = (self.run is not None or self.phase == "end") and self.panel.alive()
+        now = time.monotonic()
+        if want and (self.claim_at is None or now - self.claim_at >= CLAIM_EVERY):
+            self.claim_at = now
+            self.to_helper(f"calpanel 1 {self.claim_name}")
+        elif not want and self.claim_at is not None:
+            self.claim_at = None
+            self.to_helper(f"calpanel 0 {self.claim_name}")
+
+    def to_helper(self, text):
+        try:
+            self.helper.sendto(text.encode(), "\0" + HELPER_SOCK)
+        except OSError:
+            pass  # the helper isn't running (SteamVR isn't)
+
+    @Slot()
+    def from_helper(self):
+        while True:
+            try:
+                data = self.helper.recv(256)
+            except OSError:
+                return
+            t = benchrec.raw_now()
+            what = data.decode(errors="replace").strip()
+            if self.claim_at is None:
+                continue  # a late answer: the panel is gone
+            if what == "calaccept":     # a press: as the button's, at its arrival
+                if self.phase == "end":
+                    self.close_panel()
+                elif self.phase == "intro":
+                    self.begin()
+                elif self.run:
+                    self.mark(t, "helper")
+            elif what == "calquit":     # as holding the button
+                if self.run:
+                    self.log("pointer helper: quit (end)")
+                    self.finish(early=True)
+                else:
+                    self.close_panel()
+
+    # --- a run
+
+    @Slot(str)
+    def start(self, sid):
+        if self.run:
+            return
+        if not self.panel.alive():
+            self._notice = ("The headset panel isn't running" + (f": {self.panel.error}" if self.panel.error else "")
+                            + ". Trying again; start the scenario once it's ready.")
+            self.start_panel()
+            self.refresh_status()
+            self.changed.emit()
+            return
+        self.sc = next(s for s in self.all["scenarios"] if s["id"] == sid)
+        seed = self.sc.get("seed", random.randrange(1 << 30))
+        self.trials = make_trials(self.sc, random.Random(seed))
+        self.i, self.results = 0, []
+        info = {"display": "panel", "panel": {"deg": PANEL_DEG, "aspect": PANEL_ASPECT, "margin": MARGIN,
+                                              "prog": str(self.panel.prog)},
+                "seed": seed, "look": LOOK, "app": {"rev": self.rev}, "trials_planned": len(self.trials),
+                "button": self.button_path}
+        self.run = benchrec.Run(self.sc, self.gaze, images=self._images, base=self.base, log=self.log, info=info).start()
+        r = self.panel.ask(f"log start {self.run.dir}")
+        if not (r or "").startswith("ok"):
+            self.log(f"panel log: {r or 'no answer'}")
+            self.run.info["panel"]["log_error"] = r or "no answer"
+            self.run.write_info()
+        self._page, self._summary, self._last, self._notice = "run", "", "", ""
+        prompt = self.sc.get("prompt", self.all.get("prompt", "Look at the dot and press the button (or click, Enter or pinch)."))
+        intro = [self.sc["message"]] if self.sc.get("message") else []
+        self._message = "\n".join(intro + [prompt])
+        self.phase, self.target, self.next_at = "intro", None, None
+        self.panel.show(self.bg)
+        self.panel.dot(0, 0, "off")
+        self.panel.lines(self.sc["name"], text_line(self._message), KEYS_START, f"{len(self.trials)} targets")
+        self._progress = f"{self.sc['name']}: {len(self.trials)} targets. Press the headset button (or Space) to start."
+        self.run.trial({"kind": "message", "text": self._message, "t": benchrec.raw_now()})
+        self.wake_at = 0.0
+        self.claim()
+        self.changed.emit()
+
+    def begin(self):
+        """The intro read: the first target."""
+        self.run.trial({"kind": "message-done", "t": benchrec.raw_now()})
+        self.panel.lines()
+        self.show(self.i)
+
+    @Slot()
+    def again(self):
+        if self._page == "done" and self.sc:
+            self.start(self.sc["id"])
+
+    def show(self, i):
+        self.i = i
+        if i >= len(self.trials):
+            return self.finish()
+        p = self.trials[i]
+        self.target = panel_direction(p["u"], p["v"])
+        bg = float(p.get("bg", self.bg))
+        self.panel.set("bg", f"bg {bg:.3f}")
+        self.shown_t = benchrec.raw_now()
+        dwell = p.get("dwell")
+        self.ready_t = None if dwell else self.shown_t
+        self.panel.dot(*self.target, "capture" if dwell else "look", 0.0 if dwell else None)
+        self.phase, self.flashed, self.next_at = "target", False, None
+        self._progress = f"{self.sc['name']}: {i + 1} of {len(self.trials)}"
+        self.changed.emit()
+
+    def quick(self, t, target):
+        """How far our tracker and SteamVR were from the target: their median direction over the
+        LOOK before t, {source: {"yaw", "pitch", "n", "deg"}}."""
+        samples = self.gaze.window(t - LOOK[0], t - LOOK[1])
+        out = {}
+        for key, _ in QUICK_SOURCES:
+            rows = [g for g in (quick_gaze(s.get("src") or {}, key) for s in samples) if g]
+            if len(rows) < 3:
+                continue
+            g = (statistics.median(r[0] for r in rows), statistics.median(r[1] for r in rows))
+            out[key] = {"yaw": round(g[0], 2), "pitch": round(g[1], 2), "n": len(rows), "deg": round(angle(g, target), 2)}
+        return out
+
+    @Slot()
+    def markKey(self):
+        """Space in the window: a mark now."""
+        if self.phase == "intro":
+            self.begin()
+        elif self.phase == "end":
+            self.close_panel()
+        elif self.run:
+            self.mark(benchrec.raw_now(), "key")
+
+    def mark(self, t, by):
+        """You were looking at the dot at t (a press's down)."""
+        if self.phase != "target" or t < self.shown_t:
+            self.run.trial({"kind": "stray", "t": t, "by": by, "phase": self.phase})
+            return
+        if self.ready_t is None or t < self.ready_t:
+            self.run.trial({"kind": "early", "i": self.i, "t": t, "by": by})
+            return
+        p = self.trials[self.i]
+        yaw, pitch = self.target
+        rec = {"kind": "trial", "i": self.i, "u": p["u"], "v": p["v"], "yaw": round(yaw, 4), "pitch": round(pitch, 4),
+               "bg": float(p.get("bg", self.bg)), "shown_t": self.shown_t, "ready_t": self.ready_t,
+               "click": {"t": t, "by": by}, "truth": {"yaw": round(yaw, 4), "pitch": round(pitch, 4), "from": "target"}}
+        rec["quick"] = self.quick(t, self.target)
+        self.results.append(rec)
+        self.run.trial(rec)
+        self._last = "Last: " + ", ".join(f"{label} {rec['quick'][k]['deg']:.1f}° off" if k in rec["quick"] else
+                                          f"{label} no gaze" for k, label in QUICK_SOURCES)
+        self.panel.dot(yaw, pitch, "done")
+        self.after(0.0 if self.flashed else DONE_S)
+
+    def after(self, wait):
+        """The next target, after wait (and the scenario's gap)."""
+        self.i += 1
+        self.phase, self.next_at = "marked", time.monotonic() + wait
+        self.changed.emit()
+
+    @Slot()
+    def skip(self):
+        if self.phase == "target":
+            p = self.trials[self.i]
+            self.run.trial({"kind": "trial", "i": self.i, "u": p["u"], "v": p["v"], "yaw": round(self.target[0], 4),
+                            "pitch": round(self.target[1], 4), "shown_t": self.shown_t,
+                            "click": {"t": benchrec.raw_now(), "by": "key"}, "skipped": True})
+            self.panel.dot(*self.target, "off")
+            self.after(0.0)
+
+    @Slot()
+    def undo(self):
+        """Back to the last target (self.i is the one showing, or the next one while marked or in
+        a gap)."""
+        if not self.run or self.phase in ("intro", "end"):
+            return
+        back = self.i - 1
+        if back < 0:
+            if self.phase == "target" and self.flashed:   # the first dot's down: show it again
+                self.show(self.i)
+            return
+        if self.results and self.results[-1]["i"] == back:
+            self.results.pop()
+        self.run.trial({"kind": "undo", "i": back, "t": benchrec.raw_now()})
+        self._last = "Took the last one back"
+        self.show(back)
+
+    @Slot()
+    def stop(self):
+        if self.run:
+            self.finish(early=True)
+        elif self._page == "done":
+            self.close_panel()
+            self._page = "menu"
+            self.changed.emit()
+        else:
+            QGuiApplication.quit()
+
+    def finish(self, early=False, why=None):
+        summary = self.summarize(early, why)
+        self.phase, self.next_at = "end", None
+        self._page = "done"
+        self._summary = summary["text"]
+        self.changed.emit()
+        run, self.run = self.run, None
+        run.info["panel"]["log_rows"] = self.panel.ask("log stop") if self.panel.alive() else None
+        if self.panel.alive():
+            self.panel.dot(0, 0, "off")
+            self.panel.set("bg", f"bg {self.bg:.3f}")
+            self.panel.lines("Ended early" if early else "Done", text_line(summary["panel"]), KEYS_END)
+        self.stopping = threading.Thread(target=lambda: run.stop(summary), daemon=True)
+        self.stopping.start()
+
+    def close_panel(self):
+        if self.phase == "end":
+            self.phase = None
+            self.panel.cmd("hide")
+            self.claim()
+
+    def summarize(self, early, why=None):
+        marks = [r for r in self.results if not r.get("skipped")]
+        lines = [f"{self.sc['name']}: {len(marks)} marked" + (" (ended early)" if early else "")]
+        if why:
+            lines.append(why)
+        out = {"marks": len(marks), "early": early}
+        for key, label in QUICK_SOURCES:
+            errs = sorted(r["quick"][key]["deg"] for r in marks if key in r.get("quick", {}))
+            if errs:
+                med, worst = statistics.median(errs), errs[-1]
+                p90 = errs[min(len(errs) - 1, int(0.9 * len(errs)))]
+                out[key] = {"median": med, "p90": p90, "worst": worst, "n": len(errs)}
+                lines.append(f"{label}: {med:.1f}° off at the median, {p90:.1f}° at the 90th percentile, worst {worst:.1f}°")
+            else:
+                lines.append(f"{label}: no gaze at the marks")
+        out["panel"] = "\n".join(lines)
+        if self.run:
+            lines.append(f"Saved in {self.run.dir}")
+        out["text"] = "\n".join(lines)
+        return out
+
+    # --- timers
+
+    def tick(self):
+        now = time.monotonic()
+        if self._page != "run" and now - self.status_at > 2:
+            self.status_at = now
+            self.refresh_status()
+        self.claim()
+        if not self.run:
+            return
+        if now - self.wake_at > WAKE / 2:
+            self.wake_at = now
+            threading.Thread(target=lambda: self.gazed.ask(f"wake {WAKE}"), daemon=True).start()
+        self.run.keepalive()
+        if not self.panel.alive():
+            self.log("the panel stopped")
+            return self.finish(early=True, why="The headset panel stopped.")
+        if self.phase == "target" and self.ready_t is None:
+            dwell = self.trials[self.i]["dwell"]
+            done = min(1.0, (benchrec.raw_now() - self.shown_t) / dwell)
+            self.panel.dot(*self.target, "capture", round(done, 2))
+            if done >= 1.0:
+                self.ready_t = benchrec.raw_now()
+        if self.next_at is not None and now >= self.next_at:
+            gap = self.sc.get("gap")
+            if self.phase == "marked" and gap and self.i < len(self.trials):
+                self.panel.dot(*self.target, "off")
+                self.phase, self.next_at = "gap", now + random.uniform(*gap)
+            else:
+                self.show(self.i)
+
+    def shutdown(self):
+        self.timer.stop()
+        if self.run:
+            self.finish(early=True)
+        if self.stopping:
+            self.stopping.join(10)
+        if self.reader:
+            self.reader.stop()
+        if self.panel.alive():
+            self.panel.cmd("hide")
+        if self.claim_at is not None:
+            self.to_helper(f"calpanel 0 {self.claim_name}")
+            self.claim_at = None
+        if self.helper_note:
+            self.helper_note.setEnabled(False)
+        self.helper.close()
+        for t in (self.panel_starting, self.status_thread):
+            if t:
+                t.join(PANEL_WAIT + 1)
+        self.panel.stop()
+        self.panel.close()
+        self.gaze.stop()
+        self.gazed.close()
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Frametop Gaze Bench")
+    ap.add_argument("--base", default=str(benchrec.BASE), help="where runs are recorded")
+    ap.add_argument("--no-images", action="store_true", help="don't record the eye cameras")
+    ap.add_argument("--scenarios", default=os.path.join(HERE, "scenarios.json"))
+    ap.add_argument("--ft-gaze", help="the ft-gaze to run (default: this tree's build, else the installed release's)")
+    ap.add_argument("--ft-gazepanel", help="the ft-gazepanel to run (default: this tree's build, else the release's)")
+    ap.add_argument("--panel-no-vr", action="store_true", help="the panel without SteamVR (its --no-vr)")
+    ap.add_argument("--no-button", action="store_true", help="don't read the headset button")
+    ap.add_argument("--style", default="Fusion", help="the Qt Quick Controls style")
+    a, qt_args = ap.parse_known_args()
+    app = QGuiApplication([sys.argv[0]] + qt_args)
+    app.setApplicationName("ft-gazebench")
+    app.setApplicationDisplayName("Frametop Gaze Bench")
+    app.setDesktopFileName("ft-gazebench")
+    QQuickStyle.setStyle(a.style)
+    with open(a.scenarios) as f:
+        scenarios = json.load(f)
+    bench = Bench(scenarios, a.base, not a.no_images, gaze_prog=a.ft_gaze, panel_prog=a.ft_gazepanel,
+                  panel_no_vr=a.panel_no_vr, button=False if a.no_button else None)
+    app.aboutToQuit.connect(bench.shutdown)
+    # A stop (the launcher's container doesn't pass one on, but kill does) ends a run properly
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, lambda *_: QGuiApplication.quit())
+    engine = QQmlApplicationEngine()
+    engine.rootContext().setContextProperty("bench", bench)
+    engine.load(QUrl.fromLocalFile(os.path.join(HERE, "bench.qml")))
+    if not engine.rootObjects():
+        sys.exit(1)
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

gaze/bench/install.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Add "Frametop Gaze Bench" to the app menu on a Frame with Frametop, for this tree (README.md).
+# It needs ft-gaze and ft-gazepanel (gaze/build.sh; a release brings them built, and a tree
+# without a build uses the installed release's) and, to record our tracker, ft-eyes
+# (gaze/tracker/install.sh).
+# Usage: gaze/bench/install.sh            install or update
+#        gaze/bench/install.sh uninstall  remove the menu entry. Runs stay where they are.
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+. "$root/scripts/_env.sh"
+entry='~/.local/share/applications/frametop-gazebench.desktop'
+
+case ${1:-install} in
+  install)
+    fill_template "$root/gaze/bench/ft-gazebench.desktop" |
+      on_frame "mkdir -p ~/.local/share/applications && cat > $entry"
+    echo "Installed. On Frametop's desktop, open \"Frametop Gaze Bench\" from the app menu."
+    echo "Runs go to ~/.local/share/frametop/gaze/bench."
+    ;;
+  uninstall)
+    on_frame "rm -f $entry"
+    echo "Removed the menu entry. Runs are still in ~/.local/share/frametop/gaze/bench."
+    ;;
+  *) echo "usage: $0 [install|uninstall]" >&2; exit 2 ;;
+esac

gaze/bench/scenarios.json

@@ -0,0 +1,75 @@
+{
+  "version": 2,
+  "about": "The gaze bench's scenarios (README.md). Targets show on the headset's panel (gazebench.py), 64 degrees across (4:3), fixed to the head. They're fractions of the panel across (u) and down (v); 0 and 1 are 1 degree in from its edges: 31 degrees left or right, 24 up or down, the corners 37 out. Generators: grid [cols, rows] over span; edges N per edge, corners included; rays: fractions of the way from the middle to the edge along dirs directions; random N with edge_share of them on an edge; steps N, each size [lo, hi] degrees from the last, within box [yaw, pitch] degrees of the middle. background and backgrounds are the panel's brightness, 0 to 1.",
+  "background": 0.15,
+  "prompt": "Look at the dot and press the button (or click, Enter or pinch).",
+  "scenarios": [
+    {
+      "id": "warmup",
+      "name": "Warm-up",
+      "about": "Nine dots around the middle.",
+      "targets": {"grid": [3, 3], "span": [0.2, 0.8]},
+      "shuffle": true
+    },
+    {
+      "id": "edges",
+      "name": "Edges",
+      "about": "Sixteen dots along the panel's edges and in its corners, 24 to 37 degrees out.",
+      "targets": {"edges": 5},
+      "shuffle": true
+    },
+    {
+      "id": "hold",
+      "name": "Hold at the edges",
+      "about": "Look at an edge dot until its ring fills (3 seconds), then press: the tracker loses an eye out there.",
+      "prompt": "Keep looking at the dot. Press when its ring is full.",
+      "targets": {"edges": 3},
+      "dwell": 3.0,
+      "shuffle": true
+    },
+    {
+      "id": "spokes",
+      "name": "Out from the middle",
+      "about": "Twenty-four dots on eight spokes, a third, two thirds and all the way out.",
+      "targets": {"rays": [0.35, 0.7, 1.0], "dirs": 8},
+      "shuffle": true
+    },
+    {
+      "id": "head-moving",
+      "name": "Head moving",
+      "about": "Keep looking at the dot while you turn or nod your head slowly, and press while it moves.",
+      "prompt": "Keep looking at the dot while you turn or nod your head slowly. Press while your head is still moving.",
+      "targets": {"grid": [3, 3], "span": [0.2, 0.8]},
+      "shuffle": true
+    },
+    {
+      "id": "light",
+      "name": "Light changes",
+      "about": "The panel switches between dark, bright and grey: your pupils change size.",
+      "targets": {"grid": [4, 3], "span": [0.1, 0.9]},
+      "backgrounds": [0.0, 0.95, 0.42],
+      "shuffle": true
+    },
+    {
+      "id": "steps",
+      "name": "Small steps",
+      "about": "Twenty dots, each 2 to 4 degrees from the last, near the middle.",
+      "targets": {"steps": 20, "size": [2.0, 4.0], "box": [12.0, 9.0]}
+    },
+    {
+      "id": "reseat",
+      "name": "After a nudge",
+      "about": "Lift the headset a little and set it back, then nine dots: how fast the tracker recovers.",
+      "message": "First lift the headset a little off your face and set it back down.",
+      "targets": {"grid": [3, 3], "span": [0.15, 0.85]},
+      "shuffle": true
+    },
+    {
+      "id": "long",
+      "name": "Long session",
+      "about": "Sixty dots anywhere at your own pace, a few seconds apart, about six minutes: drift, slips and stale corrections.",
+      "targets": {"random": 60, "edge_share": 0.3},
+      "gap": [1.0, 5.0]
+    }
+  ]
+}

gaze/bench/tests/fake_ft_gaze.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""A stand-in for ft-gaze in the bench's tests: 90 lines a second, the head facing the middle of
+a 1000 x 800 screen (number 2) at 20 px per degree, our tracker 0.5 degrees right of straight
+ahead and SteamVR 1 degree up. Quits when stdin closes, as ft-gaze --watch-stdin, or after
+$FAKE_GAZE_QUIT_AFTER seconds."""
+import json
+import os
+import sys
+import threading
+import time
+
+PPD = 20.0
+
+
+def hit(hy, hp):
+    return {"s": 2, "x": 500 - PPD * hy, "y": 400 - PPD * hp, "j": [-PPD, 0.0, 0.0, -PPD], "dpp": 1 / PPD}
+
+
+def watch():
+    while sys.stdin.buffer.read(4096):
+        pass
+    os._exit(0)
+
+
+threading.Thread(target=watch, daemon=True).start()
+quit_after = float(os.environ.get("FAKE_GAZE_QUIT_AFTER", "inf"))   # s: then exit, as when SteamVR quits
+start = time.monotonic()
+n = 0
+while time.monotonic() - start < quit_after:
+    t = time.clock_gettime(time.CLOCK_MONOTONIC_RAW)
+    own = {"hy": -0.5, "hp": 0.0, "hit": hit(-0.5, 0.0), "eyes": [[-0.5, 0.0], [-0.5, 0.0]],
+           "ehit": [hit(-0.5, 0.0), hit(-0.5, 0.0)]}
+    s = {"t": t, "age": 5, "n": n, "head": {"yaw": 0, "pitch": 0, "hit": hit(0, 0)},
+         "src": {"action": {"ok": 0}, "mmap1": {"hy": 0.0, "hp": 1.0, "hit": hit(0.0, 1.0)}, "mmap2": {"ok": 0},
+                 "left": {"hy": 0.0, "hp": 1.0, "hit": hit(0.0, 1.0)}, "right": {"hy": 0.0, "hp": 1.0, "hit": hit(0.0, 1.0)},
+                 "own": own}, "eye": None}
+    try:
+        sys.stdout.write(json.dumps(s) + "\n")
+        sys.stdout.flush()
+    except BrokenPipeError:
+        break
+    n += 1
+    time.sleep(1 / 90)

gaze/bench/tests/fake_ft_gazepanel.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""A stand-in for ft-gazepanel in the bench's tests: its control socket (--socket NAME) answers
+"ok" to everything, "log start DIR" writes the three logs' files there, "log stop" answers
+"ok 3 100 1". Each command goes on a line of $FT_FAKE_PANEL_LOG. Quits when stdin closes, as
+ft-gazepanel --watch-stdin."""
+import os
+import socket
+import sys
+import threading
+from pathlib import Path
+
+
+def watch():
+    while sys.stdin.buffer.read(4096):
+        pass
+    os._exit(0)
+
+
+name = sys.argv[sys.argv.index("--socket") + 1]
+log = os.environ.get("FT_FAKE_PANEL_LOG")
+threading.Thread(target=watch, daemon=True).start()
+sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+sock.bind("\0" + name)
+while True:
+    data, addr = sock.recvfrom(65536)
+    text = data.decode()
+    if log:
+        with open(log, "a") as f:
+            f.write(text + "\n")
+    reply = "ok"
+    if text.startswith("log start "):
+        for f in ("targets.jsonl", "poses.jsonl", "ipd.jsonl"):
+            (Path(text[10:]) / f).write_text("{}\n")
+    elif text == "log stop":
+        reply = "ok 3 100 1"
+    if addr:
+        sock.sendto(reply.encode(), addr)

gaze/bench/tests/test_bench.py

@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""The gaze bench without a headset: the scenarios' targets, bench.qml against gazebench.Bench,
+and whole runs recorded with stand-ins for ft-gaze (fake_ft_gaze.py), the panel
+(fake_ft_gazepanel.py), the headset button (a FIFO), our tracker, the gaze service and the pointer
+helper (their sockets), into a temporary folder. Needs PySide6 (the dev container); the parts that need it are
+skipped without it.
+
+  scripts/in-box python3 gaze/bench/tests/test_bench.py
+"""
+import json
+import os
+import random
+import re
+import socket
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+BENCH = HERE.parent
+sys.path.insert(0, str(BENCH))
+sys.path.insert(0, str(BENCH.parent.parent))
+os.environ["FT_BENCH_EYES_SOCKET"] = f"ft_eyes_benchtest_{os.getpid()}"
+os.environ["FT_BENCH_GAZED_SOCKET"] = f"ft_gazed_benchtest_{os.getpid()}"
+os.environ["FT_BENCH_PANEL_SOCKET"] = f"ft_benchpanel_test_{os.getpid()}"
+os.environ["FT_BENCH_HELPER_SOCKET"] = f"ft_pointer_helper_benchtest_{os.getpid()}"   # (not the live helper)
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+import benchrec  # noqa: E402
+from recorder.button import EV_KEY, INPUT_EVENT, KEY_SELECT  # noqa: E402
+
+try:
+    from PySide6.QtCore import QUrl
+    from PySide6.QtGui import QGuiApplication
+    from PySide6.QtQml import QQmlApplicationEngine
+    from PySide6.QtQuickControls2 import QQuickStyle
+    import gazebench
+    APP = QGuiApplication.instance() or QGuiApplication([sys.argv[0]])
+    QQuickStyle.setStyle("Fusion")  # the app's
+except ImportError as e:
+    gazebench, APP, NO_QT = None, None, str(e)
+
+SCENARIOS = json.loads((BENCH / "scenarios.json").read_text())
+FAKE_GAZE = HERE / "fake_ft_gaze.py"
+FAKE_PANEL = HERE / "fake_ft_gazepanel.py"
+OWN, STEAMVR = (-0.5, 0.0), (0.0, 1.0)   # fake_ft_gaze.py's gaze, head-relative degrees
+
+
+class FakeService(threading.Thread):
+    """A datagram server on an abstract socket that answers with reply(text)."""
+
+    def __init__(self, name, reply):
+        super().__init__(daemon=True)
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        self.sock.bind("\0" + name)
+        self.reply, self.heard, self.done = reply, [], False
+        self.start()
+
+    def stop(self):
+        self.done = True
+        self.join(1)
+        self.sock.close()
+
+    def run(self):
+        self.sock.settimeout(0.05)
+        while not self.done:
+            try:
+                data, addr = self.sock.recvfrom(65536)
+            except TimeoutError:
+                continue
+            except OSError:
+                return
+            text = data.decode()
+            self.heard.append(text)
+            r = self.reply(text)
+            if r is not None and addr:
+                self.sock.sendto(r.encode(), addr)
+
+
+class GazeStreamTest(unittest.TestCase):
+    def test_restarts(self):
+        """ft-gaze quits with SteamVR: it's started again, and the samples go on."""
+        saved = benchrec.RESTART
+        benchrec.RESTART = 0.2
+        os.environ["FAKE_GAZE_QUIT_AFTER"] = "0.3"
+        logs = []
+        g = benchrec.GazeStream(prog=FAKE_GAZE, log=logs.append).start()
+        try:
+            end = time.monotonic() + 5
+            while g.restarts < 2 and time.monotonic() < end:
+                time.sleep(0.05)
+            self.assertGreaterEqual(g.restarts, 2, logs)
+            lines = g.lines
+            end = time.monotonic() + 3
+            while g.lines <= lines and time.monotonic() < end:
+                time.sleep(0.05)
+            self.assertGreater(g.lines, lines)
+            self.assertIn("starting it again", logs[0])
+        finally:
+            del os.environ["FAKE_GAZE_QUIT_AFTER"]
+            benchrec.RESTART = saved
+            g.stop()
+        self.assertFalse(g.reader.is_alive())
+
+
+class ScenarioTest(unittest.TestCase):
+    def setUp(self):
+        if gazebench is None:
+            self.skipTest(f"no PySide6: {NO_QT}")
+
+    def test_targets(self):
+        for sc in SCENARIOS["scenarios"]:
+            ts = gazebench.make_trials(sc, random.Random(1))
+            self.assertTrue(ts, sc["id"])
+            for p in ts:
+                self.assertTrue(-1e-9 <= p["u"] <= 1 + 1e-9 and -1e-9 <= p["v"] <= 1 + 1e-9, (sc["id"], p))
+            if sc["id"] == "edges":
+                self.assertEqual(len(ts), 16)
+                self.assertTrue(all(p["u"] in (0, 1) or p["v"] in (0, 1) for p in ts))
+            if sc["id"] == "hold":
+                self.assertTrue(all(p["dwell"] == 3.0 for p in ts))
+            if sc["id"] == "light":
+                self.assertEqual({p["bg"] for p in ts}, set(sc["backgrounds"]))
+            if sc["id"] == "steps":
+                dirs = [(0.0, 0.0)] + [gazebench.panel_direction(p["u"], p["v"]) for p in ts]
+                steps = [gazebench.angle(a, b) for a, b in zip(dirs, dirs[1:])]
+                self.assertTrue(all(1.9 < d < 4.1 for d in steps), steps)
+                self.assertTrue(all(abs(y) <= 12.01 and abs(p) <= 9.01 for y, p in dirs), dirs)
+        rays = gazebench.make_trials(next(s for s in SCENARIOS["scenarios"] if s["id"] == "spokes"), random.Random(1))
+        outer = [p for p in rays if p["u"] in (0, 1) or p["v"] in (0, 1)]
+        self.assertEqual(len(outer), 8)  # the 1.0 ring reaches the edges and corners
+
+    def test_panel_direction(self):
+        d = gazebench.panel_direction
+        self.assertEqual(d(0.5, 0.5), (0.0, 0.0))
+        self.assertGreater(d(0, 0.5)[0], 30)    # u 0: left (+yaw)
+        self.assertGreater(d(0.5, 0)[1], 20)    # v 0: up (+pitch)
+        for u, v in ((0, 0), (1, 1), (0.2, 0.7), (0.9, 0.1)):
+            back = gazebench.panel_place(*d(u, v))
+            self.assertAlmostEqual(back[0], u, places=9)
+            self.assertAlmostEqual(back[1], v, places=9)
+        # Every scenario's dot shows whole: its ring (0.75 degrees out) is on the panel
+        for sc in SCENARIOS["scenarios"]:
+            for p in gazebench.make_trials(sc, random.Random(2)):
+                yaw, pitch = d(p["u"], p["v"])
+                for dy, dp in ((0.75, 0), (-0.75, 0), (0, 0.75), (0, -0.75)):
+                    x, y = gazebench.panel_place(yaw + dy, pitch + dp, margin=0)
+                    self.assertTrue(0 <= x <= 1 and 0 <= y <= 1, (sc["id"], p, dy, dp))
+
+
+class QmlTest(unittest.TestCase):
+    """bench.qml's bench.name(...) calls are slots and its bench.name reads are properties or slots."""
+
+    def setUp(self):
+        if gazebench is None:
+            self.skipTest(f"no PySide6: {NO_QT}")
+        meta = gazebench.Bench.staticMetaObject
+        self.slots = {bytes(meta.method(i).name()).decode() for i in range(meta.methodCount())}
+        self.props = {meta.property(i).name() for i in range(meta.propertyCount())}
+        self.qml = (BENCH / "bench.qml").read_text()
+
+    def test_names(self):
+        called = set(re.findall(r"\bbench\.(\w+)\s*\(", self.qml))
+        self.assertEqual(sorted(called - self.slots), [])
+        read = set(re.findall(r"\bbench\.(\w+)\b(?!\s*\()", self.qml)) - {"qml"}
+        self.assertEqual(sorted(read - self.props - self.slots), [])
+
+
+class RunTest(unittest.TestCase):
+    """A warm-up played through with the button and the keys, recorded and summed up; a hold
+    scenario ended by holding the button; bench.qml loaded on it."""
+
+    def setUp(self):
+        if gazebench is None:
+            self.skipTest(f"no PySide6: {NO_QT}")
+        self.tmp = tempfile.TemporaryDirectory()
+        tmp = Path(self.tmp.name)
+        self.saved = {k: getattr(benchrec, k) for k in ("STATE", "EYES_STATE", "LESSON_LOG", "CONF")}
+        benchrec.STATE = tmp / "state"
+        benchrec.EYES_STATE = benchrec.STATE / "eyes"
+        benchrec.LESSON_LOG = benchrec.STATE / "pointer-lessons.jsonl"
+        benchrec.CONF = tmp / "frametop.conf"
+        benchrec.EYES_STATE.mkdir(parents=True)
+        (benchrec.EYES_STATE / "calibration.json").write_text('{"version": 1, "fits": []}')
+        benchrec.CONF.write_text("GAZE_TRACKER=own\nOTHER=1\n")
+        benchrec.LESSON_LOG.write_text(json.dumps({"time": time.time() - 100, "kind": "own"}) + "\n")
+        self.finds = []
+        self.panel_log = tmp / "panel.log"
+        os.environ["FT_FAKE_PANEL_LOG"] = str(self.panel_log)
+        self.fifo = tmp / "button"
+        os.mkfifo(self.fifo)
+        self.button = os.open(self.fifo, os.O_RDWR)   # (Linux: doesn't wait for the reader)
+
+        def eyes(text):
+            w = text.split()
+            if w[0] == "status":
+                return json.dumps({"calibration": {"made": "2026-10-17 10:00:00"}, "feature": "pupil", "model": None,
+                                   "eyes": {"right": {"shift": [0, 0], "clicks": 0, "jump": False, "jump_px": [0, 0],
+                                                      "reseat": False}}})
+            if w[:2] == ["finds", "start"]:
+                self.finds.append(w[2])
+                Path(w[2]).write_text(json.dumps({"t": 1.0, "cam": 0, "lost": True}) + "\n")
+                return "ok"
+            if w[:2] == ["finds", "stop"]:
+                return "ok 1"
+            return "fail"
+
+        def gazed(text):
+            if text == "status":
+                return json.dumps({"tracker": "own", "calibration_made": "2026-10-17 10:00:00",
+                                   "checks": {"gaze_mode": False, "headset_worn": True}})
+            return "ok"
+
+        self.eyes = FakeService(benchrec.EYES_SOCK, eyes)
+        self.gazed = FakeService(benchrec.GAZED_SOCK, gazed)
+        self.helper = FakeService(os.environ["FT_BENCH_HELPER_SOCKET"], lambda text: None)
+
+    def tearDown(self):
+        for k, v in self.saved.items():
+            setattr(benchrec, k, v)
+        self.eyes.stop()
+        self.gazed.stop()
+        self.helper.stop()
+        os.close(self.button)
+        self.tmp.cleanup()
+
+    def wait(self, cond, timeout=5.0):
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            APP.processEvents()
+            if cond():
+                return True
+            time.sleep(0.02)
+        return False
+
+    def key(self, down):
+        t = time.time()
+        os.write(self.button, INPUT_EVENT.pack(int(t), int(t % 1 * 1e6), EV_KEY, KEY_SELECT, 1 if down else 0))
+
+    def press(self, held=0.08):
+        self.key(True)
+        self.wait(lambda: False, held)
+        self.key(False)
+
+    def panel_said(self):
+        return self.panel_log.read_text().splitlines() if self.panel_log.exists() else []
+
+    def bench(self, base):
+        bench = gazebench.Bench(SCENARIOS, str(base), images=False, gaze_prog=FAKE_GAZE, panel_prog=FAKE_PANEL,
+                                button=str(self.fifo))
+        self.assertTrue(self.wait(lambda: bench.gaze.latest() is not None), "no samples from the fake ft-gaze")
+        self.assertTrue(self.wait(bench.panel.alive), bench.panel.error)
+        return bench
+
+    def test_run(self):
+        base = Path(self.tmp.name) / "runs"
+        bench = self.bench(base)
+        try:
+            self.assertTrue(self.wait(lambda: "Headset panel: ready" in bench.status), bench.status)
+            self.assertIn(str(self.fifo), bench.status)
+            bench.start("warmup")
+            self.assertEqual((bench.page, bench.phase), ("run", "intro"))
+            run = next(base.iterdir())
+            self.assertTrue(self.wait(lambda: "title Warm-up" in self.panel_said()), self.panel_said())
+            said = self.panel_said()
+            self.assertIn("show rec", said)
+            self.assertIn(f"log start {run}", said)
+            self.press()                                # the intro: a press starts it
+            self.assertTrue(self.wait(lambda: bench.phase == "target"))
+            n = len(bench.trials)
+            pressed_at = None
+            for k in range(n):
+                self.assertTrue(self.wait(lambda: bench.phase == "target"), (k, bench.phase))
+                self.wait(lambda: False, 0.45)          # samples in the look window
+                if k == 0:                               # the button marks it, at its down
+                    pressed_at = benchrec.raw_now()
+                    self.press()
+                    self.assertTrue(self.wait(lambda: len(bench.results) == 1))
+                    continue
+                if k == 2:                               # two presses: back to 1, marked again
+                    self.press()
+                    self.wait(lambda: False, 0.1)
+                    self.press()
+                    self.assertTrue(self.wait(lambda: bench.i == 1 and bench.phase == "target"), (bench.i, bench.phase))
+                    self.wait(lambda: False, 0.45)
+                    bench.markKey()
+                    self.assertTrue(self.wait(lambda: bench.phase == "target"))
+                    self.wait(lambda: False, 0.45)
+                if k == 4:
+                    bench.skip()
+                    continue
+                bench.markKey()
+            self.assertTrue(self.wait(lambda: bench.page == "done"))
+            self.assertEqual(bench.phase, "end")
+            self.assertIn("Our tracker", bench.summary)
+            self.assertIn("log stop", self.panel_said())
+            self.assertTrue(self.wait(lambda: "title Done" in self.panel_said()), self.panel_said()[-5:])
+            self.press()                                 # closes the panel
+            self.assertTrue(self.wait(lambda: self.panel_said()[-1] == "hide"))
+            self.assertTrue(self.wait(lambda: "end" in json.loads((run / "run.json").read_text())))
+        finally:
+            bench.shutdown()
+        info = json.loads((run / "run.json").read_text())
+        self.assertEqual(info["scenario"]["id"], "warmup")
+        self.assertEqual(info["display"], "panel")
+        self.assertEqual(info["panel"]["log_rows"], "ok 3 100 1")
+        self.assertEqual(info["button"], str(self.fifo))
+        self.assertEqual(info["conf"], ["GAZE_TRACKER=own"])
+        self.assertIsNotNone(info["last_lesson"])
+        self.assertGreater(info["gaze_lines"], 50)
+        self.assertEqual(info["finds_rows"], "ok 1")
+        self.assertTrue((run / "start" / "eyes-calibration.json").exists())
+        self.assertTrue((run / "targets.jsonl").exists())
+        self.assertEqual(self.finds, [str(run / "own.jsonl")])
+        rows = [json.loads(line) for line in (run / "trials.jsonl").read_text().splitlines()]
+        kinds = [r["kind"] for r in rows]
+        self.assertEqual(kinds[:2], ["message", "message-done"])
+        self.assertIn("undo", kinds)
+        trials = [r for r in rows if r["kind"] == "trial"]
+        self.assertEqual(sum(1 for r in trials if r.get("skipped")), 1)
+        by_button = [r for r in trials if r["click"]["by"] == "button"]
+        self.assertEqual(len(by_button), 1)
+        # The mark's time is the press's down, not when the press was sure (a double-press time later)
+        self.assertLess(abs(by_button[0]["click"]["t"] - pressed_at), 0.2)
+        for r in trials:
+            if r.get("skipped"):
+                continue
+            target = gazebench.panel_direction(r["u"], r["v"])
+            self.assertAlmostEqual(r["truth"]["yaw"], target[0], places=3)
+            self.assertAlmostEqual(r["truth"]["pitch"], target[1], places=3)
+            q = r["quick"]
+            self.assertAlmostEqual(q["own"]["deg"], gazebench.angle(OWN, target), places=1)
+            self.assertAlmostEqual(q["steam-eyes"]["deg"], gazebench.angle(STEAMVR, target), places=1)
+        # The button's down showed the dot done before the press counted
+        self.assertTrue(any(c.startswith("dot ") and c.endswith(" done") for c in self.panel_said()))
+        self.assertGreater(len((run / "gaze.jsonl").read_text().splitlines()), 50)
+
+    def answer(self, bench, text):
+        """The pointer helper's answer to the bench's panel claim."""
+        c = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        c.sendto(text.encode(), "\0" + bench.claim_name)
+        c.close()
+
+    def test_helper(self):
+        """The pointer helper's calibration panel: claimed while a run or its summary shows, renewed;
+        its calaccept starts, marks (at its arrival) and closes, calquit ends; then it's let go."""
+        base = Path(self.tmp.name) / "runs"
+        bench = self.bench(base)
+        claim, release = f"calpanel 1 {bench.claim_name}", f"calpanel 0 {bench.claim_name}"
+        try:
+            self.wait(lambda: False, 0.2)
+            self.assertEqual(self.helper.heard, [], "no claim before a run")
+            bench.start("warmup")
+            self.assertTrue(self.wait(lambda: claim in self.helper.heard))
+            self.assertTrue(self.wait(lambda: self.helper.heard.count(claim) >= 2, 2.5), self.helper.heard)
+            self.answer(bench, "calaccept")             # the intro: starts it
+            self.assertTrue(self.wait(lambda: bench.phase == "target"))
+            self.wait(lambda: False, 0.45)
+            sent = benchrec.raw_now()
+            self.answer(bench, "calaccept")
+            self.assertTrue(self.wait(lambda: len(bench.results) == 1))
+            self.assertEqual(bench.results[0]["click"]["by"], "helper")
+            self.assertLess(abs(bench.results[0]["click"]["t"] - sent), 0.1)
+            self.answer(bench, "calquit")                # ends it
+            self.assertTrue(self.wait(lambda: bench.page == "done"))
+            self.assertIn("ended early", bench.summary)
+            self.assertNotIn(release, self.helper.heard, "the summary still shows")
+            self.answer(bench, "calaccept")             # closes the summary
+            self.assertTrue(self.wait(lambda: self.panel_said()[-1] == "hide"))
+            self.assertTrue(self.wait(lambda: self.helper.heard[-1] == release), self.helper.heard[-3:])
+            n = len(self.helper.heard)
+            self.answer(bench, "calaccept")             # late: nothing
+            self.wait(lambda: False, 1.3)
+            self.assertEqual(len(self.helper.heard), n, "no claim once the panel is gone")
+            self.assertIsNone(bench.run)
+            run = next(base.iterdir())
+            self.assertTrue(self.wait(lambda: "end" in json.loads((run / "run.json").read_text())))
+        finally:
+            bench.shutdown()
+
+    def test_hold(self):
+        """Hold at the edges: a press before the ring fills doesn't count; holding the button ends it."""
+        base = Path(self.tmp.name) / "runs"
+        bench = self.bench(base)
+        try:
+            bench.start("hold")
+            bench.markKey()
+            self.assertEqual(bench.phase, "target")
+            bench.markKey()                              # too soon
+            self.assertTrue(self.wait(lambda: any(re.fullmatch(r"dot \S+ \S+ capture 0\.\d+", c) for c in self.panel_said())))
+            self.key(True)
+            self.assertTrue(self.wait(lambda: bench.page == "done", 3))
+            self.key(False)
+            self.assertIn("ended early", bench.summary)
+            run = next(base.iterdir())
+            self.assertTrue(self.wait(lambda: "end" in json.loads((run / "run.json").read_text())))
+        finally:
+            bench.shutdown()
+        kinds = [json.loads(line)["kind"] for line in (run / "trials.jsonl").read_text().splitlines()]
+        self.assertIn("early", kinds)
+        self.assertNotIn("trial", kinds)
+
+    def test_no_panel(self):
+        bench = gazebench.Bench(SCENARIOS, str(Path(self.tmp.name) / "runs"), images=False, gaze_prog=FAKE_GAZE,
+                                panel_prog="/nonexistent/ft-gazepanel", button=False)
+        try:
+            self.wait(lambda: bench.panel.error is not None, 2)
+            bench.start("warmup")
+            self.assertEqual(bench.page, "menu")
+            self.assertIn("isn't running", bench.notice)
+            self.assertTrue(self.wait(lambda: "Headset panel: not running" in bench.status), bench.status)
+            self.assertIn("Headset button: not found", bench.status)
+        finally:
+            bench.shutdown()
+
+    def test_qml_loads(self):
+        bench = self.bench(Path(self.tmp.name) / "runs")
+        warnings = []
+        try:
+            engine = QQmlApplicationEngine()
+            engine.warnings.connect(lambda ws: warnings.extend(w.toString() for w in ws))
+            engine.rootContext().setContextProperty("bench", bench)
+            engine.load(QUrl.fromLocalFile(str(BENCH / "bench.qml")))
+            self.assertTrue(engine.rootObjects())
+            self.wait(lambda: False, 0.3)
+            bench.start("steps")
+            self.wait(lambda: False, 0.2)
+            bench.markKey()
+            self.wait(lambda: False, 0.2)
+            bench.stop()
+            self.wait(lambda: bench.page == "done", 1)
+            self.wait(lambda: False, 0.5)
+            self.assertEqual(warnings, [])
+            del engine
+        finally:
+            bench.shutdown()
+
+
+if __name__ == "__main__":
+    unittest.main()

gaze/bench/tests/test_compare.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""compare.py on a made-up run with known errors: SteamVR 1 degree high (its eyes 1 degree either
+side of that), our live tracker 0.5 degrees left (both its eyes), and our tracker's finds made
+from a calibration, with the headset slipping 8 px (2 degrees) a third of the way in, so the
+replays' jump rules differ in a known way. Needs
+numpy and OpenCV (the tracker's Python):
+
+  scripts/in-box /opt/frametop/venv/bin/python gaze/bench/tests/test_compare.py
+"""
+import json
+import math
+import shutil
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent))
+try:
+    import numpy as np
+    import cv2  # noqa: F401  (eyes_pupil's)
+    import compare
+    import eyes_model
+except ImportError as e:
+    compare, NO_DEPS = None, str(e)
+
+PPD = 20.0               # screen pixels per degree, as fake_ft_gaze.py
+K = 4.0                  # pupil pixels per degree
+T0, WALL = 1000.0, 1.79e9
+SLIP_AT, SLIP = 14.0, (8.0, 0.0)   # s after T0, px: the headset slips this much (both eyes)
+# (s after T0 of the click, yaw, pitch, nudged)
+TRIALS = [(3, 0, 0, False), (5, 10, 0, False), (7, -15, 5, True), (9, 5, -10, False), (11, 25, 0, False),
+          (13, -5, 8, False),
+          (16, 8, 3, False),                                  # 2 s after the slip: the jump isn't in yet
+          (24, -10, -5, False), (27, 12, 6, False), (30, 0, -12, False), (33, -18, 0, False)]
+
+
+def hit(hy, hp):
+    return {"s": 2, "x": 500 - PPD * hy, "y": 400 - PPD * hp, "j": [-PPD, 0.0, 0.0, -PPD], "dpp": 1 / PPD}
+
+
+def pupil(e, hy, hp, t):
+    """Where eye e's pupil is for a gaze, t s after T0."""
+    sx = SLIP[0] if t >= SLIP_AT else 0.0
+    return (256 + 10 * e + K * hy + sx, 200 - K * hp)
+
+
+def mid(e, t):
+    sx = SLIP[0] if t >= SLIP_AT else 0.0
+    return (256 + 10 * e + sx, 230.0)
+
+
+def looking(t):
+    """The target being looked at: the next one to be clicked."""
+    for tc, hy, hp, _ in TRIALS:
+        if t <= T0 + tc:
+            return hy, hp
+    return TRIALS[-1][1:3]
+
+
+def make_run(d):
+    (d / "start").mkdir(parents=True)
+    dots = [{"truth": (hy, hp), "eye": [{"pupil": np.array(pupil(e, hy, hp, 0)), "mid": np.array(mid(e, 0))}
+                                        for e in (0, 1)]}
+            for hy in (-20, -10, 0, 10, 20) for hp in (-15, -7, 0, 7, 15)]
+    cal = eyes_model.Calibration.fit(dots, {"made": "M", "feature": "pupil", "dots": len(dots)})
+    cal.save(d / "start" / "eyes-calibration.json")
+    with open(d / "start" / "eyes-calibration-dots.jsonl", "w") as f:
+        for k in dots:
+            f.write(json.dumps({"made": "M", "truth": k["truth"]}) + "\n")
+    blank = {"base": [0, 0], "ref": None, "meas": []}
+    (d / "start" / "eyes-state.json").write_text(json.dumps({"calibration": "M", "shift": {"0": blank, "1": blank}}))
+    eyes = {"right": {"reseat": False, "jump": False, "jump_px": [0, 0]},
+            "left": {"reseat": False, "jump": False, "jump_px": [0, 0]}}
+    (d / "run.json").write_text(json.dumps({
+        "scenario": {"id": "synthetic"}, "screen": {"w": 1000, "h": 800, "dpr": 1.0}, "look": [0.35, 0.05],
+        "start": {"time": WALL, "t_raw": T0, "eyes": {"feature": "pupil", "eyes": eyes}}, "last_lesson": WALL - 500}))
+    with open(d / "gaze.jsonl", "w") as g, open(d / "own.jsonl", "w") as o:
+        n = 0
+        while n / 90 < TRIALS[-1][0] + 1:
+            t = T0 + n / 90
+            hy, hp = looking(t)
+            src = {"mmap1": {"hy": hy, "hp": hp + 1, "hit": hit(hy, hp + 1)},
+                   "left": {"hy": hy + 1, "hp": hp + 1, "hit": hit(hy + 1, hp + 1)},
+                   "right": {"hy": hy - 1, "hp": hp + 1, "hit": hit(hy - 1, hp + 1)},
+                   "own": {"hy": hy + 0.5, "hp": hp, "hit": hit(hy + 0.5, hp),
+                           "eyes": [[hy + 0.5, hp], [hy + 0.5, hp]]}}
+            g.write(json.dumps({"t": t, "head": {"yaw": 0, "pitch": 0, "hit": hit(0, 0)}, "src": src}) + "\n")
+            for e in (0, 1):
+                px, py = pupil(e, hy, hp, t - T0)
+                mx, my = mid(e, t - T0)
+                o.write(json.dumps({"t": t + 0.001 * e, "cam": e, "x": px, "y": py, "a": 20, "b": 18, "angle": 0,
+                                    "glints": [[mx, my - 10], [mx, my + 10]]}) + "\n")
+            n += 1
+    with open(d / "trials.jsonl", "w") as f, open(d / "lessons.jsonl", "w") as ls:
+        for i, (tc, hy, hp, nudged) in enumerate(TRIALS):
+            x, y = 500 - PPD * hy, 400 - PPD * hp
+            f.write(json.dumps({"kind": "trial", "i": i, "u": x / 1000, "v": y / 800, "x": x, "y": y,
+                                "click": {"x": x + 3, "y": y, "t": T0 + tc, "button": "left"},
+                                "truth": {"x": x, "y": y, "from": "target"}}) + "\n")
+            if nudged:
+                ls.write(json.dumps({"time": WALL + tc + 0.02, "kind": "own", "raw": [hy + 0.5, hp], "true": [hy, hp],
+                                     "look_t": T0 + tc - 0.05}) + "\n")
+
+
+class CompareTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if compare is None:
+            raise unittest.SkipTest(f"needs numpy and OpenCV: {NO_DEPS}")
+        cls.tmp = tempfile.TemporaryDirectory()
+        cls.dir = Path(cls.tmp.name) / "run"
+        make_run(cls.dir)
+        cls.bench_run = compare.Run(cls.dir)
+        cls.recs = compare.score(cls.bench_run)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.tmp.cleanup()
+
+    def errs(self, name):
+        return [r["err"][name] for r in self.recs]
+
+    def test_trials_and_truth(self):
+        self.assertEqual(len(self.recs), len(TRIALS))
+        self.assertEqual(self.bench_run.screen, 2)
+        for r, (_, hy, hp, nudged) in zip(self.recs, TRIALS):
+            self.assertAlmostEqual(r["truth"][0], hy, places=6)
+            self.assertAlmostEqual(r["truth"][1], hp, places=6)
+            self.assertEqual(r["nudged"], nudged)
+        # 25 degrees left is the screen's left edge here (x 0)
+        self.assertEqual([r["where"] for r in self.recs], ["edge" if t[1] == 25 else "inside" for t in TRIALS])
+        self.assertAlmostEqual(self.recs[0]["since"], 3 + 500, delta=0.01)
+
+    def test_live(self):
+        for r, (_, hy, hp, _) in zip(self.recs, TRIALS):
+            self.assertAlmostEqual(r["err"]["steamvr"], compare.angle((hy, hp + 1), (hy, hp)), places=4)
+            self.assertAlmostEqual(r["err"]["steamvr-eyes"], r["err"]["steamvr"], places=6)
+            self.assertAlmostEqual(r["err"]["own-live"], compare.angle((hy + 0.5, hp), (hy, hp)), places=4)
+            fused = (hy + 0.35, hp + 0.3)
+            self.assertAlmostEqual(r["err"]["fuse"], compare.angle(fused, (hy, hp)), places=4)
+        # steamvr+clicks learns the 1 degree from the first click on
+        self.assertTrue(all(e < 1e-6 for e in self.errs("steamvr+clicks")[1:]))
+
+    def test_pointer(self):
+        for r, (_, hy, hp, nudged) in zip(self.recs, TRIALS):
+            want = compare.angle((hy + 0.5, hp), (hy, hp)) if nudged else 3 / PPD
+            self.assertAlmostEqual(r["err"]["pointer"], want, delta=0.02)
+            if nudged:
+                self.assertAlmostEqual(r["check"], 3 / PPD, delta=0.02)  # the click vs the lesson's truth
+
+    def test_replays(self):
+        before = [k for k, t in enumerate(TRIALS) if t[0] < SLIP_AT]
+        late = [k for k, t in enumerate(TRIALS) if t[0] > SLIP_AT + 8]
+        slip_deg = SLIP[0] / K
+        for name in ("own-replay", "no-jump", "both-jump", "edge-guard", "every-click", "bridge"):
+            e = self.errs(name)
+            self.assertTrue(all(e[k] < 0.05 for k in before), (name, e))
+        # The slip: the glint jump puts it right some seconds later; without it, it stays 2 degrees
+        # off until a click (there are none after it here); every click puts it right at once.
+        for name in ("own-replay", "both-jump", "edge-guard", "bridge"):
+            e = self.errs(name)
+            self.assertTrue(all(e[k] < 0.1 for k in late), (name, e))
+        nj = self.errs("no-jump")
+        self.assertTrue(all(abs(nj[k] - slip_deg) < 0.15 for k in late), nj)
+        ec = self.errs("every-click")
+        self.assertTrue(all(ec[k] < 0.1 for k in late), ec)
+        k16 = next(k for k, t in enumerate(TRIALS) if t[0] == 16)   # 2 s after: nothing has caught it yet
+        self.assertAlmostEqual(self.errs("own-replay")[k16], slip_deg, delta=0.15)
+        # The live gaze here is made up, 0.5 degrees from the replay's
+        for k in before:
+            self.assertAlmostEqual(self.recs[k]["replay_vs_live"], compare.angle((TRIALS[k][1] + 0.5, TRIALS[k][2]),
+                                                                                 TRIALS[k][1:3]), delta=0.05)
+
+    def test_edge_guard(self):
+        cal = eyes_model.Calibration.load(self.dir / "start" / "eyes-calibration.json")
+        box = compare.calibration_box(self.bench_run, cal)
+        self.assertEqual(box, (-20, 20, -15, 15))
+        clicks = [(T0 + 5, T0 + 4.9, (10.0, 0.0)), (T0 + 11, T0 + 10.9, (25.0, 0.0))]
+        rp = compare.Replay(self.bench_run, self.bench_run.frames(), cal, {}, None, clicks, guard=True, box=box)
+        rp()
+        self.assertEqual((rp.taught, rp.skipped), (1, 1))
+
+    def test_screen_scale(self):
+        """A window 800 x 640 on the 1000 x 800 screen with Qt's pixel ratio 2 (on the Frame: 2752 wide
+        on 3440 pixels): the window's pixels are scaled by the sizes in run.json, not by the ratio."""
+        self.assertIn("no screen sizes", " ".join(self.bench_run.notes))   # this run has none: the ratio (1)
+        d = Path(self.tmp.name) / "scaled"
+        d.mkdir()
+        for f in self.dir.iterdir():
+            if f.is_file():
+                (d / f.name).write_bytes(f.read_bytes())
+        (d / "start").symlink_to(self.dir / "start")
+        info = json.loads((d / "run.json").read_text())
+        info.update(screen={"w": 800, "h": 640, "dpr": 2.0}, screens={"2": [1000, 800]})
+        (d / "run.json").write_text(json.dumps(info))
+        rows = []
+        for line in (d / "trials.jsonl").read_text().splitlines():
+            r = json.loads(line)
+            for k in ("click", "truth"):
+                r[k]["x"], r[k]["y"] = 0.8 * r[k]["x"], 0.8 * r[k]["y"]
+            r["x"], r["y"] = r["truth"]["x"], r["truth"]["y"]
+            rows.append(json.dumps(r))
+        (d / "trials.jsonl").write_text("\n".join(rows) + "\n")
+        run = compare.Run(d)
+        self.assertEqual((run.sx, run.sy), (1.25, 1.25))
+        self.assertEqual(run.notes, [])
+        for r, (_, hy, hp, _) in zip(compare.score(run), TRIALS):
+            self.assertAlmostEqual(r["truth"][0], hy, places=6)
+            self.assertAlmostEqual(r["truth"][1], hp, places=6)
+
+    def test_panel_run(self):
+        """A run on the headset's panel: the truth is the target's direction (no screen), there's
+        no pointer, and the nudges' lessons (none would come from the bench) aren't matched."""
+        d = Path(self.tmp.name) / "panel"
+        d.mkdir()
+        for f in self.dir.iterdir():
+            if f.is_file():
+                (d / f.name).write_bytes(f.read_bytes())
+        (d / "start").symlink_to(self.dir / "start")
+        info = json.loads((d / "run.json").read_text())
+        del info["screen"]
+        info.update(display="panel", look=[0.4, 0.1])
+        (d / "run.json").write_text(json.dumps(info))
+        with open(d / "trials.jsonl", "w") as f:
+            for i, (tc, hy, hp, _) in enumerate(TRIALS):
+                f.write(json.dumps({"kind": "trial", "i": i, "u": 0.0 if hy == 25 else 0.5, "v": 0.5, "yaw": hy, "pitch": hp,
+                                    "click": {"t": T0 + tc, "by": "button"},
+                                    "truth": {"yaw": hy, "pitch": hp, "from": "target"}}) + "\n")
+        run = compare.Run(d)
+        self.assertTrue(run.panel)
+        self.assertEqual(run.notes, [])
+        recs = compare.score(run)
+        self.assertEqual(len(recs), len(TRIALS))
+        for r, (_, hy, hp, _) in zip(recs, TRIALS):
+            self.assertEqual(r["truth"], (hy, hp))
+            self.assertFalse(r["nudged"])
+            self.assertNotIn("pointer", r["err"])
+            self.assertAlmostEqual(r["err"]["steamvr"], compare.angle((hy, hp + 1), (hy, hp)), places=4)
+            self.assertAlmostEqual(r["err"]["own-live"], compare.angle((hy + 0.5, hp), (hy, hp)), places=4)
+        self.assertEqual([r["where"] for r in recs], ["edge" if t[1] == 25 else "inside" for t in TRIALS])
+
+    def test_fusions(self):
+        """Fitted on the other clicks, SteamVR's affine takes out its 1 degree; the fusion is
+        halfway between that and ours (both our eyes are found), ours-else-steam is ours."""
+        recs = compare.score(self.bench_run)
+        compare.cross(recs)
+        before = [k for k, t in enumerate(TRIALS) if t[0] < SLIP_AT]
+        for k, (r, (_, hy, hp, _)) in enumerate(zip(recs, TRIALS)):
+            self.assertLess(r["err"]["steamvr-affine-loo"], 1e-6)
+            self.assertAlmostEqual(r["err"]["fusion-loo"], compare.angle((hy + 0.25, hp), (hy, hp)), places=4)
+            self.assertAlmostEqual(r["err"]["ours-else-steam-loo"], compare.angle((hy + 0.5, hp), (hy, hp)), places=4)
+            self.assertNotIn("steamvr-affine-xrun", r["err"])   # one run: no other runs to fit on
+            if k in before:   # the replay's eyes are right until the slip: so is the fusion with them
+                self.assertLess(r["err"]["fusion-loo:own-replay"], 0.05)
+        # Steady pupil sizes: the size guards refuse nothing
+        for name in ("guard-both", "guard-long", "no-guard"):
+            self.assertEqual(self.errs(name), self.errs("own-replay"), name)
+
+    def test_fusion_from_start(self):
+        """A run started with a fusion (start/gazed-fusion.json), and --fit-fusion's."""
+        with tempfile.TemporaryDirectory() as tmp:
+            d = Path(tmp) / "fused"
+            shutil.copytree(self.dir, d)
+            f = compare.Fusion()
+            f.fit([(hy, hp + 1, hy, hp) for hy in (-20, 0, 20) for hp in (-10, 0, 10)], {"how": "test"})
+            f.save(d / "start" / "gazed-fusion.json")
+            recs = compare.score(compare.Run(d))
+            for r, (_, hy, hp, _) in zip(recs, TRIALS):
+                self.assertLess(r["err"]["steamvr-affine"], 1e-6)
+                self.assertLess(r["err"]["steamvr-affine+clicks"], 1e-6)
+                self.assertAlmostEqual(r["err"]["fusion"], compare.angle((hy + 0.25, hp), (hy, hp)), places=4)
+            out = Path(tmp) / "fusion.json"
+            compare.fit_fusion(recs, out, ["fused"])
+            g = compare.Fusion.load(out)
+            self.assertTrue(g.ready())
+            self.assertEqual((g.info["how"], g.info["dots"]), ("bench", len(TRIALS)))
+            dy, dp = g.steam.get(5.0, 5.0, g.MODE)
+            self.assertAlmostEqual(dy, 0.0, places=3)
+            self.assertAlmostEqual(dp, -1.0, places=2)
+
+    def test_main(self):
+        out = Path(self.tmp.name) / "recs.json"
+        sys.argv = ["compare.py", str(self.dir.parent), "--json", str(out)]
+        compare.main()
+        self.assertEqual(len(json.loads(out.read_text())), len(TRIALS))
+
+
+if __name__ == "__main__":
+    unittest.main()

gaze/build.sh

@@ -13,7 +13,8 @@ g++ -std=c++17 -O2 -Wall -Wno-unused-parameter -Wno-missing-field-initializers -
   -o build/ft-gaze ft-gaze.cpp $OPENVR_LIBS -lpthread
 stb=2c980bb59875b0d32144a71867fbdebb2f77cd20
 [ -f build/include/stb-$stb ] || { curl -fsSL "https://raw.githubusercontent.com/nothings/stb/$stb/stb_truetype.h" -o build/include/stb_truetype.h && touch build/include/stb-$stb; }
-g++ -std=c++17 -O2 -Wall -Wno-unused-parameter -Wno-missing-field-initializers -Ibuild/include $(pkg-config --cflags gbm libdrm) \
+g++ -std=c++17 -O2 -ffunction-sections -fdata-sections -Wl,--gc-sections -Wall -Wno-unused-parameter -Wno-missing-field-initializers -Ibuild/include $(pkg-config --cflags gbm libdrm) \
   -o build/ft-gazepanel panel/ft-gazepanel.cpp $OPENVR_LIBS \
   $(pkg-config --libs gbm libdrm) -lpthread
+strip --strip-unneeded build/ft-gaze build/ft-gazepanel
 echo "built build/ft-gaze build/ft-gazepanel"'

gaze/ft-gaze.cpp

@@ -14,10 +14,12 @@
 // about 1.5 KB, 130 KB a second through podman's relay.
 //
 //   {"t":<sample time, CLOCK_MONOTONIC_RAW s>,"age":<ms old when read>,"n":<sample counter>,
-//    "head":{"yaw":..,"pitch":..,"hit":HIT},          head forward ray (for head nudging)
+//    "head":{"yaw":..,"pitch":..,"q":Q,"hit":HIT},    head forward ray (for head nudging)
 //    "src":{"action":SRC,"mmap1":SRC,"mmap2":SRC,"left":SRC,"right":SRC,"own":SRC},"eye":EYE}
-//   SRC = {"hy":..,"hp":..,"hit":HIT} or {"ok":0}    hy/hp: gaze direction relative to the
-//                                                     head, degrees (yaw +left, pitch +up)
+//   SRC = {"hy":..,"hp":..,"hq":Q,"hit":HIT} or {"ok":0}  hy/hp: gaze direction relative to
+//                                                     the head, degrees (yaw +left, pitch +up);
+//                                                     hq: the head pose it's relative to (the
+//                                                     one at the source's own sample time)
 //         mmap1 adds "open":[l,r] (probably eye openness, 0 in a blink) and "dist" (vergence
 //         distance, m); both mmap sets add "lr", the angle between the eyes (deg), which
 //         jumps when the tracker loses an eye, and "eyes":[[hy,hp],[hy,hp]], each eye's own
@@ -39,6 +41,10 @@
 //         variance (about 2e-5 on a clear view of the eye, rising as the lid or lashes get
 //         in the way), "new" whether it changed since the last sample (it freezes while the
 //         tracker can't see that eye, and in blinks). "eye" is null without the mmap.
+//   Q = [w,x,y,z]   a head pose's rotation as a unit quaternion (standing universe), so a
+//         head-relative direction can be turned into the room and back: the gaze service's
+//         fixation lock holds the gaze still in the room, where a look at a screen stays put
+//         while the head turns (gazecal.GazeLock).
 //   HIT = {"s":<screen>,"x":..,"y":..,"j":[dx/dhy,dy/dhy,dx/dhp,dy/dhp],"dpp":<deg per px>}
 //         or null. x, y are pixels on that screen; j is pixels per degree of head-relative
 //         yaw and pitch there, so a correction in degrees can be turned into pixels and back.
@@ -468,13 +474,38 @@ std::string HitJson(const std::vector<Screen> &screens, const vr::HmdMatrix34_t
     return buf;
 }
 
+// Q: a pose's rotation as a unit quaternion [w,x,y,z] (v' = R v, R the pose's 3x3 part).
+std::string QuatJson(const vr::HmdMatrix34_t &p) {
+    const auto &m = p.m;
+    double w, x, y, z;
+    const double tr = m[0][0] + m[1][1] + m[2][2];
+    if (tr > 0) {
+        const double s = 2 * std::sqrt(tr + 1);  // 4w
+        w = s / 4, x = (m[2][1] - m[1][2]) / s, y = (m[0][2] - m[2][0]) / s, z = (m[1][0] - m[0][1]) / s;
+    } else if (m[0][0] > m[1][1] && m[0][0] > m[2][2]) {
+        const double s = 2 * std::sqrt(1 + m[0][0] - m[1][1] - m[2][2]);  // 4x
+        w = (m[2][1] - m[1][2]) / s, x = s / 4, y = (m[0][1] + m[1][0]) / s, z = (m[0][2] + m[2][0]) / s;
+    } else if (m[1][1] > m[2][2]) {
+        const double s = 2 * std::sqrt(1 + m[1][1] - m[0][0] - m[2][2]);  // 4y
+        w = (m[0][2] - m[2][0]) / s, x = (m[0][1] + m[1][0]) / s, y = s / 4, z = (m[1][2] + m[2][1]) / s;
+    } else {
+        const double s = 2 * std::sqrt(1 + m[2][2] - m[0][0] - m[1][1]);  // 4z
+        w = (m[1][0] - m[0][1]) / s, x = (m[0][2] + m[2][0]) / s, y = (m[1][2] + m[2][1]) / s, z = s / 4;
+    }
+    const double n = std::sqrt(w * w + x * x + y * y + z * z);
+    if (n < 1e-9) return "[1,0,0,0]";
+    char buf[80];
+    std::snprintf(buf, sizeof buf, "[%.6f,%.6f,%.6f,%.6f]", w / n, x / n, y / n, z / n);
+    return buf;
+}
+
 std::string SrcJson(const std::vector<Screen> &screens, const vr::HmdMatrix34_t &head, Vec3 dHead,
                     const std::string &extra = "") {
     double yaw, pitch;
     Angles(Normalize(dHead), yaw, pitch);
     char buf[96];
     std::snprintf(buf, sizeof buf, "{\"hy\":%.4f,\"hp\":%.4f,", yaw, pitch);
-    return buf + extra + "\"hit\":" + HitJson(screens, head, yaw, pitch) + "}";
+    return buf + extra + "\"hq\":" + QuatJson(head) + ",\"hit\":" + HitJson(screens, head, yaw, pitch) + "}";
 }
 
 // Sources (--sources, "sources LIST" on stdin): a bit each.
@@ -798,11 +829,12 @@ int main(int argc, char **argv) {
             const Vec3 f = Rotate(headNow, {0, 0, -1});
             yaw = std::atan2(-f.x, -f.z) * 180 / M_PI;
             pitch = std::asin(std::clamp(f.y, -1.0, 1.0)) * 180 / M_PI;
-            std::printf("{\"t\":%.5f,\"age\":%.1f,\"n\":%u,\"head\":{\"yaw\":%.4f,\"pitch\":%.4f,\"hit\":%s},"
+            std::printf("{\"t\":%.5f,\"age\":%.1f,\"n\":%u,\"head\":{\"yaw\":%.4f,\"pitch\":%.4f,\"q\":%s,\"hit\":%s},"
                         "\"src\":{\"action\":%s,\"mmap1\":%s,\"mmap2\":%s,\"left\":%s,\"right\":%s,\"own\":%s},"
                         "\"eye\":%s}\n",
-                        s.t, (now - s.t) * 1000, s.n, yaw, pitch, HitJson(list, headNow, 0, 0).c_str(), action.c_str(),
-                        m1.c_str(), m2.c_str(), left.c_str(), right.c_str(), own.c_str(), eye.c_str());
+                        s.t, (now - s.t) * 1000, s.n, yaw, pitch, QuatJson(headNow).c_str(),
+                        HitJson(list, headNow, 0, 0).c_str(), action.c_str(), m1.c_str(), m2.c_str(), left.c_str(),
+                        right.c_str(), own.c_str(), eye.c_str());
             if (std::fflush(stdout) != 0) break;  // the reader went away
         }
 

gaze/ft-gazed

@@ -10,9 +10,15 @@ again when the file changes:
                            grabber, and ft-eyes' Python in this checkout), else SteamVR's; it
                            switches when ours is installed or removed.
   GAZE_EYE=auto|left|right the eye bias (gazecal.EyeWeights): auto weights each eye by how far
-                           off it was at your recent nudges; left or right counts that eye twice
-                           as much as the other. Either eye alone carries the gaze when the
-                           other isn't seen.
+                           off it was at your recent nudges (since our tracker's last
+                           calibration: a new one starts them over); left or right counts that
+                           eye twice as much as the other. Either eye alone carries the gaze
+                           when the other isn't seen.
+  GAZE_FUSION=off|on       with our tracker: SteamVR's gaze too (gazecal.Fusion, fusion.json).
+                           SteamVR's two eyes' mean, corrected by an affine fitted at our
+                           calibration's dots, is mixed half and half with ours where both our
+                           eyes are found, and used alone where ours has one or none. off (the
+                           default) until the bench says so (gaze/bench/compare.py's fusion).
 
 Runs ft-gaze (in the dev container), and for every eye tracker sample (90 Hz):
 
@@ -27,8 +33,15 @@ Runs ft-gaze (in the dev container), and for every eye tracker sample (90 Hz):
      ft-gazeprobe (calibration.json, reloaded when the probe changes it) plus what the
      pointer's corrections have taught that eye since (LiveCorrection, saved in
      pointer-lessons.json), then weighted by the eye bias. A lost or closed eye drops out.
-     Our own tracker keeps its own calibration, so its eyes are used as they come;
-  3. smooths it with a fixation lock (the running mean of the current fixation, 1 degree);
+     Our own tracker keeps its own calibration, so its eyes are used as they come, and with
+     GAZE_FUSION=on (and a fusion.json) mixed with SteamVR's (above). When one of its eyes
+     drops out or comes back, gazecal.EyeBridge eases the step between the two eyes' gaze
+     and the one eye's over about 0.3 s, instead of a jump of about a degree. SteamVR's eyes count
+     only when both are open and found, and not while SteamVR tracks one eye only;
+  3. smooths it with a fixation lock (the running mean of the current fixation, 1 degree), on
+     where the gaze points in the room, so a look at a screen stays put while the head turns
+     (gazecal.GazeLock: ft-gaze gives each sample's head pose). With our tracker, an eye whose
+     lids came down stays out for BLINK_SETTLE after they're up again;
   4. sends it to the pointer helper: "gz <yaw> <pitch> <raw yaw> <raw pitch>", head-relative
      degrees (yaw +left, pitch +up). The helper uses it only in gaze mode.
 
@@ -80,7 +93,8 @@ tracker's next click after it starts again re-seats it, as after the headset was
 gaze mode on after a while opens the quick check.
 
 ft-gaze prints only the sources this uses ("sources LIST" on its stdin, see wanted_sources):
-own and mmap1 with our tracker, left, right and mmap1 with SteamVR's eyes, and every source
+own and mmap1 with our tracker (and left, right with the fusion), left, right and mmap1 with
+SteamVR's eyes, and every source
 while a check or the calibration runs or is asked for, since those record them all. So
 SteamVR's gaze action, the one source that calls into vrserver, is read only then (or with
 --source action).
@@ -98,7 +112,7 @@ Control socket: abstract unix datagram "@ft_gazed":
                                    POINTER_GAZE_NUDGE_MAX, so the quick check (gazecheck.py)
   status                           reply: one JSON object
   forget                           drop what the lessons taught (the calibration stays)
-  reload                           read calibration.json and the settings again
+  reload                           read calibration.json, fusion.json and the settings again
   eyes <seconds>                   keep our own tracker running that much longer (at most 120),
                                    whatever GAZE_TRACKER says: the probe's lease. Reply: "ok"
   wake <seconds>                   keep the gaze running (not idle) that much longer (at most 120),
@@ -109,8 +123,8 @@ Control socket: abstract unix datagram "@ft_gazed":
   fivecheck                        the five-dot check now (it otherwise follows a quick check
                                    that didn't fix the tracker)
   calaccept | calquit              from the pointer helper while the panel is up: take this dot
-                                   now (a left click, Meta+J, or a gaze precision or gaze drag
-                                   press) | close it (a right click, Meta+K)
+                                   now (a left click, Enter, a pinch, Meta+J, or a gaze
+                                   precision or gaze drag press) | close it (a right click, Meta+K)
 
 Options: --source action|mmap1|mmap2 (the older one-source path with that source, whatever
 the settings say; set 2 was a little quieter in the probe, but loses the pointer whenever
@@ -134,8 +148,8 @@ from collections import deque
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from gazecal import (DEFAULT_MODEL, EYE_FOUND, EYE_LOST, MODELS, STATE, Correction, EyeFallback,  # noqa: E402
-                     EyeWeights, Fixation, LiveCorrection, SteamEyeLog, TrackedEye)
+from gazecal import (DEFAULT_MODEL, EYE_FOUND, EYE_LOST, FUSION, MODELS, STATE, Correction, EyeBridge,  # noqa: E402
+                     EyeFallback, EyeWeights, Fusion, GazeLock, LiveCorrection, SteamEyeLog, TrackedEye)
 from gazecheck import Checks  # noqa: E402
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "models"))
@@ -172,6 +186,8 @@ IDLE_AFTER = 30.0  # seconds after the gaze was last in use before ft-gaze and o
 WAKE_SETTLE = 15.0  # seconds after waking that the tracker may take to start sending
 WAKE_MAX = 120.0
 KEYBOARD_PITCH = -20.0  # degrees: gaze under this, on no screen, is a look at the keyboard
+BLINK_SETTLE = 0.1  # seconds our tracker's eye stays out after its lids came down: the pupil the
+                    # lid cuts finds wrong for a few frames past SteamVR's openness (2026-10-17)
 
 
 class PointerLessons(LiveCorrection):
@@ -190,9 +206,15 @@ def log(msg):
     print(f"ft-gazed: {msg}", file=sys.stderr, flush=True)
 
 
+def venv_built(python):
+    """Is a build/venv's python there? It's for the container: in a release its link points at the
+    image's Python (/usr/bin/python3.14), which the host doesn't have, so the link itself counts."""
+    return os.path.lexists(python)
+
+
 def own_installed():
     """Is our own tracker installed: its frame grabber, and ft-eyes' Python here?"""
-    return all(p.exists() for p in EYEGRAB) and EYES_PYTHON.exists()
+    return all(p.exists() for p in EYEGRAB) and venv_built(EYES_PYTHON)
 
 
 def read_settings():
@@ -218,6 +240,18 @@ def read_settings():
     return tracker, setting, bias if bias in BIASES else "auto", nudge
 
 
+def read_fusion():
+    """GAZE_FUSION from frametop.conf: True for on (off, the default, for anything else)."""
+    try:
+        for line in CONF.read_text().splitlines():
+            k, _, v = line.split("#", 1)[0].partition("=")
+            if k.strip() == "GAZE_FUSION":
+                return v.strip().lower() == "on"
+    except OSError:
+        pass
+    return False
+
+
 def mtime(path):
     try:
         return path.stat().st_mtime
@@ -226,6 +260,8 @@ def mtime(path):
 
 
 class Service:
+    fusion_on, fusion = False, None   # (set in __init__; here too for tests that build one by parts)
+
     def __init__(self, source, verbose, to=POINTER):
         self.override, self.verbose, self.to = source, verbose, to
         self.source = source or "mmap1"  # the older path's source
@@ -237,14 +273,20 @@ class Service:
         self.cal_mtime = None
         self.lives = {name: PointerLessons() for name in SOURCES}
         self.weights = {t: EyeWeights(self.bias) for t in TRACKERS}
+        self.own_made = None  # when our tracker's calibration was made, as its misses knew it
         self.dirty = False
+        self.fusion_on = read_fusion()
+        self.fusion, self.fusion_mtime = None, None
+        self.load_fusion()
         self.load_calibration()
         self.load_lessons()
         self.steam = SteamEyeLog()
         self.steam.poll()
         self.refit()
-        self.fix = Fixation(radius=1.0)
+        self.fix = GazeLock(radius=1.0)
         self.opens = (deque(maxlen=90), deque(maxlen=90))  # left, right
+        self.low_until = [0.0, 0.0]  # sample time until which each eye counts as closed (BLINK_SETTLE)
+        self.bridge = EyeBridge()    # our tracker: no jump when an eye drops out or comes back
         self.vergence = deque(maxlen=90)
         self.fallback = EyeFallback()
         # SteamVR's tracker following one eye only (gazecal.tracked_eye): 0 left, 1 right, or None.
@@ -253,7 +295,8 @@ class Service:
         self.lost = [False, False]
         self.bad_at = [0.0, 0.0]    # sample time an eye was last lost or closed
         self.counts = {"samples": 0, "sent": 0, "blinks": 0, "one_eye": 0, "one_eye_used": 0, "lost_left": 0,
-                       "lost_right": 0, "looking_down": 0, "dropped": 0, "lessons_taken": 0, "refused": 0}
+                       "lost_right": 0, "looking_down": 0, "dropped": 0, "lessons_taken": 0, "refused": 0,
+                       "fused": 0, "steam_only": 0}
         self.last_sample = 0.0
         self.last = None
         self.last_kind = None
@@ -300,6 +343,11 @@ class Service:
         sides = SIDES if self.one_eye is None else (SIDES[self.one_eye],)
         return "eyes" if all(self.models[e].samples for e in sides) else "source"
 
+    @property
+    def fusing(self):
+        """Our tracker's gaze mixed with SteamVR's (GAZE_FUSION=on, a fitted fusion.json)."""
+        return self.kind == "own" and self.fusion_on and self.fusion is not None and self.fusion.ready()
+
     # --- Settings, calibration and lessons ---
 
     @staticmethod
@@ -336,6 +384,12 @@ class Service:
         self.conf_mtime = mtime(CONF)
         self.check_eyes_model()
         tracker, self.tracker_setting, bias, self.nudge_max = read_settings()
+        fusion_on = read_fusion()
+        if fusion_on != self.fusion_on:
+            self.fusion_on = fusion_on
+            log(f"fusion {'on' if fusion_on else 'off'}" + ("" if not fusion_on or (self.fusion and self.fusion.ready())
+                                                            else f": no fitted {FUSION} yet (our tracker's calibration makes one)"))
+            self.fix.reset()
         if (tracker, bias) != (self.tracker, self.bias):
             auto = ""
             if self.tracker_setting == "auto":
@@ -349,6 +403,14 @@ class Service:
                 w.bias = bias
             self.fix.reset()
 
+    def load_fusion(self):
+        self.fusion_mtime = mtime(FUSION)
+        self.fusion = Fusion.load(FUSION)
+        if self.fusion:
+            log(f"fusion: SteamVR's affine from {self.fusion.info.get('dots', 0)} dots "
+                f"({self.fusion.info.get('how', '?')}, {self.fusion.info.get('made', '?')}), "
+                + ("on" if self.fusion_on else "off (GAZE_FUSION)"))
+
     def load_calibration(self):
         try:
             mt = CALIBRATION.stat().st_mtime
@@ -377,12 +439,14 @@ class Service:
         for t, misses in (d.get("misses") or {}).items():
             if t in self.weights:
                 self.weights[t] = EyeWeights(self.bias, misses)
+        self.own_made = d.get("own_made")
         log(", ".join(f"{n} {len(self.lives[n].samples)}" for n in (self.source,) + SIDES) + " lessons")
 
     def save_lessons(self):
         tmp = LESSONS.with_suffix(".tmp")
         tmp.write_text(json.dumps({"version": 2, "sources": {n: lv.samples for n, lv in self.lives.items() if lv.samples},
-                                   "misses": {t: w.misses for t, w in self.weights.items()}}))
+                                   "misses": {t: w.misses for t, w in self.weights.items()},
+                                   "own_made": self.own_made}))
         tmp.replace(LESSONS)
         self.dirty = False
 
@@ -528,7 +592,7 @@ class Service:
             return "all"
         kind = self.kind
         if kind == "own":
-            return "own,mmap1"
+            return "own,mmap1,left,right" if self.fusing else "own,mmap1"
         if kind == "eyes":
             return "left,right,mmap1"
         return ",".join(dict.fromkeys((self.source, "mmap1", "mmap2")))  # mmap2: each eye, for the fallback
@@ -594,7 +658,7 @@ class Service:
     def start_eyes(self):
         """Our own tracker, in the container, with build/venv's numpy and OpenCV. Like
         ft-gaze, it quits when its stdin closes."""
-        if not EYES_PYTHON.exists():
+        if not venv_built(EYES_PYTHON):
             log(f"ft-eyes isn't built: run {REPO}/gaze/tracker/build.sh")
             self.eyes_restart_at = time.monotonic() + 30
             return
@@ -725,7 +789,7 @@ class Service:
             if "hy" not in src:
                 return
             eyes = [tuple(e) if e else None for e in (src.get("eyes") or [None, None])]
-            hp, hit = src["hp"], src.get("hit")
+            hp, hit, then = src["hp"], src.get("hit"), src.get("hq")
         else:
             per = [s["src"].get(name) or {} for name in SIDES]
             eyes = [(p["hy"], p["hp"]) if "hy" in p else None for p in per]
@@ -733,6 +797,7 @@ class Service:
                 return
             one = self.one_eye
             hp, hit = (eyes[one] if one is not None and eyes[one] else next(e for e in eyes if e))[1], m1.get("hit")
+            then = next((p["hq"] for p in per if "hq" in p), None)
         self.counts["samples"] += 1
         self.last_sample = time.monotonic()
         down = hp < KEYBOARD_PITCH and not hit
@@ -744,11 +809,22 @@ class Service:
             # SteamVR judges only that eye's openness, and a blink closes both: ours still
             # sees the other, so it stays in.
             low[1 - self.one_eye] = low[self.one_eye]
+        if own:
+            for k in (0, 1):
+                if low[k]:
+                    self.low_until[k] = s["t"] + BLINK_SETTLE
+                elif s["t"] < self.low_until[k]:
+                    low[k] = True
         # Our tracker finds the pupils itself; SteamVR's openness still marks the blinks.
         bad = [eyes[k] is None or low[k] or (not own and self.lost[k]) for k in (0, 1)]
         if not own and self.one_eye is not None:
             bad[1 - self.one_eye] = True  # SteamVR ignores that eye
-        if all(bad):
+        steam = None
+        if own and self.fusing and self.one_eye is None:
+            per = [s["src"].get(name) or {} for name in SIDES]
+            steam = self.fusion.steam_gaze(*[(p["hy"], p["hp"]) if "hy" in p and not low[k] and not self.lost[k]
+                                             else None for k, p in enumerate(per)])
+        if all(bad) and steam is None:
             self.counts["blinks"] += 1
             return
         if any(bad):
@@ -762,8 +838,15 @@ class Service:
             for name, e in zip(SIDES, seen):
                 c = self.correction(name, *e) if e else None
                 corrected.append((e[0] + c[0], e[1] + c[1]) if e else None)
-        gy, gp = self.weights["own" if own else "steam"].combine(corrected)
-        fy, fp = self.fix(gy, gp, s["t"], 1.0)
+        g = self.weights["own" if own else "steam"].combine(corrected)
+        if own:
+            g = self.bridge(s["t"], seen, g)
+        if steam is not None:
+            n = sum(e is not None for e in seen)
+            self.counts["fused" if n == 2 else "steam_only"] += 1
+            g = self.fusion.combine(g, n, steam)
+        gy, gp = g
+        fy, fp = self.fix(gy, gp, s["t"], then, (s.get("head") or {}).get("q"))
         self.send(s["t"], fy, fp, fy, fp, seen)
 
     def on_source_sample(self, s):
@@ -796,7 +879,7 @@ class Service:
                     self.counts["dropped"] += 1
                     return
                 hy, hp = eyes[one]
-            fy, fp = self.fix(hy, hp, s["t"], 1.0)
+            fy, fp = self.fix(hy, hp, s["t"], src.get("hq"), (s.get("head") or {}).get("q"))
             cy, cp = self.correction(self.source, fy, fp)
             self.send(s["t"], fy + cy, fp + cp, fy, fp, None)
             return
@@ -830,8 +913,8 @@ class Service:
             if eyes and s["t"] - max(self.bad_at) > SETTLE:
                 for k in (0, 1):
                     self.fallback.update(k, eyes[k][0], eyes[k][1], hy, hp)
-        # The fixation lock works in degrees here (1 degree per "pixel").
-        fy, fp = self.fix(hy, hp, s["t"], 1.0)
+        # The fixation lock works in degrees here, on the gaze's direction in the room.
+        fy, fp = self.fix(hy, hp, s["t"], src.get("hq"), (s.get("head") or {}).get("q"))
         cy, cp = self.correction(self.source, fy, fp)
         self.send(s["t"], fy + cy, fp + cp, fy, fp, None)
 
@@ -893,6 +976,7 @@ class Service:
                     reply = "error bad seconds"
             elif words[:1] == ["reload"]:
                 self.load_settings()
+                self.load_fusion()
                 self.load_calibration()
                 self.refit()
                 reply = "ok"
@@ -916,9 +1000,29 @@ class Service:
                     self.own, self.own_at = json.loads(data), time.monotonic()
                 except ValueError:
                     pass
+                else:
+                    self.note_own_calibration()
             else:
                 log(f"our tracker: {data}")
 
+    def note_own_calibration(self):
+        """Our tracker's status names a calibration other than the one its eye misses were
+        measured on: they start over, and the eyes count alike until each has EyeWeights.MIN
+        again. The misses say how far each eye's old mapping was off, and a new calibration
+        replaces both mappings (it can drop an eye, or be someone else's). Live 2026-10-18 a
+        calibration's own dots fed the right eye misses of the right-only one before it, and the
+        balance after it was that one's. Whatever made the calibration: the panel, the probe."""
+        made = (self.own.get("calibration") or {}).get("made")
+        if not made or made == self.own_made:
+            return
+        w = self.weights["own"]
+        if self.own_made is not None and any(w.misses):
+            log(f"our tracker's calibration from {made}: the eye weights start over "
+                f"(were {', '.join(f'{v:.2f}' for v in w.weights())} from {', '.join(str(len(m)) for m in w.misses)} misses)")
+            self.weights["own"] = EyeWeights(self.bias)
+        self.own_made = made
+        self.dirty = True
+
     def status(self):
         kind = self.kind
         tracker = "own" if kind == "own" else "steam"
@@ -940,7 +1044,13 @@ class Service:
             cal = own.get("calibration") or {}
             st.update(calibration_samples=cal.get("dots", 0), calibration_made=cal.get("made"),
                       lessons=max(len(m) for m in w.misses), own_running=bool(own),
-                      own_reseat=any(e.get("reseat") for e in own.get("eyes", {}).values()))
+                      own_reseat=any(e.get("reseat") for e in own.get("eyes", {}).values()),
+                      size_guard=own.get("size_guard"), size_guard_counts=own.get("size_guard_counts"),
+                      own_mapped=own.get("mapped"))
+        f = self.fusion
+        st["fusion"] = {"setting": "on" if self.fusion_on else "off", "in_use": self.fusing,
+                        "fitted": bool(f and f.ready()), "dots": f.info.get("dots", 0) if f else 0,
+                        "how": f.info.get("how") if f else None, "made": f.info.get("made") if f else None}
         st.update(awake=self.awake, idle=None if self.awake else self.idle_reason())
         st.update(eyes_process=self.eyes_proc is not None, eyegrab=EYES_CAMS.exists(),
                   tracker_setting=self.tracker_setting, own_installed=own_installed())
@@ -959,6 +1069,8 @@ class Service:
         if mtime(CALIBRATION) != self.cal_mtime:
             self.load_calibration()
             self.refit()
+        if mtime(FUSION) != self.fusion_mtime:
+            self.load_fusion()
         if mtime(CONF) != self.conf_mtime or (self.tracker_setting == "auto"
                                               and own_installed() != (self.tracker == "own")):
             self.load_settings()

gaze/gazecal.py

@@ -98,6 +98,99 @@ class Fixation:
         return self.sum[0] / self.count, self.sum[1] / self.count
 
 
+def direction(yaw, pitch):
+    """A head-relative (yaw, pitch) in degrees as a unit vector, as ft-gaze's Direction: -Z
+    forward, positive yaw turns left (about +Y), positive pitch looks up."""
+    y, p = math.radians(yaw), math.radians(pitch)
+    return (-math.sin(y) * math.cos(p), math.sin(p), -math.cos(y) * math.cos(p))
+
+
+def angles(v):
+    """(yaw, pitch) in degrees of a direction, as ft-gaze's Angles."""
+    n = math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) or 1.0
+    return math.degrees(math.atan2(-v[0], -v[2])), math.degrees(math.asin(max(-1.0, min(1.0, v[1] / n))))
+
+
+def rotate(q, v, inverse=False):
+    """v turned by the unit quaternion q = [w, x, y, z] (ft-gaze's "hq" and the head's "q": head
+    space into the room), or back into head space with inverse."""
+    w, x, y, z = q
+    if inverse:
+        x, y, z = -x, -y, -z
+    # v + 2w (u x v) + 2 u x (u x v), u = (x, y, z)
+    cx, cy, cz = y * v[2] - z * v[1], z * v[0] - x * v[2], x * v[1] - y * v[0]
+    dx, dy, dz = y * cz - z * cy, z * cx - x * cz, x * cy - y * cx
+    return (v[0] + 2 * (w * cx + dx), v[1] + 2 * (w * cy + dy), v[2] + 2 * (w * cz + dz))
+
+
+class GazeLock:
+    """The fixation lock (Fixation, above) on where the gaze points in the room.
+
+    A look at something that stays put (a screen) stays put in the room while the head turns:
+    the eyes turn the other way, so the head-relative gaze slides. Locked in head-relative
+    degrees, the pointer rode along with the head until the slide passed the radius, then
+    snapped back, a jump every few hundred milliseconds; replaying two practice captures, during
+    still looks with the head moving 5-30 degrees a second that was 4 jumps over 1 degree a
+    second, and 13 in the one second it turned faster. Locked in the room it's 1 to 2 (2026-10-17).
+
+    Each sample's gaze is turned into the room with the head pose of its own sample time
+    (`then`, ft-gaze's "hq"), locked there, and turned back into the head with the newest pose
+    (`now`, the head's "q"), the closest one to the pose the pointer helper draws it with.
+    Without poses (an older ft-gaze) it's the head-relative lock."""
+
+    def __init__(self, radius=1.0):
+        self.radius = radius
+        self.head = Fixation(radius)
+        self.reset()
+
+    def reset(self):
+        self.head.reset()
+        self.sum = [0.0, 0.0, 0.0]
+        self.count = 0
+        self.outside = []
+        self.last_t = None
+
+    def __call__(self, yaw, pitch, t, then=None, now=None):
+        """The locked gaze, head-relative (yaw, pitch) degrees, for a head-relative sample at t."""
+        if not then or not now:
+            if self.count:
+                self.reset()
+            return self.head(yaw, pitch, t, 1.0)
+        if self.last_t is None and self.head.count:
+            self.head.reset()
+        m = self.lock(rotate(then, direction(yaw, pitch)), t)
+        return angles(rotate(now, m, inverse=True))
+
+    @staticmethod
+    def mean(s):
+        n = math.sqrt(s[0] * s[0] + s[1] * s[1] + s[2] * s[2]) or 1.0
+        return (s[0] / n, s[1] / n, s[2] / n)
+
+    def lock(self, v, t):
+        """Fixation's rules on room directions (unit vectors)."""
+        if self.last_t is not None and (t <= self.last_t or t - self.last_t > 0.5):
+            self.reset()
+        self.last_t = t
+        if self.count:
+            m = self.mean(self.sum)
+            dot = max(-1.0, min(1.0, m[0] * v[0] + m[1] * v[1] + m[2] * v[2]))
+            if math.degrees(math.acos(dot)) > self.radius:
+                self.outside.append(v)
+                if len(self.outside) < 2:
+                    return m  # one stray sample: probably noise
+                self.sum = [sum(p[k] for p in self.outside) for k in range(3)]
+                self.count = len(self.outside)
+                self.outside = []
+                return self.mean(self.sum)
+        self.outside = []
+        if self.count >= 90:  # the last second or so: a slow drift still gets followed
+            self.sum = [s * 89 / 90 for s in self.sum]
+            self.count = 89
+        self.sum = [self.sum[k] + v[k] for k in range(3)]
+        self.count += 1
+        return self.mean(self.sum)
+
+
 MODELS = ["none", "offset", "affine", "affine+grid", "quadratic", "quadratic+grid"]
 DEFAULT_MODEL = "quadratic"
 
@@ -456,6 +549,42 @@ class TrackedEye:
         return self.eye
 
 
+class EyeBridge:
+    """Our tracker's eyes, each with its own calibration, miss in their own ways, so the gaze
+    jumped whenever one eye dropped out or came back (a median 0.3-0.85 degrees in the 10-16
+    edges round): enough to break the fixation lock. While both are seen, this averages each
+    eye's offset from their combined gaze over about LEARN seconds; with one eye, the gaze is
+    that eye plus its offset, fading out over about FADE seconds, since the offset belongs to
+    where the eyes looked then.
+
+    `__call__` takes and gives head-relative degrees (yaw, pitch)."""
+
+    LEARN = 0.3
+    FADE = 0.3
+
+    def __init__(self):
+        self.off = [None, None]   # per eye: (yaw, pitch) from it to the combined gaze
+        self.at = None            # sample time both were last seen
+
+    def __call__(self, t, eyes, combined):
+        """The gaze at sample time t (s), from `combined`, the eye-weighted gaze of `eyes`
+        [(yaw, pitch) or None, (yaw, pitch) or None]."""
+        seen = [k for k in (0, 1) if eyes[k] is not None]
+        if len(seen) == 2:
+            a = 1.0 if self.at is None else 1.0 - math.exp(-max(t - self.at, 0.0) / self.LEARN)
+            for k in seen:
+                d = (combined[0] - eyes[k][0], combined[1] - eyes[k][1])
+                o = self.off[k]
+                self.off[k] = d if o is None else (o[0] + a * (d[0] - o[0]), o[1] + a * (d[1] - o[1]))
+            self.at = t
+            return combined
+        if len(seen) == 1 and self.at is not None and self.off[seen[0]] is not None:
+            f = math.exp(-max(t - self.at, 0.0) / self.FADE)
+            o = self.off[seen[0]]
+            return combined[0] + f * o[0], combined[1] + f * o[1]
+        return combined
+
+
 class EyeFallback:
     """The gaze from one eye, while the tracker has lost the other.
 
@@ -546,7 +675,10 @@ class EyeWeights:
     alike until then. Each miss is measured before its lesson teaches anything, so each is a
     fresh test. On SteamVR's own test (2026-09-29) its calibration dots said the left eye was
     the better one and new spots said the right, so the misses come from lessons, not the fit.
-    An eye that isn't seen (None) drops out, and the other carries the gaze alone."""
+    An eye that isn't seen (None) drops out, and the other carries the gaze alone. Our
+    tracker's start over with each new calibration of it (ft-gazed's note_own_calibration).
+    Not from the new fit's per-eye spread: on 2026-10-18's replays (frame-eyes
+    one_eye_replay.py) spread and equal weights came out the same, 2.29 degrees median."""
 
     LEAN = 2.0
     KEEP = 20
@@ -589,6 +721,126 @@ class EyeWeights:
         return (sum(wk * e[0] for wk, e in zip(w, seen)) / total, sum(wk * e[1] for wk, e in zip(w, seen)) / total)
 
 
+FUSION = STATE / "fusion.json"
+
+
+class Fusion:
+    """Our tracker and SteamVR's together (ft-gazed's GAZE_FUSION=on). On two Gaze Bench runs
+    (2026-10-17, 25 clicks on a head-locked panel out to 37 degrees) the two failed on
+    different looks: ours at its misfinds and with an eye lost, SteamVR with a steady bend
+    across the view. Ours was 2.01 degrees off at the median (6.47 at the 90th percentile),
+    SteamVR's two eyes' mean 2.67 (5.72). An affine correction fitted on the other clicks took
+    SteamVR's to 1.78 (4.26); ours where both its eyes were found, mixed half and half with
+    that, and SteamVR's alone where ours had one eye, to 1.51 (3.10). Fitted on the other run
+    only, 1.41 (4.59) (gaze/bench/compare.py's steamvr-affine-loo, fusion-loo, fusion-xrun).
+
+    So: SteamVR's eyes' mean, corrected by an affine fitted at the calibration's dots (gazecheck
+    records SteamVR's eyes at each of ours, and fits this after ours: fusion.json); then ours
+    mixed in at SHARE where both our eyes are found, SteamVR's alone where we have one, and ours
+    alone where SteamVR has no gaze.
+
+    click() adds an offset on top: the median of what the clicks since the headset went on said
+    was still off (SteamVR starts its eye model over then, and the error may move). ft-gazed
+    doesn't feed it yet: within one wear on those runs it made SteamVR's worse (2.15 to 2.72 at
+    the median, fitted on the other run), and across wears it's untested (compare.py's +clicks)."""
+
+    MODE = "affine"
+    RIDGE = 0.05    # Correction.fit's: on the gain and tilt, so a lopsided set of dots can't bend it far
+    SHARE = 0.5     # our tracker's share when both its eyes are found
+    MIN = 5         # dots for a fit
+    KEEP = 5        # clicks the offset on top comes from
+    STALE = 8.0     # degrees: a click this far off is a look elsewhere, not SteamVR's error
+
+    def __init__(self):
+        self.steam = Correction()
+        self.info = {}
+        self.points = []
+        self.clicks = []   # (wear time, dy, dp): what was still off at a click
+        self.wear = None   # the headset's current wear (SteamEyeLog.worn): clicks from others don't count
+
+    def ready(self):
+        return self.steam.samples >= self.MIN
+
+    def fit(self, points, info=None):
+        """points: (yaw, pitch, true yaw, true pitch), SteamVR's eyes' mean at a dot and the dot."""
+        self.points = [list(map(float, p)) for p in points]
+        self.steam.fit([(hy, hp, ty - hy, tp - hp) for hy, hp, ty, tp in self.points], self.MODE, ridge=self.RIDGE)
+        self.info = dict(info or {}, dots=len(self.points), fitted_at=time.time())
+        self.clicks = []
+
+    def misses(self):
+        """How far off the affine leaves each of the points it was fitted on (degrees)."""
+        out = []
+        for hy, hp, ty, tp in self.points:
+            dy, dp = self.steam.get(hy, hp, self.MODE)
+            out.append(math.hypot(ty - hy - dy, tp - hp - dp))
+        return out
+
+    @staticmethod
+    def mean(left, right):
+        if not left or not right:
+            return None
+        return (left[0] + right[0]) / 2, (left[1] + right[1]) / 2
+
+    def offset(self):
+        keep = [c for c in self.clicks if c[0] == self.wear][-self.KEEP:]
+        if not keep:
+            return 0.0, 0.0
+        return statistics.median(c[1] for c in keep), statistics.median(c[2] for c in keep)
+
+    def steam_gaze(self, left, right, clicks=True):
+        """SteamVR's corrected gaze from its two eyes' readings, or None without both."""
+        m = self.mean(left, right)
+        if m is None or not self.ready():
+            return None
+        dy, dp = self.steam.get(m[0], m[1], self.MODE)
+        oy, op = self.offset() if clicks else (0.0, 0.0)
+        return m[0] + dy + oy, m[1] + dp + op
+
+    def click(self, left, right, thy, thp):
+        """A look at (thy, thp) with SteamVR's eyes there: how far off the correction still was
+        joins the offset on top. Returns that miss (degrees), or None."""
+        g = self.steam_gaze(left, right, clicks=False)
+        if g is None:
+            return None
+        dy, dp = thy - g[0], thp - g[1]
+        miss = math.hypot(dy, dp)
+        if miss <= self.STALE:
+            self.clicks = (self.clicks + [(self.wear, dy, dp)])[-4 * self.KEEP:]
+        return miss
+
+    def combine(self, own, own_eyes, steam, share=None):
+        """own: ours, combined from own_eyes of its eyes (0-2); steam: steam_gaze(). Either may be None."""
+        share = self.SHARE if share is None else share
+        if steam is None:
+            return own
+        if own is None or own_eyes < 2:
+            return steam
+        return share * own[0] + (1 - share) * steam[0], share * own[1] + (1 - share) * steam[1]
+
+    def to_json(self):
+        return {"version": 1, "steam": self.steam.to_json(), "mode": self.MODE, "points": self.points, **self.info}
+
+    def from_json(self, d):
+        self.steam.from_json(d.get("steam") or {})
+        self.points = d.get("points") or []
+        self.info = {k: v for k, v in d.items() if k not in ("version", "steam", "mode", "points")}
+        return self
+
+    @classmethod
+    def load(cls, path=FUSION):
+        try:
+            return cls().from_json(json.loads(Path(path).read_text()))
+        except (OSError, ValueError):
+            return None
+
+    def save(self, path=FUSION):
+        path = Path(path)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(self.to_json(), indent=1))
+        tmp.replace(path)
+
+
 class SteamEyeLog:
     """Follows SteamVR's eye tracking log (read only) for what moves the raw gaze under a
     calibration.

gaze/gazecheck.py

@@ -30,7 +30,7 @@ directions: look at each one.
   fit     the headset fit check (on "fitcheck", Check headset fit on the Gaze page): live, a
           card per eye (tracked or lost, the tracker's signal, how much of the last 10 s it was
           seen) and hints, from the gaze probe's Headset fit (gaze/fitcheck.py), while you
-          adjust the headset. A left click or Meta+J runs its guided check (dots, then looks
+          adjust the headset. A left click, Enter, a pinch or Meta+J runs its guided check (dots, then looks
           down, up, left and right); a right click or Meta+K closes it, as does FIT_TIMEOUT.
           With our tracker installed, its first hint line is the fit coach's (gaze/fitcoach.py):
           where the headset sits, from where ft-eyes sees each pupil and glint (ft-eyes "fit",
@@ -46,7 +46,7 @@ again when the file changes) adds two things, with our tracker installed, its re
           you look at its dot, against your saved fit, and holds the dot meanwhile (at most
           PUTON_READ). If the headset sits more than fitcoach.MOVED_DEG from it, or the IPD
           setting changed, the panel widens (five's size) and says which way to move it, live,
-          until it's back; then the dot is taken as usual. A left click or Meta+J takes it as
+          until it's back; then the dot is taken as usual. A left click, Enter, a pinch or Meta+J takes it as
           it sits, and after PUTON_TIMEOUT it's taken anyway. So the click teaches our tracker
           the headset where you meant it to be, not where it landed.
   slip    while gaze mode is on with our tracker, ft-eyes' glint jump (the headset slipped
@@ -61,15 +61,17 @@ waits until the tracker sends, at most ft-gazed's WAKE_SETTLE; then it opens, or
 The quick check's dot captures itself: from CHECK_SETTLE after it shows (the eyes getting
 there), once the gaze has held within CHECK_SPREAD for CHECK_WINDOW (the probe's max spread and
 capture time). It's the gaze holding still that counts, not where the tracker puts it, so it
-works however far off the tracker is; a left click or Meta+J (the pointer helper's
-"calaccept") takes it now. The full calibration's and five's dots wait for that click: you
+works however far off the tracker is; a left click, Enter, an index pinch with hand tracking,
+or Meta+J (the pointer helper's "calaccept") takes it now. The full calibration's and five's dots wait for that click: you
 click when you're looking at the dot (the user asked for that: a steady gaze isn't always on
 the dot), and the gaze held still up to then is taken (ACCEPT_SPREAD). They wait as long as
 it takes, up to CLICK_IDLE. A dot not taken says why in the panel's note line (reject_reason:
 gazecal.steady_samples' drop counts for SteamVR's tracker, ft-eyes' reply for ours), as does a
 click with nothing taken after ACCEPT_WAIT, and a failed calibration names its most common
 reason there and in the status. A right click or Meta+K ("calquit") closes the panel. A press
-mapped to gaze precision or gaze drag counts as the left click (pointer/helper/calpanel.h). The
+mapped to gaze precision or gaze drag counts as the left click (pointer/helper/calpanel.h);
+Enter is the input relay's ("calkey 1" to the helper while the panel is up), and a pinch the
+helper's own, read from ft-hands whether or not hand interaction is on. The
 pointer hides meanwhile ("calpanel 1", renewed every second; the helper shows it again by itself
 when that stops).
 
@@ -77,8 +79,21 @@ Our tracker's first calibration: before it has one, ft-eyes publishes no gaze (i
 to a gaze only with a calibration), so there's no gaze to hold still. Its calibration runs
 anyway ("blind"): someone in the headset (SteamVR's tracker sees an eye) and ft-eyes answering
 are enough to start it, each dot stands in for the gaze, and a click takes the CHECK_WINDOW up
-to it. ft-eyes then checks that each pupil was seen and held still in that window (calib-point)
-and says why not. Without this, a fresh install could never calibrate our tracker.
+to it. ft-eyes then checks that the pupils were seen and held still in that window (calib-point:
+one eye is enough, and the dot is kept for that eye) and says why not. Without this, a fresh
+install could never calibrate our tracker. A full calibration goes blind the same way whenever
+ours sends no gaze for OWN_GONE: its calibration maps one eye, and that's the one you can't
+show it now. Live 2026-10-18 a calibration with the left eye closed mapped only the right, and
+the next one, with the right eye closed, took no dot: every click waited for a gaze that
+couldn't come ("Waiting: the eye tracker isn't sending a gaze").
+
+Looked away (our tracker's full calibration): where SteamVR saw both eyes at a dot, their mean more
+than LOOKED_AWAY from it, past their usual offset in this calibration (the median over the dots
+it took, from AWAY_OFFSET_MIN of them), and the dot isn't taken: "you looked away from the dot"
+(looked_away; ft-eyes isn't asked). Live 2026-10-18 the palm menu opened the Steam menu
+mid-calibration, and three dots were taken 17-35 degrees from where the user looked. A third
+dot in a row like that is SteamVR being off, not you: it's taken, and the check stops for that
+calibration (AWAY_GIVE_UP).
 
 The service doesn't wait for ft-eyes' answers to calib-point and calib-fit (ask_eyes): the dot
 shows its ring full, and further clicks do nothing until the answer comes, or its deadline
@@ -88,7 +103,10 @@ behind the panel), and an answer over EYES_GONE closed the calibration as the he
 
 What a capture teaches:
   our tracker   quick and five: a click ("click T YAW PITCH", like a pointer lesson); full:
-                calib-start, a calib-point for each dot, calib-fit (its calibration)
+                calib-start, a calib-point for each dot, calib-fit (its calibration); and
+                SteamVR's two eyes at each dot ft-eyes took, where SteamVR saw both: after the
+                fit, SteamVR's affine for ft-gazed's fusion (gazecal.Fusion) is fitted on
+                them and saved to fusion.json (kept as it was with under Fusion.MIN of them)
   SteamVR's     quick and five: a lesson for each eye, like the pointer's; full: each source's
                 calibration fitted from the dots (gazecal.Correction, the probe's way), saved
                 to calibration.json, and the lessons start over on top of it
@@ -110,7 +128,7 @@ from pathlib import Path
 
 import fitcoach
 from fitcheck import MIN_REGION, FitCheck, wrap
-from gazecal import DEFAULT_MODEL, EYE_LOST, STATE, steady_samples
+from gazecal import DEFAULT_MODEL, EYE_LOST, FUSION, STATE, Fusion, steady_samples
 
 REPO = Path(__file__).resolve().parents[1]
 PANEL_PROG = REPO / "gaze" / "build" / "ft-gazepanel"
@@ -128,6 +146,11 @@ CHECK_WINDOW = 0.6
 CHECK_SPREAD = 1.0     # degrees
 ACCEPT_SPREAD = 2.5    # degrees: a capture asked for (calaccept) takes this much
 CLICK_IDLE = 120.0     # seconds a dot of five or full waits for its click; then the check closes
+LOOKED_AWAY = 15.0     # degrees: SteamVR's eyes this far from a full calibration's dot (our tracker's), past
+                       # their usual offset in it, and the dot isn't taken: you looked away
+AWAY_OFFSET_MIN = 3    # dots taken with SteamVR's eyes before their median offset counts
+AWAY_GIVE_UP = 2       # dots in a row turned down as looked away: at a third, SteamVR is off, not you;
+                       # that one's taken and the check stops
 QUICK_TIMEOUT = 6.0
 QUICK_COOLDOWN = 120.0
 DON_DELAY = 3.0        # seconds of eyes after AWAY_MIN without: the headset went on
@@ -188,6 +211,7 @@ STEAM_REASONS = {"lost_left": ("left eye lost", "SteamVR lost your left eye"),
                  "vergence": ("eyes disagreed", "SteamVR's two eyes disagreed")}
 FIT_HINT = "check the headset fit"
 ACCEPT_WAIT = 1.5      # seconds after a click with no capture before the panel says what it waits for
+OWN_GONE = 0.5         # seconds without our tracker's gaze before a full calibration goes blind (see the top)
 
 
 def reject_reason(reply, why):
@@ -199,13 +223,18 @@ def reject_reason(reply, why):
         key = max(why, key=why.get)
         return *STEAM_REASONS[key], key.startswith("lost")
     words = reply.removeprefix("fail ").split()
-    # ft-eyes: "fail the left eye was seen in only 3 frames", "fail the left eye moved (4.2 px)"
+    # ft-eyes: "fail the left eye moved (4.2 px)", "fail neither eye was seen enough (right 3
+    # frames, left 0 frames)"; one eye seen is enough for a dot (and its answer is "ok ...")
+    if reply.startswith("fail neither eye was seen"):
+        return "eyes not seen", "our tracker saw neither eye well enough", True
     if len(words) >= 3 and words[0] == "the" and words[2] == "eye":
         eye = words[1]
         if "seen" in words:
             return f"{eye} eye not seen", f"our tracker saw your {eye} eye in only {words[-2]} frames", True
         if "moved" in words:
             return f"{eye} eye moved", f"your {eye} eye moved while you looked", False
+    if reply.startswith("looked away"):  # gazecheck's own (looked_away): SteamVR's eyes were elsewhere
+        return "looked away", "you looked away from the dot (by SteamVR's eyes)", False
     if not reply:
         return "no answer", "our tracker didn't answer", False
     if reply.startswith("our tracker isn't running"):
@@ -581,7 +610,8 @@ class Checks:
         self.check = {"kind": kind, "reason": reason, "own": own, "dots": check_dots(kind, own), "i": 0,
                       "started": now, "shown": now, "run": [], "accept": False, "done_at": None, "tries": 0,
                       "skipped": 0, "captured": 0, "points": {}, "reasons": {}, "fit_reasons": set(), "note": "",
-                      "blind": blind}
+                      "blind": blind, "fusion": [], "away_dots": [], "away_off": False, "steam_offsets": [],
+                      "own_at": now, "run_blind": blind, "went_blind": False}
         log(f"{kind} check: {reason}" + (" (our tracker's first: no gaze yet, so each click takes the look "
                                          "up to it)" if blind else ""))
         self.note_until = None   # the check's panel replaces the slip note
@@ -619,7 +649,7 @@ class Checks:
         self.to_helper("calpanel 1")
         self.to_panel("show fit")
         self.to_panel("title Headset fit: adjust the headset while you watch")
-        self.to_panel("text Left click or Meta+J: guided check · Right click or Meta+K: done")
+        self.to_panel("text Left click, Enter or pinch: guided check · Right click or Meta+K: done")
         return "ok"
 
     def new_coach(self):
@@ -849,7 +879,7 @@ class Checks:
                 drawn[k] = cmd
                 self.to_panel(cmd)
         if fit.have_eye_data and fit.samples < 3 * MIN_REGION:
-            hints = ["Look around slowly: up, down, left and right. Or left click (Meta+J) for a guided check."]
+            hints = ["Look around slowly: up, down, left and right. Or left click, press Enter or pinch for a guided check."]
         else:
             hints = fit.hints()
         hints = self.coach_lines() + hints
@@ -865,9 +895,9 @@ class Checks:
         if c["kind"] == "full":
             self.to_panel(f"bg {ROUND_BG[rnd]}")
             self.to_panel(f"title Gaze calibration: {ROUND_NAMES[rnd]} round, {rnd + 1} of 3")
-            self.to_panel("text Look at the dot and click (left click or Meta+J). Right click or Meta+K: stop")
+            self.to_panel("text Look at the dot, then left click, press Enter or pinch. Right click or Meta+K: stop")
         elif c["kind"] == "five":
-            self.to_panel(f"text Look at the dot and click ({c['i'] + 1} of {len(c['dots'])})")
+            self.to_panel(f"text Look at the dot, then click, Enter or pinch ({c['i'] + 1} of {len(c['dots'])})")
         else:
             self.to_panel("text Look at the dot")
         self.to_panel(f"dot {yaw:.3f} {pitch:.3f} look")
@@ -896,10 +926,21 @@ class Checks:
             return  # (asking: ft-eyes has this dot's look, or the fit)
         if c["own"]:
             src = s["src"].get("own") or {}
-            if c["blind"]:
-                # Our tracker's first calibration: no gaze yet, so the dot stands in for it (the
-                # gaze can't seem to move) and a click takes the look up to it. ft-eyes checks
-                # the pupils held still (see the top).
+            if "hy" in src:
+                c["own_at"] = self.sample_at
+            # Our tracker's first calibration: no gaze yet, so the dot stands in for it (the
+            # gaze can't seem to move) and a click takes the look up to it. ft-eyes checks
+            # the pupils held still (see the top). A full calibration does the same while ours
+            # sends no gaze: its calibration maps only the eye you've closed.
+            blind = c["blind"] or (c["kind"] == "full" and self.sample_at - c["own_at"] > OWN_GONE)
+            if blind != c["run_blind"]:
+                c["run"].clear()  # the dot standing in and our gaze aren't one look
+                c["run_blind"] = blind
+                if blind and not c["went_blind"]:
+                    c["went_blind"] = True
+                    log(f"{c['kind']} check: our tracker sends no gaze (its calibration's eyes aren't seen): "
+                        "each click takes the look up to it")
+            if blind:
                 yaw, pitch, _ = c["dots"][c["i"]]
                 src = {"hy": yaw, "hp": pitch}
         else:
@@ -960,6 +1001,21 @@ class Checks:
             miss = [math.hypot(yaw - e[0], pitch - e[1]) if e else None for e in eyes]
             rec.update(eyes=eyes, miss=miss)
             t0, t1 = samples[0]["t"], samples[-1]["t"]
+            if c["kind"] == "full" and svc.one_eye is None:
+                # SteamVR's eyes at the dot too, for the fusion (finish): each one's median over
+                # the steady samples, as its own calibration takes them.
+                steady = steady_samples(samples)
+                lr = []
+                for name in ("left", "right"):
+                    pts = [(smp["src"][name]["hy"], smp["src"][name]["hp"]) for smp in steady
+                           if "hy" in (smp["src"].get(name) or {})]
+                    lr.append((statistics.median(p[0] for p in pts), statistics.median(p[1] for p in pts))
+                              if len(pts) >= 15 else None)
+                if all(lr):
+                    rec["steam"] = lr
+                    if self.looked_away(rec):
+                        self.captured(rec, False)
+                        return
             if c["kind"] == "full":
                 # ft-eyes checks the pupils held still: its answer takes the dot or not (point_done).
                 # The ring shows it full meanwhile, so the click is seen to have landed.
@@ -1023,12 +1079,41 @@ class Checks:
                 svc.dirty = True
         self.captured(rec, ok)
 
+    def looked_away(self, rec):
+        """A full calibration's dot for our tracker, where SteamVR saw both eyes: whether they say
+        you looked away (LOOKED_AWAY past their usual offset in this calibration). The dot isn't
+        taken then (ft-eyes isn't asked): one taken there teaches our tracker the wrong place.
+        Past AWAY_GIVE_UP dots in a row turned down, it's SteamVR that's off: the check stops."""
+        c = self.check
+        (my, mp), (ty, tp) = Fusion.mean(*rec["steam"]), rec["true"]
+        dy, dp = ty - my, tp - mp
+        offs = c["steam_offsets"]
+        if len(offs) >= AWAY_OFFSET_MIN:
+            dy -= statistics.median(o[0] for o in offs)
+            dp -= statistics.median(o[1] for o in offs)
+        rec["away"] = round(math.hypot(dy, dp), 2)
+        away = rec["away"] > LOOKED_AWAY and not c["away_off"]
+        if away and c["i"] not in c["away_dots"] and len(c["away_dots"]) >= AWAY_GIVE_UP:
+            c["away_off"], away = True, False
+            log(f"full check: SteamVR's eyes {rec['away']:.0f} deg off at {AWAY_GIVE_UP + 1} dots in a row: "
+                "taken as SteamVR being off, the looked-away check is off for this calibration")
+        if not away:
+            c["away_dots"] = []
+            offs.append((ty - my, tp - mp))
+            return False
+        if c["i"] not in c["away_dots"]:
+            c["away_dots"].append(c["i"])
+        rec["reply"] = f"looked away ({rec['away']:.0f} deg by SteamVR)"
+        return True
+
     def point_done(self, rec, miss, reply):
         """ft-eyes' answer to a full calibration dot's calib-point ("" without one)."""
         rec["reply"] = reply
         ok = reply.startswith("ok")
         if ok:
             self.svc.weights["own"].add(miss)
+            if rec.get("steam"):
+                self.check["fusion"].append((*Fusion.mean(*rec["steam"]), *rec["true"]))
         self.captured(rec, ok)
 
     def captured(self, rec, ok):
@@ -1115,6 +1200,8 @@ class Checks:
         if c["own"]:
             def fitted(reply):
                 log(f"calibration ({c['captured']} of {n} dots): our tracker says {reply or 'nothing'}")
+                if reply.startswith("ok"):
+                    self.fit_fusion(c["fusion"])
                 self.close()
 
             self.to_panel("text Saving the calibration")
@@ -1139,6 +1226,22 @@ class Checks:
             log(f"calibration ({c['captured']} of {n} dots): {mode}, saved")
         self.close()
 
+    def fit_fusion(self, pts):
+        """SteamVR's affine for ft-gazed's fusion, from its eyes at the dots ours took."""
+        if len(pts) < Fusion.MIN:
+            log(f"fusion: SteamVR saw both eyes at only {len(pts)} of the dots; {FUSION.name} stays as it was")
+            return
+        f = Fusion()
+        f.fit(pts, {"how": "calibration", "made": time.strftime("%Y-%m-%d %H:%M:%S"), "wear": self.svc.steam.worn()})
+        try:
+            f.save(FUSION)
+        except OSError as e:
+            log(f"fusion: couldn't save {FUSION}: {e}")
+            return
+        self.svc.load_fusion()
+        log(f"fusion: SteamVR's affine from {len(pts)} dots, {statistics.median(f.misses()):.2f} deg left at the "
+            "median, saved")
+
     def close(self, why=None):
         if not self.check:
             return

gaze/panel/ft-gazepanel.cpp

@@ -644,8 +644,12 @@ struct PoseLog {
             next += kPosePeriodNs;
             const int64_t now = RawNs();
             if (next < now - kPosePeriodNs) next = now;
-            const timespec ts{time_t(next / 1'000'000'000), long(next % 1'000'000'000)};
-            clock_nanosleep(CLOCK_MONOTONIC_RAW, TIMER_ABSTIME, &ts, nullptr);
+            // Linux has no absolute sleeps on CLOCK_MONOTONIC_RAW (EINVAL at once: the loop spun at
+            // ~160k poses/s), so sleep the gap relative on CLOCK_MONOTONIC.
+            if (const int64_t wait = next - now; wait > 0) {
+                const timespec ts{time_t(wait / 1'000'000'000), long(wait % 1'000'000'000)};
+                clock_nanosleep(CLOCK_MONOTONIC, 0, &ts, nullptr);
+            }
         }
     }
 };

gaze/rec/CONSENT.md

@@ -50,7 +50,7 @@ The recorder doesn't record sound, the headset's outward cameras, your name, you
 
 - Recordings stay on your headset, in `~/.local/share/frametop/eyes/contrib`. Nothing is uploaded automatically.
 - Before you share anything, you can look through every recording in the Review page. You can delete any stretch of a take, a whole take or a whole round. Export leaves out what you deleted.
-- You upload the export yourself, from the Upload page. That opens a pull request on the dataset. The maintainer checks it before it becomes part of the dataset, and may decline it. Until it's merged, you can close the pull request yourself.
+- You upload the export yourself: from the Upload page, or with Export and upload, which sends it once it's exported. That opens a pull request on the dataset. The maintainer checks it before it becomes part of the dataset, and may decline it. Until it's merged, you can close the pull request yourself.
 
 ## Where it goes, and who can read it
 

gaze/rec/DESIGN.md

@@ -93,7 +93,7 @@ The launch bounties:
 |---|---|---|
 | View edges | Dots at the panel's edges and corners: 30 degrees to the sides, 23 up and down, about 35 in the corners (the rec panel is 64 degrees across; every round's dots are checked against it) | Eyes turned far: the lid, the glints lost, the pupil foreshortened |
 | Blinks and lids | Blink on a beep, close both eyes on a beep and open them on the next (sounds.py: the eyes are shut, so words can't cue them), wink each eye, squint, eyes wide, half-closed, looking down with lids lowered | Closed and partly closed eyes; one eye missing |
-| Headset slips | Nudge the headset up, down, left, right, tilt it; then take it off and put it back on; dots after each | Headset shifting on the face: the put-on check's data |
+| Headset slips | Nudge the headset up, down, left, right, tilt it, tip its front down, pull it off the face, on a beep, holding it through dots, letting go on a low beep; then take it off and put it back on; dots after each | Headset shifting on the face: the put-on check's data |
 | Glasses | A 5x5 grid and the edges with glasses or inserts on (offered when the checklist says so) | Lens reflections, the glasses' frame in view |
 | Jumps and pursuit | A dot jumping between random spots (0.5 to 1.5 s each), then moving on circles, lines and a figure eight at two speeds | Saccades, overshoot, smooth pursuit, the tracker's lag |
 | Depth | Dots at 0.5 m, 1.5 m and 5 m in turn (the panel's distance changes) | Vergence; the eyes' angle with distance |
@@ -157,7 +157,7 @@ The export recompresses nothing (the chunks are zstd already), drops deleted ran
 
 ## Shared with the hand recorder
 
-Much of `hands/rec/` isn't about hands: the headset button reader, profile and consent, take bookkeeping (deleted ranges, redo, parts, clock samples), the Hugging Face login and upload, validate's manifest and checksum checks, and most of the window. These live in `recorder/` at the top of the tree, with the bounty board, and both recorders use them: `common.py`, `units.py`, `button.py`, `bounties.py`, `files.py` (ranges, checksums, sizes), `checks.py` (validate's report, SHA256SUMS, typed manifest lookups), `hub.py` (login, errors, upload records, the pull request flow), `age.py` (the export's encryption) and `window.py` (the window backend's shared half: consent, disk, session controls, export, login and upload; each recorder's `Backend` subclasses it). The hand recorder's modules keep their names on top of them, and its tests pass.
+Much of `hands/rec/` isn't about hands: the headset button reader, profile and consent, take bookkeeping (deleted ranges, redo, parts, clock samples), the Hugging Face login and upload, validate's manifest and checksum checks, and most of the window. These live in `recorder/` at the top of the tree, with the bounty board, and both recorders use them: `common.py`, `units.py`, `button.py`, `bounties.py`, `files.py` (ranges, checksums, sizes), `checks.py` (validate's report, SHA256SUMS, typed manifest lookups), `hub.py` (login, errors, upload records, the pull request flow), `age.py` (the export's encryption) and `window.py` (the window backend's shared half: consent, disk, session controls, export, login and upload; each recorder's `Backend` subclasses it). The hand recorder's modules keep their names on top of them, and its tests pass. The export queue, with Export and upload sending a round by itself once it's exported (2026-10-17), is `window.py`'s too, so both windows have it: `hands/rec/DESIGN.md` (Upload) has how it works.
 
 Uploads: `gaze/rec/hub.py` sends nothing to the real dataset until `CONSENT.md` and `UPLOAD.md` exist and aren't drafts. `FT_EYEREC_ALLOW_UPLOAD=1` opens rehearsals, and only to another dataset (`FT_EYEREC_DATASET`). Rehearsed 2026-10-14 against the private `DeeJanuz/frametop-eyes-test` with a round of random bytes: uploaded, downloaded, checked, and decrypted with both keys by age 1.1.1 on the 7i.
 

gaze/rec/ft_eyerec.py

@@ -337,6 +337,9 @@ class Backend(RecorderBackend):
     def _upload_values(self, session, path):
         return {"ROUND": session}
 
+    def _session_label(self, session):
+        return round_label(session)
+
     @Property(str, constant=True)
     def toolVersion(self):
         return takes.tool_version()
@@ -739,7 +742,7 @@ class Backend(RecorderBackend):
 
     @Slot(str)
     def deleteSession(self, rnd):
-        if self._active_guard(rnd):
+        if self._active_guard(rnd) or self._busy_guard(rnd):
             return
         try:
             self.store.delete_round(rnd)

gaze/rec/main.qml

@@ -96,6 +96,24 @@ Kirigami.ApplicationWindow {
         return n + " " + word + (n === 1 ? "" : "s")
     }
 
+    // A round's label, from its id (the Export page's queue).
+    function sessionLabel(id) {
+        for (const s of backend.sessions)
+            if (s.id === id)
+                return s.label
+        return id
+    }
+    // The round's export can upload by itself once done: logged in, and its dataset takes
+    // contributions (or a dry run).
+    function canUploadAfter(id) {
+        return backend.canUploadAfter && (backend.hubDryRun || backend.uploadAllowedFor(id))
+    }
+    // Waiting to export, or exporting now.
+    function exportPending(id) {
+        return backend.exportSessionId === id && backend.exporting
+               || backend.exportQueue.some(q => q.session === id)
+    }
+
     function show(page) {
         pageStack.clear()
         pageStack.push(page)
@@ -171,9 +189,11 @@ Kirigami.ApplicationWindow {
             close.accepted = false
             confirm.ask("Stop the round?", "A round is recording. Closing stops it; what's recorded so far is kept.",
                         () => { root.quitting = true; Qt.quit() })
-        } else if (backend.uploading && !quitting) {
+        } else if ((backend.uploading || backend.exporting || backend.uploadQueue.length > 0) && !quitting) {
             close.accepted = false
-            confirm.ask("Cancel the upload?", "An upload is running. Closing cancels it; you can start it again later.",
+            confirm.ask("Cancel the exports and uploads?",
+                        "An export or upload is running or waiting (the Export page lists them). Closing cancels "
+                        + "them all; an export cancelled keeps nothing. You can start them again later.",
                         () => { root.quitting = true; Qt.quit() })
         }
     }
@@ -887,9 +907,10 @@ Kirigami.ApplicationWindow {
                     opacity: 0.7
                     text: "The dots and instructions appear in the headset. "
                           + (sessionView.st.button ? "The button on the right side of the headset: next, pause or "
-                             + "resume; twice: record the last step again; hold: stop. " : "")
-                          + "While this window has focus: Space: next · P: pause or resume · R: record the last step "
-                          + "again · S: skip the rest of the take · Esc: stop. Stopping keeps what's recorded so far."
+                             + "resume; twice: redo; hold: stop. " : "")
+                          + "While this window has focus: Space: next · P: pause or resume · R: redo · S: skip the "
+                          + "rest of the take · Esc: stop. Redo during a step starts it again; before a step "
+                          + "starts, it goes back to the one before. Stopping keeps what's recorded so far."
                 }
                 RowLayout {
                     // No keyboard focus on the buttons, so Space always reaches the shortcut.
@@ -911,7 +932,8 @@ Kirigami.ApplicationWindow {
                         visible: backend.sessionActive
                         enabled: !!sessionView.st.can_redo
                         focusPolicy: Qt.NoFocus
-                        text: "Redo step"
+                        // At a ready screen it goes back to the step before; else this one again.
+                        text: sessionView.state === "ready" ? "Back to the last step" : "Redo this step"
                         icon.name: "edit-undo"
                         onClicked: backend.redo()
                     }
@@ -1310,6 +1332,12 @@ Kirigami.ApplicationWindow {
                         return s
                 return null
             }
+            // The chosen round is exporting, or waiting to.
+            readonly property bool pending: chosen !== null && root.exportPending(chosen.id)
+            readonly property bool canExport: chosen !== null && !pending && backend.exportProblem === "" && !chosen.active
+                                              && !(backend.uploading && backend.upload.session === chosen.id)
+                                              && backend.uploadQueue.indexOf(chosen.id) < 0
+            Component.onCompleted: if (backend.login.state === "unknown") backend.checkLogin()
 
             Timer {
                 interval: 5000
@@ -1329,6 +1357,15 @@ Kirigami.ApplicationWindow {
                     text: "Exporting keeps the processor busy for a minute or so, so VR may stutter a little until "
                           + "it's done. You can keep using the headset meanwhile."
                 }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.uploadAfter.length + backend.uploadQueue.length > 0
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Positive
+                    text: "You can take the headset off and leave it plugged in: it stays awake until the "
+                          + "exports and uploads below are done, and they show here how they went. Keep this "
+                          + "window open: closing it cancels them."
+                }
                 Kirigami.InlineMessage {
                     Layout.fillWidth: true
                     visible: backend.exportProblem !== ""
@@ -1345,7 +1382,6 @@ Kirigami.ApplicationWindow {
                     model: backend.sessions
                     textRole: "label"
                     valueRole: "id"
-                    enabled: !backend.exporting
                     Component.onCompleted: {
                         const i = indexOfValue(root.chosenSession)
                         currentIndex = i >= 0 ? i : (count > 0 ? 0 : -1)
@@ -1361,32 +1397,73 @@ Kirigami.ApplicationWindow {
                     Kirigami.FormData.label: "Export:"
                     visible: exportView.chosen !== null
                     text: !exportView.chosen ? ""
+                          : exportView.pending ? (backend.exportSessionId === exportView.chosen.id && backend.exporting
+                                                  ? "exporting now" : "waiting its turn, below")
                           : exportView.chosen.export_stale ? "changed since it was exported: export it again"
                           : exportView.chosen.exported ? "ready, " + exportView.chosen.exportText : "not exported yet"
                 }
+                // Exports run one at a time; one asked for meanwhile waits its turn. "Export and
+                // upload" sends it by itself once it's exported.
                 RowLayout {
                     Controls.Button {
-                        text: backend.exporting ? "Exporting…"
-                              : exportView.chosen && exportView.chosen.exported ? "Export again" : "Export"
+                        text: exportView.chosen && exportView.chosen.exported ? "Export again" : "Export"
                         icon.name: "document-export"
-                        enabled: exportView.chosen !== null && !backend.exporting && backend.exportProblem === ""
-                                 && !exportView.chosen.active
-                        onClicked: backend.exportSession(exportView.chosen.id, false)
+                        enabled: exportView.canExport
+                        onClicked: backend.queueExport(exportView.chosen.id, false, false)
                     }
+                    Controls.Button {
+                        text: "Export and upload"
+                        icon.name: "cloud-upload"
+                        enabled: exportView.canExport && root.canUploadAfter(exportView.chosen.id)
+                        onClicked: backend.queueExport(exportView.chosen.id, false, true)
+                    }
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    visible: exportView.chosen !== null && !backend.hubDryRun
+                             && (!backend.canUploadAfter || !backend.uploadAllowedFor(exportView.chosen.id))
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: !backend.canUploadAfter ? "To upload by itself once exported, log in on the Upload page first."
+                          : "Contributions aren't open yet, so it can't upload by itself."
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    visible: backend.exporting && exportView.chosen !== null && !exportView.pending
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "Another export is running: this one waits its turn."
+                }
+
+                // The running export
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Exporting now"
+                    visible: backend.exporting
+                }
+                RowLayout {
+                    Kirigami.FormData.label: "Round:"
+                    visible: backend.exporting
+                    Controls.Label { text: root.sessionLabel(backend.exportSessionId) }
                     // Shows the moment Export is pressed: the first progress can take a few seconds.
                     Controls.BusyIndicator {
-                        visible: backend.exporting
-                        running: visible
+                        running: backend.exporting
                         implicitWidth: Kirigami.Units.gridUnit * 1.5
                         implicitHeight: implicitWidth
                     }
                     Controls.Button {
-                        visible: backend.exporting
                         text: "Cancel"
                         icon.name: "dialog-cancel"
                         onClicked: backend.cancelExport()
                     }
                 }
+                Controls.CheckBox {
+                    visible: backend.exporting
+                    text: "Upload it once exported"
+                    checked: backend.uploadAfter.indexOf(backend.exportSessionId) >= 0
+                    enabled: checked || root.canUploadAfter(backend.exportSessionId)
+                    onToggled: backend.setUploadAfter(backend.exportSessionId, checked)
+                }
                 // Drawn here: the desktop style's ProgressBar paints nothing without a QApplication.
                 Rectangle {
                     Kirigami.FormData.label: "Progress:"
@@ -1409,7 +1486,7 @@ Kirigami.ApplicationWindow {
                     text: backend.exportText
                 }
                 RowLayout {
-                    visible: exportView.chosen !== null && exportView.chosen.exported && !backend.exporting
+                    visible: exportView.chosen !== null && exportView.chosen.exported && !exportView.pending
                     Controls.Button {
                         text: "Upload"
                         icon.name: "go-next"
@@ -1418,6 +1495,8 @@ Kirigami.ApplicationWindow {
                     Controls.Button {
                         text: "Delete export"
                         icon.name: "edit-delete"
+                        enabled: !(backend.uploading && backend.upload.session === exportView.chosen.id)
+                                 && backend.uploadQueue.indexOf(exportView.chosen.id) < 0
                         onClicked: {
                             const rid = exportView.chosen.id
                             confirm.ask("Delete this export?", "The export is deleted; the round's recordings stay.",
@@ -1425,6 +1504,107 @@ Kirigami.ApplicationWindow {
                         }
                     }
                 }
+
+                // Waiting: exports, then uploads
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Waiting to export"
+                    visible: backend.exportQueue.length > 0
+                }
+                Repeater {
+                    model: backend.exportQueue
+                    delegate: RowLayout {
+                        required property var modelData
+                        required property int index
+                        Kirigami.FormData.label: (index + 1) + "."
+                        Controls.Label { text: root.sessionLabel(modelData.session) }
+                        Controls.CheckBox {
+                            text: "then upload"
+                            checked: modelData.upload
+                            enabled: checked || root.canUploadAfter(modelData.session)
+                            onToggled: backend.setUploadAfter(modelData.session, checked)
+                        }
+                        Controls.ToolButton {
+                            icon.name: "list-remove"
+                            text: "Remove"
+                            display: Controls.AbstractButton.IconOnly
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: backend.unqueueExport(modelData.session)
+                        }
+                    }
+                }
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Uploading"
+                    visible: backend.uploading || backend.uploadQueue.length > 0
+                }
+                RowLayout {
+                    Kirigami.FormData.label: "Now:"
+                    visible: backend.uploading
+                    Controls.Label {
+                        text: root.sessionLabel(backend.upload.session || "") + (backend.upload.text ? ": " + backend.upload.text : "")
+                    }
+                    Controls.Button {
+                        text: "Show"
+                        icon.name: "go-next"
+                        flat: true
+                        onClicked: { root.chosenSession = backend.upload.session; root.show(uploadPage) }
+                    }
+                }
+                Repeater {
+                    model: backend.uploadQueue
+                    delegate: RowLayout {
+                        required property var modelData
+                        required property int index
+                        Kirigami.FormData.label: "Then:"
+                        Controls.Label { text: root.sessionLabel(modelData) }
+                        Controls.ToolButton {
+                            icon.name: "list-remove"
+                            text: "Don't upload it"
+                            display: Controls.AbstractButton.IconOnly
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: backend.unqueueUpload(modelData)
+                        }
+                    }
+                }
+
+                // How they went, for whoever comes back to the headset
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Done"
+                    visible: backend.doneLog.length > 0
+                }
+                Repeater {
+                    model: backend.doneLog
+                    delegate: RowLayout {
+                        required property var modelData
+                        Kirigami.Icon {
+                            source: modelData.error ? "dialog-error" : "checkmark"
+                            implicitWidth: Kirigami.Units.iconSizes.small
+                            implicitHeight: implicitWidth
+                        }
+                        Controls.Label {
+                            Layout.maximumWidth: Kirigami.Units.gridUnit * 24
+                            wrapMode: Text.Wrap
+                            text: modelData.text
+                        }
+                        Controls.ToolButton {
+                            visible: modelData.link !== ""
+                            icon.name: "internet-services"
+                            text: "Open"
+                            onClicked: Qt.openUrlExternally(modelData.link)
+                        }
+                    }
+                }
+                Controls.Button {
+                    visible: backend.doneLog.length > 0
+                    text: "Clear"
+                    icon.name: "edit-clear-history"
+                    flat: true
+                    onClicked: backend.clearDoneLog()
+                }
             }
 
             footer: Controls.Label {
@@ -1433,8 +1613,9 @@ Kirigami.ApplicationWindow {
                 opacity: 0.7
                 text: "Export leaves out the ranges you deleted, encrypts the eye images and any health answers to "
                       + "the dataset's keys (only its maintainers can read them), and adds a manifest and checksums, "
-                      + "in " + backend.exportsDir + ". It runs at the lowest priority; the headset stays awake "
-                      + "until it's done. Nothing is uploaded until you press Upload on the Upload page."
+                      + "in " + backend.exportsDir + ". It runs at the lowest priority, one at a time; the headset "
+                      + "stays awake until they're done. Nothing is uploaded unless you press Export and upload here, "
+                      + "or Upload on the Upload page."
             }
         }
     }
@@ -1460,7 +1641,7 @@ Kirigami.ApplicationWindow {
             readonly property string blocked: {
                 if (session === "") return "Choose an export"
                 if (chosen && chosen.export_stale) return "Export the round again first"
-                if (backend.exporting) return "Wait for the export to finish"
+                if (root.exportPending(session)) return "Wait for its export to finish"
                 if (backend.uploading) return ""
                 if (backend.hubDryRun) return ""
                 if (!backend.uploadAllowed) return "Contributions aren't open yet"
@@ -1473,6 +1654,14 @@ Kirigami.ApplicationWindow {
             Connections {
                 target: backend
                 function onSessionsChanged() { uploadView.refreshInfo() }
+                // An upload started by itself (queued on the Export page): show it.
+                function onUploadChanged() {
+                    const i = backend.uploading ? exportBox.indexOfValue(backend.upload.session) : -1
+                    if (i >= 0 && i !== exportBox.currentIndex) {
+                        exportBox.currentIndex = i
+                        exportBox.keep = backend.upload.session
+                    }
+                }
             }
             Component.onCompleted: {
                 refreshInfo()
@@ -1553,8 +1742,19 @@ Kirigami.ApplicationWindow {
                             textRole: "label"
                             valueRole: "id"
                             enabled: !backend.uploading
-                            Component.onCompleted: currentIndex = Math.max(0, indexOfValue(root.chosenSession))
-                            onActivated: root.chosenSession = currentValue
+                            // An export that finishes meanwhile adds a row (newest first): stay on the
+                            // same export, the uploading one while an upload runs.
+                            property string keep: ""
+                            Component.onCompleted: {
+                                currentIndex = Math.max(0, indexOfValue(root.chosenSession))
+                                keep = currentValue || ""
+                            }
+                            onActivated: root.chosenSession = keep = currentValue
+                            onModelChanged: Qt.callLater(() => {
+                                const i = indexOfValue(backend.uploading ? backend.upload.session : keep)
+                                currentIndex = i >= 0 ? i : (count > 0 ? Math.max(0, currentIndex) : -1)
+                                keep = currentValue || ""
+                            })
                         }
                         Controls.Label {
                             opacity: 0.7
@@ -1667,6 +1867,14 @@ Kirigami.ApplicationWindow {
                               + "\">its page</a>. Upload checks the export, opens your pull request, then sends the files."
                         onLinkActivated: link => Qt.openUrlExternally(link)
                     }
+                    Controls.Label {
+                        Layout.fillWidth: true
+                        visible: backend.uploadQueue.length + backend.uploadAfter.length > 0
+                        wrapMode: Text.Wrap
+                        opacity: 0.7
+                        text: "Queued on the Export page to upload after this one, by themselves: "
+                              + root.plural(backend.uploadQueue.length + backend.uploadAfter.length, "export") + "."
+                    }
                     RowLayout {
                         Controls.Button {
                             text: backend.uploading ? "Uploading…" : backend.hubDryRun ? "Upload (dry run)" : "Upload"

gaze/rec/rounds/README.md

@@ -26,6 +26,32 @@ Every recorded second becomes training data, labelled by where the dot was. So:
 - **Rounds open the same way.** The recorder adds putting the headset on and the nine dots before every
   round. Don't repeat them. The group `dots` is theirs **(checked)**.
 
+## What the person sees and hears, step by step
+
+A round moves through the same states every step. Each one has its own way of telling the person what
+to do and when, and the step's text and cues have to fit it.
+
+| State | Recorded | What they do | How they know when |
+|---|---|---|---|
+| Ready screen | no | read the text, press Next | the title, the text, the keys line |
+| Countdown 3-2-1 | yes | look at the dot it shows | the numbers |
+| Eyes on dots | yes | look at each dot | its ring fills, then the dot moves; the bar along the bottom |
+| Eyes shut | yes | close, then open | beeps (below) |
+| Moving the headset | yes | push, slide or tilt it by hand, hold, let go | a cue word and a beep each way (below) |
+| Head or reading | yes | the one action the text says, until the bar runs out | the bar along the bottom |
+
+- **The ready screen says it all, the action first.** It's the only time they read: what to do, what
+  starts it ("when it says Push up and beeps"), and what ends it ("until its ring fills", "until the bar
+  runs out", "until it says Let go"). A step with no ready screen (`"ready": false`) can only add to that
+  in a few words, as they're doing something already.
+- **Nothing starts in the countdown.** It points the eyes at the first dot. A one-off action (a blink, a
+  push) starts on a cue word after it, never on "go" from the numbers.
+- **One-off actions get a cue word; ongoing ones get the bar.** Turning the head, reading or looking
+  around run until the bar runs out. A push, a blink or closing the eyes happens on its cue.
+- **Redo does a chain again.** R or two presses during a step start it again, from the first step of its
+  chain; at a ready screen they go back to the step before. Make a chain one thing to do over: a nudge,
+  the dots done holding it, and letting go.
+
 ## Cues the person can't see get a beep
 
 The panel can't cue someone whose eyes are shut. A cue that asks for that plays a beep
@@ -42,6 +68,26 @@ The panel can't cue someone whose eyes are shut. A cue that asks for that plays
 - **No voice.** Beeps only; generated speech sounds odd in the headset. A new kind of cue sound goes
   into `sounds.SOUNDS` and the tests.
 
+## Moving the headset by hand
+
+A hand on the headset can't press Next, and the moment it moves is what the data is about. So:
+
+- **A cue word and a beep start it:** a cue word starting with push, pull, slide, tilt, tip or nudge plays
+  `go` **(checked)**: `["Push up", 2.5, "go"]`. Say the direction in the word, the same way each time
+  ("to your left", "left side up").
+- **Eyes first:** a cue on the dot comes before it, so there's a still moment to compare with
+  **(checked)**: `["Look at the dot", 1.5]`.
+- **Letting go has its own cue and beep:** "Let go" plays `done` **(checked)** and shows 2 s or more
+  **(checked)**, long enough to put the headset back and look at the dot again.
+- **In the same chain:** the `done` cue comes before the next ready screen, a new group or a reseat
+  **(checked)**, so a redo does the push, the dots and the letting go again.
+- **Steps done while holding say so:** their text starts "Keep holding" **(checked)**.
+- **Say exactly how, in the ready screen's text:** where the hand goes (the same grip each time), which way
+  it moves, how far, what stays still ("Keep it level", "Its middle stays where it is"), and that the head
+  and eyes don't move. "Push the headset up" alone leaves people guessing.
+- **A few millimetres, one hand, gently.** Say it in the round's intro, with the kinds of move to come, and
+  that a little blur while it's moved is fine. Never press it into the face.
+
 ## Cue words are labels
 
 Training reads the cue words in `prompts.jsonl` (`frame-eyes/train/data/ingest.py`, `shut_cams`):

gaze/rec/rounds/slips.json

@@ -2,25 +2,35 @@
  "schema": 1,
  "id": "slips",
  "title": "Headset slips",
- "intro": "You'll nudge the headset on your face on purpose, then put it back. Use one hand, gently: a few millimetres is enough.",
+ "intro": "You'll move the headset on your face on purpose, seven ways: up, down, to your left, to your right, tilted, tipped forward and away from your face. Each time it's one hand on the front and a few millimetres, no more; each step says how. The picture may blur a little while it's moved: that's fine. Then you take it off and put it back on.",
  "steps": [
   {
    "id": "nudge-up",
    "kind": "prompt",
    "group": "nudges",
-   "text": "Keep looking at the dot and push the headset up a little. Hold it there.",
+   "text": "Look at the dot. When it says Push up and beeps:|Hold the front with one hand, thumb under the bottom edge, and push the headset straight up a few millimetres, so it sits higher on your face. Keep it level: both sides go up together.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
    "dot": [
     0,
     0
    ],
-   "seconds": 5
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Push up",
+     2.5,
+     "go"
+    ]
+   ]
   },
   {
    "id": "after-up",
    "kind": "dots",
    "group": "nudges",
    "ready": false,
-   "text": "Hold the headset there. Look at each dot until its ring fills. Keep your head still.",
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
    "dots": [
     [
      0,
@@ -46,22 +56,50 @@
    "hold": 1.0
   },
   {
-   "id": "nudge-down",
+   "id": "back-up",
    "kind": "prompt",
    "group": "nudges",
-   "text": "Let go, then pull the headset down a little. Hold it there.",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
    "dot": [
     0,
     0
    ],
-   "seconds": 5
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-down",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Pull down and beeps:|Hold the front with one hand, thumb under the bottom edge, and pull the headset straight down a few millimetres, the way a loose headset sags. Keep it level: both sides go down together.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Pull down",
+     2.5,
+     "go"
+    ]
+   ]
   },
   {
    "id": "after-down",
    "kind": "dots",
    "group": "nudges",
    "ready": false,
-   "text": "Hold it there. Look at each dot until its ring fills. Keep your head still.",
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
    "dots": [
     [
      0,
@@ -87,22 +125,50 @@
    "hold": 1.0
   },
   {
-   "id": "nudge-left",
+   "id": "back-down",
    "kind": "prompt",
    "group": "nudges",
-   "text": "Let go, then slide the headset a little to your left.",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
    "dot": [
     0,
     0
    ],
-   "seconds": 5
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-left",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Slide to your left and beeps:|Hold the front with one hand, thumb under the bottom edge, and slide the headset a few millimetres to your left, across your face. Keep it level and at the same height.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Slide to your left",
+     2.5,
+     "go"
+    ]
+   ]
   },
   {
    "id": "after-left",
    "kind": "dots",
    "group": "nudges",
    "ready": false,
-   "text": "Hold it there. Look at each dot until its ring fills. Keep your head still.",
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
    "dots": [
     [
      0,
@@ -128,22 +194,50 @@
    "hold": 1.0
   },
   {
-   "id": "nudge-right",
+   "id": "back-left",
    "kind": "prompt",
    "group": "nudges",
-   "text": "Let go, then slide it a little to your right.",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
    "dot": [
     0,
     0
    ],
-   "seconds": 5
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-right",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Slide to your right and beeps:|Hold the front with one hand, thumb under the bottom edge, and slide the headset a few millimetres to your right, across your face. Keep it level and at the same height.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Slide to your right",
+     2.5,
+     "go"
+    ]
+   ]
   },
   {
    "id": "after-right",
    "kind": "dots",
    "group": "nudges",
    "ready": false,
-   "text": "Hold it there. Look at each dot until its ring fills. Keep your head still.",
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
    "dots": [
     [
      0,
@@ -169,22 +263,50 @@
    "hold": 1.0
   },
   {
-   "id": "nudge-tilt",
+   "id": "back-right",
    "kind": "prompt",
    "group": "nudges",
-   "text": "Let go, then tilt the headset a little: one side up.",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
    "dot": [
     0,
     0
    ],
-   "seconds": 5
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-tilt",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Tilt: left side up and beeps:|Hold the front with one hand, thumb under the bottom edge, and turn your wrist so the headset's left side goes up a few millimetres and its right side down, so it sits crooked on your face. Its middle stays where it is.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Tilt: left side up",
+     2.5,
+     "go"
+    ]
+   ]
   },
   {
    "id": "after-tilt",
    "kind": "dots",
    "group": "nudges",
    "ready": false,
-   "text": "Hold it there. Look at each dot until its ring fills. Keep your head still.",
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
    "dots": [
     [
      0,
@@ -209,6 +331,162 @@
    ],
    "hold": 1.0
   },
+  {
+   "id": "back-tilt",
+   "kind": "prompt",
+   "group": "nudges",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-tip",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Tip the front down and beeps:|Hold the front with one hand, thumb under the bottom edge, and tip the front down a little, the way a heavy headset droops: its bottom edge goes down a few millimetres and its top stays against your forehead. Keep it level side to side.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Tip the front down",
+     2.5,
+     "go"
+    ]
+   ]
+  },
+  {
+   "id": "after-tip",
+   "kind": "dots",
+   "group": "nudges",
+   "ready": false,
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
+   "dots": [
+    [
+     0,
+     0
+    ],
+    [
+     15,
+     12
+    ],
+    [
+     -15,
+     -12
+    ],
+    [
+     15,
+     -12
+    ],
+    [
+     -15,
+     12
+    ]
+   ],
+   "hold": 1.0
+  },
+  {
+   "id": "back-tip",
+   "kind": "prompt",
+   "group": "nudges",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
+  {
+   "id": "nudge-away",
+   "kind": "prompt",
+   "group": "nudges",
+   "text": "Look at the dot. When it says Pull away from your face and beeps:|Hold the front with one hand, thumb under the bottom edge, and pull the headset a few millimetres straight out, away from your face, so there's a small gap at your cheeks. Gently: the strap pulls back. Keep it level.|Only the headset moves: your head stays still and your eyes stay on the dot. Hold it there until it says Let go and beeps low.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Look at the dot",
+     1.5
+    ],
+    [
+     "Pull away from your face",
+     2.5,
+     "go"
+    ]
+   ]
+  },
+  {
+   "id": "after-away",
+   "kind": "dots",
+   "group": "nudges",
+   "ready": false,
+   "text": "Keep holding the headset there. Look at each dot until its ring fills. Keep your head still.",
+   "dots": [
+    [
+     0,
+     0
+    ],
+    [
+     15,
+     12
+    ],
+    [
+     -15,
+     -12
+    ],
+    [
+     15,
+     -12
+    ],
+    [
+     -15,
+     12
+    ]
+   ],
+   "hold": 1.0
+  },
+  {
+   "id": "back-away",
+   "kind": "prompt",
+   "group": "nudges",
+   "ready": false,
+   "text": "Keep holding it until it says Let go. Then put the headset back as it was, and look at the dot.",
+   "dot": [
+    0,
+    0
+   ],
+   "cues": [
+    [
+     "Let go, put it back",
+     3,
+     "done"
+    ]
+   ]
+  },
   {
    "id": "reseat",
    "kind": "reseat",

gaze/rec/session.py

@@ -24,9 +24,12 @@ steps are recorded; the frame writer pauses while a step waits. During the round
 looks again at the end of each centre dot, and a headset that moved since the fitment gets a
 note (fit.json "slips").
 
-Controls, as the hand recorder's: Next, pause, redo (the step running, or at a ready screen the
-one before; the range is marked with a "redo" event), skip (the rest of the take), stop. The
-headset button: press = next or pause, two presses = redo, hold = stop.
+Controls, as the hand recorder's: Next, pause, redo, skip (the rest of the take), stop. Redo in
+the countdown or the step starts it again; at a ready screen it goes back to the step before,
+into the take before too (Back). A step that follows on without a ready screen goes again with
+the one it follows. The range done before is marked with a "redo" event. The headset button:
+press = next or pause, two presses = redo, hold = stop. The panel's keys line says what redo
+does at that moment.
 
 Round scripts, rounds/<id>.json: {"schema": 1, "id", "title", "intro", "shift_check": true,
 "steps": [step]}. A step: {"id", "kind", "text" ("|" starts a line), "group" (default its id),
@@ -37,8 +40,9 @@ Round scripts, rounds/<id>.json: {"schema": 1, "id", "title", "intro", "shift_ch
   jumps    "count", "range": [yaw, pitch] (a box), "each": [shortest, longest] s
   prompt   "dot": [yaw, pitch] or null (none), and "seconds" or "cues": [[word, s]...] (shown
            big in turn; [word, s, sound] also plays a beep as it starts, for steps done with the
-           eyes shut: sound blink, close or open, sounds.py; rounds/README.md has the rules,
-           and load_round enforces them), "cue_distance": {word: metres}
+           eyes shut or moving the headset by hand: sound blink, close, open, go or done,
+           sounds.py; rounds/README.md has the rules, and load_round enforces them),
+           "cue_distance": {word: metres}
   light    "dot", "levels": [[background, s]...]
   world    "point": [x, y, z] (metres from the head when it starts, -z ahead), "seconds"
   reseat   not recorded: the text, Next, then a fit reading
@@ -121,9 +125,11 @@ READY_BUTTON = "Ready? Press the button on the right side of the headset"
 READY_BUTTON_MOUSE = "Ready? Press Space, click Next, or press the headset button"
 RESUME_HINT = "Paused. Resume: P in the Eye recorder window"
 RESUME_HINT_BUTTON = "Paused. Resume: press the headset button, or P in the Eye recorder window"
-KEYS = "Eye recorder window:  Space next  ·  P pause  ·  R redo  ·  S skip  ·  Esc stop"
-KEYS_BUTTON = ("Headset button: press for next or pause  ·  press twice to redo  ·  hold to stop  "
-               "·  Window: Space P R S Esc")
+# What R (two presses of the headset button) does now, for the panel's keys line (_keys): during
+# the countdown and the step, it starts again; at a ready screen, the step before goes again.
+REDO_RUNNING = "start this step again"
+REDO_BACK = "back to the last step"
+NOTHING_BACK = "Nothing to go back to from here"
 FIT_TITLE = "Headset fit"
 FIT_TEXT = "Look at the dot. Adjust the headset until this says good."
 FIT_ADJUST = "Adjust the headset until it says good"
@@ -216,11 +222,20 @@ def _dot(v, what):
     return d
 
 
+HAND_WORDS = ("push", "pull", "slide", "tilt", "tip", "nudge")   # a cue word starting so moves the headset
+HOLD_TEXT = "Keep holding"      # the text of a step done while holding the headset moved
+
+
 def cue_needs(word):
-    """The sound a cue must have because the person can't see the panel then (rounds/README.md):
-    "blink" for a blink, "close" for shutting both eyes, else None. Half-closed eyes and one eye
-    (a wink: the other one reads the panel) don't need one."""
+    """The sound a cue must have because the person can't see the panel then, or the timing is
+    the point (rounds/README.md): "blink" for a blink, "close" for shutting both eyes, "go" for
+    moving the headset by hand, "done" for letting go of it, else None. Half-closed eyes and one
+    eye (a wink: the other one reads the panel) don't need one."""
     w = word.lower()
+    if w.split()[:1] and w.split()[0].strip(":,") in HAND_WORDS:
+        return "go"
+    if "let go" in w:
+        return "done"
     if "half" in w or "left" in w or "right" in w:
         return None
     if "blink" in w:
@@ -232,7 +247,8 @@ def cue_needs(word):
 
 def _check_sounds(cues, sid):
     """Eyes-shut cues beep, and the cue after a "close" plays "open": with the eyes shut, the
-    words can't tell anyone when to open them."""
+    words can't tell anyone when to open them. A push on the headset ("go") comes after a cue on
+    the dot, and letting go ("done") shows long enough to settle."""
     for k, (word, _secs, *sound) in enumerate(cues):
         need = cue_needs(word)
         if need and sound != [need]:
@@ -240,6 +256,38 @@ def _check_sounds(cues, sid):
                              % (sid, word, need))
         if sound == ["close"] and (k + 1 == len(cues) or cues[k + 1][2:] != ["open"]):
             raise ValueError('%s: after "%s" comes a cue with the sound "open" (rounds/README.md)' % (sid, word))
+        if sound == ["go"] and k == 0:
+            raise ValueError('%s: "%s" comes after a cue on the dot, so the eyes are still first (rounds/README.md)'
+                             % (sid, word))
+        if sound == ["done"] and _secs < 2:
+            raise ValueError('%s: "%s" shows 2 s or more, so the eyes settle (rounds/README.md)' % (sid, word))
+
+
+def _check_hands(steps, path):
+    """A headset moved by hand is let go of in the same chain (the steps that follow on without a
+    ready screen), and the steps done while holding it say so: the person can't take a hand off
+    the headset to press Next, and a redo does the whole chain again."""
+    holding = None      # the step whose "go" cue moved the headset
+    for k, st in enumerate(steps):
+        if holding and (st["ready"] or st["group"] != holding["group"] or st["kind"] == "reseat"):
+            raise ValueError('%s: %s moves the headset; a "done" cue ("Let go...") follows in its chain '
+                             '(rounds/README.md)' % (path, holding["id"]))
+        sounds_ = [c[2] for c in st.get("cues") or [] if len(c) > 2]
+        if holding and not st["text"].startswith(HOLD_TEXT):
+            raise ValueError('%s: %s is done holding the headset; its text starts "%s" (rounds/README.md)'
+                             % (path, st["id"], HOLD_TEXT))
+        for snd in sounds_:
+            if snd == "go":
+                if holding:
+                    raise ValueError('%s: %s moves the headset again before letting go' % (path, st["id"]))
+                holding = st
+            elif snd == "done":
+                if not holding:
+                    raise ValueError('%s: %s lets go of a headset nothing moved' % (path, st["id"]))
+                holding = None
+    if holding:
+        raise ValueError('%s: %s moves the headset; a "done" cue ("Let go...") follows in its chain '
+                         '(rounds/README.md)' % (path, holding["id"]))
 
 
 def _step(raw, i):
@@ -356,6 +404,7 @@ def load_round(path):
         last = s["group"]
     if "dots" in groups:
         raise ValueError("%s: the group dots is the opener's" % path)
+    _check_hands(steps, path)
     rid = raw.get("id")
     return {"id": rid if isinstance(rid, str) else os.path.basename(path)[:-5], "title": str(raw.get("title", rid)),
             "intro": str(raw.get("intro", "")), "shift_check": raw.get("shift_check", True) is not False and
@@ -647,6 +696,7 @@ class Session:
         self._paused = self._paused_recording = False
         self._waiting = False
         self._redo_ok = False
+        self._lingering = False
         self._button_reader = None
         self._ipd = None
         self._step_t0 = None
@@ -897,7 +947,7 @@ class Session:
     def _finish(self, state, error=""):
         if self._take:
             try:
-                self._end_take("complete" if state == "done" else "stopped")
+                self._end_take("complete" if state == "done" or self._lingering else "stopped")
             except Exception:
                 self._log(traceback.format_exc())
         if self._session_json is not None:
@@ -963,6 +1013,9 @@ class Session:
             raise _Skip()
         if want["redo"] and self._redo_ok:
             raise _Redo()
+        if want["redo"] and self._waiting:
+            self._panel.set("note", "note " + NOTHING_BACK)
+            self._emit(note=NOTHING_BACK)
         if not want["pause"]:
             return False
         self._pause()
@@ -1064,9 +1117,21 @@ class Session:
         text = (READY_BUTTON_MOUSE if mouse_connected(self.input_devices) else READY_BUTTON) if button else READY_TEXT
         if action:
             self._panel.set("action", "action " + text)
-        self._panel.set("keys", "keys " + (KEYS_BUTTON if button else KEYS))
+        self._keys(back=self._redo_ok)
         self._status.update(ready_text=text, button=button)
 
+    def _keys(self, running=False, back=False):
+        """The panel's bottom line: the controls, saying what R does now (or leaving it out)."""
+        redo = REDO_RUNNING if running else REDO_BACK if back else ""
+        if self._button_ok():
+            parts = ["Headset button: press for " + ("pause" if running else "next")]
+            parts += ["press twice: " + redo] if redo else []
+            text = "  ·  ".join(parts + ["hold to stop", "Window: Space P R S Esc"])
+        else:
+            parts = ["Eye recorder window:  Space next", "P pause"] + (["R " + redo] if redo else [])
+            text = "  ·  ".join(parts + ["S skip", "Esc stop"])
+        self._panel.set("keys", "keys " + text)
+
     def _show(self, title, text):
         self._panel.set("title", "title " + clean_text(title))
         self._panel.set("text", "text " + clean_text(text))
@@ -1292,15 +1357,29 @@ class Session:
             self._log("take %s %s" % (t["id"], status))
 
     # --- the steps
+    def _chain_head(self, k):
+        """The first step of k's chain: the steps that follow on without a ready screen ("ready":
+        false) go again with the one they follow (a nudge and the dots done while holding it)."""
+        plan, h = self.plan, k
+        while h > 0 and not plan[h]["ready"] and plan[h - 1]["group"] == plan[k]["group"]:
+            h -= 1
+        return h
+
     def _steps(self):
         """The plan's steps. Each "ready" one (and one to do again) shows first and waits for
         Next, then a recorded countdown; the recording pauses after a step unless the next one
-        follows straight on. A new group starts a new take. R during a step: it starts again;
-        at a ready screen: the step before (in the same take) goes again."""
+        follows straight on. A new group starts a new take, once its first step's Next is
+        pressed: until then the take before stays open, so Back can reach its last step.
+
+        R during the countdown or the step: it starts again, from the start of its chain (a step
+        that follows on goes again with the one it follows). R at a ready screen (Back): the
+        step before goes again, with its chain. Either way the range done before is marked with
+        a "redo" event. Nothing goes back over a reseat: the headset sits differently after it."""
         plan = self.plan
-        done = []       # steps finished in this take: (index, id, from_ns, to_ns)
+        done = []       # steps finished in the open take: (index, id, from_ns, to_ns)
         again = set()
         k = 0
+        self._lingering = False   # the open take's steps are done; it ends at the next step's Next
         while k < len(plan):
             st = plan[k]
             where = "%s · step %d of %d" % (self._session_json["title"], k + 1, len(plan))
@@ -1310,23 +1389,31 @@ class Session:
                 if self._take:
                     self._end_take("complete")
                 done = []
+                self._lingering = False
                 self._reseat(st)
                 k += 1
                 continue
-            if self._take and self._take["group"] != st["group"]:
-                self._end_take("complete")
+            ready = st["ready"] or k in again
+            if self._take and self._take["group"] != st["group"] and not ready:
+                self._end_take("complete")      # follows on into a new group: no screen to go back from
                 done = []
+            self._lingering = bool(self._take and self._take["group"] != st["group"])
             started = self._step_t0 = None
             try:
-                if st["ready"] or k in again:
+                if ready:
                     self._redo_ok = bool(done)
                     self._ready(st, can_redo=bool(done))
                     self._await_next()
+                    if self._take and self._take["group"] != st["group"]:
+                        self._end_take("complete")
+                        done = []
+                    self._lingering = False
                     self._redo_ok = True
                     started = self._countdown(st)
                 else:
                     self._redo_ok = True
                     self._show(self._title(st), st["text"])
+                    self._keys(running=True)
                     self._emit(can_redo=True, prompt=st["text"].replace("|", "\n"))
                     self._step_t0 = started = self._event("step", id=st["id"], kind=st["kind"])
                 self._take["json"]["steps"].append(st["id"]) if st["id"] not in self._take["json"]["steps"] else None
@@ -1340,29 +1427,43 @@ class Session:
                 k += 1
             except _Redo:
                 self._redo_ok = False
-                if started is not None:
-                    self._event("redo", id=st["id"], **{"from": started, "to": mono_ns()})
-                    self._log("    redo %s" % st["id"])
+                if started is None:
+                    started = self._step_t0   # R in the countdown: its "ready" event
+                if started is not None:   # this step again, from the start of its chain
+                    h = self._chain_head(k)
+                    while done and done[-1][0] >= h:
+                        started = done.pop()[2]
+                    self._event("redo", id=plan[h]["id"], **{"from": started, "to": mono_ns()})
+                    self._log("    redo %s" % plan[h]["id"])
                     self._step_end()
-                    again.add(k)
-                elif done:
+                    k = h
+                    again = {x for x in again if x < k} | {k}
+                elif done:                # Back: the step before, with its chain
                     k, sid, a, b = done.pop()
+                    h = self._chain_head(k)
+                    while done and done[-1][0] >= h:
+                        k, sid, a, _ = done.pop()
                     self._event("redo", id=sid, **{"from": a, "to": b})
-                    self._log("    redo %s" % sid)
-                    again.add(k)
+                    self._log("    back to %s" % sid)
+                    self._lingering = False
+                    again = {x for x in again if x < k} | {k}
             except _Skip:
                 group = st["group"]
                 self._log("skipped the rest of %s" % group)
-                if self._take:
+                if self._take and self._take["group"] != group:
+                    self._end_take("complete")      # at the first step's ready screen: the take before is done
+                elif self._take:
                     self._step_end()
                     self._end_take("skipped")
                 done = []
+                self._lingering = False
                 while k < len(plan) and plan[k]["group"] == group and plan[k]["kind"] != "reseat":
                     k += 1
             finally:
                 self._redo_ok = False
         if self._take:
             self._end_take("complete")
+        self._lingering = False
 
     def _ready(self, st, can_redo):
         self._show(self._title(st), st["text"])
@@ -1394,6 +1495,9 @@ class Session:
             self._start_take(st["group"])
         t = self._step_t0 = self._event("ready", id=st["id"], seconds=COUNTDOWN_S)
         self._record(True)
+        self._keys(running=True)
+        self._panel.set("note", "note ")
+        self._emit(note="")
         first = self._first_dot(st)
         if first:
             self._panel.cmd("dot %.3f %.3f look" % tuple(first))

gaze/rec/sounds.py

@@ -1,11 +1,13 @@
 #!/usr/bin/env python3
 """The eye recorder's sound cues: plain beeps for steps done with the eyes shut, where the panel's
-words can't be seen. A round script names one as a cue's third field (session.py: "cues":
+words can't be seen, and for moving the headset by hand, where the timing matters. A round script names one as a cue's third field (session.py: "cues":
 [[word, seconds, sound]...]); it plays as the cue starts, and prompts.jsonl's "cue" line says which.
 
   blink   a short high beep: blink once
   close   a beep: close your eyes
   open    the same beep again: open them
+  go      a higher beep: move the headset now (the cue word says how)
+  done    a low, longer one: let go of it
 
 No voice, no sound files: the beeps are made here (a sine with a short fade, so it doesn't click)
 into the run folder, and played with PipeWire's pw-play on the default output (the headset's
@@ -31,6 +33,8 @@ SOUNDS = {
     "blink": (1000.0, 0.09),
     "close": (660.0, 0.18),
     "open": (660.0, 0.18),
+    "go": (880.0, 0.14),
+    "done": (440.0, 0.3),
 }
 FADE_S = 0.005
 

gaze/rec/tests/test_session.py

@@ -76,6 +76,24 @@ class RoundTest(unittest.TestCase):
         self.bad([{"id": "a", "kind": "prompt", "cues": [["Close both eyes", 2], ["Open", 2]]}], 'needs the sound "close"')
         self.bad([{"id": "a", "kind": "prompt", "cues": [["Shut your eyes", 2, "close"]]}], 'comes a cue with the sound "open"')
         self.bad([{"id": "a", "kind": "prompt", "cues": [["Close your eyes", 2, "close"], ["Open", 2]]}], '"open"')
+        # Moving the headset by hand
+        look = ["Look at the dot", 1.5]
+        self.bad([{"id": "a", "kind": "prompt", "cues": [look, ["Push up", 2]]}], 'needs the sound "go"')
+        self.bad([{"id": "a", "kind": "prompt", "cues": [["Push up", 2, "go"], ["Let go", 2, "done"]]}],
+                 "the eyes are still first")
+        self.bad([{"id": "a", "kind": "prompt", "cues": [look, ["Push up", 2, "go"], ["Let go", 1, "done"]]}], "2 s or more")
+        self.bad([{"id": "a", "kind": "prompt", "cues": [look, ["Push up", 2, "go"]]}], 'a "done" cue')
+        self.bad([{"id": "a", "kind": "prompt", "cues": [look, ["Push up", 2, "go"]]},
+                  {"id": "b", "kind": "prompt", "cues": [["Let go", 2, "done"]]}], 'a "done" cue')
+        self.bad([{"id": "a", "kind": "prompt", "cues": [look, ["Tilt: left side up", 2, "go"]]},
+                  {"id": "b", "kind": "dots", "ready": False, "group": "a", "dots": [[0, 0]], "text": "Look"},
+                  {"id": "c", "kind": "prompt", "ready": False, "group": "a", "text": "Keep holding",
+                   "cues": [["Let go", 2, "done"]]}], 'starts "Keep holding"')
+        session.load_round(write_round(self.tmp, [
+            {"id": "a", "kind": "prompt", "cues": [look, ["Slide to your left", 2, "go"]]},
+            {"id": "b", "kind": "dots", "ready": False, "group": "a", "dots": [[0, 0]], "text": "Keep holding it"},
+            {"id": "c", "kind": "prompt", "ready": False, "group": "a", "text": "Keep holding",
+             "cues": [["Let go, put it back", 2, "done"]]}]))
         for word in ("Close your left eye", "Half closed", "Squint", "Open"):
             session.load_round(write_round(self.tmp, [{"id": "a", "kind": "prompt", "cues": [[word, 1]]}]))
 
@@ -300,6 +318,116 @@ class DryRunTest(unittest.TestCase):
         self.assertLess(redo[0]["from"], redo[0]["to"])
         self.assertNotIn("bounties", profile, "a stopped round isn't counted")
 
+    # A round of two takes: a nudge with dots done while holding it (a chain), then one prompt.
+    TWO = [{"id": "nudge", "kind": "prompt", "group": "one", "dot": [0, 0], "seconds": 1, "text": "Push"},
+           {"id": "hold", "kind": "dots", "group": "one", "dots": [[0, 0], [5, 0]], "hold": 0.5, "ready": False,
+            "text": "Keep holding"},
+           {"id": "other", "kind": "prompt", "group": "two", "dot": [0, 0], "seconds": 1, "text": "Other"}]
+
+    def run_two(self, steer, **kw):
+        write_round(self.tmp, self.TWO)
+        return self.run_round("t", steer=steer, speed=10, next_after=0.6, rounds_dir=self.tmp, fit_coach=False,
+                              profile={"eyes_ipd": 0.063}, **kw)
+
+    @staticmethod
+    def at(s, step, state):
+        end = time.monotonic() + 30
+        while time.monotonic() < end and not (s._status["step"] == step and s._status["state"] == state):
+            time.sleep(0.005)
+        return s._status["step"] == step and s._status["state"] == state
+
+    def take_status(self, s, take):
+        with open(os.path.join(s.session_dir, "takes", take, "take.json")) as f:
+            return json.load(f)["status"]
+
+    def redos(self, s, take):
+        return [e["id"] for e in self.prompts(s, take) if e["event"] == "redo"]
+
+    def test_redo_in_the_countdown(self):
+        # R in the countdown starts this step again (it used to go back to the one before).
+        seen = {}
+        def steer(s, states):
+            self.assertTrue(self.at(s, "other", "countdown"))
+            s.redo()
+            seen["ready"] = self.at(s, "other", "ready")
+            seen["recording"] = s._recording
+        s, _, _ = self.run_two(steer)
+        self.assertEqual(s.state, "done")
+        self.assertTrue(seen["ready"])
+        self.assertFalse(seen["recording"], "the ready screen isn't recorded")
+        takes = self.files(s)[0]["takes"]
+        self.assertEqual(self.redos(s, takes[-1]), ["other"])
+        self.assertEqual(self.redos(s, takes[-2]), [])
+
+    def test_back_into_the_take_before(self):
+        # Back at a new take's first ready screen: the take before stays open until its Next,
+        # so its last step (with the nudge it follows on from) goes again in the same take.
+        seen = {}
+        def steer(s, states):
+            self.assertTrue(self.at(s, "other", "ready"))
+            seen["can_redo"] = s._status["can_redo"]
+            s.redo()
+            seen["back"] = self.at(s, "nudge", "ready")
+        s, _, _ = self.run_two(steer)
+        self.assertEqual(s.state, "done")
+        self.assertTrue(seen["can_redo"])
+        self.assertTrue(seen["back"], "back to the chain's head, not to hold")
+        takes = self.files(s)[0]["takes"]
+        self.assertEqual(len(takes), 3, takes)        # the opener's dots, one, two: no extra take
+        one = self.prompts(s, takes[1])
+        self.assertEqual(self.redos(s, takes[1]), ["nudge"])
+        self.assertEqual([e["id"] for e in one if e["event"] == "step"], ["nudge", "hold", "nudge", "hold"])
+        self.assertEqual(self.take_status(s, takes[1]), "complete")
+
+    def test_redo_a_step_that_follows_on(self):
+        # R while holding: the nudge goes again with it.
+        def steer(s, states):
+            self.assertTrue(self.at(s, "hold", "running"))
+            s.redo()
+            self.assertTrue(self.at(s, "nudge", "ready"))
+        s, _, _ = self.run_two(steer)
+        self.assertEqual(s.state, "done")
+        takes = self.files(s)[0]["takes"]
+        steps = [e["id"] for e in self.prompts(s, takes[1]) if e["event"] == "step"]
+        self.assertEqual(self.redos(s, takes[1]), ["nudge"])
+        self.assertEqual(steps, ["nudge", "hold", "nudge", "hold"])
+
+    def test_stop_or_skip_at_the_next_ready_screen(self):
+        # The take before is finished, not stopped or skipped, when the next take's ready screen
+        # is where it ends.
+        def stop(s, states):
+            self.assertTrue(self.at(s, "other", "ready"))
+            s.stop(wait=0)
+        s, _, _ = self.run_two(stop)
+        self.assertEqual(s.state, "stopped")
+        takes = self.files(s)[0]["takes"]
+        self.assertEqual(len(takes), 2)
+        self.assertEqual(self.take_status(s, takes[1]), "complete")
+
+        def skip(s, states):
+            self.assertTrue(self.at(s, "other", "ready"))
+            s.skip()
+        s, _, _ = self.run_two(skip)
+        self.assertEqual(s.state, "done")
+        takes = self.files(s)[0]["takes"]
+        self.assertEqual(len(takes), 2, "two was skipped before it started")
+        self.assertEqual(self.take_status(s, takes[1]), "complete")
+
+    def test_nothing_to_go_back_to(self):
+        # After a reseat Back is off: the headset sits differently now.
+        rnd = [{"id": "a", "kind": "prompt", "dot": [0, 0], "seconds": 1, "text": "A"},
+               {"id": "off", "kind": "reseat", "text": "off and on"},
+               {"id": "b", "kind": "prompt", "dot": [0, 0], "seconds": 1, "text": "B"}]
+        write_round(self.tmp, rnd)
+        seen = {}
+        def steer(s, states):
+            self.assertTrue(self.at(s, "b", "ready"))
+            seen["can_redo"] = s._status["can_redo"]
+        s, states, _ = self.run_round("t", steer=steer, speed=10, next_after=0.4, rounds_dir=self.tmp,
+                                      fit_coach=False, profile={"eyes_ipd": 0.063})
+        self.assertEqual(s.state, "done")
+        self.assertFalse(seen["can_redo"], "nothing goes back over a reseat")
+
     def test_pause_stops_the_recording(self):
         def steer(s, states):
             end = time.monotonic() + 30

gaze/rec/tests/test_sounds.py

@@ -24,7 +24,8 @@ class SoundsTest(unittest.TestCase):
         shutil.rmtree(self.tmp, ignore_errors=True)
 
     def test_wavs(self):
-        self.assertEqual(set(sounds.SOUNDS), {"blink", "close", "open"})
+        self.assertEqual(set(sounds.SOUNDS), {"blink", "close", "open", "go", "done"})
+        self.assertEqual(len({sounds.SOUNDS[n] for n in ("blink", "close", "go", "done")}), 4, "told apart by ear")
         self.assertEqual(sounds.SOUNDS["close"], sounds.SOUNDS["open"], "open is the same beep again")
         for name, (hz, secs) in sounds.SOUNDS.items():
             path = sounds.wav_path(name)

gaze/test/blind-recalibration-test.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""Offline test of our own eye tracker's calibration going blind (gaze/gazecheck.py, OWN_GONE):
+a full calibration while ours is calibrated but sends no gaze. Live 2026-10-18 a calibration
+with the left eye closed mapped only the right eye; the next one, with the right eye closed,
+took no dot, since every click waited for our tracker's gaze ("Waiting: the eye tracker isn't
+sending a gaze"). Now the dot stands in for the gaze while there's none, as in the first
+calibration (first-calibration-test.py), and ft-eyes checks the pupils it sees.
+
+Same harness as first-calibration-test.py: ft-gazed's Service with its sockets renamed and HOME
+in a temp folder, a fake pointer helper (gaze mode on, headset worn), a fake ft-gaze (SteamVR
+sees both eyes; ours sends a gaze while OWN_FLAG exists), a fake ft-eyes control socket
+(calibrated), and no panel. Nothing reaches the live gaze service, the pointer helper, ft-eyes,
+or SteamVR, so it's safe next to them.
+
+  gaze/test/blind-recalibration-test.py
+"""
+import os
+import tempfile
+
+HOME = tempfile.mkdtemp(prefix="ft-gaze-blind-recal-test-")
+os.environ["HOME"] = HOME  # before gazecal: its STATE, and frametop.conf, follow HOME
+
+import importlib.machinery  # noqa: E402
+import importlib.util  # noqa: E402
+import json  # noqa: E402
+import selectors  # noqa: E402
+import shutil  # noqa: E402
+import socket  # noqa: E402
+import subprocess  # noqa: E402
+import sys  # noqa: E402
+import threading  # noqa: E402
+import time  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+GAZE = os.path.join(HERE, "..")
+sys.path.insert(0, GAZE)
+loader = importlib.machinery.SourceFileLoader("ftgazed", os.path.join(GAZE, "ft-gazed"))
+gazed = importlib.util.module_from_spec(importlib.util.spec_from_loader("ftgazed", loader))
+loader.exec_module(gazed)
+import gazecheck  # noqa: E402  (the module ft-gazed imported)
+
+tag = f"ft_gaze_blind_recal_test_{os.getpid()}"
+gazed.ME = f"\0{tag}_gazed"
+gazed.POINTER = gazecheck.POINTER = f"\0{tag}_helper"
+gazecheck.SCREENS = f"\0{tag}_screens"
+gazecheck.PANEL = f"\0{tag}_panel"
+gazed.EYES_SOCKET = gazecheck.EYES = f"\0{tag}_eyes"
+gazed.read_settings = lambda: ("own", "auto", "auto", 55.0)
+gazed.TrackedEye = lambda: lambda now=None: None  # both eyes, whatever SteamVR's settings say
+DOTS = 4
+real_dots = gazecheck.check_dots
+gazecheck.check_dots = lambda kind, own: real_dots(kind, own)[:DOTS]  # a short calibration
+gazecheck.Fusion.MIN = DOTS   # ...whose dots still fit a fusion (SteamVR's eyes at each)
+gazecheck.LOOKED_AWAY = 1e9   # the fake SteamVR's eyes stay put whatever the dot (looked-away-test.py has that check)
+logs = []
+gazed.log = gazecheck.log = lambda msg: logs.append(msg)
+
+# The fake ft-gaze: 90 samples a second, SteamVR sees both eyes, ours sends a gaze (the right
+# eye's, at 1, 2) while OWN_FLAG exists, and {"ok":0} as with a stale file otherwise.
+FAKE = os.path.join(HOME, "ft-gaze")
+OWN_FLAG = os.path.join(HOME, "own-gaze")
+with open(FAKE, "w") as f:
+    f.write('''import json, os, select, sys, time
+flag = sys.argv[1]
+while True:
+    if select.select([sys.stdin], [], [], 1 / 90)[0]:
+        if not os.read(0, 4096):
+            break
+    own = {"hy": 1.0, "hp": 2.0, "eyes": [None, [1.0, 2.0]]} if os.path.exists(flag) else {"ok": 0}
+    print(json.dumps({"t": time.monotonic(), "src": {"mmap1": {"hy": 1.0, "hp": 2.0, "unc": [0.001, 0.001],
+          "open": [0.8, 0.8]}, "left": {"hy": 0.0, "hp": 2.0}, "right": {"hy": 2.0, "hp": 2.0},
+          "own": own}}), flush=True)
+''')
+SLEEPER = [sys.executable, "-c", "import sys; sys.stdin.read()"]  # quits when its stdin closes
+
+
+def own_gaze(on):
+    if on:
+        open(OWN_FLAG, "w").close()
+    elif os.path.exists(OWN_FLAG):
+        os.remove(OWN_FLAG)
+
+
+def start_helper(self):
+    """ft-gaze, straight from here instead of the dev container."""
+    self.proc = subprocess.Popen([sys.executable, FAKE, OWN_FLAG], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                 stderr=subprocess.PIPE)
+    self.proc_sources = self.wanted_sources()
+    os.set_blocking(self.proc.stdout.fileno(), False)
+    os.set_blocking(self.proc.stderr.fileno(), False)
+    self.sel.register(self.proc.stdout, selectors.EVENT_READ, "stdout")
+    self.sel.register(self.proc.stderr, selectors.EVENT_READ, "stderr")
+    self.buf = b""
+
+
+def start_eyes(self):
+    """ft-eyes' process: a stand-in. Its control socket is the fake below."""
+    self.eyes_proc = subprocess.Popen(SLEEPER, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+    os.set_blocking(self.eyes_proc.stderr.fileno(), False)
+    self.sel.register(self.eyes_proc.stderr, selectors.EVENT_READ, "eyes")
+
+
+def start_panel(self):
+    self.panel_proc = subprocess.Popen(SLEEPER, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+    os.set_blocking(self.panel_proc.stderr.fileno(), False)
+    self.sel.register(self.panel_proc.stderr, selectors.EVENT_READ, "panel")
+
+
+gazed.Service.start_helper = start_helper
+gazed.Service.start_eyes = start_eyes
+gazecheck.Checks.start_panel = start_panel
+
+# The fake ft-eyes: calibrated (the right eye only, as after a calibration with the left closed).
+eyes_state = {"cal": {"made": "test", "dots": 27}, "points": []}
+eyes = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+eyes.bind(gazed.EYES_SOCKET)
+eyes.settimeout(0.2)
+
+
+def eyes_answer():
+    while True:
+        try:
+            data, addr = eyes.recvfrom(512)
+        except socket.timeout:
+            continue
+        except OSError:
+            return
+        w = data.decode().split()
+        if w[0] == "status":
+            reply = json.dumps({"calibration": eyes_state["cal"], "calibrating": False, "dots": 0, "mapped": ["right"],
+                                "eyes": {"right": {"reseat": False}, "left": {"reseat": False}}})
+        elif w[0] == "calib-start":
+            eyes_state["points"] = []
+            reply = "ok"
+        elif w[0] == "calib-point":
+            eyes_state["points"].append(tuple(map(float, w[1:5])))
+            reply = "ok 0 50 nan 1.00 (left eye only: the right eye was seen in only 0 frames)"
+        elif w[0] == "calib-fit":
+            eyes_state["cal"] = {"made": "test", "dots": len(eyes_state["points"])}
+            reply = f"ok {len(eyes_state['points'])} dots, fit median 1.00 deg, eyes right not used (0 dots, needs 12), left 1.00 ({len(eyes_state['points'])} dots)"
+        elif w[0] == "click":
+            continue
+        else:
+            reply = f"fail unknown command {w[0]}"
+        if addr:
+            eyes.sendto(reply.encode(), addr)
+
+
+threading.Thread(target=eyes_answer, daemon=True).start()
+
+helper_state = {"reply": "ok on worn", "heard": []}
+helper = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+helper.bind(gazed.POINTER)
+helper.settimeout(0.2)
+
+
+def helper_answer():
+    while True:
+        try:
+            data, addr = helper.recvfrom(512)
+        except socket.timeout:
+            continue
+        except OSError:
+            return
+        if data.startswith(b"gaze ?") and addr:
+            helper.sendto(helper_state["reply"].encode(), addr)
+        else:
+            helper_state["heard"].append(data.decode())
+
+
+threading.Thread(target=helper_answer, daemon=True).start()
+own_gaze(True)
+svc = gazed.Service(None, False, gazed.POINTER)
+threading.Thread(target=svc.run, daemon=True).start()
+ctl = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+ctl.bind("")
+ctl.settimeout(3)
+
+
+def ask(cmd):
+    ctl.sendto(cmd.encode(), gazed.ME)
+    return ctl.recv(65536).decode()
+
+
+failures = []
+
+
+def check(label, got, want):
+    ok = got == want
+    print(("ok    " if ok else "FAIL  ") + label + ("" if ok else f": got {got!r}, want {want!r}"), flush=True)
+    if not ok:
+        failures.append(label)
+
+
+def wait(cond, seconds):
+    end = time.monotonic() + seconds
+    while time.monotonic() < end:
+        if cond():
+            return True
+        time.sleep(0.05)
+    return cond()
+
+
+def check_state():
+    return svc.checks.check or {}
+
+
+def click_dot(i, settle=0.0):
+    """Wait for dot i, then click: is it taken (within 2 s)?"""
+    wait(lambda: check_state().get("i") == i and not check_state().get("done_at"), 3)
+    time.sleep(gazecheck.CHECK_SETTLE + gazecheck.CHECK_WINDOW + 0.1 + settle)
+    before = check_state().get("captured", 0)
+    ask("calaccept")
+    return wait(lambda: check_state().get("captured", 0) > before, 2)
+
+
+check("ours runs, calibrated", ask("wake 60") == "ok" and wait(lambda: svc.checks.calibrated() is True, 6), True)
+check("SteamVR sees the eyes (the fake ft-gaze is sending)", wait(svc.checks.eyes_seen, 6), True)
+check("calibrate: a full calibration opens",
+      ask("calibrate").startswith("ok") and wait(lambda: check_state().get("kind") == "full", 6), True)
+check("not blind: ours is calibrated", check_state().get("blind"), False)
+
+check("dot 1, ours sends a gaze: taken", click_dot(0), True)
+check("...on our gaze, not blind", (check_state().get("run_blind"), check_state().get("went_blind")), (False, False))
+
+# Dot 2: the eye ours maps closes, and its gaze stops. The old way (OWN_GONE never) the click waits.
+own_gaze(False)
+gazecheck.OWN_GONE = 1e9
+check("dot 2, no gaze from ours, the old way: the click takes nothing", click_dot(1), False)
+check("...and the panel says it waits for a gaze",
+      wait(lambda: "isn't sending a gaze" in check_state().get("note", ""), 2), True)
+gazecheck.OWN_GONE = 0.5
+check("now: the dot stands in for the gaze, and the click waiting there takes it",
+      wait(lambda: check_state().get("captured") == 2, 3), True)
+check("...said once in the log", sum("our tracker sends no gaze" in m for m in logs), 1)
+t0, t1, yaw, pitch = eyes_state["points"][-1]
+dot = gazecheck.check_dots("full", True)[1]
+check("ft-eyes got dot 2's direction", (round(yaw, 3), round(pitch, 3)), (round(dot[0], 3), round(dot[1], 3)))
+
+own_gaze(True)
+check("dot 3, ours sends a gaze again: taken on it", click_dot(2) and not check_state().get("run_blind"), True)
+own_gaze(False)
+check("dot 4, gone again: blind once OWN_GONE passes, taken", click_dot(3, gazecheck.OWN_GONE), True)
+t0, t1, yaw, pitch = eyes_state["points"][-1]
+check("its window is the look up to the click (about CHECK_WINDOW)", abs((t1 - t0) - gazecheck.CHECK_WINDOW) < 0.15, True)
+check("still said once in the log", sum("our tracker sends no gaze" in m for m in logs), 1)
+check("all dots: ours fits its calibration", wait(lambda: not svc.checks.check and len(eyes_state["points"]) == DOTS, 5), True)
+check("the fit's reply in the log", any("left 1.00 (4 dots)" in m for m in logs), True)
+
+# A check of our gaze (five) has nothing to check without one: it waits for ours to send, and
+# never goes blind.
+check("five check without our gaze: it waits for ours to send", ask("fivecheck"), "ok waking the eye tracker first")
+check("...and doesn't open meanwhile", wait(lambda: svc.checks.check is not None, 3), False)
+own_gaze(True)
+check("ours sends: the five check opens", wait(lambda: check_state().get("kind") == "five", 6), True)
+own_gaze(False)
+check("its click without our gaze takes nothing", click_dot(0, gazecheck.OWN_GONE), False)
+check("...and it never went blind", (check_state().get("run_blind"), check_state().get("went_blind")), (False, False))
+ask("calquit")
+
+print("FAILED: " + ", ".join(failures) if failures else "all passed", flush=True)
+svc.running = False
+time.sleep(0.7)
+shutil.rmtree(HOME, ignore_errors=True)
+os._exit(1 if failures else 0)

gaze/test/first-calibration-test.py

@@ -49,6 +49,8 @@ gazed.TrackedEye = lambda: lambda now=None: None  # both eyes, whatever SteamVR'
 DOTS = 4
 real_dots = gazecheck.check_dots
 gazecheck.check_dots = lambda kind, own: real_dots(kind, own)[:DOTS]  # a short calibration
+gazecheck.Fusion.MIN = DOTS   # ...whose dots still fit a fusion (SteamVR's eyes at each)
+gazecheck.LOOKED_AWAY = 1e9   # the fake SteamVR's eyes stay put whatever the dot (looked-away-test.py has that check)
 logs = []
 gazed.log = gazecheck.log = lambda msg: logs.append(msg)
 
@@ -61,7 +63,8 @@ while True:
         if not os.read(0, 4096):
             break
     print(json.dumps({"t": time.monotonic(), "src": {"mmap1": {"hy": 1.0, "hp": 2.0, "unc": [0.001, 0.001],
-          "open": [0.8, 0.8]}, "own": {"ok": 0}}}), flush=True)
+          "open": [0.8, 0.8]}, "left": {"hy": 0.0, "hp": 2.0}, "right": {"hy": 2.0, "hp": 2.0},
+          "own": {"ok": 0}}}), flush=True)
 ''')
 SLEEPER = [sys.executable, "-c", "import sys; sys.stdin.read()"]  # quits when its stdin closes
 
@@ -285,6 +288,16 @@ check("the service sees it calibrated", wait(lambda: svc.checks.calibrated() is
 check("and gaze mode stays on", "gaze off" in helper_state["heard"], False)
 check("and no second calibration opens", wait(lambda: svc.checks.check is not None, 3), False)
 check("one calibration in the log", sum(m.startswith("full check:") for m in logs), 1)
+fusion = gazecheck.Fusion.load(gazecheck.FUSION)
+check("SteamVR's eyes at the dots ours took: a fusion saved", (fusion.info.get("dots"), fusion.info.get("how"))
+      if fusion else None, (DOTS, "calibration"))
+dots = [d[:2] for d in real_dots("full", True)[:DOTS]]
+check("its points: SteamVR's eyes' mean, and the dot", [p[:2] for p in fusion.points] if fusion else None,
+      [[1.0, 2.0]] * DOTS)
+check("...the dots", [tuple(round(v, 3) for v in p[2:]) for p in fusion.points] if fusion else None,
+      [tuple(round(v, 3) for v in d) for d in dots])
+check("the service loaded it", wait(lambda: svc.fusion is not None and svc.fusion.ready(), 3), True)
+check("GAZE_FUSION unset: not in use", (svc.fusing, svc.status()["fusion"]["setting"]), (False, "off"))
 
 print("FAILED: " + ", ".join(failures) if failures else "all passed", flush=True)
 svc.running = False

gaze/test/fusion-test.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Offline test of the fusion (gazecal.Fusion, ft-gazed's GAZE_FUSION): SteamVR's affine from
+calibration dots, the clicks' offset per wear, which tracker carries the gaze when, saving and
+loading fusion.json, the setting, and ft-gazed's live gaze with it on. ft-gazed's Service is
+built without its sockets, and HOME is a temp folder, so nothing reaches the live gaze service.
+
+  gaze/test/fusion-test.py
+"""
+import os
+import tempfile
+
+HOME = tempfile.mkdtemp(prefix="ft-fusion-test-")
+os.environ["HOME"] = HOME  # before gazecal: its STATE, and frametop.conf, follow HOME
+
+import importlib.machinery  # noqa: E402
+import importlib.util  # noqa: E402
+import math  # noqa: E402
+import shutil  # noqa: E402
+import sys  # noqa: E402
+from collections import deque  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, ".."))
+from gazecal import EyeWeights, Fusion, GazeLock  # noqa: E402
+
+loader = importlib.machinery.SourceFileLoader("ftgazed", os.path.join(HERE, "..", "ft-gazed"))
+gazed = importlib.util.module_from_spec(importlib.util.spec_from_loader("ftgazed", loader))
+loader.exec_module(gazed)
+
+failures = []
+
+
+def check(what, got, want):
+    if got != want:
+        failures.append(what)
+        print(f"FAIL {what}: got {got!r}, want {want!r}", flush=True)
+    else:
+        print(f"ok   {what}", flush=True)
+
+
+def near(a, b, tol=1e-6):
+    return a is not None and b is not None and all(abs(x - y) < tol for x, y in zip(a, b))
+
+
+# --- gazecal.Fusion ---
+f = Fusion()
+check("not fitted: not ready, no SteamVR gaze", (f.ready(), f.steam_gaze((0, 0), (0, 0))), (False, None))
+# SteamVR's eyes' mean reads 1 degree high everywhere: the affine's offset takes it out
+f.fit([(y, p + 1, y, p) for y in (-20, -10, 0, 10, 20) for p in (-10, 0, 10)], {"how": "test"})
+check("fitted on 15 dots: ready", (f.ready(), f.info["dots"], f.info["how"]), (True, 15, "test"))
+check("an offset: taken out", near(f.steam_gaze((14.0, 6.0), (16.0, 6.0)), (15.0, 5.0)), True)
+check("...leaving nothing on its dots", max(f.misses()) < 1e-6, True)
+# ...and 10 % wide too: the gain is taken out as well without the ridge (with it, a little short:
+# on 2026-10-17's runs it fitted other sittings better)
+wide = Fusion()
+wide.RIDGE = 0.0
+wide.fit([(1.1 * y, 1.1 * p + 1, y, p) for y in (-20, -10, 0, 10, 20) for p in (-10, 0, 10)])
+check("a gain, no ridge: taken out", near(wide.steam_gaze((1.1 * 15 - 1, 1.1 * 5 + 1), (1.1 * 15 + 1, 1.1 * 5 + 1)),
+                                         (15.0, 5.0), 1e-6), True)
+wide.RIDGE = Fusion.RIDGE
+wide.fit(wide.points)
+check("with the ridge: most of it", 0.0 < max(wide.misses()) < 0.6, True)
+check("one SteamVR eye: no gaze from it", f.steam_gaze((1.0, 2.0), None), None)
+check("the mean of the eyes", Fusion.mean((0.0, 2.0), (2.0, 4.0)), (1.0, 3.0))
+
+# Who carries the gaze
+ours, steam = (2.0, 0.0), (0.0, 2.0)
+check("both our eyes and SteamVR's: half and half", f.combine(ours, 2, steam), (1.0, 1.0))
+check("one of our eyes: SteamVR's", f.combine(ours, 1, steam), steam)
+check("none of ours: SteamVR's", f.combine(None, 0, steam), steam)
+check("no SteamVR gaze: ours", f.combine(ours, 1, None), ours)
+check("a share of 1: ours where both are found", f.combine(ours, 2, steam, share=1.0), ours)
+
+# The clicks' offset: per wear, a median, stale clicks left out
+g = Fusion()
+g.fit([(y, p, y, p - 1) for y in (-10, 0, 10) for p in (-10, 0, 10)])   # 1 degree low... corrected
+g.wear = 100.0
+check("no clicks: no offset", g.offset(), (0.0, 0.0))
+check("a click 0.5 off: its miss", round(g.click((0.0, 0.0), (0.0, 0.0), 0.5, -1.0), 3), 0.5)
+check("...and it's the offset", near(g.offset(), (0.5, 0.0)), True)
+check("a click 20 degrees off (a look elsewhere): not taken", (round(g.click((0, 0), (0, 0), 20.0, -1.0), 1),
+                                                              near(g.offset(), (0.5, 0.0))), (20.0, True))
+g.wear = 200.0
+check("the headset on again: the old wear's clicks don't count", g.offset(), (0.0, 0.0))
+check("steam_gaze without the clicks", near(g.steam_gaze((3.0, 3.0), (3.0, 3.0), clicks=False), (3.0, 2.0)), True)
+
+# Saving and loading
+path = Path(HOME) / "fusion.json"
+f.save(path)
+h = Fusion.load(path)
+check("saved and loaded: the same correction", near(h.steam_gaze((5.0, 5.0), (7.0, 5.0)), f.steam_gaze((5.0, 5.0), (7.0, 5.0))),
+      True)
+check("...and its info", (h.info["how"], h.info["dots"], len(h.points)), ("test", 15, 15))
+check("a missing file: None", Fusion.load(Path(HOME) / "none.json"), None)
+path.write_text("{ broken")
+check("a broken file: None", Fusion.load(path), None)
+
+# --- GAZE_FUSION ---
+conf = Path(HOME) / ".config" / "frametop.conf"
+conf.parent.mkdir(parents=True, exist_ok=True)
+check("no frametop.conf: off", gazed.read_fusion(), False)
+for text, want in (("GAZE_FUSION=on\n", True), ("GAZE_FUSION = ON  # yes\n", True), ("GAZE_FUSION=off\n", False),
+                   ("GAZE_FUSION=yes\n", False), ("# GAZE_FUSION=on\n", False), ("GAZE_TRACKER=own\n", False)):
+    conf.write_text(text)
+    check(f"frametop.conf {text.strip()!r}", gazed.read_fusion(), want)
+
+
+# --- ft-gazed's live gaze: the parts of Service the samples go through, no sockets ---
+def service(fusion_on=True, one=None):
+    svc = gazed.Service.__new__(gazed.Service)
+    svc.override, svc.tracker, svc.source, svc.one_eye = None, "own", "mmap1", one
+    svc.counts = dict.fromkeys(("samples", "sent", "blinks", "one_eye", "one_eye_used", "lost_left", "lost_right",
+                                "looking_down", "dropped", "fused", "steam_only"), 0)
+    svc.opens, svc.lost = (deque(maxlen=90), deque(maxlen=90)), [False, False]
+    svc.fix, svc.last_sample, svc.low_until = GazeLock(radius=1.0), 0.0, [0.0, 0.0]
+    svc.bridge = gazed.EyeBridge()
+    svc.weights = {"own": EyeWeights()}
+    svc.fusion_on = fusion_on
+    svc.fusion = Fusion()
+    svc.fusion.fit([(y, p + 1, y, p) for y in (-10, 0, 10) for p in (-10, 0, 10)])   # SteamVR 1 degree high
+    svc.checks = type("Checks", (), {"active": False, "pending": None})()
+    svc.sent = []
+    svc.send = lambda t, hy, hp, rhy, rhp, eyes: svc.sent.append((round(hy, 3), round(hp, 3), eyes))
+    return svc
+
+
+def feed(svc, n=30, own_eyes=((4.0, 2.0), (4.0, 2.0)), steam=True, opens=(0.8, 0.8), unc=(0.001, 0.001)):
+    for i in range(n):
+        src = {"mmap1": {"unc": list(unc), "open": list(opens)},
+               "own": {"hy": 4.0, "hp": 2.0, "eyes": [list(e) if e else None for e in own_eyes]}}
+        if steam:
+            src["left"], src["right"] = {"hy": 1.0, "hp": 3.0}, {"hy": 3.0, "hp": 3.0}   # mean (2, 3): corrected (2, 2)
+        svc.on_eyes_sample({"t": i / 90, "src": src}, True)
+
+
+svc = service()
+check("fusing with our tracker, on, and fitted", svc.fusing, True)
+check("ft-gaze prints SteamVR's eyes too", svc.wanted_sources(), "own,mmap1,left,right")
+feed(svc)
+check("both our eyes: half ours (4, 2), half SteamVR's corrected (2, 2)", svc.sent[-1][:2], (3.0, 2.0))
+check("...counted as fused", (svc.counts["fused"], svc.counts["steam_only"]), (30, 0))
+check("...and the eyes sent with it are ours (for lessons)", svc.sent[-1][2], [(4.0, 2.0), (4.0, 2.0)])
+svc = service()
+feed(svc, own_eyes=((4.0, 2.0), None))
+check("one of our eyes: SteamVR's", svc.sent[-1][:2], (2.0, 2.0))
+check("...counted", (svc.counts["steam_only"], svc.counts["one_eye"]), (30, 30))
+svc = service()
+feed(svc, own_eyes=(None, None))
+check("neither of ours: SteamVR's carries it", (len(svc.sent), svc.sent[-1][:2] if svc.sent else None), (30, (2.0, 2.0)))
+svc = service()
+feed(svc, steam=False)
+check("SteamVR's eyes missing: ours", svc.sent[-1][:2], (4.0, 2.0))
+svc = service()
+feed(svc, n=60, unc=(0.02, 0.001))
+check("SteamVR lost its left eye: ours", svc.sent[-1][:2], (4.0, 2.0))
+svc = service()
+feed(svc, n=60, opens=(0.0, 0.0))
+check("a blink (both lids down): nothing", (svc.sent, svc.counts["blinks"]), ([], 60))
+svc = service(one=1)
+feed(svc)
+check("SteamVR tracking one eye: no fusion", (svc.sent[-1][:2], svc.counts["fused"]), ((4.0, 2.0), 0))
+svc = service(fusion_on=False)
+check("GAZE_FUSION off: not fusing, SteamVR's eyes not asked for", (svc.fusing, svc.wanted_sources()),
+      (False, "own,mmap1"))
+feed(svc)
+check("...ours alone", svc.sent[-1][:2], (4.0, 2.0))
+svc = service()
+svc.fusion = Fusion()
+check("no fitted fusion: not fusing", svc.fusing, False)
+svc = service()
+svc.tracker = "steam"
+svc.models = {name: gazed.Correction() for name in gazed.SOURCES}
+check("SteamVR's tracker: no fusion", svc.fusing, False)
+
+shutil.rmtree(HOME, ignore_errors=True)
+print("FAILED: " + ", ".join(failures) if failures else "all passed")
+sys.exit(1 if failures else 0)

gaze/test/gaze-lock-test.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Offline test of the fixation lock on the gaze's direction in the room (gazecal.GazeLock) and
+of ft-gazed's blink settle for our tracker (BLINK_SETTLE). Made-up samples only: ft-gazed's
+Service is built without its sockets, so nothing reaches the live gaze service.
+
+  gaze/test/gaze-lock-test.py
+"""
+import importlib.machinery
+import importlib.util
+import math
+import os
+import random
+import sys
+from collections import deque
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, ".."))
+from gazecal import EyeWeights, Fixation, GazeLock, angles, direction, rotate  # noqa: E402
+
+loader = importlib.machinery.SourceFileLoader("ftgazed", os.path.join(HERE, "..", "ft-gazed"))
+gazed = importlib.util.module_from_spec(importlib.util.spec_from_loader("ftgazed", loader))
+loader.exec_module(gazed)
+
+failures = []
+
+
+def check(what, ok, detail=""):
+    if not ok:
+        failures.append(what)
+        print(f"FAIL {what} {detail}", flush=True)
+
+
+def head(yaw, pitch=0.0, roll=0.0):
+    """A head pose's quaternion [w, x, y, z]: yaw about +Y (left), then pitch about +X (up), then
+    roll about -Z, as a headset's pose matrix would give."""
+    def q(axis, deg):
+        h = math.radians(deg) / 2
+        return [math.cos(h)] + [math.sin(h) * a for a in axis]
+
+    def mul(a, b):
+        w1, x1, y1, z1 = a
+        w2, x2, y2, z2 = b
+        return [w1 * w2 - x1 * x2 - y1 * y2 - z1 * z2, w1 * x2 + x1 * w2 + y1 * z2 - z1 * y2,
+                w1 * y2 - x1 * z2 + y1 * w2 + z1 * x2, w1 * z2 + x1 * y2 - y1 * x2 + z1 * w2]
+    return mul(mul(q((0, 1, 0), yaw), q((1, 0, 0), pitch)), q((0, 0, -1), roll))
+
+
+def room(q, yaw, pitch):
+    """Where a head-relative gaze points in the room, as (yaw, pitch)."""
+    return angles(rotate(q, direction(yaw, pitch)))
+
+
+def head_rel(q, ryaw, rpitch):
+    return angles(rotate(q, direction(ryaw, rpitch), inverse=True))
+
+
+def off(a, b):
+    return math.degrees(math.acos(max(-1.0, min(1.0, sum(x * y for x, y in zip(direction(*a), direction(*b)))))))
+
+
+# --- The conventions: ft-gaze's Direction and Angles, and the quaternion as a pose rotation
+check("straight ahead is -Z", direction(0, 0) == (-0.0, 0.0, -1.0), direction(0, 0))
+check("yaw turns left (-X), pitch looks up", direction(90, 0)[0] < -0.99 and direction(0, 90)[1] > 0.99)
+rng = random.Random(1)
+worst = 0.0
+for _ in range(500):
+    q = head(rng.uniform(-180, 180), rng.uniform(-60, 60), rng.uniform(-30, 30))
+    y, p = rng.uniform(-50, 50), rng.uniform(-40, 40)
+    back = head_rel(q, *room(q, y, p))
+    worst = max(worst, abs(back[0] - y), abs(back[1] - p))
+check("into the room and back", worst < 1e-9, worst)
+check("a head turned 30 deg left, eyes ahead: the room's 30 left", max(map(abs, (room(head(30), 0, 0)[0] - 30,
+                                                                              room(head(30), 0, 0)[1]))) < 1e-9)
+check("a head pitched 10 up, eyes 5 up: the room's 15 up", abs(room(head(0, 10), 0, 5)[1] - 15) < 1e-9)
+
+# --- A look at a spot in the room while the head turns (the eyes turn the other way)
+def turning(speed, lock, poses=True, noise=0.05, seconds=2.0):
+    """The pointer's place in the room (drawn with the newest head, as the helper does) while the
+    eyes hold room yaw 10, pitch 5 and the head turns at `speed` deg/s: the worst miss, and the
+    jumps over 0.5 deg between samples."""
+    rng = random.Random(2)
+    worst, jumps, last = 0.0, 0, None
+    for i in range(int(90 * seconds)):
+        t = i / 90
+        q = head(-20 + speed * t, 3.0, 2.0)
+        hy, hp = head_rel(q, 10.0 + rng.gauss(0, noise), 5.0 + rng.gauss(0, noise))
+        if isinstance(lock, GazeLock):
+            out = lock(hy, hp, t, q if poses else None, q if poses else None)
+        else:
+            out = lock(hy, hp, t, 1.0)
+        at = room(q, *out)
+        if i >= 3:
+            worst = max(worst, off(at, (10.0, 5.0)))
+            jumps += last is not None and off(at, last) > 0.5
+        last = at
+    return worst, jumps
+
+
+w, j = turning(20, GazeLock())
+check("room lock, head turning 20 deg/s: the pointer stays on the spot", w < 0.3 and j == 0, (w, j))
+w, j = turning(60, GazeLock())
+check("room lock, head turning 60 deg/s: still on it", w < 0.3 and j == 0, (w, j))
+w, j = turning(20, Fixation(1.0))
+check("the head-relative lock rides along and snaps back (why the room lock)", w > 0.8 and j >= 10, (w, j))
+w, j = turning(20, GazeLock(), poses=False)
+check("no poses (an older ft-gaze): the head-relative lock", w > 0.8 and j >= 10, (w, j))
+
+# A look elsewhere moves it at once (two samples), and a still head is as before
+lock = GazeLock()
+q = head(15, -5, 1)
+for i in range(30):
+    out = lock(2.0, 1.0, i / 90, q, q)
+check("still: the look", off(out, (2.0, 1.0)) < 1e-6, out)
+lock(20.0, 1.0, 30 / 90, q, q)
+out = lock(20.0, 1.0, 31 / 90, q, q)
+check("a saccade: there after two samples", off(out, (20.0, 1.0)) < 1e-6, out)
+one = lock(2.0, 1.0, 32 / 90, q, q)
+check("one stray sample is held off", off(one, (20.0, 1.0)) < 1e-6, one)
+fix, lock2 = Fixation(1.0), GazeLock()
+same = 0.0
+for i in range(200):
+    y, p = 3 + 0.3 * math.sin(i / 7), -2 + 0.3 * math.cos(i / 5)
+    a, b = fix(y, p, i / 90, 1.0), lock2(y, p, i / 90, q, q)
+    same = max(same, off(a, b))
+check("a still head: as the head-relative lock", same < 0.02, same)
+lock2(3, -2, 3.0, q, q)
+lock2(3, -2, 3.1, None, None)
+check("switching to no poses starts over", lock2.count == 0 and lock2.head.count == 1)
+# Newest pose differs from the sample's: the room direction is kept, re-expressed in the newest head
+lock3 = GazeLock()
+then, now = head(0), head(4)
+out = lock3(10.0, 0.0, 0.0, then, now)
+check("drawn with the newest head", abs(out[0] - 6.0) < 1e-9 and abs(out[1]) < 1e-9, out)
+
+
+# --- ft-gazed's own path: an eye stays out for BLINK_SETTLE after its lids came down
+def service():
+    svc = gazed.Service.__new__(gazed.Service)
+    svc.override, svc.tracker, svc.source, svc.one_eye = None, "own", "mmap1", None
+    svc.counts = dict.fromkeys(("samples", "sent", "blinks", "one_eye", "one_eye_used", "lost_left", "lost_right",
+                                "looking_down", "dropped"), 0)
+    svc.opens, svc.lost = (deque(maxlen=90), deque(maxlen=90)), [False, False]
+    svc.fix, svc.last_sample, svc.low_until = GazeLock(radius=1.0), 0.0, [0.0, 0.0]
+    svc.bridge = gazed.EyeBridge()
+    svc.weights = {"own": EyeWeights()}
+    svc.sent = []
+    svc.send = lambda t, hy, hp, rhy, rhp, eyes: svc.sent.append((t, hy, hp))
+    return svc
+
+
+def blink(settle):
+    """The right eye's lids down for 3 samples, and its pupil found wrong (30, -20) for 3 more
+    after they're up: the gaze sent from 60 on."""
+    saved = gazed.BLINK_SETTLE
+    gazed.BLINK_SETTLE = settle
+    try:
+        svc = service()
+        q = head(0)
+        for i in range(120):
+            closing = 60 <= i < 63
+            right = [30.0, -20.0] if 60 <= i < 66 else [6.0, 2.0]
+            svc.on_eyes_sample({"t": i / 90, "head": {"q": q}, "src": {
+                "mmap1": {"unc": [0.001, 0.001], "open": [0.8, 0.0 if closing else 0.8]},
+                "own": {"hy": 5.0, "hp": 2.0, "hq": q, "eyes": [[4.0, 2.0], right]}}}, True)
+    finally:
+        gazed.BLINK_SETTLE = saved
+    return svc, [s for s in svc.sent if s[0] >= 60 / 90]
+
+
+svc, sent = blink(gazed.BLINK_SETTLE)
+worst = max(off(s[1:], (5.0, 2.0)) for s in sent)
+check("settle: the bad finds after the lids came up don't reach the pointer", worst < 1.1, worst)
+check("settle: then both eyes again", off(sent[-1][1:], (5.0, 2.0)) < 0.2, sent[-1])
+check("settle: counted as one-eye samples", svc.counts["one_eye"] >= 6, svc.counts)
+_, sent = blink(0.0)
+worst = max(off(s[1:], (5.0, 2.0)) for s in sent)
+check("without it, they do (the test's control)", worst > 5, worst)
+
+print("FAILED: " + ", ".join(failures) if failures else "all passed")
+sys.exit(1 if failures else 0)

gaze/test/looked-away-test.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Offline test of the full calibration's looked-away check (gaze/gazecheck.py, Checks.looked_away):
+a dot for our tracker where SteamVR's two eyes were more than LOOKED_AWAY from it, past their
+usual offset in that calibration, isn't taken, and ft-eyes isn't asked. Live 2026-10-18: the
+palm menu opened the Steam menu mid-calibration, and three dots were taken 17-35 degrees from
+where the user looked (both trackers agreed). A SteamVR that is off by itself (its eyes in one
+place whatever the dot) mustn't block the calibration: past AWAY_GIVE_UP dots in a row, the
+check stops.
+
+Drives Checks.capture with synthetic looks and a fake service: nothing reaches the live gaze
+service, the pointer helper, ft-eyes, or SteamVR. HOME is a temp folder (checks.jsonl goes there).
+
+  gaze/test/looked-away-test.py
+"""
+import os
+import tempfile
+
+HOME = tempfile.mkdtemp(prefix="ft-gaze-looked-away-test-")
+os.environ["HOME"] = HOME  # before gazecal: its STATE follows HOME
+
+import selectors  # noqa: E402
+import shutil  # noqa: E402
+import sys  # noqa: E402
+import types  # noqa: E402
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+import gazecheck  # noqa: E402
+
+tag = f"ft_gaze_looked_away_test_{os.getpid()}"
+gazecheck.PANEL = f"\0{tag}_panel"
+gazecheck.POINTER = f"\0{tag}_helper"
+gazecheck.EYES = f"\0{tag}_eyes"
+logs = []
+gazecheck.log = lambda msg: logs.append(msg)
+
+failures = []
+
+
+def check(label, got, want):
+    ok = got == want
+    print(f"{'ok  ' if ok else 'FAIL'}  {label}" + ("" if ok else f": got {got!r}, want {want!r}"), flush=True)
+    if not ok:
+        failures.append(label)
+
+
+class Weights:
+    def add(self, miss):
+        pass
+
+
+svc = types.SimpleNamespace(one_eye=None, weights={"own": Weights(), "steam": Weights()})
+checks = gazecheck.Checks(svc, selectors.DefaultSelector())
+asked = []
+checks.ask_eyes = lambda command, timeout, done: asked.append(command)
+DOTS = gazecheck.check_dots("full", True)
+
+
+def new_check():
+    checks.check = {"kind": "full", "own": True, "dots": DOTS, "i": 0, "tries": 0, "skipped": 0, "captured": 0,
+                    "points": {}, "reasons": {}, "fit_reasons": set(), "note": "", "blind": False, "fusion": [],
+                    "away_dots": [], "away_off": False, "steam_offsets": []}
+
+
+def look(at, steam_off=(0.0, 0.0), n=30):
+    """A look at `at` (yaw, pitch) by SteamVR's eyes (each this far from it, plus steam_off), our
+    tracker's at the dot: the capture window as on_sample keeps it."""
+    y, p = at[0] + steam_off[0], at[1] + steam_off[1]
+    src = {"mmap1": {"unc": [0.001, 0.001], "open": [0.8, 0.8]}, "left": {"hy": y - 1.0, "hp": p},
+           "right": {"hy": y + 1.0, "hp": p}, "own": {"ok": 1, "eyes": [list(at), list(at)]}}
+    return [(0.0, {"t": 100.0 + k / 90, "src": src}, y, p) for k in range(n)]
+
+
+def capture(i, at, steam_off=(0.0, 0.0)):
+    """Dot i shown, a click while the eyes are at `at`: was ft-eyes asked (the check let it go on)?"""
+    c = checks.check
+    c["i"], c["done_at"] = i, None
+    before = len(asked)
+    checks.capture(look(at, steam_off))
+    return len(asked) > before
+
+
+def answer_ok():
+    """ft-eyes takes the dot it was asked about (point_done's own path, with "ok")."""
+    c = checks.check
+    yaw, pitch, rnd = c["dots"][c["i"]]
+    rec = {"true": [yaw, pitch], "steam": [(yaw, pitch), (yaw, pitch)], "own": True}
+    checks.point_done(rec, [0.0, 0.0], "ok")
+
+
+# Looking at the dots: each taken, as before.
+new_check()
+for i in range(3):
+    check(f"dot {i + 1}: looking at it, ft-eyes is asked", capture(i, DOTS[i][:2]), True)
+    answer_ok()
+check("no notes for those", checks.check["note"], "")
+
+# Looking 25 degrees off (the Steam menu, mid-calibration): not taken, and the panel says why.
+dot = DOTS[3][:2]
+check("dot 4: looked 25 degrees away: ft-eyes isn't asked", capture(3, dot, (25.0, 0.0)), False)
+check("...the panel says why", "looked away" in checks.check["note"], True)
+check("...and the dot stays for another try", (checks.check["i"], checks.check["tries"]), (3, 1))
+check("...the reason is counted", checks.check["reasons"], {"you looked away from the dot (by SteamVR's eyes)": 1})
+check("dot 4, second try, looking at it: taken", capture(3, dot), True)
+answer_ok()
+
+# 14 degrees off: under LOOKED_AWAY, taken (SteamVR's own error at the corners reached 9 live).
+check("dot 5: 14 degrees off: taken", capture(4, DOTS[4][:2], (0.0, 14.0)), True)
+answer_ok()
+
+# A SteamVR that is off by itself, 20 degrees at every dot: the usual offset counts once it has
+# AWAY_OFFSET_MIN dots, so every dot is taken.
+new_check()
+for i in range(gazecheck.AWAY_OFFSET_MIN):
+    capture(i, DOTS[i][:2], (3.0, 0.0))   # a small offset first: these are taken
+    answer_ok()
+check("its usual offset in this calibration is learned", len(checks.check["steam_offsets"]), gazecheck.AWAY_OFFSET_MIN)
+check("then 18.5 degrees the same way: 15.5 past the usual 3, refused",
+      capture(3, DOTS[3][:2], (18.5, 0.0)), False)
+check("and 14 degrees the same way: taken (11 past the usual 3)", capture(3, DOTS[3][:2], (14.0, 0.0)), True)
+answer_ok()
+
+# A SteamVR off by 20 degrees from the start: the first dots are refused, then the check stops
+# (AWAY_GIVE_UP dots in a row) and the rest are taken.
+new_check()
+logs.clear()
+check("SteamVR 20 degrees off, dot 1: refused", capture(0, DOTS[0][:2], (20.0, 0.0)), False)
+check("dot 1, second try: refused, and skipped", (capture(0, DOTS[0][:2], (20.0, 0.0)), checks.check["skipped"]),
+      (False, 1))
+check("dot 2: refused", capture(1, DOTS[1][:2], (20.0, 0.0)), False)
+check("dot 2 again: refused, and skipped", (capture(1, DOTS[1][:2], (20.0, 0.0)), checks.check["skipped"]), (False, 2))
+check("dot 3: a third dot in a row: SteamVR is off, taken", capture(2, DOTS[2][:2], (20.0, 0.0)), True)
+check("...and the log says the check is off", any("looked-away check is off" in m for m in logs), True)
+answer_ok()
+check("dot 4: taken (the check stays off)", capture(3, DOTS[3][:2], (20.0, 0.0)), True)
+
+# Our tracker alone without SteamVR's eyes (one eye tracked, or SteamVR lost them): no check.
+new_check()
+svc.one_eye = 0
+check("one eye tracked by SteamVR: no check, 30 degrees off is taken", capture(0, DOTS[0][:2], (30.0, 0.0)), True)
+svc.one_eye = None
+
+# The reason's words, for the note and a failed calibration's status.
+check("reject_reason for it", gazecheck.reject_reason("looked away (25 deg by SteamVR)", None),
+      ("looked away", "you looked away from the dot (by SteamVR's eyes)", False))
+
+print("FAILED: " + ", ".join(failures) if failures else "all passed", flush=True)
+shutil.rmtree(HOME, ignore_errors=True)
+sys.exit(1 if failures else 0)

gaze/test/mmap-layout-test.cpp

@@ -162,6 +162,40 @@ void NoMapping() {
     CHECK(f.eyes.Counter() == f.n);
 }
 
+// QuatJson (the head poses printed for the gaze service's room lock): for poses turned every
+// way, including past 90 degrees where each of its four branches is taken, the quaternion turns
+// vectors as the pose matrix does.
+void Quaternions() {
+    auto axis = [](Vec3 a, double deg) {  // a rotation matrix about unit axis a
+        vr::HmdMatrix34_t m{};
+        const Vec3 cols[3] = {RotateAbout({1, 0, 0}, a, deg * M_PI / 180), RotateAbout({0, 1, 0}, a, deg * M_PI / 180),
+                              RotateAbout({0, 0, 1}, a, deg * M_PI / 180)};
+        for (int c = 0; c < 3; ++c) m.m[0][c] = cols[c].x, m.m[1][c] = cols[c].y, m.m[2][c] = cols[c].z;
+        return m;
+    };
+    double worst = 0;
+    int n = 0;
+    for (int ax = 0; ax < 7; ++ax) {
+        const Vec3 a = Normalize(Vec3{double(ax & 1), double((ax >> 1) & 1), double((ax >> 2) & 1)} +
+                                 Vec3{0.1 * ax, -0.07 * ax, 0.05});
+        for (double deg = -179; deg <= 180; deg += 23) {
+            const vr::HmdMatrix34_t m = axis(a, deg);
+            double q[4];
+            CHECK(std::sscanf(QuatJson(m).c_str(), "[%lf,%lf,%lf,%lf]", &q[0], &q[1], &q[2], &q[3]) == 4);
+            const Vec3 u{q[1], q[2], q[3]};
+            for (const Vec3 v : {Vec3{0, 0, -1}, Vec3{1, 0, 0}, Vec3{0.3, 0.8, -0.5}}) {
+                const Vec3 c = Cross(u, v);
+                const Vec3 byQ = v + c * (2 * q[0]) + Cross(u, c) * 2;
+                worst = std::max(worst, Length(byQ - Rotate(m, v)));
+            }
+            ++n;
+        }
+    }
+    CHECK(n > 100);
+    CHECK(worst < 1e-5);
+    if (worst >= 1e-5) std::printf("quaternion off by %g\n", worst);
+}
+
 }  // namespace
 
 int main() {
@@ -171,6 +205,7 @@ int main() {
     TornWrite();
     ReadsTheLayoutFound();
     NoMapping();
+    Quaternions();
     if (failures) {
         std::printf("%d failed\n", failures);
         return 1;

gaze/test/one-eye-calibration-test.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Offline test of our tracker with one eye lost (2026-10-18): a calibration dot is taken with
+the eye that was seen when the other wasn't (ft-eyes calib-point), each eye is fitted on its
+own dots and an eye seen at too few is left out (calib-fit, eyes_model.Calibration.fit), and
+ft-gazed eases the step when an eye drops out (gazecal.EyeBridge). A second person's eyes each
+lost the pupil looking 20 degrees outward, so until now their outer dots failed, and the rest
+fitted both eyes from the middle only.
+
+Pupil positions are written into ft-eyes' eye histories as its frames would leave them: no
+cameras, SteamVR or live gaze service. Needs the tracker's Python (numpy, OpenCV).
+
+  scripts/in-box /opt/frametop/venv/bin/python gaze/test/one-eye-calibration-test.py
+"""
+import importlib.machinery
+import importlib.util
+import json
+import math
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HOME = tempfile.mkdtemp(prefix="ft-eyes-one-eye-test-")
+os.environ.update(HOME=HOME, FT_EYES_CAMS="/nonexistent", FT_EYES_STATE=os.path.join(HOME, "eyes"),
+                  FT_EYES_MODEL="classic")
+GAZE = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(GAZE))
+sys.path.insert(0, str(GAZE / "tracker"))
+
+import gazecheck  # noqa: E402
+from gazecal import EyeBridge, EyeWeights, GazeLock  # noqa: E402
+
+loader = importlib.machinery.SourceFileLoader("fteyes", str(GAZE / "tracker" / "ft-eyes"))
+fe = importlib.util.module_from_spec(importlib.util.spec_from_loader(loader.name, loader))
+loader.exec_module(fe)
+loader = importlib.machinery.SourceFileLoader("ftgazed", str(GAZE / "ft-gazed"))
+gazed = importlib.util.module_from_spec(importlib.util.spec_from_loader(loader.name, loader))
+loader.exec_module(gazed)
+
+failures = []
+
+
+def check(what, got, want):
+    ok = got == want
+    print(f"{'ok  ' if ok else 'FAIL'}  {what}" + ("" if ok else f": got {got!r}, want {want!r}"), flush=True)
+    if not ok:
+        failures.append(what)
+
+
+DOTS = [d[:2] for d in gazecheck.check_dots("full", True)]   # 27 dots, out to +-20
+CENTRE = {0: (300.0, 200.0), 1: (330.0, 205.0)}               # right, left: pupil looking ahead
+
+
+def pupil(eye, yaw, pitch):
+    """Where an eye's pupil sits for a gaze: 4 px a degree, yaw +left moves it to lower x."""
+    x0, y0 = CENTRE[eye]
+    return x0 - 4.0 * yaw + 0.02 * yaw * pitch, y0 - 4.0 * pitch
+
+
+class Clock:
+    t = 100.0
+
+
+def look(tracker, yaw, pitch, seen=(0, 1), jitter=()):
+    """Half a second at a dot: 45 frames per eye that's seen (jitter: those that jump about),
+    then calib-point over that window."""
+    t0 = Clock.t
+    for i in range(45):
+        t = t0 + i / 90
+        for e in tracker.eyes:
+            if e.eye not in seen:
+                continue
+            x, y = pupil(e.eye, yaw, pitch)
+            if e.eye in jitter:
+                x += 0.5 * (i - 22)   # drifting: half its frames over 5.5 px from the middle
+            e.history.append((t, x, y, math.nan, math.nan))
+    Clock.t = t0 + 1.0
+    return tracker.command(f"calib-point {t0:.6f} {t0 + 0.5:.6f} {yaw:.4f} {pitch:.4f}")
+
+
+def outward_lost(yaw):
+    """The second person: the right eye lost looking 14+ degrees right (yaw -), the left 14+ left."""
+    return tuple(e for e in (0, 1) if not (e == 0 and yaw <= -14 or e == 1 and yaw >= 14))
+
+
+# --- calib-point: one eye is enough for a dot ---
+tracker = fe.Tracker()
+check("calib-start", tracker.command("calib-start"), "ok")
+r = look(tracker, 0.0, 0.0)
+check("both eyes seen: taken", r.split()[:3], ["ok", "45", "45"])
+check("...with no note", "only" in r, False)
+r = look(tracker, -20.0, 0.0, seen=(1,))
+check("right eye lost: taken with the left", r.startswith("ok 0 45"), True)
+check("...and says so", r.endswith("(left eye only: the right eye was seen in only 0 frames)"), True)
+check("...the dot holds the left eye alone", sorted(tracker.dots[-1]["eye"]), [1])
+r = look(tracker, 10.0, 0.0, jitter=(1,))
+check("left eye jumping about: taken with the right", "(right eye only: the left eye moved" in r, True)
+check("...the dot holds the right eye alone", sorted(tracker.dots[-1]["eye"]), [0])
+n = len(tracker.dots)
+r = look(tracker, 0.0, 10.0, seen=())
+check("neither eye seen: not taken", r, "fail neither eye was seen enough (right 0 frames, left 0 frames)")
+r = look(tracker, 0.0, 10.0, jitter=(0, 1))
+check("both moved: not taken, as before", r, "fail the right eye moved (5.5 px)")
+r = look(tracker, 0.0, 10.0, seen=(1,), jitter=(1,))
+check("one lost and the other moved: the move is the reason", r, "fail the left eye moved (5.5 px)")
+check("...none of those kept", len(tracker.dots), n)
+
+# The panel's words for them (gazecheck.reject_reason).
+check("reject_reason: neither eye", gazecheck.reject_reason(
+    "fail neither eye was seen enough (right 3 frames, left 0 frames)", None),
+    ("eyes not seen", "our tracker saw neither eye well enough", True))
+check("reject_reason: one eye moved, as before", gazecheck.reject_reason("fail the left eye moved (12.0 px)", None),
+      ("left eye moved", "your left eye moved while you looked", False))
+
+# --- calib-fit: a full calibration where each eye is lost looking outward ---
+tracker = fe.Tracker()
+tracker.command("calib-start")
+for yaw, pitch in DOTS:
+    look(tracker, yaw, pitch, seen=outward_lost(yaw))
+seen = {c: sum(1 for k in tracker.dots if c in k["eye"]) for c in (0, 1)}
+check("all 27 dots taken", len(tracker.dots), 27)
+check("each eye at the dots it was seen at", seen, {0: 22, 1: 22})
+r = tracker.command("calib-fit")
+check("fitted", r.startswith("ok 27 dots, fit median 0.0"), True)
+check("...each eye's dots in the reply", r.endswith("(22 dots)") and "(22 dots), left 0.0" in r, True)
+check("both eyes mapped", tracker.status()["mapped"], ["right", "left"])
+check("...the dots per eye saved with it", tracker.cal.info["eye_dots"], {"right": 22, "left": 22})
+right, left = tracker.eyes
+check("each eye calibrated", (right.cal is not None, left.cal is not None), (True, True))
+g = tracker.cal.gaze(1, *pupil(1, -20.0, 0.0))
+check("the left eye at 20 right (only it saw that dot): on it", (round(g[0], 1), round(g[1], 1)), (-20.0, 0.0))
+rows = [json.loads(x) for x in open(fe.CALIBRATION.with_name("calibration-dots.jsonl"))]
+check("calibration-dots.jsonl keeps the one-eye dots", sorted(len(x["eye"]) for x in rows)[:4], [1, 1, 1, 1])
+check("...and its spreads come back from them", sorted(fe.spread_from_dots(tracker.cal)), [0, 1])
+loaded = fe.eyes_model.Calibration.load(fe.CALIBRATION)
+check("the saved calibration maps both", loaded.eyes(), [0, 1])
+
+# --- calib-fit with one eye seen at too few dots: the other alone ---
+tracker = fe.Tracker()
+tracker.command("calib-start")
+for i, (yaw, pitch) in enumerate(DOTS):
+    look(tracker, yaw, pitch, seen=(1,) if i % 3 else (0, 1))   # the right eye at 9 of 27
+r = tracker.command("calib-fit")
+check("right eye at 9 dots: fitted with the left alone", r.endswith("(27 dots)")
+      and "right not used (9 dots, needs 12)" in r, True)
+check("...the left mapped only", tracker.status()["mapped"], ["left"])
+right, left = tracker.eyes
+check("...the right eye gives no gaze", (right.cal, left.cal is not None), (None, True))
+check("...a click teaches the left only", tracker.command(f"click {Clock.t:.6f} 0 0").split()[1:3], ["nan", "nan"])
+fresh = fe.Tracker()
+check("...and a restart says so", (fresh.cal.eyes(), fresh.eyes[0].cal), ([1], None))
+
+# --- calib-fit with too few dots for either eye ---
+tracker = fe.Tracker()
+tracker.command("calib-start")
+for i, (yaw, pitch) in enumerate(DOTS[:14]):
+    look(tracker, yaw, pitch, seen=(0,) if i % 2 else (1,))
+r = tracker.command("calib-fit")
+check("7 dots each: no calibration", r, "fail neither eye was seen at enough dots (right 7, left 7; need 12)")
+check("...the last one stays", fe.eyes_model.Calibration.load(fe.CALIBRATION).eyes(), [1])
+
+# --- gazecal.EyeBridge: no jump when an eye drops out ---
+b = EyeBridge()
+for i in range(90):   # both eyes, a degree apart: their mean is the gaze
+    out = b(i / 90, [(4.0, 2.0), (6.0, 2.0)], (5.0, 2.0))
+check("both eyes: the combined gaze", out, (5.0, 2.0))
+t = 1.0
+out = b(t, [None, (6.0, 2.0)], (6.0, 2.0))
+check("the left drops out: the gaze stays put", (abs(out[0] - 5.0) < 0.05, out[1]), (True, 2.0))
+out = b(t + 0.3, [None, (6.0, 2.0)], (6.0, 2.0))
+check("...eases toward the right eye", 5.5 < out[0] < 5.8, True)
+out = b(t + 2.0, [None, (6.0, 2.0)], (6.0, 2.0))
+check("...and is the right eye's after 2 s", round(out[0], 2), 6.0)
+out = b(t + 2.1, [(4.0, 2.0), (6.0, 2.0)], (5.0, 2.0))
+check("both back: the combined gaze", out, (5.0, 2.0))
+check("no eyes learned yet: as it comes", EyeBridge()(0.0, [None, (6.0, 2.0)], (6.0, 2.0)), (6.0, 2.0))
+
+
+# --- ft-gazed's own path uses it ---
+def service():
+    svc = gazed.Service.__new__(gazed.Service)
+    svc.override, svc.tracker, svc.source, svc.one_eye = None, "own", "mmap1", None
+    svc.models = {name: gazed.Correction() for name in gazed.SOURCES}
+    svc.counts = dict.fromkeys(("samples", "sent", "blinks", "one_eye", "one_eye_used", "lost_left", "lost_right",
+                                "looking_down", "dropped"), 0)
+    from collections import deque
+    svc.opens, svc.vergence = (deque(maxlen=90), deque(maxlen=90)), deque(maxlen=90)
+    svc.lost, svc.bad_at, svc.fallback = [False, False], [0.0, 0.0], gazed.EyeFallback()
+    svc.fix, svc.last_sample, svc.low_until = GazeLock(radius=1.0), 0.0, [0.0, 0.0]
+    svc.bridge = EyeBridge()
+    svc.fix = lambda gy, gp, t, then, q: (gy, gp)   # what goes into the lock
+    svc.weights, svc.fusion_on, svc.fusion = {"own": EyeWeights()}, False, None
+    svc.sent = []
+    svc.send = lambda t, hy, hp, rhy, rhp, eyes: svc.sent.append((round(hy, 2), round(hp, 2)))
+    return svc
+
+
+svc = service()
+for i in range(90):
+    svc.on_eyes_sample({"t": i / 90, "src": {"mmap1": {"unc": [0.001, 0.001], "open": [0.8, 0.8]},
+                                             "own": {"hy": 5.0, "hp": 2.0, "eyes": [[4.0, 2.0], [6.0, 2.0]]}}}, True)
+svc.on_eyes_sample({"t": 1.0, "src": {"mmap1": {"unc": [0.001, 0.001], "open": [0.8, 0.8]},
+                                      "own": {"hy": 6.0, "hp": 2.0, "eyes": [None, [6.0, 2.0]]}}}, True)
+check("ft-gazed, our tracker: both eyes, then the left lost: no jump",
+      (svc.sent[-2], abs(svc.sent[-1][0] - 5.0) < 0.05), ((5.0, 2.0), True))
+check("...counted as one eye", svc.counts["one_eye"], 1)
+
+
+# --- a new calibration starts the eye weights over (ft-gazed's note_own_calibration) ---
+logs = []
+gazed.log = lambda msg: logs.append(msg)
+svc = service()
+svc.bias, svc.own_made, svc.dirty = "auto", None, False
+svc.own = {"calibration": {"made": "2026-10-18 20:58:26", "dots": 27}}
+svc.note_own_calibration()
+check("the first calibration it hears of: adopted, nothing dropped", (svc.own_made, logs), ("2026-10-18 20:58:26", []))
+for _ in range(6):
+    svc.weights["own"].add([2.0, 0.5])   # the left eye's mapping was the worse one
+before = svc.weights["own"].weights()
+check("misses on that calibration lean toward the right eye", before[1] > 0.9, True)
+svc.note_own_calibration()
+check("the same calibration again: kept", svc.weights["own"].weights(), before)
+svc.own = {"calibration": {"made": "2026-10-18 21:11:33", "dots": 26}}
+svc.note_own_calibration()
+check("a new calibration: the misses start over", svc.weights["own"].misses, [[], []])
+check("...the eyes count alike until each has MIN again", tuple(svc.weights["own"].weights()), (0.5, 0.5))
+check("...said in the log", sum("eye weights start over" in m for m in logs), 1)
+check("...and saved with the stamp", (svc.own_made, svc.dirty), ("2026-10-18 21:11:33", True))
+svc.own = {}
+svc.note_own_calibration()
+check("a status without a calibration changes nothing", svc.own_made, "2026-10-18 21:11:33")
+
+# The stamp lives with the misses, so a restart keeps them and a calibration made meanwhile doesn't.
+svc.lives = {name: gazed.PointerLessons() for name in gazed.SOURCES}
+svc.weights["own"].add([1.0, 1.0])
+gazed.STATE.mkdir(parents=True, exist_ok=True)
+svc.save_lessons()
+again = service()
+again.bias, again.lives = "auto", {name: gazed.PointerLessons() for name in gazed.SOURCES}
+again.source = "mmap1"
+again.load_lessons()
+check("after a restart: the stamp and the misses", (again.own_made, again.weights["own"].misses),
+      ("2026-10-18 21:11:33", [[1.0], [1.0]]))
+again.own = {"calibration": {"made": "2026-10-18 21:11:33"}}
+again.note_own_calibration()
+check("...the same calibration: kept", again.weights["own"].misses, [[1.0], [1.0]])
+again.own = {"calibration": {"made": "2026-10-18 21:30:00"}}
+again.note_own_calibration()
+check("...one made while it was down: started over", again.weights["own"].misses, [[], []])
+
+shutil.rmtree(HOME, ignore_errors=True)
+print("FAILED: " + ", ".join(failures) if failures else "all passed", flush=True)
+sys.exit(1 if failures else 0)

gaze/test/one-eye-test.py

@@ -21,7 +21,7 @@ from gazecal import (  # noqa: E402
     Correction,
     EyeFallback,
     EyeWeights,
-    Fixation,
+    GazeLock,
     TrackedEye,
     steady_samples,
     tracked_eye,
@@ -112,7 +112,8 @@ def service(one, source="mmap1"):
                                 "looking_down", "dropped"), 0)
     svc.opens, svc.vergence = (deque(maxlen=90), deque(maxlen=90)), deque(maxlen=90)
     svc.lost, svc.bad_at, svc.fallback = [False, False], [0.0, 0.0], EyeFallback()
-    svc.fix, svc.last_sample = Fixation(radius=1.0), 0.0
+    svc.fix, svc.last_sample, svc.low_until = GazeLock(radius=1.0), 0.0, [0.0, 0.0]
+    svc.bridge = gazed.EyeBridge()
     svc.correction = lambda name, hy, hp: (0.0, 0.0)
     svc.sent = []
     svc.send = lambda t, hy, hp, rhy, rhp, eyes: svc.sent.append((hy, hp))

gaze/test/size-guard-test.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Offline test of ft-eyes' size guard (eyes_pupil.SizeGuard, EYES_SIZE_GUARD): synthetic frames
+fed to its eyes as the live loop does. A find two thirds of the pupil's usual size in one eye,
+while the other's is as usual, counts as not found: no gaze from it, the search stays on the
+last pupil, the finds log marks it "guard". With the guard off, it's taken. Needs the
+tracker's Python (numpy, OpenCV); no cameras or SteamVR.
+
+  scripts/in-box /opt/frametop/venv/bin/python gaze/test/size-guard-test.py
+"""
+import importlib.machinery
+import importlib.util
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+HOME = tempfile.mkdtemp(prefix="ft-eyes-size-guard-test-")
+TRACKER = Path(__file__).resolve().parents[1] / "tracker"
+
+
+def load(rule):
+    os.environ.update(HOME=HOME, FT_EYES_CAMS="/nonexistent", FT_EYES_STATE=os.path.join(HOME, "eyes"),
+                      FT_EYES_MODEL="classic", FT_EYES_SIZE_GUARD=rule)
+    loader = importlib.machinery.SourceFileLoader(f"fteyes_{rule}", str(TRACKER / "ft-eyes"))
+    mod = importlib.util.module_from_spec(importlib.util.spec_from_loader(loader.name, loader))
+    loader.exec_module(mod)
+    return mod
+
+
+def frame(a, b):
+    img = np.full((400, 512), 100, np.uint8)
+    cv2.ellipse(img, (256, 200), (a, b), 0, 0, 360, 0, -1)
+    return img
+
+
+failed = 0
+
+
+def check(ok, what):
+    global failed
+    print(("ok   " if ok else "FAIL ") + what)
+    failed += not ok
+
+
+for rule, refused in (("both", True), ("off", False)):
+    fe = load(rule)
+    tracker = fe.Tracker()
+    log = os.path.join(HOME, f"finds-{rule}.jsonl")
+    tracker.command(f"finds start {log}")
+    right, left = tracker.eyes
+    t = 100.0
+    for i in range(40):           # both pupils as usual
+        right.feed(t, frame(30, 24))
+        left.feed(t + 0.001, frame(30, 24))
+        t += 1 / 90
+    last = right.last
+    left.feed(t, frame(30, 24))
+    right.feed(t + 0.001, frame(20, 15))   # 0.67 of usual, the left eye as usual
+    tracker.command("finds stop")
+    rows = [json.loads(x) for x in open(log)]
+    check(tracker.status()["size_guard"] == rule, f"{rule}: status says the rule")
+    check((right.refused == 1) == refused, f"{rule}: the small find refused: {right.refused}")
+    check((right.last is last) == refused, f"{rule}: the search stays on the last pupil")
+    check(bool(rows[-1].get("guard")) == refused, f"{rule}: the finds log marks it: {rows[-1]}")
+    check(abs(rows[-1]["a"] - 20) < 1.5, f"{rule}: ...with its size")
+    check(left.refused == 0 and sum(1 for r in rows if r.get("guard")) == (1 if refused else 0),
+          f"{rule}: nothing else refused")
+    counts = tracker.status()["size_guard_counts"]
+    got = {e: (c["kept"] >= 30, c["refused"], c["restarts"]) for e, c in counts.items()}
+    want = {"right": (True, 1, 0), "left": (True, 0, 0)} if refused else \
+        {e: (False, 0, 0) for e in ("right", "left")}   # the rule off: nothing judged
+    check(got == want, f"{rule}: status counts the guard's finds: {counts}")
+    zero = {e: {"kept": 0, "refused": 0, "restarts": 0} for e in (0, 1)}
+    _, line = fe.guard_line(tracker.guard, zero)
+    check(("right refused 1 of " in line and "left refused 0 of " in line and "restarts" not in line) if refused
+          else line == "", f"{rule}: its minute's log line: {line!r}")
+    if refused:
+        # The right pupil really smaller (one eye's light) for over GUARD_RESET: its usual size
+        # starts over, once, and that's counted.
+        was = {e: tracker.guard.counts(e) for e in (0, 1)}
+        t += 0.01
+        for i in range(int(fe.eyes_pupil.GUARD_RESET * 90) + 30):
+            left.feed(t, frame(30, 24))
+            right.feed(t + 0.001, frame(20, 15))
+            t += 1 / 90
+        check(tracker.guard.counts(1)["restarts"] == 0 and tracker.guard.counts(0)["restarts"] == 1,
+              f"{rule}: a pupil that stayed smaller: one restart: {tracker.status()['size_guard_counts']}")
+        _, line = fe.guard_line(tracker.guard, was)
+        check(", 1 restarts" in line, f"{rule}: ...in the log line: {line!r}")
+
+print(f"{'FAILED' if failed else 'ok'}: size guard")
+sys.exit(1 if failed else 0)

gaze/test/test_eyes_pupil.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Offline pupil detection: shared preprocessing preserves both closing attempts.
+
+Synthetic images exercise normal pupils, glints, the small-kernel retry, lost eyes,
+and windowed searches. No camera, calibration, or SteamVR connection is needed.
+"""
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tracker"))
+import eyes_pupil as pupil
+
+
+def frame(retry=False):
+    img = np.full((400, 512), 100, np.uint8)
+    centre = (44, 200) if retry else (256, 200)
+    if retry:
+        img[:, :11] = 0  # large closing joins the pupil to this edge region
+    cv2.ellipse(img, centre, (30, 24), 0, 0, 360, 0, -1)
+    return img
+
+
+def separate_attempts(img, ox, oy):
+    """The old preprocessing order: each attempt gets a newly calculated mask."""
+    for close in (pupil.CLOSE, pupil.CLOSE_TIGHT):
+        dark = (cv2.GaussianBlur(img, (5, 5), 0) < pupil.DARK).astype(np.uint8)
+        p = pupil._find(img, dark, ox, oy, close)
+        if p is not None:
+            return p
+    return None
+
+
+class PupilTest(unittest.TestCase):
+    def test_first_attempt(self):
+        img = frame()
+        with patch.object(pupil.cv2, "GaussianBlur", wraps=cv2.GaussianBlur) as blur, \
+                patch.object(pupil, "_find", wraps=pupil._find) as find:
+            p = pupil.find_pupil(img)
+        self.assertEqual((blur.call_count, find.call_count), (1, 1))
+        self.assertAlmostEqual(p["x"], 256, delta=0.1)
+        self.assertAlmostEqual(p["y"], 200, delta=0.1)
+
+    def test_retry_preserves_mask_and_kernels(self):
+        img = frame(retry=True)
+        dark = (cv2.GaussianBlur(img, (5, 5), 0) < pupil.DARK).astype(np.uint8)
+        self.assertIsNone(pupil._find(img, dark, 0, 0))
+        expected = pupil._find(img, dark, 0, 0, pupil.CLOSE_TIGHT)
+        self.assertIsNotNone(expected)
+        kernels = {k: v.copy() for k, v in pupil._KERNELS.items()}
+        with patch.object(pupil.cv2, "GaussianBlur", wraps=cv2.GaussianBlur) as blur, \
+                patch.object(pupil, "_find", wraps=pupil._find) as find:
+            self.assertEqual(pupil._find_either(img, 0, 0), expected)
+        self.assertEqual((blur.call_count, find.call_count), (1, 2))
+        first, second = (call.args[1] for call in find.call_args_list)
+        self.assertIs(first, second)
+        np.testing.assert_array_equal(first, dark)
+        for k, v in kernels.items():
+            np.testing.assert_array_equal(pupil._KERNELS[k], v)
+
+    def test_exact_results_for_full_and_cropped_images(self):
+        rng = np.random.default_rng(512400)
+        images = [np.zeros((400, 512), np.uint8), np.full((400, 512), 255, np.uint8),
+                  frame(), frame(retry=True)]
+        glints = frame()
+        for y in (194, 207):
+            cv2.circle(glints, (256, y), 2, 255, -1)
+        images.append(glints)
+        for _ in range(12):
+            img = rng.integers(35, 180, (400, 512), np.uint8)
+            cv2.ellipse(img, (int(rng.integers(30, 480)), int(rng.integers(25, 375))),
+                        (int(rng.integers(10, 45)), int(rng.integers(8, 25))),
+                        int(rng.integers(0, 180)), 0, 360, 0, -1)
+            images.append(img)
+        for i, img in enumerate(images):
+            for x, y in ((0, 0), (11, 15), (200, 120)):
+                roi = img if (x, y) == (0, 0) else img[y:y + 180, x:x + 200]
+                before = roi.copy()
+                with self.subTest(image=i, offset=(x, y)):
+                    self.assertEqual(pupil._find_either(roi, x, y), separate_attempts(roi, x, y))
+                    np.testing.assert_array_equal(roi, before)
+
+    def test_window_hint_and_full_frame_fallback(self):
+        img = frame()
+        expected = pupil.find_pupil(img)
+        self.assertEqual(pupil.find_pupil(img, expected), expected)
+        self.assertEqual(pupil.find_pupil(img, {"x": 50, "y": 50, "a": 5}), expected)
+        self.assertEqual(pupil.find_pupil(np.zeros_like(img), expected), None)
+
+    def test_a_much_smaller_spot_isnt_the_pupil(self):
+        """The right camera's dark spot of 2026-10-17: darker and smaller than the pupil, so it
+        wins on score unless the pupil's recent size rules it out."""
+        img = np.full((400, 512), 100, np.uint8)
+        cv2.ellipse(img, (256, 200), (30, 24), 0, 0, 360, 20, -1)
+        cv2.ellipse(img, (215, 250), (10, 7), 0, 0, 360, 0, -1)
+        self.assertAlmostEqual(pupil.find_pupil(img)["x"], 215, delta=0.5)
+        p = pupil.find_pupil(img, smallest=15)
+        self.assertAlmostEqual(p["x"], 256, delta=0.5)
+        self.assertAlmostEqual(pupil.find_pupil(img, p, 15)["x"], 256, delta=0.5)
+        self.assertIsNone(pupil.find_pupil(img, p, 40))
+
+    def test_pupil_size(self):
+        size = pupil.PupilSize()
+        for i in range(pupil.SIZE_FINDS - 1):
+            size.add(i / 90, {"a": 20.0})
+        self.assertEqual(size.smallest(9 / 90), 0.0)  # too few finds yet
+        size.add(9 / 90, {"a": 24.0})
+        size.add(10 / 90, None)  # lost frames don't count
+        self.assertAlmostEqual(size.smallest(10 / 90), pupil.SMALLEST * 20.0)
+        self.assertEqual(size.smallest(10 / 90 + pupil.SIZE_WINDOW + 0.2), 0.0)  # all of them too old
+
+
+def warm(guard, t=0.0, a=(20.0, 20.0)):
+    """Both eyes' usual sizes: GUARD_FINDS finds each, 90 Hz, from t. Returns the next t."""
+    for i in range(pupil.GUARD_FINDS):
+        for e in (0, 1):
+            assert guard.keep(e, t + i / 90, a[e])
+    return t + pupil.GUARD_FINDS / 90
+
+
+class SizeGuardTest(unittest.TestCase):
+    def test_a_misfind_in_one_eye(self):
+        g = pupil.SizeGuard("both")
+        t = warm(g)
+        self.assertTrue(g.keep(1, t, 19.0))
+        self.assertFalse(g.keep(0, t + 0.001, 13.0))   # 0.65 of usual, the other eye at 0.95
+        self.assertTrue(g.keep(0, t + 1 / 90, 19.5))
+        self.assertEqual(g.refused, {0: 1, 1: 0})
+
+    def test_light_shrinks_both(self):
+        """Both pupils down to under half their usual size: kept with "both", refused with "long"."""
+        for rule, kept in (("both", True), ("long", False)):
+            g = pupil.SizeGuard(rule)
+            t = warm(g)
+            ok = []
+            for i in range(20):   # narrowing over 20 frames, both eyes alike
+                a = 20.0 * (1 - 0.03 * i)
+                ok += [g.keep(0, t, a), g.keep(1, t + 0.001, a)]
+                t += 1 / 90
+            with self.subTest(rule=rule):
+                self.assertEqual(all(ok), kept)
+
+    def test_other_eye_not_seen(self):
+        g = pupil.SizeGuard("both")
+        t = warm(g) + 1.0   # the other eye's last find is old
+        self.assertTrue(g.keep(0, t, 13.0))    # 0.65: over GUARD_ALONE
+        self.assertFalse(g.keep(0, t + 0.01, 11.0))
+
+    def test_refusals_going_on_start_over(self):
+        g = pupil.SizeGuard("long")
+        t = warm(g)
+        ok = [g.keep(0, t + i / 90, 10.0) for i in range(int(pupil.GUARD_RESET * 90) + 5)]
+        self.assertFalse(ok[0])
+        self.assertTrue(ok[-1])        # taken again after GUARD_RESET s
+        self.assertTrue(g.keep(0, t + 2.0, 10.0))
+
+    def test_off_and_unknown(self):
+        self.assertTrue(pupil.SizeGuard("off").keep(0, 0.0, 1.0))
+        self.assertEqual(pupil.SizeGuard("nonsense").rule, "both")
+
+
+if __name__ == "__main__":
+    unittest.main()

gaze/tracker/build.sh

@@ -13,6 +13,7 @@ root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 "$root/scripts/sync.sh" >/dev/null
 exec "$root/scripts/frame.sh" -C gaze/tracker 'set -e; mkdir -p build
 gcc -std=gnu11 -O2 -Wall -Wextra -pthread -o build/ft-eyegrab ft-eyegrab.c
+strip --strip-unneeded build/ft-eyegrab
 max=$(objdump -T build/ft-eyegrab | grep -oE "GLIBC_[0-9.]+" | sort -uV | tail -1)
 echo "built build/ft-eyegrab, newest glibc symbol: $max"
 [ "$(printf "%s\n" "$max" GLIBC_2.39 | sort -V | tail -1)" = GLIBC_2.39 ] || { echo "needs newer glibc than the host has" >&2; exit 1; }

gaze/tracker/eyes_model.py

@@ -75,13 +75,26 @@ def pair_mid(pair):
     return ((pair[0][0] + pair[1][0]) / 2, (pair[0][1] + pair[1][1]) / 2)
 
 
+def eye_of(click, eye):
+    """A click's features for one eye, or None: `eye` is a list by eye (the lab tools) or a dict
+    of the eyes seen (ft-eyes' calibration dots, which may hold one)."""
+    e = click["eye"]
+    return e.get(eye) if isinstance(e, dict) else e[eye]
+
+
 class Calibration:
     """The three fits per eye. Build from clicks (ft-eyes-score's features) or load from JSON.
 
     `spread` is each eye's RMS miss (degrees) on the clicks its pupil fit was made from.
     `combine` weights the eyes by its inverse square: on practice2 (one headset position,
     leave-one-out) that gave 0.75 median against 0.84 for the plain average, since one eye
-    is usually much better than the other (left 0.73, right 1.32 there)."""
+    is usually much better than the other (left 0.73, right 1.32 there).
+
+    Each eye is fitted on the clicks it was seen in, so a click may hold one eye only, and an
+    eye seen in under MIN_CLICKS is left out (the calibration then maps the other alone). A
+    second person's eyes (2026-10-17 rounds) each lost the pupil looking 20 degrees outward:
+    with only the clicks that saw both, each eye's fit had none out there and guessed (frame
+    errors 8.1 degrees median, 84 p90, held-out takes); each on its own clicks, 2.3 and 5.0."""
 
     def __init__(self, fits=None, info=None, spread=None):
         self.fits = fits or {}   # (name, eye) -> Quad
@@ -93,21 +106,26 @@ class Calibration:
         truth = lambda cs: np.array([k["truth"] for k in cs])  # noqa: E731
         fits, spread = {}, {}
         for c in (0, 1):
-            cs = [k for k in clicks if k["eye"][c] is not None]
+            cs = [k for k in clicks if eye_of(k, c) is not None]
             if len(cs) < MIN_CLICKS:
                 continue
-            fits["pupil", c] = Quad([k["eye"][c]["pupil"] for k in cs], truth(cs))
-            miss = fits["pupil", c]([k["eye"][c]["pupil"] for k in cs]) - truth(cs)
+            pupils = [eye_of(k, c)["pupil"] for k in cs]
+            fits["pupil", c] = Quad(pupils, truth(cs))
+            miss = fits["pupil", c](pupils) - truth(cs)
             spread[c] = float(np.sqrt(np.mean(np.sum(miss ** 2, axis=1))))
-            fits["where", c] = Quad(truth(cs), [k["eye"][c]["pupil"] for k in cs])
-            gs = [k for k in cs if k["eye"][c]["mid"] is not None]
+            fits["where", c] = Quad(truth(cs), pupils)
+            gs = [k for k in cs if eye_of(k, c)["mid"] is not None]
             if len(gs) >= MIN_CLICKS:
-                fits["glint", c] = Quad([k["eye"][c]["pupil"] - k["eye"][c]["mid"] for k in gs], truth(gs))
+                fits["glint", c] = Quad([eye_of(k, c)["pupil"] - eye_of(k, c)["mid"] for k in gs], truth(gs))
         return cls(fits, info, spread)
 
     def has(self, name, eye):
         return (name, eye) in self.fits
 
+    def eyes(self):
+        """The eyes it maps (0 right, 1 left)."""
+        return [c for c in (0, 1) if self.has("pupil", c)]
+
     def slip(self, eye, rows):
         """Median slip in pixels from pair sightings `rows` (t, px, py, mx, my), or None."""
         if not self.has("glint", eye) or len(rows) < SLIP_MIN:

gaze/tracker/eyes_pupil.py

@@ -5,7 +5,14 @@ background are just as dark, but they touch the image edge, so any dark region t
 the edge is dropped. Closing the glints' holes can join the pupil to that background (the
 left camera's, when you look more than about 20 degrees left), so when nothing is found
 the search runs again with a smaller closing.
+
+A dark spot well inside the frame can pass all that too: on 2026-10-17 the right camera took
+one about 9 px across for the pupil (23 px) about once a second, for 3-7 frames at a time, and
+the gaze jumped 60 degrees. A pupil doesn't shrink to half its size in a frame, so a find that
+much smaller than the last half second's (PupilSize) is skipped.
 """
+from collections import deque
+
 import cv2
 import numpy as np
 
@@ -22,42 +29,44 @@ MAX_ASPECT = 3.0   # long / short axis; the steep camera sees a squashed pupil
 GLINT = 200        # glints are near-saturated spots on or by the pupil
 CLOSE = 7          # px: closes the glints' holes in the pupil (the right eye's need this much)
 CLOSE_TIGHT = 3    # px: the retry, keeps a pupil near the dark background apart from it
+_KERNELS = {size: np.ones((size, size), np.uint8) for size in {3, CLOSE, CLOSE_TIGHT}}
 
 
 NEAR = 70          # the windowed search: this many pixels, or 3 pupil radii, around a hint
 
 
-def find_pupil(frame, near=None):
+def find_pupil(frame, near=None, smallest=0.0):
     """Return dict(x, y, a, b, angle, area, fill, glints) or None.
 
     `near` (a previous result) searches a window around it first (0.4 ms, not 1.4-2.1);
-    if the pupil isn't wholly inside the window it falls back to the whole frame."""
+    if the pupil isn't wholly inside the window it falls back to the whole frame. Blobs whose
+    long semi-axis is under `smallest` px don't count (PupilSize.smallest)."""
     if near is not None:
         r = int(max(NEAR, 3 * near['a']))
         x0, y0 = max(int(near['x']) - r, 0), max(int(near['y']) - r, 0)
-        p = _find_either(frame[y0:int(near['y']) + r, x0:int(near['x']) + r], x0, y0)
+        p = _find_either(frame[y0:int(near['y']) + r, x0:int(near['x']) + r], x0, y0, smallest)
         if p is not None:
             p['glints'] = find_glints(frame, p)
             return p
-    p = _find_either(frame, 0, 0)
+    p = _find_either(frame, 0, 0, smallest)
     if p is not None:
         p['glints'] = find_glints(frame, p)
     return p
 
 
-def _find_either(img, ox, oy):
-    p = _find(img, ox, oy)
-    return p if p is not None else _find(img, ox, oy, CLOSE_TIGHT)
+def _find_either(img, ox, oy, smallest=0.0):
+    # Both closing sizes use the same input mask; morphologyEx returns a new one.
+    dark = (cv2.GaussianBlur(img, (5, 5), 0) < DARK).astype(np.uint8)
+    p = _find(img, dark, ox, oy, smallest=smallest)
+    return p if p is not None else _find(img, dark, ox, oy, CLOSE_TIGHT, smallest)
 
 
-def _find(img, ox, oy, close=CLOSE):
-    """The pupil in `img` (a window at ox, oy of the frame), with frame coordinates. A dark
+def _find(img, dark, ox, oy, close=CLOSE, smallest=0.0):
+    """The pupil in `img` (a window at ox, oy), using its prepared `dark` mask. A dark
     region touching the window's edge doesn't count: it's background, rim, or cut off."""
-    f = cv2.GaussianBlur(img, (5, 5), 0)
-    dark = (f < DARK).astype(np.uint8)
     # Glints punch bright holes in the pupil; close them so the blob stays whole.
-    dark = cv2.morphologyEx(dark, cv2.MORPH_CLOSE, np.ones((close, close), np.uint8))
-    dark = cv2.morphologyEx(dark, cv2.MORPH_OPEN, np.ones((3, 3), np.uint8))
+    dark = cv2.morphologyEx(dark, cv2.MORPH_CLOSE, _KERNELS[close])
+    dark = cv2.morphologyEx(dark, cv2.MORPH_OPEN, _KERNELS[3])
     n, lab, stats, _ = cv2.connectedComponentsWithStats(dark, connectivity=8)
     h, w = img.shape
     best = None
@@ -74,7 +83,7 @@ def _find(img, ox, oy, close=CLOSE):
             continue
         (ex, ey), (d1, d2), ang = cv2.fitEllipse(c)
         a, b = max(d1, d2) / 2, min(d1, d2) / 2
-        if b < 3 or a / b > MAX_ASPECT:
+        if b < 3 or a / b > MAX_ASPECT or a < smallest:
             continue
         fill = area / (np.pi * a * b)
         if fill < MIN_FILL or fill > 1.25:
@@ -90,6 +99,116 @@ def _find(img, ox, oy, close=CLOSE):
     return best[1] if best else None
 
 
+SMALLEST = 0.5     # a find under this share of the pupil's recent size is something else
+SIZE_WINDOW = 0.5  # s of finds the recent size comes from
+SIZE_FINDS = 10    # and at least this many of them
+
+
+class PupilSize:
+    """One eye's recent pupil size, the median long semi-axis of its finds over the last
+    SIZE_WINDOW s. A pupil narrows in bright light over a second or so, and turning the eye
+    changes how big the camera sees it by a few percent per frame; in the practice captures
+    (2026-09-29) under 0.4 % of finds were below half this median, many of them strays as well.
+    Only smaller finds are refused: if a wrong spot gets in (after a loss, with no recent size),
+    the real pupil isn't refused when it's back, and the median follows it."""
+
+    def __init__(self):
+        self.finds = deque()   # (t, a)
+
+    def smallest(self, t):
+        """The smallest long semi-axis a find at time t may have, in px (0: no limit yet)."""
+        while self.finds and self.finds[0][0] < t - SIZE_WINDOW:
+            self.finds.popleft()
+        if len(self.finds) < SIZE_FINDS:
+            return 0.0
+        return SMALLEST * float(np.median([a for _, a in self.finds]))
+
+    def add(self, t, p):
+        if p is not None:
+            self.finds.append((t, p['a']))
+
+
+GUARD_RULES = ("both", "long", "off")
+GUARD_LONG = 10.0   # s of kept finds an eye's usual size comes from
+GUARD_FINDS = 20    # and at least this many of them
+GUARD_BOTH = 0.75   # "both": a find under this share of the other eye's ratio to its usual size
+GUARD_ALONE = 0.6   # without the other eye just now (or "long"): under this share of its usual size
+GUARD_FRESH = 0.05  # s: the other eye's last find counts this long
+GUARD_RESET = 1.0   # s of refusals in a row: the pupil really did change, its usual size starts over
+
+
+class SizeGuard:
+    """Both eyes' usual pupil sizes, for the misfinds PupilSize lets through (2026-10-17, two
+    Gaze Bench runs): a dark spot two thirds of the pupil's size, held for a few frames, so the
+    last half second's median follows it in. Here each eye's usual size is the median long
+    semi-axis of its kept finds over the last GUARD_LONG s, and a find is judged by its ratio to
+    that. The pupils narrow and widen together in light (the consensual reflex), so with
+    "both" a find is refused when its ratio is under GUARD_BOTH of the other eye's latest
+    (capped at 1): light shrinks both, a misfind one. On those runs (8884 finds) good finds sat
+    at 0.84 of the usual size or more 95 % of the time, the right eye's misfinds at a median of
+    0.77 and a quarter of them under 0.52. "long" is the ratio alone, under GUARD_ALONE, which
+    is also the rule while the other eye isn't seen. A refused find counts as not found. If
+    refusals go on for GUARD_RESET s, the eye's usual size starts over, so a pupil that did
+    change (light with one eye lost) is taken again. Each eye's kept and refused finds and those
+    restarts are counted (counts), so a session shows whether it refused real pupils: many
+    restarts, or refusals while both eyes looked fine, say it did."""
+
+    def __init__(self, rule="both"):
+        self.rule = rule if rule in GUARD_RULES else "both"
+        self.finds = {0: deque(), 1: deque()}   # (t, a) of kept finds
+        self.usual = {0: None, 1: None}         # the median, recomputed every few finds
+        self.since = {0: 0, 1: 0}
+        self.last = {0: None, 1: None}          # (t, ratio) of each eye's last kept find
+        self.refusing = {0: None, 1: None}      # when the current run of refusals began
+        self.refused = {0: 0, 1: 0}
+        self.kept = {0: 0, 1: 0}
+        self.restarts = {0: 0, 1: 0}            # runs of refusals that went on GUARD_RESET s
+
+    def ratio(self, e, t, a):
+        h = self.finds[e]
+        while h and h[0][0] < t - GUARD_LONG:
+            h.popleft()
+            self.usual[e] = None
+        if len(h) < GUARD_FINDS:
+            return None
+        if self.usual[e] is None or self.since[e] >= 10:
+            self.usual[e], self.since[e] = float(np.median([x for _, x in h])), 0
+        return a / self.usual[e]
+
+    def keep(self, e, t, a):
+        """Is eye e's find at time t, long semi-axis a px, its pupil? (It learns from the kept ones.)"""
+        if self.rule == "off":
+            return True
+        r = self.ratio(e, t, a)
+        ok = True
+        if r is not None:
+            o = self.last[1 - e]
+            if self.rule == "both" and o is not None and t - o[0] <= GUARD_FRESH:
+                ok = r >= GUARD_BOTH * min(1.0, o[1])
+            else:
+                ok = r >= GUARD_ALONE
+        if not ok:
+            if self.refusing[e] is None:
+                self.refusing[e] = t
+            elif t - self.refusing[e] > GUARD_RESET:
+                self.finds[e].clear()
+                self.usual[e], ok, r = None, True, None
+                self.restarts[e] += 1
+        if not ok:
+            self.refused[e] += 1
+            return False
+        self.refusing[e] = None
+        self.kept[e] += 1
+        self.finds[e].append((t, a))
+        self.since[e] += 1
+        self.last[e] = (t, 1.0 if r is None else r)
+        return True
+
+    def counts(self, e):
+        """Eye e's finds judged so far: {"kept", "refused", "restarts"} (none with the rule off)."""
+        return {"kept": self.kept[e], "refused": self.refused[e], "restarts": self.restarts[e]}
+
+
 GLINT_RING = 140   # a glint sits on dark iris or pupil: its surroundings are below this
 GLINT_PAIR = (5, 45)  # the two LEDs' reflections: this far apart, in pixels, mostly vertical
 

gaze/tracker/ft-eyes

@@ -28,8 +28,13 @@ Control socket: abstract datagram "@ft_eyes"; each command gets one reply line.
   calib-start                  a new calibration: collect dots from now on
   calib-point T0 T1 YAW PITCH  a dot you looked at from T0 to T1 (CLOCK_MONOTONIC_RAW) in
                                that direction (head-relative degrees): "ok N0 N1 SD0 SD1"
-                               (frames and spread in px per eye, right first) or "fail WHY"
-  calib-fit                    fit the dots, save, and start the shifts and clicks over
+                               (frames and spread in px per eye, right first), then
+                               " (EYE eye only: WHY)" if one eye wasn't seen enough or moved
+                               (the dot is kept for the other), or "fail WHY"
+  calib-fit                    fit the dots, save, and start the shifts and clicks over. Each
+                               eye is fitted on the dots it was seen at; one seen at too few
+                               (eyes_model.MIN_CLICKS) is left out, and the other maps the
+                               gaze alone ("..., left not used (9 dots, needs 12)")
   click T YAW PITCH            a click: you were looking there just before T; teaches the
                                shift: "ok DX0 DY0 DX1 DY1" (the shift each eye measured)
   fit                          JSON: the last second of pupil finds per camera, for the fit
@@ -37,8 +42,9 @@ Control socket: abstract datagram "@ft_eyes"; each command gets one reply line.
   finds start PATH | finds stop
                                append every frame looked at to PATH as JSON lines (the eye
                                recorder's own.jsonl): {"t", "cam", "x", "y", "a", "b", "angle",
-                               "glints": [[x, y], ...], "gaze": [yaw, pitch] once calibrated},
-                               or {"t", "cam", "lost": true}; with the net also "net": {"gaze",
+                               "glints": [[x, y], ...], "gaze": [yaw, pitch] once calibrated,
+                               "guard": true if the size guard refused it}, or {"t", "cam",
+                               "lost": true}; with the net also "net": {"gaze",
                                "x", "y", "open", "visible"}. "finds stop" replies "ok ROWS"
 
 The eye net (eyes_net.py) instead of the pupil finder: EYES_MODEL in ~/.config/frametop.conf (or
@@ -53,9 +59,17 @@ service restarts ft-eyes when EYES_MODEL changes. If the model can't load, ft-ey
 so and uses the pupil finder. While the fit coach asks ("fit") or finds are logged, the pupil
 finder runs too, for them.
 
+The pupil finder's size guard (eyes_pupil.SizeGuard): a find much smaller than that eye's usual
+size, judged against how the other eye's size compares with its own (both narrow in light),
+counts as not found. EYES_SIZE_GUARD in frametop.conf (or FT_EYES_SIZE_GUARD): both (the
+default), long (against its own usual size only) or off. Read at start. Each eye's kept and
+refused finds, and its usual size's restarts, are in the status ("size_guard_counts", since the
+start), and once a minute that it refused any, a log line says how many ("size guard, the last
+60 s: right refused 40 of 3100 finds; left refused 0 of 3200 finds").
+
 Environment, for replays (lab/ft-eyes-e2e): FT_EYES_CAMS, FT_EYES_GAZE, FT_EYES_STATE (the
-state folder), FT_EYES_SOCKET (the socket's name), FT_EYES_MODEL. With FT_EYES_CAMS set, the want file isn't
-touched.
+state folder), FT_EYES_SOCKET (the socket's name), FT_EYES_MODEL, FT_EYES_SIZE_GUARD. With
+FT_EYES_CAMS set, the want file isn't touched.
 
 /dev/shm/frametop-eyes-gaze, 128 bytes, little-endian (mirrored in ft-gaze.cpp):
    0 u32 seq      odd while it's being written: read it before and after, retry if it moved
@@ -121,6 +135,27 @@ def load_net():
 
 NET = load_net()
 
+
+def size_guard_rule():
+    """EYES_SIZE_GUARD in ~/.config/frametop.conf (FT_EYES_SIZE_GUARD wins): eyes_pupil.SizeGuard's
+    rule, both (the default), long or off. Read at start."""
+    v = os.environ.get("FT_EYES_SIZE_GUARD")
+    if v is None:
+        v = ""
+        try:
+            for line in (Path.home() / ".config" / "frametop.conf").read_text().splitlines():
+                k, _, val = line.split("#", 1)[0].partition("=")
+                if k.strip() == "EYES_SIZE_GUARD":
+                    v = val.strip().strip("\"'")
+        except OSError:
+            pass
+    v = v.strip().lower()
+    return v if v in eyes_pupil.GUARD_RULES else "both"
+
+
+SIZE_GUARD = size_guard_rule()
+GUARD_REPORT = 60.0  # s between the size guard's log lines (only when it refused something)
+
 CAMS = os.environ.get("FT_EYES_CAMS", "/dev/shm/frametop-eyes-cams")  # overrides for replays
 OUT = os.environ.get("FT_EYES_GAZE", "/dev/shm/frametop-eyes-gaze")
 WANT = None if "FT_EYES_CAMS" in os.environ else Path("/dev/shm/frametop-eyes-want")
@@ -222,6 +257,9 @@ class Eye:
         self.shift = eyes_model.Shift()
         self.history = deque()  # (t, x, y, glint mid x, y)
         self.last = None        # the previous pupil (window hint)
+        self.size = eyes_pupil.PupilSize()   # its recent size: much smaller finds are something else
+        self.guard = None       # both eyes' usual sizes (eyes_pupil.SizeGuard, Tracker's), for the pupil finder
+        self.refused = 0
         self.gaze = None        # (t, yaw, pitch, x, y)
         self.lost = 0
         self.frames = self.found = 0
@@ -250,12 +288,18 @@ class Eye:
             if self.lost % LOST_EVERY:
                 return
         t0 = time.perf_counter()
-        p = eyes_pupil.find_pupil(img, self.last)
-        self.last = p
+        p = eyes_pupil.find_pupil(img, self.last, self.size.smallest(t))
+        self.size.add(t, p)
+        # A find the size guard refuses counts as not found, and the search stays where the last one was.
+        refused = p is not None and self.guard is not None and not self.guard.keep(self.eye, t, p["a"])
+        if refused:
+            self.refused += 1
+        else:
+            self.last = p
         if self.obs is not None:
             self.obs.add(self.eye, t, p)
             self.fed = (t, time.clock_gettime(time.CLOCK_MONOTONIC_RAW))
-        if p is not None:
+        if p is not None and not refused:
             self.found += 1
             self.lost = 0
             pair = eyes_pupil.glint_pair(p)
@@ -270,7 +314,7 @@ class Eye:
                 g = self.cal.gaze(self.eye, p["x"], p["y"], self.shift.value)
                 self.gaze = (t, float(g[0]), float(g[1]), p["x"], p["y"])
         if self.finds is not None:
-            self.finds.write(self, t, p)
+            self.finds.write(self, t, p, refused=refused)
         self.work += time.perf_counter() - t0
 
     def feed_net(self, t, img):
@@ -280,8 +324,9 @@ class Eye:
         classic = self.finds is not None or time.monotonic() < self.coach[0]
         p = None
         if classic:
-            p = eyes_pupil.find_pupil(img, self.last)
+            p = eyes_pupil.find_pupil(img, self.last, self.size.smallest(t))
             self.last = p
+            self.size.add(t, p)
             if self.obs is not None:
                 self.obs.add(self.eye, t, p)
                 self.fed = (t, time.clock_gettime(time.CLOCK_MONOTONIC_RAW))
@@ -317,7 +362,7 @@ class Finds:
         self.f = open(path, "a", buffering=1 << 16)
         self.rows = 0
 
-    def write(self, eye, t, p, net=None):
+    def write(self, eye, t, p, net=None, refused=False):
         if p is None:
             row = {"t": round(t, 6), "cam": eye.eye, "lost": True}
         else:
@@ -326,6 +371,8 @@ class Finds:
                    "glints": [[round(float(x), 1), round(float(y), 1)] for x, y in p.get("glints") or []]}
             if eye.gaze and eye.gaze[0] == t and not NET:
                 row["gaze"] = [round(eye.gaze[1], 3), round(eye.gaze[2], 3)]
+            if refused:
+                row["guard"] = True
         if net is not None:
             row["net"] = {"gaze": [round(v, 3) for v in net["gaze"]], "x": round(net["x"], 1), "y": round(net["y"], 1),
                           "open": round(net["open"], 3), "visible": round(net["visible"], 3)}
@@ -347,8 +394,9 @@ class Tracker:
         self.calibrating = False
         self.fit = fitcoach.Observations()
         coach = [0.0]
+        self.guard = eyes_pupil.SizeGuard(SIZE_GUARD)
         for e in self.eyes:
-            e.obs, e.coach = self.fit, coach
+            e.obs, e.coach, e.guard = self.fit, coach, self.guard
         if CALIBRATION.exists():
             self.cal = eyes_model.Calibration.load(CALIBRATION)
             if self.cal.info.get("feature", "pupil") != FEATURE:
@@ -417,23 +465,44 @@ class Tracker:
                 return "fail no calibration started"
             t0, t1, yaw, pitch = map(float, w[1:])
             got = {e.eye: e.window(t0, t1) for e in self.eyes}
+            # Each eye that was seen and held still counts: the dot is taken with one eye if
+            # the other was lost (looking far toward that eye's ear, say) or jumped about.
+            why = {}
             for c, g in got.items():
                 if g is None or g["n"] < CALIB_MIN:
-                    return f"fail the {EYES[c]} eye was seen in only {0 if g is None else g['n']} frames"
-                if g["spread"] > CALIB_SPREAD:
-                    return f"fail the {EYES[c]} eye moved ({g['spread']:.1f} px)"
-            self.dots.append(dict(truth=(yaw, pitch), eye={c: dict(pupil=g["pupil"], mid=g["mid"]) for c, g in got.items()}))
-            return "ok {} {} {:.2f} {:.2f}".format(got[0]["n"], got[1]["n"], got[0]["spread"], got[1]["spread"])
+                    why[c] = f"the {EYES[c]} eye was seen in only {0 if g is None else g['n']} frames"
+                elif g["spread"] > CALIB_SPREAD:
+                    why[c] = f"the {EYES[c]} eye moved ({g['spread']:.1f} px)"
+            if len(why) == 2:
+                moved = [c for c in (0, 1) if "moved" in why[c]]
+                if moved:
+                    return "fail " + why[moved[0]]
+                return "fail neither eye was seen enough ({})".format(
+                    ", ".join(f"{EYES[c]} {0 if got[c] is None else got[c]['n']} frames" for c in (0, 1)))
+            self.dots.append(dict(truth=(yaw, pitch), eye={c: dict(pupil=g["pupil"], mid=g["mid"])
+                                                           for c, g in got.items() if c not in why}))
+            n = [0 if got[c] is None else got[c]["n"] for c in (0, 1)]
+            spread = [math.nan if got[c] is None else got[c]["spread"] for c in (0, 1)]
+            reply = "ok {} {} {:.2f} {:.2f}".format(*n, *spread)
+            for c, text in why.items():
+                reply += f" ({EYES[1 - c]} eye only: {text})"
+            return reply
         if w[0] == "calib-fit":
             if len(self.dots) < eyes_model.MIN_CLICKS:
                 return f"fail only {len(self.dots)} dots (need {eyes_model.MIN_CLICKS})"
+            seen = {c: sum(1 for k in self.dots if c in k["eye"]) for c in (0, 1)}
             cal = eyes_model.Calibration.fit(self.dots, {"made": time.strftime("%Y-%m-%d %H:%M:%S"),
                                                        "dots": len(self.dots), "from": "probe calibration",
-                                                       "feature": FEATURE})
-            if not all(cal.has(n, c) for n in ("pupil", "where") for c in (0, 1)):
-                return "fail not enough dots with both eyes"
-            errs = [float(np.hypot(*(np.mean([cal.gaze(c, *k["eye"][c]["pupil"]) for c in (0, 1)], axis=0)
-                                     - k["truth"]))) for k in self.dots]
+                                                       "feature": FEATURE,
+                                                       "eye_dots": {EYES[c]: seen[c] for c in (0, 1)}})
+            if not cal.eyes():
+                return "fail neither eye was seen at enough dots ({}; need {})".format(
+                    ", ".join(f"{EYES[c]} {seen[c]}" for c in (0, 1)), eyes_model.MIN_CLICKS)
+            errs = []
+            for k in self.dots:
+                g = cal.combine({c: cal.gaze(c, *v["pupil"]) for c, v in k["eye"].items() if cal.has("pupil", c)})
+                if g is not None:
+                    errs.append(float(np.hypot(*(g - k["truth"]))))
             if CALIBRATION.exists():
                 CALIBRATION.replace(CALIBRATION.with_name(time.strftime("calibration-%Y%m%d-%H%M%S.json")))
             cal.save(CALIBRATION)
@@ -448,7 +517,9 @@ class Tracker:
                                                     "mid": None if v["mid"] is None else v["mid"].tolist()}
                                                 for c, v in k["eye"].items()}}) + "\n")
             return (f"ok {len(self.dots)} dots, fit median {np.median(errs):.2f} deg, eyes "
-                    + ", ".join(f"{EYES[c]} {cal.spread[c]:.2f}" for c in sorted(cal.spread)))
+                    + ", ".join(f"{EYES[c]} {cal.spread[c]:.2f} ({seen[c]} dots)" if c in cal.spread
+                                else f"{EYES[c]} not used ({seen[c]} dots, needs {eyes_model.MIN_CLICKS})"
+                                for c in (0, 1)))
         if w[0] == "click" and len(w) == 4:
             if not self.cal:
                 return "fail not calibrated"
@@ -473,8 +544,10 @@ class Tracker:
 
     def status(self):
         return {"calibration": self.cal.info if self.cal else None, "calibrating": self.calibrating,
+                "mapped": [EYES[c] for c in self.cal.eyes()] if self.cal else None,
                 "feature": FEATURE, "model": NET.folder if NET else None,
-                "dots": len(self.dots),
+                "dots": len(self.dots), "size_guard": None if NET else self.guard.rule,
+                "size_guard_counts": None if NET else {EYES[e]: self.guard.counts(e) for e in (0, 1)},
                 "eyes": {EYES[e.eye]: {"shift": e.shift.value.tolist(), "clicks": len(e.shift.meas),
                                        "jump": bool(np.any(e.shift.jump)), "jump_px": e.shift.jump.tolist(),
                                        "reseat": e.shift.reseated} for e in self.eyes}}
@@ -558,6 +631,18 @@ def below_steamvr():
         print(f"ft-eyes: SCHED_BATCH: {e}", file=sys.stderr, flush=True)
 
 
+def guard_line(guard, was):
+    """The size guard since `was` (its counts then): (its counts now, a log line, or "" if it
+    refused nothing). Its own line, once a minute: ft-gazed keeps it (it drops the fps lines)."""
+    now = {e: guard.counts(e) for e in (0, 1)}
+    d = {e: {k: now[e][k] - was[e][k] for k in now[e]} for e in (0, 1)}
+    if not any(d[e]["refused"] for e in (0, 1)):
+        return now, ""
+    parts = [f"{EYES[e]} refused {d[e]['refused']} of {d[e]['kept'] + d[e]['refused']} finds"
+             + (f", {d[e]['restarts']} restarts" if d[e]["restarts"] else "") for e in (0, 1)]
+    return now, f"size guard, the last {GUARD_REPORT:.0f} s: " + "; ".join(parts)
+
+
 def main():
     below_steamvr()
     verbose = "-v" in sys.argv
@@ -580,12 +665,14 @@ def main():
     cal = tracker.cal
     print("ft-eyes: " + (f"the eye net {NET.name} ({NET.folder}); " if NET else "")
           + (f"calibration from {cal.info.get('made')} ({cal.info.get('from', cal.info.get('capture'))})"
-                           if cal else "not calibrated: run the probe's calibration with the Own tracker")
+             + ("" if len(cal.eyes()) == 2 else f", the {' and '.join(EYES[c] for c in cal.eyes())} eye only")
+             if cal else "not calibrated: run the probe's calibration with the Own tracker")
           + f"; waiting for {CAMS}", file=sys.stderr, flush=True)
     cams = wait_for_cams(sock, tracker, want)
     print("ft-eyes: frames found, tracking", file=sys.stderr, flush=True)
     seen = [cams.count(0), cams.count(1)]
-    report = time.monotonic()
+    report = guard_at = time.monotonic()
+    guard_was = {e: tracker.guard.counts(e) for e in (0, 1)}
     arrived = [0.0, 0.0]  # when each camera's newest frame was seen (monotonic)
     while True:
         serve(sock, tracker)
@@ -621,13 +708,18 @@ def main():
                 parts = []
                 for e in eyes:
                     s = e.shift.value
-                    parts.append(f"{EYES[e.eye]} {e.frames / 5:.0f} fps, found {e.found / max(e.frames, 1):.0%}, "
+                    parts.append(f"{EYES[e.eye]} {e.frames / 5:.0f} fps, found {e.found / max(e.frames, 1):.0%}"
+                                 + (f" ({e.refused} refused by size)" if e.refused else "") + ", "
                                  f"{e.work / max(e.frames, 1) * 1000:.2f} ms/frame, shift ({s[0]:+.1f},{s[1]:+.1f})"
                                  f" from {len(e.shift.meas)} clicks" + (", jump" if np.any(e.shift.jump) else ""))
-                    e.frames = e.found = 0
+                    e.frames = e.found = e.refused = 0
                     e.work = 0.0
                 print("ft-eyes: " + "; ".join(parts), file=sys.stderr, flush=True)
             report = now
+            if now - guard_at >= GUARD_REPORT:
+                guard_at, guard_was, line = now, *guard_line(tracker.guard, guard_was)
+                if line and not NET:
+                    print("ft-eyes: " + line, file=sys.stderr, flush=True)
             if cams.replaced():
                 print("ft-eyes: frames went away; waiting", file=sys.stderr, flush=True)
                 cams = wait_for_cams(sock, tracker, want)

hand-recorder.md

@@ -54,7 +54,7 @@ The [standalone recorder's README](https://github.com/Frametop/frametop-hand-rec
    curl -fsSL https://frametop.github.io/frametop/get.sh | bash -s -- --release --experimental
    ```
 
-   This downloads Frametop's newest experimental release (about 1.4 GB) and installs it without compiling anything. The installer asks what to install: say yes to the Hand Recorder, and to hand tracking if you want to record testing sessions. It asks for your `sudo` password for those. At the end SteamVR restarts, which closes Konsole. If Frametop is already installed, the same command updates it, and the Hand Recorder with it.
+   This downloads Frametop's newest experimental release (about 1.2 GB) and installs it without compiling anything. The installer asks what to install: say yes to the Hand Recorder, and to hand tracking if you want to record testing sessions. It asks for your `sudo` password for those. At the end SteamVR restarts, which closes Konsole. If Frametop is already installed, the same command updates it, and the Hand Recorder with it.
 4. Choose Launch a program → Desktop again, and open Frametop Hand Recorder from the application menu.
 
 Installing `Frametop.zip` with [FrameDrop](https://framedropvr.com), or by hand from the [releases](https://github.com/Frametop/frametop/releases), works too: leave Hand Recorder ticked in the installer's window.

hands/rec/CONSENT.md

@@ -43,7 +43,7 @@ The recorder doesn't record sound, your name, your email address or your Steam a
 
 - Recordings stay on your headset, in `~/.local/share/frametop/hands/contrib`. Nothing is uploaded automatically.
 - Before you share anything, you can watch every recording in the Review page. You can delete any stretch of a recording, a whole take or a whole session. Export leaves out what you deleted.
-- You upload the export yourself, from the Upload page. That opens a pull request on the dataset. The maintainer checks it before it becomes part of the dataset, and may decline it. Until it's merged, you can close the pull request yourself.
+- You upload the export yourself: from the Upload page, or with Export and upload, which sends it once it's exported. That opens a pull request on the dataset. The maintainer checks it before it becomes part of the dataset, and may decline it. Until it's merged, you can close the pull request yourself.
 
 ## Where it goes
 

hands/rec/DESIGN.md

@@ -65,6 +65,7 @@ Test hooks:
 ```
 ~/.local/share/frametop/hands/contrib/
   profile.json                  consent and contributor id (below)
+  contributions.json            every finished upload, kept when its session is deleted (Review and export, "Freeing space")
   sessions/<YYYYMMDD-HHMMSS>/   (a second session started in the same second gets -2, and so on)
     session.json                the session: checklist answers, lighting, versions, mode, takes
     calibration.json            /persist/xrservice.json with identifying fields removed (below)
@@ -401,7 +402,7 @@ Short rounds (about 3 min recorded, 4 with reading) of what the hand tracker nee
 
 - `bounties.json` is the board: `{"schema": 1, "updated", "bounties": [{"id", "title", "blurb", "minutes", "priority", "script"}]}`. A newer copy fetched from the dataset (`hub.py board`, the window's "Get the newest board", into `BASE/board-cache.json`) can only describe, reorder, reprioritise or retire bounties: each one's steps come from `bounties/<script>.json`, shipped with the recorder. A bounty whose script this recorder lacks shows "Needs a newer recorder".
 - A round script is a normal script (above) with `"record_hz": 30`: hand size first (the no-hands check), then one scene section, and at most 30 s of plain steps after it when a gesture needs no window (the palm up). At 30 sets a second a round is about 2.5 min recorded, about 2.1 MB a second exported.
-- The window opens on the Bounties page: the board by priority, then least done first, then in the board's own order (a fetched board ranks bounties of one priority by listing them; before 2026-10-15 the title broke ties), each with Record (Record again once done), "Get the newest board", and below them the full session and the quick round. Picking a round goes to the consent page if this contributor hasn't agreed to the current version, else straight to the checklist; the checklist's Round section shows the pick (or the full/quick choice) with "Pick another…" back to the board, and hides what a bounty doesn't use (objects within reach, controllers, guidance). Its camera check and Start then run the script (`session.py --bounty ID`; `--board` lists them). When the round is done, the Session page's "Export and upload" exports it and opens the Upload page for that export once the export finishes (`exportDone`). session.json gets `"bounty"`, the upload's title and description name it, and Review shows its title by the session. A round that ends `done` (not a dry run) counts in profile.json's `bounties`.
+- The window opens on the Bounties page: the board by priority, then least done first, then in the board's own order (a fetched board ranks bounties of one priority by listing them; before 2026-10-15 the title broke ties), each with Record (Record again once done), "Get the newest board", and below them the full session and the quick round. Picking a round goes to the consent page if this contributor hasn't agreed to the current version, else straight to the checklist; the checklist's Round section shows the pick (or the full/quick choice) with "Pick another…" back to the board, and hides what a bounty doesn't use (objects within reach, controllers, guidance). Its camera check and Start then run the script (`session.py --bounty ID`; `--board` lists them). When the round is done, the Session page's "Export and upload" queues its export to upload by itself once exported (logged in), or else exports it and opens the Upload page for that export once the export finishes (`exportDone`). session.json gets `"bounty"`, the upload's title and description name it, and Review shows its title by the session. A round that ends `done` (not a dry run) counts in profile.json's `bounties`.
 
 The first four (2026-10-14), each on the gestures Frametop uses:
 
@@ -450,6 +451,10 @@ The board can list one script under two bounties: `daylight-taps` is the index-t
   Compression runs at nice 19. While it runs with the headset worn, the window notes that VR may stutter a little (exports are done in the headset). Worn is judged the way `frame-job` does: `vrcompositor` runs and a `/sys/class/backlight/*/brightness` reads over 0 (SteamVR turns the panel off 5 s after the headset comes off). CPU work while in VR causes stutter. The proximity sensor is no use here: it read 9-43 with the headset sitting unworn.
 
   Free space and zstd's pipe (2026-10-15). An export is about three quarters of the recording (2026-10-14's 15 GB sessions made 11 GB exports), so a round that fit can leave too little room for its export. Export refuses to start with less than half the kept recording free, and a disk that fills up as it goes ends it with what's free, about what it needs, and the old export it would replace (that one stays until the new one is done), not with "Broken pipe" (`takes.DiskFull`). zstd's messages go to a temporary file, so a zstd that ends early (a full disk, a signal) leaves its own words as the error (`takes.ZstdStopped`), and one that writes a lot can't stall the export. A testing session's encryption drains zstd a piece at a time when it fails. The window reads hub.py's stderr as it comes for the same reason: read only at the end, retry warnings on a bad network could fill the pipe and stall the upload. `tests/test_export_pipes.py` and `recorder/tests/test_window_pipes.py` cover these.
+
+  Room to export (2026-10-17). A user's middle-taps export kept failing with "Broken pipe" on rc3: the round passed the 16 GB check before recording, then filled the disk while exporting, with earlier rounds still kept. The Frame's five exports measured 0.72 to 0.76 of their recordings. Now a round needs room for its recording and its export before it starts (`ft_handrec.ROUND_BYTES`: 16 GB plus `takes.export_need` of it, about 31 GB), export needs 0.8 of the kept recording plus 2 GB to start (`takes.export_need`), and it stops itself, removing its half, when the disk gets down to 1.5 GB (`takes.check_room`, as the session stops recording at 1.5 GB), so a full home disk never takes SteamVR and Steam down with it. `tests/test_free_space.py` covers these.
+
+  Freeing space (2026-10-17). Nothing is deleted after an upload by itself, and a session's uploads were recorded only in its session.json, so deleting it lost the record. `contributions.json` (`recorder/contributions.py`) now keeps one entry per finished upload: session, bounty, consent kind, dataset, pull request, upload time, export size, and `local_deleted` once its local copy is gone. hub.py adds the entry when an upload finishes, and the window copies in what older recorders recorded only in session.json when it opens. A session is freeable when a finished upload exists and its recordings haven't changed since (an upload without a readable time: when the export there now is the one uploaded); `Store.free_session` writes the log entry first, then deletes the recordings and export, so a log that can't be written deletes nothing. The window offers it per session on Review ("Free up space"), for all of them on Review, on Before you start when there isn't room for a round, on Export after a failed export, and on Upload right after an upload. Review lists "Your uploads" from the log, including the ones deleted here; the board's round counts were already in profile.json, and the testing session's count adds the log's.
 - **Upload.** The Upload page uploads an export from the window, logging in included: no terminal. Below its steps it shows `UPLOAD.md` ("About uploading"), with the export's path, size and contributor id filled in.
   - **`hands/rec/validate.py`** (standard library) checks an export. The window runs it before an upload, and the maintainer runs it on each submission (`validate.py DIR [--json]`, exit status 1 on errors). It checks:
     - `SHA256SUMS`: every file listed and matching.
@@ -485,7 +490,9 @@ The board can list one script under two bounties: `daylight-taps` is the index-t
     2. Log in to Hugging Face. The page shows whether someone is logged in (`whoami`). Log in runs `hub.py login`, opens the link in the browser, and shows the code large, with Copy code and Cancel. "Use another account" logs in again. A classic read-only token counts as not logged in.
     3. Upload, with a note to accept the dataset's terms the first time.
 
-    Upload has Cancel, the phase with a progress bar (a share while the export is checked, a sweep while it's sent, as `huggingface_hub` reports no progress), the pull request's link once it's open, with "plug in the headset and leave it plugged in until this says Uploaded", and Uploaded at the end. If this export was uploaded before, the page says so, and uploading it again asks first. A stale export can't be uploaded.
+    Upload has Cancel, the phase with a progress bar (a share while the export is checked, a sweep while it's sent, as `huggingface_hub` reports no progress), the pull request's link once it's open, with "plug in the headset and leave it plugged in until this says Uploaded", and Uploaded at the end. If this export was uploaded before, the page says so, and uploading it again asks first. A stale export can't be uploaded. An export and an upload of different sessions run together (2026-10-17: Upload used to wait for any export); a session's own export and upload wait for each other, since an export replaces its old one when it ends. One export and one upload at a time. `tests/test_upload_during_export.py` covers it.
+
+    Exports queue (2026-10-17, "so they don't have to keep coming back to the headset"): Export, or Export and upload, while another export runs puts it in a queue on the Export page, run in order. Export and upload (logged in, and the dataset takes contributions) uploads it by itself once its export is done: uploads wait their turn too, one at a time, and an export uploaded before (the same SHA256SUMS) isn't sent again. Each waiting export has a "then upload" box and Remove; Cancel stops only the running export (and its upload), and the next one starts. A failed export or upload doesn't hold up the rest. The page's Done list says how each went, with the pull request's link, for whoever comes back to the headset. The queue lives in the window: closing it asks, then cancels them all. A session waiting to export or upload can't be deleted, nor its export. The awake unit's workers now bring it to the reasons current when they run, so an export's end and its upload's start can't leave it stopped (`recorder/tests/test_stay_awake.py`). `tests/test_export_queue.py` covers the queue.
   - **Staying awake:** while an export or an upload runs, the window holds a host unit, `frametop-handrec-awake.service`, running `systemd-inhibit --what=sleep:idle --mode=block ... sleep infinity`, and stops it when the last of them ends (or on quit). It's meant to keep Steam from putting the Frame to sleep with the headset off; whether Steam's sleep honours a logind block inhibitor is still to be checked on the device. Exports and uploads are done in the headset: the export page only notes that VR may stutter a little while it compresses.
   - **While the texts are drafts**, Upload stays off unless `FT_HANDREC_ALLOW_UPLOAD=1`, so the maintainer can rehearse against a private test repo. `FT_HANDREC_DATASET` overrides `HF_DATASET`. `ft-handrec --hub-dry-run` makes Upload a dry run: no network, so it isn't held back by the drafts.
   - **Rehearsal: `hands/rec/rehearse.sh [--repo ID]`** runs it all without the headset, in the dev container, in one `frame-job --local` scope when frame-job is installed. `ft-ringplay` plays 30 s of a recording into a ring in `/run/user/UID`. A tracking ft-hands that's already running is used, or one is started on that ring. `ft-handpanel --no-vr` stands in for the panel. `session.py --no-start --next-after 0.3` records a three-section test script (a prompt, a two-cue sweep, no hands) in step mode, three parts of 6 s (countdown and hold), about 360 MB once exported. Then `takes.py` exports, `validate.py` checks, and `hub.py` uploads: a dry run by default, or for real to `--repo ID` with `FT_HANDREC_ALLOW_UPLOAD=1`. It prints a summary, deletes its temporary folders (camera images of a room) and stops everything it started, Ctrl+C included. The `--no-vr` panel logs no poses, so `poses.jsonl` is missing there (a warning).

hands/rec/ft_handrec.py

@@ -21,7 +21,8 @@ A Kirigami (QML) app with a Python backend. It runs in the dev container:
     focus; the button on the headset's right side is Next, pause and resume). The prompts appear
     in the headset. Each step waits for Next unless "Advance by itself" was ticked.
   - Review: sessions, their takes, and a viewer for one frame set at a time, where ranges,
-    takes and sessions can be deleted (takes.py).
+    takes and sessions can be deleted (takes.py). Uploaded sessions can be deleted to free space
+    while the record of their uploads stays (contributions.json), listed under "Your uploads".
   - Export: compress what's kept into exports/<session>/ at nice 19 (takes.py), with a warning
     when the headset is worn.
   - Upload: the Hugging Face login status, and Upload: hub.py checks the export (validate.py)
@@ -85,7 +86,11 @@ DEBUG_ROW = {"id": DEBUG_ID, "title": "Testing session", "priority": "", "minute
 LIVE_HANDS_UNIT = "frametop-hands.service"
 # One window at a time, Frametop's or the standalone one (recorder/one_window.py)
 WINDOW_NAME = "ft_handrec_window"
-ROUND_BYTES = 16 * 1000 ** 3  # about what one round of recording takes (a bounty: 2.5-3 min at 30 sets/s, ~85 MB/s)
+RECORD_BYTES = 16 * 1000 ** 3  # about what one round of recording takes (a bounty: 2.5-3 min at 30 sets/s, ~85 MB/s)
+# The free space a round needs before it starts: the recording, then its export next to it
+# (takes.export_need). Until 2026-10-17 only the recording was asked for, so a round could be
+# recorded that couldn't be exported.
+ROUND_BYTES = RECORD_BYTES + takes.export_need(RECORD_BYTES)
 # The checklist's choices; the keys are what session.json stores.
 OBJECTS = [("pencil", "Pencil or pen"), ("phone", "Phone"), ("cup", "Cup or mug (empty)"),
            ("keyboard", "Keyboard"), ("mouse", "Mouse"), ("gamepad", "Gamepad"),
@@ -239,6 +244,10 @@ class Backend(RecorderBackend):
         self._ready_panel = None     # the ft-handpanel getReady started: ends on quit
         self._readyPart.connect(self._on_ready_part)
         self._readyDone.connect(self._on_ready_done)
+        try:   # uploads older recorders kept only in session.json join the contributions log
+            store.log_uploads()
+        except (OSError, ValueError) as e:
+            print(f"contributions log: {e}", file=sys.stderr, flush=True)
 
     def _texts_draft(self):
         return hub.texts_draft(self._consent_kind)
@@ -257,6 +266,9 @@ class Backend(RecorderBackend):
         except hub.HubError:
             return hub.HF_TEST_DATASET if self._consent_kind == "testing" else hub.HF_DATASET
 
+    def _session_label(self, session):
+        return session_label(session)
+
     def _session_dataset(self, session):
         try:
             return hub.dataset_id(hub.session_kind(self.store, session))
@@ -378,9 +390,12 @@ class Backend(RecorderBackend):
         return self._frametop_hands
 
     def _debug_row(self):
-        """The testing session as a row of the board (bounties.view's keys)."""
-        done = [s for s in self.store.sessions() if s.get("debug") and s["status"] == "done" and not s["dry_run"]]
-        return dict(DEBUG_ROW, done=len(done), last=done[0]["id"] if done else "", available="")
+        """The testing session as a row of the board (bounties.view's keys). Uploaded ones whose
+        local copy was deleted count from the contributions log."""
+        done = {s["id"] for s in self.store.sessions() if s.get("debug") and s["status"] == "done" and not s["dry_run"]}
+        done |= {c["session"] for c in self.store.contributions() if c.get("debug")}
+        last = max(done) if done else ""
+        return dict(DEBUG_ROW, done=len(done), last=last, available="")
 
     @Property(str, notify=boardChanged)
     def boardUpdated(self):
@@ -704,6 +719,8 @@ class Backend(RecorderBackend):
             return "exporting a recording"
         if self.uploading:
             return "uploading a recording"
+        if self._upload_queue:
+            return "waiting to upload a recording"
         return ""
 
     def shutdown(self):
@@ -800,6 +817,9 @@ class Backend(RecorderBackend):
             s["active"] = self.sessionActive and s["id"] == self._session_id
             s["statusText"] = {"recording": "" if s["active"] else "interrupted", "error": "ended with an error",
                                "stopped": "stopped early"}.get(s["status"], "")
+            s["freeable"] = s["freeable"] and not s["active"]
+            s["freeText"] = takes.human_bytes(s["bytes"] + s["export_bytes"])
+            s["uploadText"] = ("uploaded" if s["freeable"] else "uploaded, changed since") if s["uploaded"] else ""
             out.append(s)
         return out
 
@@ -872,7 +892,7 @@ class Backend(RecorderBackend):
 
     @Slot(str)
     def deleteSession(self, session):
-        if self._active_guard(session):
+        if self._active_guard(session) or self._busy_guard(session):
             return
         try:
             self.store.delete_session(session)
@@ -881,6 +901,84 @@ class Backend(RecorderBackend):
             self.message.emit(f"Couldn't delete the session: {e}", True)
         self.refreshSessions()
 
+    # --- freeing space: uploaded rounds' local copies go, the contributions log keeps the record
+    def _freeable(self):
+        busy = {self._session_id if self.sessionActive else "", self._export_session if self.exporting else "",
+                (self._upload or {}).get("session", "") if self.uploading else ""}
+        return [f for f in self.store.freeable() if f["id"] not in busy and not self._queued(f["id"])]
+
+    @Property(int, notify=sessionsRelay)
+    def freeableCount(self):
+        """Uploaded rounds whose local copies can be deleted (nothing changed since the upload)."""
+        return len(self._freeable())
+
+    @Property(str, notify=sessionsRelay)
+    def freeableText(self):
+        """What deleting them all frees, "" when nothing can go."""
+        rows = self._freeable()
+        return takes.human_bytes(sum(f["bytes"] for f in rows)) if rows else ""
+
+    @Property(str, constant=True)
+    def roundNeedText(self):
+        return gigabytes(self.ROUND_BYTES)
+
+    @Property("QVariantList", notify=sessionsRelay)
+    def contributions(self):
+        """The contributions log for the Review page, newest first: {session, label, title,
+        uploadedText, prUrl, prText, local, testing}."""
+        out = []
+        for c in self.store.contributions():
+            title = (c.get("bounty") or {}).get("title") or ("Testing session" if c.get("debug") else "Session")
+            when = (c.get("uploaded") or "")[:10]
+            out.append({"session": c["session"], "label": session_label(c["session"]), "title": title,
+                        "uploadedText": f"uploaded {when}" if when else "uploaded",
+                        "prUrl": c.get("pr_url", ""), "prText": f"pull request #{c['pr_num']}" if c.get("pr_num") else "",
+                        "local": c["local"], "testing": c.get("kind") == "testing",
+                        "deletedText": "deleted here, still in your record" if not c["local"] else ""})
+        return out
+
+    def _free(self, sids):
+        freed, failed = 0, []
+        for sid in sids:
+            try:
+                freed += self.store.free_session(sid)
+            except (OSError, ValueError) as e:
+                failed.append(f"{session_label(sid)}: {e}")
+        return freed, failed
+
+    @Slot(str)
+    def freeSession(self, session):
+        """Delete one uploaded session's recordings and export; its record stays."""
+        if self._active_guard(session):
+            return
+        if session not in {f["id"] for f in self._freeable()}:
+            self.message.emit("Only an uploaded round, unchanged since its upload, can be deleted this way", True)
+            return
+        freed, failed = self._free([session])
+        if failed:
+            self.message.emit("Couldn't delete it: " + failed[0], True)
+        else:
+            self.message.emit(f"Deleted the local copy of {session_label(session)}: {takes.human_bytes(freed)} freed. "
+                              "Your record of the upload stays.", False)
+        self.refreshSessions()
+
+    @Slot()
+    def freeAllUploaded(self):
+        """Delete every uploaded, unchanged round's local copy; their records stay."""
+        sids = [f["id"] for f in self._freeable()]
+        if not sids:
+            self.message.emit("No uploaded rounds to delete", False)
+            return
+        freed, failed = self._free(sids)
+        done = len(sids) - len(failed)
+        if failed:
+            self.message.emit(f"Deleted {done} of {len(sids)} rounds ({takes.human_bytes(freed)} freed). "
+                              "Couldn't delete " + "; ".join(failed), True)
+        else:
+            self.message.emit(f"Deleted {done} uploaded round{'s' if done != 1 else ''}: {takes.human_bytes(freed)} "
+                              "freed. Your record of the uploads stays.", False)
+        self.refreshSessions()
+
     # --- export
     @Property(bool, constant=True)
     def zstdFound(self):

hands/rec/hub.py

@@ -21,7 +21,9 @@ An upload:
      and records it under "uploads" in session.json with "status": "started";
   6. upload_folder(..., revision="refs/pr/N") to contributions/<contributor>/<session>; a retry of
      the same export goes on in the same pull request while it's still open;
-  7. marks the record {"repo", "pr_url", "pr_num", "uploaded", "export_sha", "status": "done"}.
+  7. marks the record {"repo", "pr_url", "pr_num", "uploaded", "export_sha", "status": "done"},
+     and adds it to BASE/contributions.json (recorder/contributions.py), which outlives the
+     session: deleting the local copy to free space keeps it.
 --dry-run does all of it except the network calls (4 to 6) and recording (5, 7), and says what
 it would upload.
 
@@ -53,6 +55,7 @@ sys.path.insert(0, HERE)
 import takes  # noqa: E402  (next to this file)
 sys.path.insert(0, os.path.dirname(os.path.dirname(HERE)))
 from recorder import bounties  # noqa: E402
+from recorder import contributions  # noqa: E402
 from recorder import hub as rhub  # noqa: E402
 from recorder.hub import HF_ENV, REPO_RE, TOKENS_URL, HubError, explain, export_sha, is_draft, now_iso  # noqa: E402,F401
 
@@ -275,6 +278,11 @@ def upload(store, session, dry_run=False, again=False, progress=None, log=None):
 
     pr, who, record = rhub.push(_hf(), repo, export, path_in_repo, message, description, meta_path(store, session), sha,
                                 len(files), report.bytes, tell, takes.write_json, takes.human_bytes)
+    try:   # the log is for the contributor's own record: a failure to write it doesn't undo the upload
+        contributions.add(store.base, [contributions.entry(session, takes.read_json(meta_path(store, session)), record,
+                                                           report.bytes, summary.get("minutes"))])
+    except OSError as e:
+        say(f"couldn't add the upload to {contributions.FILE}: {e}")
     tell("done", "Uploaded", 1.0)
     return dict(plan, dry_run=False, pr_url=record["pr_url"], pr_num=pr.num, user=who.get("name", ""), record=record)
 

hands/rec/main.qml

@@ -85,6 +85,24 @@ Kirigami.ApplicationWindow {
         return n + " " + word + (n === 1 ? "" : "s")
     }
 
+    // A session's label, from its id (the Export page's queue).
+    function sessionLabel(id) {
+        for (const s of backend.sessions)
+            if (s.id === id)
+                return s.label
+        return id
+    }
+    // The session's export can upload by itself once done: logged in, and its dataset takes
+    // contributions (or a dry run).
+    function canUploadAfter(id) {
+        return backend.canUploadAfter && (backend.hubDryRun || backend.uploadAllowedFor(id))
+    }
+    // Waiting to export, or exporting now.
+    function exportPending(id) {
+        return backend.exportSessionId === id && backend.exporting
+               || backend.exportQueue.some(q => q.session === id)
+    }
+
     function show(page) {
         pageStack.clear()
         pageStack.push(page)
@@ -137,6 +155,23 @@ Kirigami.ApplicationWindow {
         }
     }
 
+    // Freeing space: an uploaded round's recordings and export go, the record of its upload
+    // stays (contributions.json, listed on the Review page).
+    function askFreeAll() {
+        confirm.ask("Delete the uploaded rounds here?",
+                    root.plural(backend.freeableCount, "uploaded round") + " (" + backend.freeableText + ") are deleted "
+                    + "from the headset: their recordings and exports. They're already in your pull requests, and "
+                    + "your record of each upload stays on the Review page.",
+                    () => backend.freeAllUploaded())
+    }
+    function askFree(row, after) {
+        const sid = row.id
+        confirm.ask("Delete the local copy?",
+                    "The session of " + row.label + " is uploaded (" + row.pr_url + "). Its recordings and export ("
+                    + row.freeText + ") are deleted from the headset; your record of the upload stays on the Review page.",
+                    () => { if (after) after(); backend.freeSession(sid) })
+    }
+
     // Restart SteamVR (the camera check's fix). What it does to Frametop, read from the code
     // (hands/README.md, "Camera check"): ft-screens quits when SteamVR does, which ends the
     // desktop; its unit doesn't restart, and stopping it ends what was started in it.
@@ -180,9 +215,11 @@ Kirigami.ApplicationWindow {
             close.accepted = false
             confirm.ask("Stop the session?", "A session is recording. Closing stops it; what's recorded so far is kept.",
                         () => { root.quitting = true; Qt.quit() })
-        } else if (backend.uploading && !quitting) {
+        } else if ((backend.uploading || backend.exporting || backend.uploadQueue.length > 0) && !quitting) {
             close.accepted = false
-            confirm.ask("Cancel the upload?", "An upload is running. Closing cancels it; you can start it again later.",
+            confirm.ask("Cancel the exports and uploads?",
+                        "An export or upload is running or waiting (the Export page lists them). Closing cancels "
+                        + "them all; an export cancelled keeps nothing. You can start them again later.",
                         () => { root.quitting = true; Qt.quit() })
         }
     }
@@ -661,15 +698,26 @@ Kirigami.ApplicationWindow {
                 Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Space" }
                 Controls.Label {
                     Kirigami.FormData.label: "Free space:"
-                    text: backend.freeText + " (a round takes about 15 GB, and its export about 12 GB more)"
+                    text: backend.freeText + " (a round needs about " + backend.roundNeedText
+                          + ": about 16 GB to record and 15 GB to export it)"
                 }
                 Kirigami.InlineMessage {
                     Layout.maximumWidth: Kirigami.Units.gridUnit * 26
                     Layout.fillWidth: true
                     visible: !backend.diskOk
                     type: Kirigami.MessageType.Error
-                    text: "Not enough free space for a round. Export and delete earlier sessions (Review), "
-                          + "or free up space, first."
+                    text: "Not enough free space for a round and its export. "
+                          + (backend.freeableCount > 0
+                             ? root.plural(backend.freeableCount, "uploaded round") + " can go to free "
+                               + backend.freeableText + ": your record of each upload stays."
+                             : "Delete sessions you don't need (Review), or free up space, first.")
+                    actions: backend.freeableCount > 0 ? [freeAllBefore] : []
+                    Kirigami.Action {
+                        id: freeAllBefore
+                        text: "Delete uploaded rounds"
+                        icon.name: "edit-delete"
+                        onTriggered: root.askFreeAll()
+                    }
                 }
 
                 Kirigami.Separator { Kirigami.FormData.isSection: true; Kirigami.FormData.label: "Cameras" }
@@ -1328,15 +1376,22 @@ Kirigami.ApplicationWindow {
                         icon.name: "media-playback-stop"
                         onClicked: backend.stopSession()
                     }
+                    // Logged in: the export uploads by itself once done (queued behind any other).
+                    // Not yet: the Upload page follows the export, to log in there.
                     Controls.Button {
-                        visible: !backend.sessionActive && backend.sessionId !== "" && !backend.exporting
+                        visible: !backend.sessionActive && backend.sessionId !== ""
+                        enabled: !root.exportPending(backend.sessionId)
                         focusPolicy: Qt.NoFocus
                         text: "Export and upload"
                         icon.name: "cloud-upload"
                         onClicked: {
                             root.chosenSession = backend.sessionId
-                            root.sendAfterExport = true
-                            backend.exportSession(backend.sessionId, false)
+                            if (root.canUploadAfter(backend.sessionId)) {
+                                backend.queueExport(backend.sessionId, false, true)
+                            } else {
+                                root.sendAfterExport = true
+                                backend.exportSession(backend.sessionId, false)
+                            }
                             root.show(exportPage)
                         }
                     }
@@ -1368,10 +1423,58 @@ Kirigami.ApplicationWindow {
                 model: backend.sessions
                 spacing: Kirigami.Units.smallSpacing
 
+                header: ColumnLayout {
+                    width: ListView.view.width
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        Layout.bottomMargin: visible ? Kirigami.Units.smallSpacing : 0
+                        visible: backend.freeableCount > 0
+                        type: Kirigami.MessageType.Information
+                        text: root.plural(backend.freeableCount, "uploaded round") + " can be deleted here to free "
+                              + backend.freeableText + ". Your record of each upload stays, below."
+                        actions: [
+                            Kirigami.Action {
+                                text: "Delete uploaded rounds"
+                                icon.name: "edit-delete"
+                                onTriggered: root.askFreeAll()
+                            }
+                        ]
+                    }
+                }
+
+                // The contributions log: every upload, kept when its local copy is deleted.
+                footer: ColumnLayout {
+                    width: ListView.view.width
+                    visible: backend.contributions.length > 0
+                    spacing: Kirigami.Units.smallSpacing
+                    Kirigami.Heading {
+                        Layout.topMargin: Kirigami.Units.largeSpacing
+                        Layout.leftMargin: Kirigami.Units.largeSpacing
+                        level: 3
+                        text: "Your uploads"
+                    }
+                    Repeater {
+                        model: backend.contributions
+                        delegate: Controls.Label {
+                            required property var modelData
+                            Layout.fillWidth: true
+                            Layout.leftMargin: Kirigami.Units.largeSpacing
+                            Layout.rightMargin: Kirigami.Units.largeSpacing
+                            wrapMode: Text.Wrap
+                            textFormat: Text.StyledText
+                            text: "<b>" + modelData.title + "</b> · " + modelData.label + " · " + modelData.uploadedText
+                                  + (modelData.prUrl ? " · <a href=\"" + modelData.prUrl + "\">" + (modelData.prText || "pull request") + "</a>" : "")
+                                  + (modelData.testing ? " · testing" : "")
+                                  + (modelData.deletedText ? " · " + modelData.deletedText : "")
+                            onLinkActivated: link => Qt.openUrlExternally(link)
+                        }
+                    }
+                }
+
                 Kirigami.PlaceholderMessage {
                     anchors.centerIn: parent
                     width: parent.width - Kirigami.Units.gridUnit * 4
-                    visible: parent.count === 0
+                    visible: parent.count === 0 && backend.contributions.length === 0
                     text: "No sessions yet"
                     explanation: "Recorded sessions appear here, to watch and trim before you export them."
                 }
@@ -1407,8 +1510,18 @@ Kirigami.ApplicationWindow {
                                       + (sessionRow.modelData.lightingText ? " · " + sessionRow.modelData.lightingText : "")
                                       + (sessionRow.modelData.export_stale ? " · changed since its export"
                                          : sessionRow.modelData.exported ? " · exported (" + sessionRow.modelData.exportText + ")" : "")
+                                      + (sessionRow.modelData.uploadText ? " · " + sessionRow.modelData.uploadText : "")
                             }
                         }
+                        Controls.ToolButton {
+                            icon.name: "edit-clear-all"
+                            text: "Free up space: delete the local copy, keep the record of the upload"
+                            display: Controls.AbstractButton.IconOnly
+                            visible: sessionRow.modelData.freeable
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: root.askFree(sessionRow.modelData, () => pageStack.pop(pageStack.items[0]))
+                        }
                         Controls.ToolButton {
                             icon.name: "edit-delete"
                             text: "Delete session"
@@ -1722,6 +1835,12 @@ Kirigami.ApplicationWindow {
                         return s
                 return null
             }
+            // The chosen session is exporting, or waiting to.
+            readonly property bool pending: chosen !== null && root.exportPending(chosen.id)
+            readonly property bool canExport: chosen !== null && !pending && backend.zstdFound && !chosen.active
+                                              && !(backend.uploading && backend.upload.session === chosen.id)
+                                              && backend.uploadQueue.indexOf(chosen.id) < 0
+            Component.onCompleted: if (backend.login.state === "unknown") backend.checkLogin()
 
             Timer {
                 interval: 5000
@@ -1740,6 +1859,15 @@ Kirigami.ApplicationWindow {
                     type: Kirigami.MessageType.Information
                     text: "Exporting your session: the Upload page follows by itself once it's done."
                 }
+                Kirigami.InlineMessage {
+                    Layout.fillWidth: true
+                    visible: backend.uploadAfter.length + backend.uploadQueue.length > 0
+                    position: Kirigami.InlineMessage.Position.Header
+                    type: Kirigami.MessageType.Positive
+                    text: "You can take the headset off and leave it plugged in: it stays awake until the "
+                          + "exports and uploads below are done, and they show here how they went. Keep this "
+                          + "window open: closing it cancels them."
+                }
                 Kirigami.InlineMessage {
                     Layout.fillWidth: true
                     visible: exportView.worn && backend.exporting
@@ -1764,7 +1892,6 @@ Kirigami.ApplicationWindow {
                     model: backend.sessions
                     textRole: "label"
                     valueRole: "id"
-                    enabled: !backend.exporting
                     Component.onCompleted: {
                         const i = indexOfValue(root.chosenSession)
                         currentIndex = i >= 0 ? i : (count > 0 ? 0 : -1)
@@ -1780,32 +1907,73 @@ Kirigami.ApplicationWindow {
                     Kirigami.FormData.label: "Export:"
                     visible: exportView.chosen !== null
                     text: !exportView.chosen ? ""
+                          : exportView.pending ? (backend.exportSessionId === exportView.chosen.id && backend.exporting
+                                                  ? "exporting now" : "waiting its turn, below")
                           : exportView.chosen.export_stale ? "changed since it was exported: export it again"
                           : exportView.chosen.exported ? "ready, " + exportView.chosen.exportText : "not exported yet"
                 }
+                // Exports run one at a time; one asked for meanwhile waits its turn. "Export and
+                // upload" sends it by itself once it's exported.
                 RowLayout {
                     Controls.Button {
-                        text: backend.exporting ? "Exporting…"
-                              : exportView.chosen && exportView.chosen.exported ? "Export again" : "Export"
+                        text: exportView.chosen && exportView.chosen.exported ? "Export again" : "Export"
                         icon.name: "document-export"
-                        enabled: exportView.chosen !== null && !backend.exporting && backend.zstdFound
-                                 && !exportView.chosen.active
-                        onClicked: backend.exportSession(exportView.chosen.id, false)
+                        enabled: exportView.canExport
+                        onClicked: backend.queueExport(exportView.chosen.id, false, false)
                     }
+                    Controls.Button {
+                        text: "Export and upload"
+                        icon.name: "cloud-upload"
+                        enabled: exportView.canExport && root.canUploadAfter(exportView.chosen.id)
+                        onClicked: backend.queueExport(exportView.chosen.id, false, true)
+                    }
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    visible: exportView.chosen !== null && !backend.hubDryRun
+                             && (!backend.canUploadAfter || !backend.uploadAllowedFor(exportView.chosen.id))
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: !backend.canUploadAfter ? "To upload by itself once exported, log in on the Upload page first."
+                          : "Contributions aren't open yet, so it can't upload by itself."
+                }
+                Controls.Label {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    visible: backend.exporting && exportView.chosen !== null && !exportView.pending
+                    wrapMode: Text.Wrap
+                    opacity: 0.7
+                    text: "Another export is running: this one waits its turn."
+                }
+
+                // The running export
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Exporting now"
+                    visible: backend.exporting
+                }
+                RowLayout {
+                    Kirigami.FormData.label: "Session:"
+                    visible: backend.exporting
+                    Controls.Label { text: root.sessionLabel(backend.exportSessionId) }
                     // Shows the moment Export is pressed: the first progress can take a few seconds.
                     Controls.BusyIndicator {
-                        visible: backend.exporting
-                        running: visible
+                        running: backend.exporting
                         implicitWidth: Kirigami.Units.gridUnit * 1.5
                         implicitHeight: implicitWidth
                     }
                     Controls.Button {
-                        visible: backend.exporting
                         text: "Cancel"
                         icon.name: "dialog-cancel"
                         onClicked: { root.sendAfterExport = false; backend.cancelExport() }
                     }
                 }
+                Controls.CheckBox {
+                    visible: backend.exporting
+                    text: "Upload it once exported"
+                    checked: backend.uploadAfter.indexOf(backend.exportSessionId) >= 0
+                    enabled: checked || root.canUploadAfter(backend.exportSessionId)
+                    onToggled: backend.setUploadAfter(backend.exportSessionId, checked)
+                }
                 // Drawn here: the desktop style's ProgressBar paints nothing without a QApplication.
                 Rectangle {
                     Kirigami.FormData.label: "Progress:"
@@ -1827,8 +1995,23 @@ Kirigami.ApplicationWindow {
                     wrapMode: Text.WrapAnywhere
                     text: backend.exportText
                 }
+                Kirigami.InlineMessage {
+                    Layout.maximumWidth: Kirigami.Units.gridUnit * 26
+                    Layout.fillWidth: true
+                    visible: !backend.exporting && backend.exportText.indexOf("Failed") === 0 && backend.freeableCount > 0
+                    type: Kirigami.MessageType.Information
+                    text: root.plural(backend.freeableCount, "uploaded round") + " can be deleted to free "
+                          + backend.freeableText + ". Your record of each upload stays."
+                    actions: [
+                        Kirigami.Action {
+                            text: "Delete uploaded rounds"
+                            icon.name: "edit-delete"
+                            onTriggered: root.askFreeAll()
+                        }
+                    ]
+                }
                 RowLayout {
-                    visible: exportView.chosen !== null && exportView.chosen.exported && !backend.exporting
+                    visible: exportView.chosen !== null && exportView.chosen.exported && !exportView.pending
                     Controls.Button {
                         text: "Upload"
                         icon.name: "go-next"
@@ -1837,6 +2020,8 @@ Kirigami.ApplicationWindow {
                     Controls.Button {
                         text: "Delete export"
                         icon.name: "edit-delete"
+                        enabled: !(backend.uploading && backend.upload.session === exportView.chosen.id)
+                                 && backend.uploadQueue.indexOf(exportView.chosen.id) < 0
                         onClicked: {
                             const sid = exportView.chosen.id
                             confirm.ask("Delete this export?", "The export is deleted; the session's recordings stay.",
@@ -1844,6 +2029,107 @@ Kirigami.ApplicationWindow {
                         }
                     }
                 }
+
+                // Waiting: exports, then uploads
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Waiting to export"
+                    visible: backend.exportQueue.length > 0
+                }
+                Repeater {
+                    model: backend.exportQueue
+                    delegate: RowLayout {
+                        required property var modelData
+                        required property int index
+                        Kirigami.FormData.label: (index + 1) + "."
+                        Controls.Label { text: root.sessionLabel(modelData.session) }
+                        Controls.CheckBox {
+                            text: "then upload"
+                            checked: modelData.upload
+                            enabled: checked || root.canUploadAfter(modelData.session)
+                            onToggled: backend.setUploadAfter(modelData.session, checked)
+                        }
+                        Controls.ToolButton {
+                            icon.name: "list-remove"
+                            text: "Remove"
+                            display: Controls.AbstractButton.IconOnly
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: backend.unqueueExport(modelData.session)
+                        }
+                    }
+                }
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Uploading"
+                    visible: backend.uploading || backend.uploadQueue.length > 0
+                }
+                RowLayout {
+                    Kirigami.FormData.label: "Now:"
+                    visible: backend.uploading
+                    Controls.Label {
+                        text: root.sessionLabel(backend.upload.session || "") + (backend.upload.text ? ": " + backend.upload.text : "")
+                    }
+                    Controls.Button {
+                        text: "Show"
+                        icon.name: "go-next"
+                        flat: true
+                        onClicked: { root.chosenSession = backend.upload.session; root.show(uploadPage) }
+                    }
+                }
+                Repeater {
+                    model: backend.uploadQueue
+                    delegate: RowLayout {
+                        required property var modelData
+                        required property int index
+                        Kirigami.FormData.label: "Then:"
+                        Controls.Label { text: root.sessionLabel(modelData) }
+                        Controls.ToolButton {
+                            icon.name: "list-remove"
+                            text: "Don't upload it"
+                            display: Controls.AbstractButton.IconOnly
+                            Controls.ToolTip.text: text
+                            Controls.ToolTip.visible: hovered
+                            onClicked: backend.unqueueUpload(modelData)
+                        }
+                    }
+                }
+
+                // How they went, for whoever comes back to the headset
+                Kirigami.Separator {
+                    Kirigami.FormData.isSection: true
+                    Kirigami.FormData.label: "Done"
+                    visible: backend.doneLog.length > 0
+                }
+                Repeater {
+                    model: backend.doneLog
+                    delegate: RowLayout {
+                        required property var modelData
+                        Kirigami.Icon {
+                            source: modelData.error ? "dialog-error" : "checkmark"
+                            implicitWidth: Kirigami.Units.iconSizes.small
+                            implicitHeight: implicitWidth
+                        }
+                        Controls.Label {
+                            Layout.maximumWidth: Kirigami.Units.gridUnit * 24
+                            wrapMode: Text.Wrap
+                            text: modelData.text
+                        }
+                        Controls.ToolButton {
+                            visible: modelData.link !== ""
+                            icon.name: "internet-services"
+                            text: "Open"
+                            onClicked: Qt.openUrlExternally(modelData.link)
+                        }
+                    }
+                }
+                Controls.Button {
+                    visible: backend.doneLog.length > 0
+                    text: "Clear"
+                    icon.name: "edit-clear-history"
+                    flat: true
+                    onClicked: backend.clearDoneLog()
+                }
             }
 
             footer: Controls.Label {
@@ -1852,8 +2138,8 @@ Kirigami.ApplicationWindow {
                 opacity: 0.7
                 text: "Export leaves out the ranges you deleted, compresses the rest and adds a manifest and "
                       + "checksums, in " + backend.exportsDir + ". It runs at the lowest priority "
-                      + "and takes a few minutes per round; the headset stays awake until it's done. Nothing is "
-                      + "uploaded until you press Upload on the Upload page."
+                      + "and takes a few minutes per round, one at a time; the headset stays awake until they're "
+                      + "done. Nothing is uploaded unless you press Export and upload here, or Upload on the Upload page."
             }
         }
     }
@@ -1879,7 +2165,7 @@ Kirigami.ApplicationWindow {
             readonly property string blocked: {
                 if (session === "") return "Choose an export"
                 if (chosen && chosen.export_stale) return "Export the session again first"
-                if (backend.exporting) return "Wait for the export to finish"
+                if (root.exportPending(session)) return "Wait for its export to finish"
                 if (backend.uploading) return ""
                 if (backend.hubDryRun) return ""
                 if (!backend.uploadAllowedFor(session)) return "Contributions aren't open yet"
@@ -1892,6 +2178,14 @@ Kirigami.ApplicationWindow {
             Connections {
                 target: backend
                 function onSessionsChanged() { uploadView.refreshInfo() }
+                // An upload started by itself (queued on the Export page): show it.
+                function onUploadChanged() {
+                    const i = backend.uploading ? exportBox.indexOfValue(backend.upload.session) : -1
+                    if (i >= 0 && i !== exportBox.currentIndex) {
+                        exportBox.currentIndex = i
+                        exportBox.keep = backend.upload.session
+                    }
+                }
             }
             Component.onCompleted: {
                 refreshInfo()
@@ -1971,8 +2265,19 @@ Kirigami.ApplicationWindow {
                             textRole: "label"
                             valueRole: "id"
                             enabled: !backend.uploading
-                            Component.onCompleted: currentIndex = Math.max(0, indexOfValue(root.chosenSession))
-                            onActivated: root.chosenSession = currentValue
+                            // An export that finishes meanwhile adds a row (newest first): stay on the
+                            // same export, the uploading one while an upload runs.
+                            property string keep: ""
+                            Component.onCompleted: {
+                                currentIndex = Math.max(0, indexOfValue(root.chosenSession))
+                                keep = currentValue || ""
+                            }
+                            onActivated: root.chosenSession = keep = currentValue
+                            onModelChanged: Qt.callLater(() => {
+                                const i = indexOfValue(backend.uploading ? backend.upload.session : keep)
+                                currentIndex = i >= 0 ? i : (count > 0 ? Math.max(0, currentIndex) : -1)
+                                keep = currentValue || ""
+                            })
                         }
                         Controls.Label {
                             opacity: 0.7
@@ -2086,6 +2391,14 @@ Kirigami.ApplicationWindow {
                               + "\">its page</a>. Upload checks the export, opens your pull request, then sends the files."
                         onLinkActivated: link => Qt.openUrlExternally(link)
                     }
+                    Controls.Label {
+                        Layout.fillWidth: true
+                        visible: backend.uploadQueue.length + backend.uploadAfter.length > 0
+                        wrapMode: Text.Wrap
+                        opacity: 0.7
+                        text: "Queued on the Export page to upload after this one, by themselves: "
+                              + root.plural(backend.uploadQueue.length + backend.uploadAfter.length, "export") + "."
+                    }
                     RowLayout {
                         Controls.Button {
                             text: backend.uploading ? "Uploading…" : backend.hubDryRun ? "Upload (dry run)" : "Upload"
@@ -2192,6 +2505,22 @@ Kirigami.ApplicationWindow {
                             onTriggered: backend.copy(uploadView.upResult.pr_url)
                         }
                     }
+                    Kirigami.InlineMessage {
+                        Layout.fillWidth: true
+                        visible: !backend.uploading && uploadView.mine && uploadView.up.phase === "done"
+                                 && !uploadView.upResult.dry_run && uploadView.chosen !== null && uploadView.chosen.freeable
+                        type: Kirigami.MessageType.Information
+                        text: "This round doesn't need to stay on the headset now. Deleting its local copy frees "
+                              + (uploadView.chosen ? uploadView.chosen.freeText : "") + "; your record of the upload "
+                              + "stays on the Review page."
+                        actions: [
+                            Kirigami.Action {
+                                text: "Delete local copy"
+                                icon.name: "edit-clear-all"
+                                onTriggered: root.askFree(uploadView.chosen, null)
+                            }
+                        ]
+                    }
                     Kirigami.InlineMessage {
                         Layout.fillWidth: true
                         visible: !backend.uploading && uploadView.mine && uploadView.up.phase === "failed"

hands/rec/takes.py

@@ -4,6 +4,7 @@
 Standard library only (no Qt, no NumPy), so the window and the command line share it.
 The layout is hands/rec/DESIGN.md's "Files":
   BASE/profile.json
+  BASE/contributions.json  (finished uploads, kept after their sessions go: recorder/contributions.py)
   BASE/sessions/<YYYYMMDD-HHMMSS>/session.json, calibration.json
   BASE/sessions/<id>/takes/<NN>-<section>/sets.bin (sets-2.bin, ... after pauses),
                                           prompts.jsonl, poses.jsonl, take.json
@@ -26,6 +27,7 @@ usage: takes.py [--base DIR] list | takes SESSION | export SESSION | sides SESSI
 import argparse
 import datetime
 import errno
+import hashlib
 import json
 import os
 import re
@@ -35,11 +37,13 @@ import subprocess
 import sys
 import tempfile
 import threading
+import time
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import sides  # noqa: E402  (hands/rec/sides.py, next to this file)
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
 from recorder import age  # noqa: E402  (a debug session's recordings are encrypted)
+from recorder import contributions  # noqa: E402  (the log of uploads that outlives the sessions)
 from recorder.common import tree_version  # noqa: E402
 import eventlog  # noqa: E402  (hands/rec/eventlog.py: a debug session's panel and pointer decisions)
 from recorder.files import (Cancelled, free_bytes, human_bytes, in_ranges, merge_ranges, read_json,  # noqa: E402,F401
@@ -85,10 +89,16 @@ EXPORT_SCHEMA = 1
 # someone is in VR makes the headset stutter).
 ZSTD_ARGS = ["-10", "-T2", "-q", "-c"]
 ZSTD_PATHS = ("/usr/bin/zstd", "/usr/local/bin/zstd", "/run/host/usr/bin/zstd")
-# An export is about three quarters of the recording's size (2026-10-14's: 15 GB sessions, 11 GB
-# exports). Under half of it free, it can't fit: export says so before it starts.
+# An export is about three quarters of the recording's size (2026-10-17, the Frame's five
+# exports: 0.72 to 0.76). Export starts only with room for EXPORT_RATIO_NEED of it plus
+# EXPORT_RESERVE, and stops when the disk gets down to EXPORT_MIN_FREE: a full home disk breaks
+# more than the export (SteamVR, Steam and the desktop write there too). Until 2026-10-17 it
+# started with half free and ran until zstd failed on a full disk.
 EXPORT_RATIO = 0.75
-EXPORT_RATIO_MIN = 0.5
+EXPORT_RATIO_NEED = 0.8
+EXPORT_RESERVE = 2 * 1000 ** 3
+EXPORT_MIN_FREE = 1.5e9       # as session.py's MIN_FREE for recording
+ROOM_CHECK_S = 1.0
 
 
 class ZstdStopped(RuntimeError):
@@ -100,6 +110,33 @@ class DiskFull(RuntimeError):
     """Not enough free space for the export, before it started or as it went."""
 
 
+class NearlyFull(OSError):
+    """The export stopped itself: the disk got down to EXPORT_MIN_FREE."""
+
+    def __init__(self, free):
+        super().__init__(errno.ENOSPC, f"only {human_bytes(free)} left on the disk")
+
+
+def export_need(kept):
+    """The free space an export of kept bytes of recording needs to start."""
+    return int(kept * EXPORT_RATIO_NEED + EXPORT_RESERVE)
+
+
+_room_checked = [0.0]   # when check_room last looked (monotonic s)
+
+
+def check_room(path):
+    """Raise NearlyFull when the disk holding path is down to EXPORT_MIN_FREE. Looks at most once
+    every ROOM_CHECK_S (a statvfs per set would cost more than it saves)."""
+    now = time.monotonic()
+    if now - _room_checked[0] < ROOM_CHECK_S:
+        return
+    _room_checked[0] = now
+    free = free_bytes(path)
+    if 0 < free < EXPORT_MIN_FREE:
+        raise NearlyFull(free)
+
+
 def disk_full(e):
     """True if e (an export's error) or what it came from is a full disk or a quota."""
     seen = set()
@@ -433,6 +470,41 @@ def take_index(take_dir):
     return index
 
 
+def export_sha(export_dir):
+    """The export's identity, as hub.py records it: the SHA256 of its SHA256SUMS ("" if none)."""
+    try:
+        with open(os.path.join(export_dir, "SHA256SUMS"), "rb") as f:
+            return hashlib.sha256(f.read()).hexdigest()
+    except OSError:
+        return ""
+
+
+def _epoch(iso):
+    try:
+        return datetime.datetime.fromisoformat(iso).timestamp()
+    except (TypeError, ValueError):
+        return None
+
+
+def upload_state(meta, changed, export_dir):
+    """A session's uploads, from its session.json (meta) and its files' newest change (changed,
+    tree_stat's): {"uploaded": a finished upload exists, "pr_url": the last one's, "freeable":
+    deleting the local copy loses nothing that wasn't uploaded}. That's when the recordings haven't
+    changed since the last finished upload, or (an upload without a readable time) the export
+    there now is the one uploaded."""
+    done = contributions.done_uploads(meta)
+    if not done:
+        return {"uploaded": False, "pr_url": "", "freeable": False}
+    last = done[-1]
+    when = _epoch(last.get("uploaded", ""))
+    if when is not None:
+        freeable = changed <= when
+    else:
+        sha = export_sha(export_dir)
+        freeable = bool(sha) and any(u.get("export_sha") == sha for u in done)
+    return {"uploaded": True, "pr_url": last.get("pr_url", ""), "freeable": freeable}
+
+
 # ---------------------------------------------------------------- the store
 
 class Store:
@@ -463,7 +535,8 @@ class Store:
     # --- listing
     def sessions(self):
         """Newest first: [{id, started, takes, bytes, lighting, status, dry_run, contributor, exported,
-        export_stale (changed since), export_bytes}]."""
+        export_stale (changed since), export_bytes, uploaded, pr_url, freeable}] (upload_state's
+        last three)."""
         out = []
         try:
             names = os.listdir(self.sessions_dir)
@@ -484,7 +557,8 @@ class Store:
                         "bounty": ((meta.get("bounty") or {}).get("title") or "") if isinstance(meta.get("bounty"), dict) else "",
                         "debug": bool(meta.get("debug")), "testing": consent_kind(meta) == "testing",
                         "exported": bool(exported), "export_stale": bool(exported) and changed > exported,
-                        "export_bytes": tree_bytes(self.export_dir(sid)) if exported else 0})
+                        "export_bytes": tree_bytes(self.export_dir(sid)) if exported else 0,
+                        **upload_state(meta, changed, self.export_dir(sid))})
         return sorted(out, key=lambda s: s["id"], reverse=True)
 
     def take_ids(self, session):
@@ -559,6 +633,53 @@ class Store:
         if os.path.isdir(path):
             shutil.rmtree(path)
 
+    # --- freeing space: uploaded sessions go, their record stays (recorder/contributions.py)
+    def log_uploads(self, session=None):
+        """Copy finished uploads from session.json into the contributions log: one session's, or
+        every session's (uploads older recorders recorded only there). Returns how many were new."""
+        items = []
+        for sid in [session] if session else [s for s in os.listdir(self.sessions_dir)
+                                              if SESSION_RE.match(s)] if os.path.isdir(self.sessions_dir) else []:
+            meta = read_json(os.path.join(self.session_dir(sid), "session.json"))
+            export = self.export_dir(sid)
+            size = tree_bytes(export) if os.path.isdir(export) else 0
+            items += [contributions.entry(sid, meta, u, size if u.get("export_sha") == export_sha(export) else 0)
+                      for u in contributions.done_uploads(meta)]
+        return contributions.add(self.base, items) if items else 0
+
+    def free_session(self, session):
+        """Delete an uploaded session's recordings and export, keeping its uploads in the
+        contributions log. Refuses (ValueError) a session that isn't uploaded as it is now.
+        Returns the bytes freed."""
+        path = self.session_dir(session)
+        meta = read_json(os.path.join(path, "session.json"))
+        if not meta:
+            raise ValueError(f"no session {session}")
+        _, changed = tree_stat(path)
+        state = upload_state(meta, changed, self.export_dir(session))
+        if not state["freeable"]:
+            raise ValueError("This session isn't uploaded as it is now: upload it first, or delete it")
+        freed = tree_bytes(path) + (tree_bytes(self.export_dir(session)) if os.path.isdir(self.export_dir(session)) else 0)
+        self.log_uploads(session)   # the record first: if it can't be written, nothing is deleted
+        if session not in contributions.sessions(self.base):
+            raise OSError(f"couldn't keep the record of {session} in {contributions.FILE}")
+        self.delete_session(session)
+        contributions.mark_deleted(self.base, session)
+        return freed
+
+    def freeable(self):
+        """The sessions free_session would take: [{id, bytes (recordings + export)}], newest first."""
+        return [{"id": s["id"], "bytes": s["bytes"] + s["export_bytes"]} for s in self.sessions()
+                if s["freeable"] and s["status"] != "recording"]
+
+    def contributions(self):
+        """The contributions log, newest first, each with "local": its session is still here."""
+        out = []
+        for c in reversed(contributions.load(self.base)):
+            local = bool(SESSION_RE.match(c["session"])) and os.path.isdir(os.path.join(self.sessions_dir, c["session"]))
+            out.append(dict(c, local=local))
+        return out
+
     # --- export
     def sides(self, session, swapped=None):
         """session.json's side camera decision (sides.py) plus each take's parts; with swapped
@@ -609,7 +730,7 @@ class Store:
             shutil.rmtree(work)
         kept = self.kept_bytes(session)
         free = free_bytes(self.exports_dir)   # 0: couldn't tell, so no check
-        if 0 < free < kept * EXPORT_RATIO_MIN:
+        if 0 < free < export_need(kept):
             raise DiskFull(self.space_text(session, kept, "Not enough free space to export this session"))
         os.makedirs(work)
         try:
@@ -619,6 +740,9 @@ class Store:
             os.replace(work, final)
         except BaseException as e:
             shutil.rmtree(work, ignore_errors=True)
+            if isinstance(e, NearlyFull):
+                raise DiskFull(self.space_text(session, kept, "The disk got nearly full, so the export "
+                                                              "stopped and removed its half")) from e
             if isinstance(e, Exception) and not isinstance(e, DiskFull) and disk_full(e):
                 raise DiskFull(self.space_text(session, kept, "The disk filled up while exporting")) from e
             raise
@@ -632,7 +756,8 @@ class Store:
     def space_text(self, session, kept, first):
         """The disk-full message: what's free, about what the export needs, and what to do."""
         text = (f"{first}: {human_bytes(free_bytes(self.exports_dir))} free, and the export needs about "
-                f"{human_bytes(kept * EXPORT_RATIO)}. Free some space and export again.")
+                f"{human_bytes(export_need(kept))} to start. Free some space and export again. Rounds that "
+                "are already uploaded can be deleted on the Review page, and your record of them stays.")
         old = tree_bytes(self.export_dir(session)) if os.path.isdir(self.export_dir(session)) else 0
         if old:
             text += f" Its old export ({human_bytes(old)}) stays until the new one is done: deleting it frees that too."
@@ -768,6 +893,7 @@ class Store:
                     for i in keep:
                         if cancelled():
                             raise Cancelled()
+                        check_room(dest)
                         record = index.read_raw(i)
                         proc.stdin.write(record)
                         raw += len(record)

hands/rec/tests/test_export_queue.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Exports queue up and run one at a time; one set to upload uploads by itself once it's
+exported, after any upload before it (recorder/window.py queueExport, 2026-10-17: "users can
+queue exports, and trigger an auto upload when the export is finished"). Needs PySide6 (the dev
+container); skipped without it.
+
+  python3 hands/rec/tests/test_export_queue.py
+"""
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import takes  # noqa: E402
+from test_validate import make_session  # noqa: E402
+
+A, B, C = "20261003-184200", "20261003-190000", "20261003-193000"
+
+
+class ExportQueueTest(unittest.TestCase):
+    def setUp(self):
+        try:
+            import ft_handrec
+            from recorder import window
+        except ImportError as e:
+            self.skipTest(f"no PySide6: {e}")
+        self.base = tempfile.mkdtemp(prefix="handrec-export-queue-test-")
+        for sid in (A, B, C):
+            make_session(self.base, sid=sid)
+        self.store = takes.Store(self.base)
+        self.backend = ft_handrec.Backend(self.store, {"dry_run": True}, hub_dry_run=True, ignore_cameras=True)
+        self.backend._stay_awake = lambda why, on: None
+        # Nothing runs: exports start and end by hand (finish), uploads start a fake hub.py.
+        self.started = []    # sessions whose export started, in order
+        self.sent = []       # sessions whose upload started, in order
+        real_start = self.backend._start_export
+
+        def start_export(session, keep_notes):
+            real_start(session, keep_notes)
+            self.started.append(session)
+        self.backend._start_export = start_export
+        popen = mock.patch.object(window.subprocess, "Popen", side_effect=self.popen)
+        popen.start()
+        self.addCleanup(popen.stop)
+        thread = mock.patch.object(self.backend, "_thread")
+        thread.start()
+        self.addCleanup(thread.stop)
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def popen(self, argv, **kw):
+        self.sent.append(argv[argv.index("upload") + 1])
+        return mock.Mock()
+
+    def finish_export(self, error=""):
+        self.backend._on_export_finished("" if error else self.base, error)
+
+    def finish_upload(self, ok=True):
+        self.backend._on_upload_finished({"done": {"dry_run": True}} if ok else {"error": {"kind": "hub", "text": "no"}})
+
+    def test_exports_run_in_turn(self):
+        for sid in (A, B, C):
+            self.backend.queueExport(sid, False, False)
+        self.assertEqual(self.started, [A])
+        self.assertEqual([q["session"] for q in self.backend.exportQueue], [B, C])
+        self.finish_export()
+        self.assertEqual(self.started, [A, B])
+        self.finish_export("disk full")   # a failed one doesn't hold up the rest
+        self.assertEqual(self.started, [A, B, C])
+        self.finish_export()
+        self.assertFalse(self.backend.exporting)
+        self.assertEqual(self.sent, [])   # none was set to upload
+
+    def test_queued_once(self):
+        self.backend.queueExport(A, False, False)
+        self.backend.queueExport(B, False, False)
+        self.backend.queueExport(B, False, True)   # again, now to upload: the same place in the queue
+        self.backend.queueExport(A, False, False)
+        self.assertEqual(self.backend.exportQueue, [{"session": B, "upload": True}])
+        self.assertEqual(self.started, [A])
+
+    def test_upload_after_export(self):
+        self.backend.queueExport(A, False, True)
+        self.assertEqual(self.sent, [])
+        self.finish_export()
+        self.assertEqual(self.sent, [A])
+        self.assertEqual(self.backend.upload["session"], A)
+
+    def test_no_upload_after_a_failed_or_cancelled_export(self):
+        self.backend.queueExport(A, False, True)
+        self.finish_export("disk full")
+        self.backend.queueExport(B, False, True)
+        self.backend.cancelExport()
+        self.finish_export("cancelled")
+        self.assertEqual(self.sent, [])
+        self.assertTrue(self.backend.doneLog[0]["error"])
+
+    def test_uploads_wait_their_turn(self):
+        for sid in (A, B, C):
+            self.backend.queueExport(sid, False, sid != B)
+        self.finish_export()              # A exported: it uploads
+        self.finish_export()              # B exported: not set to upload
+        self.finish_export()              # C exported: waits for A's upload
+        self.assertEqual(self.sent, [A])
+        self.assertEqual(self.backend.uploadQueue, [C])
+        self.finish_upload(ok=False)      # a failed upload doesn't hold up the next
+        self.assertEqual(self.sent, [A, C])
+        self.finish_upload()
+        self.assertFalse(self.backend.uploading)
+        self.assertEqual(self.backend.uploadQueue, [])
+
+    def test_upload_after_can_change(self):
+        self.backend.queueExport(A, False, False)
+        self.backend.queueExport(B, False, True)
+        self.backend.setUploadAfter(A, True)
+        self.backend.setUploadAfter(B, False)
+        self.finish_export()
+        self.finish_upload()
+        self.finish_export()
+        self.assertEqual(self.sent, [A])
+
+    def test_unqueue(self):
+        self.backend.queueExport(A, False, False)
+        self.backend.queueExport(B, False, True)
+        self.backend.unqueueExport(B)
+        self.finish_export()
+        self.assertEqual(self.started, [A])
+        self.assertEqual(self.sent, [])
+
+    def test_queued_session_isnt_deleted(self):
+        self.backend.queueExport(A, False, False)
+        self.backend.queueExport(B, False, False)
+        self.backend.deleteSession(B)
+        self.assertTrue(os.path.isdir(os.path.join(self.base, "sessions", B)))
+
+    def test_no_second_upload_of_the_same_export(self):
+        self.backend.queueExport(A, False, True)
+        with mock.patch.object(self.backend, "uploadInfo", return_value={"previous": {"export_sha": "x"}, "uploads": 1}):
+            self.finish_export()
+        self.assertEqual(self.sent, [])
+        self.assertIn("uploaded before", self.backend.doneLog[-1]["text"])
+
+
+if __name__ == "__main__":
+    unittest.main()

hands/rec/tests/test_free_space.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Tests for freeing space (2026-10-17): the contributions log (recorder/contributions.py) that
+outlives deleted sessions, Store.free_session and its refusals, the export's tighter space check
+and its stop before the disk fills, and hub.py adding each finished upload to the log.
+
+  python3 hands/rec/tests/test_free_space.py     (anywhere with zstd)
+"""
+import datetime
+import os
+import shutil
+import sys
+import tempfile
+import time
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import takes  # noqa: E402
+import hub  # noqa: E402
+from recorder import contributions  # noqa: E402
+from test_validate import make_session, SESSION  # noqa: E402
+
+PR = "https://huggingface.co/datasets/DeeJanuz/frametop-hands/discussions/12"
+
+
+def iso(t):
+    return datetime.datetime.fromtimestamp(t).astimezone().isoformat(timespec="seconds")
+
+
+class LogTest(unittest.TestCase):
+    def setUp(self):
+        self.base = tempfile.mkdtemp(prefix="handrec-log-test-")
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def entry(self, **kw):
+        c = {"session": SESSION, "repo": "a/b", "pr_url": PR, "pr_num": 12, "uploaded": "2026-10-15T13:04:38+00:00",
+             "export_sha": "s", "export_bytes": 0, "bounty": {}, "kind": "public", "debug": False, "started": "",
+             "minutes": None, "local_deleted": ""}
+        c.update(kw)
+        return c
+
+    def test_add_once(self):
+        self.assertEqual(contributions.add(self.base, [self.entry()]), 1)
+        self.assertEqual(contributions.add(self.base, [self.entry()]), 0)
+        self.assertEqual(len(contributions.load(self.base)), 1)
+
+    def test_add_fills_gaps_only(self):
+        contributions.add(self.base, [self.entry()])
+        contributions.add(self.base, [self.entry(export_bytes=99, pr_url="other")])
+        c, = contributions.load(self.base)
+        self.assertEqual(c["export_bytes"], 99)
+        self.assertEqual(c["pr_url"], PR)
+
+    def test_two_pull_requests_two_entries(self):
+        contributions.add(self.base, [self.entry(), self.entry(pr_num=13, pr_url=PR[:-2] + "13")])
+        self.assertEqual(len(contributions.load(self.base)), 2)
+
+    def test_mark_deleted(self):
+        contributions.add(self.base, [self.entry()])
+        self.assertTrue(contributions.mark_deleted(self.base, SESSION, "then"))
+        self.assertEqual(contributions.load(self.base)[0]["local_deleted"], "then")
+        self.assertFalse(contributions.mark_deleted(self.base, "20990101-000000"))
+
+    def test_unreadable_log(self):
+        with open(contributions.path(self.base), "w") as f:
+            f.write("{not json")
+        self.assertEqual(contributions.load(self.base), [])
+
+    def test_done_uploads(self):
+        meta = {"uploads": [{"status": "started", "pr_url": PR}, {"status": "done", "pr_url": PR},
+                            {"pr_url": PR, "uploaded": "old"}, {"status": "done", "pr_url": ""}, "junk"]}
+        self.assertEqual(len(contributions.done_uploads(meta)), 2)
+
+
+class FreeTest(unittest.TestCase):
+    def setUp(self):
+        self.base = tempfile.mkdtemp(prefix="handrec-free-test-")
+        make_session(self.base)
+        self.store = takes.Store(self.base)
+        self.sdir = self.store.session_dir(SESSION)
+        self.meta_path = os.path.join(self.sdir, "session.json")
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def upload(self, **kw):
+        record = {"repo": "DeeJanuz/frametop-hands", "pr_url": PR, "pr_num": 12, "uploaded": iso(time.time() + 5),
+                  "export_sha": "x", "status": "done"}
+        record.update(kw)
+        meta = takes.read_json(self.meta_path)
+        meta.setdefault("uploads", []).append(record)
+        meta["bounty"] = {"id": "index-taps", "title": "Index taps"}
+        st = os.stat(self.meta_path)
+        takes.write_json(self.meta_path, meta)
+        os.utime(self.meta_path, ns=(st.st_atime_ns, st.st_mtime_ns))   # as record_upload keeps it
+
+    def row(self):
+        return next(s for s in self.store.sessions() if s["id"] == SESSION)
+
+    def test_not_uploaded(self):
+        self.assertFalse(self.row()["freeable"])
+        with self.assertRaises(ValueError):
+            self.store.free_session(SESSION)
+        self.assertTrue(os.path.isdir(self.sdir))
+
+    def test_started_upload_isnt_enough(self):
+        self.upload(status="started")
+        self.assertFalse(self.row()["uploaded"])
+        self.assertFalse(self.row()["freeable"])
+
+    def test_free_uploaded(self):
+        self.upload()
+        os.makedirs(self.store.export_dir(SESSION))
+        row = self.row()
+        self.assertTrue(row["uploaded"] and row["freeable"])
+        self.assertEqual(row["pr_url"], PR)
+        self.assertEqual([f["id"] for f in self.store.freeable()], [SESSION])
+        self.assertGreater(self.store.free_session(SESSION), 0)
+        self.assertFalse(os.path.exists(self.sdir))
+        self.assertFalse(os.path.exists(self.store.export_dir(SESSION)))
+        c, = self.store.contributions()
+        self.assertEqual((c["session"], c["pr_url"], c["bounty"]["id"], c["local"]), (SESSION, PR, "index-taps", False))
+        self.assertTrue(c["local_deleted"])
+        self.assertEqual(self.store.freeable(), [])
+
+    def test_changed_since_upload(self):
+        self.upload(uploaded=iso(time.time() - 3600))
+        self.assertTrue(self.row()["uploaded"])
+        self.assertFalse(self.row()["freeable"])
+        with self.assertRaises(ValueError):
+            self.store.free_session(SESSION)
+        self.assertTrue(os.path.isdir(self.sdir))
+
+    def test_no_upload_time_uses_the_export(self):
+        path = self.store.export(SESSION, low_priority=False)
+        sha = takes.export_sha(path)
+        self.upload(uploaded="", export_sha="other")
+        self.assertFalse(self.row()["freeable"])
+        self.upload(uploaded="", export_sha=sha, pr_num=13)
+        self.assertTrue(self.row()["freeable"])
+
+    def test_record_first(self):
+        """The log can't be written: nothing is deleted."""
+        self.upload()
+        with mock.patch.object(contributions, "add", side_effect=OSError(28, "No space left on device")):
+            with self.assertRaises(OSError):
+                self.store.free_session(SESSION)
+        self.assertTrue(os.path.isdir(self.sdir))
+
+    def test_backfill(self):
+        self.upload()
+        self.assertEqual(self.store.log_uploads(), 1)
+        self.assertEqual(self.store.log_uploads(), 0)
+        self.assertTrue(self.store.contributions()[0]["local"])
+
+    def test_bad_ids(self):
+        for sid in ("../x", "", "20261002-101500/.."):
+            with self.assertRaises(ValueError):
+                self.store.free_session(sid)
+
+
+class ExportRoomTest(unittest.TestCase):
+    def setUp(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        self.base = tempfile.mkdtemp(prefix="handrec-room-test-")
+        make_session(self.base)
+        self.store = takes.Store(self.base)
+        self.partial = self.store.export_dir(SESSION) + ".partial"
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+        takes._room_checked[0] = 0.0
+
+    def test_needs_the_export_and_a_reserve(self):
+        kept = self.store.kept_bytes(SESSION)
+        self.assertEqual(takes.export_need(kept), int(kept * takes.EXPORT_RATIO_NEED + takes.EXPORT_RESERVE))
+        with mock.patch.object(takes, "free_bytes", return_value=takes.export_need(kept) - 1):
+            with self.assertRaises(takes.DiskFull) as cm:
+                self.store.export(SESSION, low_priority=False)
+        self.assertIn("already uploaded can be deleted", str(cm.exception))
+        self.assertFalse(os.path.exists(self.partial))
+
+    def test_stops_before_full(self):
+        """The disk gets down to EXPORT_MIN_FREE as it goes: the export stops and cleans up."""
+        real = takes.free_bytes
+        takes._room_checked[0] = 0.0
+
+        def free(path):
+            return 10 ** 12 if path == self.store.exports_dir else int(takes.EXPORT_MIN_FREE) - 1
+        with mock.patch.object(takes, "free_bytes", side_effect=free):
+            with self.assertRaises(takes.DiskFull) as cm:
+                self.store.export(SESSION, low_priority=False)
+        self.assertTrue(str(cm.exception).startswith("The disk got nearly full, so the export stopped"))
+        self.assertFalse(os.path.exists(self.partial))
+        self.assertIs(takes.free_bytes, real)
+
+
+class HubLogTest(unittest.TestCase):
+    """hub.upload adds the finished upload to the contributions log."""
+
+    def setUp(self):
+        if not takes.find_zstd():
+            self.skipTest("no zstd")
+        self.base = tempfile.mkdtemp(prefix="handrec-hublog-test-")
+        make_session(self.base)
+        self.store = takes.Store(self.base)
+        self.store.export(SESSION, low_priority=False)
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def fake_push(self, hf, repo, export, path_in_repo, message, description, meta_path, sha, nfiles, nbytes, tell,
+                  write_json, human_bytes):
+        record = {"repo": repo, "pr_url": PR, "pr_num": 12, "started": hub.now_iso(), "export_sha": sha,
+                  "uploaded": hub.now_iso(), "status": "done"}
+        hub.rhub.record_upload(meta_path, record, write_json)
+        return mock.Mock(num=12), {"name": "someone"}, record
+
+    def test_logged(self):
+        with mock.patch.object(hub, "upload_allowed", return_value=True), \
+                mock.patch.object(hub, "_hf", return_value=None), \
+                mock.patch.object(hub.rhub, "push", side_effect=self.fake_push):
+            result = hub.upload(self.store, SESSION)
+        self.assertEqual(result["pr_url"], PR)
+        c, = contributions.load(self.base)
+        self.assertEqual((c["session"], c["pr_num"], c["kind"]), (SESSION, 12, "public"))
+        self.assertGreater(c["export_bytes"], 0)
+
+    def test_dry_run_not_logged(self):
+        hub.upload(self.store, SESSION, dry_run=True)
+        self.assertEqual(contributions.load(self.base), [])
+
+
+class BackendTest(unittest.TestCase):
+    """The window's side: what can be freed, the free slots, the testing session's count from the
+    log, and the backfill when the window opens. Needs PySide6 (the dev container)."""
+
+    def setUp(self):
+        try:
+            import ft_handrec
+        except ImportError as e:
+            self.skipTest(f"no PySide6: {e}")
+        self.ft = ft_handrec
+        self.base = tempfile.mkdtemp(prefix="handrec-free-backend-test-")
+        make_session(self.base)
+        self.store = takes.Store(self.base)
+        meta_path = os.path.join(self.store.session_dir(SESSION), "session.json")
+        meta = takes.read_json(meta_path)
+        meta["debug"] = {"use": "testing"}
+        meta["status"] = "done"
+        meta["uploads"] = [{"repo": "DeeJanuz/frametop-hands-test", "pr_url": PR, "pr_num": 3, "status": "done",
+                            "uploaded": iso(time.time() + 5), "export_sha": "x"}]
+        st = os.stat(meta_path)
+        takes.write_json(meta_path, meta)
+        os.utime(meta_path, ns=(st.st_atime_ns, st.st_mtime_ns))
+        os.environ["FT_HANDREC_FRAMETOP_HANDS"] = "1"
+        self.addCleanup(os.environ.pop, "FT_HANDREC_FRAMETOP_HANDS", None)
+        self.backend = ft_handrec.Backend(self.store, {"dry_run": True}, ignore_cameras=True)
+        self.messages = []
+        self.backend.message.connect(lambda text, error: self.messages.append((text, error)))
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def test_backfilled_on_open(self):
+        self.assertEqual([c["session"] for c in contributions.load(self.base)], [SESSION])
+
+    def test_free_all(self):
+        self.assertEqual(self.backend.freeableCount, 1)
+        self.assertTrue(self.backend.freeableText)
+        row, = self.backend.sessions
+        self.assertTrue(row["freeable"])
+        self.assertEqual(row["uploadText"], "uploaded")
+        self.backend.freeAllUploaded()
+        self.assertFalse(os.path.exists(self.store.session_dir(SESSION)))
+        self.assertEqual(self.backend.freeableCount, 0)
+        self.assertEqual(self.backend.freeableText, "")
+        self.assertFalse(self.messages[-1][1], self.messages)
+        c, = self.backend.contributions
+        self.assertEqual((c["title"], c["local"], c["testing"]), ("Testing session", False, True))
+        self.assertTrue(c["deletedText"])
+        debug = next(b for b in self.backend.bounties if b["id"] == self.ft.DEBUG_ID)
+        self.assertEqual(debug["done"], 1)   # counted from the log once the session is gone
+
+    def test_free_one_refuses_unuploaded(self):
+        make_session(self.base, sid="20261003-184200")
+        self.backend.freeSession("20261003-184200")
+        self.assertTrue(self.messages[-1][1])
+        self.assertTrue(os.path.isdir(self.store.session_dir("20261003-184200")))
+
+    def test_busy_session_not_offered(self):
+        self.backend._upload_proc = object()
+        self.backend._upload = {"session": SESSION}
+        self.assertEqual(self.backend.freeableCount, 0)
+        self.backend.freeSession(SESSION)
+        self.assertTrue(os.path.isdir(self.store.session_dir(SESSION)))
+        self.backend._upload_proc = None
+
+    def test_round_needs_room_for_its_export(self):
+        self.assertGreaterEqual(self.ft.ROUND_BYTES, self.ft.RECORD_BYTES + takes.export_need(self.ft.RECORD_BYTES))
+
+
+if __name__ == "__main__":
+    unittest.main()

hands/rec/tests/test_upload_during_export.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""An export and an upload of different sessions go on together; the same session waits
+(recorder/window.py exportSession and startUpload, 2026-10-17: an upload was refused while
+any other session exported). Needs PySide6 (the dev container); skipped without it.
+
+  python3 hands/rec/tests/test_upload_during_export.py
+"""
+import os
+import shutil
+import sys
+import tempfile
+import threading
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import takes  # noqa: E402
+from test_validate import make_session  # noqa: E402
+
+A, B = "20261003-184200", "20261003-190000"
+
+
+class UploadDuringExportTest(unittest.TestCase):
+    def setUp(self):
+        try:
+            import ft_handrec
+            from recorder import window
+        except ImportError as e:
+            self.skipTest(f"no PySide6: {e}")
+        self.window = window
+        self.base = tempfile.mkdtemp(prefix="handrec-upload-export-test-")
+        make_session(self.base, sid=A)
+        make_session(self.base, sid=B)
+        self.store = takes.Store(self.base)
+        self.backend = ft_handrec.Backend(self.store, {"dry_run": True}, hub_dry_run=True, ignore_cameras=True)
+        self.backend._stay_awake = lambda why, on: None
+
+    def tearDown(self):
+        shutil.rmtree(self.base, ignore_errors=True)
+
+    def exporting(self, session):
+        self.backend._export_cancel = threading.Event()
+        self.backend._export_session = session
+
+    def uploading(self, session):
+        self.backend._upload_proc = object()
+        self.backend._upload = {"session": session}
+
+    def upload(self, session):
+        """startUpload(session): whether it started hub.py."""
+        with mock.patch.object(self.window.subprocess, "Popen") as popen, \
+                mock.patch.object(self.backend, "_thread"):
+            self.backend.startUpload(session, False)
+        return popen.called
+
+    def export(self, session):
+        """exportSession(session): whether it started the export."""
+        with mock.patch.object(self.backend, "_thread") as thread:
+            self.backend.exportSession(session, False)
+        return thread.called
+
+    def test_upload_while_another_exports(self):
+        self.exporting(A)
+        self.assertTrue(self.upload(B))
+        self.assertTrue(self.backend.uploading)
+
+    def test_upload_waits_for_its_own_export(self):
+        self.exporting(A)
+        self.assertFalse(self.upload(A))
+
+    def test_export_while_another_uploads(self):
+        self.uploading(B)
+        self.assertTrue(self.export(A))
+        self.assertEqual(self.backend.exportSessionId, A)
+
+    def test_no_export_of_the_uploading_session(self):
+        self.uploading(B)
+        self.assertFalse(self.export(B))
+
+    def test_one_export_at_a_time(self):
+        self.exporting(A)
+        self.assertFalse(self.export(B))
+        self.assertEqual(self.backend.exportQueue, [{"session": B, "upload": False}])   # it waits its turn
+
+
+if __name__ == "__main__":
+    unittest.main()

host/linux/README.md

@@ -49,7 +49,7 @@ sudo ufw allow Vibepollo
 
 ## Good to know
 
-- The resolution switch and the HDR guard of Frametop's build are Windows-only for now. On Linux, a monitor keeps its own resolution and the stream scales it.
+- The resolution switch, the HDR guard and the Frame's microphone are Windows-only for now. On Linux, a monitor keeps its own resolution and the stream scales it, and Send my microphone does nothing.
 - Vibepollo runs as system services. `sudo systemctl status vibepollo-session-controller.service vibepollo.service` shows them, and `sudo journalctl -u vibepollo-session-controller.service -u vibepollo.service --since '-10 minutes'` shows their log. Don't start `vibepollo.service` yourself: the session controller starts it when you log in.
 - Settings, the Web UI login and pairings are in `/var/lib/vibepollo`.
 - Vibepollo's [Linux install guide](https://github.com/Frametop/frametop-vibepollo/blob/frametop-2.0.0-3/docs/linux/install.md) has the details and troubleshooting.

host/windows/README.md

@@ -37,6 +37,7 @@ Frametop's build is Vibepollo 2.0.0 with a few changes, from [Frametop/frametop-
 - An HDR monitor's HDR is off while it streams, and back on after. An HDR desktop in the stream looked washed out.
 - A virtual display that goes away leaves your monitor layout as it was.
 - The Web UI doesn't stall after a client disconnects.
+- It can take the Frame's microphone, for calls and voice chat on the PC. Turn on Send my microphone on the PC's card in Remote Displays. While its displays stream, apps on the PC can record it as "Microphone (Steam Streaming Microphone)". That's Steam's virtual microphone: the build installs it from Steam's drivers the first time if it's missing, and leaves your default microphone as it was. It only goes over the encrypted stream.
 
 ## Stream over a Steam Link dongle
 

input-settings/ft_input_settings.py

@@ -1645,21 +1645,28 @@ class Backend(QObject):
             running = v["resolved"]["name"] or "classic"
             if not v["resolved"]["folder"]:
                 note = note or f"{v['latest']} isn't downloaded yet: the classic tracker runs until it is."
+        # One row a version. The latest version's row is "latest": picking it follows updates. Set by
+        # name in frametop.conf, it shows on that row as pinned (not following) until picked here.
+        pinned = choice == v["latest"]
+        if pinned:
+            choice = "latest"
+            setting = "HANDS_MODEL" if kind == "hands" else "EYES_MODEL"
+            note = note or (f"{setting} in frametop.conf names {v['latest']}, so it stays on {v['latest']} when a "
+                            "newer version comes. Use this to follow updates.")
         opts = []
-        latest = by.get(v["latest"])
-        if latest:
-            opts.append(dict(latest, name="latest", target=latest["name"], follows=True,
-                             title=f"Latest (follows updates): {latest['title']}",
-                             tag=MODEL_TAGS.get(latest["status"], ""),
-                             installed=True if kind == "hands" else latest["installed"]))
         for m in v["models"]:
             tag = MODEL_TAGS.get(m["status"]) or MODEL_KIND_TAGS.get(m["kind"], "")
-            opts.append(dict(m, target=m["name"], follows=False, tag=tag))
+            if m["name"] == v["latest"]:
+                opts.append(dict(m, name="latest", target=m["name"], follows=True,
+                                 tag=(tag + "  ·  " if tag else "") + "Latest",
+                                 installed=True if kind == "hands" else m["installed"]))
+            else:
+                opts.append(dict(m, target=m["name"], follows=False, tag=tag))
         for o in opts:
             o["bench"] = {k: (None if val is None else float(val)) for k, val in o["bench"].items()}
         checked = time.strftime("%H:%M", time.localtime(v["checked"])) if v["checked"] else ""
         return {"options": opts, "metrics": v["metrics"], "byName": by, "latest": v["latest"],
-                "baseline": v["baseline"], "choice": choice, "running": running, "note": note,
+                "baseline": v["baseline"], "choice": choice, "pinned": pinned, "running": running, "note": note,
                 "source": v["source"], "checked": checked, "error": ""}
 
     def _models_update(self):

input-settings/main.qml

@@ -70,7 +70,7 @@ Kirigami.ApplicationWindow {
         readonly property string otherName: opt.target !== running ? running
                                             : opt.target !== view.baseline ? (view.baseline || "") : ""
         readonly property var other: otherName ? ((view.byName || {})[otherName] || null) : null
-        readonly property bool inUse: opt.name === view.choice
+        readonly property bool inUse: opt.name === view.choice && !view.pinned
         spacing: Kirigami.Units.smallSpacing
         Layout.maximumWidth: Kirigami.Units.gridUnit * 30
 
@@ -95,7 +95,8 @@ Kirigami.ApplicationWindow {
             delegate: Controls.RadioButton {
                 required property var modelData
                 text: modelData.title + (modelData.tag ? "  ·  " + modelData.tag : "")
-                      + (modelData.name === picker.view.choice ? "  ·  in use" : "")
+                      + (modelData.name === picker.view.choice ? (picker.view.pinned ? "  ·  in use, not following updates"
+                                                                                       : "  ·  in use") : "")
                       + (!modelData.usable ? "  ·  needs a newer Frametop"
                          : !modelData.installed ? "  ·  not downloaded" : "")
                 font.bold: modelData.name === picker.view.choice
@@ -116,14 +117,13 @@ Kirigami.ApplicationWindow {
         // The one being looked at: what it is, what to expect, what it costs, and its numbers.
         Kirigami.Separator { Layout.fillWidth: true; visible: !!picker.opt.name }
         Controls.Label {
-            text: (picker.opt.follows ? "Latest: " + picker.opt.target : picker.opt.title || "")
-                  + (picker.opt.date ? " (" + picker.opt.date + ")" : "")
+            text: (picker.opt.title || "") + (picker.opt.date ? " (" + picker.opt.date + ")" : "")
             textFormat: Text.PlainText
             font.bold: true
         }
         Controls.Label {
             visible: picker.opt.follows === true
-            text: "Moves to each new version we recommend, without asking. Pick a version below it to stay on that one."
+            text: "The newest version. Picked, it follows updates: when a newer version ships, Frametop moves to it without asking. Any other version stays put when picked."
             Layout.fillWidth: true
             wrapMode: Text.WordWrap
             opacity: 0.7
@@ -488,49 +488,49 @@ Kirigami.ApplicationWindow {
                             onClicked: { backend.setMapping(bpage.deviceId, bpage.capturedCode, newAction.currentValue); bpage.capturedCode = -1 }
                         }
                     }
-                }
 
-                Kirigami.Heading {
-                    visible: bpage.rows.length > 0
-                    level: 3
-                    text: "Current mappings"
-                }
+                    Kirigami.Separator {
+                        visible: bpage.rows.length > 0
+                        Kirigami.FormData.isSection: true
+                        Kirigami.FormData.label: "Current mappings"
+                    }
 
-                Repeater {
-                    model: bpage.rows
-                    delegate: RowLayout {
-                        required property var modelData
-                        Layout.fillWidth: true
-                        spacing: Kirigami.Units.largeSpacing
-                        Controls.Label {
-                            text: modelData.name
-                            font.family: "monospace"
-                            Layout.preferredWidth: Kirigami.Units.gridUnit * 10
+                    Repeater {
+                        model: bpage.rows
+                        delegate: RowLayout {
+                            required property var modelData
+                            Layout.fillWidth: true
+                            spacing: Kirigami.Units.largeSpacing
+                            Controls.Label {
+                                text: modelData.name
+                                font.family: "monospace"
+                                Layout.preferredWidth: Kirigami.Units.gridUnit * 10
+                            }
+                            Controls.ComboBox {
+                                model: backend.actions
+                                textRole: "text"
+                                valueRole: "value"
+                                Layout.preferredWidth: Kirigami.Units.gridUnit * 13
+                                Component.onCompleted: currentIndex = indexOfValue(modelData.action)
+                                onActivated: backend.setMapping(bpage.deviceId, modelData.code, currentValue)
+                            }
+                            Controls.Label {
+                                text: modelData.custom ? (modelData.isDefault ? "changed" : "custom") : "default"
+                                opacity: 0.6
+                                Layout.preferredWidth: Kirigami.Units.gridUnit * 4
+                            }
+                            // Remove: your own binding goes away (the button passes through again).
+                            // Reset: a changed built-in binding goes back to its default.
+                            // Unbind: an untouched built-in binding is set to "Do nothing".
+                            Controls.Button {
+                                text: modelData.custom ? (modelData.isDefault ? "Reset" : "Remove") : "Unbind"
+                                icon.name: modelData.custom ? (modelData.isDefault ? "edit-undo" : "edit-delete-remove")
+                                                            : "list-remove"
+                                onClicked: modelData.custom ? backend.removeMapping(bpage.deviceId, modelData.code)
+                                                            : backend.unbind(bpage.deviceId, modelData.code)
+                            }
+                            Item { Layout.fillWidth: true }
                         }
-                        Controls.ComboBox {
-                            model: backend.actions
-                            textRole: "text"
-                            valueRole: "value"
-                            Layout.preferredWidth: Kirigami.Units.gridUnit * 13
-                            Component.onCompleted: currentIndex = indexOfValue(modelData.action)
-                            onActivated: backend.setMapping(bpage.deviceId, modelData.code, currentValue)
-                        }
-                        Controls.Label {
-                            text: modelData.custom ? (modelData.isDefault ? "changed" : "custom") : "default"
-                            opacity: 0.6
-                            Layout.preferredWidth: Kirigami.Units.gridUnit * 4
-                        }
-                        // Remove: your own binding goes away (the button passes through again).
-                        // Reset: a changed built-in binding goes back to its default.
-                        // Unbind: an untouched built-in binding is set to "Do nothing".
-                        Controls.Button {
-                            text: modelData.custom ? (modelData.isDefault ? "Reset" : "Remove") : "Unbind"
-                            icon.name: modelData.custom ? (modelData.isDefault ? "edit-undo" : "edit-delete-remove")
-                                                        : "list-remove"
-                            onClicked: modelData.custom ? backend.removeMapping(bpage.deviceId, modelData.code)
-                                                        : backend.unbind(bpage.deviceId, modelData.code)
-                        }
-                        Item { Layout.fillWidth: true }
                     }
                 }
 
@@ -1633,6 +1633,8 @@ Kirigami.ApplicationWindow {
                     text: gpage.status.calibration_samples > 0
                           ? gpage.status.calibration_samples + " points ("
                             + (gpage.status.tracker === "own" ? "Own tracker, " + gpage.status.calibration_made
+                               + (gpage.status.own_mapped && gpage.status.own_mapped.length === 1
+                                  ? ", " + gpage.status.own_mapped[0] + " eye only" : "")
                                : gpage.status.kind === "eyes" ? gpage.status.model + ", each eye" : gpage.status.model) + ")"
                           : "none yet: use Calibrate"
                 }

input/input-relay.py

@@ -67,6 +67,9 @@ reaches games; see pointer/helper/vrbuttons.h).
 
 In gaze mode outside games, the helper keeps the pointer ("gazeawake 1", repeated every 5
 seconds; "gazeawake 0" or silence ends it): the pointer isn't released when the mouse is idle.
+When something else let the pointer go, the gaze takes it back and the helper says "gazewoke"
+(the pointer is on again here too). The hides here say why: "hide toggle" (pointer_toggle: the
+gaze leaves it off until something wakes it), "hide idle", "hide pause".
 Typing on a keyboard sends the helper "typing" (at most 4 times a second): it takes no hand
 pinches right after a key, since typing touches thumb to index like a pinch.
 
@@ -115,6 +118,12 @@ pointer helper decides per side whether a hand holds a controller or is bare
 state as "paused 1|0" (hands work in a VR game only with the dashboard open or Frametop toggled
 back on).
 
+The gaze calibration panel (gaze/panel/ft-gazepanel; the pointer helper says "calpanel 1" while
+it's up): Enter on a pass-through keyboard (either Enter, with no modifier held) takes the
+panel's dot instead of typing: "calkey 1" to the helper, which answers the panel as it does a
+left click. Its repeats and its release go nowhere either. That works while the relay has the
+keyboard (typing goes to the desktop); while typing goes to Steam, Steam sees the Enter too.
+
 Frametop can pause for VR games (game_pause.py: by hand, with a controller gesture, or by itself
 while a game runs). Paused, it stops the services that cost the game CPU and GPU, and the relay
 plays a plain one: the pointer devices feed the virtual mouse and keyboard as without pointer
@@ -132,10 +141,12 @@ Control socket (abstract datagram @frametop_relay, JSON replies to the sender):
   reload            re-read both config files, re-apply roles, tell the helper
   vrcapture <s>     take every controller button for s seconds (0: stop), so the settings
                     app can capture one; watchers see them as events with id frame_controller
-  vrbtn, vrhello, gazeawake   from the pointer helper (above)
+  vrbtn, vrhello, gazeawake, gazewoke   from the pointer helper (above)
   vrgame 1|0        from the pointer helper: a VR game runs (on a change and every 5 s), for pausing
   vrdash 1|0        from the pointer helper (hand interaction): the dashboard is open, so hand
                     tracking parked for a game wakes (game_pause.py, PARK_PATH)
+  calpanel 1|0      from the pointer helper: a gaze calibration panel is up (renewed every second,
+                    lapses 3 s after the last), so Enter answers it (above)
   textfield 1|0     from the desktop's input method (above)
   pause on|off|toggle [reason]   pause Frametop or resume it (input/ft-pause; the gesture reader)
   pause ?           the pause state, as {"t": "pause", ...}
@@ -179,6 +190,7 @@ SCROLLS = {0x06, REL_WHEEL, 0x0B, 0x0C}  # REL_HWHEEL, REL_WHEEL and their _HI_R
 BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_SIDE, BTN_EXTRA = 0x110, 0x111, 0x112, 0x113, 0x114
 BTN_MOUSE, BTN_TASK = 0x110, 0x117  # mouse buttons, the first and the last
 KEY_LEFTMETA, KEY_RIGHTMETA = 125, 126
+KEY_ENTER, KEY_KPENTER = 28, 96
 KEY_MUTE, KEY_VOLUMEDOWN, KEY_VOLUMEUP = 113, 114, 115
 # Volume keys are remapped to KEY_MACRO28, KEY_MACRO29 and KEY_MACRO30: above 255, so X11
 # can't carry them, and bound to nothing in the default keymap.
@@ -681,7 +693,7 @@ class Pointer:
             self.send("recenter")
         elif name == "pointer_toggle":
             if self.active:
-                self.send("hide")
+                self.send("hide toggle")  # gaze mode leaves it off until something wakes it
                 self.active = False
                 log("pointer off (toggle)")
             else:
@@ -755,7 +767,7 @@ class Pointer:
             self.send("scroll 0 0")
             self.scroll_until = None
         if self.active and now - self.last_used > self.idle and now >= self.gaze_awake_until:
-            self.send("hide")
+            self.send("hide idle")
             self.active = False
             log("pointer off (idle)")
 
@@ -798,7 +810,7 @@ class Pointer:
         self.dx = self.dy = self.pending = 0
         self.gaze_awake_until = 0.0
         if self.active or releases:
-            self.send("hide")
+            self.send("hide pause")
         if self.active:
             self.active = False
             log("pointer off (paused)")
@@ -894,7 +906,7 @@ def main():
     # differ while Frametop is paused).
     state = {"pointer": None, "pointer_conf": None, "rules": {},
              "desktop_until": 0.0, "typing_applied": None, "vr_capture_until": 0.0, "vr_bind_retry": False,
-             "pointer_holding": False}
+             "pointer_holding": False, "calpanel_until": 0.0}
 
     def pause_changed(paused):
         """Frametop paused or resumed (game_pause.py): the relay's own part."""
@@ -1070,6 +1082,25 @@ def main():
     held_meta = set()  # the Meta keys held, as they are (KEY_LEFTMETA, KEY_RIGHTMETA)
     meta_hidden = set()  # held Meta keys the desktop was told came up (a combination; key_binding)
     combos_down = {}  # key code -> the action its combination started (released with it)
+    cal_keys = set()  # Enter keys whose press answered the gaze calibration panel (cal_enter)
+
+    def cal_enter(code, value, now):
+        """Enter while the gaze calibration panel is up (see the top): its press goes to the helper
+        as "calkey 1", and the press, its repeats and its release aren't typed. True if taken."""
+        if value == 1 and code in (KEY_ENTER, KEY_KPENTER) and now < state["calpanel_until"] \
+                and not held_modifiers and code not in combos_down:
+            cal_keys.add(code)
+            try:
+                screens_sock.sendto(b"calkey 1", HELPER)
+            except OSError:
+                pass  # helper not running (SteamVR not running)
+            log("Enter: the gaze calibration panel's")
+            return True
+        if code in cal_keys:
+            if value == 0:
+                cal_keys.discard(code)
+            return True
+        return False
 
     def key_binding(code, value, now):
         """A key from a keyboard: does it complete a key combination ("key_bindings")? True if
@@ -1404,10 +1435,22 @@ def main():
                     else:
                         log(f"type from another user ({uid}): ignored")
                     continue
+                if cmd == "calpanel" and len(words) == 2:
+                    # From the pointer helper (see the top). Only from this user: it takes Enter.
+                    if uid == os.getuid():
+                        state["calpanel_until"] = now + 3.0 if words[1] == "1" else 0.0
+                    continue
                 if cmd == "gazeawake" and len(words) == 2:
                     if state["pointer"]:
                         state["pointer"].gaze_awake_until = now + 12.0 if words[1] == "1" else 0.0
                     continue
+                if cmd == "gazewoke":
+                    # The gaze took the pointer back (gaze mode owns it): it's on, as a wake leaves it.
+                    p = state["pointer"]
+                    if p and not p.active:
+                        p.active, p.last_used = True, now
+                        log("pointer on (gaze)")
+                    continue
                 if not addr:
                     continue  # unbound sender, nowhere to reply
                 if cmd == "devices":
@@ -1559,6 +1602,8 @@ def main():
                 if node.role != "pointer":
                     # Observed only, unless typing goes to the desktop. Key combinations work on
                     # any pass-through keyboard.
+                    if node.role == "passthrough" and etype == EV_KEY and cal_enter(code, value, now):
+                        continue
                     if node.role == "passthrough" and etype == EV_KEY and code < BTN_MISC and key_binding(code, value, now):
                         continue
                     if node.role == "passthrough" and etype == EV_KEY:

input/test/keys-test.py

@@ -28,6 +28,9 @@ relay_path = sys.argv[1] if len(sys.argv) > 1 else os.path.join(HERE, "..", "inp
 tag = f"ft_keys_test_{os.getpid()}"
 with open(relay_path) as f:
     src = f.read().replace('"\\0frametop_relay"', f'"\\0{tag}_relay"')
+screens_socket = "screens_sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_NONBLOCK)"
+assert src.count(screens_socket) == 1, "relay's screens socket constructor changed"
+src = src.replace(screens_socket, "screens_sock = _test_screens_sender")
 relay = importlib.util.module_from_spec(importlib.util.spec_from_loader("relay", loader=None))
 relay.__file__ = os.path.abspath(relay_path)
 sys.path.insert(0, os.path.dirname(os.path.abspath(relay_path)))  # its game_pause and vrws
@@ -174,7 +177,10 @@ def probe(path):
 
 relay.probe = probe
 
-screens = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+# A connected pair holds all 16 startup releases even when the kernel limits unconnected
+# datagram queues to 10 messages. The relay still uses real sendto(), including other peers.
+relay._test_screens_sender, screens = socket.socketpair(socket.AF_UNIX, socket.SOCK_DGRAM)
+relay._test_screens_sender.setblocking(False)
 screens.bind(relay.SCREENS)
 screens.settimeout(0.05)
 voice = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)  # Frametop Voice's socket
@@ -394,7 +400,7 @@ def tests():
                 m = helper.recv(256).decode()
             except socket.timeout:
                 return got
-            if m == "hide" or (m.startswith("btn ") and not m.startswith("btn a ")):
+            if m.startswith("hide") or (m.startswith("btn ") and not m.startswith("btn a ")):
                 got.append(m)
 
     conf["POINTER"] = "1"
@@ -404,7 +410,7 @@ def tests():
     check("pointer mode: a held left button reaches the helper", clicks(), ["btn trigger 1"])
     pause("on")
     check("pause with the left button held: it comes up, then the pointer hides", clicks(),
-          ["btn trigger 0", "hide"])
+          ["btn trigger 0", "hide pause"])
     key(relay.BTN_LEFT, 0, ms_w)
     check("paused: its release reaches no one", clicks(), [])
     pause("off")
@@ -569,6 +575,51 @@ def tests():
           (text_field(), said()), ([], ["text field focused: not opening Frametop's keyboard (Keyboard setting: never)"]))
     vr_keyboard["mode"] = None
     use(None)
+
+    # The gaze calibration panel (the helper's "calpanel 1"): Enter takes its dot ("calkey 1" to
+    # the helper) and isn't typed, its press, repeats and release; with a modifier held, or once
+    # the panel is gone or lapsed, Enter is typed again.
+    ENTER, KPENTER = relay.KEY_ENTER, relay.KEY_KPENTER
+
+    def cal_keys():
+        got = []
+        while True:
+            try:
+                m = helper.recv(256).decode()
+            except socket.timeout:
+                return got
+            if m.startswith("calkey"):
+                got.append(m)
+
+    def panel(on):
+        to_relay(f"calpanel {on}")
+        time.sleep(0.1)
+
+    use({})
+    typed(), cal_keys()
+    key(ENTER, 1); key(ENTER, 0)
+    check("Enter without the panel: typed", (cal_keys(), typed()), ([], ["key 28 1", "key 28 0"]))
+    panel(1)
+    key(ENTER, 1); key(ENTER, 2); key(ENTER, 2); key(ENTER, 0)
+    check("panel up: Enter takes the dot, once", cal_keys(), ["calkey 1"])
+    check("...and its press, repeats and release aren't typed", typed(), [])
+    key(KPENTER, 1); key(KPENTER, 0)
+    check("panel up: keypad Enter too", (cal_keys(), typed()), (["calkey 1"], []))
+    key(SHIFT, 1); key(ENTER, 1); key(ENTER, 0); key(SHIFT, 0)
+    check("panel up, Shift held: Enter is typed", (cal_keys(), typed()),
+          ([], ["key 42 1", "key 28 1", "key 28 0", "key 42 0"]))
+    key(A, 1); key(A, 0)
+    check("panel up: other keys are typed", (cal_keys(), typed()), ([], ["key 30 1", "key 30 0"]))
+    key(ENTER, 1); panel(0); key(ENTER, 0)
+    check("panel gone while Enter is held: it took the dot, and its release isn't typed",
+          (cal_keys(), typed()), (["calkey 1"], []))
+    key(ENTER, 1); key(ENTER, 0)
+    check("panel gone: Enter is typed", (cal_keys(), typed()), ([], ["key 28 1", "key 28 0"]))
+    panel(1)
+    time.sleep(3.1)  # no renewal: the claim lapses after 3 s
+    key(ENTER, 1); key(ENTER, 0)
+    check("panel claim lapsed: Enter is typed", (cal_keys(), typed()), ([], ["key 28 1", "key 28 0"]))
+    use(None)
     print("FAILED: " + ", ".join(failures) if failures else "all passed", flush=True)
     shutil.rmtree(OUT, ignore_errors=True)
     os._exit(1 if failures else 0)

input/test/pause-buttons-test.py

@@ -60,7 +60,7 @@ p.action("left", 1, 10.0)  # a mouse click (or drag) held: btn trigger 1
 check("press reaches the helper", p.sock.sent, ["show", "recenter", "btn trigger 1"])
 mark = len(p.sock.sent)
 p.stand_down()  # Frametop pauses while it's held
-check("stand_down releases the held button, then hides", since(p, mark), ["btn trigger 0", "hide"])
+check("stand_down releases the held button, then hides", since(p, mark), ["btn trigger 0", "hide pause"])
 
 # The release that pausing drops later is already covered: the button is no longer down,
 # so a stray second stand_down sends nothing.
@@ -74,7 +74,7 @@ p.action("left", 1, 10.0)
 p.action("right", 1, 10.5)
 mark = len(p.sock.sent)
 p.stand_down()
-check("both held buttons are released, then it hides", since(p, mark), ["btn b 0", "btn trigger 0", "hide"])
+check("both held buttons are released, then it hides", since(p, mark), ["btn b 0", "btn trigger 0", "hide pause"])
 
 # A mapped controller button and a key combination take the same path as the mouse.
 p = pointer()
@@ -83,7 +83,7 @@ p.action("back", 1, 10.1, "keyboard")  # a key combination mapped to back
 mark = len(p.sock.sent)
 p.stand_down()
 check("controller and key combination clicks are released too", since(p, mark),
-      ["btn joystick 0", "btn x 0", "hide"])
+      ["btn joystick 0", "btn x 0", "hide pause"])
 
 # ---------------------------------------------------------------- the pointer already off
 # A release with no "hide" after it would wake a helper that wakes on any btn, connecting the
@@ -93,18 +93,19 @@ p.idle = 30.0
 p.action("left", 1, 10.0)
 for t in (10.3, 10.4, 41.0):  # the claim pulse, then 30 s with no mouse input
     p.tick(t)
-check("held 30 s with no mouse input: the pointer goes off", (p.active, p.sock.sent[-1]), (False, "hide"))
+check("held 30 s with no mouse input: the pointer goes off", (p.active, p.sock.sent[-1]), (False, "hide idle"))
 mark = len(p.sock.sent)
 p.stand_down()
-check("idle with a button held: the release, then hide", since(p, mark), ["btn trigger 0", "hide"])
+check("idle with a button held: the release, then hide", since(p, mark), ["btn trigger 0", "hide pause"])
 
 p = pointer()
 p.action("left", 1, 10.0)
 p.action("pointer_toggle", 1, 10.5)
+check("pointer_toggle says why it hides (gaze mode leaves it off)", p.sock.sent[-1], "hide toggle")
 mark = len(p.sock.sent)
 p.stand_down()
 check("pointer toggled off with a button held: the release, then hide", since(p, mark),
-      ["btn trigger 0", "hide"])
+      ["btn trigger 0", "hide pause"])
 
 # ---------------------------------------------------------------- the ordinary path
 p = pointer()
@@ -112,7 +113,7 @@ p.action("left", 1, 10.0)
 p.action("left", 0, 11.0)  # released before the pause
 mark = len(p.sock.sent)
 p.stand_down()
-check("a button released before the pause: stand_down only hides", since(p, mark), ["hide"])
+check("a button released before the pause: stand_down only hides", since(p, mark), ["hide pause"])
 
 p = pointer()
 p.idle = 30.0
@@ -130,7 +131,7 @@ p.action("gaze_left", 1, 10.0, "keyboard")  # Meta+J held
 p.action("gaze_drag", 1, 10.1, "mouse")
 mark = len(p.sock.sent)
 p.stand_down()
-check("gaze holds: stand_down sends only hide (the helper ends them)", since(p, mark), ["hide"])
+check("gaze holds: stand_down sends only hide (the helper ends them)", since(p, mark), ["hide pause"])
 
 print()
 if failures:

justfile

@@ -53,6 +53,9 @@ test-c:
         g++ -std=c++17 -Wall -Wextra -Werror -I. "$t" -o "build/tests/$n"
         "build/tests/$n" >/dev/null && echo "$t: ok"
     done
+    g++ -std=c++17 -O2 -Wall -Wextra -Werror screens/tests/rounded-test.cpp \
+      -o build/tests/rounded-test
+    build/tests/rounded-test && echo "screens/tests/rounded-test.cpp: ok"
 
 # shell scripts: syntax-gate everything that ships. No git: the image has
 # none, and a mounted checkout can trip "dubious ownership" — find lists

layout/ft_layout.py

@@ -41,6 +41,8 @@ you face (yaw only), like a recenter. It lives in ~/.config/frametop-layout.json
               "direct": ["10.35.78.20"],          its Steam Link dongle on the Frame's hotspot
               "route": "auto",                    auto (the dongle when it answers) | network |
                                                           dongle (only; ft-stream reads both)
+              "mic": false,                       send the Frame's microphone to it (needs
+                                                          Frametop's Vibepollo on Windows; ft-stream)
               "displays": [{"id": "desk-pc-oled",         (docs/remote-displays.md), each a panel
                             "client": "frametop-1",       streamed by ft-stream: its paired client,
                             "app": "display:{GUID}",      what it streams (display:DEVICE, monitor:
@@ -101,8 +103,9 @@ Usage (on the Frame host; Frametop Display Settings calls it too):
                                      first, or with --login, with the Web UI login read from stdin
                                      as two lines: a Sunshine instance on PORT) -> its id
   ft-layout remote set ID size=WxH|fps=F|bitrate=KBPS|label=TEXT|app=APP|metres=M ...
-  ft-layout remote host NAME route=auto|network|dongle direct=ADDRESS[,ADDRESS]|none
-                                     how a host's streams reach it; its running streams start over
+  ft-layout remote host NAME route=auto|network|dongle direct=ADDRESS[,ADDRESS]|none mic=on|off
+                                     how a host's streams reach it (they start over), and whether
+                                     the Frame's microphone goes to it (within 3 s, no restart)
   ft-layout remote connect ID...     start their streams again (and keep them on)
   ft-layout remote disconnect ID...  stop their streams and panels until connected again
   ft-layout remote remove ID         stops it and unpairs its client (the host stays)
@@ -974,7 +977,7 @@ def remote_command(args):
         for n, host, d in remote_displays(layout):
             w, h = d.get("size", [2560, 1440])
             state = "disconnected" if d.get("off") else running.get(n, "off")
-            state += f" route {host.get('route', 'auto')}"
+            state += f" route {host.get('route', 'auto')}{' mic' if host.get('mic') else ''}"
             print(f"{n} {d['id']} {host.get('name')} {display_target(host, d)} {d['app']} {w}x{h}@{d.get('fps', 60)} "
                   f"{state}{' hidden' if d.get('hidden') else ''}  {d.get('label', '')}")
         return
@@ -983,15 +986,23 @@ def remote_command(args):
         host = next((h for h in layout.get("hosts", []) if h.get("name") == args[1]), None)
         if host is None:
             raise RuntimeError(f"no host called {args[1]!r}")
+        restart = False
         for kv in args[2:]:
             k, _, v = kv.partition("=")
             if k == "route" and v in ("auto", "network", "dongle"):
                 host["route"] = v
+                restart = True
             elif k == "direct" and (v == "none" or re.fullmatch(r"[A-Za-z0-9.:-]+(,[A-Za-z0-9.:-]+)*", v)):
                 host["direct"] = [] if v == "none" else v.split(",")
+                restart = True
+            elif k == "mic" and v in ("on", "off"):
+                host["mic"] = v == "on"  # the stream playing its sound looks every 3 s
             else:
-                raise RuntimeError(f"remote host: {kv!r}? (route=auto|network|dongle direct=ADDRESS[,ADDRESS]|none)")
+                raise RuntimeError(f"remote host: {kv!r}? (route=auto|network|dongle direct=ADDRESS[,ADDRESS]|none "
+                                   "mic=on|off)")
         save_layout(layout)
+        if not restart:
+            return
         # Its streams start over the new way, their panels where they are (ft-screens keeps
         # their places across a stop in the same run).
         try:
@@ -1153,7 +1164,7 @@ def remote_command(args):
         log(f"removed {d['id']}; {said[-1] if said else f'unpair exited {code}'}")
         return
     raise RuntimeError("remote list | monitors ADDRESS | add HOST ADDRESS APP [options] | set ID KEY=VALUE... | "
-                       "host NAME route=...|direct=... | connect ID... | disconnect ID... | remove ID")
+                       "host NAME route=...|direct=...|mic=... | connect ID... | disconnect ID... | remove ID")
 
 
 def apply(wait=0):

pack/Containerfile

@@ -8,7 +8,7 @@
 # Frame's dev container; the list below freezes the runtime-relevant subset of
 # it plus the toolchain (the binaries are built in this image). Keep the two in
 # sync on purpose: dev-container.sh documents *why* each package is there.
-FROM registry.fedoraproject.org/fedora-toolbox:44@sha256:034cb7c472038e2d879ddc19568106a1342aa24403f0d641a0f73dda638707ad
+FROM registry.fedoraproject.org/fedora-toolbox:44@sha256:034cb7c472038e2d879ddc19568106a1342aa24403f0d641a0f73dda638707ad AS runtime-common
 
 # Toolchain (the binaries are built in here) and the libraries they link.
 RUN dnf -y install --setopt=install_weak_deps=False \
@@ -25,8 +25,9 @@ RUN dnf -y install --setopt=install_weak_deps=False \
       # Vulkan backend; ft-voiced records with pw-record and plays its sounds with pw-play
       glslc spirv-headers-devel pipewire-utils \
       # Frametop Input Settings (Kirigami, PySide6) and remote desktop (krdp):
-      # the KDE/Qt stack has no PyPI wheels, so it stays a dnf package
-      python3-pyside6 kf6-kirigami kf6-qqc2-desktop-style qt6-qtwayland \
+      # keep the native KDE/Qt stack in matching Fedora packages
+      python3-shiboken6 kf6-kirigami kf6-qqc2-desktop-style \
+      qt6-qtwayland qt6-qtsvg qt6-qtimageformats qt6-qtpdf \
       breeze-icon-theme plasma-breeze krdp freerdp tigervnc-x11-server xrandr \
     && dnf -y remove 'glibc-langpack-*' \
     && dnf -y install glibc-langpack-en \
@@ -34,14 +35,6 @@ RUN dnf -y install --setopt=install_weak_deps=False \
     && rm -rf /usr/share/doc/* /usr/share/man/* /usr/share/info/* \
               /usr/share/wallpapers
 
-# uv, pinned and checked. Python dependencies come from the committed uv.lock,
-# not from whatever PyPI serves on build day.
-RUN curl -fsSL https://github.com/astral-sh/uv/releases/download/0.12.23/uv-aarch64-unknown-linux-gnu.tar.gz \
-      -o /tmp/uv.tar.gz \
- && echo "6524bd338177ed50d035d39354e12545e993bbeba2ecbddf0480c5b3a81d313f  /tmp/uv.tar.gz" | sha256sum -c \
- && tar -xzf /tmp/uv.tar.gz --strip-components=1 -C /usr/local/bin \
- && rm /tmp/uv.tar.gz
-
 # OpenVR's API library for linking, from the SDK tag the build scripts pin
 # (scripts/openvr.sh fetches the headers). The image has no SteamVR, so the
 # binaries link this copy; their rpath names SteamVR's folder first, so on the
@@ -53,47 +46,75 @@ RUN install -d /opt/frametop/bin /opt/frametop/lib \
 
 # Python: Fedora's own python3 (the digest-pinned base freezes it), with the
 # locked packages in a venv on top. The venv sees the system site-packages,
-# because PySide6 and Kirigami come from dnf for this python3: one interpreter
+# because PySide6 and Kirigami come from Fedora for this python3: one interpreter
 # imports both, as in the dev container on the Frame. The check names the
 # recorders' huggingface_hub (uploads) and cryptography (encrypted exports) too:
-# the tests that need them skip without them. Rebuilt only when the lockfile
-# changes, so source edits below reuse this layer.
+# the tests that need them skip without them. PySide6 itself is checked in the
+# runtime stage at the end, where the builder's export lands. Rebuilt only when
+# the lockfile changes, so source edits below reuse this layer.
 # uv sync --frozen --group tracker --group voice: the default dev group (pytest/ruff
 # for CI's in-image tests) plus the tracker stack and Frametop Voice's (sherpa-onnx);
 # the types group (mypy) stays out.
 # --no-cache keeps uv's download cache out of the image.
+# uv is a pinned, checked build tool, not a runtime dependency. Extract it,
+# create the environment, and remove it in one layer so neither uv nor uvx
+# takes space in an installed image.
 ENV UV_PROJECT_ENVIRONMENT=/opt/frametop/venv UV_PYTHON=/usr/bin/python3 UV_PYTHON_DOWNLOADS=never
 COPY pyproject.toml uv.lock .python-version /src/frametop/
-RUN uv venv --system-site-packages /opt/frametop/venv \
- && cd /src/frametop && uv sync --frozen --group tracker --group voice --no-cache \
- && /opt/frametop/venv/bin/python -c 'import PySide6, numpy, cv2, sherpa_onnx, sentencepiece, huggingface_hub, cryptography'
+RUN uvdir=$(mktemp -d) \
+ && curl -fsSL https://github.com/astral-sh/uv/releases/download/0.12.23/uv-aarch64-unknown-linux-gnu.tar.gz \
+      -o "$uvdir/uv.tar.gz" \
+ && echo "6524bd338177ed50d035d39354e12545e993bbeba2ecbddf0480c5b3a81d313f  $uvdir/uv.tar.gz" | sha256sum -c \
+ && tar -xzf "$uvdir/uv.tar.gz" --strip-components=1 -C "$uvdir" uv-aarch64-unknown-linux-gnu/uv \
+ && "$uvdir/uv" venv --system-site-packages /opt/frametop/venv \
+ && cd /src/frametop && "$uvdir/uv" sync --frozen --group tracker --group voice --no-cache \
+ && /opt/frametop/venv/bin/python -c 'import numpy, cv2, sherpa_onnx, sentencepiece, huggingface_hub, cryptography' \
+ && rm -rf "$uvdir"
+
+# Preserve separate base/environment layers for cached builds and rollback.
+# Keep the toolchain and headers: ft dev shell/test still work in this image.
+# PySide's full Fedora RPM also requires WebEngine/3D/etc. The builder exports
+# the unchanged bindings Frametop uses, against these same system Qt libraries.
+WORKDIR /src/frametop
+ENV FRAME_IN_BOX=1 OPENVR_LIB=/opt/frametop/lib
+ENV PATH=/opt/frametop/venv/bin:/opt/frametop/bin:/usr/local/bin:/usr/bin:/usr/sbin
+RUN ln -s /run/host/opt/steamvr /opt/steamvr
+CMD ["sleep", "infinity"]
+
+FROM runtime-common AS builder
+RUN rpm -qa --qf '%{NEVRA}\n' | sort > /tmp/runtime-rpms \
+ && dnf -y install --setopt=install_weak_deps=False python3-pyside6 \
+ && rpm -qa --qf '%{NEVRA}\n' | sort > /tmp/builder-rpms \
+ && test -z "$(comm -23 /tmp/runtime-rpms /tmp/builder-rpms)" \
+ && dnf clean all \
+ && install -d /runtime/opt/frametop/bin /runtime/opt/frametop/lib
 
 # The sources, then the binaries, built by the same build scripts as on the
 # Frame (FRAME_IN_BOX=1: they run here instead of entering the dev container).
 # Each program stays in its build/ folder in /src/frametop and is copied to
 # /opt/frametop.
 COPY . /src/frametop
-WORKDIR /src/frametop
-ENV FRAME_IN_BOX=1 OPENVR_LIB=/opt/frametop/lib
 RUN screens/build.sh \
- && install -t /opt/frametop/bin screens/build/ft-screens screens/build/ft-handtest screens/build/ft-spotpanel
+ && install -t /runtime/opt/frametop/bin screens/build/ft-screens screens/build/ft-handtest screens/build/ft-spotpanel \
+ && rm -f screens/build/*.o
 RUN pointer/helper/build.sh && pointer/driver/build.sh \
- && install -t /opt/frametop/bin pointer/helper/build/ft-pointer \
- && install -t /opt/frametop/lib pointer/driver/build/driver_ft_pointer.so
+ && install -t /runtime/opt/frametop/bin pointer/helper/build/ft-pointer \
+ && install -t /runtime/opt/frametop/lib pointer/driver/build/driver_ft_pointer.so
 RUN gaze/build.sh \
- && install -t /opt/frametop/bin gaze/build/ft-gaze gaze/build/ft-gazepanel
+ && install -t /runtime/opt/frametop/bin gaze/build/ft-gaze gaze/build/ft-gazepanel
 RUN power/build.sh \
- && install -t /opt/frametop/bin power/build/ft-powerd
+ && install -t /runtime/opt/frametop/bin power/build/ft-powerd
 RUN stream/build.sh \
- && install -t /opt/frametop/bin stream/build/ft-stream
+ && install -t /runtime/opt/frametop/bin stream/build/ft-stream \
+ && rm -rf stream/build/mlc stream/build/gamestream
 # Our own eye tracker: ft-eyegrab (it runs on the host, as root) and ft-eyes'
 # build/venv, which here only points at the venv above.
 RUN gaze/tracker/build.sh \
- && install -t /opt/frametop/bin gaze/tracker/build/ft-eyegrab
+ && install -t /runtime/opt/frametop/bin gaze/tracker/build/ft-eyegrab
 # Frametop Voice: whisper.cpp's server (Vulkan), and build/venv pointing at the venv
 # above. Its speech models aren't in the image: voice/models.sh fetches them on install.
 RUN voice/build.sh \
- && install -t /opt/frametop/bin voice/build/bin/whisper-server
+ && install -t /runtime/opt/frametop/bin voice/build/bin/whisper-server
 # Hand tracking: ft-camd (static: it runs on the host, with the file
 # capabilities hands/run.sh install sets) and ft-hands, which builds ncnn at the
 # tag hands/Makefile pins. Both stay in hands/build/, where their units and
@@ -115,14 +136,17 @@ RUN git init -q pack/build/distrobox \
  && git fetch -q --depth 1 https://github.com/89luca89/distrobox.git 40c3cd724faa434aeb0a23e28776665b92de68bd \
  && git checkout -q FETCH_HEAD \
  && rm -rf .git
-# Programs built against OpenVR look for SteamVR's library here first. In the
-# container on the Frame, distrobox mounts the host at /run/host; elsewhere the
-# link leads nowhere and they use /opt/frametop/lib's.
-RUN ln -s /run/host/opt/steamvr /opt/steamvr
+# Export Fedora's selected Python bindings without changing their native code.
+RUN python3 pack/pyside-runtime.py --repo /src/frametop --destination /runtime
 
 # The default environment: Frametop's binaries and the venv's python3 (Fedora's
-# interpreter, with the locked packages and the dnf Qt stack) first.
+# interpreter, with the locked packages and the Fedora Qt stack) first.
 # sleep infinity as the default command keeps the image usable with distrobox
 # create, like the toolbox base.
-ENV PATH=/opt/frametop/venv/bin:/opt/frametop/bin:/usr/local/bin:/usr/bin:/usr/sbin
-CMD ["sleep", "infinity"]
+FROM runtime-common AS runtime
+COPY --from=builder /runtime/usr/ /usr/
+COPY --from=builder /runtime/opt/ /opt/
+COPY --from=builder /src/frametop/ /src/frametop/
+RUN python3 pack/pyside-runtime.py --verify /usr/share/frametop/pyside-runtime.json \
+ && /usr/bin/python3 -c 'from PySide6 import QtCore, QtGui, QtQml, QtQuick, QtQuickControls2' \
+ && python3 -c 'import numpy, cv2'

pack/README.md

@@ -19,7 +19,9 @@ different glibc. This directory turns the container from a recipe into an
    versions with aarch64 wheels, installed into `/opt/frametop/venv`. The venv
    sits on Fedora's own `python3`, which the base digest freezes, and sees the
    system site-packages: PySide6 and Kirigami come from dnf for that
-   interpreter, so one `python3` imports both, as in the dev container.
+   interpreter, so one `python3` imports both, as in the dev container. The
+   checked uv executable is temporary: only the environment it creates stays
+   in the image.
 3. **OpenVR from the pinned public tag** — `v2.15.6`, in
    `scripts/openvr.sh`. The build scripts fetch its headers and check their
    sha256. The image has no SteamVR, so it links the SDK's prebuilt
@@ -36,6 +38,31 @@ tracking's `ft-camd` and `ft-hands` (with ncnn, built from the tag
 `hands/Makefile` pins) stay in `hands/build/`, where their units and
 `ft-camd`'s file capabilities point.
 
+Component builds strip non-runtime symbols before the binaries are copied into
+the image. The pointer driver and gaze panel also discard unused sections;
+they keep `-O2`, the existing floating-point flags, and the host glibc checks.
+
+The image has a shared Fedora/toolchain stage, a builder, and the final runtime.
+The builder installs Fedora's full PySide6 RPM, then `pyside-runtime.py` exports
+the bindings imported by the four Frametop settings/recording applications.
+Their native binaries and support libraries are copied unchanged to the same
+Fedora paths, so both the system Python used by distrobox and the locked venv
+can import them. A manifest records their source RPMs and file hashes; the
+image build and offline tests check imports, hashes and shared-library resolution.
+The available-module metadata describes the exported subset rather than the
+full SDK. Keep `BACKENDS` in that script current when adding another Qt app.
+
+The native Qt/Kirigami libraries, desktop style, Breeze icons, platform plugins
+and image formats (including SVG and PDF) remain distro packages. Qt WebEngine,
+3D and other bindings unused by Frametop stay in the builder. This is Frametop's
+private application runtime; the separate `dev` container still installs the
+full PySide SDK. The runtime also keeps its compilers, headers and test tools,
+so the native build recipes and `ft dev test` still work. Base/environment
+layers stay separate from the source payload: the pinned toolbox base is
+shared with the retained rollback release, and cached builds can also reuse
+the added environment layers. Clean builds on independent runners need not
+produce identical environment layers, even with identical RPM versions.
+
 What deliberately stays outside the image for now: the **host payload** — the
 SteamVR driver registration (`vrpathreg`), ft-camd's file capabilities
 (setcap), systemd units, the KWin script. Those need the SteamOS host, and

pack/pyside-runtime.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Export Frametop's Fedora PySide bindings, or verify the installed app runtime.
+
+Native Qt, QML, platform/style plugins and python3-shiboken6 remain dnf packages.
+Only the unused Python Qt bindings and SDK tool links are omitted; ELF files are
+copied unchanged to their original Fedora paths. This is a private app runtime.
+"""
+import argparse
+import ast
+import compileall
+import hashlib
+import importlib
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+DIRECT = ("QtCore", "QtGui", "QtQml", "QtQuick", "QtQuickControls2")
+BACKENDS = ("display-settings/ft_display_settings.py", "input-settings/ft_input_settings.py",
+            "remote-displays/ft_remote_displays.py", "hands/rec/ft_handrec.py", "gaze/rec/ft_eyerec.py",
+            "gaze/bench/gazebench.py")
+MANIFEST = Path("usr/share/frametop/pyside-runtime.json")
+
+
+def run(*args, **kwargs):
+    return subprocess.check_output(args, text=True, **kwargs).strip()
+
+
+def imports(repo):
+    for name in DIRECT:
+        importlib.import_module("PySide6." + name)
+    for i, name in enumerate(BACKENDS):
+        path = repo / name
+        sys.path.insert(0, str(path.parent))
+        spec = importlib.util.spec_from_file_location(f"_ft_pyside_{i}", path)
+        spec.loader.exec_module(importlib.util.module_from_spec(spec))
+        sys.path.pop(0)
+
+
+def check_elf(paths):
+    for path in paths:
+        if "not found" in run("ldd", str(path)):
+            raise RuntimeError(f"unresolved ELF dependency: {path}")
+
+
+def export(dest, repo):
+    imports(repo)
+    import PySide6
+    from PySide6 import _config
+    from PySide6.QtCore import qVersion
+
+    package = Path(PySide6.__file__).parent.resolve()
+    modules = {name.split(".")[-1]: Path(m.__file__).resolve()
+               for name, m in sys.modules.items() if name.startswith("PySide6.Qt")
+               and isinstance(getattr(m, "__file__", None), str) and m.__file__.endswith(".so")}
+    if not set(DIRECT) <= modules.keys():
+        raise RuntimeError("a required binding was not imported")
+    if (dest / package.relative_to("/")).exists() or (dest / MANIFEST).exists():
+        raise RuntimeError(f"PySide was already exported into {dest}")
+    copied, elf = [], []
+    for name in run("rpm", "-ql", "python3-pyside6").splitlines():
+        src = Path(name)
+        if not src.is_file() and not src.is_symlink():
+            continue
+        if src.name == "entry_points.txt":
+            continue  # this private runtime does not advertise the omitted SDK commands
+        if src.is_relative_to(package):
+            rel = src.relative_to(package)
+            if "__pycache__" in rel.parts or rel.parts[0] in ("Qt", "scripts"):
+                continue
+            if len(rel.parts) == 1 and rel.name.startswith("Qt") and rel.name.split(".")[0] not in modules:
+                continue
+            if src.is_symlink() and ".so" not in src.name:
+                continue  # SDK command links, not the package's Python/private helpers
+        elif not ((src.name.startswith("libpyside6") and ".so" in src.name)
+                  or any(part.startswith("PySide6-") and part.endswith((".dist-info", ".egg-info"))
+                         for part in src.parts)
+                  or name.startswith("/usr/share/licenses/python3-pyside6/")):
+            continue
+        out = dest / src.relative_to("/")
+        if out.exists() or out.is_symlink():
+            raise RuntimeError(f"export would replace a file: {out}")
+        out.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, out, follow_symlinks=False)
+        copied.append(name)
+        if ".so" in src.name:
+            elf.append(name)
+            if not src.is_symlink() and src.read_bytes() != out.read_bytes():
+                raise RuntimeError(f"ELF changed during export: {src}")
+
+    # __all__ discovers the available extension files. The build metadata must agree.
+    cfg = dest / (package / "_config.py").relative_to("/")
+    cfg_stat = cfg.stat()
+    text = cfg.read_text()
+    nodes = [n for n in ast.parse(text).body if isinstance(n, ast.Assign)
+             and any(isinstance(t, ast.Name) and t.id == "built_modules" for t in n.targets)]
+    if len(nodes) != 1 or nodes[0].col_offset:
+        raise RuntimeError("unrecognized PySide built_modules metadata")
+    available = [n for n in _config.built_modules if (n if n.startswith("Qt") else "Qt" + n) in modules]
+    if len(available) != len(modules):
+        raise RuntimeError("PySide module metadata and imported bindings disagree")
+    node, lines = nodes[0], text.splitlines(keepends=True)
+    cfg.write_text("".join(lines[:node.lineno - 1]) + f"built_modules = {available!r}\n"
+                   + "".join(lines[node.end_lineno:]))
+    os.utime(cfg, ns=(cfg_stat.st_atime_ns, cfg_stat.st_mtime_ns))
+    staged = dest / package.relative_to("/")
+    check_elf([dest / n.lstrip("/") for n in elf])
+    probe = ("import PySide6; from PySide6 import _config; "
+             f"assert set(PySide6.__all__) == {set(modules)!r}; "
+             f"assert _config.built_modules == {available!r}")
+    run(sys.executable, "-c", probe, env=dict(os.environ, PYTHONPATH=str(staged.parent),
+                                             PYTHONDONTWRITEBYTECODE="1"))
+    if not compileall.compile_dir(str(staged), ddir=str(package), quiet=1, optimize=[0, 1]):
+        raise RuntimeError("PySide bytecode compilation failed")
+    for pyc in staged.rglob("*.pyc"):
+        stat = Path(importlib.util.source_from_cache(str(pyc))).stat()
+        os.utime(pyc, ns=(stat.st_atime_ns, stat.st_mtime_ns))
+    manifest = {"private_app_runtime": True, "pyside": PySide6.__version__, "qt": qVersion(), "modules": sorted(modules),
+                "source_rpms": run("rpm", "-q", "python3-pyside6", "python3-shiboken6").splitlines(),
+                "metadata_change": "_config.built_modules narrowed; omitted SDK scripts and entry_points.txt",
+                "elf": elf, "sha256": {n: hashlib.sha256((dest / n.lstrip("/")).read_bytes()).hexdigest()
+                                       for n in copied if not (dest / n.lstrip("/")).is_symlink()}}
+    target = dest / MANIFEST
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(manifest, indent=2) + "\n")
+    print(json.dumps({"modules": sorted(modules), "files": len(copied), "destination": str(dest)}))
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    action = p.add_mutually_exclusive_group(required=True)
+    action.add_argument("--destination", "--export", dest="export", type=Path,
+                        help="staging directory, later copied to / (may already contain /opt)")
+    action.add_argument("--verify", type=Path, help="installed pyside-runtime.json")
+    p.add_argument("--repo", type=Path, default=Path(__file__).resolve().parent.parent)
+    a = p.parse_args()
+    if a.export:
+        export(a.export.resolve(), a.repo.resolve())
+    else:
+        manifest = json.loads(a.verify.read_text())
+        for path, sha in manifest["sha256"].items():
+            if hashlib.sha256(Path(path).read_bytes()).hexdigest() != sha:
+                raise RuntimeError(f"runtime file changed: {path}")
+        check_elf(manifest["elf"])
+        for name in manifest["modules"]:
+            importlib.import_module("PySide6." + name)
+        imports(a.repo.resolve())
+        import PySide6
+        from PySide6.QtCore import qVersion
+        if qVersion() != manifest["qt"] or run("rpm", "-q", "python3-shiboken6") not in manifest["source_rpms"]:
+            raise RuntimeError("runtime Qt/Shiboken version differs from the builder")
+        if set(PySide6.__all__) != set(manifest["modules"]):
+            raise RuntimeError("runtime module advertisement differs")
+        print("PySide runtime: all checks passed")
+
+
+if __name__ == "__main__":
+    main()

pack/release-notes.md

@@ -1,6 +1,6 @@
 ## Install
 
-On a Steam Frame (SteamOS, VR variant). Download **Frametop.zip** below (about 1.4 GB), then either:
+On a Steam Frame (SteamOS, VR variant). Download **Frametop.zip** below (about 1.2 GB), then either:
 
 - **With [FrameDrop](https://framedropvr.com) on a PC:** drop Frametop.zip on your paired headset. In the headset, open Frametop in your library and press Play.
 - **On the headset:** unpack Frametop.zip (in the desktop's Dolphin or Konsole) and run `Frametop/frametop-install.sh`.

pack/test/pyside-runtime-test.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Check the GUI bindings under both Python paths used by the image and distrobox."""
+import importlib.util
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+REPO = Path(__file__).resolve().parents[2]
+HELPER = REPO / "pack/pyside-runtime.py"
+
+
+def probe():
+    spec = importlib.util.spec_from_file_location("pyside_runtime", HELPER)
+    helper = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(helper)
+    manifest = Path("/") / helper.MANIFEST
+    if manifest.exists():
+        # The helper verifies hashes, ELF dependencies, advertised modules, versions,
+        # required Qt modules and the four real backend imports together.
+        subprocess.run([sys.executable, str(HELPER), "--verify", str(manifest),
+                        "--repo", str(REPO)], check=True, timeout=90)
+    else:
+        # Full Fedora SDK/source-development containers need no subset manifest.
+        helper.imports(REPO)
+    print(f"{sys.executable}: Frametop GUI bindings passed", flush=True)
+
+
+def main():
+    env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1")
+    env.pop("PYTHONPATH", None)
+    env.pop("PYTHONHOME", None)
+    seen = set()
+    for python in (Path(sys.executable), Path("/usr/bin/python3"),
+                   Path("/opt/frametop/venv/bin/python")):
+        if not python.is_file():
+            continue
+        # Keep system and venv paths distinct even when their binaries are symlinks
+        # to the same executable. Only aliases within one bin directory are skipped.
+        directory = python.parent.resolve()
+        if directory in seen:
+            continue
+        seen.add(directory)
+        subprocess.run([str(python), str(Path(__file__).resolve()), "--probe"],
+                       env=env, check=True, timeout=120)
+
+
+if __name__ == "__main__":
+    if sys.argv[1:] == ["--probe"]:
+        probe()
+    elif len(sys.argv) == 1:
+        main()
+    else:
+        raise SystemExit("usage: pyside-runtime-test.py")

pointer/driver/build.sh

@@ -10,10 +10,11 @@ root=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
 exec "$root/scripts/frame.sh" -C pointer/driver 'set -e
 mkdir -p build
 . ../../scripts/openvr.sh
-g++ -std=c++17 -O2 -fPIC -shared -fvisibility=hidden -fno-math-errno -Wall -Wno-unused-parameter \
-  -static-libstdc++ -static-libgcc -Wl,--exclude-libs,ALL \
+g++ -std=c++17 -O2 -ffunction-sections -fdata-sections -fPIC -shared -fvisibility=hidden -fno-math-errno -Wall -Wno-unused-parameter \
+  -static-libstdc++ -static-libgcc -Wl,--exclude-libs,ALL,--gc-sections \
   $OPENVR_CFLAGS \
   -o build/driver_ft_pointer.so driver_ft_pointer.cpp -lpthread
+strip --strip-unneeded build/driver_ft_pointer.so
 max=$(objdump -T build/driver_ft_pointer.so | grep -oE "GLIBC_[0-9.]+" | sort -uV | tail -1)
 echo "built build/driver_ft_pointer.so, newest glibc symbol: $max"
 [ "$(printf "%s\n" "$max" GLIBC_2.39 | sort -V | tail -1)" = GLIBC_2.39 ] || { echo "needs newer glibc than the host has" >&2; exit 1; }'

pointer/helper/build.sh

@@ -7,4 +7,5 @@ exec "$root/scripts/frame.sh" -C pointer/helper 'set -e; mkdir -p build
 . ../../scripts/openvr.sh
 g++ -std=c++17 -O2 -Wall -Wno-unused-parameter $OPENVR_CFLAGS -I../common \
   -o build/ft-pointer ft-pointer.cpp $OPENVR_LIBS -lpthread
+strip --strip-unneeded build/ft-pointer
 echo "built build/ft-pointer"'

pointer/helper/calpanel.h

@@ -1,24 +1,37 @@
-// The gaze calibration panel's answers (see ft-pointer.cpp's top): while ft-gazed says the panel
-// is up, a press from the relay answers it instead of clicking. Here so it can be tested without
-// SteamVR (pointer/test/calpanel-test.sh).
+// The gaze calibration panel's answers (see ft-pointer.cpp's top): while a panel is up, a press
+// from the relay answers it instead of clicking. Here so it can be tested without SteamVR
+// (pointer/test/calpanel-test.sh).
 //
 // Accept (take this dot): the left button's press ("btn trigger 1", whatever mouse button,
-// controller button or key combination is mapped to the left action), Meta+J ("gazekey left 1"),
-// and a gaze precision or gaze drag press ("precision|gazedrag <source> 1"): those are the left
-// button for someone who mapped it to one, and were dropped until 2026-10-09, so the panel
-// never took a dot from them. Quit: the right button ("btn b 1") and Meta+K ("gazekey right 1").
-// Their releases, and the other buttons, do nothing while the panel is up.
+// controller button or key combination is mapped to the left action), Enter on a keyboard (the
+// relay's "calkey 1", sent only while the panel is up), Meta+J ("gazekey left 1"), a gaze
+// precision or gaze drag press ("precision|gazedrag <source> 1"; those are the left button for
+// someone who mapped it to one, and were dropped until 2026-10-09, so the panel never took a dot
+// from them), and an index pinch with hand tracking (CalPinch, below). Quit: the right button
+// ("btn b 1") and Meta+K ("gazekey right 1"). Their releases, and the other buttons, do nothing
+// while the panel is up.
+//
+// Whose panel: "calpanel 1" is the gaze service's (@ft_gazed); "calpanel 1 NAME" is another
+// program's, answered on @NAME (the gaze bench). The last claim wins.
 #pragma once
 
+#include <cctype>
+#include <cstdint>
 #include <cstdio>
 #include <cstring>
+#include <string>
+
+extern "C" {
+#include "../../hands/include/fh_gestures.h"
+}
 
 enum class CalPanelAnswer { None, Accept, Quit, Ignore };
 
 inline CalPanelAnswer calPanelAnswer(const char *msg) {
     char source[16];
     int value;
-    if (!std::strncmp(msg, "btn trigger 1", 13) || !std::strncmp(msg, "gazekey left 1", 14))
+    if (!std::strncmp(msg, "btn trigger 1", 13) || !std::strncmp(msg, "gazekey left 1", 14) ||
+        !std::strcmp(msg, "calkey 1"))
         return CalPanelAnswer::Accept;
     if ((std::sscanf(msg, "precision %15s %d", source, &value) == 2 ||
          std::sscanf(msg, "gazedrag %15s %d", source, &value) == 2) && value == 1)
@@ -26,7 +39,55 @@ inline CalPanelAnswer calPanelAnswer(const char *msg) {
     if (!std::strncmp(msg, "btn b 1", 7) || !std::strncmp(msg, "gazekey right 1", 15))
         return CalPanelAnswer::Quit;
     if (!std::strncmp(msg, "btn ", 4) || !std::strncmp(msg, "gazekey ", 8) ||
-        !std::strncmp(msg, "precision ", 10) || !std::strncmp(msg, "gazedrag ", 9))
+        !std::strncmp(msg, "precision ", 10) || !std::strncmp(msg, "gazedrag ", 9) ||
+        !std::strncmp(msg, "calkey ", 7))
         return CalPanelAnswer::Ignore;
     return CalPanelAnswer::None;
 }
+
+// "calpanel 1 [NAME]" or "calpanel 0": false if msg isn't one. on: the panel is up; owner: the
+// abstract socket that gets the answers (ft_gazed without a NAME). A NAME is 1 to 64 letters,
+// digits, '_', '-' or '.'; another one makes the message not a claim.
+inline bool calPanelClaim(const char *msg, bool &on, std::string &owner) {
+    int v;
+    int used = 0;
+    if (std::sscanf(msg, "calpanel %d%n", &v, &used) != 1 || (v != 0 && v != 1)) return false;
+    const char *rest = msg + used;
+    while (*rest == ' ') ++rest;
+    std::string name = *rest ? rest : "ft_gazed";
+    if (name.size() > 64) return false;
+    for (const char c : name)
+        if (!(std::isalnum(static_cast<unsigned char>(c)) || c == '_' || c == '-' || c == '.')) return false;
+    on = v == 1, owner = name;
+    return true;
+}
+
+// Index pinches for the panel: a pinch that began since the last look (FH_PINCH begins counted
+// per side) is a tap that takes the dot, whether it was let go yet or not, so a held pinch takes
+// one. Start() at the panel's opening, so pinches from before don't count; a new gestures file
+// (opens changed) or counters that went back (ft-hands started over) start counting again.
+class CalPinch {
+public:
+    void Start() { based_ = false; }
+    // The side (0 left, 1 right) of a pinch begun since the last call, or -1. One per call: a
+    // pinch by each hand at once is one answer.
+    int Began(const fh_gestures_t &g, int opens) {
+        if (!based_ || opens != opens_ || g.pinch[0].begins < seen_[0] || g.pinch[1].begins < seen_[1]) {
+            seen_[0] = g.pinch[0].begins, seen_[1] = g.pinch[1].begins;
+            opens_ = opens, based_ = true;
+            return -1;
+        }
+        int side = -1;
+        for (int s = 0; s < 2; ++s)
+            if (g.pinch[s].begins != seen_[s]) {
+                seen_[s] = g.pinch[s].begins;
+                if (side < 0) side = s;
+            }
+        return side;
+    }
+
+private:
+    bool based_ = false;
+    int opens_ = -1;
+    uint32_t seen_[2] = {0, 0};
+};

pointer/helper/ft-pointer.cpp

@@ -165,9 +165,19 @@
 //   Outside games (no scene application), gaze mode keeps the pointer: the relay doesn't
 // release it when the mouse is idle ("gazeawake 1|0" tells it). A controller that moves
 // still releases it, as without gaze (last used wins), and in games the mouse wakes it and
-// idling releases it, as without gaze. Gaze mode is a mouse feature: the controllers aren't
-// part of it. Steam reads the Frame controllers itself, outside SteamVR's bindings, so
-// controller clicks at the gaze can't be done cleanly (docs/gaze-controllers.md).
+// idling releases it, as without gaze.
+//   Gaze owns the pointer: outside games, with Frametop not paused and the headset on, a fresh
+// gaze (GAZE_WAKE_FRESH) takes the pointer back whatever let it go, so the cursor never waits
+// for a tap (2026-10-18: a proximity blink, a hand by a panel, or the relay's idle timeout let it
+// go, and the first pinch after only woke it). Not while a hand is at a panel or for
+// GAZE_WAKE_NEAR after (ft-screens' near claim, below), during a touch, while a controller is in
+// use (hand tracking's handoff; without it, for GAZE_WAKE_CONTROLLER after a controller let it
+// go), after the relay's pointer_toggle turned it off ("hide toggle", until something wakes it
+// or gaze mode is turned on), or more than once per GAZE_WAKE_EVERY. It logs "gaze took the
+// pointer back" and tells the relay ("gazewoke"), which counts the pointer on.
+//   Gaze mode is a mouse feature: the controllers aren't part of it. Steam reads the Frame
+// controllers itself, outside SteamVR's bindings, so controller clicks at the gaze can't be done
+// cleanly (docs/gaze-controllers.md).
 //   The dot shows all the time in gaze mode (POINTER_GAZE_DOT=always, the default). With
 // POINTER_GAZE_DOT=moving it only shows while the mouse moves it (within POINTER_GAZE_SHOW,
 // 1 s), while a press is held, and briefly for each click (a pulse); otherwise it's
@@ -227,9 +237,14 @@
 // drags again from there. Without gaze mode they work from wherever the pointer is.
 //   The gaze calibration panel (gaze/panel/ft-gazepanel, run by the gaze service): while
 // ft-gazed says it's up ("calpanel 1", renewed every second; it lapses 3 s after the last),
-// the dot hides and a press answers the panel instead of clicking: a left click, gaze_left, or
-// a gaze_precision or gaze_drag press sends "calaccept" to @ft_gazed (take this dot now), a right
-// click or gaze_right "calquit" (calpanel.h).
+// the dot hides and a press answers the panel instead of clicking: a left click, Enter (the
+// relay's "calkey 1"), gaze_left, a gaze_precision or gaze_drag press, or an index pinch with
+// hand tracking (with or without POINTER_HANDS: a pinch's begin, so a tap and a held pinch are
+// both one) sends "calaccept" to @ft_gazed (take this dot now), a right click or gaze_right
+// "calquit" (calpanel.h). Another program's head-locked panel can take them the same way
+// ("calpanel 1 NAME", answered on @NAME: the gaze bench). The relay hears "calpanel 1|0" from
+// here, so it knows when Enter is the panel's and not the desktop's, and so does ft-screens, so
+// the palm menu waits.
 //   POINTER_ROLE (treadmill, the default, or right, left, stylus): the role our device takes while
 // connected. Treadmill is no hand, so the real controllers keep both hand roles and a controller
 // can be used beside the pointer (or a bare hand's ray). The driver must hint it from the start
@@ -374,7 +389,9 @@
 // typing before the first key, within POINTER_TYPING_RECENT (600 s) of one. A hand held back makes
 // no pinch, middle pinch or grip ("pinch right: ignored (typing: the hand is on the keyboard)"),
 // and has no ray: one that drove the pointer lets it go to the mouse or the gaze ("hand ray: right
-// -> none (typing)"), and it can't claim it again until the hand is lifted. ft-screens gets "typing
+// -> none (typing)"), and it can't claim it again until the hand is lifted. A hand that goes onto the
+// keyboard holding a pinch, grip or three-finger scroll lets go of it, as lost: no click ("hand left
+// pinch ended: typing: the hand is on the keyboard"). ft-screens gets "typing
 // <L 0|1> <R 0|1>" on @ft_screens, on a change and every second: no pokes, near grabs or "grab
 // that" by those hands. Changes go to the log ("typing: right hand on the keyboard", "typing: right
 // hand off the keyboard (raised 0.09 m)").
@@ -460,8 +477,9 @@
 // (ft-screens reads 512-byte datagrams), without ours (frametop.*), POINTER_IGNORE's, or keys with
 // spaces.
 //
-// Commands (datagrams on @ft_pointer_helper): show, hide, recenter, move <dyaw> <dpitch>,
-// follow on|off|toggle (head follow, until the next restart or a change to POINTER_FOLLOW),
+// Commands (datagrams on @ft_pointer_helper): show, hide [toggle|idle|pause] (why: see "Gaze owns
+// the pointer"), recenter, move <dyaw> <dpitch>, follow on|off|toggle (head follow, until the next
+// restart or a change to POINTER_FOLLOW),
 // gaze on|off|toggle|? (gaze mode, likewise with POINTER_GAZE; ? only asks, and "? headset" adds
 // worn|away to the reply), gz ... (the gaze, from ft-gazed),
 // reload (re-read the settings below), debug (toggle a twice-a-second state log),
@@ -925,6 +943,13 @@ constexpr double SETTINGS_ORIGIN = 0.25, SETTINGS_DOT = 0.6, SETTINGS_CATCHER =
 // A touch's grab hovers this long before it presses (a floating panel's grab bar comes up under the
 // laser), and after a release the laser holds still this long (see "Touch" at the top).
 constexpr auto kTouchHover = std::chrono::milliseconds(120), kTouchDrop = std::chrono::milliseconds(250);
+// The headset counts as off after SteamVR has said idle this long (see the main loop).
+constexpr auto HEADSET_OFF_AFTER = std::chrono::milliseconds(1500);
+// Gaze owns the pointer (see the top): a gaze this fresh takes it back, the hand this long away
+// from a panel, a controller this long after it let it go (without hand tracking's handoff),
+// and at most once per GAZE_WAKE_EVERY.
+constexpr std::chrono::milliseconds GAZE_WAKE_FRESH{250}, GAZE_WAKE_NEAR{1000}, GAZE_WAKE_CONTROLLER{5000},
+    GAZE_WAKE_EVERY{2000};
 
 // Whether the line of sight from `eye` along `d` crosses the SteamVR Settings page, drawn by
 // the dashboard's scene-graph panel (valve.steam.gamepadui.frame.menu.N, transform t); see
@@ -1209,6 +1234,9 @@ int main() {
         double yaw = 0, pitch = 0;
     } posed;
     Clock::time_point lastMouse{}, claimAt{}, claimRelease{}, wokeAt{}, noWakeUntil{};
+    // Gaze owns the pointer (see the top): a controller last let it go then; a hand was last at a
+    // panel then (ft-screens' near claim); the gaze last took it back then.
+    Clock::time_point controllerTookAt{}, nearBusyAt{}, gazeWokeAt{};
     bool claimPending = false, claimHeld = false;
     // Last used wins: since when each controller has been moving (zero: it isn't).
     Clock::time_point movingSince[vr::k_unMaxTrackedDeviceCount] = {};
@@ -1239,8 +1267,14 @@ int main() {
     Vec3 pivot, tiltOrigin, lastPoint, lastOrigin, lastAim{0, 0, -1};
     Basis tiltBasis{};
     bool headsetOff = false;  // nobody is wearing the headset (see the main loop)
+    Clock::time_point headsetIdleSince{};  // SteamVR has said idle since then (none: it doesn't)
+    bool headsetSeen = false;              // its activity level was read once
+    // Turned off on purpose (the relay's pointer_toggle, "hide toggle"): gaze mode leaves it off
+    // until something wakes it (see "Gaze owns the pointer" at the top).
+    bool pointerOff = false;
     auto wake = [&](Clock::time_point t) {
         if (t < noWakeUntil || headsetOff) return;
+        pointerOff = false;
         wokeAt = t;
         active = true;
         recenter = true;
@@ -1507,10 +1541,12 @@ int main() {
     bool pressRight = false;
     std::string heldButton = "trigger";
     bool confirmLesson = false;  // a keyboard click's quick tap: a lesson with no correction (see the top)
-    // The gaze calibration panel is up until then ("calpanel 1"; see the top); calOpened: it just
-    // came up, so a press in progress ends without a click.
+    // The gaze calibration panel is up until then ("calpanel 1"; see the top), and its answers go
+    // to calOwner; calOpened: it just came up, so a press in progress ends without a click.
     Clock::time_point calPanelUntil{};
     bool calOpened = false;
+    std::string calOwner = "ft_gazed";
+    CalPinch calPinch;
     auto pressLeft = [&] {
         // ft-screens sends the keyboard to the panel clicked last; it sees clicks on
         // its own screens, but only we know when one lands on another panel.
@@ -1860,11 +1896,21 @@ int main() {
     while (true) {
         // The headset off: SteamVR drops the HMD's activity to idle as soon as it comes off.
         // An awake pointer (a connected controller, SteamVR's laser mode forced on) kept the
-        // displays from sleeping, so it's released at once, and the mouse can't wake it until
-        // the headset is back on (then the first mouse input does).
+        // displays from sleeping, so it's released, and the mouse can't wake it until the
+        // headset is back on (then the first mouse input does, or the gaze in gaze mode).
+        // Idle for HEADSET_OFF_AFTER first: settling the headset on the face blinks the
+        // proximity sensor off for 0.3-0.5 s (five times in the first minute of a wear,
+        // 2026-10-18), and each blink let the pointer go. Standby comes 5 s after it's off.
         const auto level = sys->GetTrackedDeviceActivityLevel(vr::k_unTrackedDeviceIndex_Hmd);
-        headsetOff = level == vr::k_EDeviceActivityLevel_Idle || level == vr::k_EDeviceActivityLevel_Standby ||
-                     level == vr::k_EDeviceActivityLevel_Idle_Timeout;
+        const bool headsetIdle = level == vr::k_EDeviceActivityLevel_Idle ||
+                                 level == vr::k_EDeviceActivityLevel_Standby ||
+                                 level == vr::k_EDeviceActivityLevel_Idle_Timeout;
+        if (!headsetIdle) headsetIdleSince = {};
+        else if (headsetIdleSince == Clock::time_point{})  // (idle at the start: off already)
+            headsetIdleSince = Clock::now() - (headsetSeen ? std::chrono::milliseconds(0) : HEADSET_OFF_AFTER);
+        headsetSeen = true;
+        headsetOff = headsetIdle && (level == vr::k_EDeviceActivityLevel_Standby ||
+                                     Clock::now() - headsetIdleSince >= HEADSET_OFF_AFTER);
         if (headsetOff && active) {
             active = false;
             claimPending = claimHeld = false;
@@ -1925,7 +1971,8 @@ int main() {
                 mouseMove(mx, my);
                 continue;
             }
-            // The gaze, from ft-gazed: not mouse input, it never wakes the pointer.
+            // The gaze, from ft-gazed: not mouse input. In gaze mode a fresh one takes the pointer back
+            // in the main loop (see "Gaze owns the pointer" at the top).
             double g[4];
             if (std::sscanf(buf, "gz %lf %lf %lf %lf", &g[0], &g[1], &g[2], &g[3]) == 4) {
                 gz = {g[0], g[1], g[2], g[3], Clock::now()};
@@ -1934,18 +1981,25 @@ int main() {
             }
             // The gaze calibration panel (see the top): presses answer it instead of clicking.
             {
-                int on;
-                if (std::sscanf(buf, "calpanel %d", &on) == 1) {
+                bool on;
+                std::string owner;
+                if (calPanelClaim(buf, on, owner)) {
                     const bool was = Clock::now() < calPanelUntil;
-                    calPanelUntil = on ? Clock::now() + std::chrono::seconds(3) : Clock::time_point{};
-                    if (on && !was) calOpened = true;
+                    if (on) {
+                        calPanelUntil = Clock::now() + std::chrono::seconds(3), calOwner = owner;
+                        if (!was) calOpened = true, calPinch.Start();
+                    } else if (owner == calOwner) {  // (another's panel closing leaves this one up)
+                        calPanelUntil = Clock::time_point{};
+                    }
+                    SendTo(out, "frametop_relay", Clock::now() < calPanelUntil ? "calpanel 1" : "calpanel 0");
+                    SendTo(out, "ft_screens", Clock::now() < calPanelUntil ? "calpanel 1" : "calpanel 0");   // no palm menu
                     continue;
                 }
             }
             if (Clock::now() < calPanelUntil) {
                 const CalPanelAnswer answer = calPanelAnswer(buf);
                 if (answer == CalPanelAnswer::Accept || answer == CalPanelAnswer::Quit) {
-                    SendTo(out, "ft_gazed", answer == CalPanelAnswer::Accept ? "calaccept" : "calquit");
+                    SendTo(out, calOwner.c_str(), answer == CalPanelAnswer::Accept ? "calaccept" : "calquit");
                     continue;
                 }
                 if (answer == CalPanelAnswer::Ignore)
@@ -2095,6 +2149,7 @@ int main() {
                              : std::strncmp(arg, "off", 3) == 0 ? false
                                                                 : !gazeOn;
                     gazeOwns = true, nudging = false;
+                    if (gazeOn) pointerOff = false;  // turning gaze mode on asks for the pointer
                     std::printf("gaze mode %s\n", gazeOn ? "on" : "off");
                     std::fflush(stdout);
                 }
@@ -2202,6 +2257,13 @@ int main() {
             } else if (std::strncmp(buf, "show", 4) == 0) {
                 if (!active) wake(Clock::now());
             } else if (std::strncmp(buf, "hide", 4) == 0) {
+                // "hide toggle": turned off on purpose, so gaze mode leaves it off (see the top);
+                // "hide idle" and "hide pause" (and a plain "hide") don't keep it from the gaze.
+                if (!std::strcmp(buf, "hide toggle") && !pointerOff) {
+                    pointerOff = true;
+                    if (gazeOn) std::printf("pointer turned off: the gaze leaves it off until you wake it\n");
+                    if (gazeOn) std::fflush(stdout);
+                }
                 active = false;
                 cursorDot.Show(false);
                 markerDot.Show(false);
@@ -2294,6 +2356,7 @@ int main() {
             SendTo(out, "ft_pointer", "btn a 0");
             SendTo(out, "ft_pointer", "hide");
             noWakeUntil = tnow + std::chrono::seconds(2);
+            controllerTookAt = tnow;
             std::printf("no hand role (a controller is in use): pointer released\n");
             std::fflush(stdout);
         }
@@ -2324,6 +2387,7 @@ int main() {
                     markerDot.Show(false);
                     SendTo(out, "ft_pointer", "btn a 0");
                     SendTo(out, "ft_pointer", "hide");
+                    controllerTookAt = tnow;
                     std::printf("controller %u moved (%.2f m/s, %.1f rad/s): pointer released\n", i, speed, spin);
                     std::fflush(stdout);
                     break;
@@ -2614,11 +2678,28 @@ int main() {
         }
         // A hand at a panel (ft-screens' near claim: it pokes and taps there): no laser at all (user,
         // 2026-10-11: the laser from the head to where the fingertip put the cursor got in the way of
-        // tapping, and held the button so pokes were refused). The mouse's next move claims it back.
+        // tapping, and held the button so pokes were refused). The mouse's next move claims it back,
+        // or in gaze mode the gaze, GAZE_WAKE_NEAR after the hand left.
         if (active && hold.src == Src::None && !leftHeld && touch.side < 0 && tnow - nearAt < std::chrono::milliseconds(200) &&
             (nearClaim[0] || nearClaim[1]) && tnow - lastMouse > std::chrono::seconds(1)) {
             releasePointer("a hand touches a panel");
         }
+        if (tnow - nearAt < std::chrono::milliseconds(200) && (nearClaim[0] || nearClaim[1])) nearBusyAt = tnow;
+        // Gaze owns the pointer (see the top): whatever let it go, a fresh gaze takes it back once
+        // nothing else should have it.
+        if (!active && gazeOn && !pointerOff && !inGame && !framePaused && !headsetOff &&
+            tnow - gz.at < GAZE_WAKE_FRESH && tnow - nearBusyAt > GAZE_WAKE_NEAR && touch.side < 0 &&
+            tnow - gazeWokeAt > GAZE_WAKE_EVERY && !controllerBusy(tnow) &&
+            (handsTrack ? !arbiter.IsController(0) && !arbiter.IsController(1)
+                        : tnow - controllerTookAt > GAZE_WAKE_CONTROLLER)) {
+            gazeWokeAt = tnow;
+            wake(tnow);
+            if (active) {
+                SendTo(out, "frametop_relay", "gazewoke");  // the relay counts the pointer on again
+                std::printf("gaze took the pointer back\n");
+                std::fflush(stdout);
+            }
+        }
         // Where a gesture's point is, seen from the hold's origin: yaw and pitch, degrees.
         auto handAngles = [&](const float p[3], uint64_t t_ns, const Vec3 &from, double &hy, double &hp) {
             vr::HmdMatrix34_t head;
@@ -2650,8 +2731,10 @@ int main() {
                 if (gazeOn) gazeOwns = true, nudging = false;
                 std::printf("three-finger pinch %s: scrolled at the gaze on %s (stick up to %.2f, held %.2f s)%s\n",
                             hold.side ? "right" : "left", lastHit.empty() ? "nothing" : lastHit.c_str(), hold.scrollMax,
-                            secsOf(tnow) - hold.gaze.Began(), lost ? ": the hand was lost" : "");
+                            secsOf(tnow) - hold.gaze.Began(),
+                            !lost ? "" : gazeEndWhy.empty() ? ": the hand was lost" : (": " + gazeEndWhy).c_str());
                 std::fflush(stdout);
+                gazeEndWhy.clear();
                 hold = {};
                 return;
             }
@@ -2890,6 +2973,32 @@ int main() {
         fh_gestures_t hg;
         const bool handOk = handsOn && handFile.Read(hg);
         if (handOk) handOkAt = tnow;
+        // The gaze calibration panel (see the top): an index pinch's begin takes the dot, with or
+        // without POINTER_HANDS, as long as a pinch could click now (not over a VR game, not by a
+        // hand typing holds back or one at a controller). Every gesture is the panel's meanwhile
+        // (below), so nothing else starts.
+        if (tnow < calPanelUntil) {
+            fh_gestures_t cg;
+            bool calHands = handOk;
+            if (handOk) cg = hg;
+            else if (!handsOn) calHands = handFile.Read(cg);
+            const int s = calHands ? calPinch.Began(cg, handFile.opens) : -1;
+            if (s >= 0) {
+                const char *why = nullptr;
+                vr::HmdMatrix34_t head;
+                // (handsAllowed and the arbiter keep up only with hand interaction on)
+                if (!(handsTrack ? handsAllowed : !headsetOff && !inGame)) why = "hands not allowed: a VR game, or the headset off";
+                else if (const char *t = typist.Why(s, secsOf(tnow))) why = t;
+                else if (arbiter.IsController(s)) why = "at a controller";
+                else if (poses.At(cg.pinch[s].begin_ns, head)) {
+                    const Vec3 at = hin::ToRoom(head, cg.pinch[s].begin_point);
+                    if (arbiter.NearController({at.x, at.y, at.z})) why = "at a controller";
+                }
+                if (!why) SendTo(out, calOwner.c_str(), "calaccept");
+                pinchLog(s, 0, why ? std::string("ignored by the gaze calibration panel (") + why + ")"
+                                   : std::string("took the gaze calibration panel's dot"));
+            }
+        }
         const char *const kLostPinch = "ft-hands lost the hand, or a grip took the pinch";
         // A ray hold (see "Hand ray" at the top): the pinch's press goes out once the laser claim
         // has landed; a middle pinch is a right click (a tap) or scrolling (held and moved).
@@ -3140,6 +3249,17 @@ int main() {
             rayHoldCancel = false;
             if (hold.src == Src::Ray) endRayHold(true, "the ray went (a controller, the mouse, or hand input off)");
         }
+        // A hand that went onto the keyboard lets go of what it held (a pinch, grip or three-finger scroll,
+        // the chord's right button), as lost: no click. Ray holds end above, when typing drops the ray.
+        if (hold.src == Src::Hand && hold.side >= 0 && typist.Parked(hold.side)) {
+            if (!hold.gaze.On()) {   // gaze pinches and three-finger scrolls say why themselves
+                std::printf("hand %s %s ended: typing: the hand is on the keyboard\n", hold.side ? "right" : "left",
+                            hold.grip ? "grip" : "pinch");
+                std::fflush(stdout);
+            }
+            endGesture(true, "typing: the hand is on the keyboard");
+        }
+        if (chordBtn.On() && chordSide >= 0 && typist.Parked(chordSide)) chordEnds(true, "typing: the hand is on the keyboard");
         if (handOk && (hg.seq != handSeq || handFile.opens != handOpens)) {
             handSeq = hg.seq;
             handPublished = hg.publish_ns;
@@ -3190,6 +3310,7 @@ int main() {
                     for (PendingBegin &p : pendingBegins)
                         if (p.side == s && p.kind == k && ended) p.ended = true, p.lost = lost;
                     if (!began) continue;
+                    if (tnow < calPanelUntil) continue;   // the gaze calibration panel's (above): no gesture
                     if (k != 1 && hold.src == Src::Ray && hold.rayThree && hold.side == s) continue;   // its other finger
                     if (!allowed) {
                         if (k != 1) pinchLog(s, k, "ignored (hands not allowed: a VR game, or the headset off)");
@@ -3349,6 +3470,7 @@ int main() {
             }
             const PendingBegin q = p;
             pendingBegins.erase(pendingBegins.begin() + long(i));
+            if (tnow < calPanelUntil) continue;   // the gaze calibration panel came up meanwhile
             if (reported && nearClaim[q.side]) {
                 if (q.kind != 1) pinchLog(q.side, q.kind, "left to ft-screens (the hand is near its panel)");
                 else if (debug) std::printf("hand %s grip left to ft-screens (near)\n", q.side ? "right" : "left");

pointer/test/calpanel-test.cpp

@@ -1,11 +1,22 @@
 // Offline test of the gaze calibration panel's answers (pointer/helper/calpanel.h): which relay
-// messages take the dot, close the panel, or do nothing while it's up. Needs no SteamVR.
+// messages take the dot, close the panel, or do nothing while it's up; whose panel a claim is;
+// and which index pinches take the dot. Needs no SteamVR.
 //
 //   pointer/test/calpanel-test.sh
 #include "../helper/calpanel.h"
 
 #include <cstdio>
 
+static int failed = 0, total = 0;
+
+static void check(bool ok, const char *what) {
+    ++total;
+    if (!ok) {
+        std::printf("FAIL %s\n", what);
+        ++failed;
+    }
+}
+
 int main() {
     struct Case {
         const char *msg;
@@ -13,6 +24,7 @@ int main() {
     } cases[] = {
         {"btn trigger 1", CalPanelAnswer::Accept},
         {"gazekey left 1", CalPanelAnswer::Accept},
+        {"calkey 1", CalPanelAnswer::Accept},  // Enter, from the relay while the panel is up
         {"precision mouse 1", CalPanelAnswer::Accept},
         {"precision keyboard 1", CalPanelAnswer::Accept},
         {"gazedrag mouse 1", CalPanelAnswer::Accept},
@@ -26,6 +38,8 @@ int main() {
         {"btn system 1", CalPanelAnswer::Ignore},
         {"gazekey left 0", CalPanelAnswer::Ignore},
         {"gazekey right 0", CalPanelAnswer::Ignore},
+        {"calkey 0", CalPanelAnswer::Ignore},
+        {"calkey 10", CalPanelAnswer::Ignore},
         {"precision mouse 0", CalPanelAnswer::Ignore},
         {"gazedrag mouse 0", CalPanelAnswer::Ignore},
         {"move 0.1000 -0.2000", CalPanelAnswer::None},
@@ -35,15 +49,66 @@ int main() {
         {"typing", CalPanelAnswer::None},
     };
     const char *names[] = {"none", "accept", "quit", "ignore"};
-    int failed = 0;
     for (const Case &c : cases) {
         const CalPanelAnswer got = calPanelAnswer(c.msg);
-        if (got != c.want) {
-            std::printf("FAIL \"%s\": %s, want %s\n", c.msg, names[int(got)], names[int(c.want)]);
-            ++failed;
-        }
+        char what[96];
+        std::snprintf(what, sizeof what, "\"%s\": %s, want %s", c.msg, names[int(got)], names[int(c.want)]);
+        check(got == c.want, what);
     }
-    std::printf("%s: %d of %zu cases\n", failed ? "FAILED" : "ok", int(sizeof cases / sizeof cases[0]) - failed,
-                sizeof cases / sizeof cases[0]);
+
+    // Claims: whose panel, and what isn't one.
+    struct Claim {
+        const char *msg;
+        bool is, on;
+        const char *owner;
+    } claims[] = {
+        {"calpanel 1", true, true, "ft_gazed"},
+        {"calpanel 0", true, false, "ft_gazed"},
+        {"calpanel 1 ft_gazebench.1234", true, true, "ft_gazebench.1234"},
+        {"calpanel 0 ft_gazebench.1234", true, false, "ft_gazebench.1234"},
+        {"calpanel 1  ft-bench", true, true, "ft-bench"},
+        {"calpanel 2", false, false, ""},
+        {"calpanel", false, false, ""},
+        {"calpanel 1 bad/name", false, false, ""},
+        {"calpanel 1 two words", false, false, ""},
+        {"calpanel 1 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", false, false, ""},  // 65
+        {"calpaneling 1", false, false, ""},
+    };
+    for (const Claim &c : claims) {
+        bool on = false;
+        std::string owner;
+        const bool is = calPanelClaim(c.msg, on, owner);
+        char what[160];
+        std::snprintf(what, sizeof what, "claim \"%s\": %d %d %s", c.msg, is, on, owner.c_str());
+        check(is == c.is && (!is || (on == c.on && owner == c.owner)), what);
+    }
+
+    // Pinches: only ones begun after Start, one answer a call, a new file or counters going back
+    // start counting again.
+    fh_gestures_t g{};
+    CalPinch p;
+    g.pinch[0].begins = 5, g.pinch[1].begins = 2;
+    p.Start();
+    check(p.Began(g, 1) == -1, "pinch: the first look only counts");
+    check(p.Began(g, 1) == -1, "pinch: nothing new");
+    g.pinch[1].begins = 3;
+    check(p.Began(g, 1) == 1, "pinch: the right hand's");
+    check(p.Began(g, 1) == -1, "pinch: taken once");
+    g.grip[0].begins = 9, g.pinch2[0].begins = 4;
+    check(p.Began(g, 1) == -1, "pinch: grips and middle pinches aren't");
+    g.pinch[0].begins = 6, g.pinch[1].begins = 4;
+    check(p.Began(g, 1) == 0, "pinch: both at once is one answer");
+    check(p.Began(g, 1) == -1, "pinch: ...and both are counted");
+    g.pinch[0].begins = 7;
+    check(p.Began(g, 2) == -1, "pinch: a new file starts over");
+    g.pinch[0].begins = 1;
+    check(p.Began(g, 2) == -1, "pinch: counters that went back start over");
+    g.pinch[0].begins = 2;
+    check(p.Began(g, 2) == 0, "pinch: then counts again");
+    p.Start();
+    g.pinch[0].begins = 3;
+    check(p.Began(g, 2) == -1, "pinch: one from before the panel opened doesn't count");
+
+    std::printf("%s: %d of %d cases\n", failed ? "FAILED" : "ok", total - failed, total);
     return failed ? 1 : 0;
 }

pointer/tests/typing-test.cpp

@@ -279,6 +279,22 @@ void TestPointAndEnter() {
     CHECK(k.ty.Parked(1) && k.Blocked(1), "a typing hand with its ray up: on the keyboard");
 }
 
+// A hand holding a gesture (busy: a three-finger scroll, live 2026-10-18 16:4x) out of the zone is
+// free; brought down onto the keys while the other hand types, it's on the keyboard, so the helper
+// ends what it held (Parked).
+void TestHoldOntoTheKeys() {
+    World w;
+    w.hands[0] = Pointing(0), w.hands[1] = Keys(1);
+    w.hands[0].busy = true;
+    w.Run(1, 0.2);
+    CHECK(!w.ty.Parked(0) && !w.Blocked(0), "holding, raised, the other hand typing: free (%s)", w.ty.Why(0, w.t));
+    w.hands[0] = Keys(0);
+    w.hands[0].busy = true;
+    w.Run(0.3, 0.2);
+    CHECK(w.ty.Parked(0), "still holding, down on the keys: on the keyboard");
+    CHECK(w.log.find("left hand on the keyboard") != std::string::npos, "logged: %s", w.log.c_str());
+}
+
 // A palm turned up (the palm menu's pose) leaves the keyboard too.
 void TestTurned() {
     World w;
@@ -339,6 +355,7 @@ int main() {
     TestMouseUser();
     TestLost();
     TestPointAndEnter();
+    TestHoldOntoTheKeys();
     TestTurned();
     TestOff();
     TestHeading();

power/build.sh

@@ -7,4 +7,5 @@ exec "$root/scripts/frame.sh" -C power 'set -e; mkdir -p build
 . ../scripts/openvr.sh
 g++ -std=c++17 -O2 -Wall -Wno-unused-parameter $OPENVR_CFLAGS \
   -o build/ft-powerd ft-powerd.cpp $OPENVR_LIBS
+strip --strip-unneeded build/ft-powerd
 echo "built build/ft-powerd"'

recorder/button.py

@@ -172,11 +172,15 @@ class ButtonReader:
     """Reads the headset button on a thread and calls on_gesture("press" | "double" | "hold")
     (ButtonGestures). path: an event device or, for testing, a FIFO carrying input_event
     structs. It's opened read-only and shared; if it can't be opened (no device, no permission,
-    /dev/input not reachable in a container) it says so in the log and tries again now and then."""
+    /dev/input not reachable in a container) it says so in the log and tries again now and then.
+    on_down(t), if given, is called at each new press as it goes down (a bounce isn't one), after
+    the gestures that down made due: t is when, on time.monotonic(). A "press" comes a double-press
+    time after its release, so the gaze bench takes its down's time from this."""
 
     def __init__(self, path, on_gesture, log=None, double_s=BUTTON_DOUBLE_S, hold_s=BUTTON_HOLD_S,
-                 bounce_s=BUTTON_BOUNCE_S):
+                 bounce_s=BUTTON_BOUNCE_S, on_down=None):
         self.path, self.on_gesture, self.log = path, on_gesture, log or (lambda s: None)
+        self.on_down = on_down
         self.gestures = ButtonGestures(double_s, hold_s, bounce_s)
         self.ok = False      # opened at least once
         self._stop = threading.Event()
@@ -229,6 +233,8 @@ class ButtonReader:
                     for is_down, t in events:
                         at = now - min(max(events[-1][1] - t, 0.0), 2.0)
                         self._report(self.gestures.down(at) if is_down else self.gestures.up(at))
+                        if is_down and self.on_down and self.gestures.down_at == at:
+                            self.on_down(at)
             except OSError as e:   # the device went away
                 self.log("headset button: %s: %s" % (self.path, e.strerror))
                 self._stop.wait(2)

recorder/contributions.py

@@ -0,0 +1,118 @@
+"""The contributions log: what a contributor has uploaded, kept after the recordings are deleted.
+
+A session's uploads are recorded in its own session.json (recorder/hub.py record_upload), so
+deleting the session to free space would lose them. This log keeps one entry per finished upload
+in BASE/contributions.json, next to profile.json:
+
+  {"schema": 1, "contributions": [
+     {"session", "repo", "pr_url", "pr_num", "uploaded", "export_sha", "export_bytes",
+      "bounty": {"id", "title"} | {}, "kind": "public" | "testing", "debug": bool,
+      "started", "minutes", "local_deleted": "<time>" | ""}]}
+
+An entry is keyed by (repo, pr_num), or (repo, session, export_sha) for one without a pull request
+number. hub.py adds the entry when an upload finishes; the window backfills uploads that older
+recorders recorded only in session.json, and marks an entry when its local copy is deleted.
+Nothing here leaves the Frame.
+
+Standard library only."""
+import datetime
+import json
+import os
+
+SCHEMA = 1
+FILE = "contributions.json"
+
+
+def path(base):
+    return os.path.join(base, FILE)
+
+
+def now_iso():
+    return datetime.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def load(base):
+    """The log's entries, oldest first ([] when there's none or it can't be read)."""
+    try:
+        with open(path(base), encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return []
+    items = data.get("contributions") if isinstance(data, dict) else None
+    return [c for c in items if isinstance(c, dict) and c.get("session")] if isinstance(items, list) else []
+
+
+def _save(base, items):
+    os.makedirs(base, mode=0o700, exist_ok=True)
+    p = path(base)
+    tmp = p + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump({"schema": SCHEMA, "contributions": items}, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, p)
+
+
+def _key(c):
+    if c.get("pr_num") not in (None, ""):
+        return (c.get("repo", ""), "pr", str(c["pr_num"]))
+    return (c.get("repo", ""), c.get("session", ""), c.get("export_sha", ""))
+
+
+def entry(session, meta, upload, export_bytes=0, minutes=None):
+    """A log entry for a finished upload: session id, its session.json (meta), the upload's
+    record (session.json "uploads", status done), and what the export held when known."""
+    bounty = meta.get("bounty") if isinstance(meta.get("bounty"), dict) else {}
+    consent = meta.get("consent") if isinstance(meta.get("consent"), dict) else {}
+    debug = bool(meta.get("debug"))
+    return {"session": session, "repo": upload.get("repo", ""), "pr_url": upload.get("pr_url", ""),
+            "pr_num": upload.get("pr_num"), "uploaded": upload.get("uploaded", ""),
+            "export_sha": upload.get("export_sha", ""), "export_bytes": int(export_bytes or 0),
+            "bounty": {"id": bounty.get("id", ""), "title": bounty.get("title", "")} if bounty else {},
+            "kind": "testing" if consent.get("kind") == "testing" or debug else "public", "debug": debug,
+            "started": meta.get("started", ""), "minutes": minutes, "local_deleted": ""}
+
+
+def done_uploads(meta):
+    """session.json's finished uploads (records from before 2026-10-03 have no status: done)."""
+    return [u for u in meta.get("uploads") or [] if isinstance(u, dict)
+            and u.get("status", "done") == "done" and u.get("pr_url")]
+
+
+def add(base, items):
+    """Add entries (a list) the log doesn't have yet, and fill in what an existing entry lacks.
+    Returns how many were new."""
+    log = load(base)
+    known = {_key(c): c for c in log}
+    new = 0
+    for c in items:
+        old = known.get(_key(c))
+        if old is None:
+            log.append(dict(c))
+            known[_key(c)] = log[-1]
+            new += 1
+        else:
+            for k, v in c.items():
+                if k != "local_deleted" and v not in (None, "", {}, 0) and old.get(k) in (None, "", {}, 0):
+                    old[k] = v
+    if items:
+        _save(base, log)
+    return new
+
+
+def mark_deleted(base, session, when=None):
+    """Note that a session's local copy was deleted (its entries stay)."""
+    log = load(base)
+    when = when or now_iso()
+    hit = False
+    for c in log:
+        if c.get("session") == session and not c.get("local_deleted"):
+            c["local_deleted"] = when
+            hit = True
+    if hit:
+        _save(base, log)
+    return hit
+
+
+def sessions(base):
+    """The session ids the log has a finished upload of."""
+    return {c["session"] for c in load(base)}

recorder/tests/test_stay_awake.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python3
+"""recorder/window.py's _stay_awake: the awake unit runs while any export or upload does, even
+when its workers run out of order (2026-10-17: a queued export's end and its upload's start come
+together, and an export's stop could land after the upload's start). Needs PySide6 (the
+standalone recorder's venv, or the dev container).
+
+  python3 recorder/tests/test_stay_awake.py
+"""
+import os
+import sys
+import tempfile
+import types
+import unittest
+from unittest import mock
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", ".."))
+try:
+    from recorder import window
+except ImportError:   # no PySide6
+    window = None
+
+
+@unittest.skipIf(window is None, "no PySide6")
+class StayAwakeTest(unittest.TestCase):
+    def setUp(self):
+        class Backend(window.RecorderBackend):
+            AWAKE_UNIT = "ft-test-awake"
+        self.base = tempfile.mkdtemp(prefix="recorder-awake-test-")
+        self.backend = Backend(types.SimpleNamespace(base=self.base), types.SimpleNamespace())
+        self.workers = []   # held back, to run in any order
+        self.backend._thread = self.workers.append
+        self.calls = []
+        for name in ("start_unit", "stop_unit"):
+            p = mock.patch.object(window.units, name, side_effect=lambda *a, n=name, **k: self.calls.append(n))
+            p.start()
+            self.addCleanup(p.stop)
+
+    def tearDown(self):
+        os.rmdir(self.base)
+
+    def run_workers(self, order):
+        for i in order:
+            self.workers[i]()
+        self.workers.clear()
+
+    def test_on_then_off(self):
+        self.backend._stay_awake("export", True)
+        self.run_workers([0])
+        self.backend._stay_awake("export", False)
+        self.run_workers([0])
+        self.assertEqual(self.calls, ["start_unit", "stop_unit"])
+
+    def test_export_ends_as_its_upload_starts(self):
+        self.backend._stay_awake("export", True)
+        self.run_workers([0])
+        self.backend._stay_awake("upload", True)
+        self.backend._stay_awake("export", False)
+        self.run_workers([1, 0])   # the export's stop runs first
+        self.assertEqual(self.calls, ["start_unit"])   # never stopped: the upload holds it
+
+    def test_out_of_order_off(self):
+        self.backend._stay_awake("export", True)
+        self.backend._stay_awake("export", False)
+        self.run_workers([1, 0])   # the stop's worker runs before the start's
+        self.assertEqual(self.calls, [])   # nothing to keep awake by then: never started
+
+
+if __name__ == "__main__":
+    unittest.main()

recorder/window.py

@@ -1,7 +1,7 @@
 """What the recorders' windows share (hands/rec/ft_handrec.py, gaze/rec/ft_eyerec.py): a QObject
-backend with the consent and profile, the session's controls, export on a thread, the Hugging Face
-login and upload in hub.py child processes, the Frame kept awake while they run, and small
-helpers. Each recorder's Backend inherits it, adds its checklist, session and review, and keeps
+backend with the consent and profile, the session's controls, export on a thread (one at a time,
+the rest queued), the Hugging Face login and upload in hub.py child processes (an export can upload
+by itself once it's done), the Frame kept awake while they run, and small helpers. Each recorder's Backend inherits it, adds its checklist, session and review, and keeps
 these slot and property names, which its main.qml calls.
 
 A "session" here is what the recorder records in one go: a hand session, or an eye round.
@@ -145,12 +145,21 @@ class RecorderBackend(QObject):
         self._session_id = ""
         self._status = {}
         self._awake = set()          # what keeps the Frame awake now: "export", "upload"
+        self._awake_on = False       # the awake unit runs (set under _awake_lock)
         self._awake_lock = threading.Lock()
         self._export_cancel = None
         self._export_thread = None
         self._export_fraction = 0.0
         self._export_text = ""
         self._export_session = ""
+        # Waiting their turn: exports [{"session", "keep_notes"}], then uploads [session]. The
+        # sessions in _upload_after upload by themselves once exported (queued or running).
+        self._export_queue = []
+        self._upload_after = set()
+        self._upload_queue = []
+        # What the exports and uploads came to, newest last, for whoever comes back to the
+        # headset: [{"text", "error", "link"}].
+        self._done_log = []
         self._statusArrived.connect(self._on_status)
         self._exportProgress.connect(self._on_export_progress)
         self._exportFinished.connect(self._on_export_finished)
@@ -197,6 +206,10 @@ class RecorderBackend(QObject):
         the dataset."""
         return {"SESSION": session}
 
+    def _session_label(self, session):
+        """How the window names a session in a message."""
+        return session
+
     def _keep_awake(self):
         """False: don't start the awake unit (a dry run)."""
         return not self._hub_dry_run
@@ -369,6 +382,8 @@ class RecorderBackend(QObject):
                 self._session.stop()
             except Exception:
                 pass
+        self._export_queue, self._upload_queue = [], []
+        self._upload_after.clear()
         if self._export_cancel:
             self._export_cancel.set()
             self._export_thread.join(15)
@@ -376,7 +391,7 @@ class RecorderBackend(QObject):
         if self._upload_proc:
             self.cancelUpload()
             self._upload_thread.join(10)
-        if self._awake and self.AWAKE_UNIT:
+        if (self._awake or self._awake_on) and self.AWAKE_UNIT:
             try:
                 units.stop_unit(self.AWAKE_UNIT)
             except Exception:
@@ -410,30 +425,130 @@ class RecorderBackend(QObject):
     def _stay_awake(self, why, on):
         """Hold off sleep while an export or upload runs, so the headset can be taken off and
         left plugged in: a host unit running systemd-inhibit, started with the first reason
-        and stopped with the last."""
+        and stopped with the last. The reasons change here, on this thread; each worker brings
+        the unit to what they are when it runs, so workers finishing out of order (an export's
+        end, then its upload's start) leave it right."""
         if not self.AWAKE_UNIT or not self._keep_awake():
             return
+        (self._awake.add if on else self._awake.discard)(why)
 
         def run():
             with self._awake_lock:
-                had = bool(self._awake)
-                (self._awake.add if on else self._awake.discard)(why)
+                want = bool(self._awake)
+                if want == self._awake_on:
+                    return
                 try:
-                    if self._awake and not had:
+                    if want:
                         units.start_unit(self.AWAKE_UNIT, "keeps the Frame awake while exporting or uploading",
                                          ["systemd-inhibit", "--what=sleep:idle", "--mode=block",
                                           "--who=" + self.APP, "--why=" + self.AWAKE_WHY, "sleep", "infinity"],
                                          app=self.APP)
-                    elif had and not self._awake:
+                    else:
                         units.stop_unit(self.AWAKE_UNIT)
+                    self._awake_on = want
                 except Exception as e:
                     print(f"keeping the Frame awake: {e}", file=sys.stderr, flush=True)
         self._thread(run)
 
+    def _exporting(self, session):
+        return self.exporting and self._export_session == session
+
+    def _uploading(self, session):
+        return self.uploading and self._upload.get("session") == session
+
+    def _queued(self, session):
+        """Waiting to export, or to upload."""
+        return (any(q["session"] == session for q in self._export_queue)
+                or session in self._upload_queue)
+
+    def _busy_guard(self, session):
+        """Its export or upload runs or waits: its recordings and export stay until then."""
+        if self._exporting(session) or self._uploading(session) or self._queued(session):
+            self.message.emit("This session is exporting or uploading, or waiting to: "
+                              "cancel that first (on the Export page)", True)
+            return True
+        return False
+
+    @Property("QVariantList", notify=exportChanged)
+    def exportQueue(self):
+        """The exports waiting their turn, in order: [{"session", "upload"}]."""
+        return [{"session": q["session"], "upload": q["session"] in self._upload_after} for q in self._export_queue]
+
+    @Property("QVariantList", notify=exportChanged)
+    def uploadAfter(self):
+        """The sessions that upload by themselves once exported (the running export's too)."""
+        return sorted(self._upload_after)
+
+    @Property("QVariantList", notify=uploadChanged)
+    def uploadQueue(self):
+        """The exported sessions waiting to upload, in order."""
+        return list(self._upload_queue)
+
+    @Property("QVariantList", notify=exportChanged)
+    def doneLog(self):
+        return list(self._done_log)
+
+    def _log_done(self, text, error=False, link=""):
+        self._done_log = (self._done_log + [{"text": text, "error": error, "link": link}])[-20:]
+        self.exportChanged.emit()
+
+    @Slot()
+    def clearDoneLog(self):
+        self._done_log = []
+        self.exportChanged.emit()
+
     @Slot(str, bool)
     def exportSession(self, session, keep_notes):
-        if self.exporting or self._active_guard(session):
+        self.queueExport(session, keep_notes, False)
+
+    @Slot(str, bool, bool)
+    def queueExport(self, session, keep_notes, upload):
+        """Export it now, or after the exports already waiting (one at a time). upload: once it's
+        exported, it uploads by itself (it waits for any upload before it)."""
+        # Another session's upload can go on: the export writes beside its own export (.partial)
+        # and only replaces that one at the end, so not while it's uploading or waiting to.
+        if self._uploading(session) or session in self._upload_queue or self._active_guard(session):
             return
+        if upload:
+            self._upload_after.add(session)
+        if self._exporting(session) or any(q["session"] == session for q in self._export_queue):
+            self.exportChanged.emit()   # already on its way: only whether it uploads changed
+            return
+        self._export_queue.append({"session": session, "keep_notes": keep_notes})
+        if self.exporting:
+            self.exportChanged.emit()
+        else:
+            self._next_export()
+
+    @Slot(str, bool)
+    def setUploadAfter(self, session, on):
+        """Whether a queued or running export uploads by itself once it's done."""
+        if not (self._exporting(session) or any(q["session"] == session for q in self._export_queue)):
+            return
+        (self._upload_after.add if on else self._upload_after.discard)(session)
+        self.exportChanged.emit()
+
+    @Slot(str)
+    def unqueueExport(self, session):
+        """Take a waiting export out of the queue (the running one: cancelExport)."""
+        self._export_queue = [q for q in self._export_queue if q["session"] != session]
+        self._upload_after.discard(session)
+        self.exportChanged.emit()
+
+    @Slot(str)
+    def unqueueUpload(self, session):
+        if session in self._upload_queue:
+            self._upload_queue.remove(session)
+            self.uploadChanged.emit()
+
+    def _next_export(self):
+        """Start the first waiting export, if none runs."""
+        if self.exporting or not self._export_queue:
+            return
+        q = self._export_queue.pop(0)
+        self._start_export(q["session"], q["keep_notes"])
+
+    def _start_export(self, session, keep_notes):
         cancel = threading.Event()
         self._export_cancel = cancel
         self._export_session = session
@@ -455,7 +570,9 @@ class RecorderBackend(QObject):
 
     @Slot()
     def cancelExport(self):
+        """Cancel the running export (and its upload after); the next waiting one starts."""
         if self._export_cancel:
+            self._upload_after.discard(self._export_session)
             self._export_cancel.set()
             self._export_text = "Cancelling"
             self.exportChanged.emit()
@@ -466,23 +583,54 @@ class RecorderBackend(QObject):
             self.exportChanged.emit()
 
     def _on_export_finished(self, path, error):
+        session = self._export_session
+        send = session in self._upload_after
+        self._upload_after.discard(session)
         self._export_cancel = None
-        self._stay_awake("export", False)
+        label = self._session_label(session)
         if error == "cancelled":
             self._export_text = "Cancelled: nothing was kept"
+            self._log_done(f"{label}: export cancelled")
         elif error:
             self._export_text = "Failed: " + error
             self.message.emit("Export failed: " + error, True)
+            self._log_done(f"{label}: export failed: {error}", True)
         else:
             self._export_fraction = 1.0
             self._export_text = f"Exported to {path} ({human_bytes(tree_bytes(path))})"
             self.message.emit("Export ready", False)
+            self._log_done(f"{label}: exported ({human_bytes(tree_bytes(path))})")
         self.exportChanged.emit()
         self.refreshSessions()
-        self.exportDone.emit(self._export_session, not error)
+        self.exportDone.emit(session, not error)
+        if send and not error:
+            self._queue_upload(session)
+        self._next_export()
+        if not self.exporting:
+            self._stay_awake("export", False)
+
+    def _queue_upload(self, session):
+        """An export done that uploads by itself: now, or after the upload running."""
+        if session not in self._upload_queue and not self._uploading(session):
+            self._upload_queue.append(session)
+            self.uploadChanged.emit()
+        self._next_upload()
+
+    def _next_upload(self):
+        """Start the first waiting upload that still can, if none runs. One already uploaded
+        (the same export) isn't sent again; one that can't go now says why and leaves the queue."""
+        while not self.uploading and self._upload_queue:
+            session = self._upload_queue.pop(0)
+            if self.uploadInfo(session)["previous"].get("export_sha"):
+                self._log_done(f"{self._session_label(session)}: this export was uploaded before, so it wasn't sent again")
+            elif self._start_upload(session, False):
+                return
+        self.uploadChanged.emit()
 
     @Slot(str)
     def deleteExport(self, session):
+        if self._busy_guard(session):
+            return
         try:
             self.store.delete_export(session)
             self.message.emit("Export deleted; the recordings stay", False)
@@ -674,13 +822,28 @@ class RecorderBackend(QObject):
             return {"previous": {}, "uploads": 0}
         return {"previous": before or {}, "uploads": count}
 
+    @Property(bool, notify=loginChanged)
+    def canUploadAfter(self):
+        """An export can be set to upload by itself: logged in (or a dry run). Whether its
+        dataset takes contributions yet: uploadAllowedFor."""
+        return self._hub_dry_run or self._login.get("state") == "ok"
+
     @Slot(str, bool)
     def startUpload(self, session, again):
-        if self.uploading or self.exporting or self._active_guard(session):
-            return
+        if session in self._upload_queue:
+            self._upload_queue.remove(session)   # pressed by hand: it goes now
+        self._start_upload(session, again)
+        self.uploadChanged.emit()
+
+    def _start_upload(self, session, again):
+        """Start hub.py upload; False if it couldn't (and it said why)."""
+        # Not while this session exports again (its export is replaced at the end); another's is fine.
+        if (self.uploading or self._exporting(session) or any(q["session"] == session for q in self._export_queue)
+                or self._active_guard(session)):
+            return False
         if not self._hub_dry_run and not self._upload_allowed_for(session):
             self.message.emit("Contributions aren't open yet", True)
-            return
+            return False
         argv = self._hub_argv("upload", session, "--json")
         if self._hub_dry_run:
             argv.append("--dry-run")
@@ -691,7 +854,7 @@ class RecorderBackend(QObject):
                                     text=True, bufsize=1)
         except OSError as e:
             self.message.emit(f"Couldn't start the upload: {e}", True)
-            return
+            return False
         self._upload_proc = proc
         self._upload_cancelled = False
         self._upload = {"session": session, "phase": "check", "text": "Starting", "fraction": 0.0, "log": "",
@@ -703,6 +866,7 @@ class RecorderBackend(QObject):
             last = self._read_lines(proc, self._uploadLine, lambda: self._upload_cancelled, "The upload stopped")
             self._uploadFinished.emit(last or {"error": {"kind": "cancelled", "text": "Cancelled"}})
         self._upload_thread = self._thread(run)
+        return True
 
     @Slot()
     def cancelUpload(self):
@@ -726,7 +890,6 @@ class RecorderBackend(QObject):
 
     def _on_upload_finished(self, last):
         self._upload_proc = None
-        self._stay_awake("upload", False)
         up = dict(self._upload)
         if "done" in last:
             result = last["done"]
@@ -734,6 +897,9 @@ class RecorderBackend(QObject):
                       text="Dry run: nothing was uploaded" if result.get("dry_run") else "Uploaded")
             if not result.get("dry_run"):
                 self.message.emit("Uploaded: the pull request is open", False)
+            self._log_done(f"{self._session_label(up.get('session', ''))}: "
+                           + ("dry run, nothing sent" if result.get("dry_run") else "uploaded"),
+                           link=result.get("pr_url", ""))
         else:
             e = last.get("error") or {}
             cancelled = e.get("kind") == "cancelled"
@@ -742,9 +908,15 @@ class RecorderBackend(QObject):
                             if up.get("pr_url") else "Cancelled") if cancelled else e.get("text", ""))
             if not cancelled:
                 self.message.emit("Upload failed", True)
+            self._log_done(f"{self._session_label(up.get('session', ''))}: upload "
+                           + ("cancelled" if cancelled else "failed: " + e.get("text", "")),
+                           not cancelled, up.get("pr_url", "") or e.get("link", ""))
         self._upload = up
         self.uploadChanged.emit()
         self.sessionsChanged.emit()
+        self._next_upload()
+        if not self.uploading:
+            self._stay_awake("upload", False)
 
     @Slot(str, result=str)
     def uploadText(self, session):

remote-displays/ft_remote_displays.py

@@ -246,7 +246,8 @@ class Backend(QObject):
             out.append({"name": h.get("name", ""), "address": address, "kind": h.get("kind", "vibepollo"),
                         "hasToken": address in self._logins if sunshine else os.path.exists(token_path(address)),
                         "online": self._online.get(address), "route": h.get("route", "auto"),
-                        "direct": ", ".join(h.get("direct", [])), "displays": displays})
+                        "direct": ", ".join(h.get("direct", [])), "mic": bool(h.get("mic")),
+                        "displays": displays})
         return out
 
     # --- hosts ---
@@ -399,6 +400,12 @@ class Backend(QObject):
         self._run(f"Connecting {name} {dict(auto='either way', network='over the network', dongle='over the dongle')[route]}",
                   "remote", "host", name, f"route={route}")
 
+    @Slot(str, bool)
+    def setMic(self, name, on):
+        """Send the Frame's microphone to the host (its streams pick it up within 3 s)."""
+        self._run(f"{'Sending' if on else 'Not sending'} the microphone to {name}",
+                  "remote", "host", name, f"mic={'on' if on else 'off'}")
+
     @Slot(str, str)
     def setDirect(self, name, text):
         addresses = [a for a in re.split(r"[\s,]+", text.strip()) if a]

remote-displays/main.qml

@@ -453,6 +453,18 @@ Kirigami.ApplicationWindow {
                                     }
                                 }
                             }
+                            // The Frame's microphone rides along with its streams. Sunshine
+                            // and stock Vibepollo ignore it, so Sunshine hosts don't get the switch.
+                            Controls.Switch {
+                                visible: !hostCard.sunshine
+                                text: "Send my microphone"
+                                checked: hostCard.modelData.mic
+                                onToggled: backend.setMic(hostCard.modelData.name, checked)
+                                Controls.ToolTip.text: "Apps on it can record the Frame's microphone while its displays stream: "
+                                                       + "pick \"Microphone (Steam Streaming Microphone)\". Windows only for now, "
+                                                       + "with Frametop's build of Vibepollo."
+                                Controls.ToolTip.visible: hovered
+                            }
                             Controls.Label {
                                 visible: hostCard.modelData.displays.length === 0
                                 text: "No displays yet."

screens/build.sh

@@ -43,4 +43,5 @@ g++ -o build/ft-screens build/compositor.o build/remote.o build/vr.o build/keybo
 g++ -o build/ft-handtest build/handtest.o build/handcut.o build/handrender.o $vrlibs
 g++ -o build/ft-handview build/handview.o build/handmesh.o build/handskin.o build/handrobot.o build/handcut.o build/handrender.o $vrlibs
 $cxx -o build/ft-spotpanel ../spotwatch/ft-spotpanel.cpp $(pkg-config --libs gbm libdrm) $OPENVR_LIBS -lpthread
+strip --strip-unneeded build/ft-screens build/ft-handtest build/ft-handview build/ft-spotpanel
 echo "built build/ft-screens build/ft-handtest build/ft-handview build/ft-spotpanel"'

screens/compositor.c

@@ -227,6 +227,7 @@ static void track_buffer(struct server *s, struct wlr_buffer *buffer) {
 
 static bool relay_can_press(struct server *s);
 static void release_relay_buttons(struct server *s, const char *why);
+static void release_seat_buttons(struct server *s, const char *why);
 
 // A video (or anything moving over a large area) on a screen you don't look at keeps the
 // full frame rate (see frame_interval): its commits keep redrawing much of it, and keep
@@ -530,7 +531,15 @@ static void handle_vr_event(const struct ft_event *e, void *data) {
                 // pointer until the next move: a press right after crossing onto another
                 // screen landed where the pointer had been. Entering one unit off makes the
                 // motion below go through.
-                wlr_seat_pointer_notify_enter(s->seat, surface, x + 1, y);
+                // With a button held (a window or a drag carried onto another screen), enter
+                // without wlroots' notify_enter: on a new surface it forgets the held buttons
+                // (reset_buttons), so their release was dropped and KWin kept the window moving
+                // until the next click. KWin is one client with a surface per screen, so the
+                // release belongs on the new one.
+                if (s->seat->pointer_state.button_count && !wlr_seat_pointer_has_grab(s->seat))
+                    wlr_seat_pointer_enter(s->seat, surface, x + 1, y);
+                else
+                    wlr_seat_pointer_notify_enter(s->seat, surface, x + 1, y);
                 s->pointer_focus = sc;
             }
             wlr_seat_pointer_notify_motion(s->seat, t, x, y);
@@ -572,6 +581,10 @@ static void handle_vr_event(const struct ft_event *e, void *data) {
         case FT_LEAVE:
             if (s->pointer_focus == sc) {
                 release_relay_buttons(s, "the pointer left the screens");
+                // Any other button still held (the 3D mouse's or a laser's press) is released
+                // here too: clearing the focus forgets it, its release would be dropped, and
+                // KWin would keep a move or drag going until the next click.
+                release_seat_buttons(s, "the pointer left the screens");
                 wlr_seat_pointer_notify_clear_focus(s->seat);
                 s->pointer_focus = NULL;
             }
@@ -755,6 +768,21 @@ static void release_relay_buttons(struct server *s, const char *why) {
     wlr_seat_pointer_notify_frame(s->seat);
 }
 
+// Release every button the seat still holds, to the surface it was pressed on. wlroots
+// counts presses of the same button (n_pressed) and sends the release with the last one,
+// so release the first button until the seat's list is empty.
+static void release_seat_buttons(struct server *s, const char *why) {
+    struct wlr_seat_pointer_state *ps = &s->seat->pointer_state;
+    if (!ps->button_count || !ps->focused_surface) return;
+    while (ps->button_count) {
+        const uint32_t code = ps->buttons[0].button;
+        const bool last = ps->buttons[0].n_pressed == 1;
+        wlr_seat_pointer_notify_button(s->seat, now_ms(), code, WL_POINTER_BUTTON_STATE_RELEASED);
+        if (last) wlr_log(WLR_INFO, "button %u released (%s)", code, why);
+    }
+    wlr_seat_pointer_notify_frame(s->seat);
+}
+
 // Keys from the input relay (physical keyboards): "key <evdev code> <1 press|0 release>".
 // They go to the screen KWin has keyboard focus on (the last one clicked), while typing
 // goes to the desktop (keys_update). The release of a key the desktop got the press for

screens/keyboard.cpp

@@ -16,6 +16,7 @@
 //     uploads a new texture each time, left the panel blank for a moment on every change;
 //     it's only the fallback if the buffers can't be made.
 #include "keyboard.h"
+#include "rounded.h"
 
 #define STB_TRUETYPE_IMPLEMENTATION
 #include "stb_truetype.h"
@@ -236,19 +237,7 @@ void Layout() {
 
 // A rounded rectangle over what's there (straight alpha, like the other panels).
 void FillRounded(int x0, int y0, int x1, int y1, double radius, const uint8_t rgba[4]) {
-    for (int y = y0; y < y1; ++y)
-        for (int x = x0; x < x1; ++x) {
-            const double cx = std::clamp(x + 0.5, x0 + radius, x1 - radius);
-            const double cy = std::clamp(y + 0.5, y0 + radius, y1 - radius);
-            const double cover = std::clamp(radius - std::hypot(x + 0.5 - cx, y + 0.5 - cy) + 0.5, 0.0, 1.0);
-            if (cover <= 0) continue;
-            uint8_t *p = &g_px[(size_t(y) * kW + x) * 4];
-            const double a = rgba[3] / 255.0 * cover, below = p[3] / 255.0;
-            const double out = a + below * (1 - a);
-            for (int c = 0; c < 3; ++c)
-                p[c] = uint8_t(std::lround(out > 0 ? (rgba[c] * a + p[c] * below * (1 - a)) / out : 0));
-            p[3] = uint8_t(std::lround(out * 255));
-        }
+    rounded::Fill(g_px.data(), kW, x0, y0, x1, y1, radius, rgba);
 }
 
 // ---------------------------------------------------------------- buffers

screens/rounded.h

@@ -0,0 +1,39 @@
+// The keyboard's straight-alpha rounded rectangles, without SteamVR or GBM dependencies.
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+
+namespace rounded {
+
+inline void Fill(uint8_t *px, int width, int x0, int y0, int x1, int y1, double radius, const uint8_t rgba[4]) {
+    for (int y = y0; y < y1; ++y) {
+        const double cy = std::clamp(y + 0.5, y0 + radius, y1 - radius);
+        const double dy = y + 0.5 - cy;
+        for (int x = x0; x < x1; ++x) {
+            const double cx = std::clamp(x + 0.5, x0 + radius, x1 - radius);
+            const double dx = x + 0.5 - cx;
+            // Most pixels lie on a straight strip or in the centre. Keep the coverage
+            // arithmetic even there: fractional radii can round just below full coverage.
+            const double distance = dx == 0 ? std::abs(dy) : dy == 0 ? std::abs(dx) : std::hypot(dx, dy);
+            const double cover = std::clamp(radius - distance + 0.5, 0.0, 1.0);
+            if (cover <= 0) continue;
+            uint8_t *p = &px[(size_t(y) * width + x) * 4];
+            // A fully covered opaque key replaces its background. The empty background
+            // likewise takes a nonzero source unchanged, including its straight RGB.
+            if (cover == 1 && rgba[3] > 0 && (rgba[3] == 255 || p[3] == 0)) {
+                std::copy_n(rgba, 4, p);
+                continue;
+            }
+            const double a = rgba[3] / 255.0 * cover, below = p[3] / 255.0;
+            const double out = a + below * (1 - a);
+            for (int c = 0; c < 3; ++c)
+                p[c] = uint8_t(std::lround(out > 0 ? (rgba[c] * a + p[c] * below * (1 - a)) / out : 0));
+            p[3] = uint8_t(std::lround(out * 255));
+        }
+    }
+}
+
+}  // namespace rounded

screens/tests/rounded-test.cpp

@@ -0,0 +1,136 @@
+// Compare every byte with the original keyboard renderer, without a headset or graphics stack.
+#include "../rounded.h"
+
+#include <chrono>
+#include <cstdio>
+#include <cstring>
+#include <random>
+#include <vector>
+
+namespace {
+
+void Original(uint8_t *px, int width, int x0, int y0, int x1, int y1, double radius, const uint8_t rgba[4]) {
+    for (int y = y0; y < y1; ++y)
+        for (int x = x0; x < x1; ++x) {
+            const double cx = std::clamp(x + 0.5, x0 + radius, x1 - radius);
+            const double cy = std::clamp(y + 0.5, y0 + radius, y1 - radius);
+            const double cover = std::clamp(radius - std::hypot(x + 0.5 - cx, y + 0.5 - cy) + 0.5, 0.0, 1.0);
+            if (cover <= 0) continue;
+            uint8_t *p = &px[(size_t(y) * width + x) * 4];
+            const double a = rgba[3] / 255.0 * cover, below = p[3] / 255.0;
+            const double out = a + below * (1 - a);
+            for (int c = 0; c < 3; ++c)
+                p[c] = uint8_t(std::lround(out > 0 ? (rgba[c] * a + p[c] * below * (1 - a)) / out : 0));
+            p[3] = uint8_t(std::lround(out * 255));
+        }
+}
+
+using Fill = decltype(&Original);
+constexpr int kW = 1280, kH = 470;
+
+uint64_t Hash(const std::vector<uint8_t> &px) {
+    uint64_t hash = 14695981039346656037ull;
+    for (uint8_t b : px) hash = (hash ^ b) * 1099511628211ull;
+    return hash;
+}
+
+// The real keyboard's rounded shapes, including hovered/pressed/latched colours and grip.
+// Text and arrows use unchanged renderers; this fixture isolates the rounded rectangles.
+void Keyboard(std::vector<uint8_t> &px, Fill fill, int state) {
+    std::fill(px.begin(), px.end(), uint8_t(0));
+    const uint8_t back[4] = {20, 22, 26, 225}, bar[4] = {220, 222, 228, uint8_t(state % 2 ? 235 : 120)};
+    fill(px.data(), kW, 0, 0, kW, kH, 22, back);
+    fill(px.data(), kW, kW / 2 - 130, 15, kW / 2 + 130, 27, 6, bar);
+    const std::vector<std::vector<double>> rows = {
+        {1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2},
+        {1.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.5},
+        {1.75, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.25},
+        {1.25, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.75, 1, 1},
+        {1.5, 1.5, 7, 2, 1, 1, 1},
+    };
+    const double unit = double(kW - 24) / 15, row = double(kH - 40 - 12) / 5;
+    int index = 0;
+    for (size_t r = 0; r < rows.size(); ++r) {
+        double x = 12;
+        for (double units : rows[r]) {
+            uint8_t face[4] = {58, 62, 70, 255};
+            if (index == state - 1) face[0] = 26, face[1] = 115, face[2] = 232;
+            else if (index == state) for (int c = 0; c < 3; ++c) face[c] = uint8_t(face[c] + 38);
+            fill(px.data(), kW, int(std::lround(x + 3.5)), int(std::lround(40 + r * row + 3.5)),
+                 int(std::lround(x + units * unit - 3.5)), int(std::lround(40 + (r + 1) * row - 3.5)), 10, face);
+            x += units * unit;
+            ++index;
+        }
+    }
+}
+
+bool Check() {
+    // Every source channel/alpha pair over transparent pixels, including nonzero RGB at A=0.
+    for (double radius : {0., 0.5})
+      for (int a = 0; a < 256; ++a)
+        for (int c = 0; c < 256; ++c) {
+            uint8_t old[4] = {43, 129, 255, 0}, got[4];
+            std::copy_n(old, 4, got);
+            const uint8_t rgba[4] = {uint8_t(c), uint8_t(255 - c), uint8_t(c ^ 85), uint8_t(a)};
+            Original(old, 1, 0, 0, 1, 1, radius, rgba);
+            rounded::Fill(got, 1, 0, 0, 1, 1, radius, rgba);
+            if (std::memcmp(old, got, 4)) return false;
+        }
+    std::mt19937 rng(42);
+    std::vector<uint8_t> old(64 * 48 * 4), got(old.size());
+    for (int i = 0; i < 4000; ++i) {
+        for (auto &v : old) v = uint8_t(rng());
+        if (i % 3 == 0) for (size_t p = 3; p < old.size(); p += 4) old[p] = 0;
+        if (i % 3 == 1) for (size_t p = 3; p < old.size(); p += 4) old[p] = 255;
+        got = old;
+        const uint8_t color[4] = {uint8_t(rng()), uint8_t(rng()), uint8_t(rng()), uint8_t(i % 256)};
+        const int x = int(rng() % 40), y = int(rng() % 24), w = 1 + int(rng() % 24), h = 1 + int(rng() % 24);
+        const double radius = std::min(w, h) * (rng() % 501) / 1000.;
+        Original(old.data(), 64, x, y, x + w, y + h, radius, color);
+        rounded::Fill(got.data(), 64, x, y, x + w, y + h, radius, color);
+        if (old != got) return false;  // compares untouched pixels outside the rectangle too
+    }
+    old.resize(kW * kH * 4), got.resize(old.size());
+    // Coverage near 1 must keep the original subtraction's rounding at larger coordinates.
+    for (auto &v : old) v = uint8_t(rng());
+    got = old;
+    const uint8_t color[4] = {191, 73, 225, 50};
+    Original(old.data(), kW, 31, 267, 51, 298, 2.84, color);
+    rounded::Fill(got.data(), kW, 31, 267, 51, 298, 2.84, color);
+    if (old != got) return false;
+    uint64_t hash = 0;
+    for (int state = 0; state <= 62; ++state) {
+        Keyboard(old, Original, state), Keyboard(got, rounded::Fill, state);
+        if (old != got) return false;
+        hash ^= Hash(got);
+    }
+    std::printf("65536 channel/alpha pairs at two coverages, 4001 varied rectangles and 63 keyboard states identical; hash %016llx\n",
+                static_cast<unsigned long long>(hash));
+    return true;
+}
+
+void Benchmark() {
+    std::vector<uint8_t> px(kW * kH * 4);
+    // Alternate order across rounds; checksum work stays outside the timed region.
+    for (int round = 0; round < 5; ++round)
+        for (int order = 0; order < 2; ++order) {
+            const bool original = (order + round) % 2 == 0;
+            const Fill fill = original ? Original : rounded::Fill;
+            Keyboard(px, fill, 0);
+            const auto start = std::chrono::steady_clock::now();
+            for (int i = 0; i < 20; ++i) Keyboard(px, fill, i);
+            const double ms = std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - start).count() / 20;
+            std::printf("round %d %s %.6f ms hash %016llx\n", round, original ? "original" : "optimized", ms,
+                        static_cast<unsigned long long>(Hash(px)));
+        }
+}
+
+}  // namespace
+
+int main(int argc, char **argv) {
+    if (!Check()) {
+        std::fputs("rounded renderer differs from the original\n", stderr);
+        return 1;
+    }
+    if (argc == 2 && std::strcmp(argv[1], "--benchmark") == 0) Benchmark();
+}

screens/vr.cpp

@@ -80,7 +80,8 @@
 //     A hand at a panel owns the pointer there (kHandPointerMs). Its log lines start "hands:".
 //   - the palm menu (palmmenu.cpp): a bare hand turned palm up toward your face, while you look
 //     at it, gets a small ring above the palm; a pinch tap by that hand opens the Steam menu
-//     (steam/ft-steam menu), or closes the dashboard. That hand counts as near meanwhile.
+//     (steam/ft-steam menu), or closes the dashboard. That hand counts as near meanwhile. Not
+//     while a gaze calibration panel is up (the pointer helper's "calpanel 1").
 //   - "grab that" (grabthat.cpp): an open hand held out to a screen or floating window, then a
 //     fist pulled back, brings it to arm's reach (about 45 cm ahead, facing you). Only a panel the
 //     palm faces (its normal's line meets it), farther than 0.8 m, not held (near ones: push,
@@ -112,6 +113,7 @@
 #include "keyboard.h"
 #include "roomview.h"
 #include "steampanels.h"
+#include "../spotwatch/reserve.h"
 
 #include <drm_fourcc.h>
 #include <openvr.h>
@@ -2321,6 +2323,11 @@ struct TypingWord {
     bool side[2] = {false, false};
     int64_t atMs = INT64_MIN / 2;
 } g_typingWord;
+// The pointer helper's word on the gaze calibration panel ("calpanel 1|0", passed on from the
+// panel's claims, about every second while it's up): the palm menu waits meanwhile (a palm up
+// between dots isn't a menu). Older than 3 s, it lapses.
+int64_t g_calPanelMs = INT64_MIN / 2;
+bool CalPanelUp() { return NowMs() - g_calPanelMs < 3000; }
 // ...and on its hand rays ("ray <L 0|1> <R 0|1>", the same way): our laser (ft_pointer's) is a hand
 // pointing only while one is up; else it's the mouse's or the gaze's (FromLaser).
 TypingWord g_rayWord;
@@ -2760,7 +2767,7 @@ void UpdatePalmMenu(const handinput::Input &in, const std::vector<handinput::Pan
     // has it near one, or it's within the touch zone and a margin of one (a card pinch from below has
     // the palm up toward the face)
     for (int k = 0; k < 2; ++k) {
-        pin.allowed[k] = in.haveHead && !g_beside && HandsAllowed(k);
+        pin.allowed[k] = in.haveHead && !g_beside && HandsAllowed(k) && !CalPanelUp();
         pin.busy[k] = g_handInput.pressing(k) || g_handInput.grabbing(k) || g_grabThat.armed(k) ||
                       g_grabThat.claims(k, g_handInput.frameNs());
         pin.atPanel[k] = g_handInput.near(k) || handinput::HandAtPanel(g_hands, k, panels, g_handInput.params());
@@ -2815,7 +2822,7 @@ void StartGrabMove(int index, Screen &s, const Mat &to, double width, double ms
 // ---------------------------------------------------------------- the front slot
 // One place in front of you for the lazy susan (user, 2026-10-11: "make the system a bit more logical
 // with the lazy susan"; the proposals they took): a stroke (or Meta+Alt+Tab) brings the next screen
-// there, 1 m ahead (g_frontReading), as big as its resolution needs for its text to read
+// there, 1 m ahead (g_frontReading; never nearer than behind spotwatch's reserved spot), as big as its resolution needs for its text to read
 // (grabthat::ReadableSize), one at a time: the one there goes home first. Turned away from, it goes
 // home, unless you used it a while (g_frontKeepMs of input on it: kept). Resized there, it comes that
 // size next time (g_frontDeg). Its home: where it lived before it came.
@@ -4271,7 +4278,8 @@ bool ft_vr_init(void) {
         g_curveMaxArc = deg * M_PI / 180;
     }
     g_susanBring = handcut::Setting("SCREEN_SPIN_BRING", "1") != "0";   // the lazy susan brings panels (0: the room turns)
-    num("SCREEN_SPIN_DISTANCE", g_frontReading, 0.4, 3);   // the front slot's reading distance (m)
+    num("SCREEN_SPIN_DISTANCE", g_frontReading, 0.4, 3);   // the front slot's reading distance (m)...
+    g_frontReading = std::max(g_frontReading, spotreserve::kDistance + spotreserve::kFrontGap);   // ...behind spotwatch's spot
     num("SCREEN_SPIN_PPD", g_frontRead.ppd, 8, 80);          // ...as big as its pixels at this many per degree need
     num("SCREEN_SPIN_MAX_DEG", g_frontRead.maxW, 30, 100);   // ...at most this wide (deg; wider ones curve round you)
     num("SCREEN_SPIN_MAX_TALL_DEG", g_frontRead.maxH, 20, 90);
@@ -5172,6 +5180,11 @@ void ft_vr_command(const char *cmd, char *reply, int size) {
     } else if (int tl = 0, tr = 0; std::sscanf(cmd, "typing %d %d", &tl, &tr) == 2) {
         g_typingWord.side[0] = tl != 0, g_typingWord.side[1] = tr != 0, g_typingWord.atMs = NowMs();
         std::snprintf(reply, size, "ok");
+    } else if (int calOn = 0; std::sscanf(cmd, "calpanel %d", &calOn) == 1) {
+        if ((calOn != 0) != CalPanelUp())
+            std::printf("gaze calibration panel %s: the palm menu %s\n", calOn ? "up" : "gone", calOn ? "waits" : "is back");
+        g_calPanelMs = calOn ? NowMs() : INT64_MIN / 2;
+        std::snprintf(reply, size, "ok");
     } else if (int rl = 0, rr = 0; std::sscanf(cmd, "ray %d %d", &rl, &rr) == 2) {
         g_rayWord.side[0] = rl != 0, g_rayWord.side[1] = rr != 0, g_rayWord.atMs = NowMs();
         std::snprintf(reply, size, "ok");

scripts/gaze-report.py

@@ -267,7 +267,7 @@ def check_install():
     venv = repo / "gaze/tracker/build/venv"
     done = venv / "requirements.done"
     req = repo / "gaze/tracker/requirements.txt"
-    if not (venv / "bin/python").exists():
+    if not os.path.lexists(venv / "bin/python"):  # a link to the container's Python (ft-gazed's venv_built)
         say("  gaze/tracker/build/venv (our tracker's Python): missing")
     else:
         same = done.is_file() and req.is_file() and done.read_bytes() == req.read_bytes()
@@ -310,7 +310,7 @@ def gaze_settings(repo):
     except OSError:
         pass
     setting = conf.get("GAZE_TRACKER", "auto").lower()
-    venv = (repo / "gaze/tracker/build/venv/bin/python").exists() if repo else False
+    venv = os.path.lexists(repo / "gaze/tracker/build/venv/bin/python") if repo else False
     installed = EYEGRAB_BIN.exists() and EYEGRAB_UNIT.exists() and venv
     tracker = setting if setting in ("own", "steam") else "own" if installed else "steam"
     return conf, setting, installed, tracker

session/frametop.conf.example

@@ -44,6 +44,8 @@ GAZE_TRACKER=auto          # gaze service: auto = our own eye tracker when it's
 GAZE_EYE=auto              # gaze service: eye bias. auto = each eye weighted by how far off it was at your recent nudges | left | right = that eye counts twice
 #EYES_MODEL=classic        # our eye tracker (GAZE_TRACKER own): classic = the pupil finder | latest = the newest eye net, following new versions | a version's name (gaze/tracker/models.json) | a model folder of your own. Pick it on Frametop Input Settings' Gaze page, which downloads it
 EYES_MODELS_UPDATE=1       # our eye tracker: 1 = when it starts, check GitHub for the eye net list and fetch the net EYES_MODEL needs | 0 = only what's downloaded
+GAZE_FUSION=off            # gaze service, with our eye tracker: on = mix in SteamVR's gaze, corrected at your calibration (half each while ours sees both eyes, SteamVR's while ours has one or none) | off = ours alone. Calibrate again after turning it on
+#EYES_SIZE_GUARD=both     # our eye tracker, classic: a pupil find much smaller than usual counts as not found. both = unless the other eye's shrank too (light) | long = under 0.6 of usual | off
 GAZE_FIT_WATCH=0           # gaze service, with our eye tracker installed: 1 = the put-on check (the quick check, when the headset goes on, first says which way to move it back to your saved fit; the fit check saves a good one) and the slip note (our tracker in use: a small note when the headset slipped) | 0 = off
 HANDS_MODE=off             # hand tracking (hands/run.sh install; install.sh sets frametop when it installs it), when it runs: frametop = while the Frametop desktop runs | always = whenever SteamVR runs, in games and the dashboard too | off = only by hand (ft-handsctl on). Frametop Input Settings' Hands page applies it at once
 HANDS_SWAP_SIDES=auto      # hand tracking: which side camera is which. auto = ft-hands tells from the hands and fixes ft-camd's names, which some SteamVR restarts swap | 0 = keep ft-camd's | 1 = exchange them
@@ -109,7 +111,7 @@ SCREEN_FRONT_AWAY=0        # ... 1 = turned away from, it goes home (unless used
 SCREEN_FRONT_KEEP_MS=3000  # ... this much input on the screen in the slot keeps it there when you look away (0 = never kept)
 SCREEN_UI_SCALE=           # ... a remote display's own UI scale for its readable size, by screen number: "102=2" (a Mac's Retina display); KWin's screens use their own scale
 HANDS_RESET_HOLD_MS=0      # the reset button under a screen resets the layout when held this long (ms; laser or finger) | 0 = a press
-SCREEN_SPIN_DISTANCE=1.0   # ... a brought screen comes this far ahead (m)
+SCREEN_SPIN_DISTANCE=1.0   # ... a brought screen comes this far ahead (m); at least 0.9, behind spotwatch's search (0.75)
 SCREEN_SPIN_PPD=26         # ... as big as its text needs to read: its logical pixels (KWin's scale undone) at this many per degree of view
 SCREEN_SPIN_MAX_DEG=100    # ... at most this wide (degrees; wider than 60 it curves round you) and SCREEN_SPIN_MAX_TALL_DEG (55) tall, its shape kept
 SCREEN_SPIN_MAX_WIDE_DEG=150   # ... an ultrawide (3:1 or wider, like 5120x1440) at most this wide instead, so its text reads too

spotwatch/ft-spotpanel.cpp

@@ -10,7 +10,8 @@
 //
 // Control socket: abstract unix datagram "@ft_spotpanel" (--socket NAME); a sender with an
 // address gets "ok" or "error ...":
-//   show          place it in front of you (head direction, at --distance) and show it with
+//   show          place it in front of you (head direction, at --distance: its reserved spot,
+//                 spotwatch/reserve.h) and show it with
 //                 its next picture
 //   show toast    the same, for a toast: the lasers pass through it
 //   hide
@@ -40,6 +41,7 @@
 
 #define STB_TRUETYPE_IMPLEMENTATION
 #include "stb_truetype.h"
+#include "reserve.h"
 
 #include <drm_fourcc.h>
 #include <fcntl.h>
@@ -509,7 +511,7 @@ void ParseState(const std::string &text, State &s) {
 int main(int argc, char **argv) {
     bool watchStdin = false;
     std::string sockName = "ft_spotpanel", notifyName = "ft_spotwatch", renderPath;
-    double distance = 1.0, width = 0.56;
+    double distance = spotreserve::kDistance, width = spotreserve::kWidth;
     for (int i = 1; i < argc; ++i) {
         if (!std::strcmp(argv[i], "--watch-stdin")) watchStdin = true;
         else if (!std::strcmp(argv[i], "--socket") && i + 1 < argc) sockName = argv[++i];
@@ -580,8 +582,8 @@ int main(int argc, char **argv) {
         std::fprintf(stderr, "ft-spotpanel: can't create the overlay (another copy running?)\n");
         return 1;
     }
-    // Over the screens and their controls (10), under Frametop's keyboard (15), which may open
-    // with it, and the 3D mouse's dot (200).
+    // Over the screens and their controls (10), so it shows through a panel nearer than it, under
+    // Frametop's keyboard (15), which may open with it, and the 3D mouse's dot (200).
     ov->SetOverlaySortOrder(h, 14);
     ov->SetOverlayWidthInMeters(h, float(width));
     ov->SetOverlayInputMethod(h, vr::VROverlayInputMethod_Mouse);

spotwatch/reserve.h

@@ -0,0 +1,12 @@
+// Spotwatch's reserved spot (user, 2026-10-17: "spotwatch should be a reserved spot and should
+// ideally always display through displays"). Its search opens kDistance straight ahead, nearer than
+// the lazy susan's front slot, which ft-screens keeps at least kFrontGap behind it: a brought panel
+// never lands in the search's plane (both were 1 m ahead). Panels nearer than it (grab that, a
+// carry) still don't cover it: its sort order is over theirs (ft-spotpanel.cpp).
+#pragma once
+
+namespace spotreserve {
+constexpr double kDistance = 0.75;   // m ahead of the head
+constexpr double kWidth = 0.42;      // m: as wide as it looks (31 degrees) as 0.56 m was at 1 m
+constexpr double kFrontGap = 0.15;   // m: the front slot is at least this far behind it
+}  // namespace spotreserve

stream/build.sh

@@ -7,7 +7,9 @@
 # also need moonlight-embedded (GPLv3) at a pinned commit: its libgamestream for pairing and
 # launching, and the moonlight-common-c it pins for the protocol, and its table of Windows key
 # codes. ft-stream plays the host's sound with Opus and PipeWire's PulseAudio server
-# (libpulse-simple).
+# (libpulse-simple), and sends the Frame's microphone back the same way. moonlight-mic.patch adds
+# that to moonlight-common-c (LiSendMicrophoneOpusData); the checkout is made again when it
+# changes.
 set -euo pipefail
 root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 "$root/scripts/sync.sh" >/dev/null
@@ -16,13 +18,17 @@ exec "$root/scripts/frame.sh" -C stream 'set -e; mkdir -p build/include
 me=f32e415aea6797d261d6b470dcf8bf18727341c2
 src=build/moonlight-embedded
 mlc=$src/third_party/moonlight-common-c
-if [ ! -f $src/.ft-$me ]; then
+mark=$me-$(sha256sum moonlight-mic.patch | cut -c1-12)
+if [ ! -f $src/.ft-$mark ]; then
   rm -rf $src build/mlc build/gamestream
-  git clone -q https://github.com/moonlight-stream/moonlight-embedded.git $src
-  git -C $src checkout -q $me
-  git -C $src submodule update -q --init third_party/moonlight-common-c
-  git -C $mlc submodule update -q --init enet
-  touch $src/.ft-$me
+  # Only this revision and its pinned submodules are build inputs, not their history.
+  git init -q $src
+  git -C $src fetch -q --depth 1 https://github.com/moonlight-stream/moonlight-embedded.git $me
+  git -C $src checkout -q --detach FETCH_HEAD
+  git -C $src submodule update -q --init --depth 1 third_party/moonlight-common-c
+  git -C $mlc submodule update -q --init --depth 1 enet
+  git -C $mlc apply "$PWD/moonlight-mic.patch"
+  touch $src/.ft-$mark
 fi
 if [ ! -f build/mlc/libmoonlight-common-c.a ]; then
   cmake -S $mlc -B build/mlc -G Ninja -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release >/dev/null
@@ -44,4 +50,5 @@ echo "built build/ft-streamtest"
 g++ $flags -I$mlc/src -I$src/libgamestream -I$src/src -o build/ft-stream ft-stream.cpp host.cpp build/gamestream/*.o \
   build/mlc/libmoonlight-common-c.a build/mlc/enet/libenet.a \
   $(pkg-config --libs gbm egl glesv2 libcurl openssl expat uuid opus libpulse-simple) -lpthread $vr
+strip --strip-unneeded build/ft-dectest build/ft-streamtest build/ft-stream
 echo "built build/ft-stream"'

stream/ft-stream.cpp

@@ -42,12 +42,17 @@
 // It exits when ft-screens closes its end. A Remote Monitor is released then ("Disconnect
 // Monitor"); an existing display holds nothing on the host.
 //
+// The host's sound plays here, and with "mic": true on its host in the layout (Frametop Remote
+// Displays: Send my microphone) the Frame's microphone goes back to the host's virtual one; see
+// Audio and Mic.
+//
 // Runs in the dev container. Build: stream/build.sh.
 #include "spike/iris.h"
 
 #include "host.h"
 
 #include <netdb.h>
+#include <opus/opus.h>
 #include <opus/opus_multistream.h>
 #include <pulse/error.h>
 #include <pulse/simple.h>
@@ -63,6 +68,7 @@
 #include <mutex>
 #include <set>
 #include <sstream>
+#include <thread>
 
 #include <linux/input-event-codes.h>
 
@@ -161,6 +167,107 @@ void AudioPlay(char *data, int length) {
     if (n > 0) pa_simple_write(g_audio.pa, g_audio.pcm.data(), size_t(n * g_audio.channels) * sizeof(int16_t), &err);
 }
 
+// The Frame's microphone, to the host's virtual microphone: Steam Streaming Microphone on
+// Windows (Frametop's host build; others ignore it, and so does its Linux service for now).
+// Sent by the stream that plays the host's sound (Audio), so a host gets it once however many
+// of its displays stream, while its host has "mic": true in the layout. Mono Opus at 48 kHz in 20 ms
+// packets on the encrypted control stream (LiSendMicrophoneOpusData, moonlight-mic.patch), never
+// in the clear. It records PipeWire's default source, which on the Frame runs through echo
+// cancelling, so the host's sound playing here doesn't go back into a call.
+struct Mic {
+    std::string name;  // the recording stream's name in the mixer
+    std::mutex mu;     // held while a packet goes out; Stop takes it, so none goes after
+    bool run = false;
+    std::atomic<bool> done{true};
+    std::atomic<bool> refused{false};  // the control stream isn't encrypted: never for this stream
+    std::atomic<int> sent{0};
+    int64_t retryAt = 0;  // a recording that ended by itself (no source) starts again after 30 s
+    std::thread thread;
+
+    bool On() {
+        std::lock_guard<std::mutex> lock(mu);
+        return run;
+    }
+
+    void Want(bool on) {
+        if (on == On() || (on && refused)) return;
+        if (!on) return Stop();
+        if (MonoNs() < retryAt) return;
+        retryAt = MonoNs() + 30'000'000'000;
+        if (thread.joinable()) thread.join();  // a loop that ended by itself
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            run = true;
+        }
+        done = false;
+        thread = std::thread(&Mic::Loop, this);
+    }
+
+    // Afterwards no packet goes out, so the connection can stop. A recording stuck in
+    // pa_simple_read (it can't be interrupted) is left behind rather than waited for.
+    void Stop() {
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            if (!run && !thread.joinable()) return;
+            run = false;
+        }
+        for (int i = 0; i < 50 && !done; ++i) usleep(10'000);
+        if (!thread.joinable()) return;
+        if (done) thread.join();
+        else thread.detach(), std::printf("mic: the recording didn't end, left behind\n");
+        std::printf("mic: off\n");
+    }
+
+    void Loop() {
+        constexpr int kSamples = 960;  // 20 ms at 48 kHz
+        const pa_sample_spec spec = {PA_SAMPLE_S16LE, 48000, 1};
+        pa_buffer_attr attr;
+        attr.maxlength = uint32_t(-1), attr.prebuf = uint32_t(-1), attr.minreq = uint32_t(-1), attr.tlength = uint32_t(-1);
+        attr.fragsize = uint32_t(kSamples * sizeof(int16_t));
+        int err = 0;
+        pa_simple *pa = pa_simple_new(nullptr, "Frametop", PA_STREAM_RECORD, nullptr, name.c_str(), &spec, nullptr, &attr, &err);
+        OpusEncoder *enc = pa ? opus_encoder_create(48000, 1, OPUS_APPLICATION_VOIP, &err) : nullptr;
+        if (!pa) std::fprintf(stderr, "mic: can't record: %s\n", pa_strerror(err));
+        else if (!enc) std::fprintf(stderr, "mic: opus: %s\n", opus_strerror(err));
+        if (enc) {
+            opus_encoder_ctl(enc, OPUS_SET_BITRATE(64000));
+            opus_encoder_ctl(enc, OPUS_SET_SIGNAL(OPUS_SIGNAL_VOICE));
+            opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(5));  // speech at 48 kHz mono: a few % of a core
+            opus_encoder_ctl(enc, OPUS_SET_INBAND_FEC(1));  // the next packet carries a lost one
+            opus_encoder_ctl(enc, OPUS_SET_PACKET_LOSS_PERC(5));
+            std::printf("mic: sending the default source to the host\n");
+            std::fflush(stdout);
+        }
+        int16_t pcm[kSamples];
+        unsigned char out[LI_MICROPHONE_MAX_OPUS_BYTES];
+        while (enc) {
+            if (pa_simple_read(pa, pcm, sizeof pcm, &err) < 0) {
+                std::fprintf(stderr, "mic: recording ended: %s\n", pa_strerror(err));
+                break;
+            }
+            const int n = opus_encode(enc, pcm, kSamples, out, sizeof out);
+            std::lock_guard<std::mutex> lock(mu);
+            if (!run) break;
+            if (n <= 0) continue;
+            const int r = LiSendMicrophoneOpusData(out, n);
+            if (r == 0) ++sent;
+            else if (r == -1) {
+                refused = true;
+                std::printf("mic: not sent: this host's control stream isn't encrypted\n");
+                break;
+            }
+        }
+        if (enc) opus_encoder_destroy(enc);
+        if (pa) pa_simple_free(pa);
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            run = false;
+        }
+        done = true;
+    }
+};
+Mic g_mic;
+
 int Submit(PDECODE_UNIT du) {
     const bool idr = du->frameType == FRAME_TYPE_IDR;
     ++g_received, g_bytes += uint64_t(du->fullLength);
@@ -318,6 +425,16 @@ std::string Route(const std::string &host, int port) {
     return host;
 }
 
+// Whether the host's entry in the layout says to send it the Frame's microphone ("mic": true,
+// Frametop Remote Displays' Send my microphone). Read again every few seconds while streaming.
+bool MicWanted(const std::string &host) {
+    const nlohmann::json layout = Layout();
+    if (layout.is_null()) return false;
+    for (const auto &h : layout["hosts"])
+        if (h.is_object() && h.value("address", "") == host) return h.contains("mic") && h["mic"].is_boolean() && h["mic"].get<bool>();
+    return false;
+}
+
 // The port of the display whose client is `id`, from the layout, or 0. A Mac runs a Sunshine
 // instance per display, each on its own port, and a client is paired with one of them only. An
 // ft-layout from before ports (an older release's Reset Screen Layout or profile launchers) asks
@@ -411,6 +528,7 @@ int Stream(Client &client, const std::string &app, int fd, int width, int height
     ar.capabilities = CAPABILITY_SUPPORTS_ARBITRARY_AUDIO_DURATION;
     g_audio.name = "Remote display: " + g_host;
     g_audio.Claim(g_host, MonoNs());
+    g_mic.name = "Remote display microphone: " + g_host;
     if (LiStartConnection(&client.server.serverInfo, &cfg, &cl, &dr, &ar, nullptr, 0, nullptr, 0) != 0)
         return viewer.Send("state lost can't connect"), 1;
     std::printf("stream: connected, %d kbit/s asked\n", bitrate);
@@ -421,6 +539,7 @@ int Stream(Client &client, const std::string &app, int fd, int width, int height
     bool live = false;
     uint64_t seq = 0;
     int64_t lastReport = MonoNs(), cpu0 = CpuNs(), lastShown = 0, allHeldSince = -1;
+    int64_t micCheck = 0;
     int shown = 0, dropped = 0, rested = 0, lastSent = -1;
     while (!g_stop) {
         pollfd p[3] = {{dec.fd, POLLIN | POLLPRI | POLLOUT, 0}, {g_wake, POLLIN, 0}, {viewer.fd, POLLIN, 0}};
@@ -459,6 +578,7 @@ int Stream(Client &client, const std::string &app, int fd, int width, int height
         // panel froze, 2026-10-07.)
         if (!open) break;
         g_audio.Claim(g_host, MonoNs());
+        if (MonoNs() >= micCheck) micCheck = MonoNs() + 3'000'000'000, g_mic.Want(g_audio.on && MicWanted(g_host));
         if (dec.Events()) {
             if (!conv.Setup(dec)) break;
             const int fds[3] = {conv.out[0].fd, conv.out[1].fd, conv.out[2].fd};
@@ -520,17 +640,20 @@ int Stream(Client &client, const std::string &app, int fd, int width, int height
             const double secs = (now - lastReport) / 1e9;
             uint32_t rtt = 0, rttVar = 0;
             LiGetEstimatedRttInfo(&rtt, &rttVar);
+            const int micSent = g_mic.sent.exchange(0);
             std::printf("%s: in %.1f fps (%d skipped), shown %.1f fps (%d dropped, %d out of sight), %.1f Mbit/s, rtt %u ms, "
-                        "convert %.1f ms, CPU %.1f%% of a core%s\n",
+                        "convert %.1f ms, CPU %.1f%% of a core%s%s\n",
                         g_hidden ? "hidden" : "shown", g_received.exchange(0) / secs, g_skipped.exchange(0), shown / secs,
                         dropped, rested, g_bytes.exchange(0) * 8 / secs / 1e6, rtt, shown ? conv.msSum / shown : 0.0,
-                        100 * (CpuNs() - cpu0) / 1e9 / secs, g_audio.on ? ", playing its sound" : "");
+                        100 * (CpuNs() - cpu0) / 1e9 / secs, g_audio.on ? ", playing its sound" : "",
+                        micSent ? (", mic " + std::to_string(int(micSent / secs + 0.5)) + " packets/s").c_str() : "");
             std::fflush(stdout);
             conv.msSum = 0, shown = dropped = rested = 0, lastReport = now, cpu0 = CpuNs();
         }
     }
     const int ended = g_ended;
     g_stop = 1;
+    g_mic.Stop();  // no packet after this, before the connection goes
     LiStopConnection();
     viewer.Send(ended ? "state lost the host ended the stream" : "state lost");
     dec.Close();

stream/moonlight-mic.patch

@@ -0,0 +1,78 @@
+diff --git a/src/ControlStream.c b/src/ControlStream.c
+index b7e3685..a249ec9 100644
+--- a/src/ControlStream.c
++++ b/src/ControlStream.c
+@@ -100,6 +100,7 @@ static PLT_THREAD asyncCallbackThread;
+ static uint32_t lastGoodFrame;
+ static uint32_t lastSeenFrame;
+ static bool stopping;
++static uint16_t microphoneSequence;
+ static bool disconnectPending;
+ static bool encryptedControlStream;
+ static bool hdrEnabled;
+@@ -299,6 +300,7 @@ static bool supportsIdrFrameRequest;
+ // Initializes the control stream
+ int initializeControlStream(void) {
+     stopping = false;
++    microphoneSequence = 0;
+     PltCreateEvent(&idrFrameRequiredEvent);
+     LbqInitializeLinkedBlockingQueue(&invalidReferenceFrameTuples, 20);
+     LbqInitializeLinkedBlockingQueue(&frameFecStatusQueue, 8); // Limits number of frame status reports per periodic ping interval
+@@ -1644,6 +1646,35 @@ int sendInputPacketOnControlStream(unsigned char* data, int length, uint8_t chan
+     return 0;
+ }
+ 
++// Frametop: the microphone's own channel, so a resent packet only holds up the microphone.
++#define CTRL_CHANNEL_MICROPHONE 0x07
++
++int LiSendMicrophoneOpusData(const unsigned char* opusData, int opusLength) {
++    unsigned char payload[4 + LI_MICROPHONE_MAX_OPUS_BYTES];
++
++    if (opusData == NULL || opusLength <= 0 || opusLength > LI_MICROPHONE_MAX_OPUS_BYTES) {
++        return -2;
++    }
++
++    // Never in the clear: only Sunshine-based hosts with the encrypted control stream.
++    if (AppVersionQuad[0] < 5 || !IS_SUNSHINE() || !encryptedControlStream || peer == NULL || stopping) {
++        return -1;
++    }
++
++    payload[0] = (unsigned char)(microphoneSequence >> 8);
++    payload[1] = (unsigned char)microphoneSequence;
++    payload[2] = 1;
++    payload[3] = 0;
++    memcpy(&payload[4], opusData, opusLength);
++    microphoneSequence++;
++
++    if (!sendMessageAndForget(0x3003, (short)(4 + opusLength), payload, CTRL_CHANNEL_MICROPHONE, ENET_PACKET_FLAG_RELIABLE, false)) {
++        return -3;
++    }
++
++    return 0;
++}
++
+ // Called by the input stream to flush queued packets before a batching wait
+ void flushInputOnControlStream(void) {
+     if (AppVersionQuad[0] >= 5) {
+diff --git a/src/Limelight.h b/src/Limelight.h
+index ac87a4b..eac01cf 100644
+--- a/src/Limelight.h
++++ b/src/Limelight.h
+@@ -711,6 +711,17 @@ int LiSendKeyboardEvent2(short keyCode, char keyAction, char modifiers, char fla
+ // This function queues an UTF-8 encoded text to be sent to the remote server.
+ int LiSendUtf8TextEvent(const char *text, unsigned int length);
+ 
++// Frametop: sends one Opus packet of the client's microphone (mono, 48 kHz) to the host on the
++// encrypted control stream: packet type 0x3003 (Apollo protocol extension range), its payload a
++// 4-byte header [sequence high, sequence low, channels (1), flags (0)] and the Opus packet, the
++// layout of Vibepollo PR #169. Reliable, on a channel of its own: ENet's throttle drops unreliable
++// packets whenever round trips wobble, a quarter of them on Wi-Fi beside video. Hosts without
++// Frametop's build ignore it. Returns 0 when sent, -1 when the control stream isn't connected or
++// isn't encrypted (never sent in the clear), -2 for an Opus packet over
++// LI_MICROPHONE_MAX_OPUS_BYTES, -3 when ENet couldn't send it.
++#define LI_MICROPHONE_MAX_OPUS_BYTES 240
++int LiSendMicrophoneOpusData(const unsigned char* opusData, int opusLength);
++
+ // Button flags
+ #define A_FLAG     0x1000
+ #define B_FLAG     0x2000