High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: real CDP network-idle and explicit load-state names
Luigi Agostifde4bed9239f
diff --git a/docs/commands.md b/docs/commands.mdindex a58be02d..43697cf2 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -150,7 +150,10 @@ pinchtab wait <ms> # Fixed duration sleep (escape hatch; mapinchtab wait --text <text> # Wait for page text to appearpinchtab wait --not-text <text> # Wait for page text to disappearpinchtab wait --url <glob> # Wait for URL match (glob: **, *, ?)-pinchtab wait --load <state> # state: load | domcontentloaded | networkidle+pinchtab wait --load <state> # state: ready-state | content-loaded | network-idle+ # ready-state → document.readyState === 'complete'+ # content-loaded → readyState in {interactive, complete}+ # network-idle → 0 in-flight requests for 500ms (override with --idle-for)pinchtab wait --fn <expression> # Wait for JS to become truthypinchtab wait ... --timeout <ms> # Override timeout (default 10000, max 30000)pinchtab network # List captured network requestsdiff --git a/docs/endpoints.md b/docs/endpoints.mdindex 7055ebbe..c25a3f7b 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -412,12 +412,16 @@ Wait body fields:- `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`+ - `load` — one of:+ - `ready-state` → `document.readyState === 'complete'`+ - `content-loaded` → `document.readyState` in {`interactive`, `complete`}+ - `network-idle` → zero in-flight CDP requests held for `idleFor` ms (default 500, max 10000). Legacy alias `networkidle` accepted.- `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` — ms, default 10000, clamped 100–30000- optional `state` for selector waits — `visible` (default) or `hidden`+- optional `idleFor` for `load: network-idle` — ms quiet period, default 500, clamped 0–10000Network query parameters:diff --git a/internal/bridge/observe/network.go b/internal/bridge/observe/network.goindex 05f39062..b07a632f 100644--- a/internal/bridge/observe/network.go+++ b/internal/bridge/observe/network.go@@ -60,6 +60,13 @@ type NetworkBuffer struct {index map[string]intmaxSize int+ // Inflight tracking is independent of the ring buffer so eviction+ // doesn't corrupt the count. inflightIDs holds request IDs currently+ // in flight; lastChange records the most recent in-flight transition+ // (request started or completed). Both are guarded by mu.+ inflightIDs map[string]struct{}+ lastChange time.Time+subMu sync.Mutexsubscribers map[int]chan NetworkEntrynextSubID int@@ -75,10 +82,50 @@ func NewNetworkBuffer(size int) *NetworkBuffer {entries: make([]NetworkEntry, 0, size),index: make(map[string]int),maxSize: size,+ inflightIDs: make(map[string]struct{}),+ lastChange: time.Now(),subscribers: make(map[int]chan NetworkEntry),}}+// MarkRequestStart records that a request is in flight. Idempotent per+// request ID. Updates lastChange so wait callers can detect activity.+func (nb *NetworkBuffer) MarkRequestStart(requestID string) {+ if requestID == "" {+ return+ }+ nb.mu.Lock()+ defer nb.mu.Unlock()+ if _, ok := nb.inflightIDs[requestID]; ok {+ return+ }+ nb.inflightIDs[requestID] = struct{}{}+ nb.lastChange = time.Now()+}++// MarkRequestEnd records that an in-flight request finished or failed.+// No-op if the request was never registered.+func (nb *NetworkBuffer) MarkRequestEnd(requestID string) {+ if requestID == "" {+ return+ }+ nb.mu.Lock()+ defer nb.mu.Unlock()+ if _, ok := nb.inflightIDs[requestID]; !ok {+ return+ }+ delete(nb.inflightIDs, requestID)+ nb.lastChange = time.Now()+}++// InflightStatus returns the current in-flight request count and the+// timestamp of the most recent in-flight transition.+func (nb *NetworkBuffer) InflightStatus() (count int, lastChange time.Time) {+ nb.mu.RLock()+ defer nb.mu.RUnlock()+ return len(nb.inflightIDs), nb.lastChange+}+// Add inserts or updates a network entry.func (nb *NetworkBuffer) Add(entry NetworkEntry) {entry = normalizeNetworkEntry(entry)@@ -172,7 +219,8 @@ func (nb *NetworkBuffer) List(filter NetworkFilter) []NetworkEntry {return result}-// Clear removes all entries.+// Clear removes all entries. Inflight tracking is preserved because+// active requests are not affected by a buffer clear.func (nb *NetworkBuffer) Clear() {nb.mu.Lock()defer nb.mu.Unlock()@@ -343,6 +391,7 @@ func (nm *NetworkMonitor) StartCaptureWithSize(tabCtx context.Context, tabID strStartTime: time.Now(),}buf.Add(entry)+ buf.MarkRequestStart(string(e.RequestID))case *network.EventResponseReceived:buf.Update(string(e.RequestID), func(entry *NetworkEntry) {@@ -374,6 +423,7 @@ func (nm *NetworkMonitor) StartCaptureWithSize(tabCtx context.Context, tabID strentry.Size = int64(e.EncodedDataLength)}})+ buf.MarkRequestEnd(string(e.RequestID))case *network.EventLoadingFailed:buf.Update(string(e.RequestID), func(entry *NetworkEntry) {@@ -385,6 +435,7 @@ func (nm *NetworkMonitor) StartCaptureWithSize(tabCtx context.Context, tabID str}entry.Error = e.ErrorText})+ buf.MarkRequestEnd(string(e.RequestID))}})diff --git a/internal/bridge/observe/network_inflight_test.go b/internal/bridge/observe/network_inflight_test.gonew file mode 100644index 00000000..e5c85a2f--- /dev/null+++ b/internal/bridge/observe/network_inflight_test.go@@ -0,0 +1,96 @@+package observe++import (+ "testing"+ "time"+)++func TestNetworkBuffer_InflightLifecycle(t *testing.T) {+ buf := NewNetworkBuffer(10)++ count, _ := buf.InflightStatus()+ if count != 0 {+ t.Fatalf("fresh buffer: got count=%d, want 0", count)+ }++ buf.MarkRequestStart("req-1")+ buf.MarkRequestStart("req-2")+ count, lastChange := buf.InflightStatus()+ if count != 2 {+ t.Errorf("after 2 starts: got count=%d, want 2", count)+ }+ startTime := lastChange++ // Sleep so we can detect lastChange advancing.+ time.Sleep(2 * time.Millisecond)++ buf.MarkRequestEnd("req-1")+ count, lastChange = buf.InflightStatus()+ if count != 1 {+ t.Errorf("after 1 end: got count=%d, want 1", count)+ }+ if !lastChange.After(startTime) {+ t.Errorf("lastChange did not advance after MarkRequestEnd")+ }++ buf.MarkRequestEnd("req-2")+ count, _ = buf.InflightStatus()+ if count != 0 {+ t.Errorf("after all ends: got count=%d, want 0", count)+ }+}++func TestNetworkBuffer_InflightIdempotent(t *testing.T) {+ buf := NewNetworkBuffer(10)++ buf.MarkRequestStart("req-1")+ buf.MarkRequestStart("req-1") // duplicate start should be no-op+ count, _ := buf.InflightStatus()+ if count != 1 {+ t.Errorf("duplicate start: got count=%d, want 1", count)+ }++ buf.MarkRequestEnd("req-1")+ buf.MarkRequestEnd("req-1") // duplicate end should be no-op+ buf.MarkRequestEnd("never-started")+ count, _ = buf.InflightStatus()+ if count != 0 {+ t.Errorf("duplicate end: got count=%d, want 0", count)+ }+}++func TestNetworkBuffer_InflightSurvivesEviction(t *testing.T) {+ // Ring buffer holds 2 entries, but inflight tracking is independent.+ buf := NewNetworkBuffer(2)++ for i, id := range []string{"r1", "r2", "r3"} {+ buf.MarkRequestStart(id)+ buf.Add(NetworkEntry{RequestID: id, URL: "https://example.com", Method: "GET"})+ _ = i+ }++ // All three are in flight even though the ring has evicted r1.+ count, _ := buf.InflightStatus()+ if count != 3 {+ t.Errorf("after eviction: got count=%d, want 3", count)+ }++ buf.MarkRequestEnd("r1")+ count, _ = buf.InflightStatus()+ if count != 2 {+ t.Errorf("after evicted-end: got count=%d, want 2", count)+ }+}++func TestNetworkBuffer_ClearPreservesInflight(t *testing.T) {+ buf := NewNetworkBuffer(10)+ buf.MarkRequestStart("r1")+ buf.Add(NetworkEntry{RequestID: "r1", URL: "https://example.com"})++ buf.Clear()++ count, _ := buf.InflightStatus()+ if count != 1 {+ t.Errorf("Clear must not reset inflight: got count=%d, want 1", count)+ }+}diff --git a/internal/handlers/wait.go b/internal/handlers/wait.goindex d2b27474..cbbf2b54 100644--- a/internal/handlers/wait.go+++ b/internal/handlers/wait.go@@ -12,14 +12,18 @@ import ("github.com/chromedp/chromedp""github.com/pinchtab/pinchtab/internal/activity"+ "github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/httpx")const (- maxWaitTimeout = 30_000 // 30s max- defaultTimeout = 10_000 // 10s default- pollInterval = 250 * time.Millisecond- maxFixedWaitMS = 30_000+ maxWaitTimeout = 30_000 // 30s max+ defaultTimeout = 10_000 // 10s default+ pollInterval = 250 * time.Millisecond+ maxFixedWaitMS = 30_000+ defaultIdleForMS = 500+ maxIdleForMS = 10_000+ networkIdlePoll = 100 * time.Millisecond)// waitRequest is the JSON body for POST /wait and POST /tabs/{id}/wait.@@ -30,10 +34,11 @@ 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"` // "load" | "domcontentloaded" | "networkidle"+ Load string `json:"load,omitempty"` // "ready-state" | "content-loaded" | "network-idle" (alias: 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+ IdleFor *int `json:"idleFor,omitempty"` // network-idle quiet period in ms (default 500, max 10000)}// waitResponse is the JSON response for wait endpoints.@@ -79,6 +84,34 @@ func (wr *waitRequest) resolvedTimeout() time.Duration {return time.Duration(ms) * time.Millisecond}+func (wr *waitRequest) resolvedIdleFor() time.Duration {+ ms := defaultIdleForMS+ if wr.IdleFor != nil {+ ms = *wr.IdleFor+ }+ if ms < 0 {+ ms = 0+ }+ if ms > maxIdleForMS {+ ms = maxIdleForMS+ }+ return time.Duration(ms) * time.Millisecond+}++// canonicalLoadState maps the user-supplied --load value to a canonical+// state name and returns false if the value is not recognised. Accepts+// the legacy "networkidle" spelling as an alias for "network-idle".+func canonicalLoadState(s string) (string, bool) {+ switch s {+ case "ready-state", "content-loaded", "network-idle":+ return s, true+ case "networkidle":+ return "network-idle", true+ default:+ return "", false+ }+}+// HandleWait handles POST /wait.//// @Endpoint POST /wait@@ -209,16 +242,21 @@ func (h *Handlers) handleWaitCore(w http.ResponseWriter, r *http.Request, req wajs = buildURLMatchJS(req.URL)matchLabel = req.URLcase "load":- switch req.Load {- case "load", "networkidle":+ canonical, ok := canonicalLoadState(req.Load)+ if !ok {+ httpx.Error(w, 400, fmt.Errorf("unsupported load state: %s (supported: ready-state, content-loaded, network-idle)", req.Load))+ return+ }+ matchLabel = canonical+ switch canonical {+ case "ready-state":js = `document.readyState === 'complete'`- case "domcontentloaded":+ case "content-loaded":js = `document.readyState === 'interactive' || document.readyState === 'complete'`- default:- httpx.Error(w, 400, fmt.Errorf("unsupported load state: %s (supported: load, domcontentloaded, networkidle)", req.Load))+ case "network-idle":+ h.handleNetworkIdleWait(w, tCtx, start, resolvedTabID, req.resolvedIdleFor())return}- matchLabel = req.Loadcase "fn":js = fmt.Sprintf(`!!(function(){try{return %s}catch(e){return false}})()`, req.Fn)matchLabel = "fn"@@ -252,6 +290,53 @@ func (h *Handlers) handleWaitCore(w http.ResponseWriter, r *http.Request, req wa}}+// handleNetworkIdleWait polls the per-tab network monitor until in-flight+// requests have stayed at zero for idleFor, or the context is cancelled.+// Falls back to a readyState=='complete' check if the monitor is unavailable+// (e.g. tab created without network capture).+func (h *Handlers) handleNetworkIdleWait(w http.ResponseWriter, ctx context.Context, start time.Time, tabID string, idleFor time.Duration) {+ mon := h.Bridge.NetworkMonitor()+ var buf *bridge.NetworkBuffer+ if mon != nil {+ buf = mon.GetBuffer(tabID)+ }+ if buf == nil {+ httpx.JSON(w, 200, waitResponse{+ Waited: false,+ Elapsed: time.Since(start).Milliseconds(),+ Error: "network monitor unavailable for tab",+ })+ return+ }++ ticker := time.NewTicker(networkIdlePoll)+ defer ticker.Stop()++ for {+ count, lastChange := buf.InflightStatus()+ if count == 0 && time.Since(lastChange) >= idleFor {+ httpx.JSON(w, 200, waitResponse{+ Waited: true,+ Elapsed: time.Since(start).Milliseconds(),+ Match: "network-idle",+ })+ return+ }++ select {+ case <-ctx.Done():+ elapsed := time.Since(start).Milliseconds()+ httpx.JSON(w, 200, waitResponse{+ Waited: false,+ Elapsed: elapsed,+ Error: fmt.Sprintf("timeout after %dms waiting for network-idle (inflight=%d)", elapsed, count),+ })+ return+ case <-ticker.C:+ }+ }+}+// buildSelectorJS builds a JS expression for selector wait.// Supports css:, xpath:, text: prefixes and bare CSS selectors.func buildSelectorJS(sel, state string) (string, string) {diff --git a/internal/handlers/wait_test.go b/internal/handlers/wait_test.goindex d0d9b11a..c4bcc2a6 100644--- a/internal/handlers/wait_test.go+++ b/internal/handlers/wait_test.go@@ -6,6 +6,7 @@ import ("fmt""net/http/httptest""testing"+ "time""github.com/pinchtab/pinchtab/internal/config")@@ -232,7 +233,7 @@ func TestHandleWait_SelectorNotBlockedByEvaluateSetting(t *testing.T) {}func TestHandleWait_LoadNoTab(t *testing.T) {- for _, state := range []string{"networkidle", "load", "domcontentloaded"} {+ for _, state := range []string{"ready-state", "content-loaded", "network-idle", "networkidle"} {t.Run(state, func(t *testing.T) {h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)body := fmt.Sprintf(`{"load":%q}`, state)@@ -246,6 +247,54 @@ func TestHandleWait_LoadNoTab(t *testing.T) {}}+func TestCanonicalLoadState(t *testing.T) {+ cases := []struct {+ in string+ want string+ wantOK bool+ }{+ {"ready-state", "ready-state", true},+ {"content-loaded", "content-loaded", true},+ {"network-idle", "network-idle", true},+ {"networkidle", "network-idle", true}, // legacy alias+ {"load", "", false},+ {"domcontentloaded", "", false},+ {"", "", false},+ {"bogus", "", false},+ }+ for _, c := range cases {+ t.Run(c.in, func(t *testing.T) {+ got, ok := canonicalLoadState(c.in)+ if ok != c.wantOK || got != c.want {+ t.Errorf("canonicalLoadState(%q) = (%q, %v), want (%q, %v)", c.in, got, ok, c.want, c.wantOK)+ }+ })+ }+}++func TestWaitRequest_IdleForClamping(t *testing.T) {+ mk := func(ms *int) waitRequest { return waitRequest{IdleFor: ms} }+ ptr := func(i int) *int { return &i }++ cases := []struct {+ name string+ req waitRequest+ want time.Duration+ }{+ {"default when nil", mk(nil), 500 * time.Millisecond},+ {"explicit value", mk(ptr(1000)), 1000 * time.Millisecond},+ {"clamps negative to 0", mk(ptr(-100)), 0},+ {"clamps above max", mk(ptr(20000)), 10000 * time.Millisecond},+ }+ for _, c := range cases {+ t.Run(c.name, func(t *testing.T) {+ if got := c.req.resolvedIdleFor(); got != c.want {+ t.Errorf("got %v, want %v", got, c.want)+ }+ })+ }+}+func TestHandleWait_InvalidLoadState(t *testing.T) {h := New(&mockBridge{}, &config.RuntimeConfig{ActionTimeout: 5e9}, nil, nil, nil)req := httptest.NewRequest("POST", "/wait", bytes.NewReader([]byte(`{"load":"invalid"}`)))diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex be369a4c..ed7f0b06 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -218,7 +218,7 @@ func allTools() []mcp.Tool {),mcp.NewTool("pinchtab_wait_for_load",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.WithString("load", mcp.Required(), mcp.Description("Load state: 'ready-state' (readyState=complete), 'content-loaded' (readyState in {interactive, complete}), or 'network-idle' (0 in-flight requests for 500ms)")),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 49350e19..642d5f05 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -157,7 +157,7 @@ Use for async DOM settling (spinners, toasts, XHR).pinchtab wait <selector> # default: visible; --state hidden to wait for disappearpinchtab wait --text "..." | --not-text "..." # text appear / disappearpinchtab wait --url "**/dashboard" # glob: **, *, ?-pinchtab wait --load load|domcontentloaded|networkidle+pinchtab wait --load ready-state|content-loaded|network-idlepinchtab wait --fn "window.dataReady === true" # requires security.allowEvaluatepinchtab wait 500 # fixed ms delay (last resort, max 30000ms)```diff --git a/tests/e2e/scenarios/api/browser-extended.sh b/tests/e2e/scenarios/api/browser-extended.shindex 995c6549..9672adef 100644--- a/tests/e2e/scenarios/api/browser-extended.sh+++ b/tests/e2e/scenarios/api/browser-extended.sh@@ -302,29 +302,48 @@ assert_json_eq "$RESULT" '.waited' 'false' "waited=false on timeout"end_test# ─────────────────────────────────────────────────────────────────-start_test "POST /wait: load states (load, domcontentloaded, networkidle)"+start_test "POST /wait: load states (ready-state, content-loaded, network-idle)"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}"+# Navigation has settled, so all three should resolve quickly.+# network-idle uses a short idleFor so the test stays fast.+for state in ready-state content-loaded network-idle; do+ pt_post /wait "{\"load\":\"${state}\",\"timeout\":8000,\"idleFor\":200}"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}"+ assert_json_eq "$RESULT" '.match' "${state}" "match label echoes ${state}"doneend_test+# ─────────────────────────────────────────────────────────────────+start_test "POST /wait: legacy 'networkidle' alias still accepted"++pt_post /navigate "{\"url\":\"${FIXTURES_URL}/buttons.html\"}"+assert_ok "navigate"++pt_post /wait '{"load":"networkidle","timeout":8000,"idleFor":200}'+assert_ok "legacy alias accepted"+assert_json_eq "$RESULT" '.waited' 'true' "waited=true via legacy alias"+assert_json_eq "$RESULT" '.match' 'network-idle' "alias canonicalised to network-idle"++end_test+# ─────────────────────────────────────────────────────────────────start_test "POST /wait: rejects unknown load state"pt_post /wait '{"load":"bogus"}'assert_http_status "400" "rejects unknown load state"+# Pre-rename names should now also be rejected.+pt_post /wait '{"load":"load"}'+assert_http_status "400" "rejects pre-rename 'load'"++pt_post /wait '{"load":"domcontentloaded"}'+assert_http_status "400" "rejects pre-rename 'domcontentloaded'"+end_test# ─────────────────────────────────────────────────────────────────