feat(windows): horizontal scroll injection (#1578)

Author: y3owk1n

docs/CLI.md

@@ -106,8 +106,7 @@ macOS, an AT-SPI walk on Linux whose coverage depends on the application, and a
 cached UI Automation walk of the control view on Windows. The `vision` strategy is the
 fallback where that tree is thin. See [Accessibility and hints](CROSS_PLATFORM.md#accessibility-and-hints).
 
-² Two action subcommands are limited: `hide_cursor` and `show_cursor` are macOS
-only, and `scroll_left` / `scroll_right` have no effect on Windows. See
+² `hide_cursor` and `show_cursor` are macOS only. See
 [Action platform support](#action-platform-support).
 
 ---
@@ -577,7 +576,6 @@ Every action not listed here behaves identically on macOS, Linux, and Windows.
 | Action                            | macOS | Linux | Windows | Note                                                     |
 | --------------------------------- | :---: | :---: | :-----: | -------------------------------------------------------- |
 | `hide_cursor`, `show_cursor`      | Yes   | No    | No      | Uses a Quartz API with no cross-platform equivalent; a no-op elsewhere. |
-| `scroll_left`, `scroll_right`     | Yes   | Yes   | No      | Windows scroll injection ignores the horizontal delta.    |
 | `move_monitor`                    | Yes   | Yes   | Yes     | Requires more than one display.                           |
 
 The injection mechanism differs per platform even where behaviour matches:
@@ -810,9 +808,8 @@ A modified scroll is what most applications read as zoom, so
 modifier is not implied by the binding: `"Ctrl+K" = "action scroll_up"` scrolls
 unmodified, and it is `--modifier ctrl` that makes it zoom.
 
-**Platforms:** vertical scrolling works everywhere. Horizontal scrolling
-(`scroll_left`, `scroll_right`) is not implemented on Windows and has no effect
-there. For what each backend does with `--modifier`, see the
+**Platforms:** scrolling works on both axes everywhere. For what each backend
+does with `--modifier`, see the
 [capability matrix](CROSS_PLATFORM.md#capability-matrix).
 
 **Examples**

docs/CROSS_PLATFORM.md

@@ -177,7 +177,7 @@ that is what [Known Gaps](#known-gaps) tracks, per
 | **Cursor position**           | ✅ `CGEventGetLocation`  | ✅ `XQueryPointer`     | ✅ compositor IPC (Hyprland) / sync-surface trick | ✅ sync-surface trick | ✅ `GetCursorPos` |
 | **Cursor move**               | ✅ `CGEventPost` ([`postMouseMoveLocked`](../internal/adapter/platform/darwin/accessibility_mouse_darwin.m)) | ✅ XTest (`XTestFakeMotionEvent`) | ✅ `zwlr_virtual_pointer` | ✅ libei                | ✅ `SetCursorPos`            |
 | **Mouse buttons / drag**      | ✅ `CGEventPost`         | ✅ XTest ⁷             | ✅ `zwlr_virtual_pointer`    | ✅ libei                | ✅ `SendInput`               |
-| **Scroll injection**          | ✅ both axes             | ✅ both axes ⁷         | ✅ both axes (uinput + virtual pointer) | ✅ libei     | ⚠️ vertical only             |
+| **Scroll injection**          | ✅ both axes             | ✅ both axes ⁷         | ✅ both axes (uinput + virtual pointer) | ✅ libei     | ✅ both axes                 |
 | **Modified scroll (`--modifier`)** | ✅ `CGEventSetFlags` on every chunk | ✅ XTest key hold ⁷ | ✅ virtual keyboard, uinput batch skipped (kept on Hyprland ⁹) | ✅ libei | ✅ `SendInput` key hold |
 | **Smooth cursor animation**   | ✅ (incl. relative, opt-in) | ✅ incl. relative, opt-in | ✅ incl. relative, opt-in | ✅ incl. relative, opt-in | ❌                        |
 | **Smooth scroll animation**   | ✅                       | ⚠️ whole notches only ³ | ✅ continuous virtual-pointer axis ³ (whole notches when modified on Hyprland ⁹) | ⚠️ libei scroll delta, unverified ³ | ❌       |
@@ -620,9 +620,10 @@ Go; only the final injection primitive differs:
 | Linux Wayland KDE     | libei via `org.freedesktop.portal.RemoteDesktop`                              |
 | Windows               | `SendInput` / `SetCursorPos`                                                  |
 
-**The one behavioral difference:** Windows `ScrollAtCursor` ignores `deltaX`, so
-horizontal scrolling is a no-op there. Everything else behaves the same on all
-three platforms.
+Scrolling behaves the same on all three platforms, both axes included: Windows
+posts `MOUSEEVENTF_HWHEEL` for the horizontal component, with the sign flipped
+because Win32 reads a positive horizontal notch as right where Neru, macOS and
+X11 read it as left.
 
 **Modifiers on a scroll** reach the injection primitive by two different routes,
 because only one of the primitives has a field for them. macOS stamps
@@ -1105,8 +1106,6 @@ green in every cell while an option means nothing, which is exactly how
 | `smooth_scroll.duration_per_pixel` | option | ✅ | ✅ | ❌ | the Windows scroll is injected in one step; macOS and Linux animate it, and on X11 the steps are whole wheel notches because X has no smaller scroll to send |
 | `hide_cursor` | action | ✅ | ❌ | ❌ | a Wayland client may not hide another client's cursor, and the blessed Linux stack is Wayland; Windows has no equivalent either |
 | `show_cursor` | action | ✅ | ❌ | ❌ | a Wayland client may not hide another client's cursor, and the blessed Linux stack is Wayland; Windows has no equivalent either |
-| `scroll_left` | action | ✅ | ✅ | ❌ | the Windows wheel event carries no horizontal delta, so a sideways scroll injects nothing |
-| `scroll_right` | action | ✅ | ✅ | ❌ | the Windows wheel event carries no horizontal delta, so a sideways scroll injects nothing |
 | `feed` | action | ✅ | ✅ | ❌ | Windows has no key-injection path yet, so the key it would post is never sent; the key_feed capability reports stub to match |
 
 <!-- END GENERATED PLATFORM SUPPORT -->
@@ -1208,12 +1207,11 @@ working, which is exactly why the build exists.
    it stays declared everywhere and is tracked as this entry instead
 4. Smooth cursor and smooth scroll animation — not implemented
 5. Modifier passthrough and `PostModifierEvent` — no-ops
-6. Horizontal scroll — `ScrollAtCursor` ignores `deltaX`
-7. `monitor_select` mode — returns `CodeNotSupported`
-8. Font resolution — alias mapping only, no system font enumeration
-9. `neru services` — every subcommand returns `CodeNotSupported`, where macOS
-    installs a launchd agent and Linux a systemd user unit
-10. IPC endpoint, client side — the daemon's endpoint is scoped to one user on
+6. `monitor_select` mode — returns `CodeNotSupported`
+7. Font resolution — alias mapping only, no system font enumeration
+8. `neru services` — every subcommand returns `CodeNotSupported`, where macOS
+   installs a launchd agent and Linux a systemd user unit
+9. IPC endpoint, client side — the daemon's endpoint is scoped to one user on
     every platform, but only the Unix client checks that for itself before
     connecting. A named pipe carries no ownership a client can read without
     opening it, so the Windows CLI trusts the name it derives from its own SID.

docs/ROADMAP.md

@@ -44,7 +44,7 @@ The two largest open areas:
   CGO build rather than missing code, and whose remaining work is failing
   loudly with the remedy.
 - **Windows** — the remaining Known Gaps entries: notifications, UIA tree
-  depth, animations, horizontal scroll and `monitor_select`.
+  depth, animations and `monitor_select`.
 
 GNOME Wayland remains unsupported; the daemon refuses to start there. Reviving
 it needs libei plus a GNOME Shell extension — see

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

@@ -11,7 +11,6 @@ import (
 	"github.com/y3owk1n/neru/internal/adapter/platform/mousestate"
 	winplatform "github.com/y3owk1n/neru/internal/adapter/platform/windows"
 	"github.com/y3owk1n/neru/internal/config"
-	"github.com/y3owk1n/neru/internal/derrors"
 	"github.com/y3owk1n/neru/internal/domain/action"
 	"github.com/y3owk1n/neru/internal/domain/element"
 )
@@ -322,22 +321,10 @@ func MouseUp(button action.MouseButton) error {
 	return MouseUpAtPoint(pos, button, 0)
 }
 
-// ScrollAtCursor scrolls the mouse, with modifiers presented as held.
-//
-// Windows scroll injection has no horizontal axis, so a horizontal delta is
-// dropped — a long-standing, documented no-op. Dropping a modifier along with
-// it is a different matter: the user asked for a zoom and would be told it
-// happened, so a horizontal scroll carrying one is refused instead.
+// ScrollAtCursor scrolls the mouse on both axes, with modifiers presented as
+// held.
 func ScrollAtCursor(deltaX int, deltaY int, modifiers action.Modifiers) error {
-	if deltaY == 0 && deltaX != 0 && modifiers != 0 {
-		return derrors.Newf(
-			derrors.CodeNotSupported,
-			"horizontal scroll is not supported on Windows, so its %s modifier cannot be honored",
-			modifiers,
-		)
-	}
-
-	return winplatform.ScrollWheel(deltaY, modifiers)
+	return winplatform.ScrollWheel(deltaX, deltaY, modifiers)
 }
 
 // CurrentCursorPosition returns the cursor position.

internal/adapter/accessibility/native/windows/scroll_modifier_stub_contract_test.go

@@ -5,7 +5,7 @@ The One Rule (root `AGENTS.md`) is enforced here hardest: non-darwin-tagged code
 - **Start at `profile.go`** — source of truth for each subsystem's backend family and whether a backend needs CGO (a per-backend decision, not per-OS).
 - **File slots** — use the existing slot, never invent layout: `*_darwin.go`, `*_windows.go`, `*_linux.go`, `*_other.go` (non-target fallback), `*_linux_common.go`, `*_linux_x11.go`, `*_linux_wayland.go`, `*_linux_wayland_<compositor>.go`. Inside a directory that is already one platform (`platform/linux/`, `overlay/linux/`, …) the OS token is dropped, because the directory carries it: `system_x11_cgo.go`, not `system_linux_x11_cgo.go`. `docs/CROSS_PLATFORM.md` ("File Layout Rules") owns the table and what each slot holds today; `internal/architecture/platform_slots_test.go` is what fails.
 - **Factory** — `factory.go` + build-tagged siblings are the only place that picks a `ports.SystemPort`. Linux adds a runtime axis: `backend_linux.go` detects the live compositor (wlroots / KDE / GNOME / other) and owns what is named after it — `IsWayland`, the `display_server` label; never probe the compositor elsewhere, ask `DetectLinuxBackend`. `internal/architecture/compositor_detector_test.go` pins that by confining the desktop-identity variables (`XDG_CURRENT_DESKTOP`, `XDG_SESSION_TYPE`, …) to that file. The wlroots socket trio (`SWAYSOCK`, `NIRI_SOCKET`, `HYPRLAND_INSTANCE_SIGNATURE`) answers a question the backend enum cannot — which compositor CLI to shell out to — so it stays readable, but only downstream of the backend and never as a way to decide it; `internal/architecture/compositor_socket_test.go` pins that and lists the files entitled to read it.
-- **Stubs are loud** — return `derrors.CodeNotSupported`, never a silent no-op, whenever the signature has an error to carry it. A `bool` answer has none, and `true` is not a silent no-op: `SystemPort.CheckScreenCapturePermission` and `platform.CheckAccessibilityPermissions` report "this platform has no such gate" where there is none, which `ports/system.go` specifies — and where there *is* one they report it, so that bool is a live consent state on macOS and on Linux's `wayland-kde`, whose portal ScreenCast grant is the only way to read a KWin screen — making them loud would re-prompt forever for a consent that is already granted. Contract tests pin the loudness per subsystem, not for every stub in the tree; each lives beside the stub it pins as `*stub_contract*_test.go`. The ones that exist are `platform/linux/system_stub_contract_test.go`, `overlay/linux/stub_contract_test.go`, `eventtap/linux/global_hotkey_stub_contract_nocgo_test.go`, `vision/adapter_stub_contract_other_test.go` and its Linux and Windows siblings `vision/adapter_stub_contract_linux_test.go` and `vision/adapter_stub_contract_windows_test.go` (the port is implemented there, so those files pin the *shape* of every answer rather than a refusal — capture and recognition each return a result or a reason, never neither and never both; on Windows the one `CodeNotSupported` recognition may answer with is a missing OCR language pack, and it has to say so), `scroll_modifier_stub_contract_test.go` and `scroll_stub_contract_nocgo_test.go` in `accessibility/native/linux` (the first of those also in `accessibility/native/windows`), and `overlay_stub_contract_other_test.go` in each of `overlay/render/{grid,hints,modeindicator}`. The nocgo one is worth reading before adding a background path anywhere: it pins that `smooth_scroll` cannot turn a loud `CodeNotSupported` into silence, because the backend is detected from the environment and says nothing about whether this build can inject. Write a new one when a caller could read the stub's `nil` as success. Keep `ports/capabilities.go` / `capability_presets.go` honest: a stub reports `stub`, not `supported` (`neru doctor` reports this matrix).
+- **Stubs are loud** — return `derrors.CodeNotSupported`, never a silent no-op, whenever the signature has an error to carry it. A `bool` answer has none, and `true` is not a silent no-op: `SystemPort.CheckScreenCapturePermission` and `platform.CheckAccessibilityPermissions` report "this platform has no such gate" where there is none, which `ports/system.go` specifies — and where there *is* one they report it, so that bool is a live consent state on macOS and on Linux's `wayland-kde`, whose portal ScreenCast grant is the only way to read a KWin screen — making them loud would re-prompt forever for a consent that is already granted. Contract tests pin the loudness per subsystem, not for every stub in the tree; each lives beside the stub it pins as `*stub_contract*_test.go`. The ones that exist are `platform/linux/system_stub_contract_test.go`, `overlay/linux/stub_contract_test.go`, `eventtap/linux/global_hotkey_stub_contract_nocgo_test.go`, `vision/adapter_stub_contract_other_test.go` and its Linux and Windows siblings `vision/adapter_stub_contract_linux_test.go` and `vision/adapter_stub_contract_windows_test.go` (the port is implemented there, so those files pin the *shape* of every answer rather than a refusal — capture and recognition each return a result or a reason, never neither and never both; on Windows the one `CodeNotSupported` recognition may answer with is a missing OCR language pack, and it has to say so), `scroll_modifier_stub_contract_test.go` and `scroll_stub_contract_nocgo_test.go` in `accessibility/native/linux`, and `overlay_stub_contract_other_test.go` in each of `overlay/render/{grid,hints,modeindicator}`. The nocgo one is worth reading before adding a background path anywhere: it pins that `smooth_scroll` cannot turn a loud `CodeNotSupported` into silence, because the backend is detected from the environment and says nothing about whether this build can inject. Write a new one when a caller could read the stub's `nil` as success. Keep `ports/capabilities.go` / `capability_presets.go` honest: a stub reports `stub`, not `supported` (`neru doctor` reports this matrix).
 - **Coordinates** — shared code is global top-left origin, Y down, unscaled pixels. Cocoa's bottom-left flip happens inside the darwin adapter, open-coded at each site that needs it rather than in one file; the whole of what the rule buys is that no flipped value reaches shared Go. `docs/ARCHITECTURE.md` ("Coordinate System") owns the detail, including which packages are *not* where a flip lives.
 - **`linux/wlr_protocol/` is generated** (`just generate-all-protocols`); never hand-edit.
 

internal/adapter/platform/AGENTS.md

@@ -26,6 +26,7 @@ const (
 	mouseeventfMiddleDown = 0x0020
 	mouseeventfMiddleUp   = 0x0040
 	mouseeventfWheel      = 0x0800
+	mouseeventfHWheel     = 0x1000
 	mouseeventfAbsolute   = 0x8000
 
 	keyeventfKeyUp = 0x0002
@@ -218,15 +219,49 @@ func MouseUp(point image.Point, button action.MouseButton) error {
 	return sendMouseInput(flagsForButton(button).up, 0)
 }
 
-// ScrollWheel scrolls vertically at the current cursor position, holding
+// wheelEvent is one MOUSEEVENTF_WHEEL or MOUSEEVENTF_HWHEEL record, before
+// it is posted.
+type wheelEvent struct {
+	flags uint32
+	data  uint32
+}
+
+// wheelEvents turns a scroll delta into the wheel records SendInput needs,
+// one per axis that moves. Deltas follow Neru's shared convention: positive
+// deltaY scrolls up and positive deltaX scrolls left, which is what macOS
+// posts verbatim and what X11 maps to buttons 4 and 6. MOUSEEVENTF_WHEEL
+// agrees on the vertical sign, but MOUSEEVENTF_HWHEEL reads positive as
+// right, so the horizontal component is negated.
+func wheelEvents(deltaX, deltaY int) []wheelEvent {
+	var events []wheelEvent
+
+	if deltaY != 0 {
+		events = append(events, wheelEvent{
+			flags: mouseeventfWheel,
+			data:  uint32(int32(deltaY) * wheelDelta),
+		})
+	}
+
+	if deltaX != 0 {
+		events = append(events, wheelEvent{
+			flags: mouseeventfHWheel,
+			data:  uint32(int32(-deltaX) * wheelDelta),
+		})
+	}
+
+	return events
+}
+
+// ScrollWheel scrolls at the current cursor position on both axes, holding
 // modifiers down for the duration.
 //
 // A SendInput wheel event carries no modifier field — unlike a CGEvent, which
 // takes flags — so the only way to present a held ctrl is to press the real
 // key, wheel, and release it. Releasing only what this call pressed leaves a
 // modifier the user is physically holding untouched.
-func ScrollWheel(deltaLines int, modifiers action.Modifiers) error {
-	if deltaLines == 0 {
+func ScrollWheel(deltaX, deltaY int, modifiers action.Modifiers) error {
+	events := wheelEvents(deltaX, deltaY)
+	if len(events) == 0 {
 		return nil
 	}
 
@@ -238,7 +273,14 @@ func ScrollWheel(deltaLines int, modifiers action.Modifiers) error {
 	// Only what this call actually pressed, never the whole requested set.
 	defer releaseModifiers(pressed)
 
-	return sendMouseInput(mouseeventfWheel, uint32(int32(deltaLines)*wheelDelta))
+	for _, event := range events {
+		err := sendMouseInput(event.flags, event.data)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
 }
 
 // modifierKeys lists the virtual-key code (keys.go) for each modifier bit, in