FrameDrop: proof of concept for installing Frametop from FrameDrop (#25 )

FrameDrop sideloads a Linux zip as a Steam Devkit Game. Frametop can't be copied over as an app, so the zip holds a small installer: playing it runs get.sh --yes in a transient user service (Steam reaps the title's process tree on quit) and shows progress in a GTK window. - probe/probe.sh records what a Devkit Game can reach. On SteamOS 0.3.0 it runs on the host with git, podman, systemd and GTK, even with the SLR4 compat tool set; inside SLR4, flatpak-spawn --host reaches the host. - devkit.sh registers a folder the way FrameDrop does (Valve's devkit-utils), for testing without a PC. - build.sh makes a reproducible Frametop.zip and the FrameDrop manifest. Nothing is published. Open: whether FrameDrop keeps the exec bit, and its start command and runtime choice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge branch laser-release (release a held button that can't come up on a screen: the game kept losing its controllers) into experimental
2026-10-06 06:00:09 +02:00 · 2026-10-04 21:19:30 -06:00 · 2026-10-04 09:37:46 -06:00 · 2026-10-04 09:31:27 -06:00 · 2026-10-04 08:42:12 -06:00 · 2026-10-04 08:39:44 -06:00
29 changed files with 1240 additions and 66 deletions
@@ -57,6 +57,7 @@ If you work in the desktop for long stretches, or leave the headset on a stand,
 | While carrying a screen, sweep its laser across your other controller's ring, then let go | Pins it to that wrist, at its size and distance, as you hold it when you let go; it shows while you see its front. Grab its bar to adjust it (it stays pinned); sweep across the ring again to take it off |
 | Set a screen to On your head (Frametop Display Settings, Visibility & pins) | Pins it to your head where it is, like a HUD. Grab its bar to move it; it stays on your head |
 | Meta+Shift+R in the desktop | Puts the screens back in their layout (also in the menu as Reset Screen Layout, and mappable to a mouse button) |
 | Meta+Alt+Tab, or Meta+Alt+Shift+Tab | Spins every screen and floating window around you together, like a lazy susan, so the next one on your right (or left) glides to straight ahead, with the pointer and typing going to it. Their arrangement stays the same: the room turns instead of you. Tap again to keep going; Meta+Shift+R puts the screens back. Pinned screens stay where they are |
 | Meta+Shift+H in the desktop | Hides or shows all screens (also in the menu as Hide/Show Screens, and mappable). The Visibility & pins tab of Frametop Display Settings can instead show them only with the dashboard open, or while you look at your wrist |
 | Tap Meta, on any keyboard | Opens the Steam menu in the SteamVR dashboard, or closes the dashboard, wherever you are. The desktop's launcher is still on the taskbar and Alt+F1. Change it in Frametop Input Settings (Keyboard page), where any key combination or modifier tap can do a Frametop or Steam action, open a profile, or run a command of your own |
 | Switch a screen to Hidden (Frametop Display Settings, Visibility & pins → Screens shown) | Hides just that screen until you switch it back, whatever the other visibility settings say; new windows that would open on it float instead |
@@ -3,7 +3,7 @@ Type=Application
 Name=Reset Screen Layout
 GenericName=Put the VR desktop's screens back in their layout
 Comment=Float the screens and arrange them in the layout from Frametop Display Settings
-Exec=@REPO@/layout/ft-layout apply
+Exec=@REPO@/layout/ft-layout-reset
 Icon=view-restore
 Categories=Settings;
 Keywords=display;screen;layout;arrange;reset;steamvr;frametop;
@@ -3,7 +3,7 @@ Type=Application
 Name=Hide/Show Screens
 GenericName=Hide or show the VR desktop's screens
 Comment=Hide the screens (and SteamVR's laser) for a VR game; press again to bring them back
-Exec=@REPO@/layout/ft-layout toggle
+Exec=@REPO@/layout/ft-hide-show
 Icon=view-visible
 Categories=Settings;
 Keywords=display;screen;hide;show;steamvr;frametop;
@@ -1,6 +1,6 @@
 # Controller desktop click stability
-Trigger presses reach KDE immediately, but controller motion within 8 logical
+Trigger presses reach KDE immediately, but controller motion within 32 logical
 pixels of the press stays at that position until release. Releasing without a motion outside this
 zone delivers the click at the original position, even if the hand moved during
 release. Moving outside the zone begins a normal drag immediately; returning to
@@ -13,11 +13,11 @@ floating-app title-bar carrying are unaffected. Multi-button gestures keep their
 existing behavior. A motion onto another desktop monitor starts a drag;
 cross-monitor motion is not stabilized.
-CLI (runtime preferences, reset to 8 on desktop restart):
+CLI (runtime preferences, reset to 32 on desktop restart):
 ```sh
 input/ft-clickctl status
-input/ft-clickctl threshold 8
+input/ft-clickctl threshold 32
 input/ft-clickctl threshold 0  # disable without a restart
 ```
@@ -29,6 +29,6 @@ This is a separate contribution from desktop mouse/controller ownership. Its
 hardware validation must check small controls, intentional text selection,
 long presses, cross-monitor dragging and simultaneous mouse use. The existing
 renderer laser remains tracked; this change stabilizes desktop input rather
-than smoothing the visual laser. Default threshold is a starting point to test.
+than smoothing the visual laser. The default was 8 at first. That's about 0.2° on a 3.4 m wide 3440-pixel screen 2 m away, and clicking took a very still hand, so it's 32 (about 0.9°) since 2026-10-03.
 Run `scripts/test-controller-click.sh` for the isolated gesture-state tests.
@@ -38,7 +38,7 @@ The curved layout chains screens edge to edge, like monitors on a desk: the midd
 A resize handle has to be able to shrink a screen from any direction, so the dragged corner follows the laser along the screen's diagonal rather than taking the larger of its horizontal and vertical reach. Pushing and pulling a carried screen moves it along the line from your head, because the 3D mouse's virtual controller sits just in front of the bar, below the screen's centre, so the line from the device points mostly upward.
-Wherever ft-screens needs to know where a laser points (showing the controls, the resize tab, the roll knob), it uses the laser's own pose, the render model's `tip` component, rather than the controller's pose. On the Frame's controllers the tip points 40° below the pose's forward axis, so rays from the pose missed what the laser was actually on. The 3D mouse's virtual controller has no tip, and its laser runs along its pose.
+Wherever ft-screens needs to know where a laser points (showing the controls, the resize tab, the roll knob), it uses the laser's own pose, the render model's `tip` component, rather than the controller's pose. On the Frame's controllers the tip points 40° below the pose's forward axis, so rays from the pose missed what the laser was actually on. The 3D mouse's virtual controller has no tip, and its laser runs along its pose. ft-screens reads the tip with `GetComponentState`: `GetComponentStateForDevicePath` without an input source handle fails for every component while a VR game runs, so in games the rays came from the pose, 40° too high.
 `ComputeOverlayIntersection` ignores `SetOverlayIntersectionMask`, and a control can't be allowed to cover part of its screen, so the resize tab sits entirely outside the corner.
@@ -62,7 +62,7 @@ A profile's screen part is the custom arrangement under a name: each screen's po
 `IVRApplications::GetCurrentSceneProcessId()` is 0 when no game is running (the Frame's home environment isn't a scene app) and the game's process ID while one is. ft-screens checks it twice a second, turns the flag off while a game runs, and by default hides the screens unless the dashboard is open. Flatscreen games run inside Steam's gamescope overlay and aren't scene apps, which is why "only with the dashboard open" is offered as a controller setting.
-The reset button needs to work in a game, where the screens have the flag off. So ft-screens turns the flag on for that button's overlay alone while a hand controller aims within about one button's width of it, and off half a second after the aim leaves a zone twice as wide. ft-screens finds the aim from the controllers' laser poses, which it reads anyway to show the controls, so it doesn't need SteamVR's laser to be on first. The game loses the controllers only while you aim at the button.
+In a game, Frametop's panels work like SteamVR's own floating windows: point a controller at one and its laser comes on, point away and the game has the controllers again. ft-screens turns the flag on for a panel while a hand controller's laser pose meets it, its controls, or a floating window's popups. It finds that from the poses it already reads to show the controls, so SteamVR's laser doesn't have to be on first. Leaving takes a margin two control-sizes wide and 0.3 s, a drag or a held button keeps the flag on, and the keyboard, a single overlay, uses SteamVR's `ComputeOverlayIntersection`. The 3D mouse doesn't need any of this: it has its own laser mode.
 ## Floating windows
@@ -185,6 +185,8 @@ KWin renders with OpenGL through zink on Turnip, Vulkan on the same GPU vrcompos
 The nested session also runs the system's XDG autostart entries, being a KDE session. Discover's update notifier started `plasma-discover --mode update` in it (520 to 620 MB resident and about 9% of a core, plus `flatpak-system-helper` and AppStream downloads), and IBus started a daemon, the kimpanel panel and its GTK extension that nothing can use: KWin hands text input to the one input method it starts (`ft-textinput`), and the session drops `QT_IM_MODULE`, `GTK_IM_MODULE` and `XMODIFIERS`. The session hides both for this desktop only, with `Hidden=true` copies in its own autostart folder. The geoclue demo agent stays: it's what answers apps' location requests to Geoclue outside GNOME, and it costs nothing while idle. Orca's entry only starts in GNOME-family desktops.
 Plasma 6.2.5 keeps each panel on a screen number (`lastScreen` in `plasma-org.kde.plasma.desktop-appletsrc`), and the numbers rank the enabled outputs by priority, so 0 is the primary screen. A panel whose number is past the screen count gets no view, and Plasma never moves it: the remap it runs at every start only moves a panel whose number has no desktop, and this desktop keeps a desktop for every output it has seen, spares included. So the taskbar was lost when the number of screens went down, and once it was found saved on a spare output, number 8 of a desktop with three screens ([#18](https://github.com/DeeJanuz/frametop/issues/18)). Before Plasma starts, the session runs `session/fix-panels.py`, which moves any panel numbered past the screen count, with its system tray's containment, to screen 0, keeping its widgets and settings. A panel stays put when screen 0 already has one on that edge, and comes back by itself if the screens do. The file is backed up to `<file>.ft-bak` first. Plasma's scripting can't do this while it runs (`panel.screen` is read-only in 6.2.5), so a lost taskbar comes back at the desktop's next start. `scripts/doctor.sh` and `scripts/report.sh` list the panels and their screens.
 Remote desktop is a chain (krdp, then FreeRDP inside Xvnc) because nothing on SteamOS serves KWin over VNC directly. Kept connected all the time, it cost about a core with nobody watching: krdpserver 55 to 78% (it encodes H.264 in software with openh264: VA-API finds no driver for the Frame's GPU in the container), FreeRDP 16 to 27%, Xvnc 6 to 11%, and the bridge's layout check every 5 seconds another 4%. krdp creates its screencast session per RDP connection and drops it when the connection closes (`SessionController::onNewConnection` in krdp 6.7), so an idle krdpserver costs nothing and can stay up; only the RDP connection has to go. The bridge connects FreeRDP when a VNC client appears and disconnects 45 seconds after the last one leaves. Xvnc has no hook for its clients, so the bridge counts established connections to its port with `ss`, woken early by Xvnc's log output; looking with `ss` once a second cost about 0.9% of a core in bash, against about 0.1% this way. `Xvnc -inetd` from a systemd socket would start a server per connection and lose sharing between viewers. The layout check (`ft-layout remote-view`, which scans `/proc` for plasmashell and runs `kscreen-doctor -j`) now runs only while FreeRDP runs, and then only after `kwinoutputconfig.json` or `frametop-layout.json` changes, with one check a minute in case a change touched neither.
 Program names stay within 15 characters, because Linux truncates process names there and the scripts find programs with `pgrep -x` and `pkill -x`. That's why the prefix is `ft-`.
@@ -224,6 +226,5 @@ On the Frame, SteamVR is part of the OS image (`/opt/steamvr`, the `deckard-stea
 - A controller button that shows the screens during a game. Games own the controllers, so this needs SteamVR input actions for ft-screens.
 - Drawing KWin's cursor on the screens.
 - Plasma can lose its panels when the number of screens goes down, because they're saved against a screen that no longer exists. Removing `plasma-org.kde.plasma.desktop-appletsrc` and `plasmashellrc` from `~/.config/frametop` brings the default panels back.
 - Frame pacing and GPU cost with several busy screens haven't been measured.
 - Real standby on a stand, with rendering and tracking paused, not just the backlight off. SteamVR has no call for it, and its activity level follows the proximity sensor.
@@ -44,7 +44,7 @@ Every screen is an overlay named `frametop.screen.N` with five controls:
 - `.curve` bends the screen into a cylinder around you, using your current distance as the radius, or makes it flat again.
 - `.roll` rolls the screen when you drag it sideways, like a knob. It snaps level within 2.5°, and scrolling on it turns 5° per notch.
 - `.resize`, the tab on the bottom right corner, sets the width. Screens go down to 15 cm wide.
- `.reset`, left of the bar, puts every screen back in its layout around where you are now, like Meta+Shift+R (`ft-layout apply`). In a VR game, where the screens leave the controllers to the game, aiming a controller at it turns SteamVR's laser on for that button alone, so the trigger clicks it; the game gets the controllers back half a second after you aim away.
+- `.reset`, left of the bar, puts every screen back in its layout around where you are now, like Meta+Shift+R (`ft-layout apply`).
 The controls are sized from both the screen's width and its distance from you, follow the surface of a curved screen, and stay invisible until a laser or the 3D mouse's cursor lands on one or comes within about 1.5 times a button's size of it. While invisible they're still there, fully transparent, so SteamVR's laser can find them. They're translucent until a laser is on them, like SteamVR's own window controls.
@@ -62,7 +62,7 @@ The Visibility & pins tab of Frametop Display Settings decides when the screens
 In the last three modes the hotkey shows the screens anyway. A screen can also be hidden on its own (Screens shown on the same tab, or `ft-layout hide N`): it stays hidden whatever the mode or the hotkey says, until it's shown again there. Windows on it stay put, and a new window that would open on it floats instead (ft-floatd). Profiles use this to show only some screens. Two more settings on the same tab cover VR games, which ft-screens detects as SteamVR scene apps:
 - During VR games, the Always mode hides the screens unless the dashboard is open (the default), or leaves them up.
- Controllers on the screens. Visible screens can keep SteamVR's laser mouse on, so controllers work them with the dashboard closed, but that also takes the controllers away from a game. By default this is off while a VR game runs, and the 3D mouse or the dashboard works the screens. The other choices are always on, or only with the dashboard open, which also suits flatscreen games since they aren't scene apps.
+- Controllers on the screens. Visible screens can keep SteamVR's laser mouse on, so controllers work them with the dashboard closed, but that also takes the controllers away from a game. By default this is off while a VR game runs, and the 3D mouse or the dashboard works the screens. Pointing a controller at a screen, a floating window, or the keyboard still turns its laser on, like SteamVR's own floating windows, and pointing away gives the game the controllers back. The other choices are always on, or only with the dashboard open, which also suits flatscreen games since they aren't scene apps.
 Input from the lasers reaches KWin through ft-screens' own seat. Keys come from the input relay, from pass-through keyboards and any key a pointer device passes through. Typing follows your last click: after a click on a screen it goes to the desktop, even with the SteamVR dashboard open, and after a mouse click on any other panel (the dashboard, Steam, an app like Spotify) it goes there instead. While it goes to the desktop, the relay grabs pass-through keyboards so gamescope, which reads every keyboard itself, doesn't type them into the Steam app too. A program that watches every keyboard for a hotkey loses a grabbed one; with `SHARE_KEYS=1` in `~/.config/frametop.conf`, their keys also go to `@frametop_keys` for it. That's off by default, since any local process that binds the name first would get everything typed into the desktop. Hidden screens don't take typing.
@@ -134,7 +134,7 @@ A Kirigami app with a Python backend, in the Plasma menu under Settings. It runs
 - Buttons maps a pointer device's buttons. Choose Capture a button, press the button or key, then pick an action: a click, back, scroll, toggle dashboard, recenter, pointer on or off, head follow on or off, gaze pointer on or off, gaze precision, gaze drag, gaze quick check, faster or slower, reset the screen layout, hide or show the screens, open or close the keyboard, float a window in VR or put it back, put all floating windows back, pause or resume Frametop ([Pausing for VR games](#pausing-for-vr-games)), Open profile NAME (one per profile, [profiles.md](profiles.md)), pass the key through, or nothing. Devices with saved mappings are listed even while they're asleep.
 - Controllers maps the Frame controllers' buttons (every button but the system button) to the same actions, except passing a key through and the gaze actions: gaze mode is a mouse and keyboard feature ([gaze-controllers.md](gaze-controllers.md)). Capture a button and press it on a controller, or pick it from the list. The controllers aren't input devices on the host; only SteamVR sees them. So the pointer helper reads them with SteamVR input (`pointer/helper/vrbuttons.h`, `pointer/helper/actions/`) and sends presses to the relay (`vrbtn right/a 1`), which does the mapped action. The helper only takes the buttons that are mapped (the relay tells it with `vrbind`), at an overlay-global priority, and only while no game (scene application) runs, so games keep every button; with In games on (`controller_in_games`), a mapped button is taken from games too. That needs SteamVR's "Enable global input from overlays (Experimental)" setting (`steamvr/globalActionSetPriority`), which the page's Global input switch turns on and off. Mappings are saved as `controller_buttons` in `~/.config/frametop-input.json`.
 - Game optimization has the pause for VR games: its state with Pause now or Resume, whether VR games pause Frametop by themselves, the controller gesture (one or two buttons, pressed once or twice; one button always takes two presses), what happens to the desktop, and the sound. They're saved as `pause_auto`, `pause_gesture`, `pause_desktop`, and `pause_sound` in `~/.config/frametop-input.json`. See [Pausing for VR games](#pausing-for-vr-games).
- Keyboard sets when Frametop's keyboard opens: whenever a text field is selected; only while no pass-through keyboard is connected (the default; keyboards other programs make through uinput, like frame-voice's, don't count); only with a mouse or controller button mapped to Open/close keyboard; or never, which turns the button off too. Keep it open (on by default, `vr_keyboard_persist`) leaves it open after the text field loses focus. The mode is saved as `vr_keyboard` in `~/.config/frametop-input.json`, and the page lists the keyboards that count as connected. Its Key combinations section maps modifiers plus a key, or one modifier tapped on its own, on any keyboard, to any action but passing a key through or nothing, or to Run a command…: a command line the input relay runs with `sh -c` when you press the keys (`command:CMD`). The command runs as the relay's user service, outside the desktop's session, with `layout/`, `float/` and `steam/` on its `PATH` (so `ft-layout use Work` or `ft-float launch org.kde.dolphin` work as they are), and its output goes to the relay's journal. The gaze clicks (Gaze left click and Gaze right click) only go on key combinations. The defaults are a Meta tap (open the Steam menu, or close the dashboard), Meta+J (gaze left click), Meta+K (gaze right click), and Meta+Shift+F (float window in VR or put it back); remove them or add others there. A tap is a press and release with no other key, mouse button, or scroll in between; a bound one sends the desktop F24 before the release, so Plasma's launcher doesn't open on it. The combination's last key isn't typed, and the modifiers still reach the app; while typing goes to Steam rather than the desktop, keyboards aren't grabbed, so Steam or the game sees the keys too. They're saved as `key_bindings` in the same file; a file with its own list, even an empty one, gets no defaults.
+- Keyboard sets when Frametop's keyboard opens: whenever a text field is selected; only while no pass-through keyboard is connected (the default; keyboards other programs make through uinput, like frame-voice's, don't count); only with a mouse or controller button mapped to Open/close keyboard; or never, which turns the button off too. Keep it open (on by default, `vr_keyboard_persist`) leaves it open after the text field loses focus. The mode is saved as `vr_keyboard` in `~/.config/frametop-input.json`, and the page lists the keyboards that count as connected. Its Key combinations section maps modifiers plus a key, or one modifier tapped on its own, on any keyboard, to any action but passing a key through or nothing, or to Run a command…: a command line the input relay runs with `sh -c` when you press the keys (`command:CMD`). The command runs as the relay's user service, outside the desktop's session, with `layout/`, `float/` and `steam/` on its `PATH` (so `ft-layout use Work` or `ft-float launch org.kde.dolphin` work as they are), and its output goes to the relay's journal. The gaze clicks (Gaze left click and Gaze right click) only go on key combinations. The defaults are a Meta tap (open the Steam menu, or close the dashboard), Meta+J (gaze left click), Meta+K (gaze right click), Meta+Shift+F (float window in VR or put it back), and Meta+Alt+Tab and Meta+Alt+Shift+Tab (spin the panels: every screen and floating window turns about your head, so the next one on the right or left comes to the front; ft-screens' `spin next|prev|<degrees>`); remove them or add others there. A tap is a press and release with no other key, mouse button, or scroll in between; a bound one sends the desktop F24 before the release, so Plasma's launcher doesn't open on it. The combination's last key isn't typed, and the modifiers still reach the app; while typing goes to Steam rather than the desktop, keyboards aren't grabbed, so Steam or the game sees the keys too. They're saved as `key_bindings` in the same file; a file with its own list, even an empty one, gets no defaults.
 - Pointer has a Head follow switch and sliders for the pointer settings, which apply immediately, and a Recenter button.
 - Ignored panels lists the SteamVR overlays that are showing, grouped by app (the first two parts of the overlay key, such as `sasaken.frame-perf-overlay`), from the pointer helper (`overlays`). Tick a panel, or Ignore the whole app, and the pointer passes through it to what's behind. It's for panels you only look at, like a performance overlay that follows your view. The list is saved as `POINTER_IGNORE` in `~/.config/frametop.conf`: comma-separated overlay keys, where a shell pattern like `vendor.app*` covers a whole app, including panels it opens later. The helper reloads at once. Frametop's own screens aren't listed, and entries for apps that aren't open are listed below, to remove.
 - Gaze has the gaze pointer switch (on now and from now on; a mapped button toggles it until the helper restarts), what the mouse's left button and movement do, the gaze dot, the eye tracker and eye bias, the gaze mode sliders, the gaze service's state (headset, samples per second, how often the tracker is losing each eye, the calibration, the nudges learned), and Quick check, Calibrate, and Check headset fit (each in a panel in the headset), Reload calibration, and Forget nudges. The gaze probe, a development tool, is in the page's overflow menu.
@@ -378,6 +378,17 @@ function run(c) {
        case "activate":
            if (w) workspace.activeWindow = w;
            break;
        case "activate-output": {  // the top window on that output (a spin brought it to the front)
            const order = workspace.stackingOrder;
            for (let i = order.length - 1; i >= 0; --i) {
                const o = order[i];
                if (o.deleted || o.minimized || o.hidden || !o.managed || !o.output) continue;
                if (o.output.name !== c.output || !o.normalWindow || o.popupWindow) continue;
                workspace.activeWindow = o;
                break;
            }
            break;
        }
        case "minimize":
            if (w) w.minimized = c.on;
            break;
@@ -18,6 +18,8 @@ command-line side). Replies go to the sender:
  ("float pointer" is the float key: the window under the pointer, else the active one,
  floated or docked; the input relay sends it for float_toggle, and "dock all" for dock_all)
  dock N | close N | resize N W H | scale N STEPS                      (ft-screens, N = its screen)
  front N   (ft-screens: a spin brought panel N to the front: make its window, or the top one
            on a screen, KWin's active window)
 Spare outputs are WL-<screens> .. WL-<screens + slots - 1>. A floating window's output is its
 frame plus a margin on each side (FLOAT_MARGIN pixels), so menus have room; the panel shows
@@ -1063,6 +1065,13 @@ class Daemon:
            for f in list(self.floats.values()):
                self.dock(f)
            return "ok"
        if cmd == "front" and len(rest) == 1 and rest[0].isdigit():
            f = self.by_panel(int(rest[0]))
            if f:
                self.command(cmd="activate", id=f.id)
            else:  # a screen: its output is WL-<N - 1>
                self.command(cmd="activate-output", output=f"WL-{int(rest[0]) - 1}")
            return "ok"
        if cmd in ("dock", "close", "resize", "scale") and rest and rest[0].isdigit():
            f = self.by_panel(int(rest[0]))
            if not f:
@@ -0,0 +1,59 @@
 # Install with FrameDrop (proof of concept)
 [FrameDrop](https://framedropvr.com) is a Windows app that sideloads onto a Steam Frame: it copies a build to the headset and adds it to the Steam library. Issue #25 asks for an "Install with FrameDrop" button. Frametop isn't an app FrameDrop can copy over as is: it builds in a container, installs user services and a SteamVR driver, and asks questions in a terminal. So FrameDrop installs a small installer instead. Playing "Frametop" from the library runs the one-line installer (`get.sh --yes`) and shows its progress.
 Nothing here is published yet: no release asset, no manifest on Pages, no button.
 ## How FrameDrop installs a Linux zip
 It uses Valve's SteamOS Devkit path: pair once with the headset's devkit service, then rsync the unpacked zip into `~/devkit-game/<name>` over SSH, and register it with Steam as a Devkit Game with a start command. `devkit.sh` here makes the same calls with Valve's devkit-utils, so all of this can be tested on the Frame without a PC.
 ## What the probe found (SteamOS 0.3.0, build 20260922.6101926)
 `probe/probe.sh`, started as a Devkit Game, recorded:
 - Devkit titles run on the host, not in a container, as user `steamos`, from a process tree that Steam's reaper owns. This held even with the compat tool set to `SteamLinuxRuntime_4-arm64`: Steam recorded the mapping and still ran it on the host.
 - On the host, everything the installer needs works: git, curl to GitHub, podman (sees the `dev` container), `systemctl --user`, `systemd-run --user`, and GTK 4 with libadwaita.
 - A GTK window opens in gamescope (an X11 window on `:1`, drawn through gamescope's Vulkan WSI).
 - Steam puts its overlay in `LD_PRELOAD` and Steam runtime paths in `LD_LIBRARY_PATH` and `PATH`. Every host tool prints a preload error unless they're cleared.
 - Inside the Steam Linux Runtime 4 container (started by hand with its `run` script), there's no git, podman, systemctl, or GTK, but `flatpak-spawn --host` runs commands on the host.
 - Steam refuses Devkit Game names with a `-` ("missing/invalid arguments").
 - Steam doesn't make the start command executable: without the exec bit, the title exits in a second and nothing runs.
 ## The installer
 `installer/frametop-install.sh` is the start command.
 1. In the container, it starts itself again on the host with `flatpak-spawn --host`.
 2. It clears Steam's preload and library paths.
 3. It runs `curl get.sh | bash -s -- --yes` in a transient user service, `frametop-framedrop-install`, unless one is already running. The service is used because Steam ends the title's whole process tree when it's quit, and starts it with an OOM score of 900.
 4. `installer/progress.py` (GTK 4 and libadwaita) follows the service's log, shows `install.sh`'s steps as a progress bar, and reports the result. Closing it leaves the install running. Playing the title again reattaches.
 `--yes` keeps the version that's installed, or installs stable. It skips the parts that need sudo (our eye tracker and the Bluetooth fixes) and the SteamVR restart. The window says to restart SteamVR.
 `--dry-run` clones into `~/.cache/frametop-framedrop/dry-run` and stops there (`get.sh --clone-only`).
 ## Try it on the Frame
 ```
 framedrop/devkit.sh add FrametopTest framedrop/installer "./frametop-install.sh --dry-run"
 framedrop/devkit.sh run FrametopTest        # or Play it from the Steam library
 framedrop/devkit.sh remove FrametopTest
 framedrop/devkit.sh add FrametopProbe framedrop/probe "./probe.sh native"   # the probe
 ```
 The probe writes `~/.cache/frametop-framedrop/probe-native.log`, and the installer writes `~/.cache/frametop-framedrop/install.log`.
 ## Build the download
 ```
 framedrop/build.sh [ZIP_URL]
 ```
 This writes `framedrop/build/Frametop.zip` (reproducible) and `frametop.framedrop.json`, FrameDrop's manifest with the zip's sha256. By default, `ZIP_URL` points at a `framedrop-installer` release asset. The button's link would be `https://framedropvr.com/install?manifest=https://deejanuz.github.io/frametop/frametop.framedrop.json`, with the manifest committed to main for Pages.
 ## Open questions, for a test with FrameDrop on a Windows PC
 - Does FrameDrop keep or set the exec bit on `frametop-install.sh`? A zip unpacked on Windows loses it, and without it nothing runs.
 - What start command does FrameDrop pick for this zip, and which runtime?
 - Does the manifest's `name` become the Devkit Game name? It has to stay free of `-`.
@@ -0,0 +1,39 @@
 #!/usr/bin/env bash
 # Build the FrameDrop download: framedrop/build/Frametop.zip (the installer in a "Frametop"
 # folder) and framedrop/build/frametop.framedrop.json, the manifest an "Install with
 # FrameDrop" button points at. The zip is reproducible: same files, same sha256.
 #
 # Usage: framedrop/build.sh [ZIP_URL]
 #   ZIP_URL  where the zip will be downloaded from (default: the framedrop-installer release)
 set -euo pipefail
 here=$(cd "$(dirname "$0")" && pwd)
 url=${1:-https://github.com/DeeJanuz/frametop/releases/download/framedrop-installer/Frametop.zip}
 out=$here/build
 mkdir -p "$out"
 python3 - "$here/installer" "$out/Frametop.zip" <<'EOF'
 import os, sys, zipfile
 src, dest = sys.argv[1:]
 with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as z:
    for name in ("frametop-install.sh", "progress.py"):
        info = zipfile.ZipInfo(f"Frametop/{name}", date_time=(2026, 1, 1, 0, 0, 0))
        info.create_system = 3  # unix, so the permissions below count
        info.external_attr = (0o100755 if os.access(os.path.join(src, name), os.X_OK) else 0o100644) << 16
        info.compress_type = zipfile.ZIP_DEFLATED
        with open(os.path.join(src, name), "rb") as f:
            z.writestr(info, f.read())
 EOF
 sha=$(sha256sum "$out/Frametop.zip" | cut -d' ' -f1)
 python3 - "$url" "$sha" >"$out/frametop.framedrop.json" <<'EOF'
 import json, sys
 url, sha = sys.argv[1:]
 print(json.dumps({
    "schema": "framedrop.install/v1",
    "name": "Frametop",
    "files": [{"url": url, "sha256": sha}],
 }, indent=2))
 EOF
 echo "built $out/Frametop.zip ($sha)"
 echo "      $out/frametop.framedrop.json"
@@ -0,0 +1,95 @@
 #!/usr/bin/env bash
 # Do on the Frame what FrameDrop does from a PC: copy a folder into ~/devkit-game/NAME and
 # register it with Steam as a "Devkit Game" (Valve's devkit-utils, the same calls FrameDrop and
 # the SteamOS Devkit Client make over SSH). For testing the FrameDrop installer and the probe
 # without a PC. Steam must be running, and Developer Mode on.
 #
 # Usage: devkit.sh add NAME DIR COMMAND [--compat TOOL]
 #        devkit.sh run NAME       # start it, as the library's Play button does
 #        devkit.sh remove NAME    # delete the folder and the Steam entry
 #        devkit.sh list
 #
 # NAME can't contain "-": Steam answers "missing/invalid arguments". COMMAND is relative to
 # the folder, like FrameDrop's start command ("./probe.sh native"). --compat sets the runtime
 # (SteamLinuxRuntime_4-arm64, say); on SteamOS 0.3.0 Steam recorded it but still ran the
 # title on the host. There's no environment option: this Steam ignores the devkit env file.
 #
 # devkit-utils is Valve's (LGPL, gitlab.steamos.cloud/devkit/steamos-devkit). FrameDrop and
 # the devkit client copy it to ~/devkit-utils; if that isn't there, it's fetched at a pinned
 # commit into ~/.cache/frametop-framedrop.
 set -euo pipefail
 devkit_rev=a00ceb7d91ea44a0c3e714a91a06417d6e5cdb33
 cache=$HOME/.cache/frametop-framedrop
 usage() { sed -n '7,10p' "$0" | sed 's/^# \{0,1\}//' >&2; exit 2; }
 utils() {
  if [ -e "$HOME/devkit-utils/steam-client-create-shortcut" ]; then
    echo "$HOME/devkit-utils"; return
  fi
  if [ ! -e "$cache/devkit-utils/steam-client-create-shortcut" ]; then
    echo "fetching devkit-utils ($devkit_rev)" >&2
    local tmp
    tmp=$(mktemp -d)
    git -C "$tmp" init -q
    git -C "$tmp" fetch -q --depth 1 https://gitlab.steamos.cloud/devkit/steamos-devkit.git "$devkit_rev"
    git -C "$tmp" checkout -q FETCH_HEAD
    mkdir -p "$cache"
    rm -rf "$cache/devkit-utils"
    cp -r "$tmp/client/devkit-utils" "$cache/devkit-utils"
    rm -rf "$tmp"
  fi
  echo "$cache/devkit-utils"
 }
 [ $# -ge 1 ] || usage
 cmd=$1; shift
 case $cmd in
  add)
    [ $# -ge 3 ] || usage
    name=$1 src=$2 start=$3; shift 3
    case $name in *-*) echo "NAME can't contain '-' (Steam refuses it)" >&2; exit 2 ;; esac
    compat=
    while [ $# -gt 0 ]; do
      case $1 in
        --compat) compat=${2:?}; shift ;;
        *) usage ;;
      esac
      shift
    done
    u=$(utils)
    dir=$(python3 "$u/steamos-prepare-upload" --gameid "$name" | python3 -c 'import json,sys; print(json.load(sys.stdin)["directory"])')
    # FrameDrop rsyncs the unpacked zip; --delete as a clean upload would.
    rsync -a --delete "$src/" "$dir/"
    parms=$(python3 - "$name" "$dir" "$start" "$compat" <<'EOF'
 import json, sys
 name, directory, start, compat = sys.argv[1:]
 print(json.dumps({
    "gameid": name, "directory": directory,
    "argv": [start], "env": {},
    "settings": {"steam_play": "0", "compat_tool": compat},
    "force_appid": "", "lepton_args": "",
 }))
 EOF
 )
    res=$(python3 "$u/steam-client-create-shortcut" --parms "$parms" | tail -1)
    echo "Steam: $res"
    case $res in *'"error"'*) exit 1 ;; esac
    echo "registered $name ($dir)"
    ;;
  run)
    [ $# -eq 1 ] || usage
    python3 "$(utils)/steam-devkit-rpc" run-game "gameid=$1" | tail -1
    echo
    ;;
  remove)
    [ $# -eq 1 ] || usage
    python3 "$(utils)/steamos-delete" --delete-title "$1"
    rm -f "$HOME/devkit-game/$1"-*.json
    ;;
  list)
    python3 "$(utils)/steam-devkit-rpc" list-shortcuts
    ;;
  *) usage ;;
 esac
@@ -0,0 +1,58 @@
 #!/usr/bin/env bash
 # Frametop's FrameDrop installer: the start command of the "Frametop" title that FrameDrop
 # puts in the Steam library. Playing it installs Frametop (or updates it) with the one-line
 # installer, get.sh --yes, and shows its progress in a window.
 #
 # Steam ends a title's whole process tree when it's quit, and starts it with a high OOM score,
 # so the install runs in a user service of its own (frametop-framedrop-install) and the window
 # only follows its log. Quitting or closing the window leaves the install running; playing the
 # title again reattaches to it.
 #
 # Usage: frametop-install.sh [--dry-run]
 #   --dry-run  clone into ~/.cache/frametop-framedrop/dry-run instead of ~/frametop, and
 #              don't run install.sh (get.sh --clone-only), for testing this flow
 set -u
 here=$(cd "$(dirname "$0")" && pwd)
 self=$here/$(basename "$0")
 # A Linux title can be started in the Steam Linux Runtime container, which has no git, podman,
 # systemctl, or GTK. Start this again on the host. (SteamOS 0.3.0 runs devkit titles on the
 # host anyway; this is for when FrameDrop or Steam picks the runtime.)
 if [ -e /run/pressure-vessel ]; then
  exec flatpak-spawn --host --watch-bus --env=DISPLAY="${DISPLAY-}" \
    --env=XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR-}" --env=SteamAppId="${SteamAppId-}" \
    --env=ENABLE_GAMESCOPE_WSI="${ENABLE_GAMESCOPE_WSI-}" /usr/bin/bash "$self" "$@"
 fi
 # Steam adds its overlay and runtime libraries to every child; host tools don't want them.
 unset LD_PRELOAD LD_LIBRARY_PATH
 export PATH=/usr/local/bin:/usr/bin:/bin
 dry_run=0
 [ "${1-}" = --dry-run ] && dry_run=1
 unit=frametop-framedrop-install
 state=$HOME/.cache/frametop-framedrop
 log=$state/install.log
 mkdir -p "$state"
 get_args="--yes"
 [ "$dry_run" = 1 ] && get_args="--yes --clone-only --dir $state/dry-run"
 # Start the install unless one is running already. RemainAfterExit keeps its result for the
 # window; the next start clears it.
 if [ "$(systemctl --user show -P ActiveState "$unit" 2>/dev/null)" != activating ]; then
  systemctl --user stop "$unit" 2>/dev/null
  systemctl --user reset-failed "$unit" 2>/dev/null
  : >"$log"
  systemd-run --user --unit="$unit" --description="Frametop install (FrameDrop)" \
    --property=Type=oneshot --property=RemainAfterExit=yes \
    --property=StandardOutput="truncate:$log" --property=StandardError=inherit \
    --setenv=HOME="$HOME" --setenv=PATH="$PATH" --setenv=TERM=dumb \
    --working-directory="$HOME" --quiet --no-block \
    /usr/bin/bash -c 'set -o pipefail; curl -fsSL https://deejanuz.github.io/frametop/get.sh | bash -s -- '"$get_args" ||
    { echo "couldn't start the install service" >&2; exit 1; }
 fi
 exec /usr/bin/python3 "$here/progress.py" "$unit" "$log"
@@ -0,0 +1,125 @@
 #!/usr/bin/env python3
 """Progress window for the FrameDrop installer: follows the install service's log and state.
 Usage: progress.py UNIT LOG
 Closing the window doesn't stop the install; it keeps running in the user service UNIT.
 """
 import re
 import subprocess
 import sys
 import gi
 gi.require_version("Gtk", "4.0")
 gi.require_version("Adw", "1")
 from gi.repository import Adw, GLib, Gtk, Pango  # noqa: E402
 UNIT, LOG = sys.argv[1], sys.argv[2]
 ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
 # install.sh marks each step with "== N/10 what it is"
 STEP = re.compile(r"^== (\d+)/(\d+) (.*)$")
 DONE_TEXT = ("Frametop is installed. Restart SteamVR once, or reboot the headset, so it loads "
             "Frametop's driver. Then open Launch a program, then Desktop.")
 def unit_state():
    out = subprocess.run(
        ["systemctl", "--user", "show", "-P", "ActiveState", UNIT],
        capture_output=True, text=True).stdout.strip()
    return out or "inactive"
 class Window(Adw.ApplicationWindow):
    def __init__(self, app):
        super().__init__(application=app, title="Frametop")
        self.set_default_size(900, 600)
        self.offset = 0
        self.partial = ""
        self.status = Gtk.Label(label="Installing Frametop", xalign=0, wrap=True)
        self.status.add_css_class("title-2")
        self.detail = Gtk.Label(label="Starting...", xalign=0, wrap=True)
        self.bar = Gtk.ProgressBar()
        self.bar.pulse()
        self.text = Gtk.TextView(editable=False, cursor_visible=False, monospace=True,
                                 wrap_mode=Pango.WrapMode.WORD_CHAR)
        self.text.set_left_margin(8)
        self.text.set_right_margin(8)
        scroll = Gtk.ScrolledWindow(vexpand=True, child=self.text)
        self.scroll = scroll
        self.note = note = Gtk.Label(
            label="You can close this window: the install keeps going. Play Frametop again to "
                  "come back to it.", xalign=0, wrap=True)
        note.add_css_class("dim-label")
        close = Gtk.Button(label="Close", halign=Gtk.Align.END)
        close.connect("clicked", lambda *_: self.close())
        box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12,
                      margin_top=18, margin_bottom=18, margin_start=18, margin_end=18)
        for w in (self.status, self.detail, self.bar, scroll, note, close):
            box.append(w)
        view = Adw.ToolbarView(content=box)
        view.add_top_bar(Adw.HeaderBar())
        self.set_content(view)
        self.finished = False
        GLib.timeout_add(500, self.tick)
        self.tick()
    def add_lines(self, lines):
        buf = self.text.get_buffer()
        for line in lines:
            m = STEP.match(line)
            if m:
                n, total, what = int(m[1]), int(m[2]), m[3]
                self.bar.set_fraction((n - 1) / total)
                self.detail.set_label(f"Step {n} of {total}: {what}")
            buf.insert(buf.get_end_iter(), line + "\n")
        # Keep the view at the newest line.
        end = buf.create_mark(None, buf.get_end_iter(), False)
        self.text.scroll_mark_onscreen(end)
        buf.delete_mark(end)
    def tick(self):
        try:
            with open(LOG, "rb") as f:
                f.seek(self.offset)
                data = f.read()
                self.offset += len(data)
        except FileNotFoundError:
            data = b""
        if data:
            text = self.partial + ANSI.sub("", data.decode("utf-8", "replace")).replace("\r", "\n")
            *lines, self.partial = text.split("\n")
            self.add_lines(lines)
        state = unit_state()
        if state == "activating":
            if self.bar.get_fraction() == 0:
                self.bar.pulse()
            return True
        if self.partial:
            self.add_lines([self.partial])
            self.partial = ""
        self.note.set_visible(False)
        if state == "active":
            self.status.set_label("Done")
            self.detail.set_label(DONE_TEXT)
            self.bar.set_fraction(1)
        else:
            self.status.set_label("The install stopped")
            self.detail.set_label("The log above says why. Play Frametop again to try again.")
        return False
 def main():
    app = Adw.Application(application_id="io.github.deejanuz.FrametopInstall")
    app.connect("activate", lambda a: Window(a).present())
    app.run([])
 if __name__ == "__main__":
    main()
@@ -0,0 +1,114 @@
 #!/usr/bin/env bash
 # FrameDrop proof of concept, step 1: run as a Steam "Devkit Game" (what FrameDrop installs a
 # Linux zip as) and record what an installer started from Steam could use: host or Steam Linux
 # Runtime container, podman, the user's systemd, git, the network, GTK, and a window on screen.
 # Register and start it: framedrop/devkit.sh add FrametopProbe framedrop/probe "./probe.sh native"
 #                       framedrop/devkit.sh run FrametopProbe
 # Usage: probe.sh LABEL
 # Writes ~/.cache/frametop-framedrop/probe-LABEL.log, replacing the previous one.
 label=${1:-unlabeled}
 out=$HOME/.cache/frametop-framedrop
 mkdir -p "$out"
 log=$out/probe-$label.log
 exec >"$log" 2>&1
 here=$(cd "$(dirname "$0")" && pwd)
 section() { printf '\n== %s\n' "$1"; }
 have() { command -v "$1" >/dev/null 2>&1; }
 check() { # check NAME CMD...: one line, ok or failed with the exit status
  local name=$1; shift
  if out_=$(timeout 20 "$@" 2>&1); then echo "ok      $name: $(echo "$out_" | head -1)"
  else echo "FAILED  $name (exit $?): $(echo "$out_" | head -2 | tr '\n' ' ')"; fi
 }
 section "when, who, where"
 date -Is
 echo "label=$label uid=$(id -u) user=$(id -un) pwd=$PWD here=$here"
 echo "args: $*"
 grep -E '^(ID|VARIANT_ID|VERSION_ID|BUILD_ID|PRETTY_NAME)=' /etc/os-release
 section "container?"
 for p in /run/pressure-vessel /.flatpak-info /run/host/os-release; do
  [ -e "$p" ] && echo "present: $p" || echo "absent:  $p"
 done
 echo "container=${container-} PRESSURE_VESSEL_RUNTIME=${PRESSURE_VESSEL_RUNTIME-}"
 [ -e /run/host/os-release ] && grep -E '^(ID|VARIANT_ID)=' /run/host/os-release
 section "environment"
 env | grep -E '^(PATH|HOME|XDG_[A-Z_]+|DISPLAY|WAYLAND_DISPLAY|DBUS_SESSION_BUS_ADDRESS|SteamAppId|SteamGameId|STEAM_COMPAT_[A-Z_]+|LD_LIBRARY_PATH|LD_PRELOAD|SDL_[A-Z_]+|GDK_BACKEND|ENABLE_[A-Z_]+|PRESSURE_VESSEL_[A-Z_]+)=' | sort
 echo "process tree:"
 pid=$$
 for _ in 1 2 3 4 5 6 7 8; do
  [ "$pid" -le 1 ] 2>/dev/null && break
  printf '  %s %s\n' "$pid" "$(tr '\0' ' ' </proc/"$pid"/cmdline 2>/dev/null | cut -c1-200)"
  pid=$(awk '/^PPid:/{print $2}' /proc/"$pid"/status 2>/dev/null)
 done
 # Steam adds its overlay (LD_PRELOAD) and runtime libraries to every child. An installer has
 # to drop them before running host tools, as the checks below do.
 unset LD_PRELOAD
 LD_LIBRARY_PATH=$(printf %s "${LD_LIBRARY_PATH-}" | tr ':' '\n' | grep -v -e '/Steam/' -e '^$' -e 'x86_64' -e 'i386' | paste -sd:)
 [ -n "$LD_LIBRARY_PATH" ] && export LD_LIBRARY_PATH || unset LD_LIBRARY_PATH
 PATH=$(printf %s "$PATH" | tr ':' '\n' | grep -v '/Steam/' | paste -sd:)
 echo "cleaned: PATH=$PATH LD_LIBRARY_PATH=${LD_LIBRARY_PATH-}"
 section "tools"
 for t in bash git curl python3 podman distrobox systemctl systemd-run busctl gdbus flatpak-spawn \
         steam-runtime-launch-client konsole zenity kdialog; do
  printf '%-28s %s\n' "$t" "$(command -v "$t" || echo -)"
 done
 section "what an installer needs"
 check "home writable" sh -c 'f=$HOME/.cache/frametop-framedrop/.w && : >"$f" && rm "$f" && echo yes'
 check "~/frametop visible" sh -c 'ls -d "$HOME/frametop" && git -C "$HOME/frametop" log -1 --format=%h'
 have git && check "git ls-remote github" git ls-remote --heads https://github.com/DeeJanuz/frametop.git experimental
 have curl && check "curl get.sh" sh -c 'curl -fsSL https://deejanuz.github.io/frametop/get.sh | head -1'
 have podman && check "podman ps" podman ps --format '{{.Names}}'
 have distrobox && check "distrobox list" distrobox list
 have systemctl && check "systemctl --user" systemctl --user is-system-running
 have systemctl && check "user units visible" systemctl --user is-enabled frametop-input-relay.service
 have python3 && check "python3 gi Gtk 4" python3 -c 'import gi; gi.require_version("Gtk","4.0"); gi.require_version("Adw","1"); from gi.repository import Gtk, Adw; print(Gtk.get_major_version(), Gtk.get_minor_version())'
 section "escape to the host (needed if this is a container)"
 # A transient user unit runs in the host's user manager, outside any container.
 if have systemd-run; then
  rm -f "$out/escape-$label"
  check "systemd-run --user" systemd-run --user --wait --collect --quiet -- \
    sh -c "grep -E '^(ID|VARIANT_ID)=' /etc/os-release > '$out/escape-$label'; command -v podman git >> '$out/escape-$label'"
  [ -s "$out/escape-$label" ] && sed 's/^/  host says: /' "$out/escape-$label"
 fi
 if have busctl; then
  check "busctl --user (systemd1)" busctl --user get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Version
 fi
 section "window"
 # A plain GTK 4 window for 20 s. Watch for it on the Frame; "window: mapped" means GTK showed it.
 if have python3; then
  timeout 40 python3 - <<'EOF'
 import sys
 try:
    import gi
    gi.require_version("Gtk", "4.0")
    from gi.repository import Gtk, GLib
 except Exception as e:
    print("window: no GTK 4:", e); sys.exit(0)
 app = Gtk.Application(application_id="io.github.deejanuz.FrametopProbe")
 def on_activate(app):
    w = Gtk.ApplicationWindow(application=app, title="Frametop installer probe")
    w.set_default_size(640, 240)
    w.set_child(Gtk.Label(label="Frametop installer probe\n\nIf you can read this, a FrameDrop install can show progress.\nThis window closes in 20 seconds."))
    w.connect("map", lambda *_: print("window: mapped", flush=True))
    w.present()
    GLib.timeout_add_seconds(20, app.quit)
 app.connect("activate", on_activate)
 print("window: display", Gtk.Widget.get_display(Gtk.Label()) if hasattr(Gtk.Widget, "get_display") else "?", flush=True)
 app.run([])
 print("window: closed")
 EOF
  echo "window exit: $?"
 else
  echo "window: no python3"
 fi
 section "done"
 date -Is
@@ -77,6 +77,8 @@ ACTION_LABELS = {
    "screens_toggle": "Hide/show desktop screens", "keyboard_toggle": "Open/close keyboard",
    "float_toggle": "Float window in VR / put it back", "dock_all": "Put all floating windows back",
    "pause_toggle": "Pause/resume Frametop (for VR games)",
    "spin_next": "Spin the panels: next one on the right to the front",
    "spin_prev": "Spin the panels: next one on the left to the front",
    "key": "Pass through as key",
    "none": "Do nothing",
 }
@@ -163,9 +165,10 @@ GAZE_MOUSE = {"precision": "Gaze precision: hold to steer with the mouse, releas
 MODIFIER_CODES = {29: 29, 97: 29, 42: 42, 54: 42, 56: 56, 100: 56, 125: 125, 126: 125}
 MODIFIER_NAMES = {29: "Ctrl", 42: "Shift", 56: "Alt", 125: "Meta"}
 # What a rules file without "key_bindings" gets (the relay's DEFAULT_KEY_BINDINGS): a Meta tap
-# opens Steam's menu, Meta+J and Meta+K click at the gaze, Meta+Shift+F floats a window.
+# opens Steam's menu, Meta+J and Meta+K click at the gaze, Meta+Shift+F floats a window,
 # Meta+Alt+Tab and Meta+Alt+Shift+Tab spin the panels.
 DEFAULT_KEY_BINDINGS = {"125": "steam_menu", "125+36": "gaze_left", "125+37": "gaze_right",
-                        "42+125+33": "float_toggle"}
+                        "42+125+33": "float_toggle", "56+125+15": "spin_next", "42+56+125+15": "spin_prev"}
 def key_bindings(rules):
@@ -30,7 +30,9 @@ gaze_quickcal = the gaze service's one-dot check ("quickcal" to @ft_gazed), sens
 layout_reset = put the desktop screens back in their saved layout, screens_toggle = hide or show the desktop screens,
 keyboard_toggle = open or close Frametop's keyboard, float_toggle = float the desktop window under the
 pointer (else the active one) in VR, or put it back if it floats, dock_all = put every floating
-window back (both to ft-floatd, @frametop_float), profile:NAME = switch to that profile (ft-layout
+window back (both to ft-floatd, @frametop_float), spin_next and spin_prev = turn every panel in the
 room about your head so the next one to the right or left comes to the front (ft-screens' "spin",
 Meta+Alt+Tab and Meta+Alt+Shift+Tab by default), profile:NAME = switch to that profile (ft-layout
 use NAME: its screens and apps; docs/profiles.md), steam_menu = open the SteamVR dashboard on
 Steam's menu, or close the dashboard (steam/ft-steam menu, through Steam's UI), pause_toggle =
 pause Frametop for a VR game, or resume it (game_pause.py), command:CMD = run
@@ -152,10 +154,10 @@ REL_X, REL_Y, REL_WHEEL, REL_MAX = 0x00, 0x01, 0x08, 0x0F
 SCROLLS = {0x06, REL_WHEEL, 0x0B, 0x0C}  # REL_HWHEEL, REL_WHEEL and their _HI_RES
 BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_SIDE, BTN_EXTRA = 0x110, 0x111, 0x112, 0x113, 0x114
 KEY_LEFTMETA, KEY_RIGHTMETA = 125, 126
-KEY_VOLUMEDOWN, KEY_VOLUMEUP = 114, 115
+KEY_MUTE, KEY_VOLUMEDOWN, KEY_VOLUMEUP = 113, 114, 115
-# Volume keys are remapped to KEY_MACRO29 and KEY_MACRO30: above 255, so X11 can't
+# Volume keys are remapped to KEY_MACRO28, KEY_MACRO29 and KEY_MACRO30: above 255, so X11
-# carry them, and bound to nothing in the default keymap.
+# can't carry them, and bound to nothing in the default keymap.
-VOLUME_STANDIN = {KEY_VOLUMEUP: 0x2AC, KEY_VOLUMEDOWN: 0x2AD}
+VOLUME_STANDIN = {KEY_MUTE: 0x2AB, KEY_VOLUMEUP: 0x2AC, KEY_VOLUMEDOWN: 0x2AD}
 VOLUME_ORIGINAL = {v: k for k, v in VOLUME_STANDIN.items()}
 VOLUME_CODES = set(VOLUME_STANDIN) | set(VOLUME_ORIGINAL)
 BUS_USB, BUS_BLUETOOTH, BUS_VIRTUAL = 0x03, 0x05, 0x06
@@ -209,14 +211,16 @@ RULES_PATH = os.path.expanduser("~/.config/frametop-input.json")
 ACTIONS = ("left", "right", "middle", "back", "scroll_up", "scroll_down", "dashboard", "recenter",
           "pointer_toggle", "follow_toggle", "gaze_toggle", "gaze_precision", "gaze_drag", "gaze_left", "gaze_right",
           "gaze_quickcal", "sens_up", "sens_down", "layout_reset", "screens_toggle", "keyboard_toggle", "float_toggle",
-           "dock_all", "steam_menu", "pause_toggle", "key", "none")
+           "dock_all", "spin_next", "spin_prev", "steam_menu", "pause_toggle", "key", "none")
 # Gaze mode is a mouse feature: these never come from a controller button (docs/gaze-controllers.md).
 GAZE_ACTIONS = ("gaze_toggle", "gaze_precision", "gaze_drag", "gaze_left", "gaze_right", "gaze_quickcal")
 # Key combinations a rules file without "key_bindings" gets: a Meta tap opens Steam's menu, Meta+J
 # and Meta+K click at the gaze (free on the Frametop desktop, and apps don't use Meta),
-# Meta+Shift+F floats a window.
+# Meta+Shift+F floats a window, and Meta+Alt+Tab and Meta+Alt+Shift+Tab spin the panels around
 # you (ft-screens' lazy susan); not Meta+Tab, which is Cmd+Tab on a Mac reached through a remote
 # desktop like RustDesk.
 DEFAULT_KEY_BINDINGS = {"125": "steam_menu", "125+36": "gaze_left", "125+37": "gaze_right",
-                        "42+125+33": "float_toggle"}
+                        "42+125+33": "float_toggle", "56+125+15": "spin_next", "42+56+125+15": "spin_prev"}
 KEY_F24 = 194  # sent to the desktop with a Meta combination (see the top)
 # Key combinations ("key_bindings"): modifiers, each side's code folded into the left one's.
 MODIFIERS = {29: 29, 97: 29, 42: 42, 54: 42, 56: 56, 100: 56, 125: 125, 126: 125}
@@ -232,6 +236,9 @@ GAZED = "\0ft_gazed"
 FLOAT = "\0frametop_float"  # ft-floatd, floating windows in the Frametop desktop
 # Actions for ft-floatd ("float_toggle", "dock_all"): they don't need pointer mode.
 FLOAT_ACTIONS = {"float_toggle": b"float pointer", "dock_all": b"dock all"}
 # Actions for ft-screens: spin_next and spin_prev turn every panel in the room about your head,
 # so the next one to the right or left comes to the front. They don't need pointer mode either.
 SCREENS_ACTIONS = {"spin_next": b"spin next", "spin_prev": b"spin prev"}
 PROFILE = "profile:"  # "profile:NAME": switch to that profile (doesn't need pointer mode either)
 COMMAND = "command:"  # "command:CMD": run CMD (nor does this)
@@ -242,7 +249,7 @@ def known_action(a):
 def needs_pointer(a):
-    return a not in FLOAT_ACTIONS and a not in ("steam_menu", "pause_toggle") and not a.startswith((PROFILE, COMMAND))
+    return a not in FLOAT_ACTIONS and a not in SCREENS_ACTIONS and a not in ("steam_menu", "pause_toggle") and not a.startswith((PROFILE, COMMAND))
 def works_paused(a):
@@ -422,6 +429,10 @@ class Volume:
    def key(self, fd, code, value, now):
        if value == 1:
            if VOLUME_ORIGINAL.get(code, code) == KEY_MUTE:
                subprocess.Popen(["wpctl", "set-mute", "@DEFAULT_AUDIO_SINK@", "toggle"],
                                stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            else:
                self.held = (fd, code)
                self.step(code)
                self.next_at = now + self.DELAY
@@ -925,6 +936,13 @@ def main():
                except OSError:
                    pass  # the Frametop desktop isn't running
                log(action)
        elif action in SCREENS_ACTIONS:
            if value == 1:
                try:
                    screens_sock.sendto(SCREENS_ACTIONS[action], SCREENS)
                except OSError:
                    pass  # the Frametop desktop isn't running
                log(action)
        elif state["pointer"]:
            state["pointer"].action(action, value, now, source)
@@ -206,7 +206,7 @@ def check(label, got, want):
        failures.append(label)
-META, RMETA, SHIFT, CTRL, RCTRL, A, F, J, P = 125, 126, 42, 29, 97, 30, 33, 36, 25
+META, RMETA, SHIFT, CTRL, RCTRL, ALT, A, F, J, P, TAB = 125, 126, 42, 29, 97, 56, 30, 33, 36, 25, 15
 F24 = ["key 194 1", "key 194 0"]
@@ -265,6 +265,20 @@ def tests():
    key(META, 1); key(J, 1); key(J, 0); key(META, 0)
    check("resumed: Meta+J is a combination again", typed(), ["key 125 1"] + F24 + ["key 125 0"])
    use(None)  # the defaults: Meta+Alt+Tab and Meta+Alt+Shift+Tab spin the panels (ft-screens)
    key(META, 1); key(ALT, 1); key(TAB, 1); key(TAB, 0); key(ALT, 0); key(META, 0)
    got = typed()
    check("Meta+Alt+Tab (default): spin next", [m for m in got if m.startswith("spin")], ["spin next"])
    check("Meta+Alt+Tab: Tab isn't typed", [m for m in got if m.startswith("key 15 ")], [])
    key(META, 1); key(ALT, 1); key(SHIFT, 1); key(TAB, 1); key(TAB, 0); key(SHIFT, 0); key(ALT, 0); key(META, 0)
    check("Meta+Alt+Shift+Tab (default): spin prev", [m for m in typed() if m.startswith("spin")], ["spin prev"])
    pause("on")
    key(META, 1); key(ALT, 1); key(TAB, 1); key(TAB, 0); key(ALT, 0); key(META, 0)
    check("paused: Meta+Alt+Tab doesn't spin", [m for m in typed() if m.startswith("spin")], [])
    pause("off")
    check("spinning works without pointer mode", (relay.needs_pointer("spin_next"), relay.needs_pointer("spin_prev")),
          (False, False))
    check("an empty command isn't an action", relay.known_action("command:  "), False)
    check("steam_menu, pause_toggle and commands work without pointer mode",
          (relay.needs_pointer("steam_menu"), relay.needs_pointer("pause_toggle"), relay.needs_pointer("command:ls")),
@@ -0,0 +1,3 @@
 #!/bin/bash
 # Hide/Show Screens' own program (see ft-layout-reset).
 exec "$(dirname "$(readlink -f "$0")")/ft-layout" toggle "$@"
@@ -0,0 +1,4 @@
 #!/bin/bash
 # Reset Screen Layout's own program. Steam lists menu entries by program, so entries that
 # shared ft-layout (with different arguments) launched as one.
 exec "$(dirname "$(readlink -f "$0")")/ft-layout" apply "$@"
@@ -346,6 +346,20 @@ static void handle_vr_event(const struct ft_event *e, void *data) {
    if (e->screen < 0 || e->screen >= MAX_SCREENS || !s->screens[e->screen]) return;
    struct screen *sc = s->screens[e->screen];
    struct wlr_surface *surface = sc->toplevel->base->surface;
    if (e->type == FT_FRONT) {
        // A spin brought this panel to the front: typing goes to it, as after a click there,
        // and ft-floatd makes its window (or the top one on a screen) KWin's active window.
        wlr_seat_keyboard_notify_enter(s->seat, surface, NULL, 0, NULL);
        s->keys_clicked = true;
        char msg[32];
        snprintf(msg, sizeof msg, "front %d", e->screen + 1);
        struct sockaddr_un addr = {.sun_family = AF_UNIX};
        const char name[] = "frametop_float";
        memcpy(addr.sun_path + 1, name, sizeof name - 1);
        sendto(s->relay_fd, msg, strlen(msg), MSG_DONTWAIT, (struct sockaddr *)&addr,
               offsetof(struct sockaddr_un, sun_path) + 1 + sizeof name - 1);
        return;
    }
    const uint32_t t = now_ms();
    const double x = e->x / s->scale[e->screen], y = e->y / s->scale[e->screen];  // KWin's units
    switch (e->type) {
@@ -795,7 +809,9 @@ static bool setup_dmabuf(struct server *s) {
 int main(int argc, char **argv) {
    struct server s = {0};
-    s.controller_click.threshold = 8;
+    // About 0.9 degrees on a 3.4 m wide 3440-pixel screen 2 m away; 8 (the first default,
    // about 0.2 degrees) needed a very still hand to click (headset test 2026-10-03).
    s.controller_click.threshold = 32;
    for (int i = 0; i < MAX_SCREENS; ++i) s.scale[i] = 1;
    s.kb_screen = -1;
    s.rate[FT_FOCUSED] = 0, s.rate[FT_IN_VIEW] = 15, s.rate[FT_HIDDEN] = 1;
@@ -459,7 +459,21 @@ void Hide() {
 bool Shown() { return g_shown; }
 void SetLasers(bool on) {
-    if (Create()) vr::VROverlay()->SetOverlayFlag(g_overlay, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, on);
+    static vr::VROverlayHandle_t set = vr::k_ulOverlayHandleInvalid;  // the overlay `was` is for
    static bool was = false;
    if (!Create() || (set == g_overlay && was == on)) return;
    set = g_overlay, was = on;
    vr::VROverlay()->SetOverlayFlag(g_overlay, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, on);
 }
 bool Aimed(const vr::HmdMatrix34_t &laser) {
    if (!g_shown) return false;
    vr::VROverlayIntersectionParams_t in{};
    in.eOrigin = vr::TrackingUniverseStanding;
    in.vSource = {laser.m[0][3], laser.m[1][3], laser.m[2][3]};
    in.vDirection = {-laser.m[0][2], -laser.m[1][2], -laser.m[2][2]};
    vr::VROverlayIntersectionResults_t out{};
    return vr::VROverlay()->ComputeOverlayIntersection(g_overlay, &in, &out);
 }
 void Poll(void (*handle)(const Event &, void *), void *data) {
@@ -26,6 +26,8 @@ const vr::HmdMatrix34_t &Pose();
 void EndDragBy(uint32_t device);
 // Controllers' lasers work the panel with the dashboard closed, like the screens'.
 void SetLasers(bool on);
 // A laser (its pose, aiming along -z) points at the panel.
 bool Aimed(const vr::HmdMatrix34_t &laser);
 // The panel's input: key presses and releases, and Closed for its Close key.
 void Poll(void (*handle)(const Event &, void *), void *data);
 void Destroy();
@@ -12,9 +12,7 @@
 //   - a resize tab on the bottom right corner: drag it to set the width (the height
 //     follows the screen's resolution).
 //   - a reset button left of the bar: every screen back in its layout, around where you
-//     are now (`ft-layout apply`, like Meta+Shift+R). Where the screens leave the
+//     are now (`ft-layout apply`, like Meta+Shift+R).
 //     controllers to a VR game, aiming a controller at it turns SteamVR's laser mouse on for
 //     that button alone (UpdateResetLaser), so it can be clicked in a game.
 //   The controls are translucent, like SteamVR's own, and brighten under a laser. They
 //   are invisible until a laser (a controller's, or the 3D mouse's) lands on or passes very close to
 //   one of them (UpdateControls).
@@ -44,7 +42,10 @@
 //     default it's off while a game (a scene app) runs: the screens stay up over the game,
 //     the controllers stay in it, and the 3D mouse (its own laser mode) or the dashboard
 //     works the screens. Modes: always, outside_games (default), dashboard (never on its
-//     own; also for flatscreen games, which aren't scene apps).
+//     own; also for flatscreen games, which aren't scene apps). Where the mode leaves the
 //     controllers to the game, pointing a controller at a panel (a screen, a floating window
 //     and its popups, their controls, the keyboard) turns the laser on for it until you
 //     point away, like SteamVR's own floating windows (UpdateAim).
 //   - during a VR game the screens hide unless the dashboard is open (g_inGames, default),
 //     or stay visible over it; the hotkey still shows them.
 //   - paused ("pause on", from the input relay when Frametop pauses for a VR game,
@@ -189,8 +190,12 @@ Mat TipOffset(vr::TrackedDeviceIndex_t dev) {
    Tip tip{model, Identity(), false, now};
    vr::RenderModel_ControllerMode_State_t mode{};
    vr::RenderModel_ComponentState_t state{};
-    if (model[0] && vr::VRRenderModels()->GetComponentStateForDevicePath(model, vr::k_pch_Controller_Component_Tip,
+    // GetComponentState, not GetComponentStateForDevicePath: without an input source handle
-                                                                          vr::k_ulInvalidInputValueHandle, &mode, &state))
+    // the latter fails for every component while a VR game runs, and the rays came from the
    // pose, 40 degrees above the laser. The tip doesn't move with the buttons.
    vr::VRControllerState_t buttons{};
    if (model[0] && vr::VRRenderModels()->GetComponentState(model, vr::k_pch_Controller_Component_Tip, &buttons, &mode,
                                                            &state))
        tip.offset = state.mTrackingToComponentLocal, tip.found = true;
    cache[dev] = tip;
    return tip.offset;
@@ -237,7 +242,7 @@ constexpr double kRollSnap = 2.5;    // degrees from level where rolling snaps l
 constexpr double kRollStep = 5;      // degrees per scroll notch on the roll button
 constexpr float kChromeIdle = 0.55f; // the controls' opacity without a laser on them
 constexpr long kControlsLinger = 35; // ticks (~0.4 s) the controls stay after a laser leaves
-constexpr long kResetLinger = 45;    // ticks (~0.5 s) the reset button keeps the laser mouse on
+constexpr long kAimLinger = 25;      // ticks (~0.3 s) a panel keeps the laser on after the aim leaves it
 long g_tick = 0;                     // ft_vr_poll calls
 bool g_vr = false;                   // connected to SteamVR (ft-screens --no-vr runs without it)
 constexpr vr::TrackedDeviceIndex_t kNone = vr::k_unTrackedDeviceIndexInvalid;
@@ -275,8 +280,7 @@ struct Screen {
    float controls = 0;                       // the controls' fade, 0 (hidden) .. 1
    bool controlsUp = false;                  // the controls' overlays are shown
    long nearUntil = 0;                       // a laser was near the controls until this tick
-    long resetNearUntil = 0;                  // a hand controller aimed at the reset button until this tick
+    long aimUntil = 0;                        // a hand controller pointed at it until this tick (UpdateAim)
    bool resetLaser = false;                  // the reset button has MakeOverlaysInteractiveIfVisible
    vr::TrackedDeviceIndex_t pinTarget = kNone;  // moving: rides on this controller when let go
    vr::TrackedDeviceIndex_t onWrist = kNone;    // moving: the laser is in this controller's ring
    bool barLit = false;
@@ -910,26 +914,20 @@ void UpdateAttention() {
 // Controllers' lasers on the screens (see the top): the flag follows the mode and whether a
-// VR game runs.
+// VR game runs, and where the mode leaves the controllers to the game, whether one points at
 // the panel (UpdateAim).
 bool LasersByMode() { return g_lasers == Lasers::Always || (g_lasers == Lasers::OutsideGames && !g_gameRunning); }
 long g_keyboardAimUntil = 0;
 void UpdateLasers() {
-    const bool want = g_lasers == Lasers::Always || (g_lasers == Lasers::OutsideGames && !g_gameRunning);
+    const bool byMode = LasersByMode();
    for (auto &[i, s] : g_screens) {
        const bool want = byMode || (s.visible && g_tick < s.aimUntil);
        if (s.lasers == want) continue;
        s.lasers = want;
        vr::VROverlay()->SetOverlayFlag(s.overlay, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, want);
    }
-}
+    if (keyboard::Shown()) keyboard::SetLasers(byMode || g_tick < g_keyboardAimUntil);
 // The reset button in a VR game (or the dashboard mode), where the screens don't keep
 // SteamVR's laser mouse on: aiming a hand controller at it turns the laser mouse on for that
 // button alone, so the trigger clicks it, and the game gets the controllers back
 // kResetLinger ticks after the aim leaves it (a wider zone than the one that turns it on).
 void UpdateResetLaser(Screen &s) {
    const bool want = s.resetButton != vr::k_ulOverlayHandleInvalid && s.visible && !s.lasers &&
                      g_tick < s.resetNearUntil;
    if (want == s.resetLaser) return;
    s.resetLaser = want;
    vr::VROverlay()->SetOverlayFlag(s.resetButton, vr::VROverlayFlags_MakeOverlaysInteractiveIfVisible, want);
 }
 // The distance from a laser's line to a point ahead of it, or -1 when it's behind.
@@ -947,11 +945,10 @@ double RayDistance(const Mat &d, const Mat &c) {
 // kControlsLinger ticks after it leaves, and while in use.
 void UpdateControls() {
    std::vector<Mat> lasers;
    std::vector<bool> hands;  // the laser is a hand controller's (not the 3D mouse's)
    for (vr::TrackedDeviceIndex_t i = 1; i < vr::k_unMaxTrackedDeviceCount; ++i) {
        Mat d;
        if (vr::VRSystem()->GetTrackedDeviceClass(i) == vr::TrackedDeviceClass_Controller && LaserPose(i, &d))
-            lasers.push_back(d), hands.push_back(IsHandController(i));
+            lasers.push_back(d);
    }
    for (auto &[i, s] : g_screens) {
        Mat p;
@@ -977,16 +974,7 @@ void UpdateControls() {
                    break;
                }
            }
            if (s.resetButton != vr::k_ulOverlayHandleInvalid && !s.lasers) {
                const Mat c = Mul(p, offsets[6]);
                const double aim = s.grip * (s.resetLaser ? 2.0 : 0.9);
                for (size_t k = 0; k < lasers.size(); ++k) {
                    const double r = RayDistance(lasers[k], c);
                    if (hands[k] && r >= 0 && r <= aim) s.resetNearUntil = g_tick + kResetLinger;
        }
            }
        }
        UpdateResetLaser(s);
        const bool inUse = s.drag != Drag::None || std::any_of(std::begin(s.hover), std::end(s.hover), [](bool h) { return h; });
        const bool want = s.visible && (inUse || g_tick < s.nearUntil);
        // The controls stay shown while their screen is, just fully transparent when not
@@ -1020,19 +1008,21 @@ void SendFloat(const std::string &msg) {
        std::printf("to ft-floatd: %s\n", msg.c_str());
 }
-// A new panel: the pointer helper reads SteamVR's list of panels only every 20 s, so it's told
+// To the pointer helper (@ft_pointer_helper), from an unbound socket.
-// at once ("overlay <key>"), or the mouse couldn't click a menu until then.
+void SendPointer(const std::string &msg) {
 void AnnounceOverlay(const char *key) {
    static const int fd = socket(AF_UNIX, SOCK_DGRAM | SOCK_CLOEXEC | SOCK_NONBLOCK, 0);
    sockaddr_un addr{};
    addr.sun_family = AF_UNIX;
    const char name[] = "ft_pointer_helper";
    std::memcpy(addr.sun_path + 1, name, sizeof name - 1);
    const std::string msg = std::string("overlay ") + key;
    sendto(fd, msg.data(), msg.size(), MSG_DONTWAIT, reinterpret_cast<sockaddr *>(&addr),
           socklen_t(offsetof(sockaddr_un, sun_path) + 1 + sizeof name - 1));
 }
 // A new panel: the pointer helper reads SteamVR's list of panels only every 20 s, so it's told
 // at once ("overlay <key>"), or the mouse couldn't click a menu until then.
 void AnnounceOverlay(const char *key) { SendPointer(std::string("overlay ") + key); }
 // Where a device's ray meets the screen's plane, in the screen's x (right) and y (up),
 // metres from its centre.
 bool RayOnPlane(const Mat &p, const Mat &d, double *x, double *y) {
@@ -1419,6 +1409,7 @@ struct Press {
    double x = 0, y = 0;                      // ...and where on it, in buffer pixels
    double distance = 1;                      // from the laser's start to the last panel it met
    long upAt = -1;                           // the pointer helper saw left come up: release it at this tick
    int64_t idleSince = -1;                   // the pressing controller has held nothing since (ms, ReleaseStuck)
 };
 Press g_press;
 vr::VROverlayHandle_t g_catcher = vr::k_ulOverlayHandleInvalid;
@@ -1455,6 +1446,47 @@ void ReleaseAway(uint32_t button, void (*handle)(const struct ft_event *, void *
    handle(&e, data);
 }
 // Whether a hand controller holds anything (a button down): 1 yes, 0 no, -1 unknown. SteamVR
 // answers overlay apps only while a VR game runs (checked 2026-10-04); outside games it can't
 // say. The Frame controller's axes have no types, so the buttons are all there is.
 int ControllerHolds(vr::TrackedDeviceIndex_t dev) {
    vr::VRControllerState_t st{};
    if (!vr::VRSystem()->GetControllerState(dev, &st, sizeof st)) return -1;
    return st.ulButtonPressed ? 1 : 0;
 }
 // Releases SteamVR never sends. Pausing, or hiding the screen a button went down on, takes the
 // laser off it mid-click (the pause gesture's second thumbstick click does that), and SteamVR's
 // laser mouse then forgets the button: no release comes, the catcher stayed up, and the game
 // never got its controllers back (2026-10-04). So a held button is released here when it has
 // no visible screen to come up on, or when its hand controller has held nothing for kStuckMs
 // (only known during VR games, where the lost release took the game's controllers).
 // The pointer helper's virtual controller has its own word for that ("up").
 constexpr int64_t kStuckMs = 1000;
 void ReleaseStuck(void (*handle)(const struct ft_event *, void *), void *data) {
    if (!g_press.buttons) {
        g_press.idleSince = -1;
        return;
    }
    const char *why = nullptr;
    const auto it = g_screens.find(g_press.screen);
    if (g_paused) why = "paused";
    else if (g_press.screen >= 0 && (it == g_screens.end() || !it->second.visible)) why = "its screen hid";
    else if (IsHandController(g_press.device)) {
        const int64_t now = NowMs();
        if (ControllerHolds(g_press.device) != 0) g_press.idleSince = -1;
        else if (g_press.idleSince < 0) g_press.idleSince = now;
        else if (now - g_press.idleSince >= kStuckMs) why = "the controller holds nothing";
    }
    if (!why) return;
    std::printf("a held button can't come up on a screen (%s): released\n", why);
    const vr::TrackedDeviceIndex_t dev = g_press.device;
    for (uint32_t b = 0; b < 32; ++b)
        if (g_press.buttons & (1u << b)) ReleaseAway(BTN_LEFT + b, handle, data);
    g_press.buttons = 0, g_press.upAt = -1, g_press.idleSince = -1;
    EndDragsBy(dev);
 }
 void ShowCatcher(bool on) {
    if (on == g_catcherShown || g_catcher == vr::k_ulOverlayHandleInvalid) return;
    g_catcherShown = on;
@@ -1500,6 +1532,137 @@ Screen *Find(int one_based) {
    return it == g_screens.end() ? nullptr : &it->second;
 }
 // ---------------------------------------------------------------- the lazy susan
 // "spin next|prev|<degrees>": the panels in the room (screens and floating windows, not
 // pinned ones) turn together about a vertical axis through your head, so the next panel to
 // your right (next) or left (prev) glides to straight ahead, or the ring turns by that many
 // degrees (positive turns it left, like next). Their arrangement stays as it is: the room
 // turns instead of you. A spin that arrives during one adds to it, from where the panels are
 // headed, so quick taps carry on smoothly. Grabbing a panel, or a command that places it,
 // takes it out of the spin where it is. The 3D mouse's pointer goes to straight ahead.
 constexpr double kSpinSeconds = 0.3;  // how long a spin takes
 constexpr double kSpinAhead = 8;      // degrees: a panel this near straight ahead is the current one
 constexpr double kSpinFocus = 30;     // degrees: when a spin settles, the panel this near ahead gets typing
 struct Spin {
    bool on = false;
    double cx = 0, cz = 0;    // the axis
    double from = 0, to = 0;  // radians, turned from the poses in base (positive: to the left)
    Clock::time_point start;
    std::map<int, Mat> base;  // index -> its pose before the spin
    int front = -1;           // settled: this panel came to the front (ft_vr_poll reports it)
 } g_spin;
 // p turned a radians about the vertical axis through (cx, cz); positive turns it to the left.
 Mat Turned(const Mat &p, double a, double cx, double cz) {
    const double c = std::cos(a), s = std::sin(a);
    Mat r = Identity();
    r.m[0][0] = float(c), r.m[0][2] = float(s);
    r.m[2][0] = float(-s), r.m[2][2] = float(c);
    r.m[0][3] = float(cx - c * cx - s * cz);
    r.m[2][3] = float(cz + s * cx - c * cz);
    return Mul(r, p);
 }
 bool Spinnable(const Screen &s) { return s.pinned == kNone && (!s.floating || s.floatOn) && s.drag == Drag::None; }
 double SpinNow() {
    if (!g_spin.on) return g_spin.to;
    const double t = std::min(1.0, std::chrono::duration<double>(Clock::now() - g_spin.start).count() / kSpinSeconds);
    return g_spin.from + (g_spin.to - g_spin.from) * t * t * (3 - 2 * t);
 }
 void UpdateSpin() {
    if (!g_spin.on) return;
    const double a = SpinNow();
    const bool done = Clock::now() - g_spin.start >= std::chrono::duration<double>(kSpinSeconds);
    for (auto it = g_spin.base.begin(); it != g_spin.base.end();) {
        auto s = g_screens.find(it->first);
        if (s == g_screens.end() || !Spinnable(s->second)) {
            it = g_spin.base.erase(it);  // grabbed, pinned, or gone: it stays where it is now
            continue;
        }
        SetAbsolute(s->second, Turned(it->second, a, g_spin.cx, g_spin.cz));
        ++it;
    }
    if (done) {
        // The panel now nearest straight ahead (of where you face) gets typing and the active window.
        Mat head;
        double nearest = kSpinFocus;
        if (DevicePose(vr::k_unTrackedDeviceIndex_Hmd, &head)) {
            for (const auto &[i, p] : g_spin.base) {
                const auto it = g_screens.find(i);
                Mat q;
                if (it == g_screens.end() || !it->second.visible || !ScreenPose(it->second, &q)) continue;
                double f[3] = {-head.m[0][2], 0, -head.m[2][2]};
                double d[3] = {q.m[0][3] - head.m[0][3], 0, q.m[2][3] - head.m[2][3]};
                const double fl = std::sqrt(Dot3(f, f)), dl = std::sqrt(Dot3(d, d));
                if (fl < 1e-6 || dl < 1e-6) continue;
                const double a = std::acos(std::clamp(Dot3(f, d) / (fl * dl), -1.0, 1.0)) * 180 / M_PI;
                if (a < nearest) nearest = a, g_spin.front = i;
            }
        }
        g_spin.on = false;
        g_spin.base.clear();
        ArrangeDesktopSoon();  // KWin's outputs follow where the screens are now
    }
 }
 void SpinCommand(const char *arg, char *reply, int size) {
    Mat head;
    if (!DevicePose(vr::k_unTrackedDeviceIndex_Hmd, &head))
        return (void)std::snprintf(reply, size, "error no head pose (headset off?)");
    if (g_spin.on) {
        g_spin.from = SpinNow();  // carry on from where the panels are now
    } else {
        g_spin.base.clear();
        for (auto &[i, s] : g_screens) {
            Mat p;
            if (Spinnable(s) && ScreenPose(s, &p)) g_spin.base[i] = p;
        }
        g_spin.cx = head.m[0][3], g_spin.cz = head.m[2][3];
        g_spin.from = g_spin.to = 0;
    }
    if (g_spin.base.empty()) return (void)std::snprintf(reply, size, "error nothing to spin");
    double turn;  // degrees, positive to the left
    const bool next = !std::strcmp(arg, "next");
    if (next || !std::strcmp(arg, "prev")) {
        // Each visible panel's bearing from where you face, to the right positive, as it will
        // be when the spin so far ends; the nearest one past straight ahead comes to the front.
        double fx = -head.m[0][2], fz = -head.m[2][2];
        const double n = std::sqrt(fx * fx + fz * fz) + 1e-9;
        fx /= n, fz /= n;
        const double rx = -fz, rz = fx;
        double best = 0;
        bool found = false;
        for (const auto &[i, p] : g_spin.base) {
            const auto s = g_screens.find(i);
            if (s == g_screens.end() || !s->second.visible) continue;
            const Mat q = Turned(p, g_spin.to, g_spin.cx, g_spin.cz);
            const double dx = q.m[0][3] - head.m[0][3], dz = q.m[2][3] - head.m[2][3];
            double a = std::atan2(dx * rx + dz * rz, dx * fx + dz * fz) * 180 / M_PI;
            if (!next) a = -a;
            if (a <= kSpinAhead) a += 360;
            if (!found || a < best) best = a, found = true;
        }
        if (!found || best >= 360 - kSpinAhead) {
            if (!g_spin.on) g_spin.base.clear();
            return (void)std::snprintf(reply, size, "ok 0 (no other panel)");
        }
        if (best > 180) best -= 360;  // the short way round
        turn = next ? best : -best;
    } else {
        char *end;
        turn = std::strtod(arg, &end);
        if (end == arg || *end) return (void)std::snprintf(reply, size, "error spin next|prev|<degrees>");
    }
    g_spin.to += turn * M_PI / 180;
    g_spin.start = Clock::now();
    g_spin.on = true;
    SendPointer("recenter");  // the 3D mouse's pointer stays in front of you, on what comes there
    std::snprintf(reply, size, "ok %.1f", turn);
 }
 uint32_t LinuxButton(uint32_t vrButton) {
    switch (vrButton) {
        case vr::VRMouseButton_Right: return BTN_RIGHT;
@@ -1514,6 +1677,81 @@ void ReleaseAwayBy(vr::TrackedDeviceIndex_t dev, uint32_t vrButton, void (*handl
    if (g_press.buttons && dev == g_press.device) ReleaseAway(LinuxButton(vrButton), handle, data);
 }
 // Where a laser meets a panel's surface, in the panel's u (metres along it from the centre,
 // along the arc when curved) and v (up). OpenVR curves a screen into a cylinder toward its
 // front, centred `curve` metres in front of it (see OnSurface).
 bool RayOnSurface(const Screen &s, const Mat &p, const Mat &laser, double *u, double *v) {
    const Mat inv = Inverse(p);
    const double o[3] = {inv.m[0][0] * laser.m[0][3] + inv.m[0][1] * laser.m[1][3] + inv.m[0][2] * laser.m[2][3] + inv.m[0][3],
                         inv.m[1][0] * laser.m[0][3] + inv.m[1][1] * laser.m[1][3] + inv.m[1][2] * laser.m[2][3] + inv.m[1][3],
                         inv.m[2][0] * laser.m[0][3] + inv.m[2][1] * laser.m[1][3] + inv.m[2][2] * laser.m[2][3] + inv.m[2][3]};
    double d[3];
    for (int i = 0; i < 3; ++i) d[i] = -(inv.m[i][0] * laser.m[0][2] + inv.m[i][1] * laser.m[1][2] + inv.m[i][2] * laser.m[2][2]);
    if (s.curve <= 0) {
        if (std::fabs(d[2]) < 1e-6) return false;
        const double t = -o[2] / d[2];
        if (t <= 0) return false;
        *u = o[0] + d[0] * t, *v = o[1] + d[1] * t;
        return true;
    }
    // x^2 + (z - r)^2 = r^2, on the screen's side of the axis (z < r).
    const double r = s.curve, oz = o[2] - r;
    const double a = d[0] * d[0] + d[2] * d[2], b = 2 * (o[0] * d[0] + oz * d[2]), c = o[0] * o[0] + oz * oz - r * r;
    const double disc = b * b - 4 * a * c;
    if (a < 1e-9 || disc < 0) return false;
    for (double t : {(-b - std::sqrt(disc)) / (2 * a), (-b + std::sqrt(disc)) / (2 * a)}) {
        const double x = o[0] + d[0] * t, z = oz + d[2] * t;
        if (t <= 0 || z >= 0) continue;
        *u = r * std::atan2(x, -z), *v = o[1] + d[1] * t;
        return true;
    }
    return false;
 }
 // Where the mode leaves the controllers to a VR game (see the top): a hand controller
 // pointing at a panel, its controls, or a floating window's popups keeps that panel's laser
 // on (UpdateLasers) until kAimLinger ticks after it points away, like SteamVR's own floating
 // windows. Leaving takes a wider margin than arriving, and a drag or a held button keeps it
 // on. The keyboard is one overlay, so SteamVR's own intersection test does there.
 void UpdateAim() {
    if (LasersByMode()) return;
    std::vector<Mat> lasers;
    for (vr::TrackedDeviceIndex_t i = 1; i < vr::k_unMaxTrackedDeviceCount; ++i) {
        Mat d;
        if (IsHandController(i) && LaserPose(i, &d)) lasers.push_back(d);
    }
    for (auto &[index, s] : g_screens) {
        Mat p;
        if (!s.visible || !ScreenPose(s, &p)) continue;
        if (s.drag != Drag::None || (g_press.buttons && g_press.screen == index)) {
            s.aimUntil = g_tick + kAimLinger;
            continue;
        }
        const double m = s.grip * (g_tick < s.aimUntil ? 2.0 : 0.25), h = s.heightMetres();
        // The panel and its controls: the bar row under it, the resize tab off its corner.
        const double halfW = std::max(s.metres / 2 + s.grip, s.chrome / 2 + s.chrome * 0.12 + s.grip * 2) + m;
        const double top = h / 2 + m, bottom = std::min(BarY(s) - s.grip, -(h / 2 + s.grip)) - m;
        for (const Mat &l : lasers) {
            double u, v;
            if (!RayOnSurface(s, p, l, &u, &v)) continue;
            bool on = std::fabs(u) <= halfW && v <= top && v >= bottom;
            for (const auto &[k, sub] : s.subs) {
                if (on || s.cropW <= 0) break;
                const double su = (sub.x + sub.w / 2.0 - (s.cropX + s.cropW / 2.0)) * s.mpp;
                const double sv = -(sub.y + sub.h / 2.0 - (s.cropY + s.cropH / 2.0)) * s.mpp;
                on = std::fabs(u - su) <= sub.w * s.mpp / 2 + m && std::fabs(v - sv) <= sub.h * s.mpp / 2 + m;
            }
            if (on) {
                s.aimUntil = g_tick + kAimLinger;
                break;
            }
        }
    }
    if (keyboard::Shown())
        for (const Mat &l : lasers)
            if (keyboard::Aimed(l)) g_keyboardAimUntil = g_tick + kAimLinger;
 }
 const char *LasersName() {
    switch (g_lasers) {
        case Lasers::Always: return "always";
@@ -2036,6 +2274,7 @@ void ft_vr_poll(void (*handle)(const struct ft_event *, void *), void *data) {
        if (ev.eventType == vr::VREvent_MouseButtonUp)
            ReleaseAwayBy(ev.trackedDeviceIndex, ev.data.mouse.button, handle, data);
    if (g_press.upAt >= 0 && g_tick >= g_press.upAt) ReleaseAway(BTN_LEFT, handle, data);
    ReleaseStuck(handle, data);
    RefreshChrome();
    while (vr::VRSystem()->PollNextEvent(&ev, sizeof ev)) {
        if (ev.eventType == vr::VREvent_Quit) {
@@ -2071,10 +2310,19 @@ void ft_vr_poll(void (*handle)(const struct ft_event *, void *), void *data) {
        handle(&e, data);
    }
    ++g_tick;
    UpdateSpin();
    if (g_spin.front >= 0) {
        ft_event e{};
        e.type = FT_FRONT;
        e.screen = g_spin.front;
        g_spin.front = -1;
        handle(&e, data);
    }
    UpdateGame();
    UpdateArrange();
    UpdateVisibility();
    UpdateAttention();
    UpdateAim();
    UpdateLasers();
    UpdateControls();
    UpdateGuides();
@@ -2101,7 +2349,7 @@ bool ft_vr_keyboard_show(int index) {
    const double fx = -head.m[0][2], fz = -head.m[2][2], n = std::sqrt(fx * fx + fz * fz) + 1e-9;
    const double at[3] = {head.m[0][3] + fx / n * kKeyboardAhead, head.m[1][3] - kKeyboardBelow,
                          head.m[2][3] + fz / n * kKeyboardAhead};
-    keyboard::SetLasers(g_lasers == Lasers::Always || (g_lasers == Lasers::OutsideGames && !g_gameRunning));
+    keyboard::SetLasers(LasersByMode());
    g_steamInFront = SteamInFront();
    if (g_steamInFront) {
        g_asidePose = FacingPose(at, head);
@@ -2146,6 +2394,8 @@ void ft_vr_keyboard_hide(void) {
 //                             ~100 ms (it landed on something else), KWin gets it anyway
 //   state         -> "ok <mode> <manual 0|1> <wrist deg> <gesture hand> <gesture deg>
 //                     <controllers> <game running 0|1> <ingames>"
 //   spin next|prev|<degrees>  turn every panel in the room about your head (see the lazy
 //                             susan) -> "ok <degrees turned>"
 //   cutouts on|off|state      hand cutouts (see handcut.h) -> "ok <on|off> <ready|idle|unavailable>
 //                             <last composite ms> ms, predict <on|off> lead <ms> ms"
 //   cutouts predict on|off    move the hands ahead along their velocity (on by default)
@@ -2183,6 +2433,7 @@ void ft_vr_command(const char *cmd, char *reply, int size) {
        Screen *s = Find(n);
        if (!s) return (void)std::snprintf(reply, size, "error no screen %d", n);
        EndDrag(*s);
        g_spin.base.erase(n - 1);
        SetAbsolute(*s, PanelPose(x, y, z, yaw, pitch, roll));
        std::snprintf(reply, size, "ok");
    } else if (std::sscanf(cmd, "width %d %lf", &n, &w) == 2) {
@@ -2349,6 +2600,7 @@ void ft_vr_command(const char *cmd, char *reply, int size) {
        Mat m{};
        for (int k = 0; k < 12; ++k) m.m[k / 4][k % 4] = r[k];
        EndDrag(*s);
        g_spin.base.erase(n - 1);
        SetAbsolute(*s, m);
        std::snprintf(reply, size, "ok");
    } else if (int k0; std::sscanf(cmd, "sub %d %d %d %d %d %d", &n, &k0, &x0, &y0, &w0, &h0) == 6 ||
@@ -2376,6 +2628,8 @@ void ft_vr_command(const char *cmd, char *reply, int size) {
        if ((g_press.buttons & ButtonBit(BTN_LEFT)) && g_press.device != kNone && !IsHandController(g_press.device))
            g_press.upAt = g_tick + 9;
        std::snprintf(reply, size, "ok");
    } else if (std::sscanf(cmd, "spin %15s", word) == 1) {
        SpinCommand(word, reply, size);
    } else if (std::strncmp(cmd, "state", 5) == 0) {
        std::snprintf(reply, size, "ok %s %d %.0f %s %.0f %s %d %s", ModeName(), g_manual ? 1 : 0, g_wristAngle,
                      g_gestureHand.c_str(), g_gestureAngle, LasersName(), g_gameRunning ? 1 : 0,
@@ -17,7 +17,8 @@ struct ft_dmabuf {
    int fd[4];
 };
-enum ft_event_type { FT_MOTION, FT_BUTTON, FT_SCROLL, FT_LEAVE, FT_QUIT, FT_KEY, FT_KEYBOARD_CLOSED };
+// FT_FRONT: a spin (the lazy susan) brought panel `screen` to straight ahead: typing goes there.
 enum ft_event_type { FT_MOTION, FT_BUTTON, FT_SCROLL, FT_LEAVE, FT_QUIT, FT_KEY, FT_KEYBOARD_CLOSED, FT_FRONT };
 struct ft_event {
    enum ft_event_type type;
@@ -36,6 +36,10 @@ check "distrobox" on_frame 'test -x ~/.local/bin/distrobox && ~/.local/bin/distr
 check "container $FRAME_BOX" on_frame "podman ps -a --filter name=^$FRAME_BOX\$ --format '{{.Image}} {{.Status}}' | grep ."
 check "repo on the Frame" on_frame 'pwd'
 check "free space in ~" on_frame "df -h ~ | awk 'NR==2{print \$4\" free\"}'"
 # A taskbar saved on a screen the desktop doesn't have is hidden; the desktop's next start
 # moves it to the first screen (session/fix-panels.py).
 check "taskbar on a screen" on_frame 'set -o pipefail; [ -f session/fix-panels.py ] || { echo "not checked (older checkout)"; exit 0; }
  python3 session/fix-panels.py --check | paste -sd ";" | sed "s/;/; /g"'
 echo "what Frametop needs from SteamOS:"
 if [ "$FRAME_LOCAL" = 1 ]; then
@@ -42,6 +42,25 @@ for i, s in enumerate(d.get("screens", []), 1):
 print("visibility:", d.get("visibility"))
 PY
 section "Plasma panels and outputs"
 python3 "$repo/session/fix-panels.py" --check 2>&1 || true
 python3 - "$repo" <<'PY' 2>&1 || true
 import json, subprocess, sys
 sys.path.insert(0, sys.argv[1] + "/layout")
 import ft_layout
 env = ft_layout.nested_env()
 if not env:
    sys.exit(print("desktop not running: no live outputs or panels"))
 outs = json.loads(subprocess.run(["kscreen-doctor", "-j"], capture_output=True, text=True, env=env, timeout=10).stdout or "{}")
 for o in outs.get("outputs", []):
    size = o.get("size") or {}
    print(f"output {o.get('name')}: enabled={o.get('enabled')} priority={o.get('priority')} {size.get('width')}x{size.get('height')}")
 js = "print(JSON.stringify(panels().map(p => ({id: p.id, screen: p.screen, location: p.location}))))"
 r = subprocess.run(["qdbus6", "org.kde.plasmashell", "/PlasmaShell", "org.kde.PlasmaShell.evaluateScript", js],
                   capture_output=True, text=True, env=env, timeout=10)
 print("live panels:", (r.stdout or r.stderr).strip())
 PY
 section "Input relay (last 60 lines)"
 journalctl --user -u frametop-input-relay -n 60 --no-pager -o short 2>/dev/null
 section "Pointer helper (last 60 lines)"
@@ -0,0 +1,143 @@
 #!/usr/bin/env python3
 """Bring back a taskbar that Plasma saved against a screen this desktop doesn't have.
 Plasma 6.2.5 ties each panel to a screen number (lastScreen in its containment), and the
 numbers rank the enabled outputs by priority: 0 is the primary screen. A panel whose
 number is past the screen count gets no view and stays hidden; Plasma never moves it,
 even on a later start (sanitizeScreenLayout() only remaps a panel whose number has no
 desktop, and the Frametop desktop keeps a desktop for every spare output it has seen).
 So a taskbar saved on a spare output (issue #18), or on a screen that a smaller layout
 dropped, was lost until the config was deleted.
 The session runs this before Plasma starts, so nothing races Plasma for the file. Each
 panel numbered at or past the screen count moves to screen 0, with its system tray's
 containment, and keeps its widgets and settings. A panel is left where it is when screen
 0 already has a panel on that edge: it comes back by itself if the screens do. The file
 is backed up once per repair (<file>.ft-bak), and the changes go through kwriteconfig6.
  fix-panels.py [--screens N] [--file APPLETSRC] [--check]
    --screens  the desktop's screen count (default: the configured layout's)
    --file     default: $XDG_CONFIG_HOME/plasma-org.kde.plasma.desktop-appletsrc, with
               XDG_CONFIG_HOME defaulting to the Frametop desktop's ~/.config/frametop
    --check    change nothing; list the panels, and exit 1 if one is lost
 """
 import argparse
 import os
 import re
 import shutil
 import subprocess
 import sys
 EDGES = {3: "top", 4: "bottom", 5: "left", 6: "right"}  # Plasma::Types::Location
 SYSTRAY = "org.kde.plasma.private.systemtray"
 GROUP = re.compile(r"\[([^\]]*)\]")
 def parse(text):
    """KConfig text -> {(group, subgroup, ...): {key: value}}."""
    groups, cur = {}, None
    for line in text.splitlines():
        line = line.strip()
        if line.startswith("["):
            cur = tuple(GROUP.findall(line))
            groups.setdefault(cur, {})
        elif cur is not None and "=" in line and not line.startswith("#"):
            k, v = line.split("=", 1)
            groups[cur][re.sub(r"\[\$.*\]$", "", k.strip())] = v.strip()
    return groups
 def number(v, default=-1):
    try:
        return int(v)
    except (TypeError, ValueError):
        return default
 def panels(groups):
    """The panels, by containment id: location, lastScreen, and the ids of their system
    trays' own containments (which sit on the same edge and screen as the panel)."""
    trays, found = {}, {}
    for g, keys in groups.items():
        if len(g) == 5 and g[0] == "Containments" and g[2] == "Applets" and g[4] == "Configuration":
            tray = keys.get("SystrayContainmentId")
            if tray:
                trays.setdefault(g[1], []).append(tray)
    owned = {t for ts in trays.values() for t in ts}
    for g, keys in groups.items():
        if len(g) != 2 or g[0] != "Containments" or number(g[1]) <= 0 or g[1] in owned:
            continue
        loc = number(keys.get("location"), 0)
        if loc in EDGES and keys.get("plugin") != SYSTRAY:
            found[g[1]] = {"location": loc, "screen": number(keys.get("lastScreen")),
                           "plugin": keys.get("plugin", "?"), "trays": trays.get(g[1], [])}
    return dict(sorted(found.items(), key=lambda kv: number(kv[0])))
 def plan(groups, screens):
    """(moves, kept): moves are (panel id, from screen, containment ids to put on screen 0);
    kept are (panel id, from screen, why) for lost panels left alone."""
    found = panels(groups)
    taken = {(p["screen"], p["location"]) for p in found.values() if 0 <= p["screen"] < screens}
    moves, kept = [], []
    for pid, p in found.items():
        if p["screen"] < screens:
            continue  # on a screen this desktop has (Plasma puts -1 on the first one itself)
        if (0, p["location"]) in taken:
            kept.append((pid, p["screen"], f"the first screen already has a {EDGES[p['location']]} panel"))
            continue
        taken.add((0, p["location"]))
        moves.append((pid, p["screen"], [pid, *p["trays"]]))
    return moves, kept
 def default_screens():
    sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "layout"))
    import ft_layout
    return ft_layout.screen_count()
 def main(argv):
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("--screens", type=int)
    ap.add_argument("--file")
    ap.add_argument("--check", action="store_true")
    a = ap.parse_args(argv)
    config = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config/frametop")
    path = a.file or os.path.join(config, "plasma-org.kde.plasma.desktop-appletsrc")
    screens = a.screens if a.screens else default_screens()
    try:
        with open(path) as f:
            groups = parse(f.read())
    except FileNotFoundError:
        if a.check:
            print("no Plasma config yet (Plasma makes the default taskbar)")
        return 0
    moves, kept = plan(groups, screens)
    if a.check:
        found = panels(groups)
        for pid, p in found.items():
            lost = " (lost: no such screen)" if p["screen"] >= screens else ""
            print(f"panel {pid}: screen {p['screen']}, {EDGES[p['location']]}{lost}")
        if not found:
            print("no panels")
        print(f"{screens} screen(s)")
        return 1 if moves or kept else 0
    if moves:
        shutil.copy2(path, path + ".ft-bak")
    for pid, was, ids in moves:
        for cid in ids:
            subprocess.run(["kwriteconfig6", "--file", os.path.abspath(path), "--group", "Containments",
                            "--group", cid, "--key", "lastScreen", "0"], check=True)
        print(f"frametop: panel {pid} was saved on screen {was}, which this desktop doesn't have "
              f"({screens} screen(s)); moved it to the first screen (backup: {path}.ft-bak)", file=sys.stderr)
    for pid, was, why in kept:
        print(f"frametop: panel {pid} is saved on screen {was}, which this desktop doesn't have; "
              f"left there: {why}", file=sys.stderr)
    return 0
 if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
@@ -272,4 +272,9 @@ fi
 # with both, apps would open twice.
 kwriteconfig6 --file "$XDG_CONFIG_HOME/ksmserverrc" --group General --key loginMode emptySession
 # Plasma keeps a panel on a screen number, and never moves one whose screen this desktop
 # doesn't have, like a spare output or a screen a smaller layout dropped. Put such a panel
 # back on the first (primary) screen before Plasma reads the file (session/fix-panels.py).
 python3 "$here/fix-panels.py" --screens "$screens" || true
 dbus-run-session startplasma-wayland
@@ -0,0 +1,162 @@
 #!/usr/bin/env python3
 """Tests for session/fix-panels.py: issue #18's config (the taskbar saved on spare output 8
 of a 3-screen desktop), panels that are fine, an edge that's taken, and a real run of
 kwriteconfig6 on a copy. Nothing here touches the running desktop or its config.
  python3 session/tests/test_fix_panels.py
 """
 import importlib.util
 import os
 import subprocess
 import sys
 import tempfile
 import unittest
 HERE = os.path.dirname(os.path.realpath(__file__))
 SCRIPT = os.path.join(HERE, "..", "fix-panels.py")
 spec = importlib.util.spec_from_file_location("fix_panels", SCRIPT)
 fp = importlib.util.module_from_spec(spec)
 spec.loader.exec_module(fp)
 def desktop(cid, screen):
    return f"""[Containments][{cid}]
 activityId=7e1d1a3c-0000-4000-8000-000000000000
 formfactor=0
 immutability=1
 lastScreen={screen}
 location=0
 plugin=org.kde.plasma.folder
 wallpaperplugin=org.kde.image
 """
 def panel(cid, screen, location=4, tray=None):
    text = f"""[Containments][{cid}]
 activityId=
 formfactor=2
 immutability=1
 lastScreen={screen}
 location={location}
 plugin=org.kde.panel
 wallpaperplugin=org.kde.image
 [Containments][{cid}][Applets][{cid}1]
 immutability=1
 plugin=org.kde.plasma.kickoff
 """
    if tray:
        text += f"""
 [Containments][{cid}][Applets][{cid}2]
 immutability=1
 plugin=org.kde.plasma.systemtray
 [Containments][{cid}][Applets][{cid}2][Configuration]
 PreloadWeight=90
 SystrayContainmentId={tray}
 [Containments][{tray}]
 activityId=
 formfactor=2
 immutability=1
 lastScreen={screen}
 location={location}
 plugin=org.kde.plasma.private.systemtray
 popupHeight=432
 """
    return text
 ISSUE_18 = "\n".join([desktop(1, 0), desktop(18, 1), desktop(19, 2)] + [desktop(20 + i, 3 + i) for i in range(8)]
                     + [panel(10, 8, tray=11), "[ScreenMapping]\nitemsOnDisabledScreens=\n"])
 class Plan(unittest.TestCase):
    def test_issue_18(self):
        moves, kept = fp.plan(fp.parse(ISSUE_18), 3)
        self.assertEqual(moves, [("10", 8, ["10", "11"])])
        self.assertEqual(kept, [])
    def test_panel_on_a_screen_stays(self):
        for screen in (0, 2, -1):
            moves, kept = fp.plan(fp.parse(desktop(1, 0) + panel(2, screen, tray=8)), 3)
            self.assertEqual((moves, kept), ([], []), screen)
    def test_tray_is_not_a_panel(self):
        found = fp.panels(fp.parse(panel(2, 0, tray=8)))
        self.assertEqual(list(found), ["2"])
        self.assertEqual(found["2"]["trays"], ["8"])
    def test_desktops_never_move(self):
        moves, _ = fp.plan(fp.parse(ISSUE_18), 1)
        self.assertEqual([m[0] for m in moves], ["10"])
    def test_edge_taken_on_first_screen(self):
        text = panel(2, 0, tray=8) + panel(10, 8, tray=11)
        moves, kept = fp.plan(fp.parse(text), 3)
        self.assertEqual(moves, [])
        self.assertEqual([k[:2] for k in kept], [("10", 8)])
    def test_other_edge_is_free(self):
        moves, kept = fp.plan(fp.parse(panel(2, 0) + panel(10, 4, location=3)), 3)
        self.assertEqual(moves, [("10", 4, ["10"])])
        self.assertEqual(kept, [])
    def test_two_lost_on_one_edge(self):
        moves, kept = fp.plan(fp.parse(panel(10, 5) + panel(12, 8)), 3)
        self.assertEqual([m[0] for m in moves], ["10"])
        self.assertEqual([k[0] for k in kept], ["12"])
    def test_screen_count_went_down(self):
        moves, _ = fp.plan(fp.parse(panel(2, 1, location=3)), 1)
        self.assertEqual(moves, [("2", 1, ["2"])])
 class Run(unittest.TestCase):
    def setUp(self):
        self.dir = tempfile.TemporaryDirectory()
        self.path = os.path.join(self.dir.name, "plasma-org.kde.plasma.desktop-appletsrc")
        with open(self.path, "w") as f:
            f.write(ISSUE_18)
    def tearDown(self):
        self.dir.cleanup()
    def run_script(self, *args):
        return subprocess.run([sys.executable, SCRIPT, "--file", self.path, "--screens", "3", *args],
                              capture_output=True, text=True)
    def test_check_reports_and_changes_nothing(self):
        r = self.run_script("--check")
        self.assertEqual(r.returncode, 1)
        self.assertIn("panel 10: screen 8, bottom (lost", r.stdout)
        with open(self.path) as f:
            self.assertEqual(f.read(), ISSUE_18)
    def test_repair(self):
        r = self.run_script()
        self.assertEqual(r.returncode, 0, r.stderr)
        self.assertIn("moved it to the first screen", r.stderr)
        with open(self.path) as f:
            groups = fp.parse(f.read())
        self.assertEqual(groups[("Containments", "10")]["lastScreen"], "0")
        self.assertEqual(groups[("Containments", "11")]["lastScreen"], "0")
        self.assertEqual(groups[("Containments", "10", "Applets", "101")]["plugin"], "org.kde.plasma.kickoff")
        self.assertEqual(groups[("Containments", "25")]["lastScreen"], "8")  # a spare's desktop
        with open(self.path + ".ft-bak") as f:
            self.assertEqual(f.read(), ISSUE_18)
        # A second run finds nothing to do and leaves the backup alone.
        os.remove(self.path + ".ft-bak")
        r = self.run_script()
        self.assertEqual((r.returncode, r.stderr), (0, ""))
        self.assertFalse(os.path.exists(self.path + ".ft-bak"))
        self.assertEqual(self.run_script("--check").returncode, 0)
    def test_no_config_yet(self):
        os.remove(self.path)
        self.assertEqual(self.run_script().returncode, 0)
        self.assertEqual(self.run_script("--check").returncode, 0)
 if __name__ == "__main__":
    unittest.main()
Author	SHA1	Message	Date
DeeJanuzandClaude Opus 5.5	06f2dd63c1	FrameDrop: proof of concept for installing Frametop from FrameDrop (#25 ) FrameDrop sideloads a Linux zip as a Steam Devkit Game. Frametop can't be copied over as an app, so the zip holds a small installer: playing it runs get.sh --yes in a transient user service (Steam reaps the title's process tree on quit) and shows progress in a GTK window. - probe/probe.sh records what a Devkit Game can reach. On SteamOS 0.3.0 it runs on the host with git, podman, systemd and GTK, even with the SLR4 compat tool set; inside SLR4, flatpak-spawn --host reaches the host. - devkit.sh registers a folder the way FrameDrop does (Valve's devkit-utils), for testing without a PC. - build.sh makes a reproducible Frametop.zip and the FrameDrop manifest. Nothing is published. Open: whether FrameDrop keeps the exec bit, and its start command and runtime choice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 21:19:30 -06:00
DeeJanuzandClaude Opus 5.5	ec870d2d7a	Merge branch laser-release (release a held button that can't come up on a screen: the game kept losing its controllers) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 09:37:46 -06:00
DeeJanuzandClaude Opus 5.5	80797c98b9	Screens: release a held button that can't come up on a screen Pausing, or hiding the screen a button went down on, took the laser off it mid-click; the pause gesture's second thumbstick click does that. SteamVR's laser mouse then forgot the button ("Mouse down count is 1 but states are all false"), no release came, and the catcher kept showing whenever the pressing laser was off the panels, even while paused. Being interactive, it kept the VR game's controllers from it until the desktop restarted (2026-10-04, Beat Saber). ft-screens now releases a held button when it's paused, when the screen it went down on is hidden, or, during VR games, when the pressing hand controller has held nothing for a second. GetControllerState answers overlay apps only while a game runs; outside games a hold is never cut. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 09:31:27 -06:00
DeeJanuzandClaude Opus 5.5	2fadbbe148	Merge branch orphan-panel (bring back a taskbar saved on a screen the desktop doesn't have, #18 ) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:42:12 -06:00
DeeJanuzandClaude Opus 5.5	5ee07f99a8	Merge branch menu-entry-programs (Hide/Show Screens no longer launches Reset Screen Layout) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:39:44 -06:00
John MurrayandClaude Opus 5.5	f0b93b79d3	Menu entries: own programs for Reset Screen Layout and Hide/Show Screens Reset Screen Layout and Hide/Show Screens both ran ft-layout. Steam lists entries by program, so Hide/Show launched Reset. Each gets a wrapper. From PR #17 (only this part of 9618be8; its host_command change is for the Nix packages). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:39:40 -06:00
DeeJanuzandClaude Opus 5.5	13a530d829	Merge branch mute-key (PR #24 : the mute key toggles the default output's mute) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:36:44 -06:00
DeeJanuzandClaude Opus 5.5	f260a6a9e4	Merge branch lazy-susan (PR #22 : Meta+Alt+Tab spins the panels around you) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:36:44 -06:00
DeeJanuzandClaude Opus 5.5	2e09cf9efe	Merge PR #24 (SuperTuxii: the mute key toggles the default output's mute) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:36:33 -06:00
DeeJanuzandClaude Opus 5.5	9a4b66ff50	keys-test: the spin bindings (Meta+Alt+Tab, Meta+Alt+Shift+Tab), not while paused Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:36:33 -06:00
DeeJanuzandClaude Opus 5.5	17269134ce	Merge PR #22 (ehippy: lazy susan, Meta+Alt+Tab spins the panels around you) into experimental Conflicts with experimental's pause_toggle, steam_menu and command: actions and its AnnounceOverlay: both kept. The spin bindings join the Meta tap in the defaults, spinning doesn't need pointer mode, and like other actions it does nothing while Frametop is paused. AnnounceOverlay now sends through the PR's SendPointer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:36:33 -06:00
DeeJanuzandClaude Opus 5.5	d995b815f8	Session: bring back a taskbar saved on a screen the desktop doesn't have Plasma 6.2.5 keeps a panel on a screen number and never moves one whose number is past the screen count, so a taskbar saved on a spare output (#18, lastScreen=8 with three screens) or on a screen a smaller layout dropped stayed hidden. Before Plasma starts, session/fix-panels.py moves such a panel and its tray's containment to screen 0 (the primary), keeping its widgets, unless screen 0 already has a panel on that edge. doctor.sh checks the panels' screens, and report.sh lists them with the live outputs and panels. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-04 08:32:04 -06:00
SuperTuxii	f18918f781	input-relay: Add mute key as volume key Add KEY_MUTE as volume key. It will be mapped to KEY_MACRO28 and use wpctl to toggle the mute of the default audio sink. The toggle of the mute state will be done once when the key is pressed instead of continuously toggling it when it is held down. This allows the mute button on keyboards to work properly. Signed-off-by: SuperTuxii <123881249+SuperTuxii@users.noreply.github.com>	2026-10-04 16:06:37 +02:00
DeeJanuzandClaude Opus 5.5	e0208687b6	Merge branch tip-in-games (controller laser tip found during VR games) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:33:49 -06:00
DeeJanuzandClaude Opus 5.5	c699e13104	Screens: find the controllers' laser tip during VR games too GetComponentStateForDevicePath with no input source handle fails for every render model component while a VR game runs (checked 2026-10-03 with a game up: all 21 components of frame_controller_right). TipOffset then fell back to the controller's pose, which aims 40 degrees above the Frame controller's laser. In games, pointing at a screen's middle missed it and pointing below it hit, so the new aim-to-laser only worked from the bottom; the controls' reveal and pin/roll aim were off the same way. GetComponentState still answers then, with the same tip. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:33:49 -06:00
DeeJanuzandClaude Opus 5.5	9b12b7d74e	Merge branch aim-lasers (in games, pointing a controller at a Frametop panel turns its laser on) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:27:49 -06:00
DeeJanuzandClaude Opus 5.5	c7c7c1f772	Screens: in games, pointing a controller at a panel turns its laser on SteamVR's own floating windows take the laser while a controller points at them in a game and give it back when it points away. Frametop's panels didn't: with the controllers left to the game (outside_games, the default, or dashboard), they couldn't be clicked without the dashboard. ft-screens now sets MakeOverlaysInteractiveIfVisible on a screen or floating window while a hand controller's laser pose meets it, its controls, or its popups (UpdateAim; curved screens hit on their cylinder), and clears it 0.3 s after the aim leaves a wider margin. A drag or a held button keeps it on. The keyboard, one overlay, uses ComputeOverlayIntersection and now follows the mode when a game starts or ends while it's open. This replaces the reset button's own aim zone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:27:49 -06:00
DeeJanuzandClaude Opus 5.5	2486a601e3	Merge branch click-threshold (controller click zone 32 px by default) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:17:49 -06:00
DeeJanuzandClaude Opus 5.5	de25633f87	Click stability: 32 logical pixels by default, not 8 8 is about 0.2 degrees on a 3.4 m wide 3440-pixel screen 2 m away, so a trigger press turned into a drag unless the hand was very still. 32 (about 0.9 degrees) felt much better in the headset (2026-10-03). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:17:49 -06:00
DeeJanuzandClaude Opus 5.5	53a1836dbb	Merge branch reset-button (a reset button next to each screen's grab bar, clickable in VR games) into experimental Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 21:15:51 -06:00
Patrick McDavidandClaude Opus 5.5	6fb168a8b8	Lazy susan: Meta+Alt+Tab spins the panels around you - ft-screens "spin next\|prev\|<degrees>": every unpinned screen and floating window turns together about a vertical axis through your head (0.3 s, eased), so the next panel on the right or left comes to straight ahead; the arrangement stays as it is. Taps during a spin add to it, from where the panels are headed; grabbing a panel or placing it (ft-layout, ft-floatd) takes it out of the spin - when a spin settles, the panel in front gets the pointer (recenter), typing (as after a click), and KWin's active window: its floating window, or the top window on a screen (ft-floatd "front N", the KWin script's activate-output). KWin's outputs follow the screens' new places (ft-layout scale), as after a move - the input relay: spin_next and spin_prev actions, Meta+Alt+Tab and Meta+Alt+Shift+Tab by default; Frametop Input Settings lists them. Not Meta+Tab: that's Cmd+Tab on a Mac reached through a remote desktop like RustDesk, and the relay would take the Mac's app switcher. Meta+Alt+Tab (Cmd+Option+Tab) is unused on macOS, Windows, and KDE Used on the Frame (SteamOS 0.3.0 build 20260922) with one screen and three or four floating windows, through RustDesk to a Mac. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-03 10:17:22 -06:00
Patrick McDavidandClaude Opus 5.5	1ebf3692fb	ft-floatd: a launch for a missing app no longer kills the control socket (#16 ) Gio.DesktopAppInfo.new() returns NULL for a desktop file that doesn't exist, and PyGObject raises TypeError ("constructor returned NULL") rather than returning None, so launch()'s `if info is None` never ran. The exception escaped the control socket's GLib callback, GLib dropped the watch, and ft-floatd stopped answering everything: the float key, dock, Launch as Standalone, and profiles, until the desktop restarted. Found on the Frame (2026-10-02): a profile saved with RustDesk's Flatpak open records its window's app id, com.carriez.flutter_hbb, which has no desktop file (the Flatpak's is com.rustdesk.RustDesk). `ft-layout use` on that profile asked ft-floatd to launch it, and ft-floatd went silent. With this, that launch replies "error no app com.carriez.flutter_hbb" and the profile's other apps open. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-02 21:12:49 -06:00
DeeJanuzandClaude Opus 5.5	072a294941	README: Frametop doesn't work on the SteamOS beta yet Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-02 16:12:52 -06:00
DeeJanuzandClaude Opus 5.5	7816633353	README: link the Frametop Discord Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 21:18:09 -06:00