surf-cli 2.0.0 → 2.2.0

package/native/cli.cjs

@@ -234,7 +234,7 @@ const TOOLS = {
         examples: [{ cmd: "forward", desc: "Browser forward" }]
       },
       "screenshot": { 
-        desc: "Capture screenshot (auto-resized for LLM by default)", 
+        desc: "Capture screenshot (auto-saves to /tmp by default)", 
         args: [], 
         opts: { 
           output: "Save to file", 
@@ -243,14 +243,15 @@ const TOOLS = {
           fullpage: "Capture full page", 
           "max-height": "Max height for fullpage (default: 4000)",
           full: "Skip resize, save at full resolution",
-          "max-size": "Max dimension in px (default: 1200)" 
+          "max-size": "Max dimension in px (default: 1200)",
+          "no-save": "Don't auto-save, return base64 + ID (saves context)"
         },
         examples: [
-          { cmd: "screenshot --output /tmp/shot.png", desc: "Save to file (auto-resized)" },
-          { cmd: "screenshot --full --output /tmp/shot.png", desc: "Full resolution" },
-          { cmd: "screenshot --max-size 800 --output /tmp/small.png", desc: "Custom max size" },
-          { cmd: "screenshot --annotate --output /tmp/annotated.png", desc: "With element labels" },
-          { cmd: "snap", desc: "Auto-save to /tmp (resized)" },
+          { cmd: "screenshot", desc: "Auto-save to /tmp (default)" },
+          { cmd: "screenshot --output /tmp/shot.png", desc: "Save to specific file" },
+          { cmd: "screenshot --no-save", desc: "Return base64 without saving" },
+          { cmd: "screenshot --annotate", desc: "With element labels" },
+          { cmd: "snap", desc: "Alias for screenshot" },
         ]
       },
       "snap": { desc: "Alias for screenshot (auto-saves to /tmp)", args: [], alias: "screenshot" },
@@ -348,6 +349,37 @@ const TOOLS = {
       },
     }
   },
+  element: {
+    desc: "Element inspection",
+    commands: {
+      "element.styles": {
+        desc: "Get computed styles from element(s)",
+        args: ["ref_or_selector"],
+        examples: [
+          { cmd: "element.styles e5", desc: "Get styles by ref" },
+          { cmd: 'element.styles ".header"', desc: "Get styles by selector (can return multiple)" },
+        ]
+      },
+    }
+  },
+  forms: {
+    desc: "Form interactions",
+    commands: {
+      "select": {
+        desc: "Select option(s) in dropdown",
+        args: ["ref_or_selector", "values..."],
+        opts: {
+          by: "Match by: value (default), label, index"
+        },
+        examples: [
+          { cmd: 'select e5 "US"', desc: "Select by value" },
+          { cmd: 'select e5 "opt1" "opt2"', desc: "Multi-select" },
+          { cmd: 'select e5 --by label "United States"', desc: "Select by visible text" },
+          { cmd: 'select e5 --by index 0', desc: "Select first option" },
+        ]
+      },
+    }
+  },
   wait: {
     desc: "Waiting",
     commands: {
@@ -1672,7 +1704,7 @@ if (args.includes("--script")) {
   return;
 }
 
-const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl"];
+const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save"];
 
 const AUTO_SCREENSHOT_TOOLS = ["click", "type", "key", "smart_type", "form.fill", "form_input", "drag", "hover", "scroll", "scroll.top", "scroll.bottom", "scroll.to", "dialog.accept", "dialog.dismiss", "js", "eval"];
 
@@ -1727,10 +1759,14 @@ if (REMOVED_COMMANDS[tool]) {
   process.exit(1);
 }
 
-const wasSnap = tool === "snap";
 tool = ALIASES[tool] || tool;
 
-if (wasSnap && !options.output && !options.savePath) {
+// Auto-save screenshots to temp file when no --output specified
+// This ensures agents always get a usable file path, not just an in-memory ID
+// Can be disabled with --no-save flag or autoSaveScreenshots: false in surf.json
+const config = loadConfig();
+const autoSaveEnabled = config.autoSaveScreenshots !== false && !options["no-save"];
+if (tool === "screenshot" && !options.output && !options.savePath && autoSaveEnabled) {
   options.savePath = `/tmp/surf-snap-${Date.now()}.png`;
 }
 
@@ -1804,6 +1840,8 @@ const PRIMARY_ARG_MAP = {
   "locate.label": "label",
   "emulate.device": "device",
   "frame.js": "code",
+  "element.styles": "selector",
+  "select": "selector",
 };
 
 const toolArgs = { ...options };
@@ -1840,6 +1878,17 @@ if (tool === "js" && toolArgs.file) {
   }
 }
 
+// Handle select command: capture multiple values after selector
+if (tool === "select" && positional.length > 2) {
+  const values = positional.slice(2);  // All args after "select <selector>"
+  toolArgs.values = values.length === 1 ? values[0] : values;
+} else if (tool === "select" && positional.length === 2) {
+  // Only selector provided, no values
+  console.error("Error: select requires at least one value");
+  console.error("Usage: surf select <selector> <value...>");
+  process.exit(1);
+}
+
 if (toolArgs.into && !toolArgs.selector) {
   toolArgs.selector = toolArgs.into;
   delete toolArgs.into;
@@ -1887,7 +1936,7 @@ if (!noScreenshot && AUTO_SCREENSHOT_TOOLS.includes(tool)) {
 const outputPath = toolArgs.output;
 delete toolArgs.output;
 
-if ((tool === "screenshot" || tool === "snap") && outputPath) {
+if (tool === "screenshot" && outputPath) {
   if (typeof outputPath !== "string") {
     console.error("Error: --output requires a file path");
     process.exit(1);
@@ -2208,7 +2257,7 @@ async function handleResponse(response) {
     process.exit(0);
   }
 
-  if ((tool === "screenshot" || tool === "snap") && data?.base64 && (outputPath || toolArgs.savePath)) {
+  if (tool === "screenshot" && data?.base64 && (outputPath || toolArgs.savePath)) {
     const saveTo = outputPath || toolArgs.savePath;
     fs.writeFileSync(saveTo, Buffer.from(data.base64, "base64"));
     
@@ -2227,8 +2276,11 @@ async function handleResponse(response) {
     } else {
       console.log(`Saved to ${saveTo} (${origWidth}x${origHeight})`);
     }
-  } else if ((tool === "screenshot" || tool === "snap") && data?.message) {
+  } else if (tool === "screenshot" && data?.message) {
     console.log(data.message);
+    if (data.screenshotId) {
+      console.log(`[Screenshot ID: ${data.screenshotId}]`);
+    }
   } else if (tool === "tab.list") {
     const tabs = data?.tabs || data || [];
     if (Array.isArray(tabs)) {

package/native/config.cjs

@@ -8,6 +8,9 @@ let cachedConfig = null;
 let cachedConfigPath = null;
 
 const STARTER_CONFIG = {
+  // Set to false to disable auto-saving screenshots to /tmp
+  // When disabled, screenshots return base64 + ID instead of file path
+  autoSaveScreenshots: true,
   routes: {
     main: ["http://localhost:3000"]
   },

package/native/host-helpers.cjs

@@ -20,6 +20,37 @@ function formatToolContent(result, log = () => {}) {
     return text(result.content);
   }
   
+  // Handle element.styles response
+  if (result.styles && Array.isArray(result.styles)) {
+    const output = result.styles.map(el => {
+      const lines = [`<${el.tag}>${el.text ? ` "${el.text.slice(0, 50)}${el.text.length > 50 ? '...' : ''}"` : ''}`];
+      if (el.box) lines.push(`  box: ${el.box.x},${el.box.y} ${el.box.width}x${el.box.height}`);
+      const s = el.styles;
+      if (s) {
+        if (s.fontSize) lines.push(`  font: ${s.fontSize} ${s.fontWeight} ${s.fontFamily}`);
+        if (s.color) lines.push(`  color: ${s.color}`);
+        if (s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)') lines.push(`  bg: ${s.backgroundColor}`);
+        if (s.borderRadius && s.borderRadius !== '0px') lines.push(`  radius: ${s.borderRadius}`);
+        if (s.border) lines.push(`  border: ${s.border}`);
+        if (s.boxShadow) lines.push(`  shadow: ${s.boxShadow}`);
+        if (s.padding && s.padding !== '0px') lines.push(`  padding: ${s.padding}`);
+      }
+      return lines.join('\n');
+    }).join('\n\n');
+    return text(output || "No elements found");
+  }
+  
+  // Handle select response
+  if (result.selected !== undefined) {
+    let output = Array.isArray(result.selected) 
+      ? `Selected: ${result.selected.join(', ')}`
+      : `Selected: ${result.selected}`;
+    if (result.warning) {
+      output += `\n[Warning: ${result.warning}]`;
+    }
+    return text(output);
+  }
+  
   // Handle ChatGPT/Gemini responses
   if (result.response !== undefined && result.model !== undefined && result.tookMs !== undefined) {
     let output = result.response;
@@ -84,7 +115,17 @@ function formatToolContent(result, log = () => {}) {
     return text(result.output);
   }
 
-  if (result.screenshotId) {
+  // Screenshot saved to file (has path but no base64)
+  if (result.path && result.message && !result.base64) {
+    let msg = result.message;
+    if (result.screenshotId) {
+      msg += `\n[Screenshot ID: ${result.screenshotId} - use with upload_image]`;
+    }
+    return text(msg);
+  }
+
+  // Screenshot with inline base64 (MCP flow or no savePath)
+  if (result.screenshotId && result.base64) {
     const dims = result.width && result.height 
       ? `${result.width}x${result.height}` 
       : "unknown dimensions";
@@ -489,7 +530,7 @@ function mapToolToMessage(tool, args, tabId) {
     case "screenshot":
       return { 
         type: "EXECUTE_SCREENSHOT", 
-        savePath: a.savePath,
+        savePath: a.savePath || a.output,  // Accept both savePath (CLI) and output (MCP)
         annotate: a.annotate || false,
         fullpage: a.fullpage || false,
         maxHeight: a["max-height"] || 4000,
@@ -805,6 +846,25 @@ function mapToolToMessage(tool, args, tabId) {
         value: a.value,
         ...baseMsg 
       };
+    case "element.styles":
+      if (!a.selector) throw new Error("selector argument required");
+      return { 
+        type: "GET_ELEMENT_STYLES", 
+        selector: a.selector,
+        ...baseMsg 
+      };
+    case "select": {
+      if (!a.selector) throw new Error("selector argument required");
+      const values = Array.isArray(a.values) ? a.values : (a.values ? [a.values] : []);
+      if (values.length === 0) throw new Error("at least one value required");
+      return { 
+        type: "SELECT_OPTION", 
+        selector: a.selector,
+        values,
+        by: a.by || "value",  // value, label, or index
+        ...baseMsg 
+      };
+    }
     case "ai":
       return { type: "AI_ANALYZE", query: a.query, act: a.act, mode: a.mode, ...baseMsg };
     case "wait":

package/native/host.cjs

@@ -996,7 +996,9 @@ function processInput() {
                 }
               }
               sendToolResponse(socket, originalId, { 
-                message: `Saved to ${savePath} (${finalDims})`
+                message: `Saved to ${savePath} (${finalDims})`,
+                path: savePath,
+                screenshotId: msg.screenshotId,  // Preserve for upload_image workflow
               }, null);
             } catch (e) {
               sendToolResponse(socket, originalId, null, `Failed to save: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -49,14 +49,14 @@
     "uninstall:native": "node scripts/uninstall-native-host.cjs"
   },
   "dependencies": {
-    "@google/generative-ai": "^0.21.0",
+    "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.7.0",
     "buffer": "^6.0.3",
     "crypto-browserify": "^3.12.1",
     "events": "^3.3.0",
     "stream-browserify": "^3.0.0",
     "vite-plugin-node-polyfills": "^0.24.0",
-    "zod": "^3.24.0"
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
@@ -64,7 +64,7 @@
     "@vitest/coverage-v8": "^4.0.16",
     "@vitest/ui": "^4.0.16",
     "typescript": "^5.7.2",
-    "vite": "^6.0.0",
+    "vite": "^7.3.1",
     "vitest": "^4.0.16"
   }
 }