High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: selector for text command and skill update
Luigi Agosti590f7d9af32d
diff --git a/cmd/pinchtab/cmd_cli_browser_inspect.go b/cmd/pinchtab/cmd_cli_browser_inspect.goindex e295037b..585a6adb 100644--- a/cmd/pinchtab/cmd_cli_browser_inspect.go+++ b/cmd/pinchtab/cmd_cli_browser_inspect.go@@ -59,11 +59,12 @@ var pdfCmd = &cobra.Command{}var textCmd = &cobra.Command{- Use: "text",+ Use: "text [selector]",Short: "Extract page text",+ Args: cobra.MaximumNArgs(1),Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {- browseractions.Text(rt.client, rt.base, rt.token, cmd)+ browseractions.Text(rt.client, rt.base, rt.token, cmd, args)})},}diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex f4d66d26..a68977be 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -198,6 +198,7 @@ func configureBrowserFlags() {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")textCmd.Flags().String("frame", "", "Extract text from a specific iframe by frameId. If unset, uses the tab's active frame scope (set via `pinchtab frame`) or the top-level document.")+ textCmd.Flags().StringP("selector", "s", "", "Element selector to extract text from (ref/CSS/XPath/text)")navCmd.Flags().Bool("new-tab", false, "Open in new tab")navCmd.Flags().Bool("block-images", false, "Block image loading")diff --git a/internal/cli/actions/actions_text.go b/internal/cli/actions/actions_text.goindex d1c1cb47..d2f51dac 100644--- a/internal/cli/actions/actions_text.go+++ b/internal/cli/actions/actions_text.go@@ -1,13 +1,15 @@package actionsimport (- "github.com/pinchtab/pinchtab/internal/cli/apiclient"- "github.com/spf13/cobra""net/http""net/url"++ "github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/selector"+ "github.com/spf13/cobra")-func Text(client *http.Client, base, token string, cmd *cobra.Command) {+func Text(client *http.Client, base, token string, cmd *cobra.Command, args []string) {params := url.Values{}// --full is the preferred, discoverable name; --raw is kept as a// backward-compatible alias. Both switch the server off its default@@ -29,5 +31,22 @@ func Text(client *http.Client, base, token string, cmd *cobra.Command) {if v, _ := cmd.Flags().GetString("frame"); v != "" {params.Set("frameId", v)}++ // Handle element selector - positional arg takes precedence over --selector flag+ selectorStr := ""+ if len(args) > 0 {+ selectorStr = args[0]+ } else if v, _ := cmd.Flags().GetString("selector"); v != "" {+ selectorStr = v+ }+ if selectorStr != "" {+ sel := selector.Parse(selectorStr)+ if sel.Kind == selector.KindRef {+ params.Set("ref", sel.Value)+ } else {+ params.Set("selector", selectorStr)+ }+ }+apiclient.DoGet(client, base, token, "/text", params)}diff --git a/internal/handlers/text.go b/internal/handlers/text.goindex e5acd1db..348c8b1b 100644--- a/internal/handlers/text.go+++ b/internal/handlers/text.go@@ -83,6 +83,29 @@ func (h *Handlers) HandleText(w http.ResponseWriter, r *http.Request) {}}+ // Handle element selector - extract text from specific element instead of full page+ selectorParam := r.URL.Query().Get("selector")+ refParam := r.URL.Query().Get("ref")+ if selectorParam != "" || refParam != "" {+ text, err := h.extractElementText(tCtx, resolvedTabID, selectorParam, refParam)+ if err != nil {+ httpx.Error(w, 500, fmt.Errorf("element text extract: %w", err))+ return+ }+ var url, title string+ _ = chromedp.Run(tCtx,+ chromedp.Location(&url),+ chromedp.Title(&title),+ )+ h.recordResolvedURL(r, url)+ httpx.JSON(w, 200, map[string]any{+ "url": url,+ "title": title,+ "text": text,+ })+ return+ }+script := `document.body.innerText`if mode != "raw" {script = assets.ReadabilityJS@@ -206,3 +229,79 @@ func (h *Handlers) HandleTabText(w http.ResponseWriter, r *http.Request) {h.HandleText(w, req)}++// extractElementText extracts innerText from a specific element by selector or ref.+func (h *Handlers) extractElementText(ctx context.Context, tabID, selector, ref string) (string, error) {+ var text string++ if ref != "" {+ cache := h.Bridge.GetRefCache(tabID)+ if cache == nil {+ return "", fmt.Errorf("ref not found: %s (no snapshot cache)", ref)+ }+ target, ok := cache.Lookup(ref)+ if !ok {+ return "", fmt.Errorf("ref not found: %s", ref)+ }+ nodeID := target.BackendNodeID++ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {+ var objRes struct {+ Object struct {+ ObjectID string `json:"objectId"`+ } `json:"object"`+ }+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.resolveNode", map[string]any{+ "backendNodeId": nodeID,+ }, &objRes); err != nil {+ return err+ }+ if objRes.Object.ObjectID == "" {+ return fmt.Errorf("could not resolve node")+ }+ var callRes struct {+ Result struct {+ Value string `json:"value"`+ } `json:"result"`+ }+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{+ "functionDeclaration": `function() { return this.innerText || this.textContent || ''; }`,+ "objectId": objRes.Object.ObjectID,+ "returnByValue": true,+ }, &callRes); err != nil {+ return err+ }+ text = callRes.Result.Value+ return nil+ }))+ if err != nil {+ return "", err+ }+ return text, nil+ }++ var script string+ switch {+ case strings.HasPrefix(selector, "xpath:"):+ xpath := selector[len("xpath:"):]+ script = fmt.Sprintf(`(function(){var r=document.evaluate(%q,document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null);var n=r.singleNodeValue;return n?(n.innerText||n.textContent||''):null})()`, xpath)+ case strings.HasPrefix(selector, "//") || strings.HasPrefix(selector, "(//"):+ script = fmt.Sprintf(`(function(){var r=document.evaluate(%q,document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null);var n=r.singleNodeValue;return n?(n.innerText||n.textContent||''):null})()`, selector)+ case strings.HasPrefix(selector, "text:"):+ textVal := selector[len("text:"):]+ script = fmt.Sprintf(`(function(){var w=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);while(w.nextNode()){if(w.currentNode.textContent.includes(%q))return w.currentNode.parentElement.innerText||w.currentNode.parentElement.textContent||''}return null})()`, textVal)+ case strings.HasPrefix(selector, "css:"):+ css := selector[len("css:"):]+ script = fmt.Sprintf(`(function(){var n=document.querySelector(%q);return n?(n.innerText||n.textContent||''):null})()`, css)+ default:+ script = fmt.Sprintf(`(function(){var n=document.querySelector(%q);return n?(n.innerText||n.textContent||''):null})()`, selector)+ }++ if err := chromedp.Run(ctx, chromedp.Evaluate(script, &text)); err != nil {+ return "", err+ }+ if text == "" {+ return "", fmt.Errorf("no element matches selector: %s", selector)+ }+ return text, nil+}diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex 26dfd688..bc23f1b4 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -37,15 +37,16 @@ Every PinchTab automation follows this pattern:1. Ensure the correct server, profile, or instance is available for the task.2. Navigate with `pinchtab nav <url>` or `pinchtab instance navigate <instance-id> <url>`.-3. Observe with `pinchtab snap -i -c`, `pinchtab snap --text`, or `pinchtab text`, then collect the current refs such as `e5`.+3. Observe with `pinchtab snap -i -c` (interactive refs, smaller), `pinchtab snap -c` (refs + body content), or `pinchtab text` (content only). Collect refs such as `e5`.4. Interact with those fresh refs using `click`, `fill`, `type`, `press`, `select`, `hover`, or `scroll`.5. Re-snapshot or re-read text after any navigation, submit, modal open, accordion expand, or other DOM-changing action.Rules:- Never act on stale refs after the page changes.-- Default to `pinchtab text` when you need content, not layout.-- Default to `pinchtab snap -i -c` when you need actionable elements.+- Default to `pinchtab snap -i -c` for most observations — it returns only interactive elements and is smaller/faster.+- Use `pinchtab snap -c` (no `-i`) only when you need **both** refs and body content in one call — e.g. verifying a success message after form submit.+- Default to `pinchtab text` when you need content only and won't act on refs from the same observation.- Use screenshots only for visual verification, UI diffs, or debugging.- Start multi-site or parallel work by choosing the right instance or profile first.@@ -157,6 +158,9 @@ pinchtab snap --text # Text output formatpinchtab 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 needpinchtab text --raw # Alias of --full+pinchtab text e5 # Extract text from element by ref+pinchtab text -s "#article" # Extract text from element by CSS selector+pinchtab text "xpath://div[@class='content']" # Extract text from element by XPath# CLI returns JSON; use `| jq -r .text` for plain textpinchtab find <query> # Semantic element searchpinchtab find --ref-only <query> # Return refs only@@ -164,9 +168,18 @@ pinchtab find --ref-only <query> # Return refs onlyGuidance:-- `snap -i -c` is the default for finding actionable refs.+- **`snap -i -c`** is the default for most observations. It returns only interactive elements+ (links, buttons, inputs, etc.) in compact form — smaller output, faster to parse.+ Use this after navigation, DOM changes, or when you need fresh refs to act on.+- **`snap -c` (no `-i`)** is for when you need refs **and** body content in one call.+ The compact output includes headings, paragraphs, and landmarks alongside interactive refs.+ Use this for verification steps ("did the success banner appear?") or initial page orientation+ when you need to read content and act in the same observation.- `snap -d` is the default follow-up snapshot for multi-step flows.-- `text` is the default for reading articles, dashboards, reports, or confirmation messages.+- `text` is the default for reading articles, dashboards, reports, or confirmation messages+ when you have no reason to act on refs from the same observation.+- `text <selector>` extracts text from a specific element — use it to read a single card,+ table cell, or status message without pulling the entire page.- **`pinchtab find <query>`** is the direct route when you already know the semantic target(e.g. "login button", "email input", "accept cookies link") — skips the full snapshot andreturns a ranked match with its ref. Pair with `--ref-only` on large/dense pages to get just@@ -291,7 +304,7 @@ Action examples:## Common Patterns-- **Form flow**: `nav` → `snap -i -c` → `fill` fields → `click --wait-nav` submit → `text` to verify+- **Form flow**: `nav` → `snap -i -c` (refs for form fields) → `fill` fields → `click --wait-nav` submit → `snap -i -c` + `text` or `snap -c` (to verify success message). Use `snap -c` only when you need refs and body content in the same call.- **Multi-step**: After each action, `snap -d -i -c` for diff- **Direct selectors**: Skip snapshot when structure is known: `pinchtab click "text:Accept Cookies"` or `fill "#search" "query"`@@ -299,7 +312,9 @@ Action examples:## Token Economy-Prefer low-token commands: `text`, `snap -i -c`, `snap -d`. Use `--block-images` for read-heavy tasks. Reserve screenshots/PDFs for visual verification.+Prefer low-token commands: `snap -i -c` (default), `text`, `snap -d`. Use `--block-images` for read-heavy tasks. Reserve screenshots/PDFs for visual verification.++**Always use `-i` with `snap`** unless you specifically need body content (headings, paragraphs) in the same call. Without `-i`, the full accessibility tree includes redundant StaticText nodes that inflate token usage.## Diffing and Verificationdiff --git a/tests/e2e/scenarios/cli/browser-basic.sh b/tests/e2e/scenarios/cli/browser-basic.shindex 1ec9448c..64ed9bab 100644--- a/tests/e2e/scenarios/cli/browser-basic.sh+++ b/tests/e2e/scenarios/cli/browser-basic.sh@@ -140,6 +140,33 @@ assert_output_contains "text" "returns text field"end_test+# ─────────────────────────────────────────────────────────────────+start_test "pinchtab text -s <selector>"++pt_ok nav "${FIXTURES_URL}/index.html"+pt_ok text -s "#welcome"+assert_output_json+assert_output_contains "Welcome" "extracts text from element"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab text <ref>"++pt_ok nav "${FIXTURES_URL}/index.html"+pt_ok snap -i -c+# Extract a ref from the snapshot (first link)+REF=$(echo "$PT_OUT" | safe_jq -r '.nodes[] | select(.role == "link") | .ref' | head -1)+if [ -n "$REF" ] && [ "$REF" != "null" ]; then+ pt_ok text "$REF"+ assert_output_json+ assert_output_contains "text" "returns text field for ref"+else+ echo -e " ${YELLOW}⚠${NC} Could not extract ref from snapshot, skipping"+fi++end_test+# ─────────────────────────────────────────────────────────────────# SKIP: text --raw outputs JSON instead of plain text# Bug: CLI sets mode=raw but not format=text