Skip to content

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

feat: add pixel-offset drag and extend action options

Bosch8a93fc428d0e
diff --git a/cmd/pinchtab/cmd_cli_browser_actions.go b/cmd/pinchtab/cmd_cli_browser_actions.go
index d8bc7ad5..b88d00d3 100644
--- a/cmd/pinchtab/cmd_cli_browser_actions.go
+++ b/cmd/pinchtab/cmd_cli_browser_actions.go
@@ -84,9 +84,20 @@ var mouseUpCmd = newMouseActionCmd("up [ref|selector]", "Release mouse button",
var mouseWheelCmd = newMouseActionCmd("wheel [dy|ref|selector]", "Dispatch mouse wheel deltas", bridge.ActionMouseWheel, cobra.MaximumNArgs(1))
var dragCmd = &cobra.Command{
- Use: "drag <from> <to>",
- Short: "Drag from one target to another",
- Args: cobra.ExactArgs(2),
+ Use: "drag <from> <to> | <selector> --drag-x <n> --drag-y <n>",
+ Short: "Drag from one target to another (or by pixel offset)",
+ Long: `Drag a DOM element.
+
+Two forms:
+ pinchtab drag <from> <to>
+ Synthesizes mouse-move → mouse-down → mouse-move → mouse-up.
+ Each target is a selector (CSS, ref, text:) or an "x,y" coord pair.
+
+ pinchtab drag <selector> --drag-x <n> --drag-y <n>
+ Single-step HTTP "drag" action with pixel offsets from the element's
+ current position. Symmetric with the HTTP /action body
+ {"kind":"drag","selector":"...","dragX":N,"dragY":N}.`,
+ Args: cobra.RangeArgs(1, 2),
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.Drag(rt.client, rt.base, rt.token, args, cmd)
@@ -96,7 +107,35 @@ var dragCmd = &cobra.Command{
var focusCmd = newOptionalRefActionCmd("focus <ref>", "Focus element", "focus")
-var scrollCmd = newSimpleActionCmd("scroll <ref|pixels>", "Scroll to element or by pixels", "scroll", cobra.MinimumNArgs(1))
+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:
+
+ 1. Integer → scrollY in pixels (positive down, negative up).
+ pinchtab scroll 800
+ pinchtab scroll -300
+
+ 2. Direction keyword: up | down | left | right (defaults to 800px per step).
+ pinchtab scroll down
+ pinchtab scroll right
+
+ 3. Otherwise, a unified selector — ref, CSS, XPath, text:, or semantic:.
+ The element is scrolled into view.
+ pinchtab scroll e12
+ pinchtab scroll '#footer'
+ pinchtab scroll '//footer'
+ pinchtab scroll 'text:Load more'
+
+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),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.ActionSimple(rt.client, rt.base, rt.token, "scroll", args, cmd)
+ })
+ },
+}
var selectCmd = newSimpleActionCmd("select <ref> <value>", "Select option in dropdown", "select", cobra.MinimumNArgs(2))
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index f5f18a3b..e7cf30df 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -1,6 +1,8 @@
package main
import (
+ "os"
+
"github.com/pinchtab/pinchtab/internal/bridge"
"github.com/spf13/cobra"
)
@@ -124,6 +126,8 @@ func configureBrowserFlags() {
clickCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(clickCmd, "click")
clickCmd.Flags().Bool("wait-nav", false, "Wait for navigation after click")
+ clickCmd.Flags().String("dialog-action", "", "Auto-handle a JS dialog opened by the click: accept | dismiss")
+ clickCmd.Flags().String("dialog-text", "", "Prompt response text (with --dialog-action accept on prompt())")
dblclickCmd.Flags().String("css", "", "CSS selector instead of ref")
addPointFlags(dblclickCmd, "dblclick")
@@ -148,6 +152,8 @@ func configureBrowserFlags() {
mouseWheelCmd.Flags().Int("dy", 0, "Wheel delta Y")
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")
focusCmd.Flags().String("css", "", "CSS selector instead of ref")
@@ -185,7 +191,8 @@ func configureBrowserFlags() {
findCmd.Flags().Bool("explain", false, "Show score breakdown")
findCmd.Flags().Bool("ref-only", false, "Output just the element ref")
- textCmd.Flags().Bool("raw", false, "Raw extraction mode")
+ textCmd.Flags().Bool("raw", false, "Raw extraction mode (alias of --full)")
+ textCmd.Flags().Bool("full", false, "Return the full page text (document.body.innerText) instead of the default Readability-filtered content")
navCmd.Flags().Bool("new-tab", false, "Open in new tab")
navCmd.Flags().Bool("block-images", false, "Block image loading")
@@ -229,6 +236,9 @@ func configureBrowserFlags() {
dialogDismissCmd,
)
+ evalCmd.Flags().Bool("await-promise", false, "Resolve a returned Promise before responding")
+ navCmd.Flags().Bool("print-tab-id", false, "Print only the tab ID on stdout (also triggered automatically when stdout is a pipe)")
+
scrollintoviewCmd.Flags().String("css", "", "CSS selector instead of ref")
networkCmd.Flags().String("filter", "", "URL pattern filter")
@@ -276,9 +286,19 @@ func addRootCommands(cmds ...*cobra.Command) {
rootCmd.AddCommand(cmds...)
}
+// addTabFlag wires a --tab flag onto the given commands and defaults its
+// value to $PINCHTAB_TAB when the env var is set. This lets agents avoid
+// threading `--tab "$TAB"` through every command:
+//
+// export PINCHTAB_TAB=$(pinchtab nav http://example.com)
+// pinchtab snap -i -c # auto-targets $PINCHTAB_TAB
+//
+// Explicit --tab still wins (cobra flag precedence). If the env var isn't
+// set and no flag is passed, the server picks the active tab as before.
func addTabFlag(cmds ...*cobra.Command) {
+ defaultTab := os.Getenv("PINCHTAB_TAB")
for _, cmd := range cmds {
- cmd.Flags().String("tab", "", "Tab ID")
+ cmd.Flags().String("tab", defaultTab, "Tab ID (env: PINCHTAB_TAB)")
}
}
diff --git a/internal/bridge/action_form.go b/internal/bridge/action_form.go
index 1679cc5d..5bbd486a 100644
--- a/internal/bridge/action_form.go
+++ b/internal/bridge/action_form.go
@@ -26,13 +26,18 @@ func (b *Bridge) actionSelect(ctx context.Context, req ActionRequest) (map[strin
if val == "" {
return nil, fmt.Errorf("value required for select")
}
+ // Both paths route through SelectByNodeID so they share its
+ // value-then-text match fallback. This lets callers pass either the
+ // `<option value="...">` attribute or the option's visible text.
if req.NodeID > 0 {
return map[string]any{"selected": val}, SelectByNodeID(ctx, req.NodeID, val)
}
if req.Selector != "" {
- return map[string]any{"selected": val}, chromedp.Run(ctx,
- chromedp.SetValue(req.Selector, val, chromedp.ByQuery),
- )
+ node, err := firstNodeBySelector(ctx, req.Selector)
+ if err != nil {
+ return nil, err
+ }
+ return map[string]any{"selected": val}, SelectByNodeID(ctx, int64(node.BackendNodeID), val)
}
return nil, fmt.Errorf("need selector or ref")
}
diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go
index b39106e3..d5c47f65 100644
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -625,8 +625,16 @@ type ActionRequest struct {
Value string `json:"value"`
NodeID int64 `json:"nodeId"`
- X float64 `json:"x"`
- Y float64 `json:"y"`
+ // X/Y use omitempty so that re-marshaling an ActionRequest without
+ // explicit coordinates (e.g. when the tab-scoped handler forwards to
+ // the generic one) doesn't spuriously re-introduce "x":0, "y":0. The
+ // ActionRequest.UnmarshalJSON code infers HasXY from the presence of
+ // these keys, so preserving omission is what makes "use current
+ // pointer" work for mouse-down/up after a prior mouse-move. HasXY is
+ // still marshaled (with omitempty) when it was explicitly set, which
+ // preserves the explicit-click-at-(0,0) case through the round-trip.
+ X float64 `json:"x,omitempty"`
+ Y float64 `json:"y,omitempty"`
HasXY bool `json:"hasXY,omitempty"`
Button string `json:"button,omitempty"`
diff --git a/internal/bridge/cdpops/element_ops.go b/internal/bridge/cdpops/element_ops.go
index 8e2185f7..804fac13 100644
--- a/internal/bridge/cdpops/element_ops.go
+++ b/internal/bridge/cdpops/element_ops.go
@@ -3,6 +3,7 @@ package cdpops
import (
"context"
"encoding/json"
+ "fmt"
"github.com/chromedp/chromedp"
)
@@ -51,6 +52,21 @@ func FillByNodeID(ctx context.Context, nodeID int64, value string) error {
)
}
+// SelectByNodeID sets the value of a <select> element, with a forgiving
+// lookup: if the raw input doesn't match any option's `value` attribute, the
+// function falls back to an exact (trimmed) match against each option's
+// visible text, and then to a case-insensitive trimmed text match. This lets
+// callers pass whatever they see in a snapshot (`"United Kingdom"`) instead
+// of having to look up the underlying `value` attr (`"uk"`).
+//
+// When the element isn't a <select> (no `.options` collection), behavior
+// degrades to the original "set .value directly" path — preserves backward
+// compatibility for anyone using this helper on a plain input or custom
+// element.
+//
+// Returns an error when none of the three match strategies find an option on
+// a <select> element; the error enumerates available values + texts to make
+// the failure actionable.
func SelectByNodeID(ctx context.Context, nodeID int64, value string) error {
return chromedp.Run(ctx,
chromedp.ActionFunc(func(ctx context.Context) error {
@@ -71,12 +87,85 @@ func SelectByNodeID(ctx context.Context, nodeID int64, value string) error {
if err := json.Unmarshal(result, &resolved); err != nil {
return err
}
- js := `function(v) { this.value = v; this.dispatchEvent(new Event('input', {bubbles: true})); this.dispatchEvent(new Event('change', {bubbles: true})); }`
- return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
+ // Return a structured object so the caller can inspect (a) the match
+ // strategy used and (b) the effective option value that was applied.
+ js := `function(v) {
+ var opts = this.options ? Array.from(this.options) : null;
+ if (!opts) {
+ // Not a <select>; preserve legacy behavior.
+ this.value = v;
+ this.dispatchEvent(new Event('input', {bubbles: true}));
+ this.dispatchEvent(new Event('change', {bubbles: true}));
+ return { ok: true, matchedBy: "legacy", value: v };
+ }
+ var target = String(v);
+ var trimmed = target.trim();
+ var lower = trimmed.toLowerCase();
+ var match = null, matchedBy = "";
+ // 1. Exact value attribute (the canonical form).
+ for (var i = 0; i < opts.length; i++) {
+ if (opts[i].value === target) { match = opts[i]; matchedBy = "value"; break; }
+ }
+ // 2. Exact (trimmed) visible text.
+ if (!match) {
+ for (var i = 0; i < opts.length; i++) {
+ if ((opts[i].text || "").trim() === trimmed) { match = opts[i]; matchedBy = "text"; break; }
+ }
+ }
+ // 3. Case-insensitive (trimmed) visible text.
+ if (!match) {
+ for (var i = 0; i < opts.length; i++) {
+ if ((opts[i].text || "").trim().toLowerCase() === lower) { match = opts[i]; matchedBy = "text-ci"; break; }
+ }
+ }
+ if (!match) {
+ return {
+ ok: false,
+ error: "no option matched " + JSON.stringify(v) + " by value or visible text",
+ available: opts.map(function (o) { return { value: o.value, text: (o.text || "").trim() }; })
+ };
+ }
+ this.value = match.value;
+ this.dispatchEvent(new Event('input', {bubbles: true}));
+ this.dispatchEvent(new Event('change', {bubbles: true}));
+ return { ok: true, matchedBy: matchedBy, value: match.value, text: (match.text || "").trim() };
+ }`
+ var callResult json.RawMessage
+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
"functionDeclaration": js,
"objectId": resolved.Object.ObjectID,
"arguments": []map[string]any{{"value": value}},
- }, nil)
+ "returnByValue": true,
+ }, &callResult); err != nil {
+ return err
+ }
+ var cr struct {
+ Result struct {
+ Value json.RawMessage `json:"value"`
+ } `json:"result"`
+ }
+ if err := json.Unmarshal(callResult, &cr); err != nil {
+ return err
+ }
+ var outcome struct {
+ OK bool `json:"ok"`
+ Error string `json:"error"`
+ MatchedBy string `json:"matchedBy"`
+ Available []struct {
+ Value string `json:"value"`
+ Text string `json:"text"`
+ } `json:"available"`
+ }
+ if err := json.Unmarshal(cr.Result.Value, &outcome); err != nil {
+ // Callers that use this helper on non-JSON-serializable
+ // outcomes (shouldn't happen given the JS above) get the raw
+ // error surfaced instead of a silent success.
+ return fmt.Errorf("parse select result: %w", err)
+ }
+ if !outcome.OK {
+ return fmt.Errorf("%s", outcome.Error)
+ }
+ return nil
}),
)
}
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index d93bdbd0..ddd3b9fa 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -44,6 +44,16 @@ func Action(client *http.Client, base, token, kind, selectorArg string, cmd *cob
if v, _ := cmd.Flags().GetBool("wait-nav"); v {
body["waitNav"] = true
}
+ // --dialog-action arms a one-shot JS dialog handler before the click.
+ // Mirrors the HTTP action body field {"dialogAction":"accept"|"dismiss"}.
+ // Without this, a click that opens an alert/confirm hangs until
+ // /dialog is called from a separate request.
+ if v, _ := cmd.Flags().GetString("dialog-action"); v != "" {
+ body["dialogAction"] = v
+ }
+ if v, _ := cmd.Flags().GetString("dialog-text"); v != "" {
+ body["dialogText"] = v
+ }
}
postAction(client, base, token, cmd, body)
@@ -224,6 +234,36 @@ func actionBodyForTarget(kind string, target dragTarget) map[string]any {
}
func Drag(client *http.Client, base, token string, args []string, cmd *cobra.Command) {
+ // Two modes:
+ // 1. pinchtab drag <selector> --drag-x N --drag-y N
+ // → single HTTP "drag" action with pixel offsets (dragX/dragY).
+ // 2. pinchtab drag <from> <to>
+ // → synthesized mouse-move → mouse-down → mouse-move → mouse-up
+ // sequence. Each target may be "selector" or "x,y" coords.
+ hasDragX := cmd.Flags().Changed("drag-x")
+ hasDragY := cmd.Flags().Changed("drag-y")
+
+ if hasDragX || hasDragY {
+ if len(args) != 1 {
+ cli.Fatal("Usage: pinchtab drag <selector> --drag-x <n> --drag-y <n>")
+ }
+ body := map[string]any{"kind": bridge.ActionDrag}
+ setSelectorBody(body, args[0])
+ dx, _ := cmd.Flags().GetInt("drag-x")
+ dy, _ := cmd.Flags().GetInt("drag-y")
+ body["dragX"] = dx
+ body["dragY"] = dy
+ if button, _ := cmd.Flags().GetString("button"); button != "" {
+ body["button"] = button
+ }
+ postAction(client, base, token, cmd, body)
+ return
+ }
+
+ if len(args) != 2 {
+ cli.Fatal("Usage: pinchtab drag <from> <to> or pinchtab drag <selector> --drag-x <n> --drag-y <n>")
+ }
+
from := parseDragTarget(args[0])
to := parseDragTarget(args[1])
@@ -255,24 +295,29 @@ func ActionSimple(client *http.Client, base, token, kind string, args []string,
case "press":
body["key"] = args[0]
case "scroll":
- sel := selector.Parse(args[0])
- if sel.Kind == selector.KindRef {
- body["ref"] = sel.Value
- } else if px, err := strconv.Atoi(args[0]); err == nil {
+ // 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
- } else {
- 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:
- cli.Fatal("Usage: pinchtab scroll <selector|pixels|direction> (e.g. e5, 800, or down)")
- }
+ 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])
}
case "select":
setSelectorBody(body, args[0])
diff --git a/internal/cli/actions/actions_element_test.go b/internal/cli/actions/actions_element_test.go
index 1e8a8e3a..9289bc71 100644
--- a/internal/cli/actions/actions_element_test.go
+++ b/internal/cli/actions/actions_element_test.go
@@ -17,6 +17,8 @@ func newActionCmd() *cobra.Command {
cmd.Flags().String("button", "", "")
cmd.Flags().Int("dx", 0, "")
cmd.Flags().Int("dy", 0, "")
+ cmd.Flags().String("dialog-action", "", "")
+ cmd.Flags().String("dialog-text", "", "")
return cmd
}
@@ -61,6 +63,42 @@ func TestClickWaitNav(t *testing.T) {
}
}
+func TestClickDialogAction(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newActionCmd()
+ _ = cmd.Flags().Set("dialog-action", "accept")
+ _ = cmd.Flags().Set("dialog-text", "hello")
+ Action(client, m.base(), "", "click", "#alert-btn", cmd)
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if body["dialogAction"] != "accept" {
+ t.Errorf("expected dialogAction=accept, got %v", body["dialogAction"])
+ }
+ if body["dialogText"] != "hello" {
+ t.Errorf("expected dialogText=hello, got %v", body["dialogText"])
+ }
+}
+
+func TestClickDialogActionOmittedByDefault(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newActionCmd()
+ Action(client, m.base(), "", "click", "#button", cmd)
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if _, present := body["dialogAction"]; present {
+ t.Errorf("expected dialogAction to be omitted, got %v", body["dialogAction"])
+ }
+ if _, present := body["dialogText"]; present {
+ t.Errorf("expected dialogText to be omitted, got %v", body["dialogText"])
+ }
+}
+
func TestType(t *testing.T) {
m := newMockServer()
defer m.close()
@@ -379,6 +417,26 @@ func TestScroll(t *testing.T) {
if body["scrollY"] != float64(800) {
t.Errorf("expected scrollY=800 for direction=down, got %v", body["scrollY"])
}
+
+ // CSS selector auto-detection: `scroll #footer` should forward as
+ // selector, matching how click/fill/hover behave for bare selectors.
+ ActionSimple(client, m.base(), "", "scroll", []string{"#footer"}, cmd)
+ body = nil
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if body["selector"] != "#footer" {
+ t.Errorf("expected selector=#footer, got %v", body["selector"])
+ }
+ if _, hasScrollY := body["scrollY"]; hasScrollY {
+ t.Errorf("should not set scrollY for CSS selector form, got %v", body["scrollY"])
+ }
+
+ // XPath also flows through.
+ ActionSimple(client, m.base(), "", "scroll", []string{"//footer"}, cmd)
+ body = nil
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if body["selector"] != "//footer" {
+ t.Errorf("expected selector=//footer, got %v", body["selector"])
+ }
}
func TestCheck(t *testing.T) {
diff --git a/internal/cli/actions/actions_evaluate.go b/internal/cli/actions/actions_evaluate.go
index fd6575db..16539fce 100644
--- a/internal/cli/actions/actions_evaluate.go
+++ b/internal/cli/actions/actions_evaluate.go
@@ -10,6 +10,9 @@ import (
func Evaluate(client *http.Client, base, token string, args []string, cmd *cobra.Command) {
body := map[string]any{"expression": strings.Join(args, " ")}
+ if awaitPromise, _ := cmd.Flags().GetBool("await-promise"); awaitPromise {
+ body["awaitPromise"] = true
+ }
tabID, _ := cmd.Flags().GetString("tab")
path := "/evaluate"
if tabID != "" {
diff --git a/internal/cli/actions/actions_evaluate_test.go b/internal/cli/actions/actions_evaluate_test.go
index 262d3ada..5aefae7a 100644
--- a/internal/cli/actions/actions_evaluate_test.go
+++ b/internal/cli/actions/actions_evaluate_test.go
@@ -10,6 +10,7 @@ import (
func newEvalCmd() *cobra.Command {
cmd := &cobra.Command{}
cmd.Flags().String("tab", "", "")
+ cmd.Flags().Bool("await-promise", false, "")
return cmd
}
@@ -44,3 +45,32 @@ func TestEvaluateMultiWord(t *testing.T) {
t.Errorf("expected expression='1 + 2', got %v", body["expression"])
}
}
+
+func TestEvaluateAwaitPromise(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newEvalCmd()
+ _ = cmd.Flags().Set("await-promise", "true")
+ Evaluate(client, m.base(), "", []string{"Promise.resolve(1)"}, cmd)
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if body["awaitPromise"] != true {
+ t.Errorf("expected awaitPromise=true, got %v", body["awaitPromise"])
+ }
+}
+
+func TestEvaluateAwaitPromiseOmittedByDefault(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newEvalCmd()
+ Evaluate(client, m.base(), "", []string{"document.title"}, cmd)
+ var body map[string]any
+ _ = json.Unmarshal([]byte(m.lastBody), &body)
+ if _, present := body["awaitPromise"]; present {
+ t.Errorf("expected awaitPromise to be omitted, got %v", body["awaitPromise"])
+ }
+}
diff --git a/internal/cli/actions/actions_navigate.go b/internal/cli/actions/actions_navigate.go
index 1fd44cc8..86dcaa92 100644
--- a/internal/cli/actions/actions_navigate.go
+++ b/internal/cli/actions/actions_navigate.go
@@ -5,8 +5,20 @@ import (
"github.com/pinchtab/pinchtab/internal/cli/apiclient"
"github.com/spf13/cobra"
"net/http"
+ "os"
)
+// stdoutIsPipe reports whether stdout is a pipe/redirect rather than a
+// terminal. Used to switch `nav` into machine-friendly output mode so
+// `export PINCHTAB_TAB=$(pinchtab nav URL)` captures just the tab ID.
+func stdoutIsPipe() bool {
+ fi, err := os.Stdout.Stat()
+ if err != nil {
+ return false
+ }
+ return (fi.Mode() & os.ModeCharDevice) == 0
+}
+
// Back navigates the current (or specified) tab back in history.
func Back(client *http.Client, base, token string, cmd *cobra.Command) {
tabID, _ := cmd.Flags().GetString("tab")
@@ -53,6 +65,19 @@ func Navigate(client *http.Client, base, token string, url string, cmd *cobra.Co
if tabID != "" {
path = fmt.Sprintf("/tabs/%s/navigate", tabID)
}
+
+ // Machine-friendly output: emit only the tabId when --print-tab-id is set
+ // or when stdout is a pipe/redirect. Enables:
+ // export PINCHTAB_TAB=$(pinchtab nav http://example.com)
+ printTabID, _ := cmd.Flags().GetBool("print-tab-id")
+ if printTabID || stdoutIsPipe() {
+ result := apiclient.DoPostQuiet(client, base, token, path, body)
+ if tid, ok := result["tabId"].(string); ok && tid != "" {
+ fmt.Println(tid)
+ }
+ return
+ }
+
result := apiclient.DoPost(client, base, token, path, body)
apiclient.SuggestNextAction("navigate", result)
}
diff --git a/internal/cli/actions/actions_navigate_test.go b/internal/cli/actions/actions_navigate_test.go
index 9fe92692..939d7307 100644
--- a/internal/cli/actions/actions_navigate_test.go
+++ b/internal/cli/actions/actions_navigate_test.go
@@ -2,6 +2,7 @@ package actions
import (
"encoding/json"
+ "strings"
"testing"
"github.com/spf13/cobra"
@@ -13,6 +14,7 @@ func newNavigateCmd() *cobra.Command {
cmd.Flags().Bool("block-images", false, "")
cmd.Flags().Bool("block-ads", false, "")
cmd.Flags().String("tab", "", "")
+ cmd.Flags().Bool("print-tab-id", false, "")
return cmd
}
@@ -69,3 +71,23 @@ func TestNavigateWithBlockAds(t *testing.T) {
t.Error("expected blockAds=true")
}
}
+
+// TestNavigatePrintTabID verifies that --print-tab-id makes `nav` emit only
+// the tab ID on stdout so agents can capture it via `$(pinchtab nav URL)`.
+func TestNavigatePrintTabID(t *testing.T) {
+ m := newMockServer()
+ m.response = `{"tabId":"ABC123","status":"ok"}`
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newNavigateCmd()
+ _ = cmd.Flags().Set("print-tab-id", "true")
+
+ out := captureStdout(t, func() {
+ Navigate(client, m.base(), "", "https://pinchtab.com", cmd)
+ })
+ got := strings.TrimSpace(out)
+ if got != "ABC123" {
+ t.Errorf("expected stdout to be exactly 'ABC123', got %q", got)
+ }
+}
diff --git a/internal/cli/actions/actions_text.go b/internal/cli/actions/actions_text.go
index 04fb8980..0e7177b3 100644
--- a/internal/cli/actions/actions_text.go
+++ b/internal/cli/actions/actions_text.go
@@ -9,7 +9,14 @@ import (
func Text(client *http.Client, base, token string, cmd *cobra.Command) {
params := url.Values{}
- if v, _ := cmd.Flags().GetBool("raw"); v {
+ // --full is the preferred, discoverable name; --raw is kept as a
+ // backward-compatible alias. Both switch the server off its default
+ // Readability extraction onto a plain document.body.innerText pull, so
+ // navigation / repeated headlines / short text nodes that Readability
+ // considers chrome are retained.
+ raw, _ := cmd.Flags().GetBool("raw")
+ full, _ := cmd.Flags().GetBool("full")
+ if raw || full {
params.Set("mode", "raw")
params.Set("format", "text")
}
diff --git a/internal/cli/actions/actions_text_test.go b/internal/cli/actions/actions_text_test.go
index f7bf2606..8a2fe4d9 100644
--- a/internal/cli/actions/actions_text_test.go
+++ b/internal/cli/actions/actions_text_test.go
@@ -10,6 +10,7 @@ import (
func newTextCmd() *cobra.Command {
cmd := &cobra.Command{}
cmd.Flags().Bool("raw", false, "")
+ cmd.Flags().Bool("full", false, "")
cmd.Flags().String("tab", "", "")
return cmd
}
@@ -43,6 +44,22 @@ func TestTextRaw(t *testing.T) {
}
}
+func TestTextFull(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newTextCmd()
+ _ = cmd.Flags().Set("full", "true")
+ Text(client, m.base(), "", cmd)
+ if !strings.Contains(m.lastQuery, "mode=raw") {
+ t.Errorf("expected --full to set mode=raw, got %s", m.lastQuery)
+ }
+ if !strings.Contains(m.lastQuery, "format=text") {
+ t.Errorf("expected --full to set format=text, got %s", m.lastQuery)
+ }
+}
+
func TestTextTab(t *testing.T) {
m := newMockServer()
defer m.close()
diff --git a/internal/cli/apiclient/client.go b/internal/cli/apiclient/client.go
index 5a0d40ad..b821b273 100644
--- a/internal/cli/apiclient/client.go
+++ b/internal/cli/apiclient/client.go
@@ -32,20 +32,7 @@ func DoGet(client *http.Client, base, token, path string, params url.Values) map
os.Exit(1)
}
- // Pretty-print JSON if possible
- var buf bytes.Buffer
- if json.Indent(&buf, body, "", " ") == nil {
- fmt.Println(buf.String())
- } else {
- fmt.Println(string(body))
- }
-
- // Parse and return result
- var result map[string]any
- if err := json.Unmarshal(body, &result); err != nil {
- log.Printf("warning: error unmarshaling response: %v", err)
- }
- return result
+ return printAndDecode(body)
}
func DoGetRaw(client *http.Client, base, token, path string, params url.Values) []byte {
@@ -73,14 +60,14 @@ func DoPost(client *http.Client, base, token, path string, body map[string]any)
return DoPostWithHeaders(client, base, token, path, body, nil)
}
-func DoPostWithHeaders(client *http.Client, base, token, path string, body map[string]any, headers map[string]string) map[string]any {
+// DoPostQuiet is like DoPost but does not print the response body. Callers are
+// responsible for rendering whatever output is appropriate (e.g. a single
+// field for machine-friendly piping).
+func DoPostQuiet(client *http.Client, base, token, path string, body map[string]any) map[string]any {
data, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", base+path, bytes.NewReader(data))
req.Header.Set("Content-Type", "application/json")
setClientHeaders(req, token)
- for key, value := range headers {
- req.Header.Set(key, value)
- }
resp, err := client.Do(req)
if err != nil {
fatal("Request failed: %v", err)
@@ -93,14 +80,6 @@ func DoPostWithHeaders(client *http.Client, base, token, path string, body map[s
os.Exit(1)
}
- var buf bytes.Buffer
- if json.Indent(&buf, respBody, "", " ") == nil {
- fmt.Println(buf.String())
- } else {
- fmt.Println(string(respBody))
- }
-
- // Parse and return result for suggestions
var result map[string]any
if err := json.Unmarshal(respBody, &result); err != nil {
log.Printf("warning: error unmarshaling response: %v", err)
@@ -108,6 +87,29 @@ func DoPostWithHeaders(client *http.Client, base, token, path string, body map[s
return result
}
+func DoPostWithHeaders(client *http.Client, base, token, path string, body map[string]any, headers map[string]string) map[string]any {
+ data, _ := json.Marshal(body)
+ req, _ := http.NewRequest("POST", base+path, bytes.NewReader(data))
+ req.Header.Set("Content-Type", "application/json")
+ setClientHeaders(req, token)
+ for key, value := range headers {
+ req.Header.Set(key, value)
+ }
+ resp, err := client.Do(req)
+ if err != nil {
+ fatal("Request failed: %v", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ respBody, _ := io.ReadAll(resp.Body)
+
+ if resp.StatusCode >= 400 {
+ handleAPIError(resp.StatusCode, respBody)
+ os.Exit(1)
+ }
+
+ return printAndDecode(respBody)
+}
+
// DoDelete sends a DELETE request with an optional JSON body (e.g. for ?name= query params, pass nil body and handle params in path).
func DoDelete(client *http.Client, base, token, path string, params url.Values) map[string]any {
u := base + path
@@ -128,18 +130,7 @@ func DoDelete(client *http.Client, base, token, path string, params url.Values)
os.Exit(1)
}
- var buf bytes.Buffer
- if json.Indent(&buf, respBody, "", " ") == nil {
- fmt.Println(buf.String())
- } else {
- fmt.Println(string(respBody))
- }
-
- var result map[string]any
- if err := json.Unmarshal(respBody, &result); err != nil {
- log.Printf("warning: error unmarshaling response: %v", err)
- }
- return result
+ return printAndDecode(respBody)
}
// DoDeleteJSON sends a DELETE request with a JSON body.
@@ -160,16 +151,26 @@ func DoDeleteJSON(client *http.Client, base, token, path string, body map[string
os.Exit(1)
}
+ return printAndDecode(respBody)
+}
+
+// printAndDecode pretty-prints the body when it is JSON, falls back to
+// raw output otherwise, and returns the parsed map (if any) for the
+// suggestion logic. It only warns on genuine JSON decode errors — inherently
+// non-JSON responses like /snapshot's compact text format pass silently.
+func printAndDecode(body []byte) map[string]any {
var buf bytes.Buffer
- if json.Indent(&buf, respBody, "", " ") == nil {
+ isJSON := json.Indent(&buf, body, "", " ") == nil
+ if isJSON {
fmt.Println(buf.String())
} else {
- fmt.Println(string(respBody))
+ fmt.Println(string(body))
}
-
var result map[string]any
- if err := json.Unmarshal(respBody, &result); err != nil {
- log.Printf("warning: error unmarshaling response: %v", err)
+ if isJSON {
+ if err := json.Unmarshal(body, &result); err != nil {
+ log.Printf("warning: error unmarshaling response: %v", err)
+ }
}
return result
}
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 4053c7d0..38f29a0b 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -166,6 +166,7 @@ pinchtab nav <url> --new-tab
pinchtab nav <url> --tab <tab-id>
pinchtab nav <url> --block-images
pinchtab nav <url> --block-ads
+pinchtab nav <url> --print-tab-id # Print only the new tabId on stdout
pinchtab back # Navigate back in history
pinchtab forward # Navigate forward
pinchtab reload # Reload current page
@@ -175,6 +176,23 @@ pinchtab tab close <tab-id>
pinchtab instance navigate <instance-id> <url>
```
+When stdout is a pipe (e.g. inside `$(...)`), `nav` automatically switches to
+`--print-tab-id` mode so agents can capture the tab ID with a single line,
+then export it once via `PINCHTAB_TAB` so every subsequent tab-scoped command
+picks it up without threading `--tab "$TAB"` through each call:
+
+```bash
+# Capture once, reuse across every following command.
+export PINCHTAB_TAB=$(pinchtab nav http://example.com)
+pinchtab snap -i -c
+pinchtab eval "document.title"
+pinchtab click '#submit'
+pinchtab drag '#piece' '#zone-a'
+```
+
+An explicit `--tab <id>` on any command still overrides `PINCHTAB_TAB`.
+See `references/env.md` for the full list of supported env vars.
+
### Observation
```bash
@@ -185,8 +203,9 @@ pinchtab snap -d # Diff from previous snapsho
pinchtab snap --selector <css> # Scope to CSS selector
pinchtab snap --max-tokens <n> # Token budget limit
pinchtab snap --text # Text output format
-pinchtab text # Page text content
-pinchtab text --raw # Raw text extraction
+pinchtab text # Page text content (Readability-filtered; drops nav/repeated headlines)
+pinchtab text --full # Full page text (document.body.innerText) — use when Readability is dropping content you need
+pinchtab text --raw # Alias of --full
pinchtab find <query> # Semantic element search
pinchtab find --ref-only <query> # Return refs only
```
@@ -207,6 +226,10 @@ All interaction commands accept unified selectors (refs, CSS, XPath, text, seman
pinchtab click <selector> # Click element
pinchtab click --wait-nav <selector> # Click and wait for navigation
pinchtab click --x 100 --y 200 # Click by coordinates
+pinchtab click <selector> --dialog-action accept # Click + auto-accept any alert/confirm the click opens
+pinchtab click <selector> --dialog-action dismiss # Click + auto-dismiss
+pinchtab click <selector> --dialog-action accept \
+ --dialog-text "hello" # Click + accept a prompt() with a response
pinchtab dblclick <selector> # Double-click element
pinchtab mouse move <selector> # Move pointer to element center
pinchtab mouse move <x> <y> # Move pointer to coordinates
@@ -215,13 +238,14 @@ pinchtab mouse down --button left # Press a mouse button at cu
pinchtab mouse up <selector> --button left # Release a mouse button at an explicit target
pinchtab mouse up --button left # Release a mouse button at current pointer
pinchtab mouse wheel 240 --dx 40 # Dispatch wheel deltas at current pointer
-pinchtab drag <from> <to> # Drag between selector/ref or x,y points
+pinchtab drag <from> <to> # Drag between selector/ref or x,y points (synthesized mouse sequence)
+pinchtab drag <selector> --drag-x <n> --drag-y <n> # Single-step drag by pixel offset (mirrors HTTP /action dragX/dragY)
pinchtab type <selector> <text> # Type with keystrokes
pinchtab fill <selector> <text> # Set value directly
pinchtab press <key> # Press key (Enter, Tab, Escape...)
pinchtab hover <selector> # Hover element
-pinchtab select <selector> <value> # Select dropdown option
-pinchtab scroll <selector|pixels> # Scroll element or page
+pinchtab select <selector> <value|text> # Select dropdown option by value attr, or fall back to visible text
+pinchtab scroll <pixels|direction|selector> # Scroll page (e.g. 800), by direction (up/down/left/right), or to an element (ref, #id, .class, //xpath, text:...)
```
Rules:
@@ -231,8 +255,8 @@ Rules:
- Prefer `click --wait-nav` when a click is expected to navigate.
- Prefer low-level `mouse` commands only when normal `click` / `hover` abstractions are insufficient, such as drag handles, canvas widgets, or sites that depend on exact pointer sequences.
- Re-snapshot immediately after `click`, `press Enter`, `select`, or `scroll` if the UI can change.
-- To discover valid dropdown values, snapshot with `filter=interactive` first — the output shows `<option>` elements with their `value` attributes. Then use `select` with the exact value.
-- If a click opens a JS dialog (`alert`, `confirm`, `prompt`), pass `"dialogAction": "accept"` or `"dialogAction": "dismiss"` on the click action body. The dialog is auto-handled in a single call. Without this, the click hangs until `/tabs/TAB_ID/dialog` is called from a parallel request, and a pending dialog wedges subsequent `/snapshot` and `/text` calls.
+- `select` takes whatever you have: it tries the `<option value="...">` attribute first, then falls back to exact (trimmed) visible text, then case-insensitive trimmed text. So `pinchtab select '#country' uk` and `pinchtab select '#country' 'United Kingdom'` both work; the form receives the real `value="uk"` in either case. If nothing matches, the server returns a clear error listing available options.
+- If a click opens a JS dialog (`alert`, `confirm`, `prompt`), pass `"dialogAction": "accept"` or `"dialogAction": "dismiss"` on the click action body — or `pinchtab click <selector> --dialog-action accept` from the CLI (use `--dialog-text <str>` to supply a prompt response). The dialog is auto-handled in a single call. Without this, the click hangs until `/tabs/TAB_ID/dialog` is called from a parallel request, and a pending dialog wedges subsequent `/snapshot` and `/text` calls.
- For the `scroll` action via HTTP, use `"scrollX"` / `"scrollY"` for pixel deltas, or `"selector"` to scroll an element into view. Example: `{"kind":"scroll","scrollY":1500}` or `{"kind":"scroll","selector":"#footer"}`. The `x`/`y` fields are target viewport coordinates, not scroll deltas.
- The download HTTP endpoint (`GET /download?url=...` or `GET /tabs/TAB_ID/download?url=...`) returns JSON `{contentType, data (base64), size, url}`, not raw bytes. Decode `data` with base64 to get the file. Only `http`/`https` URLs are allowed. Private/internal hosts are blocked unless listed in `security.downloadAllowedDomains`.
@@ -253,6 +277,7 @@ Use these only when the task explicitly requires them and safer commands are ins
```bash
pinchtab eval "document.title"
+pinchtab eval --await-promise "fetch('/api/me').then(r => r.json())"
pinchtab download <url> -o /tmp/pinchtab-download.bin
pinchtab upload /absolute/path/provided-by-user.ext -s <css>
```
@@ -329,6 +354,13 @@ curl -X POST http://localhost:9867/tabs/TAB_ID/action \
-H "Content-Type: application/json" \
-d '{"kind":"mouse-wheel","x":400,"y":320,"deltaY":240}'
+# Drag action: selector + pixel OFFSETS (dragX, dragY), not absolute endpoints.
+# For low-level absolute coords, sequence mouse-down / mouse-move / mouse-up.
+curl -X POST http://localhost:9867/tabs/TAB_ID/action \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"drag","selector":"#piece","dragX":12,"dragY":-158}'
+
# Navigate back/forward in a specific tab
curl -X POST http://localhost:9867/tabs/TAB_ID/back \
-H "Authorization: Bearer <token>"
@@ -451,9 +483,13 @@ pinchtab click "xpath://button[@type='submit']"
## Diffing and Verification
- Use `pinchtab snap -d` after each state-changing action in long workflows.
-- Use `pinchtab text` to confirm success messages, table updates, or navigation outcomes.
+- Use `pinchtab text` to confirm success messages, table updates, or navigation outcomes. The default mode extracts Readability-filtered content (reader view), which may drop navigation, repeated headlines, or short-text nodes. If the content you need is missing, retry with `pinchtab text --full` to get the full `document.body.innerText`.
- Use `pinchtab screenshot` only when visual regressions, CAPTCHA, or layout-specific confirmation matters.
- If a ref disappears after a change, treat that as expected and fetch fresh refs instead of retrying the stale one.
+- Action responses like `{"clicked":true,"submitted":true}` mean the event fired on the target element — **not** that the form was accepted by the server or passed native HTML validation. Always verify the expected success marker or state change via `snap`/`text` before treating a submission as complete.
+- `/action` selectors do not cross iframe boundaries. To interact with elements inside an `<iframe>`, use `eval` / `/evaluate` against `iframe.contentDocument` (e.g. `document.getElementById('my-frame').contentDocument.getElementById('inner-btn').click()`).
+- The compact snapshot shows `<option>` elements by their visible text, not their `value` attribute. You don't normally need to look up the `value`: the `select` action accepts either — it matches on `value` first and falls back to visible text (case-insensitive). Only reach for `eval` + `Array.from(select.options)` when debugging an unexpected no-match error.
+- `text:<value>` selectors are resolved by a JS-level search over visible text and can intermittently fail with `DOM Error` or `context deadline exceeded` on large/dynamic pages. If you have a fresh `snap -i -c` in hand, prefer the ref (`e12`) — refs resolve by stable backend node IDs and don't depend on page-side JS.
## References
diff --git a/skills/pinchtab/references/env.md b/skills/pinchtab/references/env.md
index ecf32766..cb3bc7ed 100644
--- a/skills/pinchtab/references/env.md
+++ b/skills/pinchtab/references/env.md
@@ -10,6 +10,7 @@ For agent workflows, most runtime behavior should be configured through `config.
|---|---|---|
| `PINCHTAB_TOKEN` | Authenticate CLI or MCP requests to a protected server | Sent as `Authorization: Bearer ...` |
| `PINCHTAB_CONFIG` | Override the config file path | Prefer this over ad hoc env overrides when automating |
+| `PINCHTAB_TAB` | Default tab ID for tab-scoped commands (`snap`, `eval`, `click`, `fill`, `drag`, etc.) | Used when `--tab` isn't passed explicitly. Lets agents `export PINCHTAB_TAB=$(pinchtab nav URL)` once and drop `--tab "$TAB"` from every subsequent command. |
## Targeting remote servers
@@ -33,6 +34,17 @@ For most agent tasks, the only variable you need is:
PINCHTAB_TOKEN=...
```
+For multi-step flows on a specific tab, also set `PINCHTAB_TAB` once after
+navigating so you don't have to thread `--tab` through every command:
+
+```bash
+export PINCHTAB_TOKEN=...
+export PINCHTAB_TAB=$(pinchtab nav http://example.com) # pipe → tabId only
+pinchtab snap -i -c # auto-targets $PINCHTAB_TAB
+pinchtab eval --await-promise "window.fetchPayload()"
+pinchtab click "#submit"
+```
+
Or use agent sessions for per-agent identity and revocability:
```bash