surf-cli 2.7.1 → 2.8.0

package/native/cli.cjs

@@ -3,7 +3,7 @@ const net = require("net");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const { execFileSync, execSync } = require("child_process");
 const { loadConfig, getConfigPath, createStarterConfig } = require("./config.cjs");
 const networkFormatters = require("./formatters/network.cjs");
 const networkStore = require("./network-store.cjs");
@@ -12,10 +12,52 @@ const { executeDoSteps } = require("./do-executor.cjs");
 const { version: VERSION } = require("../package.json");
 
 const IS_WIN = process.platform === "win32";
-const SURF_TMP = IS_WIN ? path.join(os.tmpdir(), "surf") : "/tmp";
-const SOCKET_PATH = IS_WIN ? "//./pipe/surf" : "/tmp/surf.sock";
+const { SOCKET_PATH, SURF_TMP, formatSocketError } = require("./socket-path.cjs");
+const { acquireBrowserLock } = require("./browser-lock.cjs");
 if (IS_WIN) { try { fs.mkdirSync(SURF_TMP, { recursive: true }); } catch {} }
 
+function parseBrowserLockOptions(noLockFlag) {
+  const noLock = noLockFlag || process.env.SURF_NO_LOCK === "1" || process.env.SURF_NO_LOCK === "true";
+  let timeoutMs;
+  if (process.env.SURF_LOCK_TIMEOUT_MS !== undefined) {
+    timeoutMs = Number(process.env.SURF_LOCK_TIMEOUT_MS);
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+      console.error("Error: SURF_LOCK_TIMEOUT_MS must be a non-negative number");
+      process.exit(1);
+    }
+  }
+  return { noLock, timeoutMs };
+}
+
+function installBrowserLock({ noLock, timeoutMs }) {
+  let releaseBrowserLock = () => {};
+  if (!noLock) {
+    try {
+      const lock = acquireBrowserLock(SOCKET_PATH, SURF_TMP, { timeoutMs });
+      releaseBrowserLock = lock.release;
+    } catch (error) {
+      console.error("Error:", error && error.message ? error.message : String(error));
+      process.exit(1);
+    }
+  }
+
+  const release = () => {
+    const releaseCurrent = releaseBrowserLock;
+    releaseBrowserLock = () => {};
+    releaseCurrent();
+  };
+
+  process.once("exit", release);
+  process.once("SIGINT", () => {
+    release();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    release();
+    process.exit(143);
+  });
+}
+
 // ============================================================================
 // Workflow Resolution and Management
 // ============================================================================
@@ -41,7 +83,7 @@ function resolveWorkflow(nameOrPath) {
   if (nameOrPath.includes('|')) {
     return { type: 'inline', content: nameOrPath };
   }
-  
+
   // Check if it's a direct file path (with extension or path separator)
   if (nameOrPath.includes('/') || nameOrPath.includes('\\') || nameOrPath.endsWith('.json')) {
     if (fs.existsSync(nameOrPath)) {
@@ -49,17 +91,17 @@ function resolveWorkflow(nameOrPath) {
     }
     return { type: 'not_found', name: nameOrPath };
   }
-  
+
   // Look up by name in workflow directories
   const searchDirs = getWorkflowDirs();
-  
+
   for (const { path: dir } of searchDirs) {
     const filePath = path.join(dir, `${nameOrPath}.json`);
     if (fs.existsSync(filePath)) {
       return { type: 'file', path: filePath };
     }
   }
-  
+
   return { type: 'not_found', name: nameOrPath };
 }
 
@@ -70,7 +112,7 @@ function resolveWorkflow(nameOrPath) {
 function listWorkflows() {
   const workflows = [];
   const searchDirs = getWorkflowDirs();
-  
+
   for (const { path: dir, scope } of searchDirs) {
     if (fs.existsSync(dir)) {
       try {
@@ -96,7 +138,7 @@ function listWorkflows() {
       }
     }
   }
-  
+
   return workflows;
 }
 
@@ -107,15 +149,15 @@ function listWorkflows() {
  */
 function getWorkflowInfo(name) {
   const resolved = resolveWorkflow(name);
-  
+
   if (resolved.type === 'not_found') {
     return { error: `Workflow not found: ${name}` };
   }
-  
+
   if (resolved.type === 'inline') {
     return { error: 'Cannot get info for inline workflows' };
   }
-  
+
   try {
     const content = JSON.parse(fs.readFileSync(resolved.path, 'utf8'));
     return {
@@ -175,24 +217,24 @@ function validateWorkflowFile(filePath) {
   if (!fs.existsSync(filePath)) {
     return { valid: false, error: `File not found: ${filePath}` };
   }
-  
+
   try {
     const content = fs.readFileSync(filePath, 'utf8');
     const workflow = JSON.parse(content);
-    
+
     // Basic structure validation
     if (!workflow.steps || !Array.isArray(workflow.steps)) {
       return { valid: false, error: "Workflow must have a 'steps' array" };
     }
-    
+
     if (workflow.steps.length === 0) {
       return { valid: false, error: "Workflow has no steps" };
     }
-    
+
     // Validate each step
     for (let i = 0; i < workflow.steps.length; i++) {
       const step = workflow.steps[i];
-      
+
       // Check for loops
       if (step.repeat !== undefined || step.each !== undefined) {
         if (!step.steps || !Array.isArray(step.steps)) {
@@ -200,18 +242,18 @@ function validateWorkflowFile(filePath) {
         }
         continue;
       }
-      
+
       // Regular step must have tool/cmd
       if (!step.tool && !step.cmd) {
         return { valid: false, error: `Step ${i + 1}: must have 'tool' field` };
       }
     }
-    
+
     // Validate args schema if present
     if (workflow.args && typeof workflow.args !== 'object') {
       return { valid: false, error: "'args' must be an object" };
     }
-    
+
     return { valid: true, workflow };
   } catch (e) {
     return { valid: false, error: `Invalid JSON: ${e.message}` };
@@ -226,7 +268,7 @@ function validateWorkflowFile(filePath) {
  */
 function formatStep(step, indent = 0) {
   const pad = '  '.repeat(indent);
-  
+
   if (step.repeat !== undefined) {
     const lines = [`${pad}repeat ${step.repeat} times:`];
     for (const s of step.steps || []) {
@@ -237,7 +279,7 @@ function formatStep(step, indent = 0) {
     }
     return lines.join('\n');
   }
-  
+
   if (step.each !== undefined) {
     const lines = [`${pad}each ${step.each} as ${step.as || 'item'}:`];
     for (const s of step.steps || []) {
@@ -245,24 +287,24 @@ function formatStep(step, indent = 0) {
     }
     return lines.join('\n');
   }
-  
+
   const tool = step.tool || step.cmd;
   const args = step.args || {};
   const argStr = Object.entries(args)
     .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
     .join(' ');
-  
+
   let line = `${pad}${tool}`;
   if (argStr) line += ` ${argStr}`;
   if (step.as) line += ` → ${step.as}`;
-  
+
   return line;
 }
 
 // Cross-platform image resize (macOS: sips, Linux: ImageMagick)
 function resizeImage(filePath, maxSize) {
   const platform = process.platform;
-  
+
   try {
     if (platform === "darwin") {
       // macOS: use sips
@@ -342,10 +384,10 @@ const TOOLS = {
   ai: {
     desc: "AI assistants (ChatGPT, Gemini)",
     commands: {
-      "chatgpt": { 
-        desc: "Send prompt to ChatGPT (uses browser cookies)", 
-        args: ["query"], 
-        opts: { 
+      "chatgpt": {
+        desc: "Send prompt to ChatGPT (uses browser cookies)",
+        args: ["query"],
+        opts: {
           "with-page": "Include current page context",
           model: "Model: gpt-4o, o1, etc.",
           file: "Attach file",
@@ -358,10 +400,10 @@ const TOOLS = {
           { cmd: 'chatgpt "analyze" --model gpt-4o', desc: "Specify model" },
         ]
       },
-      "gemini": { 
-        desc: "Send prompt to Gemini (uses browser cookies)", 
-        args: ["query"], 
-        opts: { 
+      "gemini": {
+        desc: "Send prompt to Gemini (uses browser cookies)",
+        args: ["query"],
+        opts: {
           "with-page": "Include current page context",
           model: "Model: gemini-3-pro (default), gemini-2.5-pro, gemini-2.5-flash",
           file: "Attach file to analyze",
@@ -402,9 +444,9 @@ const TOOLS = {
         args: ["query"],
         opts: {
           "with-page": "Include current page context",
-          model: "Model: auto, fast, expert, thinking (default)",
+          model: "Model: auto, fast (default), expert, grok-4.20-beta",
           "deep-search": "Enable DeepSearch for X post searching",
-          timeout: "Timeout in seconds (default: 300 for thinking models)",
+          timeout: "Timeout in seconds (default: 300)",
           validate: "Check Grok UI and scrape available models (no query sent)",
           "save-models": "Save discovered models to surf.json config"
         },
@@ -447,9 +489,9 @@ const TOOLS = {
           { cmd: 'aistudio.build "crm dashboard" --output ./out', desc: "Build and extract to directory" },
         ]
       },
-      "ai": { 
-        desc: "Analyze page with AI (requires GOOGLE_API_KEY)", 
-        args: ["query"], 
+      "ai": {
+        desc: "Analyze page with AI (requires GOOGLE_API_KEY)",
+        args: ["query"],
         opts: { mode: "Query mode: find|summary|extract (auto-detected)" },
         examples: [
           { cmd: 'ai "find the login button"', desc: "Find element" },
@@ -463,39 +505,39 @@ const TOOLS = {
     desc: "Tab management",
     commands: {
       "tab.list": { desc: "List all open tabs", args: [], examples: [{ cmd: "tab.list", desc: "Show all tabs" }] },
-      "tab.new": { 
-        desc: "Open new tab", 
-        args: ["url"], 
+      "tab.new": {
+        desc: "Open new tab",
+        args: ["url"],
         opts: { urls: "Open multiple URLs" },
         examples: [
           { cmd: 'tab.new "https://google.com"', desc: "Open single tab" },
           { cmd: 'tab.new --urls "https://a.com" "https://b.com"', desc: "Open multiple" },
         ]
       },
-      "tab.switch": { 
-        desc: "Switch to tab by ID or name", 
+      "tab.switch": {
+        desc: "Switch to tab by ID or name",
         args: ["id"],
         examples: [
           { cmd: "tab.switch 123", desc: "Switch by ID" },
           { cmd: 'tab.switch "myTab"', desc: "Switch by name" },
         ]
       },
-      "tab.close": { 
-        desc: "Close tab by ID or name", 
-        args: ["id"], 
+      "tab.close": {
+        desc: "Close tab by ID or name",
+        args: ["id"],
         opts: { ids: "Close multiple tabs" },
         examples: [{ cmd: "tab.close 123", desc: "Close tab" }]
       },
-      "tab.name": { 
-        desc: "Register current tab with a name", 
+      "tab.name": {
+        desc: "Register current tab with a name",
         args: ["name"],
         examples: [{ cmd: 'tab.name "dashboard"', desc: "Name current tab" }]
       },
       "tab.unname": { desc: "Unregister a named tab", args: ["name"] },
       "tab.named": { desc: "List all named tabs", args: [] },
-      "tab.group": { 
-        desc: "Create/add to tab group", 
-        args: [], 
+      "tab.group": {
+        desc: "Create/add to tab group",
+        args: [],
         opts: { name: "Group name", tabs: "Tab IDs (comma-separated)", color: "Group color" },
         examples: [
           { cmd: 'tab.group --name "Work" --color blue', desc: "Group current tab" },
@@ -504,9 +546,9 @@ const TOOLS = {
       },
       "tab.ungroup": { desc: "Remove tabs from group", args: [], opts: { tabs: "Tab IDs (comma-separated)" } },
       "tab.groups": { desc: "List all tab groups", args: [] },
-      "tab.reload": { 
-        desc: "Reload current tab", 
-        args: [], 
+      "tab.reload": {
+        desc: "Reload current tab",
+        args: [],
         opts: { hard: "Bypass cache" },
         examples: [
           { cmd: "tab.reload", desc: "Soft reload" },
@@ -518,30 +560,31 @@ const TOOLS = {
   nav: {
     desc: "Navigation",
     commands: {
-      "navigate": { 
-        desc: "Go to URL", 
+      "navigate": {
+        desc: "Go to URL",
         args: ["url"],
         examples: [{ cmd: 'navigate "https://example.com"', desc: "Go to URL" }]
       },
       "go": { desc: "Alias for navigate", args: ["url"], alias: "navigate" },
-      "back": { 
-        desc: "Go back in history", 
+      "back": {
+        desc: "Go back in history",
         args: [],
         examples: [{ cmd: "back", desc: "Browser back" }]
       },
-      "forward": { 
-        desc: "Go forward in history", 
+      "forward": {
+        desc: "Go forward in history",
         args: [],
         examples: [{ cmd: "forward", desc: "Browser forward" }]
       },
-      "screenshot": { 
-        desc: "Capture screenshot (auto-saves to /tmp by default)", 
-        args: [], 
-        opts: { 
-          output: "Save to file", 
-          selector: "Capture specific element", 
-          annotate: "Draw element labels", 
-          fullpage: "Capture full page", 
+      "screenshot": {
+        desc: "Capture screenshot (auto-saves to /tmp by default)",
+        args: [],
+        opts: {
+          output: "Save to file",
+          selector: "Capture specific element",
+          annotate: "Draw element labels",
+          fullpage: "Capture full page",
+          "full-page": "Capture full page (alias for --fullpage)",
           "max-height": "Max height for fullpage (default: 4000)",
           full: "Skip resize, save at full resolution",
           "max-size": "Max dimension in px (default: 1200)",
@@ -555,23 +598,65 @@ const TOOLS = {
           { cmd: "snap", desc: "Alias for screenshot" },
         ]
       },
+      "record": {
+        desc: "Capture screenshot frames over time and assemble an animated GIF",
+        args: [],
+        opts: {
+          output: "GIF output path (default: /tmp/surf-record-*.gif)",
+          duration: "Capture duration in ms (default: 2000, max: 10000)",
+          fps: "Frames per second (default: 10, max: 30)",
+          trigger: "Optional action before capture: click:<selector> or scroll:<target>",
+          rect: "Crop rectangle x,y,width,height"
+        },
+        examples: [
+          { cmd: "record --duration 2000 --fps 10 --output /tmp/anim.gif", desc: "Record a 2s GIF" },
+          { cmd: 'record --trigger "click:#btn" --output /tmp/click.gif', desc: "Click, then record" },
+        ]
+      },
+      "animate-audit": {
+        desc: "Sample matching elements over time and return a JSON animation timeline",
+        args: [],
+        opts: {
+          selector: "CSS selector to sample (required)",
+          duration: "Capture duration in ms (default: 2000, max: 10000)",
+          fps: "Samples per second (default: 10, max: 30)"
+        },
+        examples: [
+          { cmd: 'animate-audit --selector ".thing" --duration 2000 --fps 10', desc: "Capture a bounded JSON timeline" },
+        ]
+      },
+      "perf-audit": {
+        desc: "Capture layout shift, event, long task, and animation-frame performance entries",
+        args: [],
+        opts: {
+          duration: "Capture duration in ms (default: 3000, max: 10000)",
+          trigger: "Optional action before capture: click:<selector> or scroll:<target>",
+          output: "Save JSON to file"
+        },
+        examples: [
+          { cmd: 'perf-audit --duration 3000 --trigger "click:.cta" --output /tmp/perf.json', desc: "Capture a performance snapshot" },
+        ]
+      },
       "snap": { desc: "Alias for screenshot (auto-saves to /tmp)", args: [], alias: "screenshot" },
     }
   },
   scroll: {
     desc: "Scrolling",
     commands: {
-      "scroll": { 
-        desc: "Scroll in direction", 
-        args: [], 
+      "scroll": {
+        desc: "Scroll in direction",
+        args: ["direction", "pixels"],
         opts: { direction: "up|down|left|right", amount: "Scroll amount (1-10)" },
-        examples: [{ cmd: "scroll --direction down --amount 3", desc: "Scroll down" }]
+        examples: [
+          { cmd: "scroll down 800", desc: "Scroll down 800px" },
+          { cmd: "scroll --direction down --amount 3", desc: "Scroll down" },
+        ]
       },
       "scroll.top": { desc: "Scroll to top of page", args: [], opts: { selector: "Target specific container" } },
       "scroll.bottom": { desc: "Scroll to bottom of page", args: [], opts: { selector: "Target specific container" } },
-      "scroll.to": { 
-        desc: "Scroll element into view", 
-        args: [], 
+      "scroll.to": {
+        desc: "Scroll element into view",
+        args: [],
         opts: { ref: "Element ref" },
         examples: [{ cmd: "scroll.to --ref e5", desc: "Scroll to element" }]
       },
@@ -581,12 +666,12 @@ const TOOLS = {
   page: {
     desc: "Page inspection",
     commands: {
-      "page.read": { 
-        desc: "Get accessibility tree + visible text", 
-        args: [], 
-        opts: { 
-          all: "Include all elements", 
-          ref: "Get specific element", 
+      "page.read": {
+        desc: "Get accessibility tree + visible text",
+        args: [],
+        opts: {
+          all: "Include all elements",
+          ref: "Get specific element",
           "no-text": "Exclude visible text content",
           depth: "Maximum tree depth (default: unlimited)",
           compact: "Remove empty structural elements",
@@ -612,7 +697,7 @@ const TOOLS = {
       "locate.role": {
         desc: "Find element by ARIA role",
         args: ["role"],
-        opts: { 
+        opts: {
           name: "Element name/text",
           action: "Action to perform (click|fill|hover|text)",
           value: "Value for fill action",
@@ -684,14 +769,14 @@ const TOOLS = {
   wait: {
     desc: "Waiting",
     commands: {
-      "wait": { 
-        desc: "Wait N seconds", 
+      "wait": {
+        desc: "Wait N seconds",
         args: ["duration"],
         examples: [{ cmd: "wait 2", desc: "Wait 2 seconds" }]
       },
-      "wait.element": { 
-        desc: "Wait for element to appear", 
-        args: ["selector"], 
+      "wait.element": {
+        desc: "Wait for element to appear",
+        args: ["selector"],
         opts: { timeout: "Timeout in ms" },
         examples: [
           { cmd: 'wait.element ".loading"', desc: "Wait for element" },
@@ -699,9 +784,9 @@ const TOOLS = {
         ]
       },
       "wait.network": { desc: "Wait for network idle", args: [], opts: { timeout: "Timeout in ms" } },
-      "wait.url": { 
-        desc: "Wait for URL to match", 
-        args: ["pattern"], 
+      "wait.url": {
+        desc: "Wait for URL to match",
+        args: ["pattern"],
         opts: { timeout: "Timeout in ms" },
         examples: [{ cmd: 'wait.url "/dashboard"', desc: "Wait for URL pattern" }]
       },
@@ -712,15 +797,15 @@ const TOOLS = {
   input: {
     desc: "Input actions",
     commands: {
-      "click": { 
-        desc: "Click element or coordinates", 
-        args: ["ref"], 
-        opts: { 
-          ref: "Element ref", 
-          x: "X coordinate", 
-          y: "Y coordinate", 
-          button: "left|right|double|triple", 
-          selector: "CSS selector", 
+      "click": {
+        desc: "Click element or coordinates",
+        args: ["ref"],
+        opts: {
+          ref: "Element ref",
+          x: "X coordinate",
+          y: "Y coordinate",
+          button: "left|right|double|triple",
+          selector: "CSS selector",
           index: "Which match (0-indexed) for selector",
         },
         examples: [
@@ -730,15 +815,15 @@ const TOOLS = {
           { cmd: "click --x 100 --y 200", desc: "Click coordinates" },
         ]
       },
-      "type": { 
-        desc: "Type text (uses form.fill when --ref provided for better modal/form support)", 
-        args: ["text"], 
-        opts: { 
+      "type": {
+        desc: "Type text (uses form.fill when --ref provided for better modal/form support)",
+        args: ["text"],
+        opts: {
           into: "Target selector",
-          ref: "Element ref (uses JS DOM method, more reliable for modals)", 
-          submit: "Press enter after", 
-          clear: "Clear first", 
-          method: "cdp|js (default: cdp, but ref uses JS automatically)" 
+          ref: "Element ref (uses JS DOM method, more reliable for modals)",
+          submit: "Press enter after",
+          clear: "Clear first",
+          method: "cdp|js (default: cdp, but ref uses JS automatically)"
         },
         examples: [
           { cmd: 'type "hello world"', desc: "Type at cursor (CDP events)" },
@@ -747,9 +832,9 @@ const TOOLS = {
         ]
       },
       "smart_type": { desc: "Type into specific element (js method)", args: [], opts: { selector: "CSS selector", text: "Text to type", clear: "Clear first (default: true)", submit: "Submit after" } },
-      "key": { 
-        desc: "Press key", 
-        args: ["key"], 
+      "key": {
+        desc: "Press key",
+        args: ["key"],
         examples: [
           { cmd: "key Enter", desc: "Press Enter" },
           { cmd: "key Escape", desc: "Press Escape" },
@@ -764,9 +849,9 @@ const TOOLS = {
   js: {
     desc: "JavaScript execution",
     commands: {
-      "js": { 
-        desc: "Execute JavaScript (use 'return' for values)", 
-        args: ["code"], 
+      "js": {
+        desc: "Execute JavaScript (use 'return' for values)",
+        args: ["code"],
         opts: { file: "Run JS from file" },
         examples: [
           { cmd: 'js "return document.title"', desc: "Get title" },
@@ -779,9 +864,9 @@ const TOOLS = {
   dev: {
     desc: "Dev tools",
     commands: {
-      "console": { 
-        desc: "Read console messages", 
-        args: [], 
+      "console": {
+        desc: "Read console messages",
+        args: [],
         opts: { clear: "Clear after reading", stream: "Continuous output", level: "Filter by level (log,warn,error)", limit: "Max messages" },
         examples: [
           { cmd: "console", desc: "Get recent messages" },
@@ -794,10 +879,10 @@ const TOOLS = {
   network: {
     desc: "Network capture",
     commands: {
-      "network": { 
-        desc: "List captured network requests", 
-        args: [], 
-        opts: { 
+      "network": {
+        desc: "List captured network requests",
+        args: [],
+        opts: {
           origin: "Filter by origin (domain)",
           method: "Filter by method (GET,POST,...)",
           status: "Filter by status (200, 4xx, 5xx)",
@@ -822,16 +907,16 @@ const TOOLS = {
           { cmd: "network -v", desc: "Verbose with headers" },
         ]
       },
-      "network.get": { 
-        desc: "Get full details for a request", 
+      "network.get": {
+        desc: "Get full details for a request",
         args: ["id"],
         opts: {},
         examples: [
           { cmd: "network.get r_001", desc: "Get request details" }
         ]
       },
-      "network.body": { 
-        desc: "Get response body (for piping)", 
+      "network.body": {
+        desc: "Get response body (for piping)",
         args: ["id"],
         opts: { request: "Get request body instead" },
         examples: [
@@ -839,24 +924,24 @@ const TOOLS = {
           { cmd: "network.body r_001 | jq .", desc: "Pipe JSON to jq" }
         ]
       },
-      "network.curl": { 
-        desc: "Generate curl command for request", 
+      "network.curl": {
+        desc: "Generate curl command for request",
         args: ["id"],
         opts: {},
         examples: [
           { cmd: "network.curl r_001", desc: "Generate curl" }
         ]
       },
-      "network.origins": { 
-        desc: "List captured origins with stats", 
+      "network.origins": {
+        desc: "List captured origins with stats",
         args: [],
         opts: { "by-tab": "Group by tab" },
         examples: [
           { cmd: "network.origins", desc: "List origins" }
         ]
       },
-      "network.clear": { 
-        desc: "Clear captured requests", 
+      "network.clear": {
+        desc: "Clear captured requests",
         args: [],
         opts: { before: "Clear before timestamp/duration", origin: "Clear specific origin" },
         examples: [
@@ -864,24 +949,24 @@ const TOOLS = {
           { cmd: "network.clear --before 1h", desc: "Clear older than 1 hour" }
         ]
       },
-      "network.stats": { 
-        desc: "Show capture statistics", 
+      "network.stats": {
+        desc: "Show capture statistics",
         args: [],
         opts: {},
         examples: [
           { cmd: "network.stats", desc: "Show stats" }
         ]
       },
-      "network.export": { 
-        desc: "Export captured requests", 
+      "network.export": {
+        desc: "Export captured requests",
         args: [],
         opts: { jsonl: "Export as JSONL", output: "Output file path" },
         examples: [
           { cmd: "network.export --jsonl --output /tmp/requests.jsonl", desc: "Export as JSONL" }
         ]
       },
-      "network.path": { 
-        desc: "Get file paths for request data", 
+      "network.path": {
+        desc: "Get file paths for request data",
         args: ["id"],
         opts: {},
         examples: [
@@ -893,9 +978,19 @@ const TOOLS = {
   health: {
     desc: "Health checks",
     commands: {
-      "health": { 
-        desc: "Wait for URL or element", 
-        args: [], 
+      "doctor": {
+        desc: "Diagnose native host manifests and socket connectivity",
+        args: [],
+        opts: { browser: "Browser to inspect (default: chrome)", target: "auto|linux|windows", socket: "Socket path to check", json: "Raw diagnostic JSON" },
+        examples: [
+          { cmd: "doctor", desc: "Check default Chrome setup" },
+          { cmd: "doctor --browser all", desc: "Check all supported browsers" },
+          { cmd: "doctor --json", desc: "Machine-readable diagnostics" },
+        ]
+      },
+      "health": {
+        desc: "Wait for URL or element",
+        args: [],
         opts: { url: "URL to check (expects 200)", selector: "CSS selector to wait for", expect: "Expected status code (default: 200)", timeout: "Timeout in ms" },
         examples: [
           { cmd: 'health --url "https://api.example.com"', desc: "Check URL" },
@@ -914,9 +1009,9 @@ const TOOLS = {
     desc: "Browser dialog handling",
     commands: {
       "dialog.accept": { desc: "Accept current dialog", args: [], opts: { text: "Text for prompt input" } },
-      "dialog.dismiss": { 
-        desc: "Dismiss current dialog", 
-        args: [], 
+      "dialog.dismiss": {
+        desc: "Dismiss current dialog",
+        args: [],
         opts: { all: "Dismiss all dialogs repeatedly" },
         examples: [
           { cmd: "dialog.dismiss", desc: "Dismiss once" },
@@ -980,9 +1075,9 @@ const TOOLS = {
   upload: {
     desc: "File upload",
     commands: {
-      "upload": { 
-        desc: "Upload file(s) to input", 
-        args: [], 
+      "upload": {
+        desc: "Upload file(s) to input",
+        args: [],
         opts: { ref: "Element ref", files: "File path(s) comma-separated" },
         examples: [{ cmd: 'upload --ref e5 --files "/path/to/file.pdf"', desc: "Upload file" }]
       },
@@ -991,8 +1086,8 @@ const TOOLS = {
   frame: {
     desc: "Iframe handling",
     commands: {
-      "frame.list": { 
-        desc: "List all frames in page", 
+      "frame.list": {
+        desc: "List all frames in page",
         args: [],
         examples: [{ cmd: "frame.list", desc: "Show frame tree" }]
       },
@@ -1015,9 +1110,9 @@ const TOOLS = {
         args: [],
         examples: [{ cmd: "frame.main", desc: "Exit iframe context" }]
       },
-      "frame.js": { 
-        desc: "Execute JS in specific frame", 
-        args: ["code"], 
+      "frame.js": {
+        desc: "Execute JS in specific frame",
+        args: ["code"],
         opts: { id: "Frame ID from frame.list", file: "Run JS from file" },
         examples: [
           { cmd: 'frame.js "return document.title" --id frame1', desc: "JS in specific frame" },
@@ -1028,25 +1123,37 @@ const TOOLS = {
   cookie: {
     desc: "Cookie management",
     commands: {
-      "cookie.list": { 
-        desc: "List all cookies for current tab's domain", 
+      "cookie.list": {
+        desc: "List all cookies for current tab's domain",
+        args: [],
+        examples: [
+          { cmd: "cookie list", desc: "Show all cookies" },
+          { cmd: "cookie.list", desc: "Dot command form" },
+        ]
+      },
+      "cookie.get": {
+        desc: "Get specific cookie",
         args: [],
-        examples: [{ cmd: "cookie.list", desc: "Show all cookies" }]
+        opts: { name: "Cookie name" },
+        examples: [{ cmd: "cookie get session", desc: "Get cookie" }]
       },
-      "cookie.get": { desc: "Get specific cookie", args: [], opts: { name: "Cookie name" } },
-      "cookie.set": { 
-        desc: "Set a cookie", 
-        args: [], 
+      "cookie.set": {
+        desc: "Set a cookie",
+        args: [],
         opts: { name: "Cookie name", value: "Cookie value", expires: "Expiry date (optional)" },
-        examples: [{ cmd: 'cookie.set --name "session" --value "abc123"', desc: "Set cookie" }]
+        examples: [
+          { cmd: 'cookie set --name "session" --value "abc123"', desc: "Set cookie" },
+          { cmd: 'cookie.set --name "session" --value "abc123"', desc: "Dot command form" },
+        ]
       },
-      "cookie.clear": { 
-        desc: "Clear cookies", 
-        args: [], 
+      "cookie.clear": {
+        desc: "Clear cookies",
+        args: [],
         opts: { name: "Specific cookie (optional)", all: "Clear all for domain" },
         examples: [
-          { cmd: 'cookie.clear --name "session"', desc: "Clear one" },
-          { cmd: "cookie.clear --all", desc: "Clear all" },
+          { cmd: 'cookie delete "session"', desc: "Clear one" },
+          { cmd: "cookie clear --all", desc: "Clear all" },
+          { cmd: 'cookie.clear --name "session"', desc: "Dot command form" },
         ]
       },
     }
@@ -1054,9 +1161,9 @@ const TOOLS = {
   search: {
     desc: "Text search",
     commands: {
-      "search": { 
-        desc: "Search for text in page", 
-        args: ["term"], 
+      "search": {
+        desc: "Search for text in page",
+        args: ["term"],
         opts: { "case-sensitive": "Case-sensitive match", limit: "Max results" },
         examples: [
           { cmd: 'search "login"', desc: "Find text" },
@@ -1070,9 +1177,9 @@ const TOOLS = {
   batch: {
     desc: "Batch execution",
     commands: {
-      "batch": { 
-        desc: "Execute multiple actions", 
-        args: [], 
+      "batch": {
+        desc: "Execute multiple actions",
+        args: [],
         opts: { actions: "JSON array of actions", file: "Path to actions JSON file" },
         examples: [
           { cmd: 'batch --actions \'[{"type":"click","ref":"e1"},{"type":"wait","ms":500}]\'', desc: "Inline actions" },
@@ -1130,9 +1237,9 @@ const TOOLS = {
   zoom: {
     desc: "Zoom control",
     commands: {
-      "zoom": { 
-        desc: "Get or set zoom level", 
-        args: [], 
+      "zoom": {
+        desc: "Get or set zoom level",
+        args: [],
         opts: { level: "Zoom level (e.g., 1.5 for 150%)", reset: "Reset to default zoom" },
         examples: [
           { cmd: "zoom", desc: "Get current zoom" },
@@ -1145,11 +1252,14 @@ const TOOLS = {
   resize: {
     desc: "Window management",
     commands: {
-      "resize": { 
-        desc: "Resize browser window", 
-        args: [], 
+      "resize": {
+        desc: "Resize browser window",
+        args: ["width", "height"],
         opts: { width: "Window width", height: "Window height" },
-        examples: [{ cmd: "resize --width 1280 --height 720", desc: "Set size" }]
+        examples: [
+          { cmd: "resize 1280 720", desc: "Set size" },
+          { cmd: "resize --width 1280 --height 720", desc: "Set size with flags" },
+        ]
       },
     }
   },
@@ -1164,14 +1274,14 @@ const TOOLS = {
   history: {
     desc: "Browser history",
     commands: {
-      "history.list": { 
-        desc: "Recent history", 
-        args: [], 
+      "history.list": {
+        desc: "Recent history",
+        args: [],
         opts: { limit: "Max results" },
         examples: [{ cmd: "history.list --limit 20", desc: "Last 20 items" }]
       },
-      "history.search": { 
-        desc: "Search history", 
+      "history.search": {
+        desc: "Search history",
         args: ["query"],
         examples: [{ cmd: 'history.search "github"', desc: "Search history" }]
       },
@@ -1180,10 +1290,10 @@ const TOOLS = {
   window: {
     desc: "Window management (isolate agent from your browsing)",
     commands: {
-      "window.new": { 
-        desc: "Create new browser window", 
-        args: ["url"], 
-        opts: { 
+      "window.new": {
+        desc: "Create new browser window",
+        args: ["url"],
+        opts: {
           width: "Window width",
           height: "Window height",
           incognito: "Open incognito window",
@@ -1195,28 +1305,28 @@ const TOOLS = {
           { cmd: 'window.new --incognito', desc: "Incognito window" },
         ]
       },
-      "window.list": { 
-        desc: "List all browser windows", 
+      "window.list": {
+        desc: "List all browser windows",
         args: [],
         opts: { tabs: "Include tab details" },
         examples: [{ cmd: "window.list", desc: "Show all windows" }]
       },
-      "window.focus": { 
-        desc: "Focus a window by ID", 
+      "window.focus": {
+        desc: "Focus a window by ID",
         args: ["id"],
         examples: [{ cmd: "window.focus 123", desc: "Focus window" }]
       },
-      "window.close": { 
-        desc: "Close a window by ID", 
+      "window.close": {
+        desc: "Close a window by ID",
         args: ["id"],
         examples: [{ cmd: "window.close 123", desc: "Close window" }]
       },
-      "window.resize": { 
-        desc: "Resize or reposition a window", 
-        args: [], 
-        opts: { 
-          id: "Window ID (required)", 
-          width: "Window width", 
+      "window.resize": {
+        desc: "Resize or reposition a window",
+        args: [],
+        opts: {
+          id: "Window ID (required)",
+          width: "Window width",
           height: "Window height",
           left: "Window X position",
           top: "Window Y position",
@@ -1263,10 +1373,17 @@ Use --index to select from multiple matches:
     content: `Cookies are scoped to the current tab's domain.
 
 Commands:
-  cookie.list           List all cookies
-  cookie.get --name X   Get specific cookie
-  cookie.set            Set a cookie
-  cookie.clear          Clear cookies
+  cookie list           List all cookies
+  cookie get X          Get specific cookie
+  cookie set            Set a cookie
+  cookie clear --all    Clear all cookies
+  cookie delete X       Clear one cookie
+
+Dot commands remain supported:
+  cookie.list
+  cookie.get --name X
+  cookie.set
+  cookie.clear
 
 Notes:
   - HttpOnly cookies are accessible
@@ -1298,6 +1415,7 @@ Commands:
   screenshot --output file.png                          Basic screenshot
   screenshot --annotate --output file.png               With element labels
   screenshot --fullpage --output file.png               Full page capture
+  screenshot --full-page --output file.png              Full page capture (alias)
   screenshot --annotate --fullpage --output file.png    Full page with labels
   snap                                                  Auto-save to /tmp
 
@@ -1305,6 +1423,7 @@ Options:
   --output      Save path
   --annotate    Draw element refs
   --fullpage    Capture entire page
+  --full-page   Capture entire page (alias)
   --max-height  Max height for fullpage (default: 4000)`
   },
   automation: {
@@ -1327,7 +1446,7 @@ Wait for dynamic content:
 
 Scroll and capture:
   scroll.bottom
-  screenshot --fullpage --output full.png`
+  screenshot --full-page --output full.png`
   },
   windows: {
     title: "Window Isolation",
@@ -1346,7 +1465,7 @@ All commands in that window:
 
 Manage windows:
   surf window.list              # List all windows
-  surf window.list --tabs       # Include tab details  
+  surf window.list --tabs       # Include tab details
   surf window.focus 123         # Bring window to front
   surf window.close 123         # Close when done
 
@@ -1439,7 +1558,7 @@ Exclude text content:
 };
 
 const ALL_SOCKET_TOOLS = [
-  "ai", "screenshot", "navigate",
+  "ai", "screenshot", "record", "animate-audit", "perf-audit", "navigate",
   "form_input", "find_and_type", "autocomplete", "set_value", "smart_type",
   "scroll_to_position", "get_scroll_info", "close_dialogs", "page_state",
   "javascript_tool", "health", "smoke",
@@ -1453,8 +1572,8 @@ const ALL_SOCKET_TOOLS = [
   "scroll.top", "scroll.bottom", "scroll.to", "scroll.info",
   "wait.element", "wait.network", "wait.url", "wait.dom", "wait.load",
   "click", "hover", "drag",
-  "js", "console", "network", 
-  "network.get", "network.body", "network.curl", "network.origins", 
+  "js", "console", "network",
+  "network.get", "network.body", "network.curl", "network.origins",
   "network.clear", "network.stats", "network.export", "network.path",
   "dialog.accept", "dialog.dismiss", "dialog.info",
   "emulate.network", "emulate.cpu", "emulate.geo", "emulate.device", "emulate.viewport", "emulate.touch",
@@ -1497,6 +1616,9 @@ const SEE_ALSO = {
   "perf.metrics": ["perf.start", "console", "network"],
   "navigate": ["wait.load", "page.read"],
   "screenshot": ["page.read", "scroll.bottom for fullpage"],
+  "record": ["screenshot", "animate-audit", "perf-audit"],
+  "animate-audit": ["screenshot", "record", "perf-audit", "js"],
+  "perf-audit": ["record", "animate-audit", "perf.metrics", "console"],
   "search": ["locate.text", "page.read"],
   "wait.element": ["wait.load", "wait.network"],
   "wait.load": ["wait.element", "wait.network"],
@@ -1516,10 +1638,14 @@ Common Commands:
   click <ref>        Click element by ref or selector
   type <text>        Type text at cursor or into element
   screenshot         Capture screenshot (alias: snap)
+  record             Capture screenshot frames into an animated GIF
+  animate-audit      JSON timeline of element animation/style samples
+  perf-audit         PerformanceObserver snapshot for motion/jank debugging
   page.read          Get page accessibility tree (alias: read)
   locate.role <role> Find element by ARIA role
   search <term>      Search for text in page (alias: find)
   window.new <url>   Create isolated browser window
+  doctor             Diagnose native host/socket setup
   wait <seconds>     Wait N seconds
 
 Quick Examples:
@@ -1534,6 +1660,7 @@ Quick Examples:
 
 More Help:
   surf --help-full           All commands
+  surf --llm-context         Compact reference for AI agents
   surf --help-topic <topic>  Topic guide (refs, semantic, frames, devices...)
   surf <command> --help      Command details
   surf --find <query>        Search for commands
@@ -1541,6 +1668,34 @@ More Help:
 `);
 };
 
+const showLlmContext = () => {
+  console.log(`SURF CLI LLM CONTEXT
+Purpose: control Chrome from shell. Commands are \`surf <command> [args] [options]\`.
+Core loop: navigate -> wait/read -> act -> screenshot/read.
+Navigate: surf navigate "https://example.com"    # alias: surf go "..."
+Wait after navigation: surf wait 2                # or wait.load for load complete
+Read DOM/refs: surf page.read --depth 3 --compact # alias: surf read
+Refs: use e1/e2 refs from page.read; prefer refs over CSS when available.
+Click ref: surf click e5
+Click selector/coords: surf click --selector ".btn" | surf click 100 200
+Type: surf type "text" --submit                  # use --ref e5 to target a field
+Screenshot: surf screenshot /tmp/shot.png         # auto-saves to /tmp if no path
+Full page screenshot: surf screenshot --full-page /tmp/full.png
+Record animation: surf record --duration 2000 --fps 10 --output /tmp/anim.gif
+Animation audit: surf animate-audit --selector ".thing" --duration 2000 --fps 10
+Performance audit: surf perf-audit --duration 3000 --trigger "click:.cta" --output /tmp/perf.json
+JavaScript: surf js "return document.title"
+Scroll: surf scroll down 800 | surf scroll up 400 | surf scroll bottom | surf scroll top
+Find by semantics: surf locate.role button --name "Submit" --action click
+Device/viewport: surf emulate.device "iPhone 14" | surf resize 375 812
+Cookies: surf cookie list | surf cookie get "name" | surf cookie delete "name"
+Window isolation: surf window.new "https://example.com" then pass --window-id <id>
+Concurrency: surf serializes commands per socket; use --no-lock only for intentional bypass
+Doctor: surf doctor --browser all              # native host/socket diagnostics
+Workflow: surf do 'go "https://example.com" | wait 2 | read | click e5 | screenshot'
+More help: surf --help-full | surf <command> --help | surf --help-topic refs | surf --find <query>`);
+};
+
 const showFullHelp = () => {
   console.log(`surf v${VERSION} - Browser automation CLI
 
@@ -1565,6 +1720,7 @@ Options:
   --json            Output raw JSON
   --auto-capture    On error: capture screenshot + console to /tmp
   --soft-fail       On error: warn and exit 0 (for non-critical commands)
+  --no-lock         Bypass the per-socket browser request lock
 
 Script Mode:
   surf --script <file>     Run workflow from JSON
@@ -1673,7 +1829,7 @@ const showToolHelp = (toolName) => {
 const fuzzyFind = (query) => {
   const terms = query.toLowerCase().split(/\s+/);
   const results = [];
-  
+
   for (const [groupName, group] of Object.entries(TOOLS)) {
     for (const [cmd, info] of Object.entries(group.commands)) {
       if (info.alias) continue;
@@ -1684,7 +1840,7 @@ const fuzzyFind = (query) => {
       }
     }
   }
-  
+
   return results.sort((a, b) => b.score - a.score);
 };
 
@@ -1732,6 +1888,11 @@ const showAllTools = () => {
   console.log(`\n  Total: ${ALL_SOCKET_TOOLS.length} commands\n`);
 };
 
+if (args[0] === "--llm-context") {
+  showLlmContext();
+  process.exit(0);
+}
+
 if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
   showBasicHelp();
   process.exit(0);
@@ -1790,11 +1951,17 @@ if (args[0] === "extension-path" || args[0] === "path") {
   process.exit(0);
 }
 
+if (args[0] === "doctor") {
+  const { runDoctorCli } = require("./doctor.cjs");
+  runDoctorCli(args.slice(1)).then((code) => process.exit(code));
+  return;
+}
+
 if (args[0] === "install") {
   const { spawnSync } = require("child_process");
   const scriptPath = require("path").resolve(__dirname, "../scripts/install-native-host.cjs");
   const installArgs = args.slice(1);
-  
+
   if (installArgs.length === 0 || installArgs[0] === "--help" || installArgs[0] === "-h") {
     console.log(`
 Usage: surf install <extension-id> [options]
@@ -1809,11 +1976,14 @@ Options:
   -b, --browser   Browser(s) to install for (default: chrome)
                   Values: chrome, chromium, brave, edge, arc, helium, all
                   Multiple: --browser chrome,brave
+  --target        Install target: auto, linux, windows
+                  On WSL2, auto installs for Windows Chrome. Use linux for WSLg/Linux browsers.
 
 Examples:
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl --browser brave
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl --browser all
+  surf install hnfbepgmaoklhekckbpjnleifhahkcpl --target linux
 `);
     process.exit(0);
   }
@@ -1828,7 +1998,7 @@ if (args[0] === "uninstall") {
   const { spawnSync } = require("child_process");
   const scriptPath = require("path").resolve(__dirname, "../scripts/uninstall-native-host.cjs");
   const uninstallArgs = args.slice(1);
-  
+
   if (uninstallArgs.includes("--help") || uninstallArgs.includes("-h")) {
     console.log(`
 Usage: surf uninstall [options]
@@ -1839,11 +2009,14 @@ Options:
   -b, --browser   Browser(s) to uninstall from (default: chrome)
                   Values: chrome, chromium, brave, edge, arc, helium, all
   -a, --all       Uninstall from all browsers and remove wrapper
+  --target        Install target to remove: auto, linux, windows
+                  On WSL2, auto removes Windows-browser manifests. Use linux for WSLg/Linux browsers.
 
 Examples:
   surf uninstall
   surf uninstall --browser brave
   surf uninstall --all
+  surf uninstall --target linux
 `);
     process.exit(0);
   }
@@ -1977,7 +2150,7 @@ if (args.includes("--script")) {
           }
         }
       });
-      sock.on("error", (e) => reject(e));
+      sock.on("error", (e) => reject(new Error(formatSocketError(e))));
       let timeoutId;
       timeoutId = setTimeout(() => { sock.destroy(); reject(new Error("Timeout")); }, 30000);
       sock.on("close", () => clearTimeout(timeoutId));
@@ -2046,6 +2219,10 @@ if (args.includes("--script")) {
     process.exit(failed > 0 ? 1 : 0);
   };
 
+  if (!dryRun) {
+    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")));
+  }
+
   runScript();
   return;
 }
@@ -2063,13 +2240,13 @@ if (args[0] === "do") {
   let wantJson = false;
   let tabId = undefined;
   let windowId = undefined;
-  
+
   // Reserved flags that aren't workflow args
-  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id'];
-  
+  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id', 'no-lock'];
+
   // Workflow-specific args (collected for variable substitution)
   const workflowArgs = {};
-  
+
   // Parse do-specific arguments
   for (let i = 0; i < doArgs.length; i++) {
     const arg = doArgs[i];
@@ -2117,7 +2294,7 @@ if (args[0] === "do") {
       commandsInput = arg;
     }
   }
-  
+
   if (!commandsInput && !fileInput) {
     console.error("Error: commands string, workflow name, or --file required");
     console.error('Usage: surf do \'go "url" | click e5\'');
@@ -2125,11 +2302,11 @@ if (args[0] === "do") {
     console.error("       surf do my-workflow --arg1 value1 --arg2 value2");
     process.exit(1);
   }
-  
+
   let steps;
   let workflow = null; // Full workflow object (for arg validation)
   let workflowName = null;
-  
+
   try {
     if (fileInput) {
       // Explicit file path via --file
@@ -2143,7 +2320,7 @@ if (args[0] === "do") {
     } else {
       // Resolve: inline | file path | named workflow
       const resolved = resolveWorkflow(commandsInput);
-      
+
       if (resolved.type === 'inline') {
         // Inline pipe syntax
         steps = parseDoCommands(resolved.content);
@@ -2166,13 +2343,13 @@ if (args[0] === "do") {
         }
       }
     }
-    
+
     // Process workflow file if loaded
     if (workflow) {
       if (!workflow.steps || !Array.isArray(workflow.steps)) {
         throw new Error("Workflow must have a 'steps' array");
       }
-      
+
       // Validate required args
       const argErrors = validateWorkflowArgs(workflow, workflowArgs);
       if (argErrors.length > 0) {
@@ -2190,7 +2367,7 @@ if (args[0] === "do") {
         console.error(`\nRun 'surf workflow.info ${workflowName}' for details.`);
         process.exit(1);
       }
-      
+
       // Convert steps: support both { tool, args } and { cmd, args } formats
       // Also preserve loop steps as-is
       steps = workflow.steps.map(s => {
@@ -2199,16 +2376,16 @@ if (args[0] === "do") {
           const convertSteps = (stepsArr) => stepsArr.map(ns => {
             if (ns.repeat !== undefined || ns.each !== undefined) {
               // Recursively convert nested loop steps and until condition
-              return { 
-                ...ns, 
+              return {
+                ...ns,
                 steps: convertSteps(ns.steps || []),
                 until: ns.until ? { cmd: ns.until.tool || ns.until.cmd, args: ns.until.args || {} } : undefined
               };
             }
             return { cmd: ns.tool || ns.cmd, args: ns.args || {}, as: ns.as };
           });
-          return { 
-            ...s, 
+          return {
+            ...s,
             steps: convertSteps(s.steps || []),
             until: s.until ? { cmd: s.until.tool || s.until.cmd, args: s.until.args || {} } : undefined
           };
@@ -2220,15 +2397,15 @@ if (args[0] === "do") {
     console.error(`Error: Failed to parse workflow: ${e.message}`);
     process.exit(1);
   }
-  
+
   if (!steps || steps.length === 0) {
     console.error("Error: No commands found in workflow");
     process.exit(1);
   }
-  
+
   // Apply arg defaults
   const vars = workflow ? applyArgDefaults(workflow, workflowArgs) : workflowArgs;
-  
+
   // Validate with --dry-run
   if (dryRun) {
     if (workflowName) {
@@ -2247,7 +2424,9 @@ if (args[0] === "do") {
     }
     process.exit(0);
   }
-  
+
+  installBrowserLock(parseBrowserLockOptions(doArgs.includes("--no-lock")));
+
   if (!wantJson) {
     if (workflowName) {
       console.log(`Running workflow: ${workflowName} (${steps.length} steps)...\n`);
@@ -2255,7 +2434,7 @@ if (args[0] === "do") {
       console.log(`Running workflow (${steps.length} steps)...\n`);
     }
   }
-  
+
   const runWorkflow = async () => {
     const result = await executeDoSteps(steps, {
       onError,
@@ -2268,13 +2447,13 @@ if (args[0] === "do") {
         windowId,
       },
     });
-    
+
     // Print summary
     if (wantJson) {
       console.log(JSON.stringify(result, null, 2));
       process.exit(result.status === "completed" ? 0 : 1);
     }
-    
+
     console.log("");
     if (result.status === "completed") {
       console.log(`Completed: ${result.completedSteps}/${result.totalSteps} steps (${result.totalMs}ms)`);
@@ -2288,7 +2467,7 @@ if (args[0] === "do") {
       process.exit(1);
     }
   };
-  
+
   runWorkflow();
   return;
 }
@@ -2296,7 +2475,7 @@ if (args[0] === "do") {
 // Handle workflow management commands
 if (args[0] === "workflow.list") {
   const workflows = listWorkflows();
-  
+
   if (workflows.length === 0) {
     console.log("No workflows found.");
     console.log(`\nWorkflow directories:`);
@@ -2306,13 +2485,13 @@ if (args[0] === "workflow.list") {
     console.log(`\nCreate a workflow JSON file in one of these directories.`);
     process.exit(0);
   }
-  
+
   // Group by scope
   const byScope = { project: [], user: [] };
   for (const w of workflows) {
     byScope[w.scope].push(w);
   }
-  
+
   if (byScope.user.length > 0) {
     console.log(`User Workflows (~/.surf/workflows/):`);
     for (const w of byScope.user) {
@@ -2321,7 +2500,7 @@ if (args[0] === "workflow.list") {
     }
     console.log("");
   }
-  
+
   if (byScope.project.length > 0) {
     console.log(`Project Workflows (./.surf/workflows/):`);
     for (const w of byScope.project) {
@@ -2330,7 +2509,7 @@ if (args[0] === "workflow.list") {
     }
     console.log("");
   }
-  
+
   console.log(`Run 'surf workflow.info <name>' for details.`);
   process.exit(0);
 }
@@ -2342,16 +2521,16 @@ if (args[0] === "workflow.info") {
     console.error("Usage: surf workflow.info <name>");
     process.exit(1);
   }
-  
+
   const info = getWorkflowInfo(name);
   if (info.error) {
     console.error(`Error: ${info.error}`);
     process.exit(1);
   }
-  
+
   console.log(`${info.name}${info.description ? ` - ${info.description}` : ''}`);
   console.log("");
-  
+
   // Arguments
   if (info.args && Object.keys(info.args).length > 0) {
     console.log("Arguments:");
@@ -2364,18 +2543,18 @@ if (args[0] === "workflow.info") {
     }
     console.log("");
   }
-  
+
   // Steps
   console.log(`Steps (${info.steps.length}):`);
   info.steps.forEach((step, i) => {
     console.log(`  ${i + 1}. ${formatStep(step)}`);
   });
   console.log("");
-  
+
   // Location
   console.log(`Location: ${info.path}`);
   console.log("");
-  
+
   // Example run command
   const argExample = Object.entries(info.args || {})
     .filter(([_, spec]) => spec.required)
@@ -2383,7 +2562,7 @@ if (args[0] === "workflow.info") {
     .join(' ');
   console.log(`Run:`);
   console.log(`  surf do ${name}${argExample ? ' ' + argExample : ''}`);
-  
+
   process.exit(0);
 }
 
@@ -2394,9 +2573,9 @@ if (args[0] === "workflow.validate") {
     console.error("Usage: surf workflow.validate <file>");
     process.exit(1);
   }
-  
+
   const result = validateWorkflowFile(filePath);
-  
+
   if (result.valid) {
     console.log(`✓ Valid workflow: ${filePath}`);
     console.log(`  Name: ${result.workflow.name || '(unnamed)'}`);
@@ -2414,7 +2593,7 @@ if (args[0] === "workflow.validate") {
   }
 }
 
-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", "no-auto-wait"];
+const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "full-page", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save", "no-auto-wait", "no-lock"];
 
 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"];
 
@@ -2462,6 +2641,22 @@ let { positional, options } = parseArgs(args);
 let tool = positional[0];
 let firstArg = positional[1];
 
+if (tool === "cookie" && firstArg) {
+  const cookieSubcommands = {
+    list: "cookie.list",
+    get: "cookie.get",
+    set: "cookie.set",
+    clear: "cookie.clear",
+    delete: "cookie.clear",
+  };
+  const cookieTool = cookieSubcommands[firstArg];
+  if (cookieTool) {
+    tool = cookieTool;
+    positional = [tool, ...positional.slice(2)];
+    firstArg = positional[1];
+  }
+}
+
 if (!tool) {
   console.error("Error: No command specified");
   process.exit(1);
@@ -2478,9 +2673,14 @@ tool = ALIASES[tool] || tool;
 // 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
+if (options["full-page"] === true) {
+  options.fullpage = true;
+  delete options["full-page"];
+}
+
 const config = loadConfig();
 const autoSaveEnabled = config.autoSaveScreenshots !== false && !options["no-save"];
-if (tool === "screenshot" && !options.output && !options.savePath && autoSaveEnabled) {
+if (tool === "screenshot" && !options.output && !options.savePath && firstArg === undefined && autoSaveEnabled) {
   options.savePath = path.join(SURF_TMP, `surf-snap-${Date.now()}.png`);
 }
 
@@ -2541,6 +2741,8 @@ const PRIMARY_ARG_MAP = {
   "emulate.cpu": "rate",
   search: "term",
   find: "term",
+  "cookie.get": "name",
+  "cookie.clear": "name",
   "wait.element": "selector",
   "wait.url": "pattern",
   zoom: "level",
@@ -2563,6 +2765,19 @@ const PRIMARY_ARG_MAP = {
 
 const toolArgs = { ...options };
 
+if (tool === "scroll" && firstArg) {
+  if (firstArg === "top" || firstArg === "bottom") {
+    tool = `scroll.${firstArg}`;
+    firstArg = undefined;
+  } else if (["up", "down", "left", "right"].includes(firstArg)) {
+    if (toolArgs.direction === undefined) toolArgs.direction = firstArg;
+    if (positional[2] !== undefined && /^-?\d+$/.test(positional[2]) && toolArgs.amount === undefined && toolArgs.scroll_amount === undefined) {
+      toolArgs.scroll_pixels = parseInt(positional[2], 10);
+    }
+    firstArg = undefined;
+  }
+}
+
 if (tool === "click" && firstArg) {
   if (/^e\d+$/.test(firstArg)) {
     toolArgs.ref = firstArg;
@@ -2574,6 +2789,30 @@ if (tool === "click" && firstArg) {
   }
 }
 
+if (tool === "resize") {
+  if (firstArg !== undefined && toolArgs.width === undefined) {
+    let val = firstArg;
+    if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
+    toolArgs.width = val;
+  }
+  if (positional[2] !== undefined && toolArgs.height === undefined) {
+    let val = positional[2];
+    if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
+    toolArgs.height = val;
+  }
+  firstArg = undefined;
+}
+
+if (tool === "screenshot" && firstArg !== undefined && toolArgs.output === undefined && toolArgs.savePath === undefined) {
+  toolArgs.savePath = firstArg;
+  firstArg = undefined;
+}
+
+if (tool === "record" && firstArg !== undefined && toolArgs.output === undefined) {
+  toolArgs.output = firstArg;
+  firstArg = undefined;
+}
+
 if (firstArg !== undefined) {
   const primaryKey = PRIMARY_ARG_MAP[tool];
   if (primaryKey && toolArgs[primaryKey] === undefined) {
@@ -2646,6 +2885,9 @@ delete toolArgs["no-screenshot"];
 const softFail = toolArgs["soft-fail"] === true;
 delete toolArgs["soft-fail"];
 
+const lockOptions = parseBrowserLockOptions(toolArgs["no-lock"] === true);
+delete toolArgs["no-lock"];
+
 if (!noScreenshot && AUTO_SCREENSHOT_TOOLS.includes(tool)) {
   toolArgs.autoScreenshot = true;
 }
@@ -2667,12 +2909,20 @@ if (tool === "gemini") {
     toolArgs.file = path.resolve(toolArgs.file);
   }
 }
+if (tool === "chatgpt" && toolArgs.file) {
+  if (Array.isArray(toolArgs.file)) {
+    toolArgs.file = toolArgs.file.map((filePath) => path.resolve(filePath));
+  } else if (typeof toolArgs.file === "string") {
+    toolArgs.file = path.resolve(toolArgs.file);
+  }
+}
+
+if ((tool === "screenshot" || tool === "record" || tool === "perf-audit") && outputPath && typeof outputPath !== "string") {
+  console.error("Error: --output requires a file path");
+  process.exit(1);
+}
 
 if (tool === "screenshot" && outputPath) {
-  if (typeof outputPath !== "string") {
-    console.error("Error: --output requires a file path");
-    process.exit(1);
-  }
   toolArgs.savePath = outputPath;
   if (options.full) toolArgs.full = true;
   if (options["max-size"]) toolArgs["max-size"] = options["max-size"];
@@ -2794,11 +3044,7 @@ if (streamMode && (tool === "console" || tool === "network")) {
   });
 
   sock.on("error", (e) => {
-    if (e.code === "ENOENT") {
-      console.error("Error: Socket not found. Is Chrome running with the extension?");
-    } else {
-      console.error("Error:", e.message);
-    }
+    console.error("Error:", formatSocketError(e));
     process.exit(1);
   });
 
@@ -2819,7 +3065,7 @@ const request = {
   ...globalOpts,
 };
 
-const sendRequest = (toolName, toolArgs = {}) => {
+const sendRequest = (toolName, toolArgs = {}, timeoutMs = 5000) => {
   return new Promise((resolve, reject) => {
     const sock = net.createConnection(SOCKET_PATH, () => {
       const req = {
@@ -2853,13 +3099,140 @@ const sendRequest = (toolName, toolArgs = {}) => {
         }
       }
     });
-    sock.on("error", (e) => reject(e));
+    sock.on("error", (e) => reject(new Error(formatSocketError(e))));
     let timeoutId;
-    timeoutId = setTimeout(() => { sock.destroy(); reject(new Error("Timeout")); }, 5000);
+    timeoutId = setTimeout(() => { sock.destroy(); reject(new Error("Timeout")); }, timeoutMs);
     sock.on("close", () => clearTimeout(timeoutId));
   });
 };
 
+function parseRecordNumber(value, fallback, name, min, max) {
+  if (value === undefined) return fallback;
+  if (typeof value === "boolean") throw new Error(`${name} must be a number`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be between ${min} and ${max}`);
+  }
+  return parsed;
+}
+
+function parseRecordRect(value) {
+  if (value === undefined) return null;
+  if (typeof value !== "string") throw new Error("rect must be x,y,width,height");
+  const parts = value.split(",").map((part) => Number(part.trim()));
+  if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
+    throw new Error("rect must be x,y,width,height");
+  }
+  const [x, y, width, height] = parts;
+  if (x < 0 || y < 0 || width <= 0 || height <= 0) {
+    throw new Error("rect must use non-negative x/y and positive width/height");
+  }
+  return { x, y, width, height, crop: `${width}x${height}+${x}+${y}` };
+}
+
+function assertToolOk(response, context) {
+  if (!response?.error) return;
+  const message = response.error.content?.[0]?.text || response.error.message || JSON.stringify(response.error);
+  throw new Error(`${context}: ${message}`);
+}
+
+function assembleRecordGif(framePaths, output, fps, rect) {
+  const delay = Math.max(1, Math.round(100 / fps));
+  const args = ["-delay", String(delay), "-loop", "0", ...framePaths];
+  if (rect) args.push("-crop", rect.crop, "+repage");
+  args.push(output);
+
+  try {
+    execFileSync("magick", args, { stdio: "pipe" });
+    return "magick";
+  } catch (magickError) {
+    try {
+      execFileSync("convert", args, { stdio: "pipe" });
+      return "convert";
+    } catch (convertError) {
+      const detail = convertError && convertError.message ? convertError.message : String(convertError);
+      throw new Error(`Failed to assemble GIF with ImageMagick. Install ImageMagick (magick or convert). Last error: ${detail}`);
+    }
+  }
+}
+
+async function runRecord() {
+  const durationMs = parseRecordNumber(toolArgs.duration, 2000, "duration", 100, 10000);
+  const fps = parseRecordNumber(toolArgs.fps, 10, "fps", 1, 30);
+  const rect = parseRecordRect(toolArgs.rect);
+  const output = path.resolve(outputPath || path.join(SURF_TMP, `surf-record-${Date.now()}.gif`));
+  const frameCount = Math.max(1, Math.ceil((durationMs / 1000) * fps));
+  const frameDir = fs.mkdtempSync(path.join(SURF_TMP, "surf-record-"));
+  const framePaths = [];
+  let trigger = null;
+
+  try {
+    if (toolArgs.trigger !== undefined) {
+      trigger = await runRecordTrigger(toolArgs.trigger);
+    }
+
+    const startedAt = Date.now();
+    for (let i = 0; i < frameCount; i++) {
+      const framePath = path.join(frameDir, `frame-${String(i).padStart(4, "0")}.png`);
+      const response = await sendRequest("screenshot", {
+        savePath: framePath,
+        full: toolArgs.full,
+        "max-size": toolArgs["max-size"],
+      }, 30000);
+      assertToolOk(response, `record frame ${i + 1}`);
+      framePaths.push(framePath);
+
+      if (i < frameCount - 1) {
+        const nextFrameAt = startedAt + Math.round(((i + 1) * durationMs) / frameCount);
+        const waitMs = nextFrameAt - Date.now();
+        if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+      }
+    }
+
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    const imageMagick = assembleRecordGif(framePaths, output, fps, rect);
+    const result = { output, frames: framePaths.length, durationMs, fps, imageMagick, ...(trigger && { trigger }), ...(rect && { rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } }) };
+
+    if (wantJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Saved recording to ${output} (${result.frames} frames, ${durationMs}ms @ ${fps}fps)`);
+    }
+  } finally {
+    fs.rmSync(frameDir, { recursive: true, force: true });
+  }
+}
+
+async function runRecordTrigger(trigger) {
+  if (typeof trigger !== "string") throw new Error("trigger must be action:target");
+  const separator = trigger.indexOf(":");
+  if (separator === -1) throw new Error("trigger must be action:target");
+  const action = trigger.slice(0, separator).trim();
+  const target = trigger.slice(separator + 1).trim();
+  if (!action || !target) throw new Error("trigger must be action:target");
+
+  if (action === "click") {
+    const response = await sendRequest("click", { selector: target }, 30000);
+    assertToolOk(response, "record trigger");
+    return { action, selector: target };
+  }
+
+  if (action === "scroll") {
+    let response;
+    if (["up", "down", "left", "right"].includes(target)) {
+      response = await sendRequest("scroll", { direction: target }, 30000);
+    } else if (target === "top" || target === "bottom") {
+      response = await sendRequest(`scroll.${target}`, {}, 30000);
+    } else {
+      response = await sendRequest("scroll.bottom", { selector: target }, 30000);
+    }
+    assertToolOk(response, "record trigger");
+    return { action, target };
+  }
+
+  throw new Error("trigger action must be click or scroll");
+}
+
 const performAutoCapture = async () => {
   const timestamp = Date.now();
   const screenshotPath = path.join(SURF_TMP, `surf-error-${timestamp}.png`);
@@ -2896,6 +3269,19 @@ const performAutoCapture = async () => {
   }
 };
 
+if (finalTool === "record") {
+  installBrowserLock(lockOptions);
+  runRecord()
+    .then(() => process.exit(0))
+    .catch((error) => {
+      console.error("Error:", error && error.message ? error.message : String(error));
+      process.exit(1);
+    });
+  return;
+}
+
+installBrowserLock(lockOptions);
+
 const socket = net.createConnection(SOCKET_PATH, () => {
   socket.write(JSON.stringify(request) + "\n");
 });
@@ -2923,14 +3309,14 @@ socket.on("data", (data) => {
     if (!line.trim()) continue;
     try {
       const msg = JSON.parse(line);
-      
+
       if (msg.type === "extension_disconnected") {
         clearTimeout(timeout);
         console.error(msg.message);
         socket.end();
         process.exit(1);
       }
-      
+
       handleResponse(msg).catch((err) => {
         console.error("Handler error:", err.message);
         process.exit(1);
@@ -2944,13 +3330,7 @@ socket.on("data", (data) => {
 
 socket.on("error", (err) => {
   clearTimeout(timeout);
-  if (err.code === "ENOENT") {
-    console.error("Error: Socket not found. Is Chrome running with the extension?");
-  } else if (err.code === "ECONNREFUSED") {
-    console.error("Error: Connection refused. Native host not running.");
-  } else {
-    console.error("Error:", err.message);
-  }
+  console.error("Error:", formatSocketError(err));
   process.exit(1);
 });
 
@@ -2979,7 +3359,7 @@ async function handleResponse(response) {
   }
 
   const result = response.result?.content?.[0]?.text;
-  
+
   let data;
   try {
     data = result ? JSON.parse(result) : response.result;
@@ -2991,6 +3371,17 @@ async function handleResponse(response) {
     data = { response: data };
   }
 
+  if (tool === "perf-audit" && outputPath) {
+    const saveTo = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(saveTo), { recursive: true });
+    fs.writeFileSync(saveTo, JSON.stringify(data ?? null, null, 2));
+    if (!wantJson) {
+      console.log(`Saved perf audit to ${saveTo}`);
+      socket.end();
+      process.exit(0);
+    }
+  }
+
   if (wantJson) {
     console.log(JSON.stringify(data ?? null, null, 2));
     socket.end();
@@ -3000,12 +3391,12 @@ async function handleResponse(response) {
   if (tool === "screenshot" && data?.base64 && (outputPath || toolArgs.savePath)) {
     const saveTo = outputPath || toolArgs.savePath;
     fs.writeFileSync(saveTo, Buffer.from(data.base64, "base64"));
-    
+
     const skipResize = options.full || toolArgs.full;
     const maxSize = parseInt(options["max-size"] || toolArgs["max-size"] || "1200", 10);
     const origWidth = data.width || 0;
     const origHeight = data.height || 0;
-    
+
     if (!skipResize && (origWidth > maxSize || origHeight > maxSize)) {
       const result = resizeImage(saveTo, maxSize);
       if (result.success) {
@@ -3092,7 +3483,7 @@ async function handleResponse(response) {
   } else if (tool === "smoke" && data?.results) {
     const results = data.results;
     const summary = data.summary || { pass: 0, fail: 0, total: results.length };
-    
+
     for (const r of results) {
       const status = r.status === "pass" ? "PASS" : "FAIL";
       const timeStr = r.time ? ` (${r.time}ms)` : "";
@@ -3104,10 +3495,10 @@ async function handleResponse(response) {
         }
       }
     }
-    
+
     console.log("");
     console.log(`Summary: ${summary.pass} passed, ${summary.fail} failed, ${summary.total} total`);
-    
+
     if (summary.fail > 0) {
       socket.end();
       process.exit(1);
@@ -3119,7 +3510,7 @@ async function handleResponse(response) {
   } else if (tool === "network" && (data?.entries || data?.requests)) {
     // Network list - handle both new (entries) and old (requests) formats
     const items = data.entries || data.requests || [];
-    
+
     if (items.length === 0) {
       console.log("No network requests captured");
     } else if (data._format === 'raw') {