Skip to content

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

docs: fixes for the optimizations changes

Luigi Agostia31f4160ce4a
diff --git a/docs/commands.md b/docs/commands.md
index 62bf2d5c..b56c1157 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -114,7 +114,9 @@ pinchtab snap --max-tokens <n> # Limit token budget
pinchtab snap --depth <n> # Limit tree depth
pinchtab snap --text # Text output
pinchtab text # Extract readable text
+pinchtab text --full # Full page innerText
pinchtab text --raw # Raw extraction
+pinchtab text --frame <frameId> # Read text from one iframe
pinchtab find <query> # Semantic element search
pinchtab find --threshold <0-1> # Minimum similarity score
pinchtab find --explain # Include score breakdown
@@ -122,7 +124,13 @@ pinchtab find --ref-only # Print only the best ref
pinchtab eval <expression> # Evaluate JavaScript
```
-`pinchtab eval` is intentionally not frame-scoped. Current `pinchtab frame` state affects selector-based commands such as `snap`, `click`, `fill`, and `type`, but not arbitrary JavaScript evaluation.
+`pinchtab eval` is intentionally not frame-scoped. Current `pinchtab frame`
+state affects selector-based commands such as `snap`, `click`, `fill`, and
+`type`, and it also affects `text` when `--frame` is not provided explicitly.
+
+Selector-based actions now fail fast when a selector does not match. If the UI
+is still loading, use `pinchtab wait` first instead of relying on action
+timeouts.
## Keyboard, Wait, And Diagnostics
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 07a339f2..e4317747 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -201,8 +201,16 @@ Text query parameters:
- `mode=raw`
- `format`
+- `maxChars`
+- `frameId`
-`/text` default mode picks the first **visible** `<article>` / `[role="main"]` / `<main>` (skips `display:none`) and strips nav/footer/ads. Use `mode=raw` for full `innerText`, or `/snapshot` for structured UI text like prices and button labels.
+`/text` default mode picks the first **visible** `<article>` / `[role="main"]` /
+`<main>` (skips `display:none`) and strips nav/footer/ads. Use `mode=raw` for
+full `innerText`, or `/snapshot` for structured UI text like prices and button
+labels.
+
+`/text` is also frame-aware. `frameId` targets a specific iframe for a one-shot
+read; otherwise the endpoint inherits the tab's current `/frame` scope.
Find body fields:
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 18e8f019..a8e7d4f9 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -100,7 +100,7 @@ Common commands:
| `pinchtab drag <from> <to>` | Drag from one target to another |
| `pinchtab type <selector> <text>` | Type via key events |
| `pinchtab fill <selector> <text>` | Fill directly |
-| `pinchtab text` | Extract page text |
+| `pinchtab text` | Extract page text (`--full`, `--raw`, `--frame <frameId>`) |
| `pinchtab find <query>` | Semantic element search |
| `pinchtab screenshot` | Save a screenshot |
| `pinchtab pdf` | Export the page as PDF |
@@ -113,8 +113,14 @@ Many browser commands accept `--tab <id>` to target an existing tab instead of t
Selector lookup is explicit by frame. Unscoped selectors stay in the main document unless you set a frame first with `pinchtab frame`. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.
+`pinchtab text` follows that frame model too: it uses the active frame scope
+unless you override it with `--frame`.
+
`pinchtab eval` is separate from that model and does not inherit current frame scope.
+Selector-based actions fail fast when a selector does not match. If you expect
+dynamic content to appear shortly, use `pinchtab wait` first.
+
Manual handoff is currently API-only:
This is currently advisory state only. It marks the tab as `paused_handoff`, but it does not yet provide a guaranteed blocking pause for later automation.
diff --git a/docs/reference/click.md b/docs/reference/click.md
index bcd1fbc1..57e4feb3 100644
--- a/docs/reference/click.md
+++ b/docs/reference/click.md
@@ -23,6 +23,9 @@ Notes:
- refs returned for iframe descendants can be clicked directly; no manual frame switch is required
- selector lookup is limited to the current frame scope; the default scope is `main`
- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe actions
+- missing selectors now fail immediately with `element not found: ...`; if you
+ want wait semantics for dynamic UI, use [`pinchtab wait`](./wait.md) or
+ `/wait` before the click
- the raw action endpoint also accepts `selector`, for example `{"kind":"click","selector":"#login"}`
- the CLI also accepts `#login`, `xpath://button`, `text:Submit`, and `find:login button`
- `--wait-nav` exists on the top-level CLI command
diff --git a/docs/reference/fill.md b/docs/reference/fill.md
index 28cf5af3..ef618c4f 100644
--- a/docs/reference/fill.md
+++ b/docs/reference/fill.md
@@ -23,6 +23,9 @@ Notes:
- refs returned for iframe descendants can be filled directly; no manual frame switch is required
- selector lookup is limited to the current frame scope; the default scope is `main`
- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe fills
+- missing selectors now fail immediately with `element not found: ...`; use
+ [`pinchtab wait`](./wait.md) or `/wait` first when the field is expected to
+ appear asynchronously
- for the raw HTTP action endpoint, use `selector` for CSS, XPath, text, or semantic selectors
## Related Pages
diff --git a/docs/reference/frame.md b/docs/reference/frame.md
index e9782f0c..fcd84f7a 100644
--- a/docs/reference/frame.md
+++ b/docs/reference/frame.md
@@ -46,7 +46,7 @@ Notes:
- selector scope is explicit; unscoped selectors do not automatically pierce into iframes
- same-origin iframe content is supported; cross-origin iframe descendants are not currently exposed as frame scopes
- nested iframes usually require multiple `frame` hops
-- the same frame scope applies to selector-based `/snapshot` and `/action` calls
+- the same frame scope applies to selector-based `/snapshot` and `/action` calls, and also to `/text` when `frameId` is not provided explicitly
- `/evaluate` is separate and does not inherit frame scope
## Related Pages
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index 026a89bb..919660e9 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -21,7 +21,7 @@ Selector forms include:
| `pinchtab_navigate` | `url` required, `tabId` optional | Uses `/navigate`; omitting `tabId` opens a new tab |
| `pinchtab_snapshot` | `tabId`, `interactive`, `compact`, `format`, `diff`, `selector`, `maxTokens`, `depth`, `noAnimations` | `selector` scopes the snapshot; `format` is limited to `compact` or `text` |
| `pinchtab_screenshot` | `tabId`, `format`, `quality` | `format` is `jpeg` or `png` |
-| `pinchtab_get_text` | `tabId`, `raw`, `format`, `maxChars` | `raw=true` maps to `/text?mode=raw`; `format=text/plain` returns plain text |
+| `pinchtab_get_text` | `tabId`, `raw`, `format`, `maxChars` | `raw=true` maps to `/text?mode=raw`; `format=text/plain` returns plain text; inherits the current `pinchtab_frame` scope for that tab |
## Interaction
@@ -32,7 +32,7 @@ Selector forms include:
| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |
| `pinchtab_hover` | `selector` required, `tabId`, `ref` | Hover element |
| `pinchtab_focus` | `selector` required, `tabId`, `ref` | Focus element |
-| `pinchtab_select` | `selector` required, `value` required, `tabId`, `ref` | Select `<option>` by value |
+| `pinchtab_select` | `selector` required, `value` required, `tabId`, `ref` | Select `<option>` by value or visible text |
| `pinchtab_scroll` | `selector`, `pixels`, `tabId`, `ref` | Omit `selector` to scroll the page |
| `pinchtab_fill` | `selector` required, `value` required, `tabId`, `ref` | Direct fill instead of keystrokes |
diff --git a/docs/reference/select.md b/docs/reference/select.md
index b276ce32..49b5c5f5 100644
--- a/docs/reference/select.md
+++ b/docs/reference/select.md
@@ -1,6 +1,6 @@
# Select
-Choose a value in a select element by selector or ref.
+Choose an option in a native `<select>` element by selector or ref.
```bash
curl -X POST http://localhost:9867/action \
@@ -17,7 +17,25 @@ pinchtab select e12 it
}
```
-The `value` should match the option value expected by the page. The raw action endpoint accepts `ref` or `selector`, and the CLI accepts the same unified selector forms as the other action commands.
+Matching is forgiving. PinchTab tries these strategies in order:
+
+1. exact `<option value="...">`
+2. exact visible text
+3. case-insensitive visible text
+4. case-insensitive substring of visible text
+
+That means all of these can work depending on the page:
+
+```bash
+pinchtab select e12 uk
+pinchtab select e12 "United Kingdom"
+pinchtab select e12 "united kingdom"
+pinchtab select e12 "Kingdom"
+```
+
+Prefer the canonical option value or the full visible text when disambiguation
+matters. The raw action endpoint accepts `ref` or `selector`, and the CLI
+accepts the same unified selector forms as the other action commands.
Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe selects.
diff --git a/docs/reference/text.md b/docs/reference/text.md
index f61ede28..9cf26adc 100644
--- a/docs/reference/text.md
+++ b/docs/reference/text.md
@@ -1,6 +1,15 @@
# Text
-Extract readable text from the current page. Use raw mode when you want `innerText` instead of readability-style extraction.
+Extract text from the current page.
+
+By default, PinchTab runs a Readability-style extraction against the current
+document. Use full/raw mode when you want `document.body.innerText` instead.
+
+`/text` is frame-aware:
+
+- `frameId=<id>` targets a specific iframe for a one-shot read
+- otherwise, `/text` inherits the tab's current frame scope from [`/frame`](./frame.md)
+- if no frame is selected, `/text` reads from the top-level document
```bash
curl "http://localhost:9867/text?mode=raw"
@@ -17,10 +26,31 @@ pinchtab text --raw
Useful flags:
-- CLI: `--raw`
-- API query: `mode=raw`, `maxChars`, `format=text`
+- CLI: `--full`, `--raw`, `--frame <frameId>`
+- API query: `mode=raw`, `maxChars`, `format=text`, `frameId=<frameId>`
+
+Examples:
+
+```bash
+# Default Readability extraction
+pinchtab text
+
+# Full page text (same behavior as --raw)
+pinchtab text --full
+
+# One-shot iframe read by frame id
+pinchtab text --frame FRAME123
+
+# HTTP form of the same idea
+curl "http://localhost:9867/text?frameId=FRAME123&format=text"
+```
+
+Use default mode for article-like pages. Use `--full` / `mode=raw` for UI-heavy
+pages such as dashboards, SERPs, grids, pricing tables, or short log panes that
+Readability may trim away.
## Related Pages
- [Snapshot](./snapshot.md)
+- [Frame](./frame.md)
- [PDF](./pdf.md)
diff --git a/docs/reference/type.md b/docs/reference/type.md
index 47f16a3e..a817a199 100644
--- a/docs/reference/type.md
+++ b/docs/reference/type.md
@@ -23,6 +23,9 @@ Notes:
- the top-level CLI accepts unified selector forms such as `e8`, `#name`, `xpath://input`, or `text:Name`
- selector lookup is limited to the current frame scope; the default scope is `main`
- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe typing
+- missing selectors now fail immediately with `element not found: ...`; use
+ [`pinchtab wait`](./wait.md) or `/wait` first when the field is expected to
+ appear asynchronously
- for typing without a target element (into whatever is focused), use `keyboard type`
## Related Pages
diff --git a/internal/handlers/openapi.go b/internal/handlers/openapi.go
index a5868652..f1373e61 100644
--- a/internal/handlers/openapi.go
+++ b/internal/handlers/openapi.go
@@ -48,7 +48,7 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
"/tabs/{id}/resume": map[string]any{"post": map[string]any{"summary": "Resume tab automation after handoff"}},
"/metrics": map[string]any{"get": map[string]any{"summary": "Runtime metrics"}},
"/help": map[string]any{"get": map[string]any{"summary": "Alias for /openapi.json"}},
- "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}}}},
+ "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}, {"name": "mode", "in": "query", "schema": map[string]string{"type": "string"}}, {"name": "frameId", "in": "query", "schema": map[string]string{"type": "string"}}}}},
"/navigate": map[string]any{"post": map[string]any{"summary": "Navigate"}, "get": map[string]any{"summary": "Navigate (query params)"}},
"/nav": map[string]any{"get": map[string]any{"summary": "Navigate alias"}},
"/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index e0d64e44..2dd17e1c 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -35,7 +35,7 @@ func allTools() []mcp.Tool {
mcp.WithNumber("quality", mcp.Description("JPEG quality 0-100 (only for JPEG format)")),
),
mcp.NewTool("pinchtab_get_text",
- mcp.WithDescription("Extract readable text content from the current page"),
+ mcp.WithDescription("Extract readable text content from the current page. Inherits the current frame scope for the tab unless no frame is selected."),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
mcp.WithBoolean("raw", mcp.Description("Return raw text without formatting")),
mcp.WithString("format", mcp.Description("Response format: 'text'/'plain' for plain text, default JSON envelope")),
@@ -75,10 +75,10 @@ func allTools() []mcp.Tool {
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
mcp.NewTool("pinchtab_select",
- mcp.WithDescription("Select a dropdown option by value"),
+ mcp.WithDescription("Select a dropdown option by value or visible text"),
mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector for the select element. Non-ref selectors resolve in the current frame scope.")),
mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
- mcp.WithString("value", mcp.Required(), mcp.Description("Option value to select")),
+ mcp.WithString("value", mcp.Required(), mcp.Description("Option value or visible text to select")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
mcp.NewTool("pinchtab_scroll",