Add opt-in desktop mouse and controller ownership handoff

README.md

@@ -17,8 +17,6 @@ Join the [Frametop Discord](https://discord.gg/W3X9f7z3Bc) for questions, ideas,
 
 ## Install on the headset
 
-> **Frametop doesn't work on the SteamOS beta right now.** On the beta (SteamOS 0.4.3), gaze mode can't read the eye tracker, and the desktop has started without its taskbar ([#15](https://github.com/DeeJanuz/frametop/issues/15)). Use the stable SteamOS release until this note is gone.
-
 You need a Steam Frame with an internet connection, a keyboard (Bluetooth, or the on-screen one), and about 3 GB of free space.
 
 1. In the launcher, choose Launch a program → Desktop.
@@ -57,7 +55,6 @@ 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 |
 | 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 |
 | Play a VR game | The screens hide and your controllers stay in the game. Open the SteamVR dashboard, or press Meta+Shift+H, to see and use them. To keep them visible over games, change During VR games on the Visibility & pins tab; the controllers still stay in the game, and you use the screens with the mouse or the dashboard |

docs/desktop-mouse.md

@@ -0,0 +1,121 @@
+# Independent desktop mouse
+
+`input/ft-mousectl desktop --save` selects normal desktop input: the physical
+mouse moves across the nested KDE monitors, clicks and scrolls through KDE's
+Wayland seat, and displays KDE's own cursor. No mouse event becomes a virtual
+controller event. Physical controllers remain available to SteamVR and games.
+While a routed mouse is connected, controller events on desktop app panels are ignored;
+floating app panels, the separate grab bars and placement controls still work under the existing
+controller policy. SteamVR dashboard controls are unaffected.
+
+Native CLI commands (no additional project tooling required):
+
+```sh
+input/ft-mousectl status
+input/ft-mousectl desktop --save
+input/ft-mousectl center 2
+input/ft-mousectl position 2 960 540
+input/ft-mousectl layout
+input/ft-mousectl spatial --save
+```
+
+Numbers follow KDE's WL-0, WL-1 output order, starting at 1. Positions are local
+logical pixels; `layout` reads actual output geometry and scale from the running
+private KDE session. Geometry follows FrameTop layout changes too. A drag keeps
+the Wayland implicit grab on its initial output until all buttons are released,
+while the cursor can cross onto another monitor.
+
+The relay gathers motion and wheels until the mouse's SYN_REPORT. High resolution
+wheel reports use 1/120-notch units and replace accompanying ordinary reports;
+they are delivered immediately without the spatial pointer's pulse timer. The
+main and thumb wheels are independent. Standard mouse button codes are passed
+through, including back/forward; spatial mouse button mappings do not apply.
+`DESKTOP_MOUSE_SPEED` in `~/.config/frametop.conf` sets logical pixels per motion
+count, default 1, range .05–10. This initial implementation uses constant speed,
+not KDE's libinput acceleration settings, because FrameTop's relay owns the
+physical device outside the nested session.
+
+The cursor overlay only displays KDE's cursor; it has no input method, laser
+claim, or interactive overlay flag. Cursor shape, hotspot and buffer scale come
+from KDE. GPU cursor buffers use the same zero-copy DMA-BUF import as the monitor
+textures. Common 32-bit shared-memory cursor formats are converted to RGBA.
+
+Controller fallback: `DESKTOP_CONTROLLER_FALLBACK=1` (default) allows controller
+laser input into desktop apps when no grabbed physical mouse is routed by the
+relay. Idle mice do not trigger fallback. The relay reports presence every
+second; absence must persist for one second, so disconnect detection normally
+takes about one to two seconds. Keyboard routing still follows desktop clicks.
+The virtual spatial mouse/gaze pointer stays off; controller policy stays
+`dashboard`, preserving SteamVR's existing pointer-mode behavior.
+
+Reconnect or native mouse motion returns ownership to the native seat and
+releases controller-held buttons before clearing its focus. A held native mouse
+button prevents fallback until released. An unknown presence or a heartbeat
+older than three seconds blocks automatic controller desktop input. Set
+`DESKTOP_CONTROLLER_FALLBACK=0` to retain strict separation even without a mouse;
+reload the relay at an appropriate pause after changing this preference.
+`input/ft-mousectl status` includes `controllerFallback` with presence, freshness,
+configured enablement and actual desktop controller ownership. Older running
+compositors report this field unavailable until explicitly reloaded.
+Both paths support images up to 512×512 and buffer scale 8. FrameTop retains the
+image from the first surface commit, because KDE can commit it before selecting
+the active cursor and wlroots releases current.buffer after commit callbacks.
+An unsupported buffer is reported by cursorReady=false with cursorError
+and hides the old cursor image. Rendering in VR still needs a wearer check for
+visibility, stereo depth, monitor edges and cursor shape changes.
+
+The private desktop and apps launched from it use KDE's `kcminputrc` cursor
+preferences (24px Breeze by default). Steam's VR environment exports
+`XCURSOR_SIZE=256` and `XCURSOR_THEME=steam`; inheriting these makes app cursors
+huge and can make their appearance change across monitors. A live KDE
+CursorChanged notification updates KDE, but already running apps may retain
+the old environment until reopened. Do not resize the VR overlay to mask an
+app's incorrectly configured cursor size.
+
+The updated compositor, pointer helper and relay must all be loaded before
+activation. `status` is read-only and shows readiness, actual/desired mode,
+held buttons and delivery counters. Saving happens only after an acknowledged
+mode change. Switching refuses while buttons/keys on a pointer device are held.
+An absent compositor does not prevent explicit spatial recovery. Restarting the
+desktop requires the user's approval; use `desktops.sh restart` so background
+work is preserved, and restore the current app windows afterwards.
+
+If the compositor is lost, native mouse messages are not redirected into VR.
+The input helpers need reloading when upgrading this feature. A standalone
+helper/compositor restart may require `input/ft-mousectl desktop` again; inspect
+all three components in `status` rather than inferring success from motion alone.
+
+Offline verification (or run `scripts/test-desktop-input.sh`):
+
+```sh
+python3 -m unittest discover -s input -p 'test_*.py'
+scripts/frame.sh -C screens 'gcc -std=c11 -Wall -Wextra -Werror tests/desktop-mouse-test.c -lm -o build/desktop-mouse-test && build/desktop-mouse-test'
+scripts/frame.sh -C screens 'gcc -std=c11 -Wall -Wextra -Werror $(pkg-config --cflags libdrm) tests/desktop-cursor-test.c -o build/desktop-cursor-test && build/desktop-cursor-test'
+scripts/frame.sh -C screens 'gcc -std=c11 -Wall -Wextra -Werror tests/cursor-cache-test.c $(pkg-config --cflags --libs wlroots-0.20 wayland-server wayland-client libdrm pixman-1) -o build/cursor-cache-test && build/cursor-cache-test'
+```
+
+The direct seat and cursor path follow the [Wayland pointer protocol](https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_pointer).
+
+
+The default remains `MOUSE_MODE=spatial`. Native mode is explicitly selected
+with `input/ft-mousectl desktop --save`; no driver bindings or SteamVR defaults
+are changed by installation. The new native mode suppresses virtual gaze, hand
+gesture and gaze-click input while selected. Switch back to spatial mode to
+use those features. Ordinary VR keyboard events remain available.
+
+## Experimental desktop handoff
+
+`input/ft-mousectl policy last-active` enables shared desktop input. Controller
+clicks and nonzero scrolls inside desktop monitors take ownership; aiming alone
+does not. Native mouse motion, clicks and scrolling reclaim ownership. Same
+millisecond claims favor the mouse. Held buttons keep ownership until released;
+other-device events are discarded rather than replayed after the drag. SteamVR
+controls and separate monitor grab/placement bars do not participate.
+
+`input/ft-mousectl policy mouse` restores the original mouse-first behavior
+(including configured mouse-absent fallback). `policy pointer` reserves desktop
+input for the controller. Changes refuse while either device holds a desktop
+button. `status` reports policy, owner, held buttons and ignored mouse events.
+These choices are runtime-only and reset to `mouse` when the desktop restarts.
+The original PR checkpoint is retained on `checkpoint/desktop-input-before-handoff`;
+this experiment is developed separately on `feat/desktop-input-handoff`.

docs/reference.md

@@ -2,6 +2,8 @@
 
 How each part of Frametop works, where its settings live, and the commands for running parts of it by hand. For why it's built this way, see [design.md](design.md).
 
+For independent mouse input, KDE cursor rendering and controller fallback, see [desktop-mouse.md](desktop-mouse.md).
+
 ## The desktop
 
 From the headset, open Launch a program → Desktop. The installer replaces that launcher entry with Frametop's (`~/.local/share/applications/deckard-nested-desktop.desktop`), and `desktops.sh uninstall` gives the stock single-screen desktop back.
@@ -117,7 +119,7 @@ A Kirigami app with a Python backend, in the Plasma menu under Settings. It runs
 - Devices lists every USB and Bluetooth mouse and keyboard, with a light that flashes when the device is used. Each device gets a role: 3D pointer (grabbed, drives the pointer; the default for anything with a mouse), Pass through (grabbed only while typing goes to the desktop; the default for keyboards, where a Meta tap toggles the dashboard if `META_DASHBOARD=1` is in `~/.config/frametop.conf`), or Ignore. A device is identified by its Bluetooth address, or its USB ids and name, so all of its input nodes share one role. Forget drops everything saved for a device.
 - 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, 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`.
-- 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, on any keyboard, to any action but passing a key through or nothing. The gaze clicks (Gaze left click and Gaze right click) only go on key combinations. The defaults are 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. The combination's last key isn't typed, and the modifiers still reach the app. They're saved as `key_bindings` in the same file.
+- 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, on any keyboard, to any action but passing a key through or nothing. The gaze clicks (Gaze left click and Gaze right click) only go on key combinations. The defaults are 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. The combination's last key isn't typed, and the modifiers still reach the app. They're saved as `key_bindings` in the same file.
 - 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.

float/frametop-float.js

@@ -378,17 +378,6 @@ 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;

float/ft_floatd.py

@@ -18,8 +18,6 @@ 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
@@ -747,10 +745,7 @@ class Daemon:
         Returns (reply, pid or None)."""
         if app:
             app = app.removesuffix(".desktop")
-            try:
-                info = Gio.DesktopAppInfo.new(app + ".desktop")
-            except TypeError:  # PyGObject raises for the NULL a missing desktop file returns
-                info = None
+            info = Gio.DesktopAppInfo.new(app + ".desktop")
             if info is None:
                 return f"error no app {app}", None
             pids = []
@@ -1045,13 +1040,6 @@ 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:

input-settings/ft_input_settings.py

@@ -71,8 +71,6 @@ ACTION_LABELS = {
     "sens_down": "Slower pointer", "layout_reset": "Reset desktop screen layout",
     "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",
-    "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",
 }
@@ -144,9 +142,8 @@ 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): 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+36": "gaze_left", "125+37": "gaze_right", "42+125+33": "float_toggle",
-                        "56+125+15": "spin_next", "42+56+125+15": "spin_prev"}
+# Meta+K click at the gaze, Meta+Shift+F floats a window.
+DEFAULT_KEY_BINDINGS = {"125+36": "gaze_left", "125+37": "gaze_right", "42+125+33": "float_toggle"}
 
 
 def key_bindings(rules):

input/ft-mousectl

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Native KDE mouse control, entirely over local IPC; no SteamVR client needed."""
+import argparse
+import importlib.util
+import json
+import math
+import os
+from pathlib import Path
+import re
+import socket
+import tempfile
+
+SCREENS = '\0ft_screens'
+RELAY = '\0frametop_relay'
+HELPER = '\0ft_pointer_helper'
+CONF = Path.home() / '.config/frametop.conf'
+
+
+def request(address, command):
+    with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as sock:
+        sock.bind('')
+        sock.settimeout(1)
+        sock.sendto(command.encode(), address)
+        result = sock.recv(8192).decode()
+    if result.startswith('error'):
+        raise RuntimeError(result)
+    return result
+
+
+def query(address, command):
+    try:
+        result = json.loads(request(address, command))
+        if not isinstance(result, dict): raise ValueError('Expected an object')
+        return result
+    except (OSError, ValueError, RuntimeError) as error:
+        return {'available': False, 'reason': str(error)}
+
+
+def status():
+    result = {'relay': query(RELAY, 'mouse-mode?'), 'desktop': query(SCREENS, 'mouse?'),
+              'pointer': query(HELPER, 'pointerstatus'),
+              'controllerFallback': query(SCREENS, 'mouse-presence?'),
+              'desktopPolicy': query(SCREENS, 'desktop-policy?')}
+    result['ready'] = bool(result['relay'].get('supported') and result['desktop'].get('supported')
+                           and 'desktopInput' in result['pointer'])
+    result['active'] = bool(result['ready'] and result['relay'].get('mode') == 'desktop'
+                            and result['desktop'].get('mode') == 'desktop'
+                            and result['pointer'].get('desktopInput'))
+    return result
+
+
+def require_ready():
+    result = status()
+    if not result['ready']:
+        raise RuntimeError('Native mouse support is not loaded in all three components. '
+                           'Inspect status; the updated desktop and input helpers must be running.')
+    return result
+
+
+def layout_outputs():
+    spec = importlib.util.spec_from_file_location('mouse_layout', Path(__file__).resolve().parents[1] / 'layout/ft_layout.py')
+    ft = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(ft)
+    env = ft.nested_env()
+    if env is None: raise RuntimeError('No running FrameTop KDE desktop')
+    outs = ft.outputs(env)
+    if not outs or not any(o.get('enabled') for o in outs):
+        raise RuntimeError('KDE output geometry is unavailable')
+    return outs
+
+
+def configure(outs):
+    commands = []
+    for index, output in enumerate(outs, 1):
+        if not output.get('enabled'):
+            commands.append(f'mouse-output-off {index}')
+            continue
+        scale = float(output['scale'])
+        if not math.isfinite(scale) or not .25 <= scale <= 8:
+            raise ValueError('Invalid KDE output scale')
+        w, h = (math.ceil(output['size'][k]/scale) for k in ('width', 'height'))
+        x, y = (float(output['pos'][k]) for k in ('x', 'y'))
+        if not all(math.isfinite(v) for v in (x, y)) or not (1 <= w <= 16384 and 1 <= h <= 16384):
+            raise ValueError('Invalid KDE output geometry')
+        commands.append(f'mouse-layout {index} {x:g} {y:g} {w} {h} {scale:g}')
+    # Validate the entire geometry before sending any updates.
+    for command in commands:
+        if request(SCREENS, command) != 'ok': raise RuntimeError('Mouse layout rejected')
+
+
+def save_mode(mode, path=None):
+    path = Path(path or CONF)
+    text = path.read_text() if path.exists() else ''
+    pattern = re.compile(r'^\s*MOUSE_MODE\s*=.*$', re.M)
+    text = pattern.sub('MOUSE_MODE='+mode, text) if pattern.search(text) else text.rstrip('\n')+'\nMOUSE_MODE='+mode+'\n'
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=path.name+'.', dir=path.parent)
+    try:
+        os.fchmod(fd, (path.stat().st_mode & 0o777) if path.exists() else 0o600)
+        with os.fdopen(fd, 'w') as file:
+            file.write(text)
+            file.flush()
+            os.fsync(file.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary): os.unlink(temporary)
+
+
+def switch(mode, save=False):
+    if mode == 'desktop':
+        require_ready()
+        configure(layout_outputs())
+    # Spatial recovery intentionally works with an absent desktop.
+    result = query(RELAY, 'mouse-mode '+mode)
+    if result.get('ok') is not True: raise RuntimeError(result.get('error', result.get('reason', 'Relay rejected mode')))
+    if save:
+        try: save_mode(mode)
+        except OSError as error:
+            raise RuntimeError(f'Live mode is {mode}, but saving the preference failed: {error}') from error
+    return dict(mode=mode, saved=save)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest='command', required=True)
+    sub.add_parser('status')
+    sub.add_parser('layout')
+    policy = sub.add_parser('policy', help='Choose desktop mouse/pointer ownership (runtime only)')
+    policy.add_argument('mode', choices=('mouse', 'pointer', 'last-active'))
+    for name in ('desktop', 'spatial'):
+        sub.add_parser(name).add_argument('--save', action='store_true')
+    pos = sub.add_parser('position')
+    pos.add_argument('screen', type=int)
+    pos.add_argument('x', type=float)
+    pos.add_argument('y', type=float)
+    center = sub.add_parser('center')
+    center.add_argument('screen', type=int)
+    args = parser.parse_args()
+    try:
+        if args.command == 'status': result = status()
+        elif args.command == 'policy':
+            require_ready()
+            if request(SCREENS, 'desktop-policy '+args.mode) != 'ok':
+                raise RuntimeError('Desktop policy rejected')
+            result = query(SCREENS, 'desktop-policy?')
+        elif args.command in ('desktop', 'spatial'): result = switch(args.command, args.save)
+        else:
+            require_ready()
+            outs = layout_outputs()
+            if args.command == 'layout':
+                configure(outs)
+                result = {'outputs': outs}
+            else:
+                if not 1 <= args.screen <= len(outs): raise ValueError('Invalid screen number')
+                if args.command == 'center':
+                    output = outs[args.screen-1]
+                    x, y = (math.ceil(output['size'][k]/output['scale'])/2 for k in ('width', 'height'))
+                else: x, y = args.x, args.y
+                if not all(math.isfinite(v) for v in (x, y)): raise ValueError('Position must be finite')
+                if request(SCREENS, f'mouse-position {args.screen} {x:g} {y:g}') != 'ok':
+                    raise RuntimeError('Mouse position rejected')
+                result = dict(screen=args.screen, x=x, y=y)
+        print(json.dumps(result, indent=2))
+    except (OSError, RuntimeError, ValueError, KeyError) as error:
+        parser.exit(1, str(error)+'\n')
+
+
+if __name__ == '__main__': main()

input/input-relay.py

@@ -31,9 +31,7 @@ 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), 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
+window back (both to ft-floatd, @frametop_float), profile:NAME = switch to that profile (ft-layout
 use NAME: its screens and apps; docs/profiles.md), key = pass through as a key, none).
 
 Frame controller buttons can be mapped too ("controller_buttons": {"right/a": action} in the
@@ -117,6 +115,7 @@ import atexit
 import errno
 import fcntl
 import json
+import math
 import os
 import select
 import signal
@@ -131,7 +130,7 @@ EV_SYN, EV_KEY, EV_REL, EV_MSC = 0x00, 0x01, 0x02, 0x04
 SYN_REPORT = 0
 BTN_MISC, KEY_MAX = 0x100, 0x2FF
 KEY_A = 30
-REL_X, REL_Y, REL_WHEEL, REL_MAX = 0x00, 0x01, 0x08, 0x0F
+REL_X, REL_Y, REL_HWHEEL, REL_WHEEL, REL_MAX = 0x00, 0x01, 0x06, 0x08, 0x0F
 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
@@ -191,15 +190,12 @@ 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", "spin_next", "spin_prev", "key", "none")
+           "dock_all", "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: 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, 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+36": "gaze_left", "125+37": "gaze_right", "42+125+33": "float_toggle",
-                        "56+125+15": "spin_next", "42+56+125+15": "spin_prev"}
+# (free on the Frametop desktop, and apps don't use Meta), Meta+Shift+F floats a window.
+DEFAULT_KEY_BINDINGS = {"125+36": "gaze_left", "125+37": "gaze_right", "42+125+33": "float_toggle"}
 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}
@@ -215,9 +211,6 @@ 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)
 
 
@@ -226,7 +219,7 @@ def known_action(a):
 
 
 def needs_pointer(a):
-    return a not in FLOAT_ACTIONS and a not in SCREENS_ACTIONS and not a.startswith(PROFILE)
+    return a not in FLOAT_ACTIONS and not a.startswith(PROFILE)
 KEYS = "\0frametop_keys"  # keys of keyboards grabbed for the desktop, for other readers
 FT_LAYOUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "layout", "ft-layout")
 DEFAULT_BUTTONS = {BTN_LEFT: "left", BTN_RIGHT: "right", BTN_MIDDLE: "middle",
@@ -598,6 +591,75 @@ class Pointer:
         return 0.02 if any(t is not None for t in pending) else 0.5
 
 
+def desktop_mouse_present(nodes):
+    """Only a physical mouse actually routed by this relay owns the desktop."""
+    return any(n.is_mouse and n.role == "pointer" and n.grabbed for n in nodes)
+
+
+def ipc_request(address, command, timeout=.2):
+    """Bounded local request/reply, with no OpenVR client or desktop wake."""
+    with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as sock:
+        sock.bind("")
+        sock.settimeout(timeout)
+        sock.sendto(command.encode(), address)
+        reply = sock.recv(8192).decode()
+    if reply.startswith("error"):
+        raise RuntimeError(reply)
+    return reply
+
+
+class DesktopMouse:
+    """Physical mouse -> nested KDE seat. Never sends to the VR pointer helper."""
+    def __init__(self, speed=1):
+        if not math.isfinite(speed) or not .05 <= speed <= 10:
+            raise ValueError("Desktop mouse speed must be between .05 and 10")
+        self.speed = speed
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        self.dx = self.dy = 0
+        self.wheel = [0, 0]
+        self.hires = [0, 0]
+        self.has_hires = [False, False]
+        self.held = set()
+        self.sent = self.failed = 0
+
+    def send(self, command):
+        try:
+            self.sock.sendto(command.encode(), SCREENS)
+            self.sent += 1
+        except OSError:
+            self.failed += 1
+
+    def motion(self, code, value):
+        if code == REL_X: self.dx += value
+        elif code == REL_Y: self.dy += value
+        elif code in (REL_HWHEEL, REL_WHEEL): self.wheel[code == REL_WHEEL] += value
+        elif code in (12, 11):
+            axis = int(code == 11)
+            self.hires[axis] += value
+            self.has_hires[axis] = True
+
+    def flush(self):
+        if self.dx or self.dy:
+            self.send(f"mouse-move {self.dx*self.speed:.6f} {self.dy*self.speed:.6f}")
+            self.dx = self.dy = 0
+        wheel = [self.hires[i]/120 if self.has_hires[i] else self.wheel[i] for i in (0, 1)]
+        if any(wheel): self.send(f"mouse-wheel {wheel[0]:.6f} {wheel[1]:.6f}")
+        self.wheel = [0, 0]; self.hires = [0, 0]; self.has_hires = [False, False]
+
+    def button(self, code, value):
+        if not BTN_LEFT <= code <= 279 or value not in (0, 1): return
+        self.flush()
+        self.send(f"mouse-button {code} {value}")
+        if value: self.held.add(code)
+        else: self.held.discard(code)
+
+    def release_all(self):
+        self.dx = self.dy = 0
+        self.wheel = [0, 0]; self.hires = [0, 0]; self.has_hires = [False, False]
+        for code in sorted(self.held): self.send(f"mouse-button {code} 0")
+        self.held.clear()
+
+
 class Node:
     """One input event node: a candidate device (mouse or keyboard, USB or Bluetooth),
     or any other device with volume keys (candidate False, role "volume")."""
@@ -681,13 +743,22 @@ def main():
     # every second); typing_applied: the grabs match that as of the last apply_roles().
     # vr_capture_until: every controller button is taken until then (the settings app capturing one).
     state = {"pointer": None, "rules": {}, "meta_dashboard": False, "share_keys": False,
-             "desktop_until": 0.0, "typing_applied": None, "vr_capture_until": 0.0}
+             "desktop_until": 0.0, "typing_applied": None, "vr_capture_until": 0.0,
+             "desktop_mouse": None, "mouse_mode": "spatial", "desktop_speed": 1.0,
+             "controller_fallback": True}
 
     def load_config():
         conf = read_config()
         state["rules"] = read_rules()
         state["meta_dashboard"] = conf.get("META_DASHBOARD", "0") == "1"
         state["share_keys"] = conf.get("SHARE_KEYS", "0") == "1"
+        state["mouse_mode"] = "desktop" if conf.get("MOUSE_MODE") == "desktop" else "spatial"
+        state["controller_fallback"] = conf.get("DESKTOP_CONTROLLER_FALLBACK", "1") == "1"
+        try:
+            speed = float(conf.get("DESKTOP_MOUSE_SPEED", "1"))
+            state["desktop_speed"] = speed if math.isfinite(speed) and .05 <= speed <= 10 else 1
+        except ValueError:
+            state["desktop_speed"] = 1
         if conf.get("POINTER", "0") == "1":
             p = state["pointer"] or Pointer(0.03, 30)
             p.sensitivity = float(conf.get("POINTER_SENSITIVITY", "0.03"))
@@ -706,7 +777,9 @@ def main():
 
     def vr_bind(now):
         """Tell the pointer helper which controller buttons to take from games."""
-        if now < state["vr_capture_until"]:
+        if state["desktop_mouse"]:
+            buttons = "-"  # leave every physical controller button to SteamVR/games
+        elif now < state["vr_capture_until"]:
             buttons = "*"
         else:
             state["vr_capture_until"] = 0.0
@@ -729,7 +802,7 @@ def main():
                 reply(addr, {"t": "event", "id": VR_DEVICE, "path": "", "name": "Steam Frame controllers",
                              "type": "vr", "code": button, "value": value})
         action = state["rules"]["controller_buttons"].get(button)
-        if (state["pointer"] or (action and not needs_pointer(action))) and known_action(action) \
+        if not state["desktop_mouse"] and (state["pointer"] or (action and not needs_pointer(action))) and known_action(action) \
                 and action not in ("key", "none") and action not in GAZE_ACTIONS:
             do_action(action, value, now, button.split("/")[0])
 
@@ -756,7 +829,7 @@ def main():
 
     def do_action(action, value, now, source="mouse"):
         """A mapped mouse or controller button, or key combination (pointer mode only, but
-        for FLOAT_ACTIONS, SCREENS_ACTIONS, and profiles)."""
+        for FLOAT_ACTIONS and profiles)."""
         if action == "keyboard_toggle":
             if value == 1 and vr_keyboard_mode() != "never":
                 vr_keyboard("toggle")
@@ -773,13 +846,6 @@ 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)
 
@@ -917,6 +983,12 @@ def main():
         return "pointer" if has_mouse else "passthrough"
 
     def release_held(node):
+        if node.role == "pointer" and state["desktop_mouse"]:
+            state["desktop_mouse"].release_all()
+            for code in node.held:
+                if code < BTN_MISC: to_screens(code, 0)
+            node.held.clear()
+            return
         for code in node.held:
             if node.role == "passthrough":
                 share_key(node, code, 0)
@@ -1010,6 +1082,40 @@ def main():
         except OSError:
             watchers.pop(addr, None)
 
+    def set_mouse_mode(mode, now):
+        if any(keys_down(n) for n in nodes.values() if n.role == "pointer"):
+            raise RuntimeError("Release mouse buttons before switching modes")
+        native = state["desktop_mouse"]
+        if native and native.held:
+            raise RuntimeError("Release mouse buttons before switching modes")
+        if mode == "desktop":
+            ipc_request(SCREENS, "mouse-mode desktop")
+            try:
+                ipc_request(HELPER, "desktopmouse on")
+            except (OSError, RuntimeError):
+                ipc_request(SCREENS, "mouse-mode spatial")
+                raise
+            if native:
+                state["mouse_mode"] = mode
+                return
+            state["desktop_mouse"] = DesktopMouse(state["desktop_speed"])
+            if state["pointer"]:
+                state["pointer"].active = False
+                state["pointer"].dx = state["pointer"].dy = 0
+                state["pointer"].claim_at = state["pointer"].claim_release = None
+                state["pointer"].scroll_until = state["pointer"].system_at = state["pointer"].system_release = None
+        else:
+            # An absent desktop must not prevent explicit spatial recovery.
+            try: ipc_request(SCREENS, "mouse-mode spatial")
+            except OSError: pass
+            ipc_request(HELPER, "desktopmouse off")
+            if native:
+                native.release_all(); native.sock.close()
+            state["desktop_mouse"] = None
+        state["mouse_mode"] = mode
+        vr_bind(now)
+        log(f"mouse mode: {mode}")
+
     def handle_control(now):
         while True:
             try:
@@ -1046,6 +1152,18 @@ def main():
                     reply(addr, {"t": "devices", "pointer_mode": state["pointer"] is not None,
                                  "actions": ACTIONS,
                                  "nodes": [n.describe() for n in nodes.values() if n.candidate]})
+                elif cmd == "mouse-mode?":
+                    native = state["desktop_mouse"]
+                    reply(addr, {"supported": True, "mode": "desktop" if native else "spatial",
+                                 "requestedMode": state["mouse_mode"], "speed": state["desktop_speed"],
+                                 "heldButtons": sorted(native.held) if native else [],
+                                 "sent": native.sent if native else 0, "sendFailures": native.failed if native else 0})
+                elif cmd == "mouse-mode" and len(words) == 2 and words[1] in ("desktop", "spatial"):
+                    try:
+                        set_mouse_mode(words[1], now)
+                        reply(addr, {"mode": words[1], "ok": True})
+                    except (OSError, RuntimeError, ValueError) as error:
+                        reply(addr, {"error": str(error), "ok": False})
                 elif cmd == "watch":
                     seconds = float(words[1]) if len(words) > 1 else 30
                     watchers[addr] = now + min(seconds, 600)
@@ -1093,6 +1211,9 @@ def main():
         if now >= next_scan:
             next_scan = now + 1.0
             reconcile_desktop_keys()
+            if (state["mouse_mode"] == "desktop") != bool(state["desktop_mouse"]):
+                try: set_mouse_mode(state["mouse_mode"], now)
+                except (OSError, RuntimeError, ValueError): pass  # desktop may be starting; retry on the next scan
             current = {}
             for name in os.listdir("/dev/input"):
                 if name.startswith("event"):
@@ -1119,11 +1240,18 @@ def main():
                     added = True
             if added:
                 apply_roles()
+            # Presence, not activity: an idle connected mouse keeps its own seat.
+            present = desktop_mouse_present(nodes.values())
+            try:
+                ipc_request(SCREENS, "mouse-presence %d %d" %
+                            (present, state["controller_fallback"]))
+            except (OSError, RuntimeError, ValueError):
+                pass  # Older/missing compositor: preserve existing native mode.
 
         ready, _, _ = select.select(list(nodes) + [control], [], [],
                                     volume.timeout(now, pointer.timeout() if pointer else 0.5))
         now = time.monotonic()
-        if pointer:
+        if pointer and not state["desktop_mouse"]:
             pointer.tick(now)
         volume.tick(now)
         if state["vr_capture_until"] and now >= state["vr_capture_until"]:
@@ -1175,7 +1303,7 @@ def main():
                                 node.held.add(code)
                             else:
                                 node.held.discard(code)
-                    if (pointer and state["meta_dashboard"] and node.role == "passthrough"
+                    if (pointer and not state["desktop_mouse"] and state["meta_dashboard"] and node.role == "passthrough"
                             and etype == EV_KEY):
                         if code in (KEY_LEFTMETA, KEY_RIGHTMETA):
                             if value == 1:
@@ -1187,6 +1315,14 @@ def main():
                             meta_down = False  # Meta used as a modifier, not a tap
                     continue
                 if etype == EV_KEY:
+                    if state["desktop_mouse"]:
+                        if code >= BTN_LEFT:
+                            state["desktop_mouse"].button(code, value)
+                        else:
+                            to_screens(code, value)
+                        if value: node.held.add(code)
+                        else: node.held.discard(code)
+                        continue
                     action = buttons.get(str(code), DEFAULT_BUTTONS.get(code, "key"))
                     if pointer and action not in ("key", "none"):
                         do_action(action, value, now)
@@ -1201,12 +1337,16 @@ def main():
                     else:
                         node.held.discard(code)
                 elif etype == EV_REL:
-                    if pointer:
+                    if state["desktop_mouse"]:
+                        state["desktop_mouse"].motion(code, value)
+                    elif pointer:
                         pointer.motion(code, value, now)
                     else:
                         mouse.emit(etype, code, value)
                 elif etype == EV_SYN and code == SYN_REPORT:
-                    if pointer:
+                    if state["desktop_mouse"]:
+                        state["desktop_mouse"].flush()
+                    elif pointer:
                         pointer.flush()
                     mouse.sync()
                     keyboard.sync()

input/test_desktop_mouse.py

@@ -0,0 +1,147 @@
+"""Offline physical mouse tests: no input devices, desktop or SteamVR accessed."""
+import importlib.machinery
+import importlib.util
+import math
+from pathlib import Path
+import tempfile
+import unittest
+from types import SimpleNamespace
+from unittest.mock import patch
+
+
+def module(name, file):
+    loader = importlib.machinery.SourceFileLoader(name, str(Path(__file__).with_name(file)))
+    spec = importlib.util.spec_from_loader(name, loader)
+    result = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(result)
+    return result
+
+
+relay = module('desktop_relay', 'input-relay.py')
+ctl = module('mouse_control', 'ft-mousectl')
+
+
+class DesktopMouseTests(unittest.TestCase):
+    def test_presence_requires_a_routed_grabbed_physical_mouse(self):
+        def node(mouse=True, role='pointer', grabbed=True):
+            return SimpleNamespace(is_mouse=mouse, role=role, grabbed=grabbed)
+        self.assertFalse(relay.desktop_mouse_present([]))
+        for n in (node(mouse=False), node(role='ignore'), node(role='passthrough'), node(grabbed=False)):
+            self.assertFalse(relay.desktop_mouse_present([n]))
+        self.assertTrue(relay.desktop_mouse_present([node(mouse=False), node()]))
+    def mouse(self, speed=1):
+        with patch.object(relay.socket, 'socket'):
+            m = relay.DesktopMouse(speed)
+        m.messages = []
+        m.send = m.messages.append
+        return m
+
+    def test_motion_precedes_click_at_new_location(self):
+        m = self.mouse(.5)
+        m.motion(relay.REL_X, 12)
+        m.motion(relay.REL_Y, -8)
+        m.button(272, 1)
+        m.button(272, 0)
+        m.flush()
+        self.assertEqual(m.messages, ['mouse-move 6.000000 -4.000000', 'mouse-button 272 1', 'mouse-button 272 0'])
+
+    def test_hires_replaces_companion_legacy_in_both_orders(self):
+        for events in ([(8, 1), (11, 120)], [(11, 120), (8, 1)]):
+            m = self.mouse()
+            for code, value in events: m.motion(code, value)
+            m.flush()
+            self.assertEqual(m.messages, ['mouse-wheel 0.000000 1.000000'])
+
+    def test_fractional_scroll_has_no_pulse_timer(self):
+        m = self.mouse()
+        for value in (15, 15, -30):
+            m.motion(11, value); m.flush()
+        self.assertEqual(m.messages, ['mouse-wheel 0.000000 0.125000', 'mouse-wheel 0.000000 0.125000', 'mouse-wheel 0.000000 -0.250000'])
+
+    def test_thumb_and_main_wheels_are_independent(self):
+        m = self.mouse()
+        m.motion(6, -2); m.motion(8, 3); m.motion(11, 60); m.flush()
+        self.assertEqual(m.messages, ['mouse-wheel -2.000000 0.500000'])
+        m.motion(8, -1); m.flush()
+        self.assertEqual(m.messages[-1], 'mouse-wheel 0.000000 -1.000000')
+
+    def test_hotplug_releases_all_buttons_without_stale_motion(self):
+        m = self.mouse()
+        m.button(272, 1); m.button(275, 1)
+        m.motion(0, 20); m.motion(8, 1)
+        m.release_all(); m.flush()
+        self.assertEqual(m.messages, ['mouse-button 272 1', 'mouse-button 275 1', 'mouse-button 272 0', 'mouse-button 275 0'])
+        self.assertFalse(m.held)
+
+    def test_button_repeat_is_ignored(self):
+        m = self.mouse()
+        m.button(272, 2); m.button(280, 1)
+        self.assertEqual(m.messages, [])
+
+    def test_native_messages_never_target_virtual_controller(self):
+        with patch.object(relay.socket, 'socket') as sock:
+            m = relay.DesktopMouse()
+            m.motion(0, 3); m.motion(8, 1); m.button(272, 1); m.release_all()
+            self.assertTrue(sock.return_value.sendto.call_args_list)
+            for call in sock.return_value.sendto.call_args_list:
+                self.assertEqual(call.args[1], relay.SCREENS)
+
+    def test_bad_speed_rejected_before_socket_created(self):
+        with patch.object(relay.socket, 'socket') as sock:
+            for speed in (math.nan, math.inf, 0, 11):
+                with self.assertRaises(ValueError): relay.DesktopMouse(speed)
+            sock.assert_not_called()
+
+
+class ControlTests(unittest.TestCase):
+    def test_old_components_cannot_trigger_partial_activation(self):
+        with patch.object(ctl, 'status', return_value={'ready': False}), patch.object(ctl, 'configure') as configure, patch.object(ctl, 'save_mode') as save:
+            with self.assertRaisesRegex(RuntimeError, 'not loaded'): ctl.switch('desktop', True)
+            configure.assert_not_called(); save.assert_not_called()
+
+    def test_rejected_switch_does_not_persist(self):
+        with patch.object(ctl, 'require_ready'), patch.object(ctl, 'layout_outputs'), patch.object(ctl, 'configure'), patch.object(ctl, 'query', return_value={'ok': False, 'error': 'held buttons'}), patch.object(ctl, 'save_mode') as save:
+            with self.assertRaisesRegex(RuntimeError, 'held buttons'): ctl.switch('desktop', True)
+            save.assert_not_called()
+
+    def test_spatial_recovery_does_not_need_kde(self):
+        with patch.object(ctl, 'layout_outputs') as layout, patch.object(ctl, 'query', return_value={'ok': True}) as query:
+            self.assertEqual(ctl.switch('spatial'), {'mode': 'spatial', 'saved': False})
+            layout.assert_not_called(); query.assert_called_once_with(ctl.RELAY, 'mouse-mode spatial')
+
+    def test_failed_persistence_reports_actual_live_mode(self):
+        with patch.object(ctl, 'query', return_value={'ok': True}), patch.object(ctl, 'save_mode', side_effect=OSError('read only')):
+            with self.assertRaisesRegex(RuntimeError, 'Live mode is spatial'): ctl.switch('spatial', True)
+
+    def test_scaled_outputs_use_actual_logical_geometry(self):
+        outs = [{'enabled': True, 'pos': {'x': -1280, 'y': 20}, 'size': {'width': 1920, 'height': 1080}, 'scale': 1.5}, {'enabled': False}]
+        with patch.object(ctl, 'request', return_value='ok') as request:
+            ctl.configure(outs)
+            self.assertEqual([c.args for c in request.call_args_list], [(ctl.SCREENS, 'mouse-layout 1 -1280 20 1280 720 1.5'), (ctl.SCREENS, 'mouse-output-off 2')])
+
+    def test_invalid_later_output_does_not_partially_change_geometry(self):
+        outs = [{'enabled': True, 'pos': {'x': 0, 'y': 0}, 'size': {'width': 1920, 'height': 1080}, 'scale': 1}, {'enabled': True, 'scale': 0}]
+        with patch.object(ctl, 'request') as request:
+            with self.assertRaises(ValueError): ctl.configure(outs)
+            request.assert_not_called()
+
+    def test_save_preserves_other_preferences_and_permissions(self):
+        with tempfile.TemporaryDirectory() as root:
+            path = Path(root) / 'frametop.conf'
+            path.write_text('# user settings\nPOINTER=1\nMOUSE_MODE=spatial\nMETA_DASHBOARD=0\n')
+            path.chmod(0o600)
+            ctl.save_mode('desktop', path)
+            self.assertEqual(path.read_text(), '# user settings\nPOINTER=1\nMOUSE_MODE=desktop\nMETA_DASHBOARD=0\n')
+            self.assertEqual(path.stat().st_mode & 0o777, 0o600)
+
+    def test_failed_atomic_save_preserves_old_file(self):
+        with tempfile.TemporaryDirectory() as root:
+            path = Path(root) / 'frametop.conf'
+            path.write_text('MOUSE_MODE=spatial\n')
+            with patch.object(ctl.os, 'replace', side_effect=OSError('failed')):
+                with self.assertRaises(OSError): ctl.save_mode('desktop', path)
+            self.assertEqual(path.read_text(), 'MOUSE_MODE=spatial\n')
+            self.assertEqual(list(Path(root).iterdir()), [path])
+
+
+if __name__ == '__main__': unittest.main()

layout/ft_layout.py

@@ -941,6 +941,29 @@ def send_scales(outs):
                 log(f"screen {i + 1}: scale: {reply}")
     except RuntimeError as e:
         log(f"scale: {e}")
+    finally:
+        if 'sock' in locals(): sock.sock.close()
+    # Native mouse coordinates follow the actual logical KWin output layout.
+    # Capability probing keeps this compatible with older ft-screens builds.
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as probe:
+            probe.bind(''); probe.settimeout(1)
+            probe.sendto(b'mouse?', SCREENS)
+            if not json.loads(probe.recv(8192)).get('supported'): return
+        sock = screens_socket()
+        try:
+            for i, o in enumerate(outs):
+                if not o.get('enabled', True):
+                    sock.ask(f'mouse-output-off {i+1}')
+                    continue
+                scale = float(o.get('scale', 1))
+                size, pos = o.get('size', {}), o.get('pos', {})
+                w = math.ceil(size['width']/scale - 1e-6)
+                h = math.ceil(size['height']/scale - 1e-6)
+                sock.ask(f"mouse-layout {i+1} {pos.get('x',0)} {pos.get('y',0)} {w} {h} {scale:g}")
+        finally: sock.sock.close()
+    except (OSError, ValueError, RuntimeError, KeyError):
+        pass  # old compositor, closing desktop, or a drag in progress; next layout refresh retries
 
 
 def logical_size(o):
@@ -998,6 +1021,7 @@ def apply_scales():
         if moves:
             subprocess.run(["kscreen-doctor", *moves], capture_output=True, env=env, timeout=20)
             args += moves
+            send_scales(outputs(env))
     return args
 
 

pointer/helper/ft-pointer.cpp

@@ -857,9 +857,10 @@ int main() {
     overlay->FindOverlay("system.pointer", &systemPointer);
     Vec3 pivot, tiltOrigin, lastPoint, lastOrigin, lastAim{0, 0, -1};
     Basis tiltBasis{};
+    bool desktopInput = false;  // native desktop input never claims a SteamVR hand
     bool headsetOff = false;  // nobody is wearing the headset (see the main loop)
     auto wake = [&](Clock::time_point t) {
-        if (t < noWakeUntil || headsetOff) return;
+        if (t < noWakeUntil || headsetOff || desktopInput) return;
         wokeAt = t;
         active = true;
         recenter = true;
@@ -1273,7 +1274,7 @@ int main() {
             }
             // Hand gestures in the last two minutes keep it the same way.
             const bool handsRecent = handsOn && handUsed != Clock::time_point{} && t - handUsed < std::chrono::minutes(2);
-            const bool awake = (gazeOn || handsRecent) && !inGame && !headsetOff;
+            const bool awake = (gazeOn || handsRecent) && !inGame && !headsetOff && !desktopInput;
             if (awake != gazeAwake || t - gazeAwakeAt > std::chrono::seconds(5)) {
                 if (awake != gazeAwake)
                     std::printf("%s keeps the pointer: %s\n", gazeOn ? "gaze" : "hand use",
@@ -1365,6 +1366,34 @@ int main() {
                 reply(controllerButtons.Status());
                 continue;
             }
+            if (std::strcmp(buf, "pointerstatus") == 0) {
+                char msg[256];
+                const int role = ours == vr::k_unTrackedDeviceIndexInvalid ? 0 :
+                    int(vr::VRSystem()->GetControllerRoleForTrackedDeviceIndex(ours));
+                std::snprintf(msg, sizeof msg,
+                    "{\"active\":%s,\"headsetOff\":%s,\"gazeMode\":%s,\"handRole\":%d,\"desktopInput\":%s}",
+                    active ? "true" : "false", headsetOff ? "true" : "false",
+                    gazeOn ? "true" : "false", role, desktopInput ? "true" : "false");
+                reply(msg);
+                continue;
+            }
+            if (std::strncmp(buf, "desktopmouse ", 13) == 0) {
+                if (std::strcmp(buf+13, "on") && std::strcmp(buf+13, "off")) {
+                    reply("error desktopmouse on|off");
+                    continue;
+                }
+                desktopInput = std::strcmp(buf+13, "on") == 0;
+                if (desktopInput) {
+                    if (leftHeld) releaseLeft();
+                    active = claimPending = claimHeld = false;
+                    overlay->HideOverlay(cursor); overlay->HideOverlay(marker);
+                    SendTo(out, "ft_pointer", "scroll 0 0");
+                    SendTo(out, "ft_pointer", "btn a 0");
+                    SendTo(out, "ft_pointer", "hide");
+                }
+                reply("ok");
+                continue;
+            }
             if (std::strncmp(buf, "overlays", 8) == 0) {
                 overlays.Request(sender, senderLen);  // answered from the list's thread
                 continue;
@@ -1752,6 +1781,7 @@ int main() {
             hp = std::asin(std::clamp(f.y, -1.0, 1.0)) * 180 / M_PI;
             return true;
         };
+        if (desktopInput) keyPresses.clear();
         for (const KeyPress &k : keyPresses) {
             (k.right ? keyRightDown : keyLeftDown) = k.down;
             if (!k.down) {
@@ -1841,7 +1871,7 @@ int main() {
                 handBaseline = true, handOpens = handFile.opens;
             }
             // Not over a VR game (unless the dashboard is up), and not with the headset off.
-            const bool allowed = !headsetOff && (!inGame || overlay->IsDashboardVisible());
+            const bool allowed = !desktopInput && !headsetOff && (!inGame || overlay->IsDashboardVisible());
             for (int k = 1; k >= 0; --k)  // grips first: one takes over a pinch
                 for (int s = 0; s < 2; ++s) {
                     const fh_pinch_t &g = slots[k][s];

screens/compositor.c

@@ -25,8 +25,11 @@
 //   COMMAND     run with WAYLAND_DISPLAY set to our socket (e.g. the Frametop session)
 // Runs in the dev container (wlroots 0.20); KWin connects from the host.
 #define _GNU_SOURCE
+#include "controller-fallback.h"
+#include "desktop-handoff.h"
 #include <drm_fourcc.h>
 #include <linux/input-event-codes.h>
+#include <math.h>
 #include <signal.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -58,8 +61,11 @@
 #include <wlr/util/log.h>
 
 #include "vr.h"
+#include "desktop-mouse.h"
+#include "desktop-cursor.h"
+#include "cursor-cache.h"
 
-#define MAX_SCREENS 24  // screens and spare outputs
+#define MAX_SCREENS FT_MOUSE_OUTPUTS  // screens and spare outputs
 
 struct config {
     int width, height;
@@ -104,6 +110,23 @@ struct server {
     struct wl_list buffers;  // tracked_buffer
     struct wl_event_source *tick;
     struct screen *pointer_focus;
+    bool desktop_mouse, cursor_ready, cursor_frame_pending;
+    struct ft_controller_fallback controller_fallback;
+    bool controller_desktop;
+    struct ft_handoff handoff;
+    struct ft_event controller_position[MAX_SCREENS];
+    bool controller_position_known[MAX_SCREENS];
+    unsigned long mouse_events_ignored;
+    uint32_t controller_buttons;
+    struct ft_cursor_cache cursor_cache;
+    const char *cursor_error;
+    const char *cursor_buffer;
+    struct wlr_buffer *cursor_held;
+    struct ft_mouse mouse;
+    struct wlr_surface *cursor_surface;
+    int cursor_hx, cursor_hy;
+    struct wl_listener request_cursor, cursor_commit, cursor_destroy;
+    unsigned long mouse_motions, mouse_clicks, mouse_wheels, vr_mouse_ignored;
     pid_t child;
     // Where typing goes: the screens after a click on one, Steam after a click on another
     // panel. The input relay grabs the keyboards while it's the screens (see keys_update).
@@ -201,6 +224,8 @@ static void screen_destroy(struct wl_listener *l, void *data) {
     if (sc->held) wlr_buffer_unlock(sc->held);
     ft_vr_screen_destroy(sc->index);
     if (sc->server->pointer_focus == sc) sc->server->pointer_focus = NULL;
+    sc->server->mouse.outputs[sc->index].enabled = false;
+    if (sc->server->mouse.grab == sc->index) sc->server->mouse.buttons = 0, sc->server->mouse.grab = -1;
     if (sc->decoration) wl_list_remove(&sc->decoration_destroy.link);
     sc->server->screens[sc->index] = NULL;
     wl_list_remove(&sc->commit.link);
@@ -275,7 +300,7 @@ static void new_decoration(struct wl_listener *l, void *data) {
 
 static void panel_key(struct server *s, uint32_t code, bool pressed);
 
-static void handle_vr_event(const struct ft_event *e, void *data) {
+static void deliver_pointer_event(const struct ft_event *e, void *data) {
     struct server *s = data;
     if (e->type == FT_QUIT) {
         wl_display_terminate(s->display);
@@ -294,20 +319,6 @@ 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) {
@@ -349,11 +360,11 @@ static void handle_vr_event(const struct ft_event *e, void *data) {
             }
             if (e->dy != 0)
                 wlr_seat_pointer_notify_axis(s->seat, t, WL_POINTER_AXIS_VERTICAL_SCROLL, e->dy * 15,
-                                             (int32_t)(e->dy * 120), WL_POINTER_AXIS_SOURCE_WHEEL,
+                                             (int32_t)llround(e->dy * 120), WL_POINTER_AXIS_SOURCE_WHEEL,
                                              WL_POINTER_AXIS_RELATIVE_DIRECTION_IDENTICAL);
             if (e->dx != 0)
                 wlr_seat_pointer_notify_axis(s->seat, t, WL_POINTER_AXIS_HORIZONTAL_SCROLL, e->dx * 15,
-                                             (int32_t)(e->dx * 120), WL_POINTER_AXIS_SOURCE_WHEEL,
+                                             (int32_t)llround(e->dx * 120), WL_POINTER_AXIS_SOURCE_WHEEL,
                                              WL_POINTER_AXIS_RELATIVE_DIRECTION_IDENTICAL);
             break;
         case FT_LEAVE:
@@ -368,11 +379,185 @@ static void handle_vr_event(const struct ft_event *e, void *data) {
     wlr_seat_pointer_notify_frame(s->seat);
 }
 
+static void set_desktop_owner(struct server *s, bool pointer) {
+    if (pointer == s->controller_desktop) return;
+    // Claims are refused during a held drag. Legacy disconnect recovery may
+    // still revoke a stale controller, releasing its buttons safely.
+    for (unsigned bit = 0; bit < 8; ++bit)
+        if (s->controller_buttons & (1u << bit))
+            wlr_seat_pointer_notify_button(s->seat, now_ms(), BTN_LEFT+bit,
+                                           WL_POINTER_BUTTON_STATE_RELEASED);
+    s->controller_buttons = 0;
+    wlr_seat_pointer_notify_clear_focus(s->seat);
+    wlr_seat_pointer_notify_frame(s->seat);
+    s->pointer_focus = NULL;
+    s->controller_desktop = pointer;
+    wlr_log(WLR_INFO, "desktop owner %s (policy %s)", pointer ? "pointer" : "mouse",
+            ft_handoff_name(s->handoff.policy));
+    ft_vr_cursor_move(-1, 0, 0, 1, false);
+}
+
+static void update_controller_fallback(struct server *s) {
+    bool active = s->desktop_mouse && !s->mouse.buttons &&
+        ft_fallback_active(&s->controller_fallback, now_ms());
+    if (s->desktop_mouse && s->handoff.policy != FT_PREFER_MOUSE) {
+        active = s->controller_desktop;
+        if (!s->mouse.buttons && !s->controller_buttons &&
+            (s->handoff.policy == FT_PREFER_POINTER ||
+             ft_fallback_active(&s->controller_fallback, now_ms()))) active = true;
+    }
+    set_desktop_owner(s, active);
+}
+
+static bool claim_desktop_mouse(struct server *s) {
+    if (!ft_handoff_claim(&s->handoff, false, now_ms(), s->mouse.buttons, s->controller_buttons)) {
+        ++s->mouse_events_ignored;
+        return false;
+    }
+    ft_fallback_presence(&s->controller_fallback, true, s->controller_fallback.enabled, now_ms());
+    set_desktop_owner(s, false);
+    return true;
+}
+
+static void handle_vr_event(const struct ft_event *e, void *data) {
+    struct server *s = data;
+    // Events here are panel content, not SteamVR or separate screen grab bars.
+    bool desktop = e->screen >= 0 && e->screen < s->n_config;
+    if (desktop && e->type == FT_MOTION) {
+        s->controller_position[e->screen] = *e;
+        s->controller_position_known[e->screen] = true;
+    }
+    update_controller_fallback(s);
+    if (s->desktop_mouse && desktop) {
+        bool pointer_event = e->type == FT_MOTION || e->type == FT_BUTTON ||
+                             e->type == FT_SCROLL || e->type == FT_LEAVE;
+        uint32_t bit = e->type == FT_BUTTON && e->button >= BTN_LEFT && e->button < BTN_LEFT+8
+            ? 1u << (e->button-BTN_LEFT) : 0;
+        bool action = (e->type == FT_BUTTON && e->pressed && bit) ||
+                      (e->type == FT_SCROLL && (e->dx != 0 || e->dy != 0));
+        if (action && s->handoff.policy != FT_PREFER_MOUSE &&
+            ft_handoff_claim(&s->handoff, true, now_ms(), s->mouse.buttons, s->controller_buttons)) {
+            set_desktop_owner(s, true);
+            if (e->type == FT_SCROLL && s->controller_position_known[e->screen])
+                deliver_pointer_event(&s->controller_position[e->screen], s);
+        }
+        if (pointer_event && (!s->controller_desktop || s->mouse.buttons ||
+            (e->type == FT_BUTTON && !e->pressed && !(s->controller_buttons & bit)) ||
+            (e->type == FT_LEAVE && s->controller_buttons))) {
+            ++s->vr_mouse_ignored; return;
+        }
+        if (bit) {
+            if (e->pressed) s->controller_buttons |= bit;
+            else s->controller_buttons &= ~bit;
+        }
+    }
+    deliver_pointer_event(e, data);
+}
+
+static void desktop_motion(struct server *s) {
+    int index = ft_mouse_target(&s->mouse);
+    if (index < 0 || !s->screens[index]) return;
+    const struct ft_mouse_output *o = &s->mouse.outputs[index];
+    struct ft_event event = {.type = FT_MOTION, .screen = index,
+        .x = (s->mouse.x-o->x)*o->scale, .y = (s->mouse.y-o->y)*o->scale};
+    deliver_pointer_event(&event, s);
+    const struct ft_mouse_output *display = &s->mouse.outputs[s->mouse.screen];
+    ft_vr_cursor_move(s->mouse.screen, (s->mouse.x-display->x)*display->scale,
+                     (s->mouse.y-display->y)*display->scale, display->scale, s->desktop_mouse);
+}
+
+static void cursor_hide(struct server *s) {
+    ft_vr_cursor_image(NULL, 0, 0, 0, 0, 1);
+    if (s->cursor_held) wlr_buffer_unlock(s->cursor_held);
+    s->cursor_held = NULL;
+}
+static void cursor_update(struct server *s) {
+    struct wlr_surface *surface = s->cursor_surface;
+    struct wlr_buffer *buffer = surface ? ft_cursor_cached(&s->cursor_cache, surface) : NULL;
+    s->cursor_ready = false;
+    s->cursor_error = "no cached KDE cursor buffer";
+    if (surface) s->cursor_frame_pending = true;
+    s->cursor_buffer = "none";
+    if (!buffer) { cursor_hide(s); return; }
+    if (buffer->width < 1 || buffer->height < 1 || buffer->width > 512 || buffer->height > 512) {
+        cursor_hide(s); return;
+    }
+    int scale = surface->current.scale > 0 ? surface->current.scale : 1;
+    if (scale > 8 || s->cursor_hx < -512 || s->cursor_hy < -512 || s->cursor_hx > 512 || s->cursor_hy > 512) {
+        s->cursor_error = "invalid cursor scale or hotspot";
+        cursor_hide(s); return;
+    }
+    struct wlr_dmabuf_attributes dma;
+    if (wlr_buffer_get_dmabuf(buffer, &dma)) {
+        s->cursor_buffer = "dmabuf";
+        struct ft_dmabuf b = {.width = dma.width, .height = dma.height, .format = dma.format,
+                             .modifier = dma.modifier, .n_planes = dma.n_planes};
+        for (int i = 0; i < dma.n_planes && i < 4; ++i) {
+            b.offset[i] = dma.offset[i]; b.stride[i] = dma.stride[i]; b.fd[i] = dma.fd[i];
+        }
+        track_buffer(s, buffer);
+        s->cursor_ready = ft_vr_cursor_dmabuf(buffer, &b, s->cursor_hx*scale, s->cursor_hy*scale, scale);
+        s->cursor_error = s->cursor_ready ? "" : "SteamVR rejected GPU cursor";
+        if (s->cursor_ready) {
+            wlr_buffer_lock(buffer);
+            if (s->cursor_held) wlr_buffer_unlock(s->cursor_held);
+            s->cursor_held = buffer;
+        } else cursor_hide(s);
+        return;
+    }
+    s->cursor_buffer = "shm";
+    void *data; uint32_t format; size_t stride;
+    if (!wlr_buffer_begin_data_ptr_access(buffer, WLR_BUFFER_DATA_PTR_ACCESS_READ, &data, &format, &stride)) {
+        s->cursor_error = "KDE cursor buffer cannot be read";
+        cursor_hide(s); return;
+    }
+    uint8_t *rgba = malloc((size_t)buffer->width*buffer->height*4);
+    s->cursor_error = "unsupported cursor format or allocation failed";
+    if (rgba && ft_cursor_rgba(rgba, data, buffer->width, buffer->height, stride, format)) {
+        s->cursor_error = "SteamVR rejected cursor texture";
+        s->cursor_ready = ft_vr_cursor_image(rgba, buffer->width, buffer->height,
+                                            s->cursor_hx*scale, s->cursor_hy*scale, scale);
+        if (s->cursor_ready) s->cursor_error = "";
+    }
+    free(rgba);
+    wlr_buffer_end_data_ptr_access(buffer);
+    if (!s->cursor_ready) cursor_hide(s);
+    else if (s->cursor_held) { wlr_buffer_unlock(s->cursor_held); s->cursor_held = NULL; }
+}
+
+static void cursor_committed(struct wl_listener *l, void *data) {
+    struct server *s = wl_container_of(l, s, cursor_commit);
+    cursor_update(s);
+}
+static void cursor_destroyed(struct wl_listener *l, void *data) {
+    struct server *s = wl_container_of(l, s, cursor_destroy);
+    wl_list_remove(&s->cursor_commit.link); wl_list_remove(&s->cursor_destroy.link);
+    s->cursor_surface = NULL; s->cursor_ready = false;
+    cursor_hide(s);
+}
+static void cursor_requested(struct wl_listener *l, void *data) {
+    struct server *s = wl_container_of(l, s, request_cursor);
+    struct wlr_seat_pointer_request_set_cursor_event *e = data;
+    if (e->seat_client != s->seat->pointer_state.focused_client) return;
+    if (s->cursor_surface) {
+        wl_list_remove(&s->cursor_commit.link); wl_list_remove(&s->cursor_destroy.link);
+    }
+    s->cursor_surface = e->surface; s->cursor_hx = e->hotspot_x; s->cursor_hy = e->hotspot_y;
+    if (e->surface) {
+        s->cursor_commit.notify = cursor_committed;
+        s->cursor_destroy.notify = cursor_destroyed;
+        wl_signal_add(&e->surface->events.commit, &s->cursor_commit);
+        wl_signal_add(&e->surface->events.destroy, &s->cursor_destroy);
+    }
+    cursor_update(s);
+}
+
 // Tell the input relay where typing goes, on a change and every second: while it's the
 // desktop, the relay grabs pass-through keyboards so SteamVR (and the Steam app with
 // gamescope's focus) doesn't get the keys too. Without word from us for a few seconds,
 // the relay gives the keyboards back, so a closed desktop doesn't keep them.
 static void keys_update(struct server *s) {
+    if (!s->vr) return;  // the isolated test desktop must never route live keyboards
     if (!s->vr) return;  // a test instance leaves the running desktop's keyboards alone
     const bool desktop = s->keys_clicked && ft_vr_screens_shown();
     const uint32_t t = now_ms();
@@ -391,6 +576,7 @@ static void keys_update(struct server *s) {
 // Every ~11 ms (90 Hz): SteamVR events, and frame callbacks for screens that committed.
 static int tick(void *data) {
     struct server *s = data;
+    update_controller_fallback(s);
     ft_vr_poll(handle_vr_event, s);
     if (++s->ticks % 9 == 0) keys_update(s);
     if (s->kb_close_at && s->ticks >= s->kb_close_at) {
@@ -402,6 +588,10 @@ static int tick(void *data) {
     }
     struct timespec now;
     clock_gettime(CLOCK_MONOTONIC, &now);
+    if (s->cursor_surface && s->cursor_frame_pending) {
+        s->cursor_frame_pending = false;
+        wlr_surface_send_frame_done(s->cursor_surface, &now);
+    }
     for (int i = 0; i < MAX_SCREENS; ++i) {
         struct screen *sc = s->screens[i];
         if (sc && sc->frame_pending) {
@@ -527,8 +717,121 @@ static int control_readable(int fd, uint32_t mask, void *data) {
         buf[n] = 0;
         unsigned code;
         int value, index, w, h;
-        double scale;
-        if (sscanf(buf, "size %d %d %d", &index, &w, &h) == 3) {
+        double scale, wheel_x, wheel_y;
+        double mx, my, mw, mh;
+        char mode[16], tail;
+        if (strcmp(buf, "desktop-policy?") == 0) {
+            snprintf(reply, sizeof reply,
+                "{\"supported\":true,\"policy\":\"%s\",\"owner\":\"%s\",\"mouseButtons\":%u,\"pointerButtons\":%u,\"mouseEventsIgnored\":%lu}",
+                ft_handoff_name(s->handoff.policy), s->controller_desktop ? "pointer" : "mouse",
+                s->mouse.buttons, s->controller_buttons, s->mouse_events_ignored);
+        } else if (sscanf(buf, "desktop-policy %15s %c", mode, &tail) == 1) {
+            if (s->mouse.buttons || s->controller_buttons ||
+                (strcmp(mode, "mouse") && strcmp(mode, "pointer") && strcmp(mode, "last-active")))
+                snprintf(reply, sizeof reply, "error policy or held button");
+            else {
+                s->handoff = (struct ft_handoff){.policy = !strcmp(mode, "last-active") ? FT_LAST_ACTIVE :
+                    !strcmp(mode, "pointer") ? FT_PREFER_POINTER : FT_PREFER_MOUSE};
+                set_desktop_owner(s, s->handoff.policy == FT_PREFER_POINTER);
+                update_controller_fallback(s);
+                snprintf(reply, sizeof reply, "ok");
+            }
+        } else if (strcmp(buf, "mouse-presence?") == 0) {
+            snprintf(reply, sizeof reply,
+                     "{\"supported\":true,\"known\":%s,\"present\":%s,\"enabled\":%s,\"controllerDesktop\":%s,\"fresh\":%s}",
+                     s->controller_fallback.known ? "true" : "false",
+                     s->controller_fallback.present ? "true" : "false",
+                     s->controller_fallback.enabled ? "true" : "false",
+                     s->controller_desktop ? "true" : "false",
+                     s->controller_fallback.known && (uint32_t)(now_ms()-s->controller_fallback.received)<3000 ? "true" : "false");
+        } else if (sscanf(buf, "mouse-presence %d %d %c", &index, &value, &tail) == 2) {
+            if ((index != 0 && index != 1) || (value != 0 && value != 1))
+                snprintf(reply, sizeof reply, "error invalid presence");
+            else {
+                ft_fallback_presence(&s->controller_fallback, index, value, now_ms());
+                update_controller_fallback(s);
+                snprintf(reply, sizeof reply, "ok");
+            }
+        } else if (strcmp(buf, "mouse?") == 0) {
+            snprintf(reply, sizeof reply,
+                "{\"supported\":true,\"mode\":\"%s\",\"screen\":%d,\"x\":%.3f,\"y\":%.3f,"
+                "\"buttons\":%u,\"cursorReady\":%s,\"cursorSource\":\"kde\",\"cursorCache\":true,\"cursorBuffer\":\"%s\",\"cursorError\":\"%s\","
+                "\"motionEvents\":%lu,\"buttonEvents\":%lu,\"wheelEvents\":%lu,\"controllerEventsIgnored\":%lu}",
+                s->desktop_mouse ? "desktop" : "spatial", s->mouse.screen+1, s->mouse.x, s->mouse.y,
+                s->mouse.buttons, s->cursor_ready ? "true" : "false", s->cursor_buffer ? s->cursor_buffer : "none", s->cursor_error ? s->cursor_error : "no cursor request", s->mouse_motions,
+                s->mouse_clicks, s->mouse_wheels, s->vr_mouse_ignored);
+        } else if (sscanf(buf, "mouse-output-off %d %c", &index, &tail) == 1) {
+            if (index < 1 || index > MAX_SCREENS || s->mouse.buttons)
+                snprintf(reply, sizeof reply, "error invalid mouse output or held button");
+            else { s->mouse.outputs[index-1].enabled = false; snprintf(reply, sizeof reply, "ok"); }
+        } else if (sscanf(buf, "mouse-layout %d %lf %lf %lf %lf %lf %c", &index, &mx, &my, &mw, &mh, &scale, &tail) == 6) {
+            if (index < 1 || index > MAX_SCREENS || !s->screens[index-1] ||
+                !ft_mouse_output_set(&s->mouse, index-1, mx, my, mw, mh, scale))
+                snprintf(reply, sizeof reply, "error invalid mouse output or held button");
+            else { s->scale[index-1] = scale; snprintf(reply, sizeof reply, "ok"); }
+        } else if (sscanf(buf, "mouse-mode %15s %c", mode, &tail) == 1) {
+            if (s->mouse.buttons || s->controller_buttons || (strcmp(mode, "desktop") && strcmp(mode, "spatial")))
+                snprintf(reply, sizeof reply, "error mouse mode or held button");
+            else if (!strcmp(mode, "desktop") && !ft_mouse_move(&s->mouse, 0, 0))
+                snprintf(reply, sizeof reply, "error configure mouse layout first");
+            else {
+                s->desktop_mouse = !strcmp(mode, "desktop");
+                if (s->desktop_mouse) desktop_motion(s);
+                else {
+                    wlr_seat_pointer_notify_clear_focus(s->seat); s->pointer_focus = NULL;
+                    wlr_seat_pointer_notify_frame(s->seat);
+                    ft_vr_cursor_move(-1, 0, 0, 1, false);
+                }
+                snprintf(reply, sizeof reply, "ok");
+            }
+        } else if (sscanf(buf, "mouse-move %lf %lf %c", &mx, &my, &tail) == 2) {
+            if (!s->desktop_mouse || (s->vr && !ft_vr_screens_shown()) || !isfinite(mx) || !isfinite(my) || fabs(mx)>16384 || fabs(my)>16384)
+                snprintf(reply, sizeof reply, "error desktop mouse unavailable or invalid motion");
+            else { if ((mx != 0 || my != 0) && claim_desktop_mouse(s) && ft_mouse_move(&s->mouse, mx, my)) { desktop_motion(s); ++s->mouse_motions; } snprintf(reply, sizeof reply, "ok"); }
+        } else if (sscanf(buf, "mouse-position %d %lf %lf %c", &index, &mx, &my, &tail) == 3) {
+            if (!s->desktop_mouse || s->mouse.buttons || s->controller_buttons || index < 1 || index > MAX_SCREENS ||
+                !s->mouse.outputs[index-1].enabled || !isfinite(mx) || !isfinite(my) ||
+                mx < 0 || my < 0 || mx >= s->mouse.outputs[index-1].width || my >= s->mouse.outputs[index-1].height)
+                snprintf(reply, sizeof reply, "error mouse position or held button");
+            else {
+                ft_mouse_position(&s->mouse, s->mouse.outputs[index-1].x+mx, s->mouse.outputs[index-1].y+my);
+                if (claim_desktop_mouse(s)) desktop_motion(s);
+                snprintf(reply, sizeof reply, "ok");
+            }
+        } else if (sscanf(buf, "mouse-button %u %d %c", &code, &value, &tail) == 2) {
+            if (!s->desktop_mouse || (value != 0 && value != 1) ||
+                (s->vr && !ft_vr_screens_shown() && value) || code < BTN_LEFT || code > BTN_TASK)
+                snprintf(reply, sizeof reply, "error mouse button or hidden desktop");
+            else if ((!value && !(s->mouse.buttons & (1u << (code-BTN_LEFT)))) || !claim_desktop_mouse(s))
+                snprintf(reply, sizeof reply, "ok");
+            else {
+                desktop_motion(s);
+                int target = ft_mouse_target(&s->mouse);
+                const struct ft_mouse_output *o = target >= 0 ? &s->mouse.outputs[target] : NULL;
+                if (!o || !s->screens[target]) snprintf(reply, sizeof reply, "error no mouse surface");
+                else {
+                    struct ft_event event = {.type = FT_BUTTON, .screen = target, .button = code, .pressed = value,
+                        .x = (s->mouse.x-o->x)*o->scale, .y = (s->mouse.y-o->y)*o->scale};
+                    deliver_pointer_event(&event, s);
+                    ft_mouse_button(&s->mouse, code, value); ++s->mouse_clicks;
+                    if (!s->mouse.buttons) desktop_motion(s);
+                    snprintf(reply, sizeof reply, "ok");
+                }
+            }
+        } else if (sscanf(buf, "mouse-wheel %lf %lf %c", &wheel_x, &wheel_y, &tail) == 2) {
+            int target = ft_mouse_target(&s->mouse);
+            if (!s->desktop_mouse || (s->vr && !ft_vr_screens_shown()) || target < 0 || !s->screens[target] ||
+                !s->mouse.outputs[target].enabled ||
+                !isfinite(wheel_x) || !isfinite(wheel_y) || fabs(wheel_x)>120 || fabs(wheel_y)>120)
+                snprintf(reply, sizeof reply, "error mouse wheel or hidden desktop");
+            else if ((wheel_x == 0 && wheel_y == 0) || !claim_desktop_mouse(s))
+                snprintf(reply, sizeof reply, "ok");
+            else {
+                desktop_motion(s);
+                struct ft_event event = {.type = FT_SCROLL, .screen = target, .dx = wheel_x, .dy = -wheel_y};
+                deliver_pointer_event(&event, s); ++s->mouse_wheels; snprintf(reply, sizeof reply, "ok");
+            }
+        } else if (sscanf(buf, "size %d %d %d", &index, &w, &h) == 3) {
             // A new resolution for a screen, live: KWin resizes the screen to match. (KWin makes
             // it this size times its scale; ft-floatd sends spares' sizes divided by theirs.)
             const int min_w = index - 1 < s->n_config ? 320 : 64, min_h = index - 1 < s->n_config ? 200 : 64;
@@ -567,11 +870,13 @@ static int control_readable(int fd, uint32_t mask, void *data) {
             else if (strcmp(button, "middle") == 0) e.button = BTN_MIDDLE;
             if (got >= 2 && strcmp(what, "leave") == 0) e.type = FT_LEAVE;
             else if (got >= 4 && strcmp(what, "move") == 0) e.type = FT_MOTION;
+            else if (got >= 4 && strcmp(what, "scroll") == 0 && isfinite(x) && isfinite(y) && fabs(x)<=120 && fabs(y)<=120)
+                e.type = FT_SCROLL, e.dx = x, e.dy = y;
             else if (got >= 4 && (strcmp(what, "down") == 0 || strcmp(what, "up") == 0))
                 e.type = FT_BUTTON, e.pressed = what[0] == 'd';
             else index = 0;
             if (index < 1 || index > MAX_SCREENS || !s->screens[index - 1]) {
-                snprintf(reply, sizeof reply, "error input <screen> move|down|up|leave [x y [button]]");
+                snprintf(reply, sizeof reply, "error input <screen> move|down|up|scroll|leave [x y [button]]");
             } else {
                 handle_vr_event(&e, s);
                 snprintf(reply, sizeof reply, "ok");
@@ -655,6 +960,7 @@ static bool setup_dmabuf(struct server *s) {
 
 int main(int argc, char **argv) {
     struct server s = {0};
+    ft_mouse_init(&s.mouse);
     for (int i = 0; i < MAX_SCREENS; ++i) s.scale[i] = 1;
     s.kb_screen = -1;
     const char *socket_name = "ft-screens-0", *control_name = "ft_screens";
@@ -699,7 +1005,8 @@ int main(int argc, char **argv) {
     s.display = wl_display_create();
     s.loop = wl_display_get_event_loop(s.display);
     wl_list_init(&s.buffers);
-    wlr_compositor_create(s.display, 6, NULL);
+    struct wlr_compositor *compositor = wlr_compositor_create(s.display, 6, NULL);
+    ft_cursor_cache_init(&s.cursor_cache, compositor);
     wlr_subcompositor_create(s.display);
     const uint32_t shm_formats[] = {DRM_FORMAT_ARGB8888, DRM_FORMAT_XRGB8888};  // wlroots wants DRM codes
     wlr_shm_create(s.display, 1, shm_formats, 2);
@@ -714,6 +1021,8 @@ int main(int argc, char **argv) {
     wl_signal_add(&s.decoration->events.new_toplevel_decoration, &s.new_decoration);
 
     s.seat = wlr_seat_create(s.display, "seat0");
+    s.request_cursor.notify = cursor_requested;
+    wl_signal_add(&s.seat->events.request_set_cursor, &s.request_cursor);
     wlr_keyboard_init(&s.keyboard, &keyboard_impl, "ft-screens-keyboard");
     struct xkb_context *xkb = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
     struct xkb_keymap *keymap = xkb_keymap_new_from_names(xkb, NULL, XKB_KEYMAP_COMPILE_NO_FLAGS);
@@ -760,6 +1069,7 @@ int main(int argc, char **argv) {
     // wlroots asserts that nothing still listens to its globals when they go.
     wl_list_remove(&s.new_toplevel.link);
     wl_list_remove(&s.new_decoration.link);
+    ft_cursor_cache_finish(&s.cursor_cache);
     ft_vr_shutdown();
     wl_display_destroy(s.display);
     return 0;

screens/controller-fallback.h

@@ -0,0 +1,19 @@
+#ifndef FT_CONTROLLER_FALLBACK_H
+#define FT_CONTROLLER_FALLBACK_H
+#include <stdbool.h>
+#include <stdint.h>
+struct ft_controller_fallback {
+    bool known, present, enabled;
+    uint32_t received, absent_since;
+};
+static inline void ft_fallback_presence(struct ft_controller_fallback *f,
+                                       bool present, bool enabled, uint32_t now) {
+    if (!f->known || (uint32_t)(now-f->received) >= 3000 || f->present || present)
+        f->absent_since = now;
+    f->known = true; f->present = present; f->enabled = enabled; f->received = now;
+}
+static inline bool ft_fallback_active(const struct ft_controller_fallback *f, uint32_t now) {
+    return f->known && f->enabled && !f->present &&
+        (uint32_t)(now-f->received) < 3000 && (uint32_t)(now-f->absent_since) >= 1000;
+}
+#endif

screens/cursor-cache.h

@@ -0,0 +1,67 @@
+#pragma once
+#include <stdlib.h>
+#include <wayland-server-core.h>
+#include <wlr/types/wlr_buffer.h>
+#include <wlr/types/wlr_compositor.h>
+
+// A rendererless compositor has no persistent surface texture. wlroots releases
+// current.buffer after each commit callback. KDE commits a cursor before issuing
+// set_cursor, so retain small buffers from the first commit, not from set_cursor.
+// This also keeps animation/callback-only commits from erasing the last image.
+struct ft_cursor_cache;
+struct ft_cursor_frame {
+    struct ft_cursor_cache *cache;
+    struct wlr_surface *surface;
+    struct wlr_buffer *buffer;
+    struct wl_listener commit, destroy;
+    struct wl_list link;
+};
+struct ft_cursor_cache {
+    struct wl_listener new_surface;
+    struct wl_list frames;
+};
+static inline struct wlr_buffer *ft_cursor_cached(struct ft_cursor_cache *cache, struct wlr_surface *surface) {
+    struct ft_cursor_frame *f;
+    wl_list_for_each(f, &cache->frames, link) if (f->surface == surface) return f->buffer;
+    return NULL;
+}
+static inline void ft_cursor_frame_committed(struct wl_listener *listener, void *data) {
+    (void)data;
+    struct ft_cursor_frame *f = wl_container_of(listener, f, commit);
+    if (!(f->surface->current.committed & WLR_SURFACE_STATE_BUFFER)) return;
+    struct wlr_buffer *buffer = f->surface->current.buffer;
+    // Desktop DMA-BUFs go straight to SteamVR; do not retain them here.
+    struct wlr_buffer *next = buffer && buffer->width > 0 && buffer->height > 0 &&
+        buffer->width <= 512 && buffer->height <= 512 ? wlr_buffer_lock(buffer) : NULL;
+    if (f->buffer) wlr_buffer_unlock(f->buffer);
+    f->buffer = next;
+}
+static inline void ft_cursor_frame_destroyed(struct wl_listener *listener, void *data) {
+    (void)data;
+    struct ft_cursor_frame *f = wl_container_of(listener, f, destroy);
+    wl_list_remove(&f->commit.link); wl_list_remove(&f->destroy.link); wl_list_remove(&f->link);
+    if (f->buffer) wlr_buffer_unlock(f->buffer);
+    free(f);
+}
+static inline void ft_cursor_surface_created(struct wl_listener *listener, void *data) {
+    struct ft_cursor_cache *cache = wl_container_of(listener, cache, new_surface);
+    struct wlr_surface *surface = data;
+    struct ft_cursor_frame *f = calloc(1, sizeof *f);
+    if (!f) { wl_client_post_no_memory(wl_resource_get_client(surface->resource)); return; }
+    f->cache = cache; f->surface = surface;
+    f->commit.notify = ft_cursor_frame_committed;
+    f->destroy.notify = ft_cursor_frame_destroyed;
+    wl_signal_add(&surface->events.commit, &f->commit);
+    wl_signal_add(&surface->events.destroy, &f->destroy);
+    wl_list_insert(&cache->frames, &f->link);
+}
+static inline void ft_cursor_cache_init(struct ft_cursor_cache *cache, struct wlr_compositor *compositor) {
+    wl_list_init(&cache->frames);
+    cache->new_surface.notify = ft_cursor_surface_created;
+    wl_signal_add(&compositor->events.new_surface, &cache->new_surface);
+}
+static inline void ft_cursor_cache_finish(struct ft_cursor_cache *cache) {
+    wl_list_remove(&cache->new_surface.link);
+    struct ft_cursor_frame *f, *tmp;
+    wl_list_for_each_safe(f, tmp, &cache->frames, link) ft_cursor_frame_destroyed(&f->destroy, NULL);
+}

screens/desktop-cursor.h

@@ -0,0 +1,26 @@
+#pragma once
+#include <drm_fourcc.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+// Shared-memory Wayland cursor images use ARGB with premultiplied alpha.
+// SteamVR's raw overlay texture is RGBA. Respect padding and recover RGB at edges.
+static inline bool ft_cursor_rgba(uint8_t *out, const void *data, int w, int h,
+                                  size_t stride, uint32_t format) {
+    if (!data || w < 1 || h < 1 || w > 512 || h > 512 || stride < (size_t)w*4 ||
+        (format != DRM_FORMAT_ARGB8888 && format != DRM_FORMAT_ABGR8888 &&
+         format != DRM_FORMAT_XRGB8888 && format != DRM_FORMAT_XBGR8888)) return false;
+    const bool swap = format == DRM_FORMAT_ABGR8888 || format == DRM_FORMAT_XBGR8888;
+    const bool opaque = format == DRM_FORMAT_XRGB8888 || format == DRM_FORMAT_XBGR8888;
+    for (int y = 0; y < h; ++y) for (int x = 0; x < w; ++x) {
+        uint32_t v; memcpy(&v, (const uint8_t *)data + (size_t)y*stride + x*4, 4);
+        unsigned a = opaque ? 255 : v >> 24;
+        unsigned rgb[3] = {swap ? v & 255 : (v >> 16) & 255, (v >> 8) & 255,
+                           swap ? (v >> 16) & 255 : v & 255};
+        uint8_t *p = out + ((size_t)y*w+x)*4;
+        for (int c = 0; c < 3; ++c) { unsigned n = a ? (rgb[c]*255 + a/2)/a : 0; p[c] = n > 255 ? 255 : n; }
+        p[3] = a;
+    }
+    return true;
+}

screens/desktop-handoff.h

@@ -0,0 +1,24 @@
+#ifndef FT_DESKTOP_HANDOFF_H
+#define FT_DESKTOP_HANDOFF_H
+#include <stdbool.h>
+#include <stdint.h>
+enum ft_handoff_policy { FT_PREFER_MOUSE, FT_LAST_ACTIVE, FT_PREFER_POINTER };
+struct ft_handoff { enum ft_handoff_policy policy; bool mouse_seen; uint32_t mouse_at; };
+// Only deliberate desktop actions call this. Tracking motion never claims a seat.
+static inline bool ft_handoff_claim(struct ft_handoff *h, bool pointer,
+                                    uint32_t now, uint32_t mouse_buttons,
+                                    uint32_t pointer_buttons) {
+    if (pointer) {
+        if (mouse_buttons || h->policy == FT_PREFER_MOUSE) return false;
+        if (h->policy == FT_LAST_ACTIVE && !pointer_buttons && h->mouse_seen && now == h->mouse_at)
+            return false; // Same millisecond: native mouse wins.
+    } else {
+        if (pointer_buttons || h->policy == FT_PREFER_POINTER) return false;
+        h->mouse_seen = true; h->mouse_at = now;
+    }
+    return true;
+}
+static inline const char *ft_handoff_name(enum ft_handoff_policy p) {
+    return p == FT_LAST_ACTIVE ? "last-active" : p == FT_PREFER_POINTER ? "pointer" : "mouse";
+}
+#endif

screens/desktop-mouse.h

@@ -0,0 +1,61 @@
+#pragma once
+#include <math.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+#define FT_MOUSE_OUTPUTS 24
+struct ft_mouse_output { bool enabled; double x, y, width, height, scale; };
+struct ft_mouse {
+    struct ft_mouse_output outputs[FT_MOUSE_OUTPUTS];
+    double x, y;
+    uint32_t buttons;
+    int screen, grab;
+    bool positioned;
+};
+static inline void ft_mouse_init(struct ft_mouse *m) { *m = (struct ft_mouse){.screen = -1, .grab = -1}; }
+static inline bool ft_mouse_output_set(struct ft_mouse *m, int i, double x, double y,
+                                      double w, double h, double scale) {
+    if (i < 0 || i >= FT_MOUSE_OUTPUTS || m->buttons || !isfinite(x) || !isfinite(y) ||
+        !isfinite(w) || !isfinite(h) || !isfinite(scale) || fabs(x) > 65536 || fabs(y) > 65536 ||
+        w < 1 || h < 1 || w > 16384 || h > 16384 || scale < .25 || scale > 8) return false;
+    m->outputs[i] = (struct ft_mouse_output){true, x, y, w, h, scale};
+    return true;
+}
+static inline bool ft_mouse_position(struct ft_mouse *m, double x, double y) {
+    if (!isfinite(x) || !isfinite(y)) return false;
+    double best = INFINITY, bx = 0, by = 0;
+    int screen = -1;
+    for (int i = 0; i < FT_MOUSE_OUTPUTS; ++i) {
+        const struct ft_mouse_output *o = &m->outputs[i];
+        if (!o->enabled) continue;
+        double px = fmin(fmax(x, o->x), o->x + o->width - 1);
+        double py = fmin(fmax(y, o->y), o->y + o->height - 1);
+        double d = (px-x)*(px-x) + (py-y)*(py-y);
+        if (d < best) best = d, bx = px, by = py, screen = i;
+    }
+    if (screen < 0) return false;
+    m->x = bx; m->y = by; m->screen = screen; m->positioned = true;
+    return true;
+}
+static inline bool ft_mouse_move(struct ft_mouse *m, double dx, double dy) {
+    if (!isfinite(dx) || !isfinite(dy) || fabs(dx) > 16384 || fabs(dy) > 16384) return false;
+    if (!m->positioned) {
+        for (int i = 0; i < FT_MOUSE_OUTPUTS; ++i) if (m->outputs[i].enabled) {
+            const struct ft_mouse_output *o = &m->outputs[i];
+            if (!ft_mouse_position(m, o->x + o->width/2, o->y + o->height/2)) return false;
+            break;
+        }
+    }
+    return ft_mouse_position(m, m->x + dx, m->y + dy);
+}
+// The host seat's implicit grab stays on one KWin output during a drag. Motion
+// remains in that output's coordinates, including positions beyond its edges;
+// nested KWin adds the output origin and can drag windows across its monitors.
+static inline int ft_mouse_target(const struct ft_mouse *m) { return m->buttons ? m->grab : m->screen; }
+static inline bool ft_mouse_button(struct ft_mouse *m, unsigned button, bool down) {
+    if (!m->positioned || button < 272 || button > 279) return false;
+    uint32_t bit = 1u << (button - 272);
+    if (down) { if (!m->buttons) m->grab = m->screen; m->buttons |= bit; }
+    else { m->buttons &= ~bit; if (!m->buttons) m->grab = -1; }
+    return true;
+}

screens/tests/controller-fallback-test.c

@@ -0,0 +1,29 @@
+#include <assert.h>
+#include <stdio.h>
+#include "../controller-fallback.h"
+int main(void) {
+    struct ft_controller_fallback f = {0};
+    assert(!ft_fallback_active(&f, 100));
+    ft_fallback_presence(&f, false, true, 100);
+    assert(!ft_fallback_active(&f, 1099));
+    assert(ft_fallback_active(&f, 1100));
+    ft_fallback_presence(&f, false, true, 1100);
+    assert(ft_fallback_active(&f, 1100)); // heartbeat doesn't reset debounce
+    assert(!ft_fallback_active(&f, 4100)); // lost relay fails closed
+    ft_fallback_presence(&f, false, true, 4100);
+    assert(!ft_fallback_active(&f, 4100)); // old absence cannot bypass new debounce
+    assert(ft_fallback_active(&f, 5100));
+    ft_fallback_presence(&f, true, true, 4200);
+    assert(!ft_fallback_active(&f, 9000)); // connected but idle is still a mouse
+    ft_fallback_presence(&f, false, false, 9100);
+    assert(!ft_fallback_active(&f, 10100)); // disabled preference
+    ft_fallback_presence(&f, true, true, 10200);
+    ft_fallback_presence(&f, false, true, 10300);
+    assert(!ft_fallback_active(&f, 11299));
+    assert(ft_fallback_active(&f, 11300));
+    ft_fallback_presence(&f, true, true, 11301);
+    assert(!ft_fallback_active(&f, 11301)); // reconnect wins immediately
+    ft_fallback_presence(&f, false, true, UINT32_MAX-500);
+    assert(ft_fallback_active(&f, 500)); // monotonic counter wrap
+    puts("disconnect debounce, heartbeat expiry, reconnect and disabled fallback passed");
+}

screens/tests/cursor-cache-test.c

@@ -0,0 +1,106 @@
+// Actual rendererless Wayland/wlroots lifecycle. No OpenVR or real desktop.
+#define _GNU_SOURCE
+#define WLR_USE_UNSTABLE
+#include <assert.h>
+#include <drm_fourcc.h>
+#include <fcntl.h>
+#include <signal.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/socket.h>
+#include <sys/wait.h>
+#include <unistd.h>
+#include <wayland-client.h>
+#include <wlr/types/wlr_shm.h>
+#include "../cursor-cache.h"
+
+static struct wl_compositor *client_compositor;
+static struct wl_shm *client_shm;
+static void global(void *data, struct wl_registry *registry, uint32_t name, const char *interface, uint32_t version) {
+    (void)data; (void)version;
+    if (!strcmp(interface, "wl_compositor")) client_compositor = wl_registry_bind(registry, name, &wl_compositor_interface, 4);
+    if (!strcmp(interface, "wl_shm")) client_shm = wl_registry_bind(registry, name, &wl_shm_interface, 1);
+}
+static void removed(void *data, struct wl_registry *registry, uint32_t name) { (void)data; (void)registry; (void)name; }
+static const struct wl_registry_listener registry_listener = {global, removed};
+static void stage(struct wl_display *display, int report, int ack, char value) {
+    assert(wl_display_roundtrip(display) >= 0);
+    assert(write(report, &value, 1) == 1);
+    char answer;
+    assert(read(ack, &answer, 1) == 1 && answer == value);
+}
+static void client(int fd, int report, int ack) {
+    alarm(10);
+    struct wl_display *d = wl_display_connect_to_fd(fd);
+    assert(d);
+    struct wl_registry *registry = wl_display_get_registry(d);
+    wl_registry_add_listener(registry, &registry_listener, NULL);
+    assert(wl_display_roundtrip(d) >= 0 && client_compositor && client_shm);
+    int memory = memfd_create("offline-cursor", MFD_CLOEXEC);
+    assert(memory >= 0 && ftruncate(memory, 600*4) == 0);
+    uint32_t *pixels = mmap(NULL, 600*4, PROT_READ|PROT_WRITE, MAP_SHARED, memory, 0);
+    assert(pixels != MAP_FAILED); pixels[0] = 0xff123456;
+    struct wl_shm_pool *pool = wl_shm_create_pool(client_shm, memory, 600*4);
+    struct wl_buffer *small = wl_shm_pool_create_buffer(pool, 0, 8, 1, 32, WL_SHM_FORMAT_ARGB8888);
+    struct wl_buffer *large = wl_shm_pool_create_buffer(pool, 0, 600, 1, 2400, WL_SHM_FORMAT_ARGB8888);
+    struct wl_surface *surface = wl_compositor_create_surface(client_compositor);
+    wl_surface_attach(surface, small, 0, 0); wl_surface_commit(surface);
+    stage(d, report, ack, 1); // image committed before any set_cursor/consumer
+    wl_surface_commit(surface); stage(d, report, ack, 2); // callback-only commit preserves image
+    wl_surface_attach(surface, NULL, 0, 0); wl_surface_commit(surface); stage(d, report, ack, 3);
+    wl_surface_attach(surface, large, 0, 0); wl_surface_commit(surface); stage(d, report, ack, 4);
+    wl_surface_attach(surface, small, 0, 0); wl_surface_commit(surface); stage(d, report, ack, 5);
+    wl_surface_destroy(surface); stage(d, report, ack, 6);
+    wl_buffer_destroy(small); wl_buffer_destroy(large); wl_shm_pool_destroy(pool);
+    wl_registry_destroy(registry); wl_display_disconnect(d);
+    munmap(pixels, 600*4); close(memory);
+    _exit(0);
+}
+int main(void) {
+    alarm(10);
+    struct wl_display *display = wl_display_create();
+    struct wlr_compositor *compositor = wlr_compositor_create(display, 6, NULL);
+    uint32_t formats[] = {DRM_FORMAT_ARGB8888, DRM_FORMAT_XRGB8888};
+    assert(wlr_shm_create(display, 1, formats, 2));
+    struct ft_cursor_cache cache;
+    ft_cursor_cache_init(&cache, compositor);
+    int connection[2], report[2], ack[2];
+    assert(socketpair(AF_UNIX, SOCK_STREAM|SOCK_CLOEXEC, 0, connection) == 0);
+    assert(pipe(report) == 0 && pipe(ack) == 0);
+    pid_t pid = fork(); assert(pid >= 0);
+    if (!pid) { close(connection[0]); close(report[0]); close(ack[1]); client(connection[1], report[1], ack[0]); }
+    close(connection[1]); close(report[1]); close(ack[0]);
+    fcntl(report[0], F_SETFL, O_NONBLOCK);
+    assert(wl_client_create(display, connection[0]));
+    struct wl_event_loop *loop = wl_display_get_event_loop(display);
+    struct wlr_buffer *first = NULL;
+    for (char expected = 1; expected <= 6;) {
+        assert(wl_event_loop_dispatch(loop, 10) >= 0); wl_display_flush_clients(display);
+        char observed;
+        if (read(report[0], &observed, 1) != 1) continue;
+        assert(observed == expected);
+        if (expected == 6) assert(wl_list_empty(&cache.frames));
+        else {
+            assert(!wl_list_empty(&cache.frames));
+            struct ft_cursor_frame *f = wl_container_of(cache.frames.next, f, link);
+            assert(f->surface->current.buffer == NULL); // wlroots already released it
+            struct wlr_buffer *buffer = ft_cursor_cached(&cache, f->surface);
+            if (expected == 3 || expected == 4) assert(buffer == NULL);
+            else {
+                assert(buffer && buffer->width == 8 && buffer->height == 1);
+                if (expected == 1) first = buffer;
+                if (expected == 2) assert(buffer == first);
+                void *data; uint32_t format; size_t stride;
+                assert(wlr_buffer_begin_data_ptr_access(buffer, WLR_BUFFER_DATA_PTR_ACCESS_READ, &data, &format, &stride));
+                assert(*(uint32_t *)data == 0xff123456 && format == DRM_FORMAT_ARGB8888 && stride == 32);
+                wlr_buffer_end_data_ptr_access(buffer);
+            }
+        }
+        assert(write(ack[1], &observed, 1) == 1); ++expected;
+    }
+    int status; assert(waitpid(pid, &status, 0) == pid && WIFEXITED(status) && WEXITSTATUS(status) == 0);
+    close(report[0]); close(ack[1]); wl_display_destroy_clients(display);
+    ft_cursor_cache_finish(&cache); wl_display_destroy(display);
+    puts("cursor before selection, buffer-only lifetime, null/oversize commits and destruction passed");
+}

screens/tests/desktop-cursor-test.c

@@ -0,0 +1,23 @@
+#include "../desktop-cursor.h"
+#include <assert.h>
+#include <stdio.h>
+int main(void) {
+    uint32_t input[] = {0x80402010, 0, 0xdeadbeef, 0xff102030, 0x00ffffff, 0};
+    uint8_t out[16];
+    assert(ft_cursor_rgba(out, input, 2, 2, 12, DRM_FORMAT_ARGB8888));
+    assert(out[0] == 128 && out[1] == 64 && out[2] == 32 && out[3] == 128);
+    assert(out[4] == 0 && out[7] == 0);
+    assert(out[8] == 16 && out[9] == 32 && out[10] == 48 && out[11] == 255);
+    assert(out[12] == 0 && out[13] == 0 && out[14] == 0 && out[15] == 0);
+    assert(ft_cursor_rgba(out, input, 1, 1, 4, DRM_FORMAT_ABGR8888));
+    assert(out[0] == 32 && out[1] == 64 && out[2] == 128);
+    assert(ft_cursor_rgba(out, input, 1, 1, 4, DRM_FORMAT_XRGB8888));
+    assert(out[0] == 64 && out[1] == 32 && out[2] == 16 && out[3] == 255);
+    assert(ft_cursor_rgba(out, input, 1, 1, 4, DRM_FORMAT_XBGR8888));
+    assert(out[0] == 16 && out[2] == 64 && out[3] == 255);
+    assert(!ft_cursor_rgba(out, input, 1, 1, 3, DRM_FORMAT_ARGB8888));
+    assert(!ft_cursor_rgba(out, input, 513, 1, 2052, DRM_FORMAT_ARGB8888));
+    assert(!ft_cursor_rgba(out, NULL, 1, 1, 4, DRM_FORMAT_ARGB8888));
+    assert(!ft_cursor_rgba(out, input, 1, 1, 4, DRM_FORMAT_RGB565));
+    puts("KDE cursor channels, alpha, padding and bounds passed");
+}

screens/tests/desktop-handoff-test.c

@@ -0,0 +1,22 @@
+#include <assert.h>
+#include "../desktop-handoff.h"
+int main(void) {
+    struct ft_handoff h = {.policy=FT_LAST_ACTIVE};
+    assert(ft_handoff_claim(&h, false, 100, 0, 0));
+    assert(!ft_handoff_claim(&h, true, 100, 0, 0));
+    assert(ft_handoff_claim(&h, true, 101, 0, 0));
+    assert(!ft_handoff_claim(&h, true, 102, 1, 0));
+    assert(!ft_handoff_claim(&h, false, 102, 0, 1));
+    assert(ft_handoff_claim(&h, true, 102, 0, 1));
+    assert(ft_handoff_claim(&h, false, 102, 1, 0));
+    assert(ft_handoff_claim(&h, false, 103, 0, 0));
+    h.policy=FT_PREFER_MOUSE;
+    assert(!ft_handoff_claim(&h, true, 104, 0, 0));
+    assert(ft_handoff_claim(&h, false, 104, 0, 0));
+    h.policy=FT_PREFER_POINTER;
+    assert(!ft_handoff_claim(&h, false, 105, 0, 0));
+    assert(ft_handoff_claim(&h, true, 105, 0, 0));
+    h=(struct ft_handoff){.policy=FT_LAST_ACTIVE};
+    assert(ft_handoff_claim(&h, false, UINT32_MAX, 0, 0));
+    assert(ft_handoff_claim(&h, true, 0, 0, 0));
+}

screens/tests/desktop-input-integration.py

@@ -0,0 +1,89 @@
+"""Only addresses upstream's isolated test compositor, never live input sockets."""
+import json
+import socket
+import time
+
+with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as client:
+    client.bind('')
+    client.settimeout(2)
+    def ask(command):
+        client.sendto(command.encode(), '\0ft_screens_test')
+        return client.recv(8192).decode()
+    for command in ('mouse-layout 1 0 0 960 540 2',
+                    'mouse-layout 2 960 0 540 960 2', 'mouse-output-off 24',
+                    'mouse-mode desktop', 'mouse-position 1 100 100', 'mouse-move 10 5',
+                    'mouse-button 272 1', 'mouse-move 900 0', 'mouse-button 272 0',
+                    'mouse-wheel 0 0.125'):
+        assert ask(command) == 'ok', command
+    assert ask('mouse-output-off 25').startswith('error')
+    assert ask('mouse-layout 25 0 0 960 540 1').startswith('error')
+    ask('mouse-presence 1 1')
+    before = json.loads(ask('mouse?'))
+    ask('input 1 down 200 100 left'); ask('input 1 up 200 100 left')
+    after = json.loads(ask('mouse?'))
+    assert after['controllerEventsIgnored'] >= before['controllerEventsIgnored'] + 2
+    ask('mouse-presence 0 1')
+    time.sleep(1.1)
+    assert json.loads(ask('mouse-presence?'))['controllerDesktop']
+    before = json.loads(ask('mouse?'))
+    ask('input 1 down 200 100 left')
+    after = json.loads(ask('mouse?'))
+    assert after['controllerEventsIgnored'] == before['controllerEventsIgnored']
+    ask('mouse-presence 1 1')
+    assert not json.loads(ask('mouse-presence?'))['controllerDesktop']
+    ask('mouse-button 272 1'); ask('mouse-button 272 0')
+print('Native motion/click/wheel, cross-output drag, output bounds and controller fallback passed')
+
+with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as client:
+    client.bind(''); client.settimeout(2)
+    def ask(command):
+        client.sendto(command.encode(), '\0ft_screens_test')
+        return client.recv(8192).decode()
+    def policy(): return json.loads(ask('desktop-policy?'))
+    assert ask('desktop-policy last-active') == 'ok'
+    assert ask('mouse-presence 1 1') == 'ok'
+    assert ask('mouse-move 3 0') == 'ok'
+    assert policy()['owner'] == 'mouse'
+    for _ in range(3): ask('input 1 move 200 100')
+    assert policy()['owner'] == 'mouse', 'aiming must not claim ownership'
+    time.sleep(.01)
+    ask('input 1 down 200 100 left')
+    assert policy()['owner'] == 'pointer'
+    assert policy()['pointerButtons'] == 1
+    before = json.loads(ask('mouse?'))
+    ask('mouse-move 40 0'); ask('mouse-button 272 1'); ask('mouse-button 272 0'); ask('mouse-wheel 0 1')
+    after = json.loads(ask('mouse?'))
+    assert before['x'] == after['x'], 'mouse motion must not accumulate during pointer drag'
+    assert before['buttonEvents'] == after['buttonEvents']
+    assert before['wheelEvents'] == after['wheelEvents']
+    assert policy()['owner'] == 'pointer'
+    assert ask('desktop-policy mouse').startswith('error'), 'cannot change policy during drag'
+    ask('mouse-presence 1 1')
+    assert policy()['owner'] == 'pointer', 'presence heartbeat must not steal ownership'
+    ask('input 1 up 200 100 left')
+    assert policy()['pointerButtons'] == 0
+    ask('mouse-wheel 0 1')
+    assert policy()['owner'] == 'mouse'
+    ask('mouse-button 272 1'); time.sleep(.01)
+    ask('input 1 down 200 100 left'); ask('input 1 up 200 100 left')
+    assert policy()['owner'] == 'mouse'
+    assert policy()['mouseButtons'] == 1
+    ask('mouse-button 272 0')
+    time.sleep(.01); ask('input 1 down 200 100 left'); ask('input 1 up 200 100 left')
+    assert policy()['owner'] == 'pointer'
+    ask('mouse-move 0 0')
+    assert policy()['owner'] == 'pointer', 'zero movement must not claim'
+    ask('mouse-move 1 0')
+    assert policy()['owner'] == 'mouse'
+    time.sleep(.01)
+    ask('input 1 move 200 100'); ask('input 1 scroll 0 1')
+    assert policy()['owner'] == 'pointer', 'controller scroll must claim desktop'
+    ask('mouse-wheel 0 1')
+    assert policy()['owner'] == 'mouse'
+    assert ask('desktop-policy pointer') == 'ok'
+    ask('mouse-move 1 0')
+    assert policy()['owner'] == 'pointer'
+    assert ask('desktop-policy mouse') == 'ok'
+    ask('input 1 down 200 100 left'); ask('input 1 up 200 100 left')
+    assert policy()['owner'] == 'mouse'
+print('Desktop handoff, aiming exclusion, drag locks, ignored releases, presence stability and policy controls passed')

screens/tests/desktop-mouse-test.c

@@ -0,0 +1,34 @@
+#include "../desktop-mouse.h"
+#include <assert.h>
+#include <stdio.h>
+int main(void) {
+    struct ft_mouse m;
+    ft_mouse_init(&m);
+    assert(!ft_mouse_move(&m, 0, 0));
+    assert(ft_mouse_output_set(&m, 0, -1280, 0, 1280, 720, 1.5));
+    assert(ft_mouse_output_set(&m, 1, 0, 0, 1920, 1080, 1));
+    assert(ft_mouse_move(&m, 0, 0));
+    assert(m.screen == 0 && m.x == -640 && m.y == 360);
+    assert(ft_mouse_position(&m, -1, 100));
+    assert(ft_mouse_button(&m, 272, true));
+    assert(!ft_mouse_output_set(&m, 0, 0, 0, 100, 100, 1));
+    assert(ft_mouse_move(&m, 20, 0));
+    assert(m.screen == 1 && m.x == 19 && ft_mouse_target(&m) == 0);
+    // During the grab, host coordinates exceed the old output's width.
+    assert((m.x-m.outputs[0].x)*m.outputs[0].scale == 1948.5);
+    assert(ft_mouse_button(&m, 275, true));
+    assert(ft_mouse_button(&m, 272, false));
+    assert(ft_mouse_target(&m) == 0);
+    assert(ft_mouse_button(&m, 275, false));
+    assert(ft_mouse_target(&m) == 1 && m.grab == -1);
+    assert(ft_mouse_move(&m, 10000, 10000));
+    assert(m.x == 1919 && m.y == 1079);
+    assert(!ft_mouse_move(&m, NAN, 0));
+    assert(!ft_mouse_position(&m, INFINITY, 1));
+    assert(!ft_mouse_move(&m, 16385, 0));
+    assert(!ft_mouse_output_set(&m, FT_MOUSE_OUTPUTS, 0, 0, 100, 100, 1));
+    assert(!ft_mouse_output_set(&m, 0, 0, 0, 0, 100, 1));
+    assert(!ft_mouse_output_set(&m, 0, 0, 0, 100, 100, NAN));
+    assert(!ft_mouse_button(&m, 280, true));
+    puts("desktop mouse geometry, drag and validation passed");
+}

screens/vr.cpp

@@ -302,6 +302,12 @@ struct Screen {
     }
 };
 std::map<int, Screen> g_screens;
+struct DesktopCursor {
+    vr::VROverlayHandle_t overlay = vr::k_ulOverlayHandleInvalid;
+    int width = 0, height = 0, hx = 0, hy = 0, scale = 1, screen = -1;
+    double x = 0, y = 0, outputScale = 1;
+    bool enabled = false, image = false;
+} g_cursor;
 std::map<const void *, vr::SharedTextureHandle_t> g_imports;
 
 // Hand cutouts (see the top and handcut.h).
@@ -584,6 +590,32 @@ Mat OnSurface(const Screen &s, double u, double v, double dz) {
     return m;
 }
 
+void UpdateDesktopCursor() {
+    if (g_cursor.overlay == vr::k_ulOverlayHandleInvalid) return;
+    const auto it = g_screens.find(g_cursor.screen);
+    const auto activity = vr::VRSystem()->GetTrackedDeviceActivityLevel(vr::k_unTrackedDeviceIndex_Hmd);
+    const bool off = activity == vr::k_EDeviceActivityLevel_Idle || activity == vr::k_EDeviceActivityLevel_Standby ||
+                     activity == vr::k_EDeviceActivityLevel_Idle_Timeout;
+    Mat pose;
+    if (!g_cursor.enabled || !g_cursor.image || off || it == g_screens.end() ||
+        !it->second.visible || it->second.width < 1 || !ScreenPose(it->second, &pose)) {
+        vr::VROverlay()->HideOverlay(g_cursor.overlay);
+        return;
+    }
+    const Screen &s = it->second;
+    const double perPixel = s.metres / s.width;
+    const double cursorPixel = perPixel * g_cursor.outputScale / g_cursor.scale;
+    const double u = (g_cursor.x - s.width/2.0)*perPixel + (g_cursor.width/2.0-g_cursor.hx)*cursorPixel;
+    const double v = (s.height/2.0-g_cursor.y)*perPixel + (g_cursor.hy-g_cursor.height/2.0)*cursorPixel;
+    const double width = g_cursor.width*cursorPixel;
+    const Mat m = Mul(pose, OnSurface(s, u, v, 0.004));
+    vr::VROverlay()->SetOverlayTransformAbsolute(g_cursor.overlay, vr::TrackingUniverseStanding, &m);
+    vr::VROverlay()->SetOverlayWidthInMeters(g_cursor.overlay, float(width));
+    vr::VROverlay()->SetOverlayCurvature(g_cursor.overlay, s.curve > 0 ? float(std::min(1.0, width/(2*M_PI*s.curve))) : 0);
+    vr::VROverlay()->SetOverlayAlpha(g_cursor.overlay, s.alpha);
+    vr::VROverlay()->ShowOverlay(g_cursor.overlay);
+}
+
 double BarY(const Screen &s) { return -(s.heightMetres() / 2 + s.chrome * 0.06 + s.chrome * 12 / 256); }
 Mat BarOffset(const Screen &s) { return OnSurface(s, 0, BarY(s), 0.003); }
 
@@ -894,17 +926,6 @@ void SendFloat(const std::string &msg) {
         std::printf("to ft-floatd: %s\n", msg.c_str());
 }
 
-// To the pointer helper (@ft_pointer_helper), from an unbound socket.
-void SendPointer(const std::string &msg) {
-    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);
-    sendto(fd, msg.data(), msg.size(), MSG_DONTWAIT, reinterpret_cast<sockaddr *>(&addr),
-           socklen_t(offsetof(sockaddr_un, sun_path) + 1 + sizeof name - 1));
-}
-
 // 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) {
@@ -1365,137 +1386,6 @@ 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;
@@ -1682,6 +1572,7 @@ bool ft_vr_init(void) {
 
 void ft_vr_shutdown(void) {
     if (!g_vr) return;
+    if (g_cursor.overlay != vr::k_ulOverlayHandleInvalid) vr::VROverlay()->DestroyOverlay(g_cursor.overlay);
     if (g_cutterState == 1)
         for (auto &[i, s] : g_screens) g_cutter.DropPanel(i);  // drops their imports while SteamVR is up
     if (g_catcher != vr::k_ulOverlayHandleInvalid) vr::VROverlay()->DestroyOverlay(g_catcher);
@@ -1711,6 +1602,71 @@ int ft_vr_modifiers(uint32_t format, uint64_t *out, int max) {
 
 bool ft_vr_screens_shown(void) { return g_vr && ModeVisible(); }
 
+static bool EnsureDesktopCursor() {
+    if (!g_vr) return false;
+    if (g_cursor.overlay == vr::k_ulOverlayHandleInvalid) {
+        if (vr::VROverlay()->CreateOverlay("frametop.desktop.cursor", "KDE desktop cursor", &g_cursor.overlay) != vr::VROverlayError_None) return false;
+        vr::VROverlay()->SetOverlayInputMethod(g_cursor.overlay, vr::VROverlayInputMethod_None);
+        vr::VROverlay()->SetOverlaySortOrder(g_cursor.overlay, 200);
+    }
+    return true;
+}
+
+bool ft_vr_cursor_image(const uint8_t *rgba, int width, int height, int hx, int hy, int scale) {
+    if (!rgba) { g_cursor.image = false; UpdateDesktopCursor(); return true; }
+    if (width < 1 || height < 1 || width > 512 || height > 512 || scale < 1 || scale > 8 || !EnsureDesktopCursor()) return false;
+    if (vr::VROverlay()->SetOverlayRaw(g_cursor.overlay, const_cast<uint8_t *>(rgba), width, height, 4) != vr::VROverlayError_None) return false;
+    g_cursor.width = width; g_cursor.height = height; g_cursor.hx = hx; g_cursor.hy = hy; g_cursor.scale = scale;
+    g_cursor.image = true;
+    UpdateDesktopCursor();
+    return true;
+}
+
+void ft_vr_cursor_move(int screen, double x, double y, double scale, bool enabled) {
+    g_cursor.screen = screen; g_cursor.x = x; g_cursor.y = y; g_cursor.outputScale = scale; g_cursor.enabled = enabled;
+    UpdateDesktopCursor();
+}
+
+static vr::SharedTextureHandle_t ImportBuffer(const void *key, const struct ft_dmabuf *b) {
+    auto it = g_imports.find(key);
+    if (it == g_imports.end()) {
+        vr::DmabufAttributes_t a{};
+        a.unWidth = uint32_t(b->width);
+        a.unHeight = uint32_t(b->height);
+        a.unDepth = a.unMipLevels = a.unArrayLayers = a.unSampleCount = 1;
+        a.unFormat = b->format;
+        a.ulModifier = b->modifier;
+        a.unPlaneCount = uint32_t(b->n_planes);
+        for (int i = 0; i < b->n_planes && i < int(vr::MaxDmabufPlaneCount); ++i) {
+            a.plane[i].unOffset = b->offset[i];
+            a.plane[i].unStride = b->stride[i];
+            a.plane[i].nFd = b->fd[i];
+        }
+        vr::SharedTextureHandle_t h = 0;
+        if (!vr::VRIPCResourceManager()->ImportDmabuf(vr::VRApplication_Overlay, &a, &h)) {
+            std::fprintf(stderr, "openvr: ImportDmabuf failed: %dx%d format 0x%x modifier 0x%llx\n", b->width,
+                         b->height, b->format, (unsigned long long)b->modifier);
+            return 0;
+        }
+        it = g_imports.emplace(key, h).first;
+    }
+    return it->second;
+}
+
+bool ft_vr_cursor_dmabuf(const void *key, const struct ft_dmabuf *b, int hx, int hy, int scale) {
+    if (!b || b->width < 1 || b->height < 1 || b->width > 512 || b->height > 512 ||
+        scale < 1 || scale > 8 || !EnsureDesktopCursor()) return false;
+    vr::SharedTextureHandle_t handle = ImportBuffer(key, b);
+    if (!handle) return false;
+    vr::Texture_t tex = {&handle, vr::TextureType_SharedTextureHandle, vr::ColorSpace_Gamma};
+    if (vr::VROverlay()->SetOverlayTexture(g_cursor.overlay, &tex) != vr::VROverlayError_None) return false;
+    g_cursor.width = b->width; g_cursor.height = b->height; g_cursor.hx = hx; g_cursor.hy = hy; g_cursor.scale = scale;
+    g_cursor.image = true;
+    UpdateDesktopCursor();
+    return true;
+}
+
+
 }  // extern "C"
 
 namespace {
@@ -2029,20 +1985,13 @@ 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();
     UpdateLasers();
     UpdateControls();
     UpdateGuides();
+    UpdateDesktopCursor();
     UpdateCutouts();
     UpdateCatcher();
 }
@@ -2109,8 +2058,6 @@ 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)
@@ -2148,7 +2095,6 @@ 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) {
@@ -2304,7 +2250,6 @@ 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 ||
@@ -2332,8 +2277,6 @@ 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,

screens/vr.h

@@ -17,8 +17,7 @@ struct ft_dmabuf {
     int fd[4];
 };
 
-// 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 };
+enum ft_event_type { FT_MOTION, FT_BUTTON, FT_SCROLL, FT_LEAVE, FT_QUIT, FT_KEY, FT_KEYBOARD_CLOSED };
 
 struct ft_event {
     enum ft_event_type type;
@@ -36,6 +35,11 @@ void ft_vr_shutdown(void);
 int ft_vr_modifiers(uint32_t format, uint64_t *out, int max);
 // The screens are showing (by the visibility mode; not counting a wrist-pinned screen).
 bool ft_vr_screens_shown(void);
+// Desktop cursor: KDE supplies the image; this is a non-interactive display
+// overlay only. Mouse input goes straight to the Wayland seat, never SteamVR.
+bool ft_vr_cursor_image(const uint8_t *rgba, int width, int height, int hotspot_x, int hotspot_y, int buffer_scale);
+bool ft_vr_cursor_dmabuf(const void *key, const struct ft_dmabuf *buf, int hotspot_x, int hotspot_y, int buffer_scale);
+void ft_vr_cursor_move(int screen, double pixel_x, double pixel_y, double output_scale, bool enabled);
 // A panel for screen `index`, width in metres, placed in a row in front of the head.
 void ft_vr_screen_create(int index, double metres, int count);
 void ft_vr_screen_destroy(int index);

scripts/test-desktop-input.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Offline native input tests; --headless also starts an isolated test desktop.
+set -euo pipefail
+root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$root"
+[[ $# == 0 || ($# == 1 && $1 == --headless) ]] || { echo 'Usage: scripts/test-desktop-input.sh [--headless]' >&2; exit 2; }
+python3 -m unittest discover -s input -p 'test_desktop_mouse.py'
+"$root/scripts/frame.sh" -C screens 'set -e; mkdir -p build
+gcc -std=c11 -Wall -Wextra -Werror tests/desktop-mouse-test.c -lm -o build/desktop-mouse-test
+build/desktop-mouse-test
+gcc -std=c11 -Wall -Wextra -Werror tests/controller-fallback-test.c -o build/controller-fallback-test
+build/controller-fallback-test
+gcc -std=c11 -Wall -Wextra -Werror tests/desktop-handoff-test.c -o build/desktop-handoff-test
+build/desktop-handoff-test
+gcc -std=c11 -Wall -Wextra -Werror $(pkg-config --cflags libdrm) tests/desktop-cursor-test.c -o build/desktop-cursor-test
+build/desktop-cursor-test
+gcc -std=c11 -Wall -Wextra -Werror tests/cursor-cache-test.c $(pkg-config --cflags --libs wlroots-0.20 wayland-server wayland-client libdrm pixman-1) -o build/cursor-cache-test
+build/cursor-cache-test'
+if [[ ${1:-} == --headless ]]; then
+  # Reuses upstream's throwaway @ft_screens_test fixture, never the live desktop.
+  if pgrep -f '[f]t-screens.*--control ft_screens_test' >/dev/null; then
+    echo 'Test desktop already running; stop it yourself before this test.' >&2
+    exit 1
+  fi
+  "$root/screens/build.sh"
+  trap '"$root/screens/test/headless.sh" stop' EXIT
+  "$root/screens/test/headless.sh" start 2 3
+  python3 "$root/screens/tests/desktop-input-integration.py"
+fi

session/frametop-session.sh

@@ -177,6 +177,11 @@ export XDG_CONFIG_HOME=$HOME/.config/frametop
 export XDG_STATE_HOME=$HOME/.local/state/frametop
 mkdir -p "$XDG_CONFIG_HOME" "$XDG_STATE_HOME"
 
+# Steam's VR session exports a 256px cursor. Use this desktop's own KDE
+# preferences instead of inheriting the dashboard cursor size and theme.
+export XCURSOR_SIZE=$(kreadconfig6 --file kcminputrc --group Mouse --key cursorSize --default 24)
+export XCURSOR_THEME=$(kreadconfig6 --file kcminputrc --group Mouse --key cursorTheme --default breeze_cursors)
+
 # Remote desktop over VNC: session/remote-desktop.sh captures the desktop with
 # krdp on 127.0.0.1, and session/vnc-bridge.sh re-serves its primary screen over VNC. krdpserver runs from the container, so KWin can't
 # match it to an installed app. KWin's permission check for screencast and fake

session/frametop.conf.example

@@ -10,6 +10,9 @@ REMOTE=0           # 1 = serve the desktop's primary screen over VNC on the tail
 FLOAT_SLOTS=8      # screens backend: how many windows can float in VR at once (spare outputs; 0 turns it off; restart the desktop after a change)
 FLOAT_MARGIN=300   # floating windows: pixels around each window on its output, so menus have room past its edges
 POINTER=0          # 1 = the mouse drives the universal 3D pointer (ft_pointer driver) instead of a plain mouse
+MOUSE_MODE=spatial # desktop: physical mouse controls KDE directly; controllers remain separate. CLI: input/ft-mousectl desktop --save
+DESKTOP_MOUSE_SPEED=1 # logical desktop pixels per physical mouse count (0.05 to 10)
+DESKTOP_CONTROLLER_FALLBACK=1 # desktop controller pointers when no routed physical mouse is connected
 POINTER_SENSITIVITY=0.03   # degrees per mouse count
 POINTER_IDLE=30    # seconds without mouse use before the controllers get their laser back
 POINTER_WAKE_COUNTS=40     # mouse counts within 1 s needed to wake or re-claim the laser (ignores desk jitter)