@debugg-ai/debugg-ai-mcp 4.2.0 → 4.2.1

package/README.md

@@ -142,13 +142,13 @@ Fires a server-side browser-agent crawl to populate the project's knowledge grap
 
 #### `probe_page`
 
-**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, waits for load, and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
+**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, settles on content (the DOM going quiet, bounded — never on network silence, which a live app never reaches), and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `targets` | array **required** | 1-20 entries: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]` |
 | `targets[].url` | string **required** | Public URL or localhost (auto-tunneled) |
-| `targets[].waitForLoadState` | enum | `'load'` (default) / `'domcontentloaded'` / `'networkidle'` |
+| `targets[].waitForLoadState` | enum | `'domcontentloaded'` (default, + a bounded content settle) / `'load'` (also blocks on third-party embeds) / `'networkidle'` (accepted, never issued — a live site's network does not go idle) |
 | `targets[].waitForSelector` | string | Optional CSS selector to wait for after navigation |
 | `targets[].timeoutMs` | number | Per-URL timeout, 1000-30000 (default 10000) |
 | `includeHtml` | boolean | Return raw HTML in each result (default false) |

package/dist/tools/probePage.js

@@ -22,6 +22,8 @@ LOCALHOST SUPPORT: any localhost URL is auto-tunneled. Pre-flight TCP probe fail
 
 BATCH MODE: pass up to 20 targets in one call to share browser session + tunnel — dramatically faster than firing parallel single-URL probes (one execution unit, not N). Per-URL waitForSelector / waitForLoadState / timeoutMs override defaults.
 
+READINESS: navigation settles on CONTENT (the page's DOM going quiet), bounded — not on network silence, which never arrives on a live app, and not on 'load', which blocks on third-party embeds. The default is right for SPAs; reach for waitForSelector, not waitForLoadState, when you need to wait for something specific.
+
 A single failed target's error appears in result.error without failing the whole batch — the other results stay valid.`;
 const TARGET_PROPERTIES = {
     url: {
@@ -35,11 +37,15 @@ const TARGET_PROPERTIES = {
     waitForLoadState: {
         type: 'string',
         enum: ['load', 'domcontentloaded', 'networkidle'],
-        description: "When to consider the page 'loaded' before capturing. Default 'load'. Use 'networkidle' for SPAs to wait until the bundle finishes rendering.",
+        // sentinal-kvoou. This description used to read "Default 'load'. Use 'networkidle'
+        // for SPAs to wait until the bundle finishes rendering" — advice that hangs on
+        // exactly the class of app it names. See __tests__/tools/probePageWaitContract.ts
+        // for the measurement against https://debugg.ai.
+        description: "When to consider the page ready to capture. Default 'domcontentloaded', followed by a bounded content settle (the page's DOM going quiet) — that is what actually makes a client-rendered SPA safe to screenshot, and it needs no override. Only override for a specific reason: 'load' additionally blocks on every sub-resource, including third-party iframes and images we do not control, so a slow embed can time the whole probe out. 'networkidle' is accepted for compatibility but is never issued — a live site's network does not go idle (analytics, polling, websockets, ads) — and behaves as 'domcontentloaded'. To wait on something specific, use waitForSelector.",
     },
     timeoutMs: {
         type: 'number',
-        description: 'Per-URL navigation timeout in milliseconds (1000-30000, default 10000).',
+        description: "Per-URL budget in milliseconds for navigating AND settling this target (1000-30000, default 10000). The content settle spends what the navigation left over, so this is the whole cost of the target, not just the goto.",
     },
 };
 export function buildProbePageTool() {

package/dist/types/index.js

@@ -226,7 +226,15 @@ export var LogLevel;
 export const ProbePageTargetSchema = z.object({
     url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),
     waitForSelector: z.string().optional(),
-    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('load'),
+    // sentinal-kvoou: 'domcontentloaded', NOT 'load'. 'load' blocks on every
+    // sub-resource including third-party iframes we do not control — measured against
+    // https://debugg.ai (two YouTube embeds), the 'load' default timed the goto out at
+    // 10s and reported statusCode 0 on a page that renders in 3.5s. Readiness comes from
+    // the backend's bounded CONTENT settle after the goto, not from a load state.
+    // 'networkidle' stays in the enum (this package is published; removing it would turn
+    // an existing caller's probe into a hard validation error) and is neutralized
+    // server-side — never a wait, always domcontentloaded + settle.
+    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('domcontentloaded'),
     timeoutMs: z.number().int().min(1000, 'timeoutMs minimum is 1000 (1s)').max(30000, 'timeoutMs maximum is 30000 (30s) — longer probes should use check_app_in_browser').default(10000),
 }).strict();
 export const ProbePageInputSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",