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.goindex 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.goindex 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, nildiff --git a/internal/bridge/cdpops/element_ops.go b/internal/bridge/cdpops/element_ops.goindex 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.goindex 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.goindex 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.goindex baeb2c5e..e5acd1db 100644--- a/internal/handlers/text.go+++ b/internal/handlers/text.go@@ -2,6 +2,7 @@ package handlersimport ("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 := falsediff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex 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 opinchtab back # Navigate back in historypinchtab forward # Navigate forwardpinchtab 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 runspinchtab 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