Skip to content

Lightpanda: the headless browser designed for AI and automation

input: PointerButtons gesture struct, shared focus helper, trim comments

Adrià Arrufat4ecd38ece865
diff --git a/src/browser/Page.zig b/src/browser/Page.zig
index 7fdb18abd..60a764650 100644
--- a/src/browser/Page.zig
+++ b/src/browser/Page.zig
@@ -186,20 +186,9 @@ input_modifiers: if (lp.build_config.wpt_extensions) @import("frame/user_input.z
// The element the synthetic pointer is currently over
input_hover_target: ?*Element = null,
-// The aggregate mask of mouse buttons currently held down, tracked across
-// individual mousePressed/mouseReleased (CDP) or equivalent (BiDi) messages
-// so a chorded press (a second button pressed before the first is released)
-// can be told apart from the start of a new gesture.
-input_pressed_buttons: u16 = 0,
-
-// Whether the pointerdown that started the current gesture (the 0-to-nonzero
-// transition of input_pressed_buttons) suppressed the compatibility
-// mousedown/mouseup (preventDefault() was called). Set once at the start of
-// the gesture and held for its whole duration, including any chorded
-// button presses/releases in between — CDP's mousePressed/mouseReleased
-// arrive as independent Input.dispatchMouseEvent messages, so each half
-// reads this instead of carrying the state itself.
-input_mousedown_suppressed: bool = false,
+// Per-gesture button state for the synthetic mouse pointer; see
+// user_input.PointerButtons.
+input_pointer: @import("frame/user_input.zig").PointerButtons = .{},
// Popup Frames opened by window.open. They are top-level browsing contexts
// (parent == null, no iframe element) but share this Page's factory, arena,
diff --git a/src/browser/actions.zig b/src/browser/actions.zig
index 423b91a0c..722074cac 100644
--- a/src/browser/actions.zig
+++ b/src/browser/actions.zig
@@ -55,11 +55,7 @@ pub fn click(node: *DOMNode, frame: *Frame) !void {
lp.log.err(.app, "click press failed", .{ .err = err });
return error.ActionFailed;
};
- if (!press_result.suppress_mouse and !press_result.suppress_focus) {
- Frame.user_input.focusForMouseDown(frame, el) catch |err| {
- lp.log.warn(.app, "click mousedown focus", .{ .err = err });
- };
- }
+ try Frame.user_input.runMouseDownFocus(frame, el, press_result, "click mousedown focus");
Frame.user_input.dispatchPointerRelease(frame, el, 0, 0, main, press_result.suppress_mouse, 1, .{}) catch |err| {
lp.log.err(.app, "click release failed", .{ .err = err });
diff --git a/src/browser/frame/user_input.zig b/src/browser/frame/user_input.zig
index b2b66ad5c..3143b51f0 100644
--- a/src/browser/frame/user_input.zig
+++ b/src/browser/frame/user_input.zig
@@ -180,10 +180,7 @@ fn dispatchBoundaryEvent(frame: *Frame, target: *Element, comptime mouse_typ: []
};
}
-/// Dispatch a single trusted mouse event of the given type on `target`, carrying
-/// the pressed button and pointer position. `detail` is the click count (used for
-/// click/dblclick); 0 for events where it does not apply. Reports whether the
-/// event was cancelled via preventDefault().
+/// Dispatch a trusted mouse event; returns whether preventDefault() cancelled it.
fn dispatchMouseEventOn(frame: *Frame, target: *Element, comptime typ: []const u8, x: f64, y: f64, button: i32, buttons: u16, detail: u32, modifiers: Modifiers) !bool {
const event: *MouseEvent = try .initTrusted(comptime .wrap(typ), .{
.bubbles = true,
@@ -202,9 +199,8 @@ fn dispatchMouseEventOn(frame: *Frame, target: *Element, comptime typ: []const u
return frame._event_manager.dispatchCancelable(target.asEventTarget(), event.asEvent());
}
-/// Dispatch a single trusted pointer event of the given type on `target`.
-/// This engine only ever synthesizes mouse-sourced pointer input, so
-/// pointerType is always "mouse" and pointerId/isPrimary are fixed.
+/// Dispatch a trusted pointer event (always mouse-sourced: pointerType,
+/// pointerId, isPrimary fixed); returns whether preventDefault() cancelled it.
fn dispatchPointerEventOn(frame: *Frame, target: *Element, comptime typ: []const u8, x: f64, y: f64, button: i32, buttons: u16, detail: u32, modifiers: Modifiers) !bool {
const event: *PointerEvent = try .initTrusted(typ, .{
.bubbles = true,
@@ -240,26 +236,52 @@ pub fn buttonsBitmask(button: i32) u16 {
};
}
+/// Held-button mask and suppression flag for the single synthetic mouse
+/// pointer, tracked across the split press/release messages of one gesture so
+/// a chord is told apart from a new gesture.
+pub const PointerButtons = struct {
+ /// Mask of buttons currently held.
+ held: u16 = 0,
+ /// Whether the gesture's opening pointerdown suppressed the compat mouse
+ /// events; held for the whole gesture so each split message reads it here.
+ mousedown_suppressed: bool = false,
+
+ /// `starts_gesture` is false for a chorded press (another button held).
+ pub fn press(self: *PointerButtons, button: i32) struct { starts_gesture: bool, held: u16 } {
+ const bit = buttonsBitmask(button);
+ const starts_gesture = self.held & ~bit == 0;
+ self.held |= bit;
+ return .{ .starts_gesture = starts_gesture, .held = self.held };
+ }
+
+ /// `ends_gesture` is the last held button releasing, which clears the
+ /// suppression flag; `was_suppressed` is that flag for this gesture.
+ pub fn release(self: *PointerButtons, button: i32) struct { ends_gesture: bool, held: u16, was_suppressed: bool } {
+ const was_suppressed = self.mousedown_suppressed;
+ self.held &= ~buttonsBitmask(button);
+ const ends_gesture = self.held == 0;
+ if (ends_gesture) self.mousedown_suppressed = false;
+ return .{ .ends_gesture = ends_gesture, .held = self.held, .was_suppressed = was_suppressed };
+ }
+
+ /// Discards an in-progress gesture (a press/release that hit no element).
+ pub fn reset(self: *PointerButtons) void {
+ self.* = .{};
+ }
+};
+
pub const PressResult = struct {
- /// Whether pointerdown's preventDefault() suppressed the compatibility
- /// mousedown fired here, and (the caller should record this) the
- /// paired mouseup on release.
+ /// pointerdown's preventDefault() suppressed the compat mousedown here and
+ /// the paired mouseup on release.
suppress_mouse: bool,
- /// Whether mousedown's own preventDefault() suppressed just its focus
- /// default action. Only meaningful when `suppress_mouse` is false —
- /// mousedown itself never fires when it is true.
+ /// mousedown's preventDefault() suppressed its focus default action (only
+ /// meaningful when suppress_mouse is false).
suppress_focus: bool,
};
-/// The trusted press half of a click gesture, shared by `actions.click`,
-/// `WebDriver.click`, and the CDP `Input.dispatchMouseEvent` (`mousePressed`)
-/// path: pointerdown, then — unless its preventDefault() suppresses the
-/// compatibility mouse event — mousedown. `mouse_detail` is mousedown's
-/// click count (0 where the caller doesn't track one; pointerdown itself is
-/// always detail 0, per spec). Does not itself run the focus default
-/// action: `focusForMouseDown` can fail, and the three callers don't agree
-/// on what a failure there should mean for the click, so each runs it (or
-/// not) against `PressResult` with its own error handling.
+/// Press half: pointerdown, then mousedown unless preventDefault() suppressed
+/// it; doesn't run the focus default action (callers disagree on how a focus
+/// failure should affect the click).
pub fn dispatchPointerPress(frame: *Frame, target: *Element, x: f64, y: f64, button: i32, mouse_detail: u32, modifiers: Modifiers) !PressResult {
const buttons = buttonsBitmask(button);
const suppress_mouse = try dispatchPointerEventOn(frame, target, "pointerdown", x, y, button, buttons, 0, modifiers);
@@ -270,11 +292,19 @@ pub fn dispatchPointerPress(frame: *Frame, target: *Element, x: f64, y: f64, but
return .{ .suppress_mouse = suppress_mouse, .suppress_focus = suppress_focus };
}
-/// The release half of a click gesture: pointerup, then mouseup (carrying
-/// `mouse_detail`, its click count) unless the paired pointerdown suppressed
-/// it (`suppress_mouse`, from `dispatchPointerPress`). Click still fires
-/// even when suppressed — callers dispatch it separately via
-/// `dispatchClickAsPointer`.
+/// Runs mousedown's focus default action unless the gesture suppressed it;
+/// `warn_label` logs a focus failure and continues, null propagates it.
+pub fn runMouseDownFocus(frame: *Frame, target: *Element, press: PressResult, comptime warn_label: ?[]const u8) !void {
+ if (press.suppress_mouse or press.suppress_focus) return;
+ if (warn_label) |label| {
+ focusForMouseDown(frame, target) catch |err| log.warn(.app, label, .{ .err = err });
+ } else {
+ try focusForMouseDown(frame, target);
+ }
+}
+
+/// Release half: pointerup, then mouseup unless the paired pointerdown
+/// suppressed it (click fires separately via dispatchClickAsPointer).
pub fn dispatchPointerRelease(frame: *Frame, target: *Element, x: f64, y: f64, button: i32, suppress_mouse: bool, mouse_detail: u32, modifiers: Modifiers) !void {
_ = try dispatchPointerEventOn(frame, target, "pointerup", x, y, button, 0, 0, modifiers);
if (!suppress_mouse) {
@@ -282,20 +312,16 @@ pub fn dispatchPointerRelease(frame: *Frame, target: *Element, x: f64, y: f64, b
}
}
-/// The primary-button click, dispatched as a PointerEvent — matching how
-/// the engine dispatches HTMLElement.click() and keyboard-triggered clicks.
-/// `buttons` is the mask still held when the click fires (nonzero when the
-/// primary button releases mid-chord, i.e. another button is still down).
+/// Primary-button click as a PointerEvent (matching HTMLElement.click());
+/// `buttons` is the mask still held, nonzero on a mid-chord primary release.
pub fn dispatchClickAsPointer(frame: *Frame, target: *Element, x: f64, y: f64, detail: u32, buttons: u16, modifiers: Modifiers) !void {
_ = try dispatchPointerEventOn(frame, target, "click", x, y, mouse_button.main, buttons, detail, modifiers);
}
pub fn triggerMousePress(frame: *Frame, x: f64, y: f64, button: i32, click_count: i32) !void {
const target = (try frame.window._document.elementFromPoint(x, y, frame)) orelse {
- // No gesture started on this page; don't leave a prior gesture's
- // state to be misread by the next mousePressed/mouseReleased.
- frame._page.input_pressed_buttons = 0;
- frame._page.input_mousedown_suppressed = false;
+ // Don't leave a prior gesture's state for the next message to misread.
+ frame._page.input_pointer.reset();
return;
};
if (comptime lp.IS_DEBUG) {
@@ -309,44 +335,24 @@ pub fn triggerMousePress(frame: *Frame, x: f64, y: f64, button: i32, click_count
});
}
- const button_bit = buttonsBitmask(button);
- // Whether some *other* button was already down — the same button
- // pressed again without a release in between (some callers do this
- // deliberately to simulate two independent, unrelated presses) starts a
- // fresh gesture rather than continuing a chord.
- const other_already_held = frame._page.input_pressed_buttons & ~button_bit != 0;
- frame._page.input_pressed_buttons |= button_bit;
- // A caller that doesn't track click counts (or a CDP message that omits
- // clickCount) sends 0 — preserved as-is rather than forced to 1, since
- // Chrome and Firefox both fire mousedown with detail 0 in that case.
+ const gesture = frame._page.input_pointer.press(button);
+ // clickCount 0 (omitted) stays 0, not forced to 1: Chrome and Firefox
+ // both fire mousedown with detail 0 in that case.
const detail: u32 = if (click_count > 0) @intCast(click_count) else 0;
- if (!other_already_held) {
- // Starts the gesture: full pointerdown, then (unless cancelled)
- // mousedown (carrying click_count as its detail, matching Chrome and
- // Firefox) and its focus default action. mousePressed/mouseReleased
- // arrive as two independent CDP messages, so the release half can't
- // observe this gesture's pointerdown directly — stash the outcome
- // on the page first, before the fallible focus call, mirroring
- // input_hover_target.
+ if (gesture.starts_gesture) {
+ // Stash the pointerdown outcome before the fallible focus call: the
+ // release half is a separate message and can't observe it otherwise.
const press = try dispatchPointerPress(frame, target, x, y, button, detail, .{});
- frame._page.input_mousedown_suppressed = press.suppress_mouse;
- if (!press.suppress_mouse and !press.suppress_focus) {
- try focusForMouseDown(frame, target);
- }
+ frame._page.input_pointer.mousedown_suppressed = press.suppress_mouse;
+ try runMouseDownFocus(frame, target, press, null);
} else {
- // A chorded press: another button going down while one is already
- // held is a buttons-mask change on the same pointer, not a second
- // pointerdown — https://www.w3.org/TR/pointerevents3/#chorded-button-interactions.
- // The compatibility mousedown for this button still fires unless
- // the gesture's own pointerdown was already cancelled.
- const buttons = frame._page.input_pressed_buttons;
- _ = try dispatchPointerEventOn(frame, target, "pointermove", x, y, button, buttons, 0, .{});
- if (!frame._page.input_mousedown_suppressed) {
- const suppress_focus = try dispatchMouseEventOn(frame, target, "mousedown", x, y, button, buttons, detail, .{});
- if (!suppress_focus) {
- try focusForMouseDown(frame, target);
- }
+ // A chorded press is a buttons-mask change (pointermove), not a second
+ // pointerdown: https://www.w3.org/TR/pointerevents3/#chorded-button-interactions
+ _ = try dispatchPointerEventOn(frame, target, "pointermove", x, y, button, gesture.held, 0, .{});
+ if (!frame._page.input_pointer.mousedown_suppressed) {
+ const suppress_focus = try dispatchMouseEventOn(frame, target, "mousedown", x, y, button, gesture.held, detail, .{});
+ try runMouseDownFocus(frame, target, .{ .suppress_mouse = false, .suppress_focus = suppress_focus }, null);
}
}
}
@@ -376,16 +382,12 @@ pub fn triggerMouseMove(frame: *Frame, x: f64, y: f64) !void {
}
pub fn triggerMouseRelease(frame: *Frame, x: f64, y: f64, button: i32, click_count: i32) !void {
- // Consumed unconditionally, before any early return below, so a
- // mouseReleased that misses every element (or a later error) can never
- // leave this gesture's state to be misread by the next one.
- const was_suppressed = frame._page.input_mousedown_suppressed;
- const remaining = frame._page.input_pressed_buttons & ~buttonsBitmask(button);
- frame._page.input_pressed_buttons = remaining;
- const ends_gesture = remaining == 0;
- if (ends_gesture) {
- frame._page.input_mousedown_suppressed = false;
- }
+ // Consume the state before any early return, so a release that misses
+ // every element can't leave it for the next message to misread.
+ const gesture = frame._page.input_pointer.release(button);
+ const remaining = gesture.held;
+ const ends_gesture = gesture.ends_gesture;
+ const was_suppressed = gesture.was_suppressed;
const target = (try frame.window._document.elementFromPoint(x, y, frame)) orelse return;
if (comptime lp.IS_DEBUG) {
@@ -404,8 +406,8 @@ pub fn triggerMouseRelease(frame: *Frame, x: f64, y: f64, button: i32, click_cou
if (ends_gesture) {
try dispatchPointerRelease(frame, target, x, y, button, was_suppressed, detail, .{});
} else {
- // A chorded release: another button remains held, so this is a
- // buttons-mask change on the same pointer, not pointerup.
+ // A chorded release (another button still held) is a buttons-mask
+ // change, not pointerup.
_ = try dispatchPointerEventOn(frame, target, "pointermove", x, y, button, remaining, 0, .{});
if (!was_suppressed) {
_ = try dispatchMouseEventOn(frame, target, "mouseup", x, y, button, remaining, detail, .{});
diff --git a/src/browser/webapi/WebDriver.zig b/src/browser/webapi/WebDriver.zig
index 8ec782653..d318bc2e1 100644
--- a/src/browser/webapi/WebDriver.zig
+++ b/src/browser/webapi/WebDriver.zig
@@ -75,11 +75,7 @@ pub fn click(_: *const WebDriver, element: *Element, frame: *Frame) !void {
log.warn(.app, "webdriver click press", .{ .err = err });
return;
};
- if (!press.suppress_mouse and !press.suppress_focus) {
- Frame.user_input.focusForMouseDown(frame, element) catch |err| {
- log.warn(.app, "webdriver click focus", .{ .err = err });
- };
- }
+ try Frame.user_input.runMouseDownFocus(frame, element, press, "webdriver click focus");
Frame.user_input.dispatchPointerRelease(frame, element, 0, 0, main, press.suppress_mouse, 1, modifiers) catch |err| {
log.warn(.app, "webdriver click release", .{ .err = err });
return;
@@ -346,8 +342,6 @@ fn performPointerSource(source: js.Object, frame: *Frame) !void {
}
}
-// The `buttons` bitmask bit for a WebDriver button number: the flag order does
-// not follow the button numbering (left=1, right=2, middle=4).
// A click whose mousedown and mouseup landed on different elements fires at
// their nearest common inclusive ancestor element.
fn commonClickTarget(down: *Element, up: *Element) *Element {
diff --git a/src/server/cdp/domains/input.zig b/src/server/cdp/domains/input.zig
index 7503ae69e..8fd444b41 100644
--- a/src/server/cdp/domains/input.zig
+++ b/src/server/cdp/domains/input.zig
@@ -596,10 +596,8 @@ test "cdp.input: dispatchMouseEvent right button fires contextmenu, double-click
try testing.expect(result.isTrue());
}
-// A CDP mousePressed/mouseReleased pair fires the full pointerdown/mousedown/
-// pointerup/mouseup/click sequence, matching actions.click's five-event
-// sequence (asserted in the MCP click test) — mousedown carries the press
-// message's own clickCount as its detail, matching Chrome and Firefox.
+// A CDP press/release pair fires the full pointer/mouse sequence, with
+// mousedown carrying the message's clickCount as its detail (matches Chrome).
test "cdp.input: dispatchMouseEvent mousePressed/mouseReleased fires the full pointer/mouse sequence" {
var ctx = try testing.context();
defer ctx.deinit();
@@ -643,10 +641,8 @@ test "cdp.input: dispatchMouseEvent mousePressed/mouseReleased fires the full po
try testing.expect(result.isTrue());
}
-// clickCount 0 (the struct default, same as omitting the field entirely) is
-// preserved as mousedown's detail rather than forced to 1 — Chrome and
-// Firefox both fire detail 0 for an omitted/zero clickCount, distinct from
-// the detail-1 case a plain single click sends.
+// clickCount 0 (omitted) is preserved as mousedown's detail, not forced to 1:
+// Chrome and Firefox both fire detail 0 there, distinct from a detail-1 click.
test "cdp.input: dispatchMouseEvent mousePressed's mousedown detail matches the message's clickCount" {
const cases = .{
.{ .click_count = 0, .expect_detail = 0 },
@@ -692,9 +688,8 @@ test "cdp.input: dispatchMouseEvent mousePressed's mousedown detail matches the
}
}
-// Independent check that clickCount is not press-only: a clickCount-2
-// press+release pair must carry detail 2 on mousedown, mouseup, and click,
-// and still fire dblclick from the release half.
+// clickCount reaches the release half too: a clickCount-2 pair carries
+// detail 2 on mousedown/mouseup/click and fires dblclick.
test "cdp.input: clickCount 2 on press and release puts detail 2 on mousedown, mouseup, click and fires dblclick" {
var ctx = try testing.context();
defer ctx.deinit();
@@ -743,8 +738,7 @@ test "cdp.input: clickCount 2 on press and release puts detail 2 on mousedown, m
try testing.expect(result.isTrue());
}
-// The chorded-press branch has its own mousedown dispatch; clickCount must
-// reach it too, not only the first-button dispatchPointerPress path.
+// clickCount must reach the chorded-press mousedown, not only the first press.
test "cdp.input: a chorded mousedown carries the press message's clickCount as its detail" {
var ctx = try testing.context();
defer ctx.deinit();
@@ -788,9 +782,8 @@ test "cdp.input: a chorded mousedown carries the press message's clickCount as i
try testing.expect(result.isTrue());
}
-// mousePressed and mouseReleased are two independent CDP messages, so a
-// pointerdown cancelled on the press half must still suppress mouseup on the
-// release half, with no state carried by the caller between the two calls.
+// A pointerdown cancelled on the press message must still suppress mouseup on
+// the separate release message, with no state carried by the caller.
test "cdp.input: a cancelled pointerdown suppresses mousedown and mouseup across the split mousePressed/mouseReleased calls" {
var ctx = try testing.context();
defer ctx.deinit();
@@ -831,17 +824,9 @@ test "cdp.input: a cancelled pointerdown suppresses mousedown and mouseup across
try testing.expect(result.isTrue());
}
-// A second button pressed while the first is still held is a chord on one
-// pointer, not two independent gestures: the aggregate buttons mask changes
-// (as pointermove), but pointerdown/pointerup fire only at the 0/nonzero
-// transitions, and a cancelled pointerdown's mouse-event suppression holds
-// for the whole gesture — https://www.w3.org/TR/pointerevents3/#chorded-button-interactions.
-// This asserts only the pointer events this PR owns. The pointer/mouse
-// events pin the same chord in real Chrome exactly; the *activation* order
-// below (contextmenu on release rather than on the right press, and a
-// trailing left click instead of auxclick) is a pre-existing, known
-// deviation from Chrome's chorded release switch, not something this test
-// claims is spec-correct.
+// Asserts only the pointer events: pointerdown/pointerup fire at the mask's
+// 0/nonzero transitions and a mid-gesture button change is a pointermove (the
+// activation order below is a pre-existing, non-spec deviation from Chrome).
test "cdp.input: a mouse chord fires pointermove for the mid-gesture button change, not a second pointerdown/pointerup" {
var ctx = try testing.context();
defer ctx.deinit();
@@ -894,12 +879,8 @@ test "cdp.input: a mouse chord fires pointermove for the mid-gesture button chan
try testing.expect(result.isTrue());
}
-// A primary-button release mid-chord (another button still held) reports
-// that held mask on its click, not 0 — the click is a PointerEvent and
-// PointerEvent.buttons reflects buttons still down after this one lifts.
-// Confirmed against real Chrome and Firefox: both report the held button on
-// this click too (and, like this PR, fire it as a genuine `click`, not
-// folding it into `auxclick`/`contextmenu`).
+// A primary release mid-chord reports the still-held mask on its click, not 0
+// (confirmed against Chrome and Firefox).
test "cdp.input: a primary click fired mid-chord carries the still-held buttons mask" {
var ctx = try testing.context();
defer ctx.deinit();