Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: mouse-wheel still scrolls a 120px notch for an explicit zero delta, so the rule scroll enforces has two answers — and the MCP scroll tool routes to wheel (PIN-225)

Luigi Agosti52f1ba84966e
diff --git a/internal/bridge/action_pointer.go b/internal/bridge/action_pointer.go
index 3cc9944c..96a59794 100644
--- a/internal/bridge/action_pointer.go
+++ b/internal/bridge/action_pointer.go
@@ -537,6 +537,12 @@ func (b *Bridge) actionMouseUp(ctx context.Context, req ActionRequest) (map[stri
}
func (b *Bridge) actionMouseWheel(ctx context.Context, req ActionRequest) (map[string]any, error) {
+ // Resolved before the pointer target, so a request that cannot scroll is refused
+ // without reaching CDP at all.
+ deltaX, deltaY, err := wheelDelta(req)
+ if err != nil {
+ return nil, err
+ }
x, y, err := b.pointerCoordinatesFromRequest(ctx, req, true)
if err != nil {
if req.HasXY || req.NodeID > 0 || req.Selector != "" || req.TabID == "" {
@@ -547,15 +553,6 @@ func (b *Bridge) actionMouseWheel(ctx context.Context, req ActionRequest) (map[s
return nil, fmt.Errorf("resolve wheel viewport center: %w", err)
}
}
- deltaX := req.DeltaX
- deltaY := req.DeltaY
- if deltaX == 0 && deltaY == 0 {
- deltaX = req.ScrollX
- deltaY = req.ScrollY
- }
- if deltaX == 0 && deltaY == 0 {
- deltaY = 120
- }
if err := scrollByCoordinateAction(ctx, x, y, deltaX, deltaY, req.Modifiers); err != nil {
return nil, err
}
@@ -563,6 +560,25 @@ func (b *Bridge) actionMouseWheel(ctx context.Context, req ActionRequest) (map[s
return map[string]any{"wheel": true, "x": x, "y": y, "deltaX": deltaX, "deltaY": deltaY}, nil
}
+// wheelDelta resolves a wheel delta from either spelling, deltaX/deltaY or the legacy
+// scrollX/scrollY. An absent delta means one notch down, which is what a bare wheel has
+// always meant. An explicit zero is a different request and cannot share that answer, for
+// the reason a zero scroll cannot: a caller computing a delta reaches zero exactly when it
+// wants no movement. A zero on one axis only is a real scroll on the other.
+func wheelDelta(req ActionRequest) (int, int, error) {
+ deltaX, deltaY := req.DeltaX, req.DeltaY
+ if deltaX == 0 && deltaY == 0 {
+ deltaX, deltaY = req.ScrollX, req.ScrollY
+ }
+ if deltaX != 0 || deltaY != 0 {
+ return deltaX, deltaY, nil
+ }
+ if req.HasDelta || req.HasScroll {
+ return 0, 0, fmt.Errorf("a zero delta is not a scroll: pass a non-zero deltaX/deltaY")
+ }
+ return 0, 120, nil
+}
+
func (b *Bridge) actionScroll(ctx context.Context, req ActionRequest) (map[string]any, error) {
scaleScreencastCoords(ctx, &req)
if req.NodeID > 0 {
diff --git a/internal/bridge/action_request.go b/internal/bridge/action_request.go
index b6265cd2..fc02e8ba 100644
--- a/internal/bridge/action_request.go
+++ b/internal/bridge/action_request.go
@@ -88,8 +88,11 @@ type ActionRequest struct {
// mouse-wheel actions. ScrollX/ScrollY remain for backward compatibility.
DeltaX int `json:"deltaX,omitempty"`
DeltaY int `json:"deltaY,omitempty"`
- DragX int `json:"dragX"`
- DragY int `json:"dragY"`
+ // HasDelta is the DeltaX/DeltaY counterpart of HasScroll: a bare wheel means one
+ // notch down, an explicit zero means no movement, and both leave the fields at 0.
+ HasDelta bool `json:"hasDelta,omitempty"`
+ DragX int `json:"dragX"`
+ DragY int `json:"dragY"`
// A drag's destination. ToSelector takes the same unified selector vocabulary as
// Selector and the handler resolves it to ToNodeID; HasToXY separates an absent
@@ -166,11 +169,13 @@ func (r *ActionRequest) UnmarshalJSON(data []byte) error {
r.HasScroll = r.HasScroll || hasJSONKey(raw, "scrollX") || hasJSONKey(raw, "scrollY")
r.HasText = r.HasText || hasJSONKey(raw, "text") || hasJSONKey(raw, "value")
if hasJSONKey(raw, "deltaX") {
+ r.HasDelta = true
if err := json.Unmarshal(raw["deltaX"], &r.DeltaX); err != nil {
return err
}
}
if hasJSONKey(raw, "deltaY") {
+ r.HasDelta = true
if err := json.Unmarshal(raw["deltaY"], &r.DeltaY); err != nil {
return err
}
diff --git a/internal/bridge/action_scroll_zero_test.go b/internal/bridge/action_scroll_zero_test.go
index 3d311dd9..43a91942 100644
--- a/internal/bridge/action_scroll_zero_test.go
+++ b/internal/bridge/action_scroll_zero_test.go
@@ -60,3 +60,42 @@ func TestScrollRefusesAnExplicitZeroDeltaButKeepsTheDefaultWhenAbsent(t *testing
t.Errorf("a bare scroll was refused as a zero delta: %v", err)
}
}
+
+// mouse-wheel is the sibling spelling of the same question, and it reaches further: the MCP
+// scroll tool routes to wheel semantics whenever deltaX/deltaY or a coordinate is given, so
+// an agent passing a computed deltaY of 0 lands here rather than on actionScroll. Scroll
+// refusing a zero while wheel silently scrolled a notch would be one rule with two answers.
+func TestWheelDeltaRefusesAnExplicitZeroInEitherSpelling(t *testing.T) {
+ for _, tc := range []struct {
+ body string
+ wantErr bool
+ wantX int
+ wantY int
+ whyNotOK string
+ }{
+ {body: `{"kind":"mouse-wheel"}`, wantY: 120, whyNotOK: "a bare wheel has always meant one notch down"},
+ {body: `{"kind":"mouse-wheel","deltaY":0}`, wantErr: true},
+ {body: `{"kind":"mouse-wheel","deltaX":0}`, wantErr: true},
+ {body: `{"kind":"mouse-wheel","deltaX":0,"deltaY":0}`, wantErr: true},
+ {body: `{"kind":"mouse-wheel","scrollY":0}`, wantErr: true, whyNotOK: "the legacy spelling asks the same question"},
+ {body: `{"kind":"mouse-wheel","deltaX":0,"deltaY":500}`, wantX: 0, wantY: 500, whyNotOK: "a zero on one axis is a real scroll on the other"},
+ {body: `{"kind":"mouse-wheel","deltaY":-300}`, wantY: -300},
+ {body: `{"kind":"mouse-wheel","deltaY":0,"scrollY":300}`, wantY: 300, whyNotOK: "an explicit zero delta still carries a non-zero legacy delta"},
+ } {
+ gotX, gotY, err := wheelDelta(decodeScrollRequest(t, tc.body))
+
+ if tc.wantErr {
+ if err == nil {
+ t.Errorf("%s: accepted, resolving to (%d,%d) — a zero delta scrolls a default notch nobody asked for", tc.body, gotX, gotY)
+ }
+ continue
+ }
+ if err != nil {
+ t.Errorf("%s: refused (%v); %s", tc.body, err, tc.whyNotOK)
+ continue
+ }
+ if gotX != tc.wantX || gotY != tc.wantY {
+ t.Errorf("%s: delta = (%d,%d), want (%d,%d); %s", tc.body, gotX, gotY, tc.wantX, tc.wantY, tc.whyNotOK)
+ }
+ }
+}