crawlio-browser 1.5.2 → 1.5.4

package/dist/mcp-server/{chunk-BKBNDFXW.js → chunk-MRVXVQXV.js}

@@ -1,7 +1,7 @@
 // src/shared/constants.ts
 import { homedir } from "os";
 import { join } from "path";
-var PKG_VERSION = "1.5.2";
+var PKG_VERSION = "1.5.4";
 var WS_PORT = 9333;
 var WS_PORT_MAX = 9342;
 var WS_HOST = "127.0.0.1";

package/dist/mcp-server/index.js

@@ -9,7 +9,7 @@ import {
   WS_PORT_MAX,
   WS_RECONNECT_GRACE,
   WS_STALE_THRESHOLD
-} from "./chunk-BKBNDFXW.js";
+} from "./chunk-MRVXVQXV.js";
 
 // src/mcp-server/index.ts
 import { randomBytes as randomBytes2 } from "crypto";
@@ -3709,17 +3709,37 @@ function createTools(bridge2, crawlio2) {
     }
   ];
 }
+function parseSnapshotRef(selector) {
+  const m = /^\[ref=([a-zA-Z0-9]+)\]$/.exec(selector.trim());
+  return m ? m[1] : null;
+}
 async function buildSmartObject(bridge2) {
-  const evaluate = (expression) => bridge2.send({ type: "browser_evaluate", expression }, 5e3);
+  const evaluate = (expression) => {
+    const hasReturn = /(?:^|[;\n{])\s*return\s/m.test(expression);
+    const expr = hasReturn ? `(async () => { ${expression} })()` : expression;
+    return bridge2.send({ type: "browser_evaluate", expression: expr }, 5e3);
+  };
   const smart = {
     evaluate,
     click: async (selector, opts) => {
+      const ref = parseSnapshotRef(selector);
+      if (ref) {
+        const result2 = await bridge2.send({ type: "browser_click", ref, button: "left", modifiers: {} }, 1e4);
+        await new Promise((r) => setTimeout(r, opts?.settle ?? 500));
+        return result2;
+      }
       await pollActionability(bridge2, selector);
       const result = await bridge2.send({ type: "browser_click", selector, button: "left", modifiers: {} }, 1e4);
       await new Promise((r) => setTimeout(r, opts?.settle ?? 500));
       return result;
     },
     type: async (selector, text, opts) => {
+      const ref = parseSnapshotRef(selector);
+      if (ref) {
+        const result2 = await bridge2.send({ type: "browser_type", ref, text, clearFirst: opts?.clearFirst ?? false, modifiers: {} }, 1e4);
+        await new Promise((r) => setTimeout(r, opts?.settle ?? 300));
+        return result2;
+      }
       await pollActionability(bridge2, selector);
       const result = await bridge2.send({ type: "browser_type", selector, text, clearFirst: opts?.clearFirst ?? false, modifiers: {} }, 1e4);
       await new Promise((r) => setTimeout(r, opts?.settle ?? 300));
@@ -3732,6 +3752,11 @@ async function buildSmartObject(bridge2) {
       return result;
     },
     waitFor: async (selector, timeout) => {
+      const ref = parseSnapshotRef(selector);
+      if (ref) {
+        await bridge2.send({ type: "browser_hover", ref }, timeout ?? 5e3);
+        return { found: true, selector };
+      }
       await pollActionability(bridge2, selector, timeout ?? 5e3);
       return { found: true, selector };
     },
@@ -4002,8 +4027,8 @@ function createCodeModeTools(bridge2, crawlio2) {
         "- compileRecording(session, { name, description? }) \u2014 compile RecordingSession to SKILL.md",
         "  Returns { skillMarkdown, name, pageCount, interactionCount }",
         "- smart \u2014 auto-waiting wrappers and framework-specific data accessors:",
-        "  smart.evaluate(expr) \u2014 raw JS evaluation via CDP",
-        "  smart.click(selector, opts?) \u2014 poll + click + 500ms settle",
+        "  smart.evaluate(expr) \u2192 {result, type} \u2014 access .result for value. Never JSON.parse() the return directly.",
+        "  smart.click(selector, opts?) \u2014 poll + click + 500ms settle (accepts CSS or snapshot [ref=X])",
         "  smart.type(selector, text, opts?) \u2014 poll + type + 300ms settle",
         "  smart.navigate(url, opts?) \u2014 navigate + 1000ms settle",
         "  smart.waitFor(selector, timeout?) \u2014 poll until actionable",
@@ -4045,7 +4070,10 @@ function createCodeModeTools(bridge2, crawlio2) {
         "  // ... interact with page ...",
         "  const session = await bridge.send({ type: 'stop_recording' });",
         "  const skill = compileRecording(session, { name: 'my-flow' });",
-        "  return skill;"
+        "  return skill;",
+        "",
+        "IMPORTANT: Keep scripts fast (<15s). Each smart.click costs ~1-2s. Never loop 5+ clicks \u2014 use smart.evaluate to read DOM data in bulk instead.",
+        "IMPORTANT: smart.evaluate returns {result, type}. Access .result for the value. Never JSON.stringify inside evaluate then JSON.parse outside \u2014 just return objects directly."
       ].join("\n"),
       inputSchema: {
         type: "object",
@@ -4112,7 +4140,7 @@ function createCodeModeTools(bridge2, crawlio2) {
 process.title = "Crawlio Agent";
 var initMode = process.argv.includes("init") || process.argv.includes("--setup") || process.argv.includes("setup");
 if (initMode) {
-  const { runInit } = await import("./init-5MP7GP7G.js");
+  const { runInit } = await import("./init-NSSER4A2.js");
   await runInit(process.argv.slice(2));
   process.exit(0);
 }

package/dist/mcp-server/{init-5MP7GP7G.js → init-NSSER4A2.js}

@@ -1,6 +1,6 @@
 import {
   PKG_VERSION
-} from "./chunk-BKBNDFXW.js";
+} from "./chunk-MRVXVQXV.js";
 
 // src/mcp-server/init.ts
 import { execFileSync, spawn } from "child_process";
@@ -311,7 +311,7 @@ function isAlreadyConfigured(config) {
 function buildCloudflareEntry(accountId, apiToken) {
   return {
     command: "npx",
-    args: ["-y", "@cloudflare/mcp-server-cloudflare@0.2.0", "run", accountId],
+    args: ["-y", "@cloudflare/mcp-server-cloudflare", "run", accountId],
     env: { CLOUDFLARE_API_TOKEN: apiToken }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlio-browser",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "MCP server with 96 CDP-backed tools for browser automation — screenshots, DOM, network capture, framework detection, cookies, storage, session recording, performance metrics via Chrome",
   "type": "module",
   "main": "dist/mcp-server/index.js",

package/skills/browser-automation/SKILL.md

@@ -42,6 +42,8 @@ return await bridge.send({ type: "get_connection_status" })
 2. **Return values are objects**, not primitives. Always destructure or access properties (see Return Value Shapes below).
 3. **`close_tab` requires `tabId`** — it will error without one. Get tabId from `list_tabs` or `connect_tab`.
 4. **`connect_tab` before any interaction** — most commands require an active tab connection.
+5. **`smart.evaluate` returns `{ result, type }`** — NOT the raw value. Access `.result` to get the value. Never `JSON.parse()` the return directly.
+6. **Keep scripts fast** — each `execute` call should complete in <15s. Split loops over many elements into separate `execute` calls. Never loop 5+ `smart.click` calls in one script.
 
 ## Core Patterns via `execute`
 
@@ -112,12 +114,47 @@ return await smart.snapshot()
 return await smart.snapshot()
 ```
 
-Returns `{ snapshot: string }` — the a11y tree text. Use this to discover available elements when selectors fail.
+Returns `{ snapshot: string }` — the a11y tree text with `[ref=X]` labels on interactive elements. Use this to discover available elements when selectors fail.
+
+Snapshot refs like `[ref=e3]` work directly with `smart.click`, `smart.type`, and `smart.waitFor`:
+
+```js
+const snap = await smart.snapshot()
+// snap.snapshot contains: [ref=e3] button "Platform" ...
+await smart.click('[ref=e3]')  // clicks via the snapshot ref system (not CSS)
+```
+
+These refs are resolved from the cached snapshot — they are NOT CSS selectors. They bypass `document.querySelector` and use CDP node resolution instead.
 
 ### Evaluate JavaScript
 
 ```js
-return await smart.evaluate("document.title")
+const res = await smart.evaluate("document.title")
+return res.result  // "My Page Title" — always access .result!
+```
+
+**`smart.evaluate` returns `{ result: <value>, type: <string> }`, NOT the raw value.** You must access `.result` to get the actual value.
+
+For multi-statement evaluation, just use `return` — it auto-wraps in an IIFE:
+
+```js
+const res = await smart.evaluate(`
+  const links = Array.from(document.querySelectorAll('a[href]'));
+  return links.map(a => ({ text: a.textContent.trim(), href: a.href }));
+`)
+return res.result  // [{text: "Home", href: "..."}, ...]
+```
+
+**WRONG — do NOT `JSON.stringify` inside evaluate then `JSON.parse` outside:**
+
+```js
+// BAD — will cause "[object Object]" is not valid JSON
+const res = await smart.evaluate(`return JSON.stringify(data)`)
+return JSON.parse(res)  // WRONG: res is {result: "...", type: "string"}, not a string
+
+// GOOD — return objects directly, CDP serializes them for you
+const res = await smart.evaluate(`return data`)
+return res.result  // the actual JS object/array
 ```
 
 ### Framework Detection
@@ -305,9 +342,11 @@ const tree = snap.snapshot;  // the a11y tree text
 
 // smart.evaluate(expr) → { result: any, type: string }
 const res = await smart.evaluate("document.title");
-const title = res.result;  // the actual value
+const title = res.result;  // the actual value — "My Page"
 const type = res.type;     // "string", "number", "object", etc.
-// WRONG: res.substring()  — res is an object, not the raw value
+// WRONG: res.substring()      — res is {result, type}, not the raw value
+// WRONG: JSON.parse(res)      — will get "[object Object]" is not valid JSON
+// WRONG: JSON.stringify inside + JSON.parse outside — just return objects directly
 ```
 
 ### bridge.send commands
@@ -357,9 +396,41 @@ const entries = result.entries;  // array of network entries
 | "No tab connected" | Call `connect_tab` first |
 | "Element not found" | Use `smart.snapshot()` to see available elements, then adjust selector |
 | "Extension disconnected" | Check that the Chrome extension is installed and the popup shows "Connected" |
-| Timeout | Increase timeout: `await bridge.send({ type: "..." }, 60000)` |
+| "timed out after 30000ms" | Script too slow — reduce interactions per call, use evaluate instead of click loops |
+| "[object Object]" not valid JSON | You called `JSON.parse` on a `{result, type}` object — use `.result` first |
 | "Permission required" | Click the Crawlio extension icon and grant permissions |
 
+## Script Performance Rules
+
+Each `execute` call has a 120s internal timeout, but **MCP clients may impose shorter timeouts** (30s is common). Keep scripts fast:
+
+- **Max 3-4 interactions per script** — each `smart.click`/`smart.type` costs ~1-2s (actionability polling + settle time)
+- **Never loop 5+ clicks** — split into multiple `execute` calls instead
+- **Minimize `sleep()` calls** — use `smart.waitFor(selector)` instead of `sleep(2000)`
+- **Avoid `JSON.stringify` in evaluate** — return objects directly, CDP serializes automatically
+
+### BAD — will timeout (8 clicks × ~1.5s + sleeps = ~16s minimum)
+
+```js
+for (let i = 18; i <= 25; i++) {
+  await smart.click(`[ref=e${i}]`)
+  await sleep(300)
+}
+```
+
+### GOOD — one evaluate call reads all the data at once
+
+```js
+const res = await smart.evaluate(`
+  const items = document.querySelectorAll('.faq-item');
+  return Array.from(items).map(el => ({
+    question: el.querySelector('h3')?.textContent?.trim(),
+    answer: el.querySelector('.answer')?.textContent?.trim()
+  }));
+`)
+return res.result
+```
+
 ## Multi-Step Workflow Example
 
 ```js
@@ -372,7 +443,7 @@ await smart.type("#password", "secret123")
 
 // 3. Click login
 await smart.click("button[type='submit']")
-await sleep(2000)
+await smart.waitFor(".dashboard")  // prefer waitFor over sleep
 
 // 4. Verify navigation
 const title = (await smart.evaluate("document.title")).result

package/skills/browser-automation/reference.md

@@ -232,9 +232,9 @@ The `smart` object provides auto-waiting wrappers and framework-specific data:
 
 | Method | Description |
 |--------|-------------|
-| `smart.evaluate(expr)` | Raw JS evaluation via CDP |
-| `smart.click(selector, opts?)` | Poll + click + 500ms settle |
-| `smart.type(selector, text, opts?)` | Poll + type + 300ms settle |
+| `smart.evaluate(expr)` | JS evaluation via CDP. Returns `{ result, type }` — access `.result` for the value. Auto-wraps in IIFE if `return` is used. Return objects directly, never `JSON.stringify` inside. |
+| `smart.click(selector, opts?)` | Poll + click + 500ms settle. Accepts CSS selectors or snapshot refs (`[ref=e3]`). |
+| `smart.type(selector, text, opts?)` | Poll + type + 300ms settle. Accepts CSS selectors or snapshot refs. |
 | `smart.navigate(url, opts?)` | Navigate + 1000ms settle |
 | `smart.waitFor(selector, timeout?)` | Poll until element is actionable |
 | `smart.snapshot()` | Capture accessibility snapshot |