Skip to content

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.go
index 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.go
index 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.go
index d1c1cb47..d2f51dac 100644
--- a/internal/cli/actions/actions_text.go
+++ b/internal/cli/actions/actions_text.go
@@ -1,13 +1,15 @@
package actions
import (
- "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.go
index 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.md
index 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 format
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 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 text
pinchtab find <query> # Semantic element search
pinchtab find --ref-only <query> # Return refs only
@@ -164,9 +168,18 @@ pinchtab find --ref-only <query> # Return refs only
Guidance:
-- `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 and
returns 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 Verification
diff --git a/tests/e2e/scenarios/cli/browser-basic.sh b/tests/e2e/scenarios/cli/browser-basic.sh
index 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