Skip to content

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

chore: improvement from agent loop discovery suggestion

Bosch8148c0aa29ee
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 7038dfaf..a1c1bd22 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -195,6 +195,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.")
navCmd.Flags().Bool("new-tab", false, "Open in new tab")
navCmd.Flags().Bool("block-images", false, "Block image loading")
diff --git a/internal/bridge/action_resolve.go b/internal/bridge/action_resolve.go
index ddf0e7e4..8c1b2157 100644
--- a/internal/bridge/action_resolve.go
+++ b/internal/bridge/action_resolve.go
@@ -18,6 +18,16 @@ type FrameElementMeta struct {
Src string `json:"src,omitempty"`
}
+// FrameExecutionContextID returns a Runtime.executionContextId that
+// evaluates in the given frame's document. Safe to call from other packages
+// that need to scope `Runtime.evaluate` / `Runtime.callFunctionOn` to a
+// frame (for example, the /text handler when a frame scope is active).
+// Passes frameID == "" through as a no-op (returns 0, nil) so callers can
+// fall back to the default top-level context without branching.
+func FrameExecutionContextID(ctx context.Context, frameID string) (int64, error) {
+ return frameExecutionContextID(ctx, frameID)
+}
+
func frameExecutionContextID(ctx context.Context, frameID string) (int64, error) {
if frameID == "" {
return 0, nil
diff --git a/internal/bridge/cdpops/element_ops.go b/internal/bridge/cdpops/element_ops.go
index 804fac13..a9b8ccaa 100644
--- a/internal/bridge/cdpops/element_ops.go
+++ b/internal/bridge/cdpops/element_ops.go
@@ -53,11 +53,18 @@ 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"`).
+// lookup. Strategies are tried in order; the first match wins:
+//
+// 1. Exact `<option value="...">` attribute.
+// 2. Exact (trimmed) visible text.
+// 3. Case-insensitive trimmed visible text.
+// 4. Case-insensitive substring of visible text (last resort).
+//
+// This lets callers pass whatever they have — the canonical `value` attr
+// ("uk"), the visible text they see in a snapshot ("United Kingdom"), or an
+// obvious shorthand ("Dark" → "Dark Mode"). The substring strategy is
+// deliberately permissive; if multiple options share a prefix the first one
+// in document order wins, so prefer exact forms when disambiguation matters.
//
// When the element isn't a <select> (no `.options` collection), behavior
// degrades to the original "set .value directly" path — preserves backward
@@ -118,6 +125,15 @@ func SelectByNodeID(ctx context.Context, nodeID int64, value string) error {
if ((opts[i].text || "").trim().toLowerCase() === lower) { match = opts[i]; matchedBy = "text-ci"; break; }
}
}
+ // 4. Case-insensitive substring of visible text (last resort).
+ // First match wins, so the user should prefer exact forms
+ // when options share a common prefix. This rescues natural
+ // shorthand like "Dark" matching the option "Dark Mode".
+ if (!match && lower.length > 0) {
+ for (var i = 0; i < opts.length; i++) {
+ if ((opts[i].text || "").trim().toLowerCase().indexOf(lower) !== -1) { match = opts[i]; matchedBy = "text-contains"; break; }
+ }
+ }
if (!match) {
return {
ok: false,
diff --git a/internal/cli/actions/actions_text.go b/internal/cli/actions/actions_text.go
index 0e7177b3..d1c1cb47 100644
--- a/internal/cli/actions/actions_text.go
+++ b/internal/cli/actions/actions_text.go
@@ -23,5 +23,11 @@ func Text(client *http.Client, base, token string, cmd *cobra.Command) {
if v, _ := cmd.Flags().GetString("tab"); v != "" {
params.Set("tabId", v)
}
+ // --frame lets a one-shot call target an iframe without having to go
+ // through the stateful /frame scope. If omitted, the handler falls back
+ // to the currently-scoped frame for the tab (set via `pinchtab frame`).
+ if v, _ := cmd.Flags().GetString("frame"); v != "" {
+ params.Set("frameId", v)
+ }
apiclient.DoGet(client, base, token, "/text", params)
}
diff --git a/internal/cli/actions/actions_text_test.go b/internal/cli/actions/actions_text_test.go
index 8a2fe4d9..5f34083a 100644
--- a/internal/cli/actions/actions_text_test.go
+++ b/internal/cli/actions/actions_text_test.go
@@ -12,6 +12,7 @@ func newTextCmd() *cobra.Command {
cmd.Flags().Bool("raw", false, "")
cmd.Flags().Bool("full", false, "")
cmd.Flags().String("tab", "", "")
+ cmd.Flags().String("frame", "", "")
return cmd
}
@@ -60,6 +61,19 @@ func TestTextFull(t *testing.T) {
}
}
+func TestTextFrame(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+ client := m.server.Client()
+
+ cmd := newTextCmd()
+ _ = cmd.Flags().Set("frame", "FRAME123")
+ Text(client, m.base(), "", cmd)
+ if !strings.Contains(m.lastQuery, "frameId=FRAME123") {
+ t.Errorf("expected frameId=FRAME123, got %s", m.lastQuery)
+ }
+}
+
func TestTextTab(t *testing.T) {
m := newMockServer()
defer m.close()
diff --git a/internal/handlers/text.go b/internal/handlers/text.go
index baeb2c5e..e5acd1db 100644
--- a/internal/handlers/text.go
+++ b/internal/handlers/text.go
@@ -2,6 +2,7 @@ package handlers
import (
"context"
+ "encoding/json"
"fmt"
"net/http"
"strconv"
@@ -9,6 +10,7 @@ import (
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/assets"
+ "github.com/pinchtab/pinchtab/internal/bridge"
"github.com/pinchtab/pinchtab/internal/engine"
"github.com/pinchtab/pinchtab/internal/httpx"
)
@@ -71,21 +73,65 @@ func (h *Handlers) HandleText(w http.ResponseWriter, r *http.Request) {
defer tCancel()
go httpx.CancelOnClientDone(r.Context(), tCancel)
+ // Resolve the target frame. Explicit ?frameId= wins; otherwise fall back
+ // to the currently-scoped frame on this tab (as set by /frame). Empty
+ // means "top-level document" and preserves the prior behaviour.
+ targetFrameID := r.URL.Query().Get("frameId")
+ if targetFrameID == "" {
+ if scope, ok := h.currentFrameScope(resolvedTabID); ok {
+ targetFrameID = scope.FrameID
+ }
+ }
+
+ script := `document.body.innerText`
+ if mode != "raw" {
+ script = assets.ReadabilityJS
+ }
+
var text string
- if mode == "raw" {
- if err := chromedp.Run(tCtx,
- chromedp.Evaluate(`document.body.innerText`, &text),
- ); err != nil {
+ if targetFrameID == "" {
+ // Top-frame path — keep the ergonomic chromedp.Evaluate helper.
+ if err := chromedp.Run(tCtx, chromedp.Evaluate(script, &text)); err != nil {
httpx.Error(w, 500, fmt.Errorf("text extract: %w", err))
return
}
} else {
- if err := chromedp.Run(tCtx,
- chromedp.Evaluate(assets.ReadabilityJS, &text),
- ); err != nil {
- httpx.Error(w, 500, fmt.Errorf("text extract: %w", err))
+ // Frame-scoped path — evaluate in the frame's isolated world so the
+ // expression sees the iframe's `document`, not the parent's.
+ execID, err := bridge.FrameExecutionContextID(tCtx, targetFrameID)
+ if err != nil {
+ httpx.Error(w, 500, fmt.Errorf("resolve frame context: %w", err))
+ return
+ }
+ var raw json.RawMessage
+ err = chromedp.Run(tCtx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.evaluate", map[string]any{
+ "expression": script,
+ "returnByValue": true,
+ "contextId": execID,
+ }, &raw)
+ }))
+ if err != nil {
+ httpx.Error(w, 500, fmt.Errorf("text extract (frame %s): %w", targetFrameID, err))
+ return
+ }
+ var er struct {
+ Result struct {
+ Value string `json:"value"`
+ } `json:"result"`
+ ExceptionDetails *struct {
+ Text string `json:"text"`
+ } `json:"exceptionDetails,omitempty"`
+ }
+ if err := json.Unmarshal(raw, &er); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("text extract parse: %w", err))
+ return
+ }
+ if er.ExceptionDetails != nil && er.ExceptionDetails.Text != "" {
+ httpx.Error(w, 500, fmt.Errorf("text extract (frame %s): %s", targetFrameID, er.ExceptionDetails.Text))
return
}
+ text = er.Result.Value
}
truncated := false
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 38f29a0b..d3238306 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -170,9 +170,10 @@ pinchtab nav <url> --print-tab-id # Print only the new tabId o
pinchtab back # Navigate back in history
pinchtab forward # Navigate forward
pinchtab reload # Reload current page
-pinchtab tab # List tabs or focus by ID
-pinchtab tab new <url>
-pinchtab tab close <tab-id>
+pinchtab tab # List tabs
+pinchtab tab <tab-id> # Focus an existing tab
+pinchtab tab new <url> # Open a new tab
+pinchtab tab close <tab-id> # Close a tab — use this to clean up stale tabs between runs
pinchtab instance navigate <instance-id> <url>
```
@@ -255,7 +256,7 @@ 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.
-- `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.
+- `select` takes whatever you have: it tries the `<option value="...">` attribute first, then exact (trimmed) visible text, then case-insensitive trimmed text, then case-insensitive substring of visible text (last resort, first match wins). So `pinchtab select '#country' uk`, `pinchtab select '#country' 'United Kingdom'`, and `pinchtab select '#theme' 'Dark'` (matches option "Dark Mode") all work; the form receives the real `value=...` attr in every case. If nothing matches, the server returns a clear error listing available options. Prefer exact forms when multiple options share a prefix.
- 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`.
@@ -483,13 +484,17 @@ 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. 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 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, short-text nodes, or collapse lists/grids down to a single representative item. Reach for `pinchtab text --full` whenever (a) you're verifying content on a list/grid/tab/accordion page, (b) the expected marker is short, or (c) a default read came back missing content you can see in the snapshot. It returns the raw `document.body.innerText` and is almost always the safer choice once you know Readability is going to trim.
- 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()`).
+- **Same-origin iframes** are supported natively via `pinchtab frame <target>` — a stateful scope that subsequent selector-based `/snapshot` and `/action` calls inherit. Typical flow: `pinchtab frame '#payment-frame'` → `pinchtab snap -i -c` (refs reflect iframe interior) → `pinchtab fill '#card'` / `click '#pay'` → `pinchtab frame main`. Target accepts `main`, an iframe ref, a CSS selector for the iframe element, a frame name, or a frame URL. Nested iframes need multiple hops. Refs emitted by a full `snap` (no `-i`) for iframe descendants carry frame context — ref-based actions work across the boundary without an explicit scope set. **Cross-origin iframes** are not exposed as frame scopes; fall back to `eval` against `iframe.contentDocument` (same-origin-policy permitting). `pinchtab text` (and `text --full`) honors the active frame scope and also accepts an explicit `--frame <frameId>` flag for one-shot reads — so after `pinchtab frame '#content-frame'`, a following `pinchtab text --full` extracts from the iframe's document, not the outer page.
+- `eval` expressions share the same realm across successive calls, so a top-level `const`/`let` from one call collides with the next (`SyntaxError: Identifier already declared`). Wrap multi-statement expressions in an IIFE so the bindings don't leak: `pinchtab eval "(() => { const r = document.querySelector('#x').getBoundingClientRect(); return {x: r.x, y: r.y, w: r.width, h: r.height}; })()"`. This also fixes the DOMRect case where `getBoundingClientRect()` returns a value whose own-enumerable fields don't survive JSON serialization — the explicit projection makes the result stable.
- 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.
+- `snap -i -c` (interactive, compact) skips non-interactive descendants. For iframe interiors, either set a `frame` scope first or use a full `pinchtab snap` (no `-i`) which flattens same-origin iframe descendants into the parent snapshot.
+- ARIA expansion state (`aria-expanded="true" | "false"`) is usually placed on the **outermost container** of an accordion/menu/disclosure section, not on the header/trigger that dispatches the click. When verifying state after a click, query `document.querySelector('#section-a').getAttribute('aria-expanded')` (or the wrapper's equivalent) rather than the clicked element.
+- `click --wait-nav` can return `{"success": true}` or, immediately after the navigation fires, `Error 409: unexpected page navigation` — the latter means the server saw a navigation while mid-response and aborted its reply, not that the click failed. Treat 409 after a navigation-expected click as success and verify the resulting page with a fresh `snap` / `text`.
## References