Skip to content

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.md
index a58be02d..43697cf2 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -150,7 +150,10 @@ pinchtab wait <ms> # Fixed duration sleep (escape hatch; ma
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 --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 truthy
pinchtab wait ... --timeout <ms> # Override timeout (default 10000, max 30000)
pinchtab network # List captured network requests
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 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–10000
Network query parameters:
diff --git a/internal/bridge/observe/network.go b/internal/bridge/observe/network.go
index 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]int
maxSize 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.Mutex
subscribers map[int]chan NetworkEntry
nextSubID 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 str
StartTime: 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 str
entry.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.go
new file mode 100644
index 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.go
index 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 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"` // "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 truthy
Ms *int `json:"ms,omitempty"` // fixed duration wait
Timeout *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 wa
js = buildURLMatchJS(req.URL)
matchLabel = req.URL
case "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.Load
case "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.go
index 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.go
index 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.md
index 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 disappear
pinchtab wait --text "..." | --not-text "..." # text appear / disappear
pinchtab wait --url "**/dashboard" # glob: **, *, ?
-pinchtab wait --load load|domcontentloaded|networkidle
+pinchtab wait --load ready-state|content-loaded|network-idle
pinchtab wait --fn "window.dataReady === true" # requires security.allowEvaluate
pinchtab 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.sh
index 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}"
done
end_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
# ─────────────────────────────────────────────────────────────────