@ulpi/browse 0.1.0 → 0.2.1

package/src/browser-manager.ts

@@ -7,8 +7,10 @@
  *   We do NOT try to self-heal — don't hide failure.
  */
 
-import { chromium, devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Request as PlaywrightRequest } from 'playwright';
+import { chromium, devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Frame, type FrameLocator, type Request as PlaywrightRequest } from 'playwright';
 import { SessionBuffers, type LogEntry, type NetworkEntry } from './buffers';
+import type { HarRecording } from './har';
+import type { DomainFilter } from './domain-filter';
 
 /** Shorthand aliases for common devices → Playwright device names */
 const DEVICE_ALIASES: Record<string, string> = {
@@ -136,6 +138,9 @@ export class BrowserManager {
   private customUserAgent: string | null = null;
   private currentDevice: DeviceDescriptor | null = null;
 
+  // ─── iframe targeting ─────────────────────────────────────
+  private activeFrameSelector: string | null = null;
+
   // ─── Per-session buffers ──────────────────────────────────
   private buffers: SessionBuffers;
 
@@ -156,6 +161,21 @@ export class BrowserManager {
   // ─── Network Correlation ────────────────────────────────────
   private requestEntryMap = new WeakMap<PlaywrightRequest, NetworkEntry>();
 
+  // ─── Offline Mode ─────────────────────────────────────────
+  private offline = false;
+
+  // ─── HAR Recording ────────────────────────────────────────
+  private harRecording: HarRecording | null = null;
+
+  // ─── Init Script (domain filter JS injection) ─────────────
+  private initScript: string | null = null;
+
+  // ─── User Routes (survive context recreation) ─────────────
+  private userRoutes: Array<{pattern: string; action: 'block' | 'fulfill'; status?: number; body?: string}> = [];
+
+  // ─── Domain Filter (survive context recreation) ───────────
+  private domainFilter: DomainFilter | null = null;
+
   // Whether this instance owns (and should close) the Browser process
   private ownsBrowser = false;
 
@@ -167,6 +187,10 @@ export class BrowserManager {
     return this.buffers;
   }
 
+  getContext(): BrowserContext | null {
+    return this.context;
+  }
+
   /**
    * Launch a new Chromium browser (single-session / multi-process mode).
    * This instance owns the browser and will close it on close().
@@ -341,6 +365,67 @@ export class BrowserManager {
     }
   }
 
+  // ─── iframe Targeting ──────────────────────────────────────
+  /**
+   * Set the active frame by CSS selector (e.g., '#my-iframe', 'iframe[name="content"]').
+   * Subsequent commands that use resolveRef, getLocatorRoot, or getFrameContext
+   * will target this frame's content instead of the main page.
+   */
+  setFrame(selector: string) {
+    this.activeFrameSelector = selector;
+  }
+
+  /**
+   * Reset to main frame — clears the active frame selector.
+   */
+  resetFrame() {
+    this.activeFrameSelector = null;
+  }
+
+  /**
+   * Get the current active frame selector, or null if targeting main page.
+   */
+  getActiveFrameSelector(): string | null {
+    return this.activeFrameSelector;
+  }
+
+  /**
+   * Get a FrameLocator for the active frame.
+   * Returns null if no frame is active (targeting main page).
+   */
+  getFrameLocator(): FrameLocator | null {
+    if (!this.activeFrameSelector) return null;
+    return this.getPage().frameLocator(this.activeFrameSelector);
+  }
+
+  /**
+   * Get the Frame object for the active frame (needed for evaluate() calls).
+   * Returns null if no frame is active.
+   * Unlike FrameLocator, Frame supports evaluate(), querySelector, etc.
+   */
+  async getFrameContext(): Promise<Frame | null> {
+    if (!this.activeFrameSelector) return null;
+    const page = this.getPage();
+    const frameEl = page.locator(this.activeFrameSelector);
+    const handle = await frameEl.elementHandle({ timeout: 5000 });
+    if (!handle) throw new Error(`Frame element not found: ${this.activeFrameSelector}`);
+    const frame = await handle.contentFrame();
+    if (!frame) throw new Error(`Cannot access content of frame: ${this.activeFrameSelector}`);
+    return frame;
+  }
+
+  /**
+   * Get a locator root scoped to the active frame (if any) or the page.
+   * Use this to create locators that respect the current frame context.
+   * Example: bm.getLocatorRoot().locator('button.submit')
+   */
+  getLocatorRoot(): Page | FrameLocator {
+    if (this.activeFrameSelector) {
+      return this.getPage().frameLocator(this.activeFrameSelector);
+    }
+    return this.getPage();
+  }
+
   // ─── Ref Map ──────────────────────────────────────────────
   setRefMap(refs: Map<string, Locator>) {
     this.refMap = refs;
@@ -354,6 +439,10 @@ export class BrowserManager {
   /**
    * Resolve a selector that may be a @ref (e.g., "@e3") or a CSS selector.
    * Returns { locator } for refs or { selector } for CSS selectors.
+   *
+   * When a frame is active and a CSS selector is passed, returns { locator }
+   * scoped to the frame instead of { selector }, so callers automatically
+   * interact with elements inside the iframe.
    */
   resolveRef(selector: string): { locator: Locator } | { selector: string } {
     if (selector.startsWith('@e')) {
@@ -373,6 +462,11 @@ export class BrowserManager {
       }
       return { locator };
     }
+    // When a frame is active, scope CSS selectors through the frame
+    if (this.activeFrameSelector) {
+      const frame = this.getPage().frameLocator(this.activeFrameSelector);
+      return { locator: frame.locator(selector) };
+    }
     return { selector };
   }
 
@@ -473,6 +567,28 @@ export class BrowserManager {
       if (Object.keys(this.extraHeaders).length > 0) {
         await newContext.setExtraHTTPHeaders(this.extraHeaders);
       }
+      if (this.offline) {
+        await newContext.setOffline(true);
+      }
+      if (this.initScript) {
+        await newContext.addInitScript(this.initScript);
+      }
+      // Re-apply domain filter route
+      if (this.domainFilter) {
+        const df = this.domainFilter;
+        await newContext.route('**/*', (route) => {
+          const url = route.request().url();
+          if (df.isAllowed(url)) { route.continue(); } else { route.abort('blockedbyclient'); }
+        });
+      }
+      // Re-apply user routes
+      for (const r of this.userRoutes) {
+        if (r.action === 'block') {
+          await newContext.route(r.pattern, (route) => route.abort('blockedbyclient'));
+        } else {
+          await newContext.route(r.pattern, (route) => route.fulfill({ status: r.status || 200, body: r.body || '', contentType: 'text/plain' }));
+        }
+      }
     } catch (err) {
       await newContext.close().catch(() => {});
       throw err;
@@ -484,6 +600,7 @@ export class BrowserManager {
     const oldActiveTabId = this.activeTabId;
     const oldNextTabId = this.nextTabId;
     const oldTabSnapshots = new Map(this.tabSnapshots);
+    const oldRefMap = new Map(this.refMap);
 
     // Swap to new context
     this.context = newContext;
@@ -520,7 +637,7 @@ export class BrowserManager {
       this.activeTabId = oldActiveTabId;
       this.nextTabId = oldNextTabId;
       this.tabSnapshots = oldTabSnapshots;
-      this.refMap.clear();
+      this.refMap = oldRefMap;
       throw err;
     }
 
@@ -600,6 +717,64 @@ export class BrowserManager {
     return this.currentDevice;
   }
 
+  // ─── Offline Mode ──────────────────────────────────────────
+  isOffline(): boolean {
+    return this.offline;
+  }
+
+  async setOffline(value: boolean): Promise<void> {
+    this.offline = value;
+    if (this.context) {
+      await this.context.setOffline(value);
+    }
+  }
+
+  // ─── HAR Recording ────────────────────────────────────────
+  startHarRecording(): void {
+    this.harRecording = { startTime: Date.now(), active: true };
+  }
+
+  stopHarRecording(): HarRecording | null {
+    const recording = this.harRecording;
+    this.harRecording = null;
+    return recording;
+  }
+
+  getHarRecording(): HarRecording | null {
+    return this.harRecording;
+  }
+
+  // ─── Init Script ───────────────────────────────────────────
+  setInitScript(script: string): void {
+    this.initScript = script;
+  }
+
+  getInitScript(): string | null {
+    return this.initScript;
+  }
+
+  // ─── User Routes ──────────────────────────────────────────
+  addUserRoute(pattern: string, action: 'block' | 'fulfill', status?: number, body?: string) {
+    this.userRoutes.push({pattern, action, status, body});
+  }
+
+  clearUserRoutes() {
+    this.userRoutes = [];
+  }
+
+  getUserRoutes() {
+    return this.userRoutes;
+  }
+
+  // ─── Domain Filter ────────────────────────────────────────
+  setDomainFilter(filter: DomainFilter) {
+    this.domainFilter = filter;
+  }
+
+  getDomainFilter(): DomainFilter | null {
+    return this.domainFilter;
+  }
+
   /**
    * Reverse-lookup: find the tab ID that owns this page.
    * Returns undefined if the page isn't committed to any tab yet (during newTab).

package/src/cli.ts

@@ -12,9 +12,22 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { DEFAULTS } from './constants';
+import { loadConfig } from './config';
+
+// Global CLI flags — set in main(), used by sendCommand()
+const cliFlags = {
+  json: false,
+  contentBoundaries: false,
+  allowedDomains: '' as string,
+};
 
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
-const INSTANCE_SUFFIX = BROWSE_PORT ? `-${BROWSE_PORT}` : '';
+// Instance isolation: each parent process (e.g., Claude Code) gets its own server.
+// BROWSE_PORT takes precedence (explicit), then BROWSE_INSTANCE (env override), then PPID (auto).
+// In compiled mode ($bunfs), PPID is unstable (shell forks per invocation) — skip it.
+const IS_COMPILED = import.meta.dir.includes('$bunfs');
+const BROWSE_INSTANCE = process.env.BROWSE_INSTANCE || (BROWSE_PORT || IS_COMPILED ? '' : String(process.ppid));
+const INSTANCE_SUFFIX = BROWSE_PORT ? `-${BROWSE_PORT}` : (BROWSE_INSTANCE ? `-${BROWSE_INSTANCE}` : '');
 
 /**
  * Resolve the project-local .browse/ directory for state files, logs, screenshots.
@@ -69,6 +82,11 @@ export function resolveServerScript(
     }
   }
 
+  // Compiled binary ($bunfs): server is bundled, no external file needed
+  if (metaDir.includes('$bunfs')) {
+    return '__compiled__';
+  }
+
   throw new Error(
     '[browse] Cannot find server.ts. Set BROWSE_SERVER_SCRIPT env var to the path of server.ts.'
   );
@@ -170,10 +188,15 @@ async function startServer(): Promise<ServerState> {
       }
     } catch {}
 
-    // Start server as detached background process
-    const proc = Bun.spawn(['bun', 'run', SERVER_SCRIPT], {
+    // Start server as detached background process.
+    // Compiled binary: self-spawn with __BROWSE_SERVER_MODE=1
+    // Dev mode: spawn bun with server.ts
+    const spawnCmd = SERVER_SCRIPT === '__compiled__'
+      ? [process.execPath]
+      : ['bun', 'run', SERVER_SCRIPT];
+    const proc = Bun.spawn(spawnCmd, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, BROWSE_LOCAL_DIR: LOCAL_DIR },
+      env: { ...process.env, __BROWSE_SERVER_MODE: '1', BROWSE_LOCAL_DIR: LOCAL_DIR, BROWSE_INSTANCE },
     });
 
     // Don't hold the CLI open
@@ -224,13 +247,60 @@ async function ensureServer(): Promise<ServerState> {
     } catch {
       // Health check failed — server is dead or unhealthy
     }
+
+    // Server is alive but unhealthy (shutting down, browser crashed).
+    // Kill it so we can start fresh.
+    try { process.kill(state.pid, 'SIGTERM'); } catch {}
+    // Brief wait for graceful exit
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline && isProcessAlive(state.pid)) {
+      await Bun.sleep(100);
+    }
+    if (isProcessAlive(state.pid)) {
+      try { process.kill(state.pid, 'SIGKILL'); } catch {}
+      await Bun.sleep(200);
+    }
+  }
+
+  // Clean up stale state file
+  if (state) {
+    try { fs.unlinkSync(STATE_FILE); } catch {}
   }
 
+  // Clean up orphaned state files from other instances (e.g., old PPID-suffixed files)
+  cleanOrphanedServers();
+
   // Need to (re)start
   console.error('[browse] Starting server...');
   return startServer();
 }
 
+/**
+ * Clean up orphaned browse servers:
+ * 1. Remove state files with dead PIDs
+ * 2. Kill live servers from other instances (old PPID-suffixed state files)
+ */
+function cleanOrphanedServers(): void {
+  try {
+    const files = fs.readdirSync(LOCAL_DIR);
+    for (const file of files) {
+      if (!file.startsWith('browse-server') || !file.endsWith('.json') || file.endsWith('.lock')) continue;
+      const filePath = path.join(LOCAL_DIR, file);
+      if (filePath === STATE_FILE) continue; // Don't touch our own state file
+      try {
+        const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (data.pid) {
+          if (isProcessAlive(data.pid)) {
+            // Live orphan from a different instance — kill it to free the port
+            try { process.kill(data.pid, 'SIGTERM'); } catch {}
+          }
+          fs.unlinkSync(filePath);
+        }
+      } catch {}
+    }
+  } catch {}
+}
+
 // ─── Command Dispatch ──────────────────────────────────────────
 
 // Commands that are safe to retry after a transport failure.
@@ -241,10 +311,10 @@ async function ensureServer(): Promise<ServerState> {
 export const SAFE_TO_RETRY = new Set([
   // Read commands — no side effects
   'text', 'html', 'links', 'forms', 'accessibility',
-  'css', 'attrs', 'state', 'dialog',
-  'console', 'network', 'cookies', 'perf',
-  // Meta commands that are read-only
-  'tabs', 'status', 'url', 'snapshot', 'snapshot-diff', 'devices', 'sessions',
+  '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',
 ]);
 
 // Commands that return static data independent of page state.
@@ -261,6 +331,15 @@ async function sendCommand(state: ServerState, command: string, args: string[],
   if (sessionId) {
     headers['X-Browse-Session'] = sessionId;
   }
+  if (cliFlags.json) {
+    headers['X-Browse-Json'] = '1';
+  }
+  if (cliFlags.contentBoundaries) {
+    headers['X-Browse-Boundaries'] = '1';
+  }
+  if (cliFlags.allowedDomains) {
+    headers['X-Browse-Allowed-Domains'] = cliFlags.allowedDomains;
+  }
 
   try {
     const resp = await fetch(`http://127.0.0.1:${state.port}/command`, {
@@ -286,22 +365,24 @@ async function sendCommand(state: ServerState, command: string, args: string[],
       process.stdout.write(text);
       if (!text.endsWith('\n')) process.stdout.write('\n');
 
-      // After restart succeeds, wait for old server to actually die, then start fresh
-      if (command === 'restart') {
+      // After stop/restart, wait for old server to actually die
+      if (command === 'stop' || command === 'restart') {
         const oldPid = state.pid;
-        // Wait up to 5s for graceful shutdown
         const deadline = Date.now() + 5000;
         while (Date.now() < deadline && isProcessAlive(oldPid)) {
           await Bun.sleep(100);
         }
-        // If still alive (e.g. browserManager.close() stalled), force-kill
         if (isProcessAlive(oldPid)) {
           try { process.kill(oldPid, 'SIGKILL'); } catch {}
-          // Brief wait for OS to reclaim the process and release the port
           await Bun.sleep(300);
         }
-        const newState = await startServer();
-        console.error(`[browse] Server restarted (PID: ${newState.pid})`);
+        // Clean up state file
+        try { fs.unlinkSync(STATE_FILE); } catch {}
+
+        if (command === 'restart') {
+          const newState = await startServer();
+          console.error(`[browse] Server restarted (PID: ${newState.pid})`);
+        }
       }
     } else {
       // Try to parse as JSON error
@@ -356,9 +437,12 @@ async function sendCommand(state: ServerState, command: string, args: string[],
 }
 
 // ─── Main ──────────────────────────────────────────────────────
-async function main() {
+export async function main() {
   const args = process.argv.slice(2);
 
+  // Load project config (browse.json) — values serve as defaults
+  const config = loadConfig();
+
   // Extract --session flag before command parsing
   let sessionId: string | undefined;
   const sessionIdx = args.indexOf('--session');
@@ -370,7 +454,43 @@ async function main() {
     }
     args.splice(sessionIdx, 2); // remove --session and its value
   }
-  sessionId = sessionId || process.env.BROWSE_SESSION || undefined;
+  sessionId = sessionId || process.env.BROWSE_SESSION || config.session || undefined;
+
+  // Extract --json flag
+  let jsonMode = false;
+  const jsonIdx = args.indexOf('--json');
+  if (jsonIdx !== -1) {
+    jsonMode = true;
+    args.splice(jsonIdx, 1);
+  }
+  jsonMode = jsonMode || process.env.BROWSE_JSON === '1' || config.json === true;
+
+  // Extract --content-boundaries flag
+  let contentBoundaries = false;
+  const boundIdx = args.indexOf('--content-boundaries');
+  if (boundIdx !== -1) {
+    contentBoundaries = true;
+    args.splice(boundIdx, 1);
+  }
+  contentBoundaries = contentBoundaries || process.env.BROWSE_CONTENT_BOUNDARIES === '1' || config.contentBoundaries === true;
+
+  // Extract --allowed-domains flag
+  let allowedDomains: string | undefined;
+  const domIdx = args.indexOf('--allowed-domains');
+  if (domIdx !== -1) {
+    allowedDomains = args[domIdx + 1];
+    if (!allowedDomains || allowedDomains.startsWith('-')) {
+      console.error('Usage: browse --allowed-domains domain1,domain2 <command> [args...]');
+      process.exit(1);
+    }
+    args.splice(domIdx, 2);
+  }
+  allowedDomains = allowedDomains || process.env.BROWSE_ALLOWED_DOMAINS || (config.allowedDomains ? config.allowedDomains.join(',') : undefined);
+
+  // Set global flags for sendCommand()
+  cliFlags.json = jsonMode;
+  cliFlags.contentBoundaries = contentBoundaries;
+  cliFlags.allowedDomains = allowedDomains || '';
 
   // ─── Local commands (no server needed) ─────────────────────
   if (args[0] === 'install-skill') {
@@ -382,31 +502,42 @@ async function main() {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     console.log(`browse — Fast headless browser for AI coding agents
 
-Usage: browse [--session <id>] <command> [args...]
+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> | type <text> | press <key>
-                scroll [sel] | wait <sel> | viewport <WxH>
+                hover <sel> | dblclick <sel> | focus <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>
+                viewport <WxH> | highlight <sel> | download <sel> [path]
 Device:         emulate <device> | emulate reset | devices [filter]
 Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
-                console [--clear] | network [--clear]
+                element-state <sel> | console [--clear] | network [--clear]
                 cookies | storage [set <k> <v>] | perf
+                value <sel> | count <sel>
 Visual:         screenshot [path] | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-c] [-C] [-d N] [-s sel]
 Compare:        diff <url1> <url2>
 Multi-step:     chain (reads JSON from stdin)
+Network:        offline [on|off] | route <pattern> block|fulfill
+Recording:      har start | har stop [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>
+State:          state save [name] | state load [name]
 Server:         status | cookie <n>=<v> | header <n>:<v>
                 useragent <str> | stop | restart
 Setup:          install-skill [path]
 
 Options:
-  --session <id>  Use a named session (isolates tabs, refs, cookies).
-                  Multiple agents can share one server with different sessions.
-                  Also settable via BROWSE_SESSION env var.
+  --session <id>           Named session (isolates tabs, refs, cookies)
+  --json                   Wrap output as {success, data, command}
+  --content-boundaries     Wrap page content in nonce-delimited markers
+  --allowed-domains <d,d>  Block navigation/resources outside allowlist
 
 Snapshot flags:
   -i            Interactive elements only (buttons, links, inputs)
@@ -434,7 +565,10 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
   await sendCommand(state, command, commandArgs, 0, sessionId);
 }
 
-if (import.meta.main) {
+if (process.env.__BROWSE_SERVER_MODE === '1') {
+  import('./server');
+} else if (import.meta.main) {
+  // Direct execution: bun run src/cli.ts <command>
   main().catch((err) => {
     console.error(`[browse] ${err.message}`);
     process.exit(1);