Skip to content

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

decision: 'scroll down' moves 800px on the CLI and 120px via MCP, and the MCP tool documents no magnitude, so an agent silently gets a sixth of the distance (PIN-233)

Luigi Agosti9788bebb461d
diff --git a/cmd/pinchtab/cmd_cli_scroll_test.go b/cmd/pinchtab/cmd_cli_scroll_test.go
index cf8639a1..585776c0 100644
--- a/cmd/pinchtab/cmd_cli_scroll_test.go
+++ b/cmd/pinchtab/cmd_cli_scroll_test.go
@@ -7,7 +7,7 @@ import (
"strings"
"testing"
- browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+ "github.com/pinchtab/pinchtab/internal/scroll"
)
func resetScrollFlags(t *testing.T) {
@@ -179,7 +179,7 @@ func directionsEnumeratedAfter(text, marker string) ([]string, bool) {
// and "right", which work. A guard pinning one known-bad example would not have caught
// either half — only comparing the whole set does.
func TestDocumentedScrollDirectionsAreExactlyTheSupportedOnes(t *testing.T) {
- want := browseractions.ScrollDirectionKeywords()
+ want := scroll.DirectionKeywords()
commands, err := os.ReadFile(filepath.Join("..", "..", "skills", "pinchtab", "references", "commands.md"))
if err != nil {
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index 733f8831..bc1272f4 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -44,7 +44,7 @@ All element-action tools accept the unified `selector` and the legacy aliases `r
| `pinchtab_hover` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId` | Hover an element or coordinate |
| `pinchtab_focus` | `selector`, `ref`, `query`, `tabId`, `nodeId` | Focus element |
| `pinchtab_select` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text; target with `selector` or `nodeId` |
-| `pinchtab_scroll` | `selector`, `ref`, `query`, `nodeId`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit every target to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |
+| `pinchtab_scroll` | `selector`, `ref`, `query`, `nodeId`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit every target to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `down`/`left`/`right`/`up` and moves 800px per step — the same distance as the CLI's `pinchtab scroll <direction>`, multiplied by `steps` or overridden by `pixels` |
| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `nodeId`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions; target with `selector` or `nodeId` |
| `pinchtab_fill` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes; target with `selector` or `nodeId`. An empty `value` clears the field; omitting it entirely is refused |
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index 3ae3228d..27e85fe4 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -3,7 +3,6 @@ package actions
import (
"encoding/json"
"net/http"
- "sort"
"strconv"
"strings"
@@ -11,6 +10,7 @@ import (
"github.com/pinchtab/pinchtab/internal/cli"
"github.com/pinchtab/pinchtab/internal/cli/apiclient"
"github.com/pinchtab/pinchtab/internal/cli/output"
+ "github.com/pinchtab/pinchtab/internal/scroll"
"github.com/pinchtab/pinchtab/internal/selector"
"github.com/spf13/cobra"
)
@@ -210,31 +210,6 @@ func setPointBody(body map[string]any, x, y float64) {
body["y"] = y
}
-type scrollDirection struct {
- axis string
- delta int
-}
-
-// scrollDirections is the whole vocabulary `scroll <direction>` accepts, and the single
-// place the help and the docs are checked against by ScrollDirectionKeywords.
-var scrollDirections = map[string]scrollDirection{
- "down": {"scrollY", 800},
- "up": {"scrollY", -800},
- "right": {"scrollX", 800},
- "left": {"scrollX", -800},
-}
-
-// ScrollDirectionKeywords returns the accepted direction keywords, sorted. Any prose that
-// enumerates them is asserted against this rather than against a hand-kept list.
-func ScrollDirectionKeywords() []string {
- keywords := make([]string, 0, len(scrollDirections))
- for keyword := range scrollDirections {
- keywords = append(keywords, keyword)
- }
- sort.Strings(keywords)
- return keywords
-}
-
// applyScrollTarget fills a scroll body from the single positional — integer pixels, then
// direction keyword, then unified selector — or from --dy/--dx when there is no positional.
// Pixels and directions would otherwise parse as CSS tag selectors ("up", "down"), so they
@@ -262,8 +237,8 @@ func applyScrollTarget(body map[string]any, args []string, cmd *cobra.Command) {
body["scrollY"] = px
return
}
- if direction, ok := scrollDirections[strings.ToLower(args[0])]; ok {
- body[direction.axis] = direction.delta
+ if direction, ok := scroll.DirectionFor(strings.ToLower(args[0])); ok {
+ body[direction.Axis] = direction.Delta
return
}
setSelectorBody(body, args[0])
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 3f0dba07..24a3acf7 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -7,6 +7,7 @@ import (
"strings"
"github.com/mark3labs/mcp-go/mcp"
+ "github.com/pinchtab/pinchtab/internal/scroll"
)
// humanizeAction is the set of pointer actions that accept a per-request humanize
@@ -144,24 +145,30 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
steps = 1
}
- if direction != "" && !hasDeltaY {
- magnitude := 120
+ // A direction keyword is an INTENT, so it reads its vocabulary and its
+ // magnitude from the one owner both surfaces share and routes to the same
+ // `scroll` action the CLI's keyword does. It used to carry its own switch
+ // (down and up only, no horizontal) and its own bare 120 — a wheel notch,
+ // which is a device unit: "down" moved a sixth of what the CLI moved, took
+ // six round trips to bring the next content into view, and said so nowhere.
+ if direction != "" && !hasDeltaY && !hasDeltaX {
+ resolved, ok := scroll.DirectionFor(direction)
+ if !ok {
+ return mcp.NewToolResultError(fmt.Sprintf("direction must be one of %s", strings.Join(scroll.DirectionKeywords(), ", "))), nil
+ }
+ distance := resolved.Delta * steps
if hasPixels && pixels != 0 {
- magnitude = pixels
+ magnitude := pixels
if magnitude < 0 {
magnitude = -magnitude
}
+ distance = magnitude * steps
+ if resolved.Delta < 0 {
+ distance = -distance
+ }
}
- magnitude *= steps
- switch direction {
- case "down":
- deltaY = magnitude
- case "up":
- deltaY = -magnitude
- default:
- return mcp.NewToolResultError("direction must be 'up' or 'down'"), nil
- }
- hasDeltaY = true
+ payload[resolved.Axis] = distance
+ break
}
useWheel := hasXY || hasDeltaX || hasDeltaY || (hasSelector && hasPixels)
diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.go
index 7bae994c..bef134bd 100644
--- a/internal/mcp/handlers_interaction_test.go
+++ b/internal/mcp/handlers_interaction_test.go
@@ -1,11 +1,21 @@
package mcp
import (
+ "encoding/json"
+ "fmt"
"io"
"net/http"
"net/http/httptest"
+ "os"
+ "path/filepath"
+ "strconv"
"strings"
"testing"
+
+ "github.com/mark3labs/mcp-go/mcp"
+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+ "github.com/pinchtab/pinchtab/internal/scroll"
+ "github.com/spf13/cobra"
)
func TestHandleClick(t *testing.T) {
@@ -252,7 +262,11 @@ func TestHandleScroll(t *testing.T) {
}
}
-func TestHandleScrollDirectionUsesMouseWheel(t *testing.T) {
+// A direction keyword routes to the `scroll` action, not to a wheel event. It used to
+// post kind=mouse-wheel with a notch magnitude, which is the category error that made a
+// sixth of a viewport look like a reasonable answer to "down": a wheel notch is a device
+// unit, and a keyword is an intent. steps still multiplies.
+func TestHandleScrollDirectionRoutesToTheScrollAction(t *testing.T) {
srv := mockPinchTab()
defer srv.Close()
@@ -261,13 +275,33 @@ func TestHandleScrollDirectionUsesMouseWheel(t *testing.T) {
"steps": float64(2),
}, srv)
- resp := resultJSON(t, r)
- body, _ := resp["body"].(map[string]any)
- if got, _ := body["kind"].(string); got != "mouse-wheel" {
- t.Fatalf("kind = %q, want mouse-wheel", got)
+ body, _ := resultJSON(t, r)["body"].(map[string]any)
+ if got, _ := body["kind"].(string); got != "scroll" {
+ t.Fatalf("kind = %q, want scroll — the same action the CLI's keyword posts", got)
+ }
+ if got, _ := body["scrollY"].(float64); got != float64(2*scroll.StepPixels) {
+ t.Fatalf("scrollY = %v, want %d", got, 2*scroll.StepPixels)
+ }
+ if _, wheel := body["deltaY"]; wheel {
+ t.Errorf("payload still carries a wheel delta: %v", body)
}
- if got, _ := body["deltaY"].(float64); got != 240 {
- t.Fatalf("deltaY = %v, want 240", got)
+}
+
+// An explicit pixels value still overrides the keyword magnitude, keeping its sign, so a
+// caller who wants a notch can still ask for one.
+func TestHandleScrollDirectionHonoursAnExplicitPixelsOverride(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ r := callTool(t, "pinchtab_scroll", map[string]any{
+ "direction": "up",
+ "pixels": float64(120),
+ "steps": float64(3),
+ }, srv)
+
+ body, _ := resultJSON(t, r)["body"].(map[string]any)
+ if got, _ := body["scrollY"].(float64); got != -360 {
+ t.Fatalf("scrollY = %v, want -360 (120 x 3, upward)", got)
}
}
@@ -632,3 +666,174 @@ func TestFillStillSendsAnEmptyStringVerbatim(t *testing.T) {
t.Errorf("posted %s, want text:\"\" — the documented way to clear a field", body)
}
}
+
+// THE CARD'S MEASUREMENT, as a test: capture the outbound body on BOTH surfaces and
+// compare them, rather than comparing constants — the two surfaces each used to build
+// their own body from their own copy of the vocabulary, so only the bodies can show they
+// now agree. internal/cli/actions is imported by the test binary only; production
+// internal/mcp does not depend on the CLI.
+func TestScrollDirectionMovesTheSameDistanceOnBothSurfaces(t *testing.T) {
+ for _, keyword := range scroll.DirectionKeywords() {
+ t.Run(keyword, func(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+ mcpBody, _ := resultJSON(t, callTool(t, "pinchtab_scroll", map[string]any{"direction": keyword}, srv))["body"].(map[string]any)
+
+ cliBody := cliScrollBody(t, keyword)
+
+ for _, field := range []string{"kind", "scrollX", "scrollY"} {
+ if fmt.Sprint(mcpBody[field]) != fmt.Sprint(cliBody[field]) {
+ t.Errorf("%q: MCP posted %s=%v, the CLI posted %s=%v — the same keyword must mean the same distance on both surfaces\nMCP: %v\nCLI: %v",
+ keyword, field, mcpBody[field], field, cliBody[field], mcpBody, cliBody)
+ }
+ }
+ })
+ }
+}
+
+// cliScrollBody runs the CLI's own scroll builder against a recording server and returns
+// the body it posted.
+func cliScrollBody(t *testing.T, keyword string) map[string]any {
+ t.Helper()
+ var raw []byte
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ raw, _ = io.ReadAll(r.Body)
+ _, _ = w.Write([]byte(`{"success":true}`))
+ }))
+ defer srv.Close()
+
+ cmd := &cobra.Command{}
+ cmd.Flags().String("tab", "", "")
+ cmd.Flags().Bool("json", false, "")
+ cmd.Flags().Bool("snap", false, "")
+ cmd.Flags().Bool("snap-diff", false, "")
+ cmd.Flags().Bool("text", false, "")
+ cmd.Flags().Int("dy", 0, "")
+ cmd.Flags().Int("dx", 0, "")
+ browseractions.ActionSimple(srv.Client(), srv.URL, "", "scroll", []string{keyword}, cmd)
+
+ var body map[string]any
+ if err := json.Unmarshal(raw, &body); err != nil {
+ t.Fatalf("decode the CLI's body %q: %v", raw, err)
+ }
+ return body
+}
+
+// Every keyword the owner accepts is reachable through MCP: horizontal scrolling used to
+// be refused here while the CLI accepted it, so the vocabulary is asserted as a whole
+// rather than by naming the two the handler happened to support.
+func TestScrollDirectionAcceptsEveryOwnedKeyword(t *testing.T) {
+ srv := mockPinchTab()
+ defer srv.Close()
+
+ for _, keyword := range scroll.DirectionKeywords() {
+ r := callTool(t, "pinchtab_scroll", map[string]any{"direction": keyword}, srv)
+ if r.IsError {
+ t.Errorf("direction %q was refused: %s", keyword, resultText(t, r))
+ continue
+ }
+ body, _ := resultJSON(t, r)["body"].(map[string]any)
+ want, _ := scroll.DirectionFor(keyword)
+ if got, _ := body[want.Axis].(float64); got != float64(want.Delta) {
+ t.Errorf("direction %q posted %s=%v, want %d", keyword, want.Axis, got, want.Delta)
+ }
+ }
+
+ r := callTool(t, "pinchtab_scroll", map[string]any{"direction": "sideways"}, srv)
+ if !r.IsError {
+ t.Fatal("an unknown direction was accepted")
+ }
+ for _, keyword := range scroll.DirectionKeywords() {
+ if !strings.Contains(resultText(t, r), keyword) {
+ t.Errorf("the refusal %q does not name %q, so an agent cannot learn the vocabulary from it", resultText(t, r), keyword)
+ }
+ }
+}
+
+// The tool description is where an agent learns the distance — the whole reason `steps`
+// was unusable was that the magnitude appeared nowhere it reads.
+func TestScrollToolDescriptionStatesTheMagnitudeAndEveryDirection(t *testing.T) {
+ var scrollTool *mcp.Tool
+ for i, tool := range allTools() {
+ if tool.Name == "pinchtab_scroll" {
+ scrollTool = &allTools()[i]
+ }
+ }
+ if scrollTool == nil {
+ t.Fatal("pinchtab_scroll is not declared")
+ }
+ direction, ok := scrollTool.InputSchema.Properties["direction"]
+ if !ok {
+ t.Fatal("pinchtab_scroll declares no direction argument")
+ }
+ described := fmt.Sprint(direction)
+
+ if !strings.Contains(described, strconv.Itoa(scroll.StepPixels)) {
+ t.Errorf("direction description %q states no magnitude; without it steps is only usable by a caller who already knows the default", described)
+ }
+ for _, keyword := range scroll.DirectionKeywords() {
+ if !strings.Contains(described, keyword) {
+ t.Errorf("direction description %q omits %q", described, keyword)
+ }
+ }
+}
+
+// The tool description derives its magnitude from the owner, so it cannot drift — but the
+// agent-facing reference tables spell the number out, and those CAN. They are asserted
+// against the owner too, so a change to the step reds here instead of silently leaving a
+// doc that teaches the wrong distance.
+func TestTheAgentFacingScrollDocsStateTheOwnersMagnitudeAndDirections(t *testing.T) {
+ for _, doc := range []string{
+ filepath.Join("..", "..", "docs", "reference", "mcp-tools.md"),
+ filepath.Join("..", "..", "skills", "pinchtab", "references", "mcp.md"),
+ } {
+ raw, err := os.ReadFile(doc)
+ if err != nil {
+ t.Fatalf("cannot read %s, so this guard would not cover it: %v", doc, err)
+ }
+ row, ok := lineContaining(string(raw), "`pinchtab_scroll` |")
+ if !ok {
+ t.Errorf("%s no longer has a pinchtab_scroll row, so drift there is unguarded", doc)
+ continue
+ }
+ if !strings.Contains(row, strconv.Itoa(scroll.StepPixels)) {
+ t.Errorf("%s states no direction magnitude: %s", doc, row)
+ }
+ for _, keyword := range scroll.DirectionKeywords() {
+ if !strings.Contains(row, keyword) {
+ t.Errorf("%s omits direction %q: %s", doc, keyword, row)
+ }
+ }
+ }
+}
+
+func lineContaining(text, marker string) (string, bool) {
+ for _, line := range strings.Split(text, "\n") {
+ if strings.Contains(line, marker) {
+ return line, true
+ }
+ }
+ return "", false
+}
+
+// Criterion: one owner. The handler must carry neither its own keyword switch nor its own
+// magnitude literal, or the two surfaces can drift apart again exactly as they did.
+func TestScrollHandlerCarriesNoOwnDirectionVocabularyOrMagnitude(t *testing.T) {
+ source, err := os.ReadFile("handlers_interaction.go")
+ if err != nil {
+ t.Fatalf("read the handler: %v", err)
+ }
+ text := string(source)
+
+ for _, keyword := range scroll.DirectionKeywords() {
+ if strings.Contains(text, `case "`+keyword+`"`) {
+ t.Errorf("the handler still switches on %q; the direction vocabulary has one owner, internal/scroll", keyword)
+ }
+ }
+ if strings.Contains(text, "magnitude := 120") || strings.Contains(text, "= 120") {
+ t.Error("the handler still carries a bare notch magnitude; the keyword distance comes from scroll.StepPixels")
+ }
+ if !strings.Contains(text, "scroll.DirectionFor(") {
+ t.Error("the handler no longer reads the owner, so this guard is pinning nothing")
+ }
+}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index c76fe694..c8a0ff3b 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -1,9 +1,20 @@
package mcp
-import "github.com/mark3labs/mcp-go/mcp"
+import (
+ "strconv"
+
+ "github.com/mark3labs/mcp-go/mcp"
+ "github.com/pinchtab/pinchtab/internal/scroll"
+)
const positionalWrapperGrammar = " first/last/nth index matches in document order for every selector kind, so nth:0 is the first match in the page. A bare text: selector instead picks the most control-like smallest match, so text:X and first:text:X can differ."
+// scrollStepDescription states the direction magnitude in the tool description, read
+// from the owner rather than written out: an agent reads these descriptions fresh on
+// every session, so this is where the distance becomes discoverable — without it,
+// 'steps' is only usable by a caller who already knows an undocumented default.
+var scrollStepDescription = strconv.Itoa(scroll.StepPixels) + "px"
+
// allTools returns every MCP tool exposed by the PinchTab MCP server.
func allTools() []mcp.Tool {
return []mcp.Tool{
@@ -176,8 +187,10 @@ func allTools() []mcp.Tool {
mcp.WithNumber("pixels", mcp.Description("Number of pixels to scroll (positive=down, negative=up)")),
mcp.WithNumber("deltaX", mcp.Description("Horizontal wheel delta for precise scrolling")),
mcp.WithNumber("deltaY", mcp.Description("Vertical wheel delta for precise scrolling")),
- mcp.WithString("direction", mcp.Description("Convenience direction: 'up' or 'down'")),
- mcp.WithNumber("steps", mcp.Description("Multiplier for direction-based scrolling (default 1)")),
+ mcp.WithString("direction", mcp.Description(
+ "Convenience direction: 'down', 'left', 'right' or 'up'. Moves "+scrollStepDescription+
+ " per step, the same distance as the CLI's `pinchtab scroll <direction>`; multiply it with 'steps' or override it with 'pixels'.")),
+ mcp.WithNumber("steps", mcp.Description("Multiplier for direction-based scrolling (default 1), so steps=2 moves twice "+scrollStepDescription)),
mcp.WithNumber("x", mcp.Description("Optional X coordinate for wheel target")),
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for wheel target")),
mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
diff --git a/internal/scroll/direction.go b/internal/scroll/direction.go
new file mode 100644
index 00000000..2b271465
--- /dev/null
+++ b/internal/scroll/direction.go
@@ -0,0 +1,56 @@
+// Package scroll owns the scroll DIRECTION KEYWORD: which words name a direction,
+// and how far one of them moves. Every surface that accepts "down" reads it from
+// here, because the vocabulary and the magnitude drifted apart the moment two
+// surfaces each kept their own copy — the CLI moved 800px per keyword while MCP
+// moved 120 and offered no horizontal keyword at all, so the same word meant
+// different things depending on how an agent was talking to the browser.
+//
+// This is deliberately NOT the same notion as the browser's default wheel notch
+// (internal/bridge defaultScrollNotch, 120), which answers a different question:
+// what a wheel event with no delta does. A notch is a device unit; a keyword is an
+// intent. Collapsing the two is what made a sixth of a viewport look like a
+// reasonable answer to "scroll down", so the two values stay separate on purpose.
+package scroll
+
+import "sort"
+
+// StepPixels is how far one direction keyword moves. It is a viewport-scale step
+// rather than a device notch because a caller naming a direction means "bring the
+// next content into view" — a notch takes six or seven round trips to do that, with
+// a snapshot between each.
+const StepPixels = 800
+
+// Direction is where a keyword points: the request field that carries it and the
+// signed distance. Axis is the wire spelling, so a caller can build a request body
+// without restating the mapping.
+type Direction struct {
+ Axis string
+ Delta int
+}
+
+var directions = map[string]Direction{
+ "down": {Axis: "scrollY", Delta: StepPixels},
+ "up": {Axis: "scrollY", Delta: -StepPixels},
+ "right": {Axis: "scrollX", Delta: StepPixels},
+ "left": {Axis: "scrollX", Delta: -StepPixels},
+}
+
+// DirectionFor resolves a keyword, which callers must treat as case-insensitive
+// input from an agent.
+func DirectionFor(keyword string) (Direction, bool) {
+ d, ok := directions[keyword]
+ return d, ok
+}
+
+// DirectionKeywords returns the accepted keywords, sorted. Prose that enumerates
+// them — CLI help, MCP tool descriptions, agent references — is asserted against
+// this rather than against a hand-kept list, so an invented keyword and an omitted
+// one both fail.
+func DirectionKeywords() []string {
+ keywords := make([]string, 0, len(directions))
+ for keyword := range directions {
+ keywords = append(keywords, keyword)
+ }
+ sort.Strings(keywords)
+ return keywords
+}
diff --git a/internal/scroll/direction_test.go b/internal/scroll/direction_test.go
new file mode 100644
index 00000000..bae2381a
--- /dev/null
+++ b/internal/scroll/direction_test.go
@@ -0,0 +1,49 @@
+package scroll
+
+import "testing"
+
+// The vocabulary and the magnitude are asserted here, at the owner, because both
+// surfaces now derive their behaviour from these values: a change made here moves the
+// CLI and MCP together, which is the whole point of the package existing.
+func TestDirectionsCoverBothAxesInBothSignsAtOneStep(t *testing.T) {
+ want := map[string]Direction{
+ "down": {Axis: "scrollY", Delta: StepPixels},
+ "up": {Axis: "scrollY", Delta: -StepPixels},
+ "right": {Axis: "scrollX", Delta: StepPixels},
+ "left": {Axis: "scrollX", Delta: -StepPixels},
+ }
+
+ for keyword, expected := range want {
+ got, ok := DirectionFor(keyword)
+ if !ok {
+ t.Errorf("%q is not an accepted direction", keyword)
+ continue
+ }
+ if got != expected {
+ t.Errorf("DirectionFor(%q) = %+v, want %+v", keyword, got, expected)
+ }
+ }
+ if len(DirectionKeywords()) != len(want) {
+ t.Errorf("keywords = %v, want exactly the four in this table", DirectionKeywords())
+ }
+ if _, ok := DirectionFor("top"); ok {
+ t.Error("'top' resolved; a scroll-to-extreme is an absolute position, not a keyword step")
+ }
+ if _, ok := DirectionFor("DOWN"); ok {
+ t.Error("'DOWN' resolved here; case folding is the caller's job, so a caller that forgets it must fail rather than half-work")
+ }
+}
+
+// A keyword step is a viewport-scale move, not a device notch. The browser's default
+// wheel notch (internal/bridge defaultScrollNotch) answers a different question and
+// stays 120; this asserts the two have not been collapsed into one value, which is what
+// made "scroll down" move a sixth of a viewport through MCP.
+func TestAKeywordStepIsNotAWheelNotch(t *testing.T) {
+ const wheelNotch = 120
+ if StepPixels == wheelNotch {
+ t.Errorf("StepPixels = %d, the same as a wheel notch; a keyword is an intent and a notch is a device unit, so collapsing them reintroduces the six-round-trip scroll", StepPixels)
+ }
+ if StepPixels < wheelNotch {
+ t.Errorf("StepPixels = %d, smaller than one wheel notch", StepPixels)
+ }
+}
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 534e076a..1f9113cd 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -67,7 +67,7 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_hover` | Hover over element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_focus` | Focus an element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_select` | Select dropdown option. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |
-| `pinchtab_scroll` | Scroll page or element. Optional: `selector` or legacy `ref`, `pixels`, `tabId`. |
+| `pinchtab_scroll` | Scroll page or element. Optional: `selector` or legacy `ref`, `pixels`, `tabId`, `direction` (`down`/`left`/`right`/`up`, 800px per step — same as the CLI), `steps`. |
### Keyboard
| Tool | Description |