@ulpi/browse 0.1.0 → 0.2.1

package/src/commands/meta.ts

@@ -6,6 +6,7 @@ import type { BrowserManager } from '../browser-manager';
 import type { SessionManager, Session } from '../session-manager';
 import { handleSnapshot } from '../snapshot';
 import { DEFAULTS } from '../constants';
+import { sanitizeName } from '../sanitize';
 import * as Diff from 'diff';
 import * as fs from 'fs';
 
@@ -100,12 +101,59 @@ export async function handleMetaCommand(
       return `Session "${id}" closed`;
     }
 
+    // ─── State Persistence ───────────────────────────────
+    case 'state': {
+      const subcommand = args[0];
+      if (!subcommand || !['save', 'load'].includes(subcommand)) {
+        throw new Error('Usage: browse state save [name] | browse state load [name]');
+      }
+      const name = sanitizeName(args[1] || 'default');
+      const statesDir = `${LOCAL_DIR}/states`;
+      const statePath = `${statesDir}/${name}.json`;
+
+      if (subcommand === 'save') {
+        const context = bm.getContext();
+        if (!context) throw new Error('No browser context');
+        const state = await context.storageState();
+        fs.mkdirSync(statesDir, { recursive: true });
+        fs.writeFileSync(statePath, JSON.stringify(state, null, 2), { mode: 0o600 });
+        return `State saved: ${statePath}`;
+      }
+
+      if (subcommand === 'load') {
+        if (!fs.existsSync(statePath)) {
+          throw new Error(`State file not found: ${statePath}. Run "browse state save ${name}" first.`);
+        }
+        const stateData = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        // Add cookies from saved state to current context
+        const context = bm.getContext();
+        if (!context) throw new Error('No browser context');
+        if (stateData.cookies?.length) {
+          await context.addCookies(stateData.cookies);
+        }
+        // Restore localStorage/sessionStorage for each origin
+        if (stateData.origins?.length) {
+          for (const origin of stateData.origins) {
+            if (origin.localStorage?.length) {
+              const page = bm.getPage();
+              await page.goto(origin.origin, { waitUntil: 'domcontentloaded', timeout: 5000 }).catch(() => {});
+              for (const item of origin.localStorage) {
+                await page.evaluate(([k, v]) => localStorage.setItem(k, v), [item.name, item.value]).catch(() => {});
+              }
+            }
+          }
+        }
+        return `State loaded: ${statePath}`;
+      }
+      throw new Error('Usage: browse state save [name] | browse state load [name]');
+    }
+
     // ─── Visual ────────────────────────────────────────
     case 'screenshot': {
       const page = bm.getPage();
       const annotate = args.includes('--annotate');
       const filteredArgs = args.filter(a => a !== '--annotate');
-      const screenshotPath = filteredArgs[0] || `${LOCAL_DIR}/browse-screenshot.png`;
+      const screenshotPath = filteredArgs[0] || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
 
       if (annotate) {
         const viewport = page.viewportSize() || { width: 1920, height: 1080 };
@@ -180,14 +228,14 @@ export async function handleMetaCommand(
 
     case 'pdf': {
       const page = bm.getPage();
-      const pdfPath = args[0] || `${LOCAL_DIR}/browse-page.pdf`;
+      const pdfPath = args[0] || (currentSession ? `${currentSession.outputDir}/page.pdf` : `${LOCAL_DIR}/browse-page.pdf`);
       await page.pdf({ path: pdfPath, format: 'A4' });
       return `PDF saved: ${pdfPath}`;
     }
 
     case 'responsive': {
       const page = bm.getPage();
-      const prefix = args[0] || `${LOCAL_DIR}/browse-responsive`;
+      const prefix = args[0] || (currentSession ? `${currentSession.outputDir}/responsive` : `${LOCAL_DIR}/browse-responsive`);
       const viewports = [
         { name: 'mobile', width: 375, height: 812 },
         { name: 'tablet', width: 768, height: 1024 },
@@ -229,15 +277,28 @@ export async function handleMetaCommand(
       const results: string[] = [];
       const { handleReadCommand } = await import('./read');
       const { handleWriteCommand } = await import('./write');
+      const { PolicyChecker } = await import('../policy');
 
-      const WRITE_SET = new Set(['goto','back','forward','reload','click','fill','select','hover','type','press','scroll','wait','viewport','cookie','header','useragent','upload','dialog-accept','dialog-dismiss','emulate']);
-      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','state','dialog','console','network','cookies','storage','perf','devices']);
+      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']);
 
       const sessionBuffers = currentSession?.buffers;
+      const policy = new PolicyChecker();
 
       for (const cmd of commands) {
         const [name, ...cmdArgs] = cmd;
         try {
+          // Policy check for each sub-command — chain must not bypass policy
+          const policyResult = policy.check(name);
+          if (policyResult === 'deny') {
+            results.push(`[${name}] ERROR: Command '${name}' denied by policy`);
+            continue;
+          }
+          if (policyResult === 'confirm') {
+            results.push(`[${name}] ERROR: Command '${name}' requires confirmation (policy)`);
+            continue;
+          }
+
           let result: string;
           if (WRITE_SET.has(name))      result = await handleWriteCommand(name, cmdArgs, bm);
           else if (READ_SET.has(name))  result = await handleReadCommand(name, cmdArgs, bm, sessionBuffers);
@@ -352,6 +413,116 @@ export async function handleMetaCommand(
       return output.join('\n');
     }
 
+    // ─── Auth Vault ─────────────────────────────────────
+    case 'auth': {
+      const subcommand = args[0];
+      const { AuthVault } = await import('../auth-vault');
+      const vault = new AuthVault(LOCAL_DIR);
+
+      switch (subcommand) {
+        case 'save': {
+          const [, name, url, username] = args;
+          // Password: from arg, env var, or --password-stdin flag
+          let password: string | undefined = args[4];
+          if (password === '--password-stdin') password = undefined;
+          if (!password && process.env.BROWSE_AUTH_PASSWORD) {
+            password = process.env.BROWSE_AUTH_PASSWORD;
+          }
+          if (!password && args.includes('--password-stdin')) {
+            password = (await Bun.stdin.text()).trim();
+          }
+          if (!name || !url || !username || !password) {
+            throw new Error(
+              'Usage: browse auth save <name> <url> <username> <password>\n' +
+              '       browse auth save <name> <url> <username> --password-stdin\n' +
+              '       BROWSE_AUTH_PASSWORD=secret browse auth save <name> <url> <username>'
+            );
+          }
+          // Parse optional selector flags
+          let userSel: string | undefined;
+          let passSel: string | undefined;
+          let submitSel: string | undefined;
+          for (let i = 4; i < args.length; i++) {
+            if (args[i] === '--user-sel' && args[i+1]) { userSel = args[++i]; }
+            else if (args[i] === '--pass-sel' && args[i+1]) { passSel = args[++i]; }
+            else if (args[i] === '--submit-sel' && args[i+1]) { submitSel = args[++i]; }
+          }
+          const selectors = (userSel || passSel || submitSel) ? { username: userSel, password: passSel, submit: submitSel } : undefined;
+          vault.save(name, url, username, password, selectors);
+          return `Credentials saved: ${name}`;
+        }
+        case 'login': {
+          const name = args[1];
+          if (!name) throw new Error('Usage: browse auth login <name>');
+          return await vault.login(name, bm);
+        }
+        case 'list': {
+          const creds = vault.list();
+          if (creds.length === 0) return '(no saved credentials)';
+          return creds.map(c => `  ${c.name} — ${c.url} (${c.username})`).join('\n');
+        }
+        case 'delete': {
+          const name = args[1];
+          if (!name) throw new Error('Usage: browse auth delete <name>');
+          vault.delete(name);
+          return `Credentials deleted: ${name}`;
+        }
+        default:
+          throw new Error('Usage: browse auth save|login|list|delete [args...]');
+      }
+    }
+
+    // ─── HAR Recording ────────────────────────────────
+    case 'har': {
+      const subcommand = args[0];
+      if (!subcommand) throw new Error('Usage: browse har start | browse har stop [path]');
+
+      if (subcommand === 'start') {
+        bm.startHarRecording();
+        return 'HAR recording started';
+      }
+
+      if (subcommand === 'stop') {
+        const recording = bm.stopHarRecording();
+        if (!recording) throw new Error('No active HAR recording. Run "browse har start" first.');
+
+        const sessionBuffers = currentSession?.buffers || bm.getBuffers();
+        const { formatAsHar } = await import('../har');
+        const har = formatAsHar(sessionBuffers.networkBuffer, recording.startTime);
+
+        const harPath = args[1] || (currentSession
+          ? `${currentSession.outputDir}/recording.har`
+          : `${LOCAL_DIR}/browse-recording.har`);
+
+        fs.writeFileSync(harPath, JSON.stringify(har, null, 2));
+        const entryCount = (har as any).log.entries.length;
+        return `HAR saved: ${harPath} (${entryCount} entries)`;
+      }
+
+      throw new Error('Usage: browse har start | browse har stop [path]');
+    }
+
+    // ─── iframe Targeting ─────────────────────────────
+    case 'frame': {
+      if (args[0] === 'main' || args[0] === 'top') {
+        bm.resetFrame();
+        return 'Switched to main frame';
+      }
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse frame <selector> | browse frame main');
+      // Verify the iframe exists and is accessible
+      const page = bm.getPage();
+      const frameEl = page.locator(selector);
+      const count = await frameEl.count();
+      if (count === 0) throw new Error(`iframe not found: ${selector}`);
+      const handle = await frameEl.elementHandle({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      if (!handle) throw new Error(`iframe not found: ${selector}`);
+      const frame = await handle.contentFrame();
+      if (!frame) throw new Error(`Element ${selector} is not an iframe`);
+      bm.setFrame(selector);
+      return `Switched to frame: ${selector}`;
+    }
+
     default:
       throw new Error(`Unknown meta command: ${command}`);
   }

package/src/commands/read.ts

@@ -17,12 +17,15 @@ export async function handleReadCommand(
   buffers?: SessionBuffers
 ): Promise<string> {
   const page = bm.getPage();
+  // When a frame is active, evaluate() calls run inside the frame context.
+  // For locator-based commands, resolveRef already scopes through the frame.
+  const evalCtx = await bm.getFrameContext() || page;
 
   switch (command) {
     case 'text': {
       // TreeWalker-based extraction — never appends to the live DOM,
       // so MutationObservers are not triggered.
-      return await page.evaluate(() => {
+      return await evalCtx.evaluate(() => {
         const body = document.body;
         if (!body) return '';
         const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG']);
@@ -57,11 +60,15 @@ export async function handleReadCommand(
         }
         return await page.innerHTML(resolved.selector);
       }
+      // When a frame is active, return the frame's full HTML
+      if (bm.getActiveFrameSelector()) {
+        return await evalCtx.evaluate(() => document.documentElement.outerHTML);
+      }
       return await page.content();
     }
 
     case 'links': {
-      const links = await page.evaluate(() =>
+      const links = await evalCtx.evaluate(() =>
         [...document.querySelectorAll('a[href]')].map(a => ({
           text: a.textContent?.trim().slice(0, 120) || '',
           href: (a as HTMLAnchorElement).href,
@@ -71,7 +78,7 @@ export async function handleReadCommand(
     }
 
     case 'forms': {
-      const forms = await page.evaluate(() => {
+      const forms = await evalCtx.evaluate(() => {
         return [...document.querySelectorAll('form')].map((form, i) => {
           const fields = [...form.querySelectorAll('input, select, textarea')].map(el => {
             const input = el as HTMLInputElement;
@@ -101,14 +108,15 @@ export async function handleReadCommand(
     }
 
     case 'accessibility': {
-      const snapshot = await page.locator("body").ariaSnapshot();
+      const root = bm.getLocatorRoot();
+      const snapshot = await root.locator('body').ariaSnapshot();
       return snapshot;
     }
 
     case 'js': {
       const expr = args[0];
       if (!expr) throw new Error('Usage: browse js <expression>');
-      const result = await page.evaluate(expr);
+      const result = await evalCtx.evaluate(expr);
       return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
     }
 
@@ -117,7 +125,7 @@ export async function handleReadCommand(
       if (!filePath) throw new Error('Usage: browse eval <js-file>');
       if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
       const code = fs.readFileSync(filePath, 'utf-8');
-      const result = await page.evaluate(code);
+      const result = await evalCtx.evaluate(code);
       return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
     }
 
@@ -132,7 +140,7 @@ export async function handleReadCommand(
         );
         return value;
       }
-      const value = await page.evaluate(
+      const value = await evalCtx.evaluate(
         ([sel, prop]) => {
           const el = document.querySelector(sel);
           if (!el) return { __notFound: true, selector: sel };
@@ -146,9 +154,9 @@ export async function handleReadCommand(
       return value as string;
     }
 
-    case 'state': {
+    case 'element-state': {
       const selector = args[0];
-      if (!selector) throw new Error('Usage: browse state <selector>');
+      if (!selector) throw new Error('Usage: browse element-state <selector>');
       const resolved = bm.resolveRef(selector);
       const locator = 'locator' in resolved
         ? resolved.locator
@@ -202,7 +210,7 @@ export async function handleReadCommand(
         });
         return JSON.stringify(attrs, null, 2);
       }
-      const attrs = await page.evaluate((sel) => {
+      const attrs = await evalCtx.evaluate((sel) => {
         const el = document.querySelector(sel);
         if (!el) return { __notFound: true, selector: sel };
         const result: Record<string, string> = {};
@@ -256,10 +264,10 @@ export async function handleReadCommand(
       if (args[0] === 'set' && args[1]) {
         const key = args[1];
         const value = args[2] || '';
-        await page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
+        await evalCtx.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
         return `Set localStorage["${key}"] = "${value}"`;
       }
-      const storage = await page.evaluate(() => ({
+      const storage = await evalCtx.evaluate(() => ({
         localStorage: { ...localStorage },
         sessionStorage: { ...sessionStorage },
       }));
@@ -267,7 +275,7 @@ export async function handleReadCommand(
     }
 
     case 'perf': {
-      const timings = await page.evaluate(() => {
+      const timings = await evalCtx.evaluate(() => {
         const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
         if (!nav) return 'No navigation timing data available.';
         return {
@@ -288,6 +296,24 @@ export async function handleReadCommand(
         .join('\n');
     }
 
+    case 'value': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse value <selector>');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+      const value = await locator.inputValue({ timeout: 5000 });
+      return value;
+    }
+
+    case 'count': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse count <selector>');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+      const count = await locator.count();
+      return String(count);
+    }
+
     case 'devices': {
       const filter = args.join(' ').toLowerCase();
       const all = listDevices();

package/src/commands/write.ts

@@ -1,19 +1,22 @@
 /**
  * Write commands — navigate and interact with pages (side effects)
  *
- * goto, back, forward, reload, click, fill, select, hover, type,
- * press, scroll, wait, viewport, cookie, header, useragent
+ * goto, back, forward, reload, click, dblclick, fill, select, hover,
+ * focus, check, uncheck, type, press, scroll, wait, viewport, cookie,
+ * header, useragent, drag, keydown, keyup
  */
 
 import type { BrowserManager } from '../browser-manager';
 import { resolveDevice, listDevices } from '../browser-manager';
+import type { DomainFilter } from '../domain-filter';
 import { DEFAULTS } from '../constants';
 import * as fs from 'fs';
 
 export async function handleWriteCommand(
   command: string,
   args: string[],
-  bm: BrowserManager
+  bm: BrowserManager,
+  domainFilter?: DomainFilter | null
 ): Promise<string> {
   const page = bm.getPage();
 
@@ -21,6 +24,9 @@ export async function handleWriteCommand(
     case 'goto': {
       const url = args[0];
       if (!url) throw new Error('Usage: browse goto <url>');
+      if (domainFilter && !domainFilter.isAllowed(url)) {
+        throw new Error(domainFilter.blockedMessage(url));
+      }
       const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: DEFAULTS.COMMAND_TIMEOUT_MS });
       const status = response?.status() || 'unknown';
       return `Navigated to ${url} (${status})`;
@@ -109,7 +115,17 @@ export async function handleWriteCommand(
 
     case 'scroll': {
       const selector = args[0];
-      if (selector) {
+      if (selector === 'up') {
+        const scrollCtx = await bm.getFrameContext() || page;
+        await scrollCtx.evaluate(() => window.scrollBy(0, -window.innerHeight));
+        return 'Scrolled up one viewport';
+      }
+      if (selector === 'down') {
+        const scrollCtx = await bm.getFrameContext() || page;
+        await scrollCtx.evaluate(() => window.scrollBy(0, window.innerHeight));
+        return 'Scrolled down one viewport';
+      }
+      if (selector && selector !== 'bottom') {
         const resolved = bm.resolveRef(selector);
         if ('locator' in resolved) {
           await resolved.locator.scrollIntoViewIfNeeded({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
@@ -118,13 +134,32 @@ export async function handleWriteCommand(
         }
         return `Scrolled ${selector} into view`;
       }
-      await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+      // Scroll to bottom (default or explicit "bottom")
+      const scrollCtx = await bm.getFrameContext() || page;
+      await scrollCtx.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
       return 'Scrolled to bottom';
     }
 
     case 'wait': {
       const selector = args[0];
-      if (!selector) throw new Error('Usage: browse wait <selector>');
+      if (!selector) throw new Error('Usage: browse wait <selector|--url|--network-idle> [timeout]');
+
+      // wait --network-idle [timeout] — wait for network to settle
+      if (selector === '--network-idle') {
+        const timeout = args[1] ? parseInt(args[1], 10) : DEFAULTS.COMMAND_TIMEOUT_MS;
+        await page.waitForLoadState('networkidle', { timeout });
+        return 'Network idle';
+      }
+
+      // wait --url <pattern> [timeout] — wait for URL to match
+      if (selector === '--url') {
+        const pattern = args[1];
+        if (!pattern) throw new Error('Usage: browse wait --url <pattern> [timeout]');
+        const timeout = args[2] ? parseInt(args[2], 10) : DEFAULTS.COMMAND_TIMEOUT_MS;
+        await page.waitForURL(pattern, { timeout });
+        return `URL matched: ${page.url()}`;
+      }
+
       const timeout = args[1] ? parseInt(args[1], 10) : DEFAULTS.COMMAND_TIMEOUT_MS;
       const resolved = bm.resolveRef(selector);
       if ('locator' in resolved) {
@@ -253,6 +288,165 @@ export async function handleWriteCommand(
       ].join('\n');
     }
 
+    case 'dblclick': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse dblclick <selector>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        await resolved.locator.dblclick({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      } else {
+        await page.dblclick(resolved.selector, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      }
+      return `Double-clicked ${selector}`;
+    }
+
+    case 'focus': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse focus <selector>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        await resolved.locator.focus({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      } else {
+        await page.locator(resolved.selector).focus({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      }
+      return `Focused ${selector}`;
+    }
+
+    case 'check': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse check <selector>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        await resolved.locator.check({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      } else {
+        await page.locator(resolved.selector).check({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      }
+      return `Checked ${selector}`;
+    }
+
+    case 'uncheck': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse uncheck <selector>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        await resolved.locator.uncheck({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      } else {
+        await page.locator(resolved.selector).uncheck({ timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      }
+      return `Unchecked ${selector}`;
+    }
+
+    case 'drag': {
+      const [srcSel, tgtSel] = args;
+      if (!srcSel || !tgtSel) throw new Error('Usage: browse drag <source> <target>');
+      const srcResolved = bm.resolveRef(srcSel);
+      const tgtResolved = bm.resolveRef(tgtSel);
+      const srcLocator = 'locator' in srcResolved ? srcResolved.locator : page.locator(srcResolved.selector);
+      const tgtLocator = 'locator' in tgtResolved ? tgtResolved.locator : page.locator(tgtResolved.selector);
+      await srcLocator.dragTo(tgtLocator, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+      return `Dragged ${srcSel} to ${tgtSel}`;
+    }
+
+    case 'keydown': {
+      const key = args[0];
+      if (!key) throw new Error('Usage: browse keydown <key>');
+      await page.keyboard.down(key);
+      return `Key down: ${key}`;
+    }
+
+    case 'keyup': {
+      const key = args[0];
+      if (!key) throw new Error('Usage: browse keyup <key>');
+      await page.keyboard.up(key);
+      return `Key up: ${key}`;
+    }
+
+    case 'highlight': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse highlight <selector>');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+      await locator.evaluate((el) => {
+        el.style.outline = '3px solid #e11d48';
+        el.style.outlineOffset = '2px';
+      });
+      return `Highlighted ${selector}`;
+    }
+
+    case 'download': {
+      const [selector, savePath] = args;
+      if (!selector) throw new Error('Usage: browse download <selector> [path]');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);
+      const [download] = await Promise.all([
+        page.waitForEvent('download', { timeout: DEFAULTS.COMMAND_TIMEOUT_MS }),
+        locator.click({ timeout: DEFAULTS.ACTION_TIMEOUT_MS }),
+      ]);
+      const finalPath = savePath || download.suggestedFilename();
+      await download.saveAs(finalPath);
+      return `Downloaded: ${finalPath}`;
+    }
+
+    case 'offline': {
+      const mode = args[0];
+      if (mode === 'on') {
+        await bm.setOffline(true);
+        return 'Offline mode: ON';
+      }
+      if (mode === 'off') {
+        await bm.setOffline(false);
+        return 'Offline mode: OFF';
+      }
+      // Toggle
+      const newState = !bm.isOffline();
+      await bm.setOffline(newState);
+      return `Offline mode: ${newState ? 'ON' : 'OFF'}`;
+    }
+
+    case 'route': {
+      // route <pattern> block — abort matching requests
+      // route <pattern> fulfill <status> [body] — respond with custom data
+      // route clear — remove all routes
+      const pattern = args[0];
+      if (!pattern) throw new Error('Usage: browse route <url-pattern> block | browse route <url-pattern> fulfill <status> [body] | browse route clear');
+
+      const context = bm.getContext();
+      if (!context) throw new Error('No browser context');
+
+      if (pattern === 'clear') {
+        await context.unrouteAll();
+        bm.clearUserRoutes();
+        // Re-apply domain filter route if active
+        if (domainFilter) {
+          await context.route('**/*', (route) => {
+            const url = route.request().url();
+            if (domainFilter!.isAllowed(url)) { route.continue(); } else { route.abort('blockedbyclient'); }
+          });
+        }
+        return domainFilter ? 'All routes cleared (domain filter preserved)' : 'All routes cleared';
+      }
+
+      const action = args[1] || 'block';
+
+      if (action === 'block') {
+        await context.route(pattern, (route) => route.abort('blockedbyclient'));
+        bm.addUserRoute(pattern, 'block');
+        return `Blocking requests matching: ${pattern}`;
+      }
+
+      if (action === 'fulfill') {
+        const status = parseInt(args[2] || '200', 10);
+        const body = args[3] || '';
+        await context.route(pattern, (route) =>
+          route.fulfill({ status, body, contentType: 'text/plain' })
+        );
+        bm.addUserRoute(pattern, 'fulfill', status, body);
+        return `Mocking requests matching: ${pattern} → ${status}${body ? ` "${body}"` : ''}`;
+      }
+
+      throw new Error('Usage: browse route <pattern> block | browse route <pattern> fulfill <status> [body]');
+    }
+
     default:
       throw new Error(`Unknown write command: ${command}`);
   }

package/src/config.ts

@@ -0,0 +1,44 @@
+/**
+ * Config file loader — reads browse.json from project root.
+ * Config values serve as defaults — CLI flags and env vars override.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface BrowseConfig {
+  session?: string;
+  json?: boolean;
+  contentBoundaries?: boolean;
+  allowedDomains?: string[];
+  idleTimeout?: number;
+  viewport?: string;
+  device?: string;
+}
+
+/**
+ * Load browse.json from the project root (directory containing .git or .claude).
+ * Returns empty config if file doesn't exist or is malformed.
+ */
+export function loadConfig(): BrowseConfig {
+  let dir = process.cwd();
+  for (let i = 0; i < 20; i++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.claude'))) {
+      const configPath = path.join(dir, 'browse.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          const raw = fs.readFileSync(configPath, 'utf-8');
+          return JSON.parse(raw) as BrowseConfig;
+        } catch {
+          // Malformed JSON — silently ignore
+          return {};
+        }
+      }
+      return {};
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return {};
+}