Skip to content

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

chore: improve wait and docs

Luigi Agosti395725fa5cdc
diff --git a/docs/commands.md b/docs/commands.md
index 48f03e22..a58be02d 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -144,11 +144,15 @@ pinchtab keyboard type <text> # Type at the focused element
pinchtab keyboard inserttext <text> # Insert text without key events
pinchtab keydown <key> # Hold a key down
pinchtab keyup <key> # Release a key
-pinchtab wait <selector|ms> # Wait for selector or fixed duration
-pinchtab wait --text <text> # Wait for page text
-pinchtab wait --url <glob> # Wait for URL match
-pinchtab wait --load networkidle # Wait for load state
+pinchtab wait <selector> # Wait for selector to be visible
+pinchtab wait <selector> --state hidden # Wait for selector to disappear
+pinchtab wait <ms> # Fixed duration sleep (escape hatch; max 30000ms — prefer condition-based waits)
+pinchtab wait --text <text> # Wait for page text to appear
+pinchtab wait --not-text <text> # Wait for page text to disappear
+pinchtab wait --url <glob> # Wait for URL match (glob: **, *, ?)
+pinchtab wait --load <state> # state: load | domcontentloaded | networkidle
pinchtab wait --fn <expression> # Wait for JS to become truthy
+pinchtab wait ... --timeout <ms> # Override timeout (default 10000, max 30000)
pinchtab network # List captured network requests
pinchtab network <requestId> # Show one request in detail
pinchtab network --stream # Stream network entries
diff --git a/docs/endpoints.md b/docs/endpoints.md
index de3c5caa..7055ebbe 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -407,10 +407,17 @@ POST /errors/clear
Wait body fields:
-- one of `selector`, `text`, `url`, `load`, `fn`, or `ms`
+- exactly one of:
+ - `selector` — CSS / XPath (`xpath:` prefix or leading `//`) / text (`text:` prefix)
+ - `text` — substring of `document.body.innerText`
+ - `notText` — wait until substring is no longer present
+ - `url` — glob pattern matched against `window.location.href` (`**`, `*`, `?`)
+ - `load` — one of `load`, `domcontentloaded`, `networkidle`
+ - `fn` — JS expression polled until truthy (requires `security.allowEvaluate`)
+ - `ms` — fixed sleep in milliseconds, max 30000 (escape hatch; prefer condition-based waits)
- optional `tabId`
-- optional `timeout`
-- optional `state` for selector waits
+- optional `timeout` — ms, default 10000, clamped 100–30000
+- optional `state` for selector waits — `visible` (default) or `hidden`
Network query parameters:
diff --git a/internal/handlers/wait.go b/internal/handlers/wait.go
index 66666cd9..d2b27474 100644
--- a/internal/handlers/wait.go
+++ b/internal/handlers/wait.go
@@ -30,7 +30,7 @@ type waitRequest struct {
Text string `json:"text,omitempty"` // wait for text on page
NotText string `json:"notText,omitempty"` // wait for text to disappear from page
URL string `json:"url,omitempty"` // wait for URL glob match
- Load string `json:"load,omitempty"` // "networkidle"
+ Load string `json:"load,omitempty"` // "load" | "domcontentloaded" | "networkidle"
Fn string `json:"fn,omitempty"` // JS expression to poll for truthy
Ms *int `json:"ms,omitempty"` // fixed duration wait
Timeout *int `json:"timeout,omitempty"` // timeout in ms
@@ -209,13 +209,16 @@ func (h *Handlers) handleWaitCore(w http.ResponseWriter, r *http.Request, req wa
js = buildURLMatchJS(req.URL)
matchLabel = req.URL
case "load":
- if req.Load == "networkidle" {
+ switch req.Load {
+ case "load", "networkidle":
js = `document.readyState === 'complete'`
- matchLabel = "networkidle"
- } else {
- httpx.Error(w, 400, fmt.Errorf("unsupported load state: %s (supported: networkidle)", req.Load))
+ case "domcontentloaded":
+ js = `document.readyState === 'interactive' || document.readyState === 'complete'`
+ default:
+ httpx.Error(w, 400, fmt.Errorf("unsupported load state: %s (supported: load, domcontentloaded, networkidle)", req.Load))
return
}
+ matchLabel = req.Load
case "fn":
js = fmt.Sprintf(`!!(function(){try{return %s}catch(e){return false}})()`, req.Fn)
matchLabel = "fn"
diff --git a/internal/handlers/wait_test.go b/internal/handlers/wait_test.go
index 7c37cfc9..d0d9b11a 100644
--- a/internal/handlers/wait_test.go
+++ b/internal/handlers/wait_test.go
@@ -3,6 +3,7 @@ package handlers
import (
"bytes"
"encoding/json"
+ "fmt"
"net/http/httptest"
"testing"
@@ -231,12 +232,17 @@ func TestHandleWait_SelectorNotBlockedByEvaluateSetting(t *testing.T) {
}
func TestHandleWait_LoadNoTab(t *testing.T) {
- h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
- req := httptest.NewRequest("POST", "/wait", bytes.NewReader([]byte(`{"load":"networkidle"}`)))
- w := httptest.NewRecorder()
- h.HandleWait(w, req)
- if w.Code != 404 {
- t.Errorf("expected 404, got %d: %s", w.Code, w.Body.String())
+ for _, state := range []string{"networkidle", "load", "domcontentloaded"} {
+ t.Run(state, func(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ body := fmt.Sprintf(`{"load":%q}`, state)
+ req := httptest.NewRequest("POST", "/wait", bytes.NewReader([]byte(body)))
+ w := httptest.NewRecorder()
+ h.HandleWait(w, req)
+ if w.Code != 404 {
+ t.Errorf("expected 404, got %d: %s", w.Code, w.Body.String())
+ }
+ })
}
}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index c8184e4f..be369a4c 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -217,8 +217,8 @@ func allTools() []mcp.Tool {
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
mcp.NewTool("pinchtab_wait_for_load",
- mcp.WithDescription("Wait for a page load state (e.g. networkidle)"),
- mcp.WithString("load", mcp.Required(), mcp.Description("Load state to wait for: 'networkidle'")),
+ mcp.WithDescription("Wait for a page load state"),
+ mcp.WithString("load", mcp.Required(), mcp.Description("Load state to wait for: 'load', 'domcontentloaded', or 'networkidle'")),
mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
),
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 03b93e59..49350e19 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -156,8 +156,10 @@ Use for async DOM settling (spinners, toasts, XHR).
```bash
pinchtab wait <selector> # default: visible; --state hidden to wait for disappear
pinchtab wait --text "..." | --not-text "..." # text appear / disappear
-pinchtab wait --url "**/dashboard" | --load networkidle
-pinchtab wait 500 # fixed ms delay (last resort)
+pinchtab wait --url "**/dashboard" # glob: **, *, ?
+pinchtab wait --load load|domcontentloaded|networkidle
+pinchtab wait --fn "window.dataReady === true" # requires security.allowEvaluate
+pinchtab wait 500 # fixed ms delay (last resort, max 30000ms)
```
Timeout 10s default, 30s max via `--timeout <ms>`. Prefer `--not-text`/`--state hidden` over polling.
diff --git a/tests/e2e/scenarios/api/browser-extended.sh b/tests/e2e/scenarios/api/browser-extended.sh
index 822a384b..995c6549 100644
--- a/tests/e2e/scenarios/api/browser-extended.sh
+++ b/tests/e2e/scenarios/api/browser-extended.sh
@@ -301,6 +301,32 @@ assert_json_eq "$RESULT" '.waited' 'false' "waited=false on timeout"
end_test
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /wait: load states (load, domcontentloaded, networkidle)"
+
+pt_post /navigate "{\"url\":\"${FIXTURES_URL}/buttons.html\"}"
+assert_ok "navigate before load-state checks"
+
+# Navigation has already settled, so each state should resolve on the
+# first poll. This exercises the handler's load-state mapping rather
+# than the timing of a fresh page load.
+for state in load domcontentloaded networkidle; do
+ pt_post /wait "{\"load\":\"${state}\",\"timeout\":5000}"
+ assert_ok "wait --load ${state}"
+ assert_json_eq "$RESULT" '.waited' 'true' "waited=true for ${state}"
+ assert_json_eq "$RESULT" '.match' "\"${state}\"" "match label echoes ${state}"
+done
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /wait: rejects unknown load state"
+
+pt_post /wait '{"load":"bogus"}'
+assert_http_status "400" "rejects unknown load state"
+
+end_test
+
# ─────────────────────────────────────────────────────────────────
start_test "POST /wait: invalid request (empty body)"