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.goindex 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.goindex f5f18a3b..e7cf30df 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -1,6 +1,8 @@package mainimport (+ "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.goindex 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[strinif 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.goindex 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.goindex 8e2185f7..804fac13 100644--- a/internal/bridge/cdpops/element_ops.go+++ b/internal/bridge/cdpops/element_ops.go@@ -3,6 +3,7 @@ package cdpopsimport ("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.goindex 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 *cobif 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.goindex 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.goindex 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.goindex 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.goindex 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.Coif 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.goindex 9fe92692..939d7307 100644--- a/internal/cli/actions/actions_navigate_test.go+++ b/internal/cli/actions/actions_navigate_test.go@@ -2,6 +2,7 @@ package actionsimport ("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.goindex 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.goindex 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.goindex 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) mapos.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[sos.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 suggestionsvar result map[string]anyif 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[sreturn 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[stringos.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.mdindex 4053c7d0..38f29a0b 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -166,6 +166,7 @@ pinchtab nav <url> --new-tabpinchtab nav <url> --tab <tab-id>pinchtab nav <url> --block-imagespinchtab nav <url> --block-ads+pinchtab nav <url> --print-tab-id # Print only the new tabId on stdoutpinchtab back # Navigate back in historypinchtab forward # Navigate forwardpinchtab 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 snapshopinchtab snap --selector <css> # Scope to CSS selectorpinchtab snap --max-tokens <n> # Token budget limitpinchtab 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 --fullpinchtab find <query> # Semantic element searchpinchtab find --ref-only <query> # Return refs only```@@ -207,6 +226,10 @@ All interaction commands accept unified selectors (refs, CSS, XPath, text, semanpinchtab click <selector> # Click elementpinchtab click --wait-nav <selector> # Click and wait for navigationpinchtab 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 responsepinchtab dblclick <selector> # Double-click elementpinchtab mouse move <selector> # Move pointer to element centerpinchtab mouse move <x> <y> # Move pointer to coordinates@@ -215,13 +238,14 @@ pinchtab mouse down --button left # Press a mouse button at cupinchtab mouse up <selector> --button left # Release a mouse button at an explicit targetpinchtab mouse up --button left # Release a mouse button at current pointerpinchtab 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 keystrokespinchtab fill <selector> <text> # Set value directlypinchtab 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```bashpinchtab eval "document.title"+pinchtab eval --await-promise "fetch('/api/me').then(r => r.json())"pinchtab download <url> -o /tmp/pinchtab-download.binpinchtab 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 tabcurl -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.## Referencesdiff --git a/skills/pinchtab/references/env.md b/skills/pinchtab/references/env.mdindex 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