crawlio-browser 1.5.1 → 1.5.3

package/dist/mcp-server/{chunk-DY3E5LV6.js → chunk-OCCTLY6F.js}

@@ -1,7 +1,7 @@
 // src/shared/constants.ts
 import { homedir } from "os";
 import { join } from "path";
-var PKG_VERSION = "1.5.1";
+var PKG_VERSION = "1.5.3";
 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-DY3E5LV6.js";
+} from "./chunk-OCCTLY6F.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) \u2014 JS eval via CDP (auto-wraps if expr contains `return`)",
+        "  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",
@@ -4112,7 +4137,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-JRSGXDVD.js");
+  const { runInit } = await import("./init-NEXLUHXC.js");
   await runInit(process.argv.slice(2));
   process.exit(0);
 }

package/dist/mcp-server/{init-JRSGXDVD.js → init-NEXLUHXC.js}

@@ -1,6 +1,6 @@
 import {
   PKG_VERSION
-} from "./chunk-DY3E5LV6.js";
+} from "./chunk-OCCTLY6F.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.1",
+  "version": "1.5.3",
   "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

@@ -36,6 +36,13 @@ Check connection status anytime:
 return await bridge.send({ type: "get_connection_status" })
 ```
 
+## Critical Rules
+
+1. **ALWAYS `search` before `execute`** when you're unsure of a command name or its parameters. Never guess command names — they will fail.
+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.
+
 ## Core Patterns via `execute`
 
 All browser commands run inside the `execute` tool. The code has access to:
@@ -54,10 +61,10 @@ return await smart.navigate("https://example.com")
 ### Screenshots
 
 ```js
-return await smart.screenshot()
+return await bridge.send({ type: 'take_screenshot' })
 ```
 
-Returns base64 PNG. Use `{ fullPage: true }` for full-page capture.
+Returns `{ screenshot: string }` (base64 PNG). For full-page: `bridge.send({ type: 'take_screenshot', fullPage: true })`.
 
 ### OCR Text Extraction (macOS only)
 
@@ -105,7 +112,17 @@ return await smart.snapshot()
 return await smart.snapshot()
 ```
 
-Returns the a11y tree — 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
 
@@ -113,6 +130,15 @@ Returns the a11y tree — use this to discover available elements when selectors
 return await smart.evaluate("document.title")
 ```
 
+For multi-statement evaluation, just use `return` — it auto-wraps in an IIFE:
+
+```js
+return await smart.evaluate(`
+  const links = Array.from(document.querySelectorAll('a[href]'));
+  return links.map(a => ({ text: a.textContent.trim(), href: a.href }));
+`)
+```
+
 ### Framework Detection
 
 ```js
@@ -284,6 +310,65 @@ return await crawlio.api("GET", "/settings")
 return await crawlio.api("POST", "/export", { format: "zip", destinationPath: "/tmp/site.zip" })
 ```
 
+## Return Value Shapes
+
+Commands return **objects**, not primitives. Always access the correct property.
+
+### smart methods
+
+```js
+// smart.snapshot() → { snapshot: string }
+const snap = await smart.snapshot();
+const tree = snap.snapshot;  // the a11y tree text
+// WRONG: snap.split('\n')  — snap is an object, not a string
+
+// smart.evaluate(expr) → { result: any, type: string }
+const res = await smart.evaluate("document.title");
+const title = res.result;  // the actual value
+const type = res.type;     // "string", "number", "object", etc.
+// WRONG: res.substring()  — res is an object, not the raw value
+```
+
+### bridge.send commands
+
+```js
+// list_tabs → { tabs: Tab[], connectedTabId: number|null }
+const result = await bridge.send({ type: 'list_tabs' });
+const tabs = result.tabs;           // array of tab objects
+const connected = result.connectedTabId;
+
+// connect_tab → { action, tabId, url, title, windowId, capturing, domainState }
+const tab = await bridge.send({ type: 'connect_tab', tabId: 123 });
+
+// capture_page → { url, title, framework, network, console, cookies, dom, capturedAt }
+const page = await bridge.send({ type: 'capture_page' });
+
+// take_screenshot → { screenshot: string }  (base64 PNG)
+const ss = await bridge.send({ type: 'take_screenshot' });
+
+// get_cookies → { cookies: Cookie[] }
+const result = await bridge.send({ type: 'get_cookies' });
+const cookies = result.cookies;
+
+// get_console_logs → { logs: LogEntry[] }
+const result = await bridge.send({ type: 'get_console_logs' });
+const logs = result.logs;
+
+// close_tab → requires tabId!
+await bridge.send({ type: 'close_tab', tabId: 123 });  // REQUIRED
+// WRONG: bridge.send({ type: 'close_tab' })  — will error
+```
+
+### Network capture (start/stop pattern — no `get_network_entries`)
+
+```js
+await bridge.send({ type: 'start_network_capture' });
+// ... interactions ...
+const result = await bridge.send({ type: 'stop_network_capture' });
+const entries = result.entries;  // array of network entries
+// WRONG: bridge.send({ type: 'get_network_entries' })  — does NOT exist
+```
+
 ## Error Handling
 
 | Error | Solution |
@@ -309,8 +394,8 @@ await smart.click("button[type='submit']")
 await sleep(2000)
 
 // 4. Verify navigation
-const title = await smart.evaluate("document.title")
-return { title, url: await smart.evaluate("location.href") }
+const title = (await smart.evaluate("document.title")).result
+return { title, url: (await smart.evaluate("location.href")).result }
 ```
 
 ## Reference

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. Auto-wraps in IIFE if `return` is used. |
+| `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 |