@ulpi/browse 0.7.5 → 0.10.0

package/src/cli.ts

@@ -20,8 +20,13 @@ const cliFlags = {
   contentBoundaries: false,
   allowedDomains: '' as string,
   headed: false,
+  stateFile: '' as string,
+  maxOutput: 0,
 };
 
+// Track whether --state has been applied (only sent on first command)
+let stateFileApplied = false;
+
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
 // One server per project directory by default. Sessions handle agent isolation.
 // For multiple servers on the same project: set BROWSE_INSTANCE or BROWSE_PORT.
@@ -376,7 +381,8 @@ export const SAFE_TO_RETRY = new Set([
   'css', 'attrs', 'element-state', 'dialog',
   'console', 'network', 'cookies', 'perf', 'value', 'count',
   // Meta commands that are read-only or idempotent
-  'tabs', 'status', 'url', 'snapshot', 'snapshot-diff', 'devices', 'sessions', 'frame', 'find',
+  'tabs', 'status', 'url', 'snapshot', 'snapshot-diff', 'devices', 'sessions', 'frame', 'find', 'record', 'cookie-import',
+  'box', 'errors', 'doctor', 'upgrade',
 ]);
 
 // Commands that return static data independent of page state.
@@ -402,6 +408,13 @@ async function sendCommand(state: ServerState, command: string, args: string[],
   if (cliFlags.allowedDomains) {
     headers['X-Browse-Allowed-Domains'] = cliFlags.allowedDomains;
   }
+  if (cliFlags.stateFile && !stateFileApplied) {
+    headers['X-Browse-State'] = cliFlags.stateFile;
+    stateFileApplied = true;
+  }
+  if (cliFlags.maxOutput > 0) {
+    headers['X-Browse-Max-Output'] = String(cliFlags.maxOutput);
+  }
 
   try {
     const resp = await fetch(`http://127.0.0.1:${state.port}/command`, {
@@ -511,7 +524,7 @@ export async function main() {
     for (let i = 0; i < a.length; i++) {
       if (!a[i].startsWith('-')) return i;
       // Skip flag values for known value-flags
-      if (a[i] === '--session' || a[i] === '--allowed-domains') i++;
+      if (a[i] === '--session' || a[i] === '--allowed-domains' || a[i] === '--cdp' || a[i] === '--state') i++;
     }
     return a.length;
   }
@@ -569,11 +582,79 @@ export async function main() {
   }
   headed = headed || process.env.BROWSE_HEADED === '1';
 
+  // Extract --connect flag (only before command)
+  let connectFlag = false;
+  const connectIdx = args.indexOf('--connect');
+  if (connectIdx !== -1 && connectIdx < findCommandIndex(args)) {
+    connectFlag = true;
+    args.splice(connectIdx, 1);
+  }
+
+  // Extract --cdp <port> flag (only before command)
+  let cdpPort: number | undefined;
+  const cdpIdx = args.indexOf('--cdp');
+  if (cdpIdx !== -1 && cdpIdx < findCommandIndex(args)) {
+    const portStr = args[cdpIdx + 1];
+    if (!portStr || portStr.startsWith('-')) {
+      console.error('Usage: browse --cdp <port> <command> [args...]');
+      process.exit(1);
+    }
+    cdpPort = parseInt(portStr, 10);
+    if (!Number.isFinite(cdpPort) || cdpPort <= 0) {
+      console.error(`Invalid CDP port: ${portStr}`);
+      process.exit(1);
+    }
+    args.splice(cdpIdx, 2);
+  }
+
+  // Extract --state <path> flag (only before command)
+  let stateFile = '';
+  const stateIdx = args.indexOf('--state');
+  if (stateIdx !== -1 && stateIdx < findCommandIndex(args)) {
+    stateFile = args[stateIdx + 1] || '';
+    if (!stateFile || stateFile.startsWith('-')) {
+      console.error('Usage: browse --state <path> <command> [args...]');
+      process.exit(1);
+    }
+    args.splice(stateIdx, 2);
+  }
+
+  // Handle --connect / --cdp: blocked by Bun WebSocket bug (oven-sh/bun#9911)
+  // Bun's compiled binary sends "Connection: keep-alive" instead of "Connection: Upgrade",
+  // breaking the WebSocket handshake required by Playwright's connectOverCDP().
+  // This affects all CDP-based connections (--connect, --cdp, lightpanda).
+  // The discovery and flag logic is ready — enable when Bun fixes the bug.
+  if (connectFlag || cdpPort) {
+    console.error(
+      '--connect/--cdp are not yet supported in the compiled binary.\n' +
+      'Bun\'s WebSocket client breaks the CDP handshake (oven-sh/bun#9911).\n' +
+      'Workaround: use cookie-import to borrow auth from your browser instead:\n' +
+      '  browse cookie-import chrome --domain <your-domain>'
+    );
+    process.exit(1);
+  }
+
+  // Extract --max-output <n> flag (only before command)
+  let maxOutput = 0;
+  const maxOutputIdx = args.indexOf('--max-output');
+  if (maxOutputIdx !== -1 && maxOutputIdx < findCommandIndex(args)) {
+    const val = args[maxOutputIdx + 1];
+    if (!val || val.startsWith('-')) {
+      console.error('Usage: browse --max-output <chars> <command> [args...]');
+      process.exit(1);
+    }
+    maxOutput = parseInt(val, 10);
+    args.splice(maxOutputIdx, 2);
+  }
+  maxOutput = maxOutput || parseInt(process.env.BROWSE_MAX_OUTPUT || '0', 10) || 0;
+
   // Set global flags for sendCommand()
   cliFlags.json = jsonMode;
   cliFlags.contentBoundaries = contentBoundaries;
   cliFlags.allowedDomains = allowedDomains || '';
   cliFlags.headed = headed;
+  cliFlags.stateFile = stateFile;
+  cliFlags.maxOutput = maxOutput;
 
   // ─── Local commands (no server needed) ─────────────────────
   if (args[0] === 'version' || args[0] === '--version' || args[0] === '-V') {
@@ -600,34 +681,49 @@ Usage: browse [options] <command> [args...]
 
 Navigation:     goto <url> | back | forward | reload | url
 Content:        text | html [sel] | links | forms | accessibility
-Interaction:    click <sel> | fill <sel> <val> | select <sel> <val>
-                hover <sel> | dblclick <sel> | focus <sel>
+Interaction:    click <sel> | rightclick <sel> | dblclick <sel>
+                fill <sel> <val> | select <sel> <val>
+                hover <sel> | focus <sel> | tap <sel>
                 check <sel> | uncheck <sel> | drag <src> <tgt>
                 type <text> | press <key> | keydown <key> | keyup <key>
-                scroll [sel|up|down] | wait <sel|--url|--network-idle>
+                keyboard inserttext <text>
+                scroll [sel|up|down] | scrollinto <sel>
+                swipe <up|down|left|right> [px]
+                wait <sel|ms|--url|--text|--fn|--load|--network-idle>
                 viewport <WxH> | highlight <sel> | download <sel> [path]
+Mouse:          mouse move <x> <y> | mouse down [btn] | mouse up [btn]
+                mouse wheel <dy> [dx]
+Settings:       set geo <lat> <lng> | set media <dark|light|no-preference>
 Device:         emulate <device> | emulate reset | devices [filter]
 Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
-                element-state <sel> | console [--clear] | network [--clear]
+                element-state <sel> | box <sel>
+                console [--clear] | errors [--clear] | network [--clear]
                 cookies | storage [set <k> <v>] | perf
                 value <sel> | count <sel> | clipboard [write <text>]
-Visual:         screenshot [path] | pdf [path] | responsive [prefix]
+Visual:         screenshot [sel|@ref] [path] [--full] [--clip x,y,w,h]
+                screenshot --annotate | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-f] [-V] [-c] [-C] [-d N] [-s sel]
-Find:           find role|text|label|placeholder|testid <query> [name]
+Find:           find role|text|label|placeholder|testid|alt|title <query>
+                find first|last <sel> | find nth <n> <sel>
 Compare:        diff <url1> <url2> | screenshot-diff <baseline> [current]
 Multi-step:     chain (reads JSON from stdin)
+Cookies:        cookie <n>=<v> | cookie set <n> <v> [--domain --secure]
+                cookie clear | cookie export <file> | cookie import <file>
 Network:        offline [on|off] | route <pattern> block|fulfill
+                header <n>:<v> | useragent <str>
 Recording:      har start | har stop [path]
                 video start [dir] | video stop | video status
+                record start | record stop | record status
+                record export browse|replay [path]
 Tabs:           tabs | tab <id> | newtab [url] | closetab [id]
 Frames:         frame <sel> | frame main
 Sessions:       sessions | session-close <id>
 Auth:           auth save <name> <url> <user> <pass|--password-stdin>
                 auth login <name> | auth list | auth delete <name>
+                cookie-import --list | cookie-import <browser> [--domain <d>] [--profile <p>]
 State:          state save|load|list|show [name]
 Debug:          inspect (requires BROWSE_DEBUG_PORT)
-Server:         status | instances | cookie <n>=<v> | header <n>:<v>
-                useragent <str> | stop | restart
+Server:         status | instances | stop | restart | doctor | upgrade
 Setup:          install-skill [path]
 
 Options:
@@ -636,6 +732,10 @@ Options:
   --content-boundaries     Wrap page content in nonce-delimited markers
   --allowed-domains <d,d>  Block navigation/resources outside allowlist
   --headed                 Run browser in headed (visible) mode
+  --max-output <n>         Truncate output to N characters
+  --state <path>           Load state file (cookies/storage) before first command
+  --connect                Auto-discover and connect to running Chrome
+  --cdp <port>             Connect to Chrome on specific debugging port
 
 Snapshot flags:
   -i            Interactive elements only (terse flat list by default)

package/src/commands/meta.ts

@@ -131,8 +131,8 @@ export async function handleMetaCommand(
     // ─── State Persistence ───────────────────────────────
     case 'state': {
       const subcommand = args[0];
-      if (!subcommand || !['save', 'load', 'list', 'show'].includes(subcommand)) {
-        throw new Error('Usage: browse state save|load|list|show [name]');
+      if (!subcommand || !['save', 'load', 'list', 'show', 'clean'].includes(subcommand)) {
+        throw new Error('Usage: browse state save|load|list|show|clean [name] [--older-than N]');
       }
       const name = sanitizeName(args[1] || 'default');
       const statesDir = `${LOCAL_DIR}/states`;
@@ -167,6 +167,21 @@ export async function handleMetaCommand(
         ].join('\n');
       }
 
+      if (subcommand === 'clean') {
+        const olderThanIdx = args.indexOf('--older-than');
+        const maxDays = olderThanIdx !== -1 && args[olderThanIdx + 1]
+          ? parseInt(args[olderThanIdx + 1], 10)
+          : 7;
+        if (isNaN(maxDays) || maxDays < 1) {
+          throw new Error('--older-than must be a positive number of days');
+        }
+        const { cleanOldStates } = await import('../session-persist');
+        const { deleted } = cleanOldStates(LOCAL_DIR, maxDays);
+        return deleted > 0
+          ? `Deleted ${deleted} state file(s) older than ${maxDays} days`
+          : `No state files older than ${maxDays} days`;
+      }
+
       if (subcommand === 'save') {
         const context = bm.getContext();
         if (!context) throw new Error('No browser context');
@@ -219,8 +234,31 @@ export async function handleMetaCommand(
       const page = bm.getPage();
       const annotate = args.includes('--annotate');
       const isFullPage = args.includes('--full');
-      const filteredArgs = args.filter(a => a !== '--annotate' && a !== '--full');
-      const screenshotPath = filteredArgs[0] || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
+      const clipIdx = args.indexOf('--clip');
+      const clipArg = clipIdx >= 0 ? args[clipIdx + 1] : null;
+      const filteredArgs = args.filter((a, i) => a !== '--annotate' && a !== '--full' && a !== '--clip' && (clipIdx < 0 || i !== clipIdx + 1));
+
+      // Parse --clip x,y,w,h
+      let clip: { x: number; y: number; width: number; height: number } | undefined;
+      if (clipArg) {
+        const parts = clipArg.split(',').map(Number);
+        if (parts.length !== 4 || parts.some(isNaN)) throw new Error('Usage: browse screenshot --clip x,y,width,height [path]');
+        clip = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+        if (isFullPage) throw new Error('Cannot use --clip with --full');
+      }
+
+      // Detect element/ref selector vs output path
+      // Selector: starts with @e, ., #, [ — Path: contains / or ends with image extension
+      let elementSelector: string | null = null;
+      let screenshotPath: string;
+      const firstArg = filteredArgs[0];
+      if (firstArg && (firstArg.startsWith('@e') || firstArg.startsWith('@c') || /^[.#\[]/.test(firstArg))) {
+        if (clip) throw new Error('Cannot use --clip with element selector');
+        elementSelector = firstArg;
+        screenshotPath = filteredArgs[1] || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
+      } else {
+        screenshotPath = firstArg || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
+      }
 
       if (annotate) {
         const viewport = page.viewportSize() || { width: 1920, height: 1080 };
@@ -289,7 +327,14 @@ export async function handleMetaCommand(
         return `Screenshot saved: ${screenshotPath}\n\nLegend:\n${legend.join('\n')}`;
       }
 
-      await page.screenshot({ path: screenshotPath, fullPage: isFullPage });
+      if (elementSelector) {
+        const resolved = bm.resolveRef(elementSelector);
+        const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+        await locator.screenshot({ path: screenshotPath });
+        return `Screenshot saved: ${screenshotPath} (element: ${elementSelector})`;
+      }
+
+      await page.screenshot({ path: screenshotPath, fullPage: isFullPage, clip });
       return `Screenshot saved: ${screenshotPath}`;
     }
 
@@ -346,8 +391,8 @@ export async function handleMetaCommand(
       const { handleWriteCommand } = await import('./write');
       const { PolicyChecker } = await import('../policy');
 
-      const WRITE_SET = new Set(['goto','back','forward','reload','click','dblclick','fill','select','hover','focus','check','uncheck','type','press','scroll','wait','viewport','cookie','header','useragent','upload','dialog-accept','dialog-dismiss','emulate','drag','keydown','keyup','highlight','download','route','offline']);
-      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','element-state','dialog','console','network','cookies','storage','perf','devices','value','count','clipboard']);
+      const WRITE_SET = new Set(['goto','back','forward','reload','click','dblclick','fill','select','hover','focus','check','uncheck','type','press','scroll','wait','viewport','cookie','header','useragent','upload','dialog-accept','dialog-dismiss','emulate','drag','keydown','keyup','highlight','download','route','offline','rightclick','tap','swipe','mouse','keyboard','scrollinto','scrollintoview','set']);
+      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','element-state','dialog','console','network','cookies','storage','perf','devices','value','count','clipboard','box','errors']);
 
       const sessionBuffers = currentSession?.buffers;
       const policy = new PolicyChecker();
@@ -592,6 +637,70 @@ export async function handleMetaCommand(
       }
     }
 
+    // ─── Cookie Import ──────────────────────────────────
+    case 'cookie-import': {
+      const { findInstalledBrowsers, importCookies, CookieImportError } = await import('../cookie-import');
+
+      // --list: show installed browsers
+      if (args.includes('--list')) {
+        const browsers = findInstalledBrowsers();
+        if (browsers.length === 0) return 'No supported Chromium browsers found';
+        return 'Installed browsers:\n' + browsers.map(b => `  ${b.name}`).join('\n');
+      }
+
+      const browserName = args[0];
+      if (!browserName) {
+        throw new Error(
+          'Usage: browse cookie-import --list\n' +
+          '       browse cookie-import <browser> [--domain <d>] [--profile <p>]\n' +
+          'Supported browsers: chrome, arc, brave, edge'
+        );
+      }
+
+      // Parse --domain and --profile flags
+      const domains: string[] = [];
+      let profile: string | undefined;
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--domain' && args[i + 1]) { domains.push(args[++i]); }
+        else if (args[i] === '--profile' && args[i + 1]) { profile = args[++i]; }
+      }
+
+      try {
+        // If no domains specified, import all by listing domains first then importing all
+        if (domains.length === 0) {
+          const { listDomains } = await import('../cookie-import');
+          const { domains: allDomains, browser } = listDomains(browserName, profile);
+          if (allDomains.length === 0) return `No cookies found in ${browser}`;
+          const allDomainNames = allDomains.map(d => d.domain);
+          const result = await importCookies(browserName, allDomainNames, profile);
+          const context = bm.getContext();
+          if (!context) throw new Error('No browser context');
+          if (result.cookies.length > 0) await context.addCookies(result.cookies);
+          const domainCount = Object.keys(result.domainCounts).length;
+          const failedNote = result.failed > 0 ? ` (${result.failed} failed to decrypt)` : '';
+          return `Imported ${result.count} cookies from ${browser} across ${domainCount} domains${failedNote}`;
+        }
+
+        const result = await importCookies(browserName, domains, profile);
+        const context = bm.getContext();
+        if (!context) throw new Error('No browser context');
+        if (result.cookies.length > 0) await context.addCookies(result.cookies);
+        const domainLabel = domains.length === 1 ? `for ${domains[0]} ` : '';
+        const failedNote = result.failed > 0 ? ` (${result.failed} failed to decrypt)` : '';
+        // Resolve display name from the result's domain counts keys or use arg
+        const browserDisplay = Object.keys(result.domainCounts).length > 0
+          ? browserName.charAt(0).toUpperCase() + browserName.slice(1)
+          : browserName;
+        return `Imported ${result.count} cookies ${domainLabel}from ${browserDisplay}${failedNote}`;
+      } catch (err) {
+        if (err instanceof CookieImportError) {
+          const hint = err.action === 'retry' ? ' (retry may help)' : '';
+          throw new Error(err.message + hint);
+        }
+        throw err;
+      }
+    }
+
     // ─── HAR Recording ────────────────────────────────
     case 'har': {
       const subcommand = args[0];
@@ -652,11 +761,46 @@ export async function handleMetaCommand(
       throw new Error('Usage: browse video start [dir] | browse video stop | browse video status');
     }
 
+    // ─── Doctor ────────────────────────────────────────
+    case 'doctor': {
+      const lines: string[] = [];
+      lines.push(`Bun: ${typeof Bun !== 'undefined' ? Bun.version : 'not available'}`);
+      try {
+        const pw = await import('playwright');
+        lines.push(`Playwright: installed`);
+        try {
+          const chromium = pw.chromium;
+          lines.push(`Chromium: ${chromium.executablePath()}`);
+        } catch {
+          lines.push(`Chromium: NOT FOUND — run "bunx playwright install chromium"`);
+        }
+      } catch {
+        lines.push(`Playwright: NOT INSTALLED — run "bun install playwright"`);
+      }
+      lines.push(`Server: running (you're connected)`);
+      return lines.join('\n');
+    }
+
+    // ─── Upgrade ────────────────────────────────────────
+    case 'upgrade': {
+      const { execSync } = await import('child_process');
+      try {
+        const output = execSync('npm update -g @ulpi/browse 2>&1', { encoding: 'utf-8', timeout: 30000 });
+        return `Upgrade complete.\n${output.trim()}`;
+      } catch (err: any) {
+        if (err.message?.includes('EACCES') || err.message?.includes('permission')) {
+          return `Permission denied. Try: sudo npm update -g @ulpi/browse`;
+        }
+        return `Upgrade failed: ${err.message}\nManual: npm install -g @ulpi/browse`;
+      }
+    }
+
     // ─── Semantic Locator ──────────────────────────────
     case 'find': {
       const root = bm.getLocatorRoot();
+      const page = bm.getPage();
       const sub = args[0];
-      if (!sub) throw new Error('Usage: browse find role|text|label|placeholder|testid <query> [name]');
+      if (!sub) throw new Error('Usage: browse find role|text|label|placeholder|testid|alt|title|first|last|nth <query>');
       const query = args[1];
       if (!query) throw new Error(`Usage: browse find ${sub} <query>`);
 
@@ -679,8 +823,35 @@ export async function handleMetaCommand(
         case 'testid':
           locator = root.getByTestId(query);
           break;
+        case 'alt':
+          locator = root.getByAltText(query);
+          break;
+        case 'title':
+          locator = root.getByTitle(query);
+          break;
+        case 'first': {
+          locator = page.locator(query).first();
+          const text = await locator.textContent({ timeout: 2000 }).catch(() => '') || '';
+          const total = await page.locator(query).count();
+          return `Found ${total} match(es), first: "${text.trim().slice(0, 100)}"`;
+        }
+        case 'last': {
+          locator = page.locator(query).last();
+          const text = await locator.textContent({ timeout: 2000 }).catch(() => '') || '';
+          const total = await page.locator(query).count();
+          return `Found ${total} match(es), last: "${text.trim().slice(0, 100)}"`;
+        }
+        case 'nth': {
+          const n = parseInt(query, 10);
+          const sel = args[2];
+          if (isNaN(n) || !sel) throw new Error('Usage: browse find nth <index> <selector>');
+          locator = page.locator(sel).nth(n);
+          const text = await locator.textContent({ timeout: 2000 }).catch(() => '') || '';
+          const total = await page.locator(sel).count();
+          return `Found ${total} match(es), nth(${n}): "${text.trim().slice(0, 100)}"`;
+        }
         default:
-          throw new Error(`Unknown find type: ${sub}. Use role|text|label|placeholder|testid`);
+          throw new Error(`Unknown find type: ${sub}. Use role|text|label|placeholder|testid|alt|title|first|last|nth`);
       }
 
       const count = await locator.count();
@@ -742,6 +913,73 @@ export async function handleMetaCommand(
       }
     }
 
+    // ─── Record & Export ─────────────────────────────────
+    case 'record': {
+      const subcommand = args[0];
+      if (!subcommand) throw new Error('Usage: browse record start | stop | status | export browse|replay [path]');
+
+      if (subcommand === 'start') {
+        if (!currentSession) throw new Error('Recording requires a session context');
+        if (currentSession.recording) throw new Error('Recording already active. Run "browse record stop" first.');
+        currentSession.recording = [];
+        return 'Recording started';
+      }
+
+      if (subcommand === 'stop') {
+        if (!currentSession) throw new Error('Recording requires a session context');
+        if (!currentSession.recording) throw new Error('No active recording. Run "browse record start" first.');
+        const count = currentSession.recording.length;
+        // Store last recording for export after stop
+        (currentSession as any)._lastRecording = currentSession.recording;
+        currentSession.recording = null;
+        return `Recording stopped (${count} steps captured)`;
+      }
+
+      if (subcommand === 'status') {
+        if (!currentSession) return 'No session context';
+        if (currentSession.recording) {
+          return `Recording active — ${currentSession.recording.length} steps captured`;
+        }
+        const last = (currentSession as any)._lastRecording;
+        if (last) return `Recording stopped — ${last.length} steps available for export`;
+        return 'No active recording';
+      }
+
+      if (subcommand === 'export') {
+        if (!currentSession) throw new Error('Recording requires a session context');
+        const format = args[1];
+        if (!format) throw new Error('Usage: browse record export browse|replay [path]');
+
+        // Use active recording or last stopped recording
+        const steps = currentSession.recording || (currentSession as any)._lastRecording;
+        if (!steps || steps.length === 0) {
+          throw new Error('No recording to export. Run "browse record start" first, execute commands, then export.');
+        }
+
+        const { exportBrowse, exportReplay } = await import('../record-export');
+
+        let output: string;
+        if (format === 'browse') {
+          output = exportBrowse(steps);
+        } else if (format === 'replay') {
+          output = exportReplay(steps);
+        } else {
+          throw new Error(`Unknown format: ${format}. Use "browse" (chain JSON) or "replay" (Playwright/Puppeteer).`);
+        }
+
+        const filePath = args[2];
+        if (filePath) {
+          fs.writeFileSync(filePath, output);
+          return `Exported ${steps.length} steps as ${format}: ${filePath}`;
+        }
+
+        // No path — return the script to stdout
+        return output;
+      }
+
+      throw new Error('Usage: browse record start | stop | status | export browse|replay [path]');
+    }
+
     default:
       throw new Error(`Unknown meta command: ${command}`);
   }

package/src/commands/read.ts

@@ -8,6 +8,7 @@
 import type { BrowserManager } from '../browser-manager';
 import { listDevices } from '../browser-manager';
 import type { SessionBuffers } from '../buffers';
+import { DEFAULTS } from '../constants';
 import * as fs from 'fs';
 
 export async function handleReadCommand(
@@ -331,6 +332,33 @@ export async function handleReadCommand(
       }
     }
 
+    case 'box': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse box <selector>');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+      const box = await locator.boundingBox({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      if (!box) throw new Error(`Element ${selector} is not visible or has no bounding box`);
+      return JSON.stringify({ x: Math.round(box.x), y: Math.round(box.y), width: Math.round(box.width), height: Math.round(box.height) });
+    }
+
+    case 'errors': {
+      const cb = (buffers || bm.getBuffers()).consoleBuffer;
+      if (args[0] === '--clear') {
+        const before = cb.length;
+        // Remove error entries in-place
+        for (let i = cb.length - 1; i >= 0; i--) {
+          if (cb[i].level === 'error') cb.splice(i, 1);
+        }
+        return `Cleared ${before - cb.length} error(s).`;
+      }
+      const errors = cb.filter(e => e.level === 'error');
+      if (errors.length === 0) return '(no errors)';
+      return errors.map(e =>
+        `[${new Date(e.timestamp).toISOString()}] ${e.text}`
+      ).join('\n');
+    }
+
     case 'devices': {
       const filter = args.join(' ').toLowerCase();
       const all = listDevices();