@ulpi/browse 0.2.5 → 0.3.0

package/README.md

@@ -92,7 +92,7 @@ $ browse snapshot -i -C
 
 Every detected element gets a ref. `browse click @e3` just works.
 
-### 4. 58+ Purpose-Built Commands vs Generic Tools
+### 4. 75 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:
 
@@ -116,6 +116,9 @@ Every detected element gets a ref. `browse click @e3` just works.
 | State persistence | Not available | `state save\|load` |
 | Credential vault | Not available | `auth save\|login\|list` |
 | HAR recording | Not available | `har start\|stop` |
+| Clipboard access | Not available | `clipboard [write <text>]` |
+| Element finding | Not available | `find role\|text\|label\|placeholder\|testid` |
+| DevTools inspect | Not available | `inspect` |
 | Domain restriction | Not available | `--allowed-domains` |
 | Prompt injection defense | Not available | `--content-boundaries` |
 | JSON output mode | Not available | `--json` |
@@ -255,13 +258,17 @@ 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>` | `element-state <sel>` | `value <sel>` | `count <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>` | `clipboard [write <text>]` | `console [--clear]` | `network [--clear]` | `cookies` | `storage [set <k> <v>]` | `perf`
 
 ### Visual
 `screenshot [path]` | `screenshot --annotate` | `pdf [path]` | `responsive [prefix]`
 
 ### Compare
 `diff <url1> <url2>` — text diff between two pages.
+`screenshot-diff <baseline> [current]` — pixel-level visual regression testing.
+
+### Find
+`find role|text|label|placeholder|testid <query> [name]` — semantic element locators.
 
 ### Multi-Step
 ```bash
@@ -281,13 +288,16 @@ echo '[["goto","https://example.com"],["text"]]' | browse chain
 `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>`
+`state save [name]` | `state load [name]` | `state list` | `state show [name]` | `auth save <name> <url> <user> <pass>` | `auth login <name>` | `auth list` | `auth delete <name>`
 
 ### Recording
 `har start` | `har stop [path]`
 
+### Debug
+`inspect` — open DevTools debugger (requires `BROWSE_DEBUG_PORT`).
+
 ### Server Control
-`status` | `cookie <n>=<v>` | `header <n>:<v>` | `useragent <str>` | `stop` | `restart`
+`status` | `instances` | `cookie <n>=<v>` | `header <n>:<v>` | `useragent <str>` | `stop` | `restart`
 
 ## Architecture
 
@@ -310,11 +320,22 @@ browse [--session <id>] <command>
     Chromium (Playwright, headless, shared)
 ```
 
+## CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--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 |
+| `--headed` | Run browser in headed (visible) mode |
+
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `BROWSE_PORT` | auto 9400-10400 | Fixed server port |
+| `BROWSE_PORT_START` | 9400 | Start of port scan range |
 | `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 |
@@ -323,33 +344,35 @@ browse [--session <id>] <command>
 | `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_HEADED` | (none) | Set to `1` for headed (visible) browser mode |
 | `BROWSE_PROXY` | (none) | Proxy server URL |
 | `BROWSE_PROXY_BYPASS` | (none) | Proxy bypass list |
 | `BROWSE_CDP_URL` | (none) | Connect to remote Chrome via CDP |
+| `BROWSE_SERVER_SCRIPT` | auto-detected | Override path to server.ts |
+| `BROWSE_DEBUG_PORT` | (none) | Port for DevTools debugging (inspect command) |
+| `BROWSE_POLICY` | browse-policy.json | Path to action policy file |
+| `BROWSE_CONFIRM_ACTIONS` | (none) | Comma-separated commands requiring confirmation |
+| `BROWSE_ENCRYPTION_KEY` | auto-generated | 64-char hex AES key for credential vault |
+| `BROWSE_AUTH_PASSWORD` | (none) | Password for auth save (alt to `--password-stdin`) |
 
 ## Acknowledgments
 
 Inspired by and originally derived from the `/browse` skill in [gstack](https://github.com/garrytan/gstack) by Garry Tan. The core architecture — persistent Chromium daemon, thin CLI client, ref-based element selection via ARIA snapshots — comes from gstack.
 
-### Added beyond gstack
+## Changelog
 
-**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
-- `upload` — file upload
-- `screenshot --annotate` — numbered badge overlay with legend
-- Session multiplexing — multiple agents share one Chromium
-- Safe retry classification — read vs write commands
-- TreeWalker text extraction — no MutationObserver triggers
+### v0.3.0 — Headed Mode, Clipboard, DevTools
 
-**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
+- `--headed` flag — run browser in visible mode for debugging and demos
+- `clipboard [write <text>]` — read and write clipboard contents
+- `inspect` command — open DevTools debugger via `BROWSE_DEBUG_PORT`
+- `screenshot --annotate` — pixel-annotated PNG with numbered badges
+- `instances` command — list all running browse servers
+- `BROWSE_DEBUG_PORT` env var for DevTools debugging
+
+### v0.2.0 — Security, Interactions, DX
+
+**Commands:**
 - `dblclick`, `focus`, `check`, `uncheck`, `drag`, `keydown`, `keyup` — interaction commands
 - `frame <sel>` / `frame main` — iframe targeting
 - `value <sel>`, `count <sel>` — element inspection
@@ -363,15 +386,41 @@ Inspired by and originally derived from the `/browse` skill in [gstack](https://
 - `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}/`)
+
+**Security:**
+- `--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
+- `--content-boundaries` — CSPRNG nonce wrapping for prompt injection defense
+
+**DX:**
+- `--json` — structured output mode for agent frameworks
 - `browse.json` config file support
 - AI-friendly error messages — Playwright errors rewritten to actionable hints
+- Per-session output folders (`.browse/sessions/{id}/`)
+
+**Infrastructure:**
+- Auto-instance servers via PPID — multi-Claude isolation
 - CDP remote connection (`BROWSE_CDP_URL`)
 - Proxy support (`BROWSE_PROXY`)
 - Compiled binary self-spawn mode
 - Orphaned server cleanup
 
+### v0.1.0 — Foundation
+
+**Commands:**
+- `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
+- `upload` — file upload
+- `screenshot --annotate` — numbered badge overlay with legend
+
+**Infrastructure:**
+- Session multiplexing — multiple agents share one Chromium
+- Safe retry classification — read vs write commands
+- TreeWalker text extraction — no MutationObserver triggers
+
 ## License
 
 MIT

package/package.json

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

package/skill/SKILL.md

@@ -78,7 +78,10 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse route:*)", "Bash(browse offline:*)",
 "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
 "Bash(browse cookie:*)", "Bash(browse header:*)",
-"Bash(browse useragent:*)"
+"Bash(browse useragent:*)",
+"Bash(browse clipboard:*)", "Bash(browse screenshot-diff:*)",
+"Bash(browse find:*)", "Bash(browse inspect:*)",
+"Bash(browse instances:*)", "Bash(browse --headed:*)"
 ```
 
 ## IMPORTANT
@@ -201,6 +204,25 @@ browse emulate reset
 # Parallel sessions
 browse --session agent-a goto https://site1.com
 browse --session agent-b goto https://site2.com
+
+# Clipboard
+browse clipboard
+browse clipboard write "copied text"
+
+# Find elements semantically
+browse find role button
+browse find text "Submit"
+browse find testid "login-btn"
+
+# Screenshot diff (visual regression)
+browse screenshot-diff baseline.png current.png
+
+# Headed mode (visible browser)
+browse --headed goto https://example.com
+
+# State list / show
+browse state list
+browse state show mysite
 ```
 
 ## Command Reference
@@ -297,6 +319,8 @@ browse cookies                 Dump all cookies as JSON
 browse storage [set <k> <v>]   View/set localStorage
 browse perf                    Page load performance timings
 browse devices [filter]        List available device names
+browse clipboard               Read system clipboard text
+browse clipboard write <text>  Write text to system clipboard
 ```
 
 ### Visual
@@ -313,9 +337,19 @@ browse frame <selector>        Target an iframe (subsequent commands run inside
 browse frame main              Return to main page
 ```
 
+### Find (semantic element locators)
+```
+browse find role <query>              Find elements by ARIA role
+browse find text <query>              Find elements by text content
+browse find label <query>             Find elements by label
+browse find placeholder <query>       Find elements by placeholder
+browse find testid <query>            Find elements by test ID
+```
+
 ### Compare
 ```
-browse diff <url1> <url2>      Text diff between two pages
+browse diff <url1> <url2>             Text diff between two pages
+browse screenshot-diff <base> [curr]  Pixel-diff two PNG screenshots
 ```
 
 ### Multi-step (chain)
@@ -342,6 +376,8 @@ browse session-close <id>      Close a session
 ```
 browse state save [name]       Save cookies + localStorage (all origins)
 browse state load [name]       Restore saved state
+browse state list              List saved states
+browse state show [name]       Show contents of saved state
 ```
 
 ### Auth vault
@@ -364,6 +400,7 @@ browse status                  Server health, uptime, session count
 browse instances               List all running browse servers (instance, PID, port, status)
 browse stop                    Shutdown server
 browse restart                 Kill + restart server
+browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 ```
 
 ## CLI Flags
@@ -374,6 +411,7 @@ browse restart                 Kill + restart server
 | `--json` | Wrap output as `{success, data, command}` |
 | `--content-boundaries` | Wrap page content in nonce-delimited markers (prompt injection defense) |
 | `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
+| `--headed` | Run browser in headed (visible) mode |
 
 ## Speed Rules
 
@@ -421,6 +459,11 @@ browse restart                 Kill + restart server
 | Secure browsing | `--allowed-domains example.com goto https://example.com` |
 | Scroll through results | `scroll down` → `text` → `scroll down` → `text` |
 | Drag and drop | `drag @e1 @e2` |
+| Read/write clipboard | `clipboard` / `clipboard write "text"` |
+| Find by accessibility | `find role button` / `find text "Submit"` |
+| Visual regression | `screenshot-diff baseline.png` |
+| Debug with DevTools | `inspect` (set BROWSE_DEBUG_PORT first) |
+| See the browser | `browse --headed goto <url>` |
 
 ## Architecture
 

package/src/browser-manager.ts

@@ -187,6 +187,10 @@ export class BrowserManager {
     return this.buffers;
   }
 
+  getBrowser(): Browser | null {
+    return this.browser;
+  }
+
   getContext(): BrowserContext | null {
     return this.context;
   }
@@ -199,11 +203,9 @@ export class BrowserManager {
     this.browser = await chromium.launch({ headless: true });
     this.ownsBrowser = true;
 
-    // Chromium crash → flush what we can, then exit
+    // Chromium crash → notify caller (server uses this to exit; tests ignore it)
     this.browser.on('disconnected', () => {
-      console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting.');
       if (onCrash) onCrash();
-      process.exit(1);
     });
 
     this.context = await this.browser.newContext({

package/src/cli.ts

@@ -19,6 +19,7 @@ const cliFlags = {
   json: false,
   contentBoundaries: false,
   allowedDomains: '' as string,
+  headed: false,
 };
 
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10);
@@ -251,7 +252,7 @@ async function startServer(): Promise<ServerState> {
       : ['bun', 'run', SERVER_SCRIPT];
     const proc = Bun.spawn(spawnCmd, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, __BROWSE_SERVER_MODE: '1', BROWSE_LOCAL_DIR: LOCAL_DIR, BROWSE_INSTANCE },
+      env: { ...process.env, __BROWSE_SERVER_MODE: '1', BROWSE_LOCAL_DIR: LOCAL_DIR, BROWSE_INSTANCE, ...(cliFlags.headed ? { BROWSE_HEADED: '1' } : {}) },
     });
 
     // Don't hold the CLI open
@@ -559,10 +560,20 @@ export async function main() {
   }
   allowedDomains = allowedDomains || process.env.BROWSE_ALLOWED_DOMAINS || (config.allowedDomains ? config.allowedDomains.join(',') : undefined);
 
+  // Extract --headed flag (only before command)
+  let headed = false;
+  const headedIdx = args.indexOf('--headed');
+  if (headedIdx !== -1 && headedIdx < findCommandIndex(args)) {
+    headed = true;
+    args.splice(headedIdx, 1);
+  }
+  headed = headed || process.env.BROWSE_HEADED === '1';
+
   // Set global flags for sendCommand()
   cliFlags.json = jsonMode;
   cliFlags.contentBoundaries = contentBoundaries;
   cliFlags.allowedDomains = allowedDomains || '';
+  cliFlags.headed = headed;
 
   // ─── Local commands (no server needed) ─────────────────────
   if (args[0] === 'instances') {
@@ -593,7 +604,7 @@ Device:         emulate <device> | emulate reset | devices [filter]
 Inspection:     js <expr> | eval <file> | css <sel> <prop> | attrs <sel>
                 element-state <sel> | console [--clear] | network [--clear]
                 cookies | storage [set <k> <v>] | perf
-                value <sel> | count <sel>
+                value <sel> | count <sel> | clipboard [write <text>]
 Visual:         screenshot [path] | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-c] [-C] [-d N] [-s sel]
 Find:           find role|text|label|placeholder|testid <query> [name]
@@ -607,6 +618,7 @@ 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|load|list|show [name]
+Debug:          inspect (requires BROWSE_DEBUG_PORT)
 Server:         status | instances | cookie <n>=<v> | header <n>:<v>
                 useragent <str> | stop | restart
 Setup:          install-skill [path]
@@ -616,6 +628,7 @@ Options:
   --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
+  --headed                 Run browser in headed (visible) mode
 
 Snapshot flags:
   -i            Interactive elements only (buttons, links, inputs)

package/src/commands/meta.ts

@@ -346,7 +346,7 @@ export async function handleMetaCommand(
       const { PolicyChecker } = await import('../policy');
 
       const WRITE_SET = new Set(['goto','back','forward','reload','click','dblclick','fill','select','hover','focus','check','uncheck','type','press','scroll','wait','viewport','cookie','header','useragent','upload','dialog-accept','dialog-dismiss','emulate','drag','keydown','keyup','highlight','download','route','offline']);
-      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','element-state','dialog','console','network','cookies','storage','perf','devices','value','count']);
+      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','element-state','dialog','console','network','cookies','storage','perf','devices','value','count','clipboard']);
 
       const sessionBuffers = currentSession?.buffers;
       const policy = new PolicyChecker();
@@ -516,10 +516,8 @@ export async function handleMetaCommand(
       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);
+      if (!result.passed && result.diffImage) {
+        fs.writeFileSync(diffPath, result.diffImage);
       }
 
       return [
@@ -528,7 +526,7 @@ export async function handleMetaCommand(
         `Mismatch: ${result.mismatchPct.toFixed(3)}%`,
         `Threshold: ${thresholdPct}%`,
         `Result: ${result.passed ? 'PASS' : 'FAIL'}`,
-        ...(!result.passed ? [`Current saved: ${diffPath}`] : []),
+        ...(!result.passed ? [`Diff saved: ${diffPath}`] : []),
       ].join('\n');
     }
 
@@ -684,6 +682,33 @@ export async function handleMetaCommand(
       return `Switched to frame: ${selector}`;
     }
 
+    // ─── DevTools Inspect ──────────────────────────────
+    case 'inspect': {
+      const debugPort = parseInt(process.env.BROWSE_DEBUG_PORT || '0', 10);
+      if (!debugPort) {
+        throw new Error(
+          'DevTools inspect requires BROWSE_DEBUG_PORT to be set.\n' +
+          'Restart with: BROWSE_DEBUG_PORT=9222 browse restart\n' +
+          'Then run: browse inspect'
+        );
+      }
+      try {
+        const resp = await fetch(`http://127.0.0.1:${debugPort}/json`, { signal: AbortSignal.timeout(2000) });
+        const pages = await resp.json() as any[];
+        const currentUrl = bm.getCurrentUrl();
+        const target = pages.find((p: any) => p.url === currentUrl) || pages[0];
+        if (!target) throw new Error('No debuggable pages found');
+        return [
+          `DevTools URL: ${target.devtoolsFrontendUrl}`,
+          `Page: ${target.title} (${target.url})`,
+          `WebSocket: ${target.webSocketDebuggerUrl}`,
+        ].join('\n');
+      } catch (err: any) {
+        if (err.message.includes('BROWSE_DEBUG_PORT')) throw err;
+        throw new Error(`Cannot reach Chrome debug port at ${debugPort}: ${err.message}`);
+      }
+    }
+
     default:
       throw new Error(`Unknown meta command: ${command}`);
   }

package/src/commands/read.ts

@@ -314,6 +314,23 @@ export async function handleReadCommand(
       return String(count);
     }
 
+    case 'clipboard': {
+      if (args[0] === 'write') {
+        const text = args.slice(1).join(' ');
+        if (!text) throw new Error('Usage: browse clipboard write <text>');
+        await page.context().grantPermissions(['clipboard-read', 'clipboard-write']);
+        await evalCtx.evaluate((t) => navigator.clipboard.writeText(t), text);
+        return `Clipboard set: ${text.slice(0, 50)}${text.length > 50 ? '...' : ''}`;
+      }
+      await page.context().grantPermissions(['clipboard-read', 'clipboard-write']);
+      try {
+        const text = await evalCtx.evaluate(() => navigator.clipboard.readText());
+        return text || '(empty clipboard)';
+      } catch {
+        return '(clipboard not available)';
+      }
+    }
+
     case 'devices': {
       const filter = args.join(' ').toLowerCase();
       const all = listDevices();

package/src/png-compare.ts

@@ -1,10 +1,11 @@
 /**
- * Self-contained PNG decoder + pixel comparator.
- * No external deps — uses only zlib.inflateSync (Node/Bun built-in).
+ * Self-contained PNG decoder, encoder + pixel comparator.
+ * No external deps — uses only zlib (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).
+ * Decoder supports: 8-bit RGB (color type 2) and RGBA (color type 6).
  * Handles all 5 PNG scanline filter types (None/Sub/Up/Average/Paeth).
+ * Encoder outputs: 8-bit RGBA (color type 6), filter None, zlib-compressed.
  */
 
 import * as zlib from 'zlib';
@@ -22,6 +23,7 @@ export interface CompareResult {
   diffPixels: number;
   mismatchPct: number;
   passed: boolean;
+  diffImage?: Buffer;
 }
 
 export function decodePNG(buf: Buffer): DecodedImage {
@@ -96,6 +98,111 @@ export function decodePNG(buf: Buffer): DecodedImage {
   return { width, height, data: pixels };
 }
 
+/**
+ * Encode a DecodedImage (RGBA pixels) into a PNG buffer.
+ * Uses filter type None (0) for simplicity — zlib handles compression.
+ */
+export function encodePNG(img: DecodedImage): Buffer {
+  // Helper: write a PNG chunk (length + type + data + CRC32)
+  function writeChunk(type: string, data: Buffer): Buffer {
+    const chunk = Buffer.alloc(12 + data.length);
+    chunk.writeUInt32BE(data.length, 0);
+    chunk.write(type, 4, 4, 'ascii');
+    data.copy(chunk, 8);
+    // CRC32 covers type + data
+    const crcData = chunk.slice(4, 8 + data.length);
+    chunk.writeUInt32BE(zlib.crc32(crcData) >>> 0, 8 + data.length);
+    return chunk;
+  }
+
+  // PNG signature
+  const signature = Buffer.from(PNG_MAGIC);
+
+  // IHDR: width(4) + height(4) + bitDepth(1) + colorType(1) + compression(1) + filter(1) + interlace(1)
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(img.width, 0);
+  ihdr.writeUInt32BE(img.height, 4);
+  ihdr[8] = 8;   // bit depth
+  ihdr[9] = 6;   // color type: RGBA
+  ihdr[10] = 0;  // compression method
+  ihdr[11] = 0;  // filter method
+  ihdr[12] = 0;  // no interlace
+
+  // IDAT: for each scanline, prepend filter byte 0 (None), then raw RGBA pixels
+  const rawStride = img.width * 4;
+  const rawData = Buffer.alloc(img.height * (1 + rawStride));
+  for (let y = 0; y < img.height; y++) {
+    const outOff = y * (1 + rawStride);
+    rawData[outOff] = 0; // filter type: None
+    img.data.copy(rawData, outOff + 1, y * rawStride, (y + 1) * rawStride);
+  }
+  const compressed = zlib.deflateSync(rawData);
+
+  // IEND: empty chunk
+  const iend = Buffer.alloc(0);
+
+  return Buffer.concat([
+    signature,
+    writeChunk('IHDR', ihdr),
+    writeChunk('IDAT', compressed),
+    writeChunk('IEND', iend),
+  ]);
+}
+
+/**
+ * Generate a visual diff image highlighting pixel differences.
+ * - Pixels only in one image (size mismatch): bright red (255,0,0,255)
+ * - Pixels differing beyond threshold: red-tinted (255, g/3, b/3, 255)
+ * - Pixels matching: dimmed (r/3, g/3, b/3, 128)
+ */
+export function generateDiffImage(base: DecodedImage, curr: DecodedImage, colorThreshold: number): Buffer {
+  const w = Math.max(base.width, curr.width);
+  const h = Math.max(base.height, curr.height);
+  const diffData = Buffer.alloc(w * h * 4);
+  const colorThreshSq = colorThreshold * colorThreshold * 3;
+
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const di = (y * w + x) * 4;
+      const inBase = x < base.width && y < base.height;
+      const inCurr = x < curr.width && y < curr.height;
+
+      if (!inBase || !inCurr) {
+        // Size mismatch — bright red
+        diffData[di] = 255;
+        diffData[di + 1] = 0;
+        diffData[di + 2] = 0;
+        diffData[di + 3] = 255;
+        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;
+      const isDiff = colorThreshold === 0 ? distSq > 0 : distSq > colorThreshSq;
+
+      if (isDiff) {
+        // Different — red-tinted using current image colors
+        diffData[di] = 255;
+        diffData[di + 1] = (curr.data[ci + 1] / 3) | 0;
+        diffData[di + 2] = (curr.data[ci + 2] / 3) | 0;
+        diffData[di + 3] = 255;
+      } else {
+        // Matching — dimmed
+        diffData[di] = (curr.data[ci] / 3) | 0;
+        diffData[di + 1] = (curr.data[ci + 1] / 3) | 0;
+        diffData[di + 2] = (curr.data[ci + 2] / 3) | 0;
+        diffData[di + 3] = 128;
+      }
+    }
+  }
+
+  return encodePNG({ width: w, height: h, data: diffData });
+}
+
 export function compareScreenshots(
   baselineBuf: Buffer,
   currentBuf: Buffer,
@@ -129,10 +236,12 @@ export function compareScreenshots(
   }
 
   const mismatchPct = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;
-  return {
-    totalPixels,
-    diffPixels,
-    mismatchPct,
-    passed: mismatchPct <= thresholdPct,
-  };
+  const passed = mismatchPct <= thresholdPct;
+  const result: CompareResult = { totalPixels, diffPixels, mismatchPct, passed };
+
+  if (!passed) {
+    result.diffImage = generateDiffImage(base, curr, colorThreshold);
+  }
+
+  return result;
 }

package/src/server.ts

@@ -26,6 +26,7 @@ export { type LogEntry, type NetworkEntry };
 
 // ─── Auth (inline) ─────────────────────────────────────────────
 const AUTH_TOKEN = crypto.randomUUID();
+const DEBUG_PORT = parseInt(process.env.BROWSE_DEBUG_PORT || '0', 10);
 const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10); // 0 = auto-scan
 const BROWSE_INSTANCE = process.env.BROWSE_INSTANCE || '';
 const INSTANCE_SUFFIX = BROWSE_PORT ? `-${BROWSE_PORT}` : (BROWSE_INSTANCE ? `-${BROWSE_INSTANCE}` : '');
@@ -107,7 +108,7 @@ const READ_COMMANDS = new Set([
   'text', 'html', 'links', 'forms', 'accessibility',
   'js', 'eval', 'css', 'attrs', 'element-state', 'dialog',
   'console', 'network', 'cookies', 'storage', 'perf', 'devices',
-  'value', 'count',
+  'value', 'count', 'clipboard',
 ]);
 
 const WRITE_COMMANDS = new Set([
@@ -128,7 +129,7 @@ const META_COMMANDS = new Set([
   'url', 'snapshot', 'snapshot-diff', 'screenshot-diff',
   'sessions', 'session-close',
   'frame', 'state', 'find',
-  'auth', 'har',
+  'auth', 'har', 'inspect',
 ]);
 
 // Probe if a port is free using net.createServer (not Bun.serve which fatally crashes on EADDRINUSE)
@@ -373,7 +374,10 @@ async function start() {
     console.log(`[browse] Connected to remote Chrome via CDP: ${cdpUrl}`);
   } else {
     // Launch local Chromium
-    const launchOptions: Record<string, any> = { headless: true };
+    const launchOptions: Record<string, any> = { headless: process.env.BROWSE_HEADED !== '1' };
+    if (DEBUG_PORT > 0) {
+      launchOptions.args = [`--remote-debugging-port=${DEBUG_PORT}`];
+    }
     const proxyServer = process.env.BROWSE_PROXY;
     if (proxyServer) {
       launchOptions.proxy = { server: proxyServer };
@@ -383,17 +387,11 @@ async function start() {
     }
     browser = await chromium.launch(launchOptions);
 
-    // Chromium crash → flush, cleanup, exit (only for owned browser)
+    // Chromium crash → clean shutdown (only for owned browser)
     browser.on('disconnected', () => {
-      console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting.');
-      if (sessionManager) flushAllBuffers(sessionManager, true);
-      try {
-        const currentState = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
-        if (currentState.pid === process.pid || currentState.token === AUTH_TOKEN) {
-          fs.unlinkSync(STATE_FILE);
-        }
-      } catch {}
-      process.exit(1);
+      if (isShuttingDown) return;
+      console.error('[browse] Chromium disconnected. Shutting down.');
+      shutdown();
     });
   }
 
@@ -445,13 +443,16 @@ async function start() {
   });
 
   // Write state file
-  const state = {
+  const state: Record<string, any> = {
     pid: process.pid,
     port,
     token: AUTH_TOKEN,
     startedAt: new Date().toISOString(),
     serverPath: path.resolve(import.meta.dir, 'server.ts'),
   };
+  if (DEBUG_PORT > 0) {
+    state.debugPort = DEBUG_PORT;
+  }
   fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), { mode: 0o600 });
 
   console.log(`[browse] Server running on http://127.0.0.1:${port} (PID: ${process.pid})`);