Mouse

Low-level pointer controls for drag handles, canvas-like UIs, hover-driven menus, and flows where DOM-native click or hover are not enough.

CLI

terminal 
pinchtab mouse move <x> <y>pinchtab mouse move <selector>pinchtab mouse down [selector] --button leftpinchtab mouse up [selector] --button leftpinchtab mouse wheel <dy> [--dx <n>]pinchtab mouse wheel [selector]pinchtab drag <from> <to>
pinchtab mouse move <x> <y>pinchtab mouse move <selector>pinchtab mouse down [selector] --button leftpinchtab mouse up [selector] --button leftpinchtab mouse wheel <dy> [--dx <n>]pinchtab mouse wheel [selector]pinchtab drag <from> <to>

Examples:

terminal 
# Move to an element, then use current-pointer semanticspinchtab mouse move e5pinchtab mouse down --button leftpinchtab mouse move 400 320pinchtab mouse up --button left# Explicitly target down/up at an elementpinchtab mouse down e5 --button leftpinchtab mouse up e5 --button left# Wheel at current pointerpinchtab mouse wheel 240 --dx 40# Wheel at a fresh targetpinchtab mouse wheel e5# Drag from an element to coordinatespinchtab drag e5 400,320
# Move to an element, then use current-pointer semanticspinchtab mouse move e5pinchtab mouse down --button leftpinchtab mouse move 400 320pinchtab mouse up --button left# Explicitly target down/up at an elementpinchtab mouse down e5 --button leftpinchtab mouse up e5 --button left# Wheel at current pointerpinchtab mouse wheel 240 --dx 40# Wheel at a fresh targetpinchtab mouse wheel e5# Drag from an element to coordinatespinchtab drag e5 400,320

Notes:

  • All mouse subcommands and drag accept --humanize to opt the action into the humanized bezier+jitter input path (overrides instanceDefaults.humanize).
  • mouse move accepts either coordinates or a unified selector.
  • mouse down and mouse up accept an optional selector. Without one, they use the current pointer position.
  • mouse wheel accepts either a delta form (<dy> [--dx <n>]) or an optional selector. Without a selector, it uses the current pointer position.
  • drag <from> <to> accepts selector/ref targets or x,y coordinate pairs.
  • button supports left, right, and middle.
  • Pointer move uses a bounded CDP mouseMoved dispatch first. If headless Chromium stalls that dispatch, PinchTab falls back to DOM mouse events so hover and mouse-move flows remain responsive.

HTTP API

Canonical action kinds:

  • mouse-move
  • mouse-down
  • mouse-up
  • mouse-wheel
  • drag

Targeting fields:

  • ref
  • selector
  • nodeId
  • x and y

Wheel fields:

  • deltaX
  • deltaY

Examples:

terminal 
# Move to an elementcurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","ref":"e5"}'# Move to coordinatescurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","x":120,"y":220}'# Press/release at current pointercurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-down","button":"left"}'curl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-up","button":"left"}'# Press/release at an explicit targetcurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-down","ref":"e5","button":"left"}'curl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-up","ref":"e5","button":"left"}'# Wheel at current pointercurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-wheel","deltaY":240,"deltaX":40}'# Wheel at explicit coordinatescurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-wheel","x":400,"y":320,"deltaY":240}'
# Move to an elementcurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","ref":"e5"}'# Move to coordinatescurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","x":120,"y":220}'# Press/release at current pointercurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-down","button":"left"}'curl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-up","button":"left"}'# Press/release at an explicit targetcurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-down","ref":"e5","button":"left"}'curl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-up","ref":"e5","button":"left"}'# Wheel at current pointercurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-wheel","deltaY":240,"deltaX":40}'# Wheel at explicit coordinatescurl -X POST http://localhost:9867/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-wheel","x":400,"y":320,"deltaY":240}'

Tab-scoped example:

terminal 
curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","ref":"e5"}'
curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"kind":"mouse-move","ref":"e5"}'

Behavior

  • POST coordinate bodies work with plain x and y; no extra hasXY flag is required.
  • mouse-down, mouse-up, and mouse-wheel use per-tab current-pointer state when you omit a fresh target.
  • If no current pointer position is known yet, mouse-down and mouse-up fail with a clear error. Use mouse-move first or pass an explicit target.
  • If no current pointer position is known yet, mouse-wheel and page scroll use the viewport center as a deterministic fallback.
  • mouse-wheel defaults to vertical scrolling when only deltaY is provided.
  • The CDP-to-DOM move fallback only handles renderer acknowledgement timeouts. Other CDP errors and caller cancellation are returned to the caller.

Rationale: low-level pointer actions are often used in hover menus, drag handles, and canvas-like controls where a five-second headless mouse-move stall makes a simple check look like a suite timeout. The fallback keeps these flows fast, while still surfacing real CDP errors.