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.mdindex 48f03e22..a58be02d 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -144,11 +144,15 @@ pinchtab keyboard type <text> # Type at the focused elementpinchtab keyboard inserttext <text> # Insert text without key eventspinchtab keydown <key> # Hold a key downpinchtab 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 | networkidlepinchtab wait --fn <expression> # Wait for JS to become truthy+pinchtab wait ... --timeout <ms> # Override timeout (default 10000, max 30000)pinchtab network # List captured network requestspinchtab network <requestId> # Show one request in detailpinchtab network --stream # Stream network entriesdiff --git a/docs/endpoints.md b/docs/endpoints.mdindex de3c5caa..7055ebbe 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -407,10 +407,17 @@ POST /errors/clearWait 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.goindex 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 pageNotText string `json:"notText,omitempty"` // wait for text to disappear from pageURL 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 truthyMs *int `json:"ms,omitempty"` // fixed duration waitTimeout *int `json:"timeout,omitempty"` // timeout in ms@@ -209,13 +209,16 @@ func (h *Handlers) handleWaitCore(w http.ResponseWriter, r *http.Request, req wajs = buildURLMatchJS(req.URL)matchLabel = req.URLcase "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.Loadcase "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.goindex 7c37cfc9..d0d9b11a 100644--- a/internal/handlers/wait_test.go+++ b/internal/handlers/wait_test.go@@ -3,6 +3,7 @@ package handlersimport ("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.goindex 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.mdindex 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).```bashpinchtab wait <selector> # default: visible; --state hidden to wait for disappearpinchtab 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.shindex 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)"