@ulpi/browse 0.2.1 → 0.2.4

package/README.md

@@ -92,7 +92,7 @@ $ browse snapshot -i -C
 
 Every detected element gets a ref. `browse click @e3` just works.
 
-### 4. 40+ Purpose-Built Commands vs Generic Tools
+### 4. 58+ Purpose-Built Commands vs Generic Tools
 
 @playwright/mcp has ~15 tools. For anything beyond navigate/click/type, you write JavaScript via `browser_evaluate`. `browse` has purpose-built commands that return structured, minimal output:
 
@@ -108,6 +108,17 @@ Every detected element gets a ref. `browse click @e3` just works.
 | Snapshot diff | Not available | `snapshot-diff` |
 | Responsive screenshots | Not available | `responsive` |
 | Device emulation | Not available | `emulate iphone` |
+| Input value | `browser_evaluate` + custom JS | `value <sel>` |
+| Element count | `browser_evaluate` + custom JS | `count <sel>` |
+| iframe targeting | Not available | `frame <sel>` / `frame main` |
+| Network mocking | Not available | `route <pattern> block\|fulfill` |
+| Offline mode | Not available | `offline on\|off` |
+| State persistence | Not available | `state save\|load` |
+| Credential vault | Not available | `auth save\|login\|list` |
+| HAR recording | Not available | `har start\|stop` |
+| Domain restriction | Not available | `--allowed-domains` |
+| Prompt injection defense | Not available | `--content-boundaries` |
+| JSON output mode | Not available | `--json` |
 
 ### 5. Persistent Daemon — 100ms Commands
 
@@ -167,10 +178,10 @@ For full process isolation (separate Chromium instances), use `BROWSE_PORT` to r
 ## Install
 
 ```bash
-bun install -g @ulpi/browse
+npm install -g @ulpi/browse
 ```
 
-Requires [Bun](https://bun.sh). Chromium is installed automatically via Playwright.
+Requires [Bun](https://bun.sh) runtime. Chromium is installed automatically via Playwright.
 
 ### Claude Code Skill
 
@@ -222,7 +233,7 @@ browse click @e52
 `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>`
+`click <sel>` | `dblclick <sel>` | `fill <sel> <val>` | `select <sel> <val>` | `hover <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]`
 
 ### Snapshot & Refs
 ```
@@ -244,7 +255,7 @@ After snapshot, use `@e1`, `@e2`... as selectors in any command.
 100+ devices: iPhone 12-17, Pixel 5-7, iPad, Galaxy, and all Playwright built-ins.
 
 ### Inspection
-`js <expr>` | `eval <file>` | `css <sel> <prop>` | `attrs <sel>` | `state <sel>` | `console [--clear]` | `network [--clear]` | `cookies` | `storage [set <k> <v>]` | `perf`
+`js <expr>` | `eval <file>` | `css <sel> <prop>` | `attrs <sel>` | `element-state <sel>` | `value <sel>` | `count <sel>` | `console [--clear]` | `network [--clear]` | `cookies` | `storage [set <k> <v>]` | `perf`
 
 ### Visual
 `screenshot [path]` | `screenshot --annotate` | `pdf [path]` | `responsive [prefix]`
@@ -260,9 +271,21 @@ echo '[["goto","https://example.com"],["text"]]' | browse chain
 ### Tabs
 `tabs` | `tab <id>` | `newtab [url]` | `closetab [id]`
 
+### Frames
+`frame <sel>` | `frame main`
+
 ### Sessions
 `sessions` | `session-close <id>`
 
+### Network
+`route <pattern> block` | `route <pattern> fulfill <status> [body]` | `route clear` | `offline [on|off]`
+
+### State & Auth
+`state save [name]` | `state load [name]` | `auth save <name> <url> <user> <pass>` | `auth login <name>` | `auth list` | `auth delete <name>`
+
+### Recording
+`har start` | `har stop [path]`
+
 ### Server Control
 `status` | `cookie <n>=<v>` | `header <n>:<v>` | `useragent <str>` | `stop` | `restart`
 
@@ -293,8 +316,16 @@ browse [--session <id>] <command>
 |----------|---------|-------------|
 | `BROWSE_PORT` | auto 9400-10400 | Fixed server port |
 | `BROWSE_SESSION` | (none) | Default session ID for all commands |
+| `BROWSE_INSTANCE` | auto (PPID) | Instance ID for multi-Claude isolation |
 | `BROWSE_IDLE_TIMEOUT` | 1800000 (30m) | Idle shutdown in ms |
+| `BROWSE_TIMEOUT` | (none) | Override all command timeouts (ms) |
 | `BROWSE_LOCAL_DIR` | `.browse/` or `/tmp` | State/log directory |
+| `BROWSE_JSON` | (none) | Set to `1` for JSON output mode |
+| `BROWSE_CONTENT_BOUNDARIES` | (none) | Set to `1` for nonce-delimited output |
+| `BROWSE_ALLOWED_DOMAINS` | (none) | Comma-separated domain allowlist |
+| `BROWSE_PROXY` | (none) | Proxy server URL |
+| `BROWSE_PROXY_BYPASS` | (none) | Proxy bypass list |
+| `BROWSE_CDP_URL` | (none) | Connect to remote Chrome via CDP |
 
 ## Acknowledgments
 
@@ -302,28 +333,44 @@ Inspired by and originally derived from the `/browse` skill in [gstack](https://
 
 ### Added beyond gstack
 
-**New commands:**
-- `emulate` / `devices` — device emulation with 100+ devices (iPhone, Pixel, iPad, custom descriptors)
-- `snapshot -C` — cursor-interactive detection (cursor:pointer, onclick, tabindex, data-action)
+**v0.1.0 — Foundation:**
+- `emulate` / `devices` — device emulation (100+ devices)
+- `snapshot -C` — cursor-interactive detection
 - `snapshot-diff` — before/after comparison with ref-number stripping
-- `dialog` / `dialog-accept` / `dialog-dismiss` — dialog handling with prompt value support
-- `state` — element state inspection (visible, enabled, checked, focused, bounding box)
-- `upload` — file upload to input elements
-- `sessions` / `session-close` — multi-agent session multiplexing
+- `dialog` / `dialog-accept` / `dialog-dismiss` — dialog handling
+- `upload` — file upload
 - `screenshot --annotate` — numbered badge overlay with legend
-
-**Architectural improvements:**
-- Session multiplexing — multiple agents share one Chromium via isolated BrowserContexts
-- Per-tab ref scoping — refs belong to the tab that created them, cross-tab usage throws clear error
-- Per-tab snapshot baselines — `snapshot-diff` compares the correct baseline after tab switches
-- Safe retry classification — read commands auto-retry after crash, write commands don't (prevents double form submissions)
-- Concurrency-safe server spawning — file lock with stale detection prevents race conditions
-- Network correlation via WeakMap — accurate request/response pairing even with duplicate URLs
-- Content-Length based sizing — avoids reading response bodies into memory
-- TreeWalker text extraction — `text` command never triggers MutationObservers
-- Tab creation rollback — failed `newTab(url)` closes the page instead of leaving orphan tabs
-- Context recreation with rollback — `emulate`/`useragent` preserve cookies and all tab URLs, rollback on failure
-- Crash callback — server flushes buffers and cleans state file before exit
+- Session multiplexing — multiple agents share one Chromium
+- Safe retry classification — read vs write commands
+- TreeWalker text extraction — no MutationObserver triggers
+
+**v0.2.0 — Security, Interactions, DX:**
+- `--json` — structured output mode for agent frameworks
+- `--content-boundaries` — CSPRNG nonce wrapping for prompt injection defense
+- `--allowed-domains` — domain allowlist (HTTP + WebSocket/EventSource/sendBeacon)
+- `browse-policy.json` — action policy gate (allow/deny/confirm per command)
+- `auth save/login/list/delete` — AES-256-GCM encrypted credential vault
+- `dblclick`, `focus`, `check`, `uncheck`, `drag`, `keydown`, `keyup` — interaction commands
+- `frame <sel>` / `frame main` — iframe targeting
+- `value <sel>`, `count <sel>` — element inspection
+- `scroll up/down` — viewport-relative scrolling
+- `wait --url`, `wait --network-idle` — navigation/network wait variants
+- `highlight <sel>` — visual element debugging
+- `download <sel> [path]` — file download
+- `route <pattern> block/fulfill` — network request interception and mocking
+- `offline on/off` — offline mode toggle
+- `state save/load` — persist and restore cookies + localStorage (all origins)
+- `har start/stop` — HAR recording and export
+- `screenshot-diff` — pixel-level visual regression testing
+- `find role/text/label/placeholder/testid` — semantic element locators
+- Auto-instance servers via PPID — multi-Claude isolation
+- Per-session output folders (`.browse/sessions/{id}/`)
+- `browse.json` config file support
+- AI-friendly error messages — Playwright errors rewritten to actionable hints
+- CDP remote connection (`BROWSE_CDP_URL`)
+- Proxy support (`BROWSE_PROXY`)
+- Compiled binary self-spawn mode
+- Orphaned server cleanup
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"

package/src/browser-manager.ts

@@ -139,7 +139,7 @@ export class BrowserManager {
   private currentDevice: DeviceDescriptor | null = null;
 
   // ─── iframe targeting ─────────────────────────────────────
-  private activeFrameSelector: string | null = null;
+  private activeFramePerTab: Map<number, string> = new Map();
 
   // ─── Per-session buffers ──────────────────────────────────
   private buffers: SessionBuffers;
@@ -357,6 +357,10 @@ export class BrowserManager {
     return page;
   }
 
+  getPageById(id: number): Page | undefined {
+    return this.pages.get(id);
+  }
+
   getCurrentUrl(): string {
     try {
       return this.getPage().url();
@@ -372,21 +376,21 @@ export class BrowserManager {
    * will target this frame's content instead of the main page.
    */
   setFrame(selector: string) {
-    this.activeFrameSelector = selector;
+    this.activeFramePerTab.set(this.activeTabId, selector);
   }
 
   /**
-   * Reset to main frame — clears the active frame selector.
+   * Reset to main frame — clears the active frame selector for the current tab.
    */
   resetFrame() {
-    this.activeFrameSelector = null;
+    this.activeFramePerTab.delete(this.activeTabId);
   }
 
   /**
    * Get the current active frame selector, or null if targeting main page.
    */
   getActiveFrameSelector(): string | null {
-    return this.activeFrameSelector;
+    return this.activeFramePerTab.get(this.activeTabId) ?? null;
   }
 
   /**
@@ -394,8 +398,9 @@ export class BrowserManager {
    * Returns null if no frame is active (targeting main page).
    */
   getFrameLocator(): FrameLocator | null {
-    if (!this.activeFrameSelector) return null;
-    return this.getPage().frameLocator(this.activeFrameSelector);
+    const sel = this.getActiveFrameSelector();
+    if (!sel) return null;
+    return this.getPage().frameLocator(sel);
   }
 
   /**
@@ -404,13 +409,14 @@ export class BrowserManager {
    * Unlike FrameLocator, Frame supports evaluate(), querySelector, etc.
    */
   async getFrameContext(): Promise<Frame | null> {
-    if (!this.activeFrameSelector) return null;
+    const sel = this.getActiveFrameSelector();
+    if (!sel) return null;
     const page = this.getPage();
-    const frameEl = page.locator(this.activeFrameSelector);
+    const frameEl = page.locator(sel);
     const handle = await frameEl.elementHandle({ timeout: 5000 });
-    if (!handle) throw new Error(`Frame element not found: ${this.activeFrameSelector}`);
+    if (!handle) throw new Error(`Frame element not found: ${sel}`);
     const frame = await handle.contentFrame();
-    if (!frame) throw new Error(`Cannot access content of frame: ${this.activeFrameSelector}`);
+    if (!frame) throw new Error(`Cannot access content of frame: ${sel}`);
     return frame;
   }
 
@@ -420,8 +426,9 @@ export class BrowserManager {
    * Example: bm.getLocatorRoot().locator('button.submit')
    */
   getLocatorRoot(): Page | FrameLocator {
-    if (this.activeFrameSelector) {
-      return this.getPage().frameLocator(this.activeFrameSelector);
+    const sel = this.getActiveFrameSelector();
+    if (sel) {
+      return this.getPage().frameLocator(sel);
     }
     return this.getPage();
   }
@@ -463,8 +470,9 @@ 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);
+    const frameSel = this.getActiveFrameSelector();
+    if (frameSel) {
+      const frame = this.getPage().frameLocator(frameSel);
       return { locator: frame.locator(selector) };
     }
     return { selector };
@@ -573,15 +581,7 @@ export class BrowserManager {
       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
+      // Re-apply user routes FIRST
       for (const r of this.userRoutes) {
         if (r.action === 'block') {
           await newContext.route(r.pattern, (route) => route.abort('blockedbyclient'));
@@ -589,6 +589,14 @@ export class BrowserManager {
           await newContext.route(r.pattern, (route) => route.fulfill({ status: r.status || 200, body: r.body || '', contentType: 'text/plain' }));
         }
       }
+      // Re-apply domain filter route LAST (Playwright: last registered = checked first)
+      if (this.domainFilter) {
+        const df = this.domainFilter;
+        await newContext.route('**/*', (route) => {
+          const url = route.request().url();
+          if (df.isAllowed(url)) { route.fallback(); } else { route.abort('blockedbyclient'); }
+        });
+      }
     } catch (err) {
       await newContext.close().catch(() => {});
       throw err;
@@ -601,6 +609,7 @@ export class BrowserManager {
     const oldNextTabId = this.nextTabId;
     const oldTabSnapshots = new Map(this.tabSnapshots);
     const oldRefMap = new Map(this.refMap);
+    const oldFramePerTab = new Map(this.activeFramePerTab);
 
     // Swap to new context
     this.context = newContext;
@@ -638,6 +647,7 @@ export class BrowserManager {
       this.nextTabId = oldNextTabId;
       this.tabSnapshots = oldTabSnapshots;
       this.refMap = oldRefMap;
+      this.activeFramePerTab = oldFramePerTab;
       throw err;
     }
 
@@ -650,6 +660,16 @@ export class BrowserManager {
       }
     }
 
+    // Migrate activeFramePerTab: remap old tab IDs to new tab IDs
+    const oldFrames = new Map(this.activeFramePerTab);
+    this.activeFramePerTab.clear();
+    for (const [oldId, sel] of oldFrames) {
+      const newId = idMap.get(oldId);
+      if (newId !== undefined) {
+        this.activeFramePerTab.set(newId, sel);
+      }
+    }
+
     // Success — close old pages and context
     for (const [, page] of oldPages) {
       await page.close().catch(() => {});

package/src/cli.ts

@@ -36,7 +36,10 @@ const INSTANCE_SUFFIX = BROWSE_PORT ? `-${BROWSE_PORT}` : (BROWSE_INSTANCE ? `-$
  * Falls back to /tmp/ if not found (e.g. running outside a project).
  */
 function resolveLocalDir(): string {
-  if (process.env.BROWSE_LOCAL_DIR) return process.env.BROWSE_LOCAL_DIR;
+  if (process.env.BROWSE_LOCAL_DIR) {
+    try { fs.mkdirSync(process.env.BROWSE_LOCAL_DIR, { recursive: true }); } catch {}
+    return process.env.BROWSE_LOCAL_DIR;
+  }
 
   let dir = process.cwd();
   for (let i = 0; i < 20; i++) {
@@ -121,6 +124,16 @@ function isProcessAlive(pid: number): boolean {
   }
 }
 
+function isBrowseProcess(pid: number): boolean {
+  try {
+    const { execSync } = require('child_process');
+    const cmd = execSync(`ps -p ${pid} -o command=`, { encoding: 'utf-8' }).trim();
+    return cmd.includes('browse') || cmd.includes('__BROWSE_SERVER_MODE');
+  } catch {
+    return false;
+  }
+}
+
 // ─── Server Lifecycle ──────────────────────────────────────────
 
 /**
@@ -249,16 +262,18 @@ async function ensureServer(): Promise<ServerState> {
     }
 
     // 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);
+    // Kill it so we can start fresh — but only if it's actually a browse process.
+    if (isBrowseProcess(state.pid)) {
+      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);
+      }
     }
   }
 
@@ -287,13 +302,23 @@ function cleanOrphanedServers(): void {
       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
+      // Only clean files with PID-based suffixes. Skip port-based and non-numeric.
+      // Port-based files have a port number from a BROWSE_PORT env var.
+      // PID-based files have a process ID (typically >10000, never <1000).
+      // To distinguish: read the state file and check if the suffix matches the PID inside.
+      const suffixMatch = file.match(/browse-server-(\d+)\.json$/);
+      if (!suffixMatch) continue;
+      const suffix = parseInt(suffixMatch[1], 10);
       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 {}
-          }
+        if (!data.pid) continue;
+        // Port-based file: suffix matches the port inside (intentional BROWSE_PORT instance)
+        if (data.port === suffix) continue;
+        // PID-based file: suffix was a PPID from the spawning CLI
+        if (isProcessAlive(data.pid) && isBrowseProcess(data.pid)) {
+          try { process.kill(data.pid, 'SIGTERM'); } catch {}
+        }
+        if (!isProcessAlive(data.pid)) {
           fs.unlinkSync(filePath);
         }
       } catch {}
@@ -314,7 +339,7 @@ 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',
+  'tabs', 'status', 'url', 'snapshot', 'snapshot-diff', 'devices', 'sessions', 'frame', 'find',
 ]);
 
 // Commands that return static data independent of page state.
@@ -443,41 +468,52 @@ export async function main() {
   // Load project config (browse.json) — values serve as defaults
   const config = loadConfig();
 
-  // Extract --session flag before command parsing
+  // Find the first non-flag arg (the command) to limit global flag scanning.
+  // Only extract global flags from args BEFORE the command position.
+  function findCommandIndex(a: string[]): number {
+    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++;
+    }
+    return a.length;
+  }
+
+  // Extract --session flag (only before command)
   let sessionId: string | undefined;
   const sessionIdx = args.indexOf('--session');
-  if (sessionIdx !== -1) {
+  if (sessionIdx !== -1 && sessionIdx < findCommandIndex(args)) {
     sessionId = args[sessionIdx + 1];
     if (!sessionId || sessionId.startsWith('-')) {
       console.error('Usage: browse --session <id> <command> [args...]');
       process.exit(1);
     }
-    args.splice(sessionIdx, 2); // remove --session and its value
+    args.splice(sessionIdx, 2);
   }
   sessionId = sessionId || process.env.BROWSE_SESSION || config.session || undefined;
 
-  // Extract --json flag
+  // Extract --json flag (only before command)
   let jsonMode = false;
   const jsonIdx = args.indexOf('--json');
-  if (jsonIdx !== -1) {
+  if (jsonIdx !== -1 && jsonIdx < findCommandIndex(args)) {
     jsonMode = true;
     args.splice(jsonIdx, 1);
   }
   jsonMode = jsonMode || process.env.BROWSE_JSON === '1' || config.json === true;
 
-  // Extract --content-boundaries flag
+  // Extract --content-boundaries flag (only before command)
   let contentBoundaries = false;
   const boundIdx = args.indexOf('--content-boundaries');
-  if (boundIdx !== -1) {
+  if (boundIdx !== -1 && boundIdx < findCommandIndex(args)) {
     contentBoundaries = true;
     args.splice(boundIdx, 1);
   }
   contentBoundaries = contentBoundaries || process.env.BROWSE_CONTENT_BOUNDARIES === '1' || config.contentBoundaries === true;
 
-  // Extract --allowed-domains flag
+  // Extract --allowed-domains flag (only before command)
   let allowedDomains: string | undefined;
   const domIdx = args.indexOf('--allowed-domains');
-  if (domIdx !== -1) {
+  if (domIdx !== -1 && domIdx < findCommandIndex(args)) {
     allowedDomains = args[domIdx + 1];
     if (!allowedDomains || allowedDomains.startsWith('-')) {
       console.error('Usage: browse --allowed-domains domain1,domain2 <command> [args...]');
@@ -519,7 +555,8 @@ Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
                 value <sel> | count <sel>
 Visual:         screenshot [path] | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-c] [-C] [-d N] [-s sel]
-Compare:        diff <url1> <url2>
+Find:           find role|text|label|placeholder|testid <query> [name]
+Compare:        diff <url1> <url2> | screenshot-diff <baseline> [current]
 Multi-step:     chain (reads JSON from stdin)
 Network:        offline [on|off] | route <pattern> block|fulfill
 Recording:      har start | har stop [path]
@@ -528,7 +565,7 @@ 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]
+State:          state save|load|list|show [name]
 Server:         status | cookie <n>=<v> | header <n>:<v>
                 useragent <str> | stop | restart
 Setup:          install-skill [path]
@@ -561,6 +598,13 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
     commandArgs.push(stdin.trim());
   }
 
+  // Special case: auth --password-stdin reads in CLI before sending to server
+  if (command === 'auth' && commandArgs.includes('--password-stdin')) {
+    const stdinIdx = commandArgs.indexOf('--password-stdin');
+    const password = (await Bun.stdin.text()).trim();
+    commandArgs.splice(stdinIdx, 1, password);
+  }
+
   const state = await ensureServer();
   await sendCommand(state, command, commandArgs, 0, sessionId);
 }

package/src/commands/meta.ts

@@ -97,6 +97,33 @@ export async function handleMetaCommand(
       if (!sessionManager) throw new Error('Session management not available');
       const id = args[0];
       if (!id) throw new Error('Usage: browse session-close <id>');
+      // Flush buffers before closing so logs aren't lost
+      const closingSession = sessionManager.getAllSessions().find(s => s.id === id);
+      if (closingSession) {
+        const buffers = closingSession.buffers;
+        const consolePath = `${closingSession.outputDir}/console.log`;
+        const networkPath = `${closingSession.outputDir}/network.log`;
+        const newConsoleCount = buffers.consoleTotalAdded - buffers.lastConsoleFlushed;
+        if (newConsoleCount > 0) {
+          const count = Math.min(newConsoleCount, buffers.consoleBuffer.length);
+          const entries = buffers.consoleBuffer.slice(-count);
+          const lines = entries.map(e =>
+            `[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
+          ).join('\n') + '\n';
+          fs.appendFileSync(consolePath, lines);
+          buffers.lastConsoleFlushed = buffers.consoleTotalAdded;
+        }
+        const newNetworkCount = buffers.networkTotalAdded - buffers.lastNetworkFlushed;
+        if (newNetworkCount > 0) {
+          const count = Math.min(newNetworkCount, buffers.networkBuffer.length);
+          const entries = buffers.networkBuffer.slice(-count);
+          const lines = entries.map(e =>
+            `[${new Date(e.timestamp).toISOString()}] ${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
+          ).join('\n') + '\n';
+          fs.appendFileSync(networkPath, lines);
+          buffers.lastNetworkFlushed = buffers.networkTotalAdded;
+        }
+      }
       await sessionManager.closeSession(id);
       return `Session "${id}" closed`;
     }
@@ -104,13 +131,42 @@ export async function handleMetaCommand(
     // ─── 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]');
+      if (!subcommand || !['save', 'load', 'list', 'show'].includes(subcommand)) {
+        throw new Error('Usage: browse state save|load|list|show [name]');
       }
       const name = sanitizeName(args[1] || 'default');
       const statesDir = `${LOCAL_DIR}/states`;
       const statePath = `${statesDir}/${name}.json`;
 
+      if (subcommand === 'list') {
+        if (!fs.existsSync(statesDir)) return '(no saved states)';
+        const files = fs.readdirSync(statesDir).filter(f => f.endsWith('.json'));
+        if (files.length === 0) return '(no saved states)';
+        const lines: string[] = [];
+        for (const file of files) {
+          const fp = `${statesDir}/${file}`;
+          const stat = fs.statSync(fp);
+          lines.push(`  ${file.replace('.json', '')}  ${stat.size}B  ${new Date(stat.mtimeMs).toISOString()}`);
+        }
+        return lines.join('\n');
+      }
+
+      if (subcommand === 'show') {
+        if (!fs.existsSync(statePath)) {
+          throw new Error(`State file not found: ${statePath}`);
+        }
+        const data = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        const cookieCount = data.cookies?.length || 0;
+        const originCount = data.origins?.length || 0;
+        const storageItems = (data.origins || []).reduce((sum: number, o: any) => sum + (o.localStorage?.length || 0), 0);
+        return [
+          `State: ${name}`,
+          `Cookies: ${cookieCount}`,
+          `Origins: ${originCount}`,
+          `Storage items: ${storageItems}`,
+        ].join('\n');
+      }
+
       if (subcommand === 'save') {
         const context = bm.getContext();
         if (!context) throw new Error('No browser context');
@@ -125,27 +181,37 @@ export async function handleMetaCommand(
           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');
+        const warnings: string[] = [];
         if (stateData.cookies?.length) {
-          await context.addCookies(stateData.cookies);
+          try {
+            await context.addCookies(stateData.cookies);
+          } catch (err: any) {
+            warnings.push(`Cookies: ${err.message}`);
+          }
         }
-        // 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(() => {});
+              try {
+                const page = bm.getPage();
+                await page.goto(origin.origin, { waitUntil: 'domcontentloaded', timeout: 5000 });
+                for (const item of origin.localStorage) {
+                  await page.evaluate(([k, v]) => localStorage.setItem(k, v), [item.name, item.value]);
+                }
+              } catch (err: any) {
+                warnings.push(`Storage for ${origin.origin}: ${err.message}`);
               }
             }
           }
         }
+        if (warnings.length > 0) {
+          return `State loaded: ${statePath} (${warnings.length} warning(s))\n${warnings.join('\n')}`;
+        }
         return `State loaded: ${statePath}`;
       }
-      throw new Error('Usage: browse state save [name] | browse state load [name]');
+      throw new Error('Usage: browse state save|load|list|show [name]');
     }
 
     // ─── Visual ────────────────────────────────────────
@@ -300,7 +366,7 @@ export async function handleMetaCommand(
           }
 
           let result: string;
-          if (WRITE_SET.has(name))      result = await handleWriteCommand(name, cmdArgs, bm);
+          if (WRITE_SET.has(name))      result = await handleWriteCommand(name, cmdArgs, bm, currentSession?.domainFilter);
           else if (READ_SET.has(name))  result = await handleReadCommand(name, cmdArgs, bm, sessionBuffers);
           else                          result = await handleMetaCommand(name, cmdArgs, bm, shutdown, sessionManager, currentSession);
           results.push(`[${name}] ${result}`);
@@ -413,6 +479,59 @@ export async function handleMetaCommand(
       return output.join('\n');
     }
 
+    // ─── Screenshot Diff ──────────────────────────────
+    case 'screenshot-diff': {
+      const baseline = args[0];
+      if (!baseline) throw new Error('Usage: browse screenshot-diff <baseline> [current] [--threshold 0.1]');
+      if (!fs.existsSync(baseline)) throw new Error(`Baseline file not found: ${baseline}`);
+
+      let thresholdPct = 0.1;
+      const threshIdx = args.indexOf('--threshold');
+      if (threshIdx !== -1 && args[threshIdx + 1]) {
+        thresholdPct = parseFloat(args[threshIdx + 1]);
+      }
+
+      const baselineBuffer = fs.readFileSync(baseline);
+
+      // Find optional current image path: any non-flag arg after baseline
+      let currentBuffer: Buffer;
+      let currentPath: string | undefined;
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--threshold') { i++; continue; }
+        if (!args[i].startsWith('--')) { currentPath = args[i]; break; }
+      }
+      if (currentPath) {
+        if (!fs.existsSync(currentPath)) throw new Error(`Current screenshot not found: ${currentPath}`);
+        currentBuffer = fs.readFileSync(currentPath);
+      } else {
+        const page = bm.getPage();
+        currentBuffer = await page.screenshot({ fullPage: true }) as Buffer;
+      }
+
+      const { compareScreenshots } = await import('../png-compare');
+      const result = compareScreenshots(baselineBuffer, currentBuffer, thresholdPct);
+
+      // Diff path: append -diff before extension, or add -diff.png if no extension
+      const extIdx = baseline.lastIndexOf('.');
+      const diffPath = extIdx > 0
+        ? baseline.slice(0, extIdx) + '-diff' + baseline.slice(extIdx)
+        : baseline + '-diff.png';
+      if (!result.passed) {
+        // Write current screenshot as the "what changed" artifact
+        // (true pixel-diff image generation requires re-rendering differences)
+        fs.writeFileSync(diffPath, currentBuffer);
+      }
+
+      return [
+        `Pixels: ${result.totalPixels}`,
+        `Different: ${result.diffPixels}`,
+        `Mismatch: ${result.mismatchPct.toFixed(3)}%`,
+        `Threshold: ${thresholdPct}%`,
+        `Result: ${result.passed ? 'PASS' : 'FAIL'}`,
+        ...(!result.passed ? [`Current saved: ${diffPath}`] : []),
+      ].join('\n');
+    }
+
     // ─── Auth Vault ─────────────────────────────────────
     case 'auth': {
       const subcommand = args[0];
@@ -422,15 +541,24 @@ export async function handleMetaCommand(
       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;
+          // Parse optional selector flags first (Task 9: scan flags before positional args)
+          let userSel: string | undefined;
+          let passSel: string | undefined;
+          let submitSel: string | undefined;
+          const positionalAfterUsername: string[] = [];
+          const knownFlags = new Set(['--user-sel', '--pass-sel', '--submit-sel']);
+          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]; }
+            else if (!knownFlags.has(args[i])) { positionalAfterUsername.push(args[i]); }
+          }
+          // Password: from positional arg (after username), or env var
+          // (--password-stdin is handled in CLI before reaching server)
+          let password: string | undefined = positionalAfterUsername[0];
           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' +
@@ -438,15 +566,6 @@ export async function handleMetaCommand(
               '       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}`;
@@ -502,6 +621,48 @@ export async function handleMetaCommand(
       throw new Error('Usage: browse har start | browse har stop [path]');
     }
 
+    // ─── Semantic Locator ──────────────────────────────
+    case 'find': {
+      const root = bm.getLocatorRoot();
+      const sub = args[0];
+      if (!sub) throw new Error('Usage: browse find role|text|label|placeholder|testid <query> [name]');
+      const query = args[1];
+      if (!query) throw new Error(`Usage: browse find ${sub} <query>`);
+
+      let locator;
+      switch (sub) {
+        case 'role': {
+          const nameOpt = args[2];
+          locator = nameOpt ? root.getByRole(query as any, { name: nameOpt }) : root.getByRole(query as any);
+          break;
+        }
+        case 'text':
+          locator = root.getByText(query);
+          break;
+        case 'label':
+          locator = root.getByLabel(query);
+          break;
+        case 'placeholder':
+          locator = root.getByPlaceholder(query);
+          break;
+        case 'testid':
+          locator = root.getByTestId(query);
+          break;
+        default:
+          throw new Error(`Unknown find type: ${sub}. Use role|text|label|placeholder|testid`);
+      }
+
+      const count = await locator.count();
+      let firstText = '';
+      if (count > 0) {
+        try {
+          firstText = (await locator.first().textContent({ timeout: 2000 })) || '';
+          firstText = firstText.trim().slice(0, 100);
+        } catch {}
+      }
+      return `Found ${count} match(es)${firstText ? `: "${firstText}"` : ''}`;
+    }
+
     // ─── iframe Targeting ─────────────────────────────
     case 'frame': {
       if (args[0] === 'main' || args[0] === 'top') {

package/src/commands/write.ts

@@ -6,12 +6,36 @@
  * header, useragent, drag, keydown, keyup
  */
 
+import type { BrowserContext } from 'playwright';
 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';
 
+/**
+ * Clear all routes and re-register them in correct order:
+ * user routes first, domain filter last (Playwright checks last-registered first).
+ */
+async function rebuildRoutes(context: BrowserContext, bm: BrowserManager, domainFilter?: DomainFilter | null): Promise<void> {
+  await context.unrouteAll();
+  // User routes first (checked last by Playwright)
+  for (const r of bm.getUserRoutes()) {
+    if (r.action === 'block') {
+      await context.route(r.pattern, (route) => route.abort('blockedbyclient'));
+    } else {
+      await context.route(r.pattern, (route) => route.fulfill({ status: r.status || 200, body: r.body || '', contentType: 'text/plain' }));
+    }
+  }
+  // Domain filter last (checked first by Playwright)
+  if (domainFilter) {
+    await context.route('**/*', (route) => {
+      const url = route.request().url();
+      if (domainFilter.isAllowed(url)) { route.fallback(); } else { route.abort('blockedbyclient'); }
+    });
+  }
+}
+
 export async function handleWriteCommand(
   command: string,
   args: string[],
@@ -64,7 +88,7 @@ export async function handleWriteCommand(
     case 'fill': {
       const [selector, ...valueParts] = args;
       const value = valueParts.join(' ');
-      if (!selector || !value) throw new Error('Usage: browse fill <selector> <value>');
+      if (!selector) throw new Error('Usage: browse fill <selector> <value>');
       const resolved = bm.resolveRef(selector);
       if ('locator' in resolved) {
         await resolved.locator.fill(value, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
@@ -77,7 +101,7 @@ export async function handleWriteCommand(
     case 'select': {
       const [selector, ...valueParts] = args;
       const value = valueParts.join(' ');
-      if (!selector || !value) throw new Error('Usage: browse select <selector> <value>');
+      if (!selector) throw new Error('Usage: browse select <selector> <value>');
       const resolved = bm.resolveRef(selector);
       if ('locator' in resolved) {
         await resolved.locator.selectOption(value, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
@@ -420,7 +444,7 @@ export async function handleWriteCommand(
         if (domainFilter) {
           await context.route('**/*', (route) => {
             const url = route.request().url();
-            if (domainFilter!.isAllowed(url)) { route.continue(); } else { route.abort('blockedbyclient'); }
+            if (domainFilter!.isAllowed(url)) { route.fallback(); } else { route.abort('blockedbyclient'); }
           });
         }
         return domainFilter ? 'All routes cleared (domain filter preserved)' : 'All routes cleared';
@@ -429,18 +453,16 @@ export async function handleWriteCommand(
       const action = args[1] || 'block';
 
       if (action === 'block') {
-        await context.route(pattern, (route) => route.abort('blockedbyclient'));
         bm.addUserRoute(pattern, 'block');
+        await rebuildRoutes(context, bm, domainFilter);
         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);
+        await rebuildRoutes(context, bm, domainFilter);
         return `Mocking requests matching: ${pattern} → ${status}${body ? ` "${body}"` : ''}`;
       }
 

package/src/domain-filter.ts

@@ -20,7 +20,11 @@ export class DomainFilter {
    * Non-HTTP URLs (about:blank, data:, etc.) are always allowed.
    */
   isAllowed(url: string): boolean {
-    // Non-HTTP(S) URLs are always allowed
+    // Block file:// and javascript: URLs — security risk
+    if (url.startsWith('file://') || url.startsWith('javascript:')) {
+      return false;
+    }
+    // Non-HTTP(S) URLs (about:blank, data:, blob:) are always allowed
     if (!url.startsWith('http://') && !url.startsWith('https://')) {
       return true;
     }
@@ -79,7 +83,9 @@ export class DomainFilter {
     // Normalize ws/wss to http/https for URL parsing
     if (str.startsWith('ws://')) str = 'http://' + str.slice(5);
     else if (str.startsWith('wss://')) str = 'https://' + str.slice(6);
-    // Non-HTTP(S) always allowed (data:, blob:, etc.)
+    // Block file:// and javascript: URLs
+    if (str.startsWith('file://') || str.startsWith('javascript:')) return false;
+    // Non-HTTP(S) always allowed (data:, blob:, about:)
     if (!str.startsWith('http://') && !str.startsWith('https://')) return true;
     var hostname;
     try { hostname = new URL(str).hostname.toLowerCase(); } catch(e) { return false; }

package/src/png-compare.ts

@@ -0,0 +1,138 @@
+/**
+ * Self-contained PNG decoder + pixel comparator.
+ * No external deps — uses only zlib.inflateSync (Node/Bun built-in).
+ * Works in both dev mode (bun run) and compiled binary ($bunfs).
+ *
+ * Supports: 8-bit RGB (color type 2) and RGBA (color type 6).
+ * Handles all 5 PNG scanline filter types (None/Sub/Up/Average/Paeth).
+ */
+
+import * as zlib from 'zlib';
+
+const PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+
+export interface DecodedImage {
+  width: number;
+  height: number;
+  data: Buffer; // RGBA pixels
+}
+
+export interface CompareResult {
+  totalPixels: number;
+  diffPixels: number;
+  mismatchPct: number;
+  passed: boolean;
+}
+
+export function decodePNG(buf: Buffer): DecodedImage {
+  for (let i = 0; i < 8; i++) {
+    if (buf[i] !== PNG_MAGIC[i]) throw new Error('Not a valid PNG file');
+  }
+
+  const width = buf.readUInt32BE(16);
+  const height = buf.readUInt32BE(20);
+  const bitDepth = buf[24];
+  const colorType = buf[25];
+  const interlace = buf[28];
+
+  if (bitDepth !== 8) throw new Error(`Unsupported PNG bit depth: ${bitDepth} (only 8-bit supported)`);
+  if (colorType !== 2 && colorType !== 6) throw new Error(`Unsupported PNG color type: ${colorType} (only RGB=2 and RGBA=6 supported)`);
+  if (interlace !== 0) throw new Error('Interlaced PNGs are not supported');
+
+  const channels = colorType === 6 ? 4 : 3;
+  const stride = width * channels;
+
+  // Collect IDAT chunks
+  const idats: Buffer[] = [];
+  let off = 8;
+  while (off < buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    if (type === 'IDAT') idats.push(buf.slice(off + 8, off + 8 + len));
+    if (type === 'IEND') break;
+    off += 12 + len;
+  }
+
+  const raw = zlib.inflateSync(Buffer.concat(idats));
+  const pixels = Buffer.alloc(width * height * 4);
+  const prev = Buffer.alloc(stride);
+
+  for (let y = 0; y < height; y++) {
+    const filterType = raw[y * (stride + 1)];
+    const scanline = Buffer.from(raw.slice(y * (stride + 1) + 1, (y + 1) * (stride + 1)));
+
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? scanline[x - channels] : 0;
+      const b = prev[x];
+      const c = x >= channels ? prev[x - channels] : 0;
+
+      switch (filterType) {
+        case 0: break;
+        case 1: scanline[x] = (scanline[x] + a) & 0xff; break;
+        case 2: scanline[x] = (scanline[x] + b) & 0xff; break;
+        case 3: scanline[x] = (scanline[x] + ((a + b) >> 1)) & 0xff; break;
+        case 4: {
+          const p = a + b - c;
+          const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+          scanline[x] = (scanline[x] + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c)) & 0xff;
+          break;
+        }
+        default: throw new Error(`Unknown PNG filter type: ${filterType}`);
+      }
+    }
+
+    for (let x = 0; x < width; x++) {
+      const si = x * channels;
+      const di = (y * width + x) * 4;
+      pixels[di] = scanline[si];
+      pixels[di + 1] = scanline[si + 1];
+      pixels[di + 2] = scanline[si + 2];
+      pixels[di + 3] = channels === 4 ? scanline[si + 3] : 255;
+    }
+
+    scanline.copy(prev);
+  }
+
+  return { width, height, data: pixels };
+}
+
+export function compareScreenshots(
+  baselineBuf: Buffer,
+  currentBuf: Buffer,
+  thresholdPct: number = 0.1,
+  colorThreshold: number = 30,
+): CompareResult {
+  const base = decodePNG(baselineBuf);
+  const curr = decodePNG(currentBuf);
+
+  const w = Math.max(base.width, curr.width);
+  const h = Math.max(base.height, curr.height);
+  const totalPixels = w * h;
+  let diffPixels = 0;
+  // Squared color distance threshold. 0 = exact match (any difference counts).
+  const colorThreshSq = colorThreshold * colorThreshold * 3; // across R,G,B channels
+
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const inBase = x < base.width && y < base.height;
+      const inCurr = x < curr.width && y < curr.height;
+      if (!inBase || !inCurr) { diffPixels++; continue; }
+
+      const bi = (y * base.width + x) * 4;
+      const ci = (y * curr.width + x) * 4;
+      const dr = base.data[bi] - curr.data[ci];
+      const dg = base.data[bi + 1] - curr.data[ci + 1];
+      const db = base.data[bi + 2] - curr.data[ci + 2];
+      const distSq = dr * dr + dg * dg + db * db;
+      if (colorThreshold === 0 ? distSq > 0 : distSq > colorThreshSq) diffPixels++;
+    }
+  }
+
+  const mismatchPct = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;
+  return {
+    totalPixels,
+    diffPixels,
+    mismatchPct,
+    passed: mismatchPct <= thresholdPct,
+  };
+}

package/src/server.ts

@@ -125,9 +125,9 @@ const META_COMMANDS = new Set([
   'status', 'stop', 'restart',
   'screenshot', 'pdf', 'responsive',
   'chain', 'diff',
-  'url', 'snapshot', 'snapshot-diff',
+  'url', 'snapshot', 'snapshot-diff', 'screenshot-diff',
   'sessions', 'session-close',
-  'frame', 'state',
+  'frame', 'state', 'find',
   'auth', 'har',
 ]);
 
@@ -349,7 +349,7 @@ const flushInterval = setInterval(() => {
 const sessionCleanupInterval = setInterval(async () => {
   if (!sessionManager || isShuttingDown) return;
 
-  const closed = await sessionManager.closeIdleSessions(IDLE_TIMEOUT_MS);
+  const closed = await sessionManager.closeIdleSessions(IDLE_TIMEOUT_MS, (session) => flushSessionBuffers(session, true));
   for (const id of closed) {
     console.log(`[browse] Session "${id}" idle for ${IDLE_TIMEOUT_MS / 1000}s — closed`);
   }

package/src/session-manager.ts

@@ -53,7 +53,7 @@ export class SessionManager {
             await context.route('**/*', (route) => {
               const url = route.request().url();
               if (domainFilter.isAllowed(url)) {
-                route.continue();
+                route.fallback();
               } else {
                 route.abort('blockedbyclient');
               }
@@ -61,6 +61,13 @@ export class SessionManager {
             const initScript = domainFilter.generateInitScript();
             await context.addInitScript(initScript);
             session.manager.setInitScript(initScript);
+            // Inject filter script into ALL open tabs immediately
+            for (const tab of session.manager.getTabList()) {
+              try {
+                const page = session.manager.getPageById(tab.id);
+                if (page) await page.evaluate(initScript);
+              } catch {}
+            }
           }
           session.domainFilter = domainFilter;
         }
@@ -89,7 +96,7 @@ export class SessionManager {
           await context.route('**/*', (route) => {
             const url = route.request().url();
             if (domainFilter!.isAllowed(url)) {
-              route.continue();
+              route.fallback();
             } else {
               route.abort('blockedbyclient');
             }
@@ -132,12 +139,13 @@ export class SessionManager {
    * Close sessions idle longer than maxIdleMs.
    * Returns list of closed session IDs.
    */
-  async closeIdleSessions(maxIdleMs: number): Promise<string[]> {
+  async closeIdleSessions(maxIdleMs: number, flushFn?: (session: Session) => void): Promise<string[]> {
     const now = Date.now();
     const closed: string[] = [];
 
     for (const [id, session] of this.sessions) {
       if (now - session.lastActivity > maxIdleMs) {
+        if (flushFn) flushFn(session);
         await session.manager.close().catch(() => {});
         this.sessions.delete(id);
         closed.push(id);