fix(linux): report when scrolling falls back from uinput on wayland (#1570)

Author: y3owk1n

docs/LINUX_SETUP.md

@@ -45,6 +45,7 @@ Host changes required before Neru runs correctly (not code changes):
 | 1   | Install [build dependencies](#build-dependencies)           | CGO backends and runtime libs         | All Linux | Yes                     |
 | 2   | Add user to `input` group: `sudo usermod -aG input "$USER"` | `evdev` keyboard capture **and Neru's own global hotkeys** on Wayland | Wayland | Yes (re-login required) |
 | 3   | Bind `neru <mode>` in compositor keybindings                | Only needed if you skip item 2        | Wayland   | Yes (user config)       |
+| 4   | Make `/dev/uinput` writable (udev rule below)               | Scroll injection through a uinput wheel; without it scrolling falls back to the compositor virtual pointer, which Chromium and Electron apps on Hyprland ignore. Also the fast path for `neru key` | Wayland | Yes (udev rule) |
 
 Notes:
 
@@ -55,6 +56,8 @@ Notes:
   the compositor only if you would rather not grant `/dev/input` access. See
   [Global hotkeys on Wayland](./LINUX_DESKTOPS.md#global-hotkeys-on-wayland).
 - Item 3 cannot be automated by a package; ship example snippets where helpful.
+- Item 4 is what `neru doctor` reports under `capability.scroll` when it is
+  missing, and the daemon warns once at the first scroll that falls back.
 
 ---
 
@@ -78,6 +81,30 @@ works but modified clicks may degrade.
 
 ---
 
+## Wayland scroll injection permissions
+
+On Wayland, Neru scrolls through a virtual mouse wheel it creates on
+`/dev/uinput`, so the events enter the input stack below the compositor and
+reach every client like a physical wheel. Most distros ship that node as
+root-only (`crw-rw---- root root`). The `input` group from the previous section
+does not cover it; grant it with a udev rule:
+
+```bash
+echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-neru-uinput.rules
+sudo udevadm control --reload && sudo udevadm trigger
+```
+
+Confirm with `ls -l /dev/uinput` (group `input`, mode `0660`) and restart the
+daemon. If the node is missing entirely, load the module: `sudo modprobe uinput`.
+
+Without it Neru still scrolls, through the compositor's virtual pointer, but
+that path is not honored by every client: Chromium and Electron apps on
+Hyprland scroll a few pixels and then stop. `neru doctor` reports the downgrade
+under `capability.scroll` with the open error, and the daemon logs one warning
+at the first scroll that falls back.
+
+---
+
 ## Using nix home manager
 
 Minimal flake with Home Manager:

internal/adapter/accessibility/native/linux/element.go

@@ -6,6 +6,7 @@ import (
 	"image"
 	"os"
 	"slices"
+	"sync"
 	"time"
 
 	"go.uber.org/zap"
@@ -541,6 +542,10 @@ func scrollAtCursorNow(deltaX, deltaY int, modifiers action.Modifiers) error {
 		// the compositor and client can process events incrementally.
 		const maxBatchEvents = 50
 
+		// fallbackCause is the uinput error that sends the rest of the scroll
+		// to the virtual pointer, for the one-time warning below.
+		var fallbackCause error
+
 		sendScaledScroll := func(axis int, delta int) int {
 			if delta == 0 {
 				return 0
@@ -570,6 +575,7 @@ func scrollAtCursorNow(deltaX, deltaY int, modifiers action.Modifiers) error {
 						// remaining delta is retried via wlroots virtual pointer
 						// fallback without double-counting already-sent notches.
 						remainingNotches += len(batch)
+						fallbackCause = err
 
 						break
 					}
@@ -595,6 +601,8 @@ func scrollAtCursorNow(deltaX, deltaY int, modifiers action.Modifiers) error {
 			return nil
 		}
 
+		warnUinputScrollFallback(fallbackCause)
+
 		return wlrootsScrollAtCursor(remainX, remainY, 0)
 	}
 
@@ -613,6 +621,28 @@ func scrollAtCursorNow(deltaX, deltaY int, modifiers action.Modifiers) error {
 	return nil
 }
 
+// uinputScrollFallbackOnce keeps the fallback warning to one line per
+// process: the condition is a session fact, and every scroll would repeat it.
+var uinputScrollFallbackOnce sync.Once
+
+// warnUinputScrollFallback says, once, that scrolling left the uinput wheel
+// for the compositor's virtual pointer and why. The two paths look the same
+// from the log otherwise, and only the virtual pointer one is ignored by
+// Chromium and Electron clients on Hyprland — which is how a user with a
+// root-only /dev/uinput reads as "scroll works in Firefox but not Discord".
+// cause is the batch error that triggered it: the device creation failure,
+// reason included, or a write that failed after a good start.
+func warnUinputScrollFallback(cause error) {
+	uinputScrollFallbackOnce.Do(func() {
+		currentLogger().Warn(
+			"Scrolling through the wlroots virtual pointer instead of uinput; "+
+				"some clients ignore that path (grant write access to /dev/uinput, "+
+				"see docs/LINUX_SETUP.md)",
+			zap.Error(cause),
+		)
+	})
+}
+
 // hyprlandKeepsUinputScroll reports whether a modified scroll on this session
 // keeps the uinput batch and presses the modifier beside it, rather than moving
 // the whole scroll onto the wlroots virtual pointer.

internal/adapter/accessibility/native/linux/logger.go

@@ -0,0 +1,37 @@
+//go:build linux
+
+package linux
+
+import (
+	"sync"
+
+	"go.uber.org/zap"
+)
+
+// pkgLogger is the process-global logger for the Linux injection backends,
+// a slot beside configProvider for the same reason: the scroll path picks its
+// backend at call time, deep below any struct that carries a logger, and the
+// one thing worth saying from there is which backend it ended up on.
+var (
+	pkgLoggerMu sync.RWMutex
+	pkgLogger   = zap.NewNop()
+)
+
+// SetLogger installs the logger the Linux injection backends report through.
+// It is set once at daemon startup (see internal/app/runtime_config_linux.go).
+func SetLogger(logger *zap.Logger) {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	pkgLoggerMu.Lock()
+	pkgLogger = logger.Named("accessibility.native")
+	pkgLoggerMu.Unlock()
+}
+
+func currentLogger() *zap.Logger {
+	pkgLoggerMu.RLock()
+	defer pkgLoggerMu.RUnlock()
+
+	return pkgLogger
+}

internal/adapter/eventtap/linux/evdev_scroll_cgo.go

@@ -38,11 +38,17 @@ var (
 var uinputScrollMu sync.Mutex
 
 func initUinputScroll() error {
-	var fd C.int
-	if C.neru_uinput_create_scroll(&fd) == 0 {
-		return fmt.Errorf("%w", errUinputScrollUnavailable)
+	var deviceFd C.int
+
+	created, errno := C.neru_uinput_create_scroll(&deviceFd)
+	if created == 0 {
+		// errno is the /dev/uinput open failure, which is what a user has to
+		// act on: "permission denied" means a udev rule or group, "no such
+		// file" means the uinput module is not loaded.
+		return fmt.Errorf("%w: /dev/uinput: %w", errUinputScrollUnavailable, errno)
 	}
-	uinputScrollFd = int(fd)
+
+	uinputScrollFd = int(deviceFd)
 
 	return nil
 }

internal/adapter/platform/capability_contract_test.go

@@ -263,6 +263,7 @@ func TestCapabilities_ProbeCoverageIsDocumented(t *testing.T) {
 	// device) or has only a mutating entry point, so it is checked by that
 	// subsystem's own tests instead of here.
 	uncovered := map[ports.CapabilityKey]string{
+		ports.CapabilityScroll:        "injects a real scroll into the focused app",
 		ports.CapabilityAccessibility: "needs an AX client fixture; covered by internal/adapter/accessibility",
 		ports.CapabilityOverlay:       "needs a live overlay manager; covered by internal/adapter/overlay",
 		ports.CapabilityNotifications: "only entry point displays UI to the user",

internal/adapter/platform/linux/evdev.c

@@ -95,33 +95,45 @@ int neru_evdev_get_pressed_keys(int fd, unsigned int *out_keys, int max_keys) {
 	return count;
 }
 
+/* Close fd without disturbing the errno the caller is about to report. */
+static void neru_uinput_fail(int fd) {
+	int saved = errno;
+	close(fd);
+	errno = saved;
+}
+
+/* On failure errno describes the /dev/uinput open (or the ioctl that
+ * refused), so the Go side can tell "permission denied" from "no such
+ * device" instead of reporting a bare "unavailable". */
 int neru_uinput_create_scroll(int *out_fd) {
 	int fd = open("/dev/uinput", O_RDWR);
 	if (fd < 0) {
+		int open_errno = errno;
 		fd = open("/dev/input/uinput", O_RDWR);
-	}
-	if (fd < 0) {
-		return 0;
+		if (fd < 0) {
+			errno = open_errno;
+			return 0;
+		}
 	}
 
 	if (ioctl(fd, UI_SET_EVBIT, EV_REL) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 	if (ioctl(fd, UI_SET_RELBIT, REL_WHEEL) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 	if (ioctl(fd, UI_SET_RELBIT, REL_HWHEEL) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 	if (ioctl(fd, UI_SET_RELBIT, REL_WHEEL_HI_RES) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 	if (ioctl(fd, UI_SET_RELBIT, REL_HWHEEL_HI_RES) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 
@@ -132,18 +144,32 @@ int neru_uinput_create_scroll(int *out_fd) {
 	usetup.id.product = 0x5678;
 	strcpy(usetup.name, "neru-scroll");
 	if (ioctl(fd, UI_DEV_SETUP, &usetup) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 	if (ioctl(fd, UI_DEV_CREATE) < 0) {
-		close(fd);
+		neru_uinput_fail(fd);
 		return 0;
 	}
 
 	*out_fd = fd;
 	return 1;
 }
 
+/* Create the scroll wheel the way the scroll path does, then tear it down
+ * again. Opening the node alone is not the question `neru doctor` asks: the
+ * UI_SET_* and UI_DEV_CREATE ioctls can refuse on a node that opened. On
+ * failure errno is the same one neru_uinput_create_scroll leaves. */
+int neru_uinput_probe_scroll(void) {
+	int fd;
+	if (!neru_uinput_create_scroll(&fd)) {
+		return 0;
+	}
+	ioctl(fd, UI_DEV_DESTROY);
+	close(fd);
+	return 1;
+}
+
 int neru_uinput_scroll(int fd, int axis, int value) {
 	struct input_event ev;
 	memset(&ev, 0, sizeof(ev));

internal/adapter/platform/linux/evdev.h

@@ -14,6 +14,7 @@ int neru_evdev_get_bustype(int fd);
 ssize_t neru_evdev_read_event(int fd, struct input_event *event);
 int neru_evdev_get_pressed_keys(int fd, unsigned int *out_keys, int max_keys);
 int neru_uinput_create_scroll(int *out_fd);
+int neru_uinput_probe_scroll(void);
 int neru_uinput_scroll(int fd, int axis, int value);
 int neru_uinput_scroll_batch(int fd, int axis, int *values, int count);
 int neru_uinput_create_keyboard(int *out_fd);

internal/adapter/platform/linux/scroll_capability_cgo.go

@@ -0,0 +1,24 @@
+//go:build linux && cgo
+
+package linux
+
+/*
+#include "evdev.h"
+*/
+import "C"
+
+import "fmt"
+
+// uinputScrollDeviceError reports why the uinput scroll wheel cannot be
+// created, or nil when it can. It builds and destroys the same device the
+// scroll path uses, so a node that opens but refuses an ioctl is reported
+// too. The errno is the part a user acts on: "permission denied" means a
+// udev rule or group, "no such file" means the uinput module is not loaded.
+func uinputScrollDeviceError() error {
+	created, errno := C.neru_uinput_probe_scroll()
+	if created == 0 {
+		return fmt.Errorf("%s: %w", uinputDevicePath, errno)
+	}
+
+	return nil
+}

internal/adapter/platform/linux/scroll_capability_nocgo.go

@@ -0,0 +1,14 @@
+//go:build linux && !cgo
+
+package linux
+
+import "github.com/y3owk1n/neru/internal/derrors"
+
+// uinputScrollDeviceError reports that the uinput scroll wheel is compiled
+// out: the device is created through cgo.
+func uinputScrollDeviceError() error {
+	return derrors.New(
+		derrors.CodeNotSupported,
+		"uinput scroll device unavailable: this binary was built with CGO_ENABLED=0",
+	)
+}

internal/adapter/platform/linux/scroll_capability_test.go

@@ -0,0 +1,54 @@
+//go:build linux
+
+package linux
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/y3owk1n/neru/internal/ports"
+)
+
+// TestScrollCapability_UinputUnwritableNamesTheFix pins what `neru doctor`
+// prints when the uinput wheel cannot be opened: a downgrade rather than a
+// green row, carrying the open error and the device to make writable.
+func TestScrollCapability_UinputUnwritableNamesTheFix(t *testing.T) {
+	declared := ports.FeatureCapability{Status: ports.FeatureStatusSupported, Detail: "declared"}
+
+	tests := []struct {
+		name       string
+		uinputErr  error
+		wantStatus ports.FeatureStatus
+		wantDetail []string
+	}{
+		{
+			name:       "uinput writable keeps the declared capability",
+			uinputErr:  nil,
+			wantStatus: ports.FeatureStatusSupported,
+			wantDetail: []string{"declared"},
+		},
+		{
+			name:       "uinput unwritable downgrades with the reason and the device",
+			uinputErr:  &os.PathError{Op: "open", Path: uinputDevicePath, Err: os.ErrPermission},
+			wantStatus: ports.FeatureStatusStub,
+			wantDetail: []string{"permission denied", uinputDevicePath, "virtual pointer"},
+		},
+	}
+
+	for _, testCase := range tests {
+		t.Run(testCase.name, func(t *testing.T) {
+			got := scrollCapability(declared, testCase.uinputErr)
+
+			if got.Status != testCase.wantStatus {
+				t.Fatalf("Status = %q, want %q", got.Status, testCase.wantStatus)
+			}
+
+			for _, want := range testCase.wantDetail {
+				if !strings.Contains(got.Detail, want) {
+					t.Errorf("Detail %q does not mention %q", got.Detail, want)
+				}
+			}
+		})
+	}
+}