Skip to content

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

fix: scroll -300 is documented twice and never works, and the only workaround silently scrolls the wrong tab (PIN-136)

Luigi Agosti5146c76e649a
diff --git a/cmd/pinchtab/cmd_cli_browser_actions.go b/cmd/pinchtab/cmd_cli_browser_actions.go
index 739ae569..fba8a510 100644
--- a/cmd/pinchtab/cmd_cli_browser_actions.go
+++ b/cmd/pinchtab/cmd_cli_browser_actions.go
@@ -1,6 +1,9 @@
package main
import (
+ "fmt"
+ "strings"
+
"github.com/pinchtab/pinchtab/internal/bridge"
browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
"github.com/spf13/cobra"
@@ -115,11 +118,13 @@ var focusCmd = newOptionalRefActionCmd("focus <ref>", "Focus element", "focus")
var scrollCmd = &cobra.Command{
Use: "scroll <pixels|direction|selector>",
Short: "Scroll the page by pixels, in a direction, or to an element",
- Long: `Scroll the page. The single positional argument is interpreted by precedence:
+ Long: `Scroll the page. Give either --dy/--dx or one positional argument.
- 1. Integer → scrollY in pixels (positive down, negative up).
- pinchtab scroll 800
- pinchtab scroll -300
+ 1. Pixels: --dy <n> vertically, --dx <n> horizontally (positive down/right).
+ A negative count needs the flag — cobra reads a leading minus on a
+ positional as a bundle of shorthand flags, so "scroll -300" cannot parse.
+ pinchtab scroll --dy 800
+ pinchtab scroll --dy -300
2. Direction keyword: up | down | left | right (defaults to 800px per step).
pinchtab scroll down
@@ -132,9 +137,11 @@ var scrollCmd = &cobra.Command{
pinchtab scroll '//footer'
pinchtab scroll 'text:Load more'
+A positional integer still works for a positive count (pinchtab scroll 800).
+
Precedence: integer and direction keywords win over selector parsing so that
'up'/'down' are treated as directions, not as CSS tag selectors.`,
- Args: cobra.MinimumNArgs(1),
+ Args: scrollArgs,
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.ActionSimple(rt.client, rt.base, rt.token, "scroll", args, cmd)
@@ -142,6 +149,26 @@ Precedence: integer and direction keywords win over selector parsing so that
},
}
+// scrollArgs refuses a second positional, which is what made a mistyped scroll
+// silently scroll the WRONG tab: the only spelling of a negative count used to be
+// `scroll -- -300`, everything after `--` is a positional, and MinimumNArgs(1)
+// accepted `--tab <id>` as args[1:] and dropped it — so the action ran on the
+// current tab and reported OK. It also refuses the empty and the doubly-specified
+// forms, since --dy/--dx and the positional are two spellings of one argument.
+func scrollArgs(cmd *cobra.Command, args []string) error {
+ byFlag := cmd.Flags().Changed("dy") || cmd.Flags().Changed("dx")
+ if len(args) > 1 {
+ return fmt.Errorf("accepts at most 1 positional argument, received %d (%s); a negative count is --dy <n>, and flags must not follow --", len(args), strings.Join(args, " "))
+ }
+ if len(args) == 0 && !byFlag {
+ return fmt.Errorf("needs a positional <pixels|direction|selector> or --dy/--dx")
+ }
+ if len(args) == 1 && byFlag {
+ return fmt.Errorf("give either %q or --dy/--dx, not both", args[0])
+ }
+ return nil
+}
+
var selectCmd = newSimpleActionCmd("select <ref> <value>", "Select option in dropdown", "select", cobra.MinimumNArgs(2))
var checkCmd = newRequiredRefActionCmd("check <selector>", "Check a checkbox or radio", "check")
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index ea912ed0..3fb20f6c 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -94,6 +94,9 @@ func configureBrowserFlags() {
mouseWheelCmd.Flags().Int("dx", 0, "Wheel delta X")
mouseWheelCmd.Flags().Int("dy", 0, "Wheel delta Y")
+ scrollCmd.Flags().Int("dy", 0, "Vertical scroll in pixels (negative scrolls up)")
+ scrollCmd.Flags().Int("dx", 0, "Horizontal scroll in pixels (negative scrolls left)")
+
dragCmd.Flags().String("button", "left", "Mouse button: left, right, middle")
dragCmd.Flags().Int("drag-x", 0, "Horizontal pixel offset for single-step drag action")
dragCmd.Flags().Int("drag-y", 0, "Vertical pixel offset for single-step drag action")
diff --git a/cmd/pinchtab/cmd_cli_scroll_test.go b/cmd/pinchtab/cmd_cli_scroll_test.go
new file mode 100644
index 00000000..39b25b75
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_scroll_test.go
@@ -0,0 +1,149 @@
+package main
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func resetScrollFlags(t *testing.T) {
+ t.Helper()
+ t.Cleanup(func() {
+ for _, name := range []string{"dy", "dx"} {
+ flag := scrollCmd.Flags().Lookup(name)
+ if flag == nil {
+ continue
+ }
+ _ = flag.Value.Set("0")
+ flag.Changed = false
+ }
+ })
+}
+
+// A second positional used to be accepted and dropped, which is how a scroll ran on the
+// WRONG tab and still reported OK: `scroll -- -300 --tab <id>` put --tab and its value in
+// args[1:], and MinimumNArgs(1) was happy. Refusing the count is the whole guard — it needs
+// no special case for --tab.
+func TestScrollRefusesArgumentsItCannotHonour(t *testing.T) {
+ resetScrollFlags(t)
+
+ for _, tc := range []struct {
+ name string
+ args []string
+ flags map[string]string
+ wantErr string
+ }{
+ {
+ name: "the swallowed tab",
+ args: []string{"-300", "--tab", "zzz-not-a-tab"},
+ wantErr: "at most 1 positional",
+ },
+ {
+ name: "any stray second positional",
+ args: []string{"800", "junk"},
+ wantErr: "at most 1 positional",
+ },
+ {
+ name: "nothing to scroll by",
+ args: nil,
+ wantErr: "--dy",
+ },
+ {
+ name: "two spellings of one argument",
+ args: []string{"800"},
+ flags: map[string]string{"dy": "-300"},
+ wantErr: "not both",
+ },
+ {
+ name: "a positional alone",
+ args: []string{"800"},
+ flags: nil,
+ },
+ {
+ name: "a selector alone",
+ args: []string{"e12"},
+ flags: nil,
+ },
+ {
+ name: "the pixel flag alone",
+ args: nil,
+ flags: map[string]string{"dy": "-300"},
+ },
+ {
+ name: "the horizontal flag alone",
+ args: nil,
+ flags: map[string]string{"dx": "-120"},
+ },
+ } {
+ for name, value := range tc.flags {
+ if err := scrollCmd.Flags().Set(name, value); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ err := scrollCmd.Args(scrollCmd, tc.args)
+
+ switch {
+ case tc.wantErr == "" && err != nil:
+ t.Errorf("%s: scroll %v rejected with %v, want accepted", tc.name, tc.args, err)
+ case tc.wantErr != "" && err == nil:
+ t.Errorf("%s: scroll %v was accepted; anything it cannot honour must be refused rather than dropped", tc.name, tc.args)
+ case tc.wantErr != "" && !strings.Contains(err.Error(), tc.wantErr):
+ t.Errorf("%s: error = %v, want it to mention %q", tc.name, err, tc.wantErr)
+ }
+
+ for name := range tc.flags {
+ flag := scrollCmd.Flags().Lookup(name)
+ _ = flag.Value.Set("0")
+ flag.Changed = false
+ }
+ }
+}
+
+// The negative count is only reachable through a flag, so the flags have to exist: a help
+// text promising --dy over a command that never registered it is the same defect one layer up.
+func TestScrollRegistersThePixelFlags(t *testing.T) {
+ for _, name := range []string{"dy", "dx"} {
+ flag := scrollCmd.Flags().Lookup(name)
+ if flag == nil {
+ t.Fatalf("scroll has no --%s, so a negative pixel count has no spelling that parses", name)
+ }
+ if flag.Value.Type() != "int" {
+ t.Errorf("--%s is %s, want int: a signed count must be accepted as a flag VALUE", name, flag.Value.Type())
+ }
+ }
+}
+
+// scroll -300 was an example in this help and in the agent-facing reference, and it never
+// parsed — cobra reads the leading minus as shorthand flags. Both sites are checked here
+// because a doc that teaches an unparseable command is how this reached a user.
+func TestNoDocumentedScrollExampleUsesABareNegativePositional(t *testing.T) {
+ docs := map[string]string{"scroll --help": scrollCmd.Long}
+
+ for _, path := range []string{
+ filepath.Join("..", "..", "skills", "pinchtab", "references", "commands.md"),
+ filepath.Join("..", "..", "docs", "reference", "scroll.md"),
+ } {
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("cannot read %s, so this guard would not cover the doc site it names: %v", path, err)
+ }
+ docs[filepath.ToSlash(path)] = string(raw)
+ }
+
+ for site, text := range docs {
+ for _, line := range strings.Split(text, "\n") {
+ fields := strings.Fields(line)
+ for i, field := range fields {
+ if field != "scroll" || i+1 >= len(fields) {
+ continue
+ }
+ next := fields[i+1]
+ if len(next) > 1 && next[0] == '-' && next[1] >= '0' && next[1] <= '9' {
+ t.Errorf("%s teaches %q, which cobra reads as shorthand flags and refuses; a negative count is --dy <n>", site, strings.TrimSpace(line))
+ }
+ }
+ }
+ }
+}
diff --git a/docs/reference/scroll.md b/docs/reference/scroll.md
index 4b5064ce..760555b4 100644
--- a/docs/reference/scroll.md
+++ b/docs/reference/scroll.md
@@ -15,10 +15,19 @@ pinchtab scroll down
pinchtab scroll down --snap # scroll and output snapshot
pinchtab scroll 800 --snap-diff # scroll and output snapshot diff
pinchtab scroll 800 --json # Full JSON response
+
+pinchtab scroll --dy -300 # scroll up 300px
+pinchtab scroll --dx -120 # scroll left 120px
```
Notes:
+- a negative pixel count uses `--dy` / `--dx`: a leading minus on a positional argument is
+ read as a bundle of shorthand flags and refused before the command runs
+- give either the flags or one positional, never both, and only one positional is accepted —
+ so `--tab` stays a flag and must not be placed after `--`, where it would be read as a
+ positional
+
- use `--snap` to output an interactive snapshot after scrolling
- use `--snap-diff` to output only the changes from the previous snapshot
- the top-level CLI also accepts a pixel value such as `pinchtab scroll 800`
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index 3ff6c6b3..f3f360df 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -209,6 +209,46 @@ func setPointBody(body map[string]any, x, y float64) {
body["y"] = y
}
+// applyScrollTarget fills a scroll body from --dy/--dx, or from the single positional by
+// precedence: integer pixels, then direction keyword, then unified selector. Pixels and
+// directions are short, low-cardinality inputs that would otherwise parse as CSS tag
+// selectors ("up", "down"), so they are intercepted before setSelectorBody.
+//
+// The flags are how a NEGATIVE count is reachable at all: cobra reads a leading minus on a
+// positional as shorthand flags, so `scroll -300` — an example in this command's own help —
+// never parsed, and `scroll -- -300` was the only workaround. scrollArgs in cmd/pinchtab
+// rejects the combinations this cannot express, so an empty args slice here means the flags
+// carry the request.
+func applyScrollTarget(body map[string]any, args []string, cmd *cobra.Command) {
+ if deltaY, ok := readWheelDelta(cmd, "dy"); ok {
+ body["scrollY"] = deltaY
+ }
+ if deltaX, ok := readWheelDelta(cmd, "dx"); ok {
+ body["scrollX"] = deltaX
+ }
+ if len(args) == 0 {
+ return
+ }
+ if px, err := strconv.Atoi(args[0]); err == nil {
+ body["scrollY"] = px
+ return
+ }
+ switch strings.ToLower(args[0]) {
+ case "down":
+ body["scrollY"] = 800
+ case "up":
+ body["scrollY"] = -800
+ case "right":
+ body["scrollX"] = 800
+ case "left":
+ body["scrollX"] = -800
+ default:
+ // Refs ("e5"), CSS ("#footer"), XPath ("//..."), text: and semantic selectors all
+ // work here — the same contract as click, fill and hover.
+ setSelectorBody(body, args[0])
+ }
+}
+
func readWheelDelta(cmd *cobra.Command, primary string) (int, bool) {
if cmd.Flags().Changed(primary) {
if value, err := cmd.Flags().GetInt(primary); err == nil {
@@ -420,30 +460,7 @@ func ActionSimple(client *http.Client, base, token, kind string, args []string,
body["key"] = args[0]
}
case "scroll":
- // Precedence: integer pixels > direction keyword > unified selector.
- // Pixels and directions are short, low-cardinality inputs that would
- // otherwise also parse as CSS tag selectors (e.g. "up" / "down"), so
- // we intercept them before handing off to setSelectorBody.
- if px, err := strconv.Atoi(args[0]); err == nil {
- body["scrollY"] = px
- break
- }
- switch strings.ToLower(args[0]) {
- case "down":
- body["scrollY"] = 800
- case "up":
- body["scrollY"] = -800
- case "right":
- body["scrollX"] = 800
- case "left":
- body["scrollX"] = -800
- default:
- // Fall back to the unified selector parser so refs ("e5"),
- // CSS ("#footer", ".class"), XPath ("//..."), text: and
- // semantic selectors all work — same contract as `click`,
- // `fill`, `hover`, etc. Server supports these via req.Selector.
- setSelectorBody(body, args[0])
- }
+ applyScrollTarget(body, args, cmd)
case "select":
setSelectorBody(body, args[0])
body["value"] = args[1]
diff --git a/internal/cli/actions/actions_element_test.go b/internal/cli/actions/actions_element_test.go
index a92ca69d..1d63d75f 100644
--- a/internal/cli/actions/actions_element_test.go
+++ b/internal/cli/actions/actions_element_test.go
@@ -826,3 +826,76 @@ func TestKeyboardTypeWithTab(t *testing.T) {
t.Errorf("expected /tabs/tab42/action, got %s", m.lastPath)
}
}
+
+// newScrollCmd carries the flags cmd/pinchtab registers on `scroll`, so a body built here is
+// built from the same inputs production reads.
+func newScrollCmd() *cobra.Command {
+ cmd := newSimpleCmd()
+ cmd.Flags().Int("dy", 0, "")
+ cmd.Flags().Int("dx", 0, "")
+ return cmd
+}
+
+// Scrolling up by an exact pixel count is what had no working spelling: a positional "-300"
+// cannot reach the command (cobra reads it as shorthand flags), and `-- -300` swallowed
+// --tab. The flag is the reachable route, and negatives are fine as flag VALUES.
+func TestScrollByPixelFlags(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ flags map[string]string
+ want map[string]float64
+ }{
+ {name: "up", flags: map[string]string{"dy": "-300"}, want: map[string]float64{"scrollY": -300}},
+ {name: "down", flags: map[string]string{"dy": "800"}, want: map[string]float64{"scrollY": 800}},
+ {name: "left", flags: map[string]string{"dx": "-120"}, want: map[string]float64{"scrollX": -120}},
+ {name: "both axes", flags: map[string]string{"dy": "-300", "dx": "40"}, want: map[string]float64{"scrollY": -300, "scrollX": 40}},
+ } {
+ m := newMockServer()
+ cmd := newScrollCmd()
+ for flag, value := range tc.flags {
+ if err := cmd.Flags().Set(flag, value); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ ActionSimple(m.server.Client(), m.base(), "", "scroll", nil, cmd)
+
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ for key, want := range tc.want {
+ if body[key] != want {
+ t.Errorf("%s: %s = %v, want %v (body %+v)", tc.name, key, body[key], want, body)
+ }
+ }
+ m.close()
+ }
+}
+
+// The positional forms are what everything else in the docs teaches, and adding the flags
+// touched the same precedence path that resolves them.
+func TestScrollPositionalFormsAreUnchangedByThePixelFlags(t *testing.T) {
+ for _, tc := range []struct {
+ arg string
+ key string
+ want any
+ }{
+ {arg: "800", key: "scrollY", want: float64(800)},
+ {arg: "down", key: "scrollY", want: float64(800)},
+ {arg: "up", key: "scrollY", want: float64(-800)},
+ {arg: "right", key: "scrollX", want: float64(800)},
+ {arg: "left", key: "scrollX", want: float64(-800)},
+ {arg: "e12", key: "ref", want: "e12"},
+ {arg: "#footer", key: "selector", want: "#footer"},
+ {arg: "text:Load more", key: "selector", want: "text:Load more"},
+ } {
+ m := newMockServer()
+ ActionSimple(m.server.Client(), m.base(), "", "scroll", []string{tc.arg}, newScrollCmd())
+
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if body[tc.key] != tc.want {
+ t.Errorf("scroll %q: %s = %v, want %v (body %+v)", tc.arg, tc.key, body[tc.key], tc.want, body)
+ }
+ m.close()
+ }
+}
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index ef56139a..58b9de40 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -137,11 +137,12 @@ pinchtab drag e5 400,320
Use these for drag handles, canvas controls, precise hover choreography, or sites that require exact pointer sequencing.
### `pinchtab scroll <pixels|direction|selector>`
-Scroll the page or a specific element. Argument is positional — there is no `--pixels` flag.
+Scroll the page or a specific element. Give either `--dy`/`--dx` or one positional argument, never both. A negative pixel count must use the flag: a leading minus on a positional is read as a bundle of shorthand flags and refused. Only one positional is accepted, so `--tab` must be a flag, never placed after `--`.
```bash
pinchtab scroll 800 # scroll page down 800px
-pinchtab scroll -300 # scroll page up 300px
+pinchtab scroll --dy -300 # scroll page up 300px
+pinchtab scroll --dx -120 # scroll page left 120px
pinchtab scroll down # named direction (also up, top, bottom)
pinchtab scroll '#footer' # scroll a CSS selector into view
pinchtab scroll e20 # scroll an element ref into view