feat(wayland): turn on KDE pointer restore by itself

Getting working pointer restore on KDE required knowing to set an environment
variable, which no user would discover. Doing it in the installer would only
cover launches from the desktop menu, not a terminal, and would bury the
policy where nobody would find it again.

Instead the helper enables itself when the session is KDE on Wayland — the
only environment it targets — so it works however the app is launched, for
every KDE user rather than whoever read the docs.

PAIRUX_WAYLAND_CURSOR_RESTORE now means the opposite: 0 forces it off if a
compositor misbehaves, 1 forces it on for a KDE session that does not
advertise itself in XDG_CURRENT_DESKTOP.

Safe to default on now that the rails are in place: the report rate is capped
at 10/s regardless of pointer speed, the script exists only while a guest
holds control, it self-disables after five consecutive DBus failures, and if
it fails to report at all the viability probe drops two-cursor mode so clicks
keep landing. A probe on KWin 6.6.5 confirmed cursorPosChanged is exposed to
scripting.

Ships as @profullstack/remote-input 0.2.4.

Author: ralyodio

docs/LINUX-SETUP.md

@@ -151,8 +151,11 @@ Wayland support requires PipeWire for screen capture. Input injection works via
 
 ### Pointer restoration on KDE (KWin)
 
-Automatic — PairUX claims a DBus name and loads a small KWin script that reports
-`workspace.cursorPos`, then unloads it on quit. The only requirement is `gdbus`:
+Automatic on a KDE Wayland session — PairUX claims a DBus name and loads a small
+KWin script that reports `workspace.cursorPos`, then unloads it on quit. The
+report rate is capped, the script exists only while a guest holds control, and it
+self-disables after repeated failures. Set `PAIRUX_WAYLAND_CURSOR_RESTORE=0` to
+turn it off. The only requirement is `gdbus`:
 
 ```bash
 sudo apt install libglib2.0-bin   # usually already present

packages/remote-input/README.md

@@ -105,6 +105,11 @@ method, then installs and loads a small script that pushes `workspace.cursorPos`
 to it — distance-throttled, since the signal fires on every motion event. This
 happens automatically; the user installs nothing.
 
+Enabled automatically on a KDE session running Wayland — the only environment
+it targets. `PAIRUX_WAYLAND_CURSOR_RESTORE=0` forces it off if a compositor
+misbehaves; `=1` forces it on for a KDE session that does not advertise itself
+in `XDG_CURRENT_DESKTOP`.
+
 Requires `gdbus` (`libglib2.0-bin`, present on essentially every desktop).
 Readings older than two seconds are discarded rather than used, so a
 half-working helper can never fling the pointer somewhere its owner never left

packages/remote-input/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/remote-input",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Cross-platform OS input injection for remote control (macOS, Windows, Linux X11 and Wayland)",
   "license": "MIT",
   "type": "module",

packages/remote-input/src/wayland/kwinCursorProvider.test.ts

@@ -1,5 +1,9 @@
-import { describe, it, expect } from 'vitest';
-import { KWinCursorProvider, buildKWinScript } from './kwinCursorProvider.js';
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  KWinCursorProvider,
+  buildKWinScript,
+  isKWinCursorRestoreEnabled,
+} from './kwinCursorProvider.js';
 
 const silent = { log: () => {}, warn: () => {} };
 
@@ -48,8 +52,8 @@ describe('KWinCursorProvider', () => {
   // Restoring the pointer is a comfort; the only way to do it puts our code in
   // the compositor's input path, where a mistake costs the user their desktop.
   // So it stays off until explicitly asked for.
-  it('does nothing unless explicitly enabled', async () => {
-    delete process.env.PAIRUX_WAYLAND_CURSOR_RESTORE;
+  it('does nothing where the helper does not apply', async () => {
+    process.env.PAIRUX_WAYLAND_CURSOR_RESTORE = '0';
     const provider = new KWinCursorProvider({ logger: silent });
     await expect(provider.start()).resolves.toBe(false);
     expect(provider.isAvailable).toBe(false);
@@ -76,3 +80,51 @@ describe('KWinCursorProvider', () => {
     expect(provider.getPosition()).toBeNull();
   });
 });
+
+describe('isKWinCursorRestoreEnabled', () => {
+  const saved = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...saved };
+  });
+
+  function env(vars: Record<string, string | undefined>): void {
+    delete process.env.PAIRUX_WAYLAND_CURSOR_RESTORE;
+    delete process.env.XDG_SESSION_TYPE;
+    delete process.env.WAYLAND_DISPLAY;
+    delete process.env.XDG_CURRENT_DESKTOP;
+    for (const [k, v] of Object.entries(vars)) {
+      if (v !== undefined) process.env[k] = v;
+    }
+  }
+
+  // The helper only targets KDE on Wayland, and a user should not have to
+  // discover an env var to get working pointer restore there.
+  it('is on for a KDE Wayland session', () => {
+    env({ XDG_SESSION_TYPE: 'wayland', XDG_CURRENT_DESKTOP: 'KDE' });
+    expect(isKWinCursorRestoreEnabled()).toBe(true);
+  });
+
+  it('is off where the helper does not apply', () => {
+    env({ XDG_SESSION_TYPE: 'x11', XDG_CURRENT_DESKTOP: 'KDE' });
+    expect(isKWinCursorRestoreEnabled()).toBe(false);
+
+    env({ XDG_SESSION_TYPE: 'wayland', XDG_CURRENT_DESKTOP: 'GNOME' });
+    expect(isKWinCursorRestoreEnabled()).toBe(false);
+  });
+
+  // An escape hatch matters: this hooks the compositor's input path.
+  it('can be forced off', () => {
+    env({
+      XDG_SESSION_TYPE: 'wayland',
+      XDG_CURRENT_DESKTOP: 'KDE',
+      PAIRUX_WAYLAND_CURSOR_RESTORE: '0',
+    });
+    expect(isKWinCursorRestoreEnabled()).toBe(false);
+  });
+
+  it('can be forced on for a session that does not advertise itself', () => {
+    env({ PAIRUX_WAYLAND_CURSOR_RESTORE: '1' });
+    expect(isKWinCursorRestoreEnabled()).toBe(true);
+  });
+});

packages/remote-input/src/wayland/kwinCursorProvider.ts

@@ -40,15 +40,27 @@ const POSITION_MAX_AGE_MS = 2000;
 const REPORT_INTERVAL_MS = 100;
 
 /**
- * Off unless explicitly enabled.
+ * On automatically where it applies: a KDE session on Wayland.
  *
- * Restoring the pointer on Wayland is a comfort, not a requirement, and the
- * only way to do it puts our code in the compositor's input path — where a
- * mistake costs the user their whole desktop. Opt in with
- * PAIRUX_WAYLAND_CURSOR_RESTORE=1.
+ * This is the only environment the helper targets, and enabling it by hand is
+ * not something a user should have to discover. It puts a hook in the
+ * compositor's input path, so the rails around it matter more than the switch:
+ * the report rate is capped, it exists only while a guest holds control, and it
+ * gives up after repeated failures.
+ *
+ * PAIRUX_WAYLAND_CURSOR_RESTORE=0 forces it off (if a compositor misbehaves),
+ * =1 forces it on (e.g. a KDE session that does not advertise itself).
  */
 export function isKWinCursorRestoreEnabled(): boolean {
-  return process.env.PAIRUX_WAYLAND_CURSOR_RESTORE === '1';
+  const override = process.env.PAIRUX_WAYLAND_CURSOR_RESTORE;
+  if (override === '0') return false;
+  if (override === '1') return true;
+
+  const wayland =
+    process.env.XDG_SESSION_TYPE === 'wayland' || process.env.WAYLAND_DISPLAY !== undefined;
+  const kde = (process.env.XDG_CURRENT_DESKTOP ?? '').toUpperCase().includes('KDE');
+
+  return wayland && kde;
 }
 
 /**