feat(hotkeys): glide the cursor smoothly while a relative-move key is held (#1626)

Author: y3owk1n

AGENTS.md

@@ -68,7 +68,7 @@ Hard rules that apply everywhere:
 - **Errors**: use `derrors` (`derrors.New` / `derrors.Wrap`). Unsupported platform behavior returns `derrors.CodeNotSupported` explicitly — never a silent no-op; callers degrade via `IsNotSupported`.
 - **`modes.Handler` has a strict locking contract** — read `internal/app/modes/AGENTS.md` before touching modes or anything that calls back into the handler.
 
-Runtime shape: a daemon plus a thin CLI. `neru launch` starts the daemon; other commands dial a per-user Unix socket (`$XDG_RUNTIME_DIR/neru/neru.sock`, else `$TMPDIR/neru-<uid>/neru.sock`, 0600 in a 0700 directory) or a per-user Windows named pipe (`\\.\pipe\neru-<SID>`) — transport in `internal/adapter/ipc`, handlers in `internal/app/ipcctrl`. The endpoint stays scoped to one user and never widens; `docs/ARCHITECTURE.md` (Runtime Shape) owns the detail. New user-facing behavior usually needs a CLI command, an IPC handler, and the service/mode work behind it (the `add-cli-command` skill walks it). Startup is a numbered, individually-unwound phase sequence in `internal/app/new.go`. Input flow: native event tap → `adapter/eventtap` → `app/modes/handler.go` → active `Mode` → `app/services/*` → adapter → native API.
+Runtime shape: a daemon plus a thin CLI. `neru launch` starts the daemon; other commands dial a per-user Unix socket (`$XDG_RUNTIME_DIR/neru/neru.sock`, else `$TMPDIR/neru-<uid>/neru.sock`, 0600 in a 0700 directory) or a per-user Windows named pipe (`\\.\pipe\neru-<SID>`) — transport in `internal/adapter/ipc`, handlers in `internal/app/ipcctrl`. The endpoint stays scoped to one user and never widens; `docs/ARCHITECTURE.md` (Runtime Shape) owns the detail. New user-facing behavior usually needs a CLI command, an IPC handler, and the service/mode work behind it (the `add-cli-command` skill walks it). Startup is a numbered, individually-unwound phase sequence in `internal/app/new.go`. Input flow: native event tap → `adapter/eventtap` → `app/modes/handler.go` → active `Mode` → `app/services/*` → adapter → native API. Keys steering the held-key glide leave that path at the handler (and at the hotkey binder): `app/heldmotion` integrates the held set on its own tick and posts to the system port directly.
 
 Configuration is hot-reloadable TOML; adding an option touches five links every time and up to four more when it needs them, with a guardrail test behind most of them — read `internal/config/AGENTS.md` or use the `add-config-option` skill. One of the five is the option's **platform column**: every option, mode flag and action declares which of macOS, Linux and Windows writing it does anything on, beside the vocabulary that owns it, and writing an inert one warns at load rather than refusing (`docs/adr/0013-parity-is-measured-in-words-not-subsystems.md`).
 

configs/default-config.toml

@@ -416,12 +416,12 @@ duration_per_pixel = 1.00                   # Ms per pixel for adaptive duration
 # Held-key repeat (fires scroll/page/mouse-move actions repeatedly while held)
 # See https://github.com/y3owk1n/neru/blob/main/docs/CONFIGURATION.md#held_repeat
 [held_repeat]
-enabled = false                         # Master toggle for held-key repeat
+enabled = false                         # Master toggle for held-key repeat (a held move_mouse_relative glides)
 initial_delay_ms = 50                   # Delay before first repeat fires (ms)
 interval_ms = 50                        # Interval between subsequent repeats (ms)
-accel_enabled = false                   # Ramp step distance up the longer the key is held
+accel_enabled = false                   # Ramp the glide's speed up the longer the key stays held
 accel_ramp_ms = 500                     # Hold time to reach accel_max_multiplier (ms)
-accel_max_multiplier = 4.0              # Step distance multiplier at full ramp
+accel_max_multiplier = 4.0              # Speed multiplier at full ramp
 accel_targets = ["move_mouse_relative"] # Action names eligible for acceleration
 
 # Systray

docs/ARCHITECTURE.md

@@ -262,7 +262,12 @@ clearer is covered in
 2. **Adapters** — [adapter.go](../internal/adapter/eventtap/adapter.go)
    receives and dispatches them
 3. **Application** — [handler.go](../internal/app/modes/handler.go) routes the
-   key to the active [Mode](../internal/app/modes/base.go)
+   key to the active [Mode](../internal/app/modes/base.go). A held direction
+   key in the held-key glide is the one exception: the handler and the global
+   hotkey binder both press it into
+   [heldmotion](../internal/app/heldmotion/controller.go), whose fixed-rate
+   loop integrates the held set into cursor moves and posts them straight to
+   the system port, never through a mode
 4. **Service** — the mode calls into
    [hint_service.go](../internal/app/services/hint_service.go) and friends
 5. **Keyboard layout changes** — on macOS the mode-level CGEventTap rebuilds its

docs/CONFIGURATION.md

@@ -1614,16 +1614,16 @@ duration_per_pixel = 1.0
 
 ## [held_repeat]
 
-Repeatedly dispatches scroll, page, relative-mouse-move, and `move_cell` actions while the key is held, with a configurable initial delay and repeat interval. Disable held-key repeat entirely by setting `enabled = false`.
+Repeatedly dispatches scroll, page, and `move_cell` actions while the key is held, with a configurable initial delay and repeat interval, and glides the cursor for a held `move_mouse_relative` (see [Glide](#glide)). Disable held-key behaviour entirely by setting `enabled = false`.
 
 | Option                 | Type     | Default                   | Description                                      |
 | ---------------------- | -------- | ------------------------- | ------------------------------------------------ |
-| `enabled`              | bool     | `false`                   | Master toggle for held-key repeat                |
+| `enabled`              | bool     | `false`                   | Master toggle for held-key repeat and the glide  |
 | `initial_delay_ms`     | int      | `50`                      | Delay before first repeat fires (ms)             |
 | `interval_ms`          | int      | `50`                      | Interval between subsequent repeats (ms)         |
-| `accel_enabled`        | bool     | `false`                   | Ramp step distance up the longer the key is held |
+| `accel_enabled`        | bool     | `false`                   | Ramp the glide's speed up the longer the key stays held |
 | `accel_ramp_ms`        | int      | `500`                     | Hold time to reach `accel_max_multiplier` (ms)   |
-| `accel_max_multiplier` | float    | `4.0`                     | Step distance multiplier at full ramp            |
+| `accel_max_multiplier` | float    | `4.0`                     | Speed multiplier at full ramp                    |
 | `accel_targets`        | string[] | `["move_mouse_relative"]` | Action names eligible for acceleration           |
 
 ```toml
@@ -1637,29 +1637,41 @@ accel_max_multiplier = 4.0
 accel_targets = ["move_mouse_relative"]
 ```
 
+### Glide
+
+With `enabled = true`, holding a key bound to a lone `move_mouse_relative` does
+not repeat its step. The key contributes a direction, read from the sign of its
+`--dx`/`--dy`, to one continuous glide: the cursor starts moving the moment the
+key goes down at the binding's step per `interval_ms` (the default 10px step
+every 50ms is 200px/s) and keeps that speed until release. Two keys held
+together move diagonally at the same speed as one key moves straight, and
+opposite keys cancel; when held keys have different steps the larger one sets
+the speed. A short tap still travels about one step.
+
+The glide runs on its own 10ms tick from the moment a key goes down until the
+last direction key is released, with a subpixel position so slow speeds stay
+smooth, so `initial_delay_ms` does not apply to it. It works across monitors,
+and a click or any other action fired while moving acts at the cursor's live
+position. Scroll, page and `move_cell` keep their fixed step and repeat on
+`interval_ms` as before.
+
 ### Acceleration
 
-With `accel_enabled = true`, a held key ramps linearly from 1x to `accel_max_multiplier`
-over `accel_ramp_ms`, then holds there until release. With the values above the
-multiplier is 2.5x at 250ms and 4x from 500ms onward, so a binding of
-`action move_mouse_relative --dx=20 --dy=0` moves 50px per tick at 250ms and 80px per
-tick from 500ms. The repeat interval never changes, only the per-tick distance, which is
-how pointer acceleration works at the OS level and avoids rescheduling the repeat timer
-on every tick.
-
-The ramp is measured from the first repeat, not from the key press, so `initial_delay_ms`
-does not eat into it.
-
-Acceleration only applies to actions listed in `accel_targets`. Scaling acts on the
-action's `--dx`/`--dy` flags, which only `move_mouse_relative` accepts, so that is
-currently the sole valid entry: anything else is a config error rather than a binding
-that silently never accelerates. An empty `accel_targets` while `accel_enabled = true` is
-rejected for the same reason. Scroll and page keep their fixed step.
-
-`accel_enabled = true` while `enabled = false` is not an error: acceleration scales a
-repeat, so with no repeat to scale it simply does nothing, and refusing the file would
-stop you turning held-key repeat off without also unwinding the settings under it.
-`neru config validate` reports it as a warning instead.
+With `accel_enabled = true`, the glide's speed ramps linearly to
+`accel_max_multiplier` times the binding's speed over `accel_ramp_ms`, then holds
+there until release. With the values above a 10px binding is at 500px/s after
+250ms and 800px/s from 500ms onward. Leave it off for a glide at constant speed.
+
+Acceleration only applies to actions listed in `accel_targets`. Only
+`move_mouse_relative` glides, so that is currently the sole valid entry:
+anything else is a config error rather than a binding that silently never
+accelerates. An empty `accel_targets` while `accel_enabled = true` is rejected
+for the same reason.
+
+`accel_enabled = true` while `enabled = false` is not an error: acceleration
+shapes a glide, so with no glide to shape it simply does nothing, and refusing
+the file would stop you turning held-key behaviour off without also unwinding
+the settings under it. `neru config validate` reports it as a warning instead.
 
 ---
 

docs/CROSS_PLATFORM.md

@@ -167,6 +167,7 @@ answer.
 | **Scroll injection**          | ✅ both axes             | ✅ both axes ⁷         | ✅ both axes (uinput, virtual-pointer fallback) | ✅ both axes (uinput, libei fallback) | ✅ both axes ⁷               |
 | **Modified scroll (`--modifier`)** | ✅ `CGEventSetFlags` on every chunk | ✅ XTest key hold ⁷ | ✅ virtual keyboard + virtual pointer (uinput 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 | ✅ incl. relative, opt-in |
+| **Held-key glide (`held_repeat`)** | ✅ `CGEventPost` per tick | ✅ XTest per tick | ✅ virtual-pointer relative motion per tick | ✅ libei per tick | ✅ `SetCursorPos` per tick |
 | **Smooth scroll animation**   | ✅                       | ⚠️ whole notches only ³ | ✅ continuous axis ³ (whole notches when modified on Hyprland ⁹) | ⚠️ libei scroll delta, unverified ³ | ✅ 120ths of a notch ³ |
 | **Element discovery (hints)** | ✅ AXUIElement           | ⚠️ AT-SPI walk         | ⚠️ AT-SPI walk               | ⚠️ AT-SPI walk          | ⚠️ UIA, control view only    |
 | **Overlay**                   | ✅ NSPanel + CoreAnimation | ✅ X11 + Cairo       | ✅ layer-shell + Cairo       | ✅ layer-shell + Cairo  | ✅ DirectComposition + Direct2D (GDI fallback; windows/arm64 is GDI only ¹⁰) |
@@ -1042,8 +1043,8 @@ Current ports: `SystemPort`, `AccessibilityPort`, `OverlayPort`, `EventTapPort`,
 `HotkeyPort`, `IPCPort`, `VisionPort`, `TextInputPort`, `KeyFeedPort`,
 `AppWatcherPort`, `SystrayPort`, `FontResolver`.
 
-Optional extensions (Tier 3): `RelativeCursorMover` and `CursorSynchronizer`
-on `SystemPort`, `HotkeyReleaseRegistrar` and `HotkeyHealthReporter` on
+Optional extensions (Tier 3): `RelativeCursorMover`, `CursorSynchronizer`
+and `InstantCursorMover` on `SystemPort`, `HotkeyReleaseRegistrar` and `HotkeyHealthReporter` on
 `HotkeyPort`, `OverlayKeyboardPassthroughReporter` on `EventTapPort`,
 `OverlayCapabilityReporter` on `OverlayPort`, and `SyntheticModifierSink` on
 the `tap.Tap` backend contract (Linux only, declared in a `_linux.go` file

internal/adapter/platform/darwin/mouse.go

@@ -105,6 +105,16 @@ func MoveMouse(point image.Point, bypassSmooth bool) {
 	}
 }
 
+// PostMouseMove posts one absolute cursor move (or drag, while a button is
+// held) and returns at once. Unlike MoveMouse it neither animates nor spins
+// the run loop, so a fixed-rate motion loop can call it every tick.
+func PostMouseMove(point image.Point) {
+	cursorAnimator.stop()
+
+	eventType, button := dragEventType()
+	postCursorMoveEvent(point, uint32(eventType), uint32(button))
+}
+
 // MoveMouseSmooth moves the mouse cursor smoothly to the specified point.
 func MoveMouseSmooth(end image.Point, steps int, eventType, button uint32) {
 	cursorAnimator.animateTo(end, steps, eventType, button)

internal/adapter/platform/darwin/system.go

@@ -126,6 +126,14 @@ func (s *SystemAdapter) MoveCursorBy(
 	return MoveMouseRelativeSmooth(delta), nil
 }
 
+// MoveCursorInstantly posts one cursor move without animating or waiting
+// (ports.InstantCursorMover).
+func (s *SystemAdapter) MoveCursorInstantly(ctx context.Context, point image.Point) error {
+	PostMouseMove(point)
+
+	return nil
+}
+
 // WaitForCursorIdle blocks until any in-flight cursor movement animation settles.
 func (s *SystemAdapter) WaitForCursorIdle(ctx context.Context) error {
 	return cursorAnimator.wait(ctx)
@@ -226,6 +234,9 @@ var _ ports.SystemPort = (*SystemAdapter)(nil)
 // moves when smooth cursor is enabled).
 var _ ports.RelativeCursorMover = (*SystemAdapter)(nil)
 
+// SystemAdapter posts single moves without waiting for the held-key glide.
+var _ ports.InstantCursorMover = (*SystemAdapter)(nil)
+
 // Ensure SystemAdapter opts into settling in-flight cursor animations before
 // position-dependent actions.
 var _ ports.CursorSettler = (*SystemAdapter)(nil)

internal/adapter/platform/linux/system_common.go

@@ -365,6 +365,33 @@ func (s *SystemAdapter) MoveCursorToPoint(
 	return s.moveCursorDirect(point)
 }
 
+// MoveCursorInstantly posts one cursor move and returns at once
+// (ports.InstantCursorMover). Both animators are stopped first so a stale
+// step cannot land after it. On wlroots the move is injected as a relative
+// delta against the client-side cache — the same reason MoveCursorBy stays in
+// delta space there: nothing can query the real pointer, so an absolute warp
+// would jump by however stale the cache is. X11 and KDE warp directly.
+func (s *SystemAdapter) MoveCursorInstantly(ctx context.Context, point image.Point) error {
+	err := ctx.Err()
+	if err != nil {
+		return err
+	}
+
+	s.relativeAnimator.stop()
+	s.cursorAnimator.stop()
+
+	if s.backend == backendWaylandWlroots {
+		cached, err := waylandCursorPosition()
+		if err != nil {
+			return err
+		}
+
+		return wlrootsMoveCursorBy(point.Sub(cached))
+	}
+
+	return s.moveCursorDirect(point)
+}
+
 // MoveCursorBy applies a relative cursor move. With smooth cursor enabled
 // (smooth_cursor.move_mouse_enabled) the move animates over the fixed
 // per-move duration smooth_cursor.relative_movement_duration:
@@ -1081,3 +1108,6 @@ func darkModeCapability(value int, source darkModeSource, ok bool) ports.Feature
 		Detail: "current state: " + label + " (source=" + string(source) + ")",
 	}
 }
+
+// SystemAdapter posts single moves without waiting for the held-key glide.
+var _ ports.InstantCursorMover = (*SystemAdapter)(nil)

internal/adapter/platform/linux/system_stub_contract_test.go

@@ -406,9 +406,10 @@ func TestSystemAdapter_StartsNoCompositorBridgeOffKDE(t *testing.T) {
 	}
 }
 
-// TestSystemAdapter_MoveCursorToPointReportsNotSupported covers the one mutating
-// method worth pinning here. It is safe on an unimplemented backend precisely
-// because nothing is wired up to move — which is the behavior being asserted.
+// TestSystemAdapter_MoveCursorToPointReportsNotSupported covers the two mutating
+// methods worth pinning here (its sibling below is the second). They are safe on
+// an unimplemented backend precisely because nothing is wired up to move — which
+// is the behavior being asserted.
 func TestSystemAdapter_MoveCursorToPointReportsNotSupported(t *testing.T) {
 	adapter := linux.NewSystemAdapter(unimplementedBackend)
 
@@ -422,3 +423,17 @@ func TestSystemAdapter_MoveCursorToPointReportsNotSupported(t *testing.T) {
 			err, derrors.GetCode(err))
 	}
 }
+
+func TestSystemAdapter_MoveCursorInstantlyReportsNotSupported(t *testing.T) {
+	adapter := linux.NewSystemAdapter(unimplementedBackend)
+
+	err := adapter.MoveCursorInstantly(context.Background(), image.Point{X: 10, Y: 10})
+	if err == nil {
+		t.Fatal("MoveCursorInstantly on an unimplemented backend returned nil")
+	}
+
+	if !derrors.IsNotSupported(err) {
+		t.Errorf("MoveCursorInstantly returned %v (code %q), want CodeNotSupported",
+			err, derrors.GetCode(err))
+	}
+}

internal/adapter/platform/windows/system.go

@@ -234,6 +234,20 @@ func (s *SystemAdapter) MoveCursorToPoint(
 	return moveCursorTo(point)
 }
 
+// MoveCursorInstantly warps the cursor with SetCursorPos and returns at once
+// (ports.InstantCursorMover). Like the bypass branch of MoveCursorToPoint it
+// stops the animator first, so a stale glide step cannot land after the warp.
+func (s *SystemAdapter) MoveCursorInstantly(ctx context.Context, point image.Point) error {
+	err := ctx.Err()
+	if err != nil {
+		return err
+	}
+
+	s.cursorAnimator.stop()
+
+	return moveCursorTo(point)
+}
+
 // MoveCursorBy applies a relative cursor move. With smooth cursor enabled
 // (smooth_cursor.move_mouse_enabled) the delta extends the animator's pending
 // endpoint, clamped to the active screen, and animates over the fixed
@@ -367,3 +381,6 @@ var (
 	_ ports.RelativeCursorMover = (*SystemAdapter)(nil)
 	_ ports.CursorSettler       = (*SystemAdapter)(nil)
 )
+
+// SystemAdapter posts single moves without waiting for the held-key glide.
+var _ ports.InstantCursorMover = (*SystemAdapter)(nil)