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.goindex 739ae569..fba8a510 100644--- a/cmd/pinchtab/cmd_cli_browser_actions.go+++ b/cmd/pinchtab/cmd_cli_browser_actions.go@@ -1,6 +1,9 @@package mainimport (+ "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 -3002. 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.goindex 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.gonew file mode 100644index 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.mdindex 4b5064ce..760555b4 100644--- a/docs/reference/scroll.md+++ b/docs/reference/scroll.md@@ -15,10 +15,19 @@ pinchtab scroll downpinchtab scroll down --snap # scroll and output snapshotpinchtab scroll 800 --snap-diff # scroll and output snapshot diffpinchtab 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.goindex 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.goindex 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.mdindex ef56139a..58b9de40 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -137,11 +137,12 @@ pinchtab drag e5 400,320Use 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 `--`.```bashpinchtab 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 120pxpinchtab scroll down # named direction (also up, top, bottom)pinchtab scroll '#footer' # scroll a CSS selector into viewpinchtab scroll e20 # scroll an element ref into view