@ulpi/browse 0.3.0 → 0.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ciprian Hacman
+Copyright (c) 2026 Open Growth Group INC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -116,6 +116,7 @@ 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` |
+| Video recording | Not available | `video start [dir]\|stop\|status` |
 | Clipboard access | Not available | `clipboard [write <text>]` |
 | Element finding | Not available | `find role\|text\|label\|placeholder\|testid` |
 | DevTools inspect | Not available | `inspect` |
@@ -291,7 +292,7 @@ echo '[["goto","https://example.com"],["text"]]' | browse chain
 `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]`
+`har start` | `har stop [path]` | `video start [dir]` | `video stop` | `video status`
 
 ### Debug
 `inspect` — open DevTools debugger (requires `BROWSE_DEBUG_PORT`).
@@ -384,6 +385,7 @@ Inspired by and originally derived from the `/browse` skill in [gstack](https://
 - `offline on/off` — offline mode toggle
 - `state save/load` — persist and restore cookies + localStorage (all origins)
 - `har start/stop` — HAR recording and export
+- `video start/stop/status` — video recording (WebM, compositor-level, works with remote CDP)
 - `screenshot-diff` — pixel-level visual regression testing
 - `find role/text/label/placeholder/testid` — semantic element locators
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"
   },
   "dependencies": {
+    "@ulpi/browse": "^0.3.0",
     "diff": "^7.0.0",
     "playwright": "^1.58.2"
   },
@@ -38,7 +39,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build --compile --external electron --external chromium-bidi src/cli.ts --outfile dist/browse",
+    "build": "bun build --compile --external electron --external chromium-bidi src/cli.ts --outfile dist/browse && rm -f .*.bun-build",
     "build:all": "bash scripts/build-all.sh",
     "dev": "bun run src/cli.ts",
     "server": "bun run src/server.ts",

package/skill/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: browse
-version: 2.0.0
+version: 2.3.0
 description: |
-  Fast web browsing for Claude Code via persistent headless Chromium daemon. Navigate to any URL,
+  Fast web browsing for AI coding agents via persistent headless Chromium daemon. Navigate to any URL,
   read page content, click elements, fill forms, run JavaScript, take screenshots,
   inspect CSS/DOM, capture console/network logs, and more. ~100ms per command after
-  first call. Use when you need to check a website, verify a deployment, read docs,
-  or interact with any web page. No MCP, no Chrome extension — just fast CLI.
+  first call. Works with Claude Code, Cursor, Cline, Windsurf, and any agent that can run Bash.
+  No MCP, no Chrome extension — just fast CLI.
 allowed-tools:
   - Bash
   - Read
 
 ---
 
-# browse: Persistent Browser for Claude Code
+# browse: Persistent Browser for AI Coding Agents
 
 Persistent headless Chromium daemon. First call auto-starts the server (~3s).
 Every subsequent call: ~100-200ms. Auto-shuts down after 30 min idle.
@@ -74,7 +74,7 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse newtab:*)", "Bash(browse closetab:*)",
 "Bash(browse frame:*)",
 "Bash(browse sessions:*)", "Bash(browse session-close:*)",
-"Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)",
+"Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)", "Bash(browse video:*)",
 "Bash(browse route:*)", "Bash(browse offline:*)",
 "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
 "Bash(browse cookie:*)", "Bash(browse header:*)",
@@ -197,6 +197,12 @@ browse har start
 browse goto https://example.com
 browse har stop ./recording.har
 
+# Video recording
+browse video start ./videos
+browse goto https://example.com
+browse click @e3
+browse video stop
+
 # Device emulation
 browse emulate iphone
 browse emulate reset
@@ -325,7 +331,8 @@ browse clipboard write <text>  Write text to system clipboard
 
 ### Visual
 ```
-browse screenshot [path]              Screenshot (default: .browse/sessions/{id}/screenshot.png)
+browse screenshot [path]              Viewport screenshot (default: .browse/sessions/{id}/screenshot.png)
+browse screenshot --full [path]       Full-page screenshot (entire scrollable page)
 browse screenshot --annotate [path]   Screenshot with numbered badges + legend
 browse pdf [path]                     Save as PDF
 browse responsive [prefix]            Screenshots at mobile/tablet/desktop
@@ -394,6 +401,13 @@ browse har start               Start recording network traffic
 browse har stop [path]         Stop and save HAR file
 ```
 
+### Video recording
+```
+browse video start [dir]       Start recording video (WebM, compositor-level)
+browse video stop              Stop recording and save video files
+browse video status            Check if recording is active
+```
+
 ### Server management
 ```
 browse status                  Server health, uptime, session count
@@ -454,6 +468,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Save/restore session | `state save mysite` / `state load mysite` |
 | Auto-login | `auth save gh https://github.com/login user pass` → `auth login gh` |
 | Record network | `har start` → browse around → `har stop ./out.har` |
+| Record video | `video start ./vids` → browse around → `video stop` |
 | Parallel agents | `--session agent-a <cmd>` / `--session agent-b <cmd>` |
 | Multi-step flow | `echo '[...]' \| browse chain` |
 | Secure browsing | `--allowed-domains example.com goto https://example.com` |

package/src/browser-manager.ts

@@ -167,6 +167,9 @@ export class BrowserManager {
   // ─── HAR Recording ────────────────────────────────────────
   private harRecording: HarRecording | null = null;
 
+  // ─── Video Recording ────────────────────────────────────────
+  private videoRecording: { dir: string; startedAt: number } | null = null;
+
   // ─── Init Script (domain filter JS injection) ─────────────
   private initScript: string | null = null;
 
@@ -553,6 +556,17 @@ export class BrowserManager {
   private async recreateContext(contextOptions: Record<string, any>): Promise<void> {
     if (!this.browser) return;
 
+    // Auto-inject recordVideo when video recording is active (so emulateDevice/applyUserAgent pass it through)
+    if (this.videoRecording && !contextOptions.recordVideo) {
+      contextOptions = {
+        ...contextOptions,
+        recordVideo: {
+          dir: this.videoRecording.dir,
+          size: contextOptions.viewport || this.currentDevice?.viewport || { width: 1920, height: 1080 },
+        },
+      };
+    }
+
     // Save all tab URLs and which tab was active
     const tabUrls: Array<{ id: number; url: string; active: boolean }> = [];
     for (const [id, page] of this.pages) {
@@ -766,6 +780,67 @@ export class BrowserManager {
     return this.harRecording;
   }
 
+  // ─── Video Recording ──────────────────────────────────────
+
+  async startVideoRecording(dir: string): Promise<void> {
+    if (this.videoRecording) throw new Error('Video recording already active');
+    const fs = await import('fs');
+    fs.mkdirSync(dir, { recursive: true });
+
+    this.videoRecording = { dir, startedAt: Date.now() };
+    const viewport = this.currentDevice?.viewport || { width: 1920, height: 1080 };
+    await this.recreateContext({
+      viewport,
+      ...(this.customUserAgent ? { userAgent: this.customUserAgent } : {}),
+      ...(this.currentDevice ? {
+        deviceScaleFactor: this.currentDevice.deviceScaleFactor,
+        isMobile: this.currentDevice.isMobile,
+        hasTouch: this.currentDevice.hasTouch,
+      } : {}),
+      recordVideo: { dir, size: viewport },
+    });
+  }
+
+  async stopVideoRecording(): Promise<{ dir: string; startedAt: number; paths: string[] } | null> {
+    if (!this.videoRecording) return null;
+
+    const recording = this.videoRecording;
+    // Collect video objects before pages are closed by recreateContext
+    const videos: Array<{ video: any; tabId: number }> = [];
+    for (const [id, page] of this.pages) {
+      const video = page.video();
+      if (video) videos.push({ video, tabId: id });
+    }
+
+    // Clear state BEFORE recreateContext so auto-injection doesn't add recordVideo
+    this.videoRecording = null;
+
+    const viewport = this.currentDevice?.viewport || { width: 1920, height: 1080 };
+    await this.recreateContext({
+      viewport,
+      ...(this.customUserAgent ? { userAgent: this.customUserAgent } : {}),
+      ...(this.currentDevice ? {
+        deviceScaleFactor: this.currentDevice.deviceScaleFactor,
+        isMobile: this.currentDevice.isMobile,
+        hasTouch: this.currentDevice.hasTouch,
+      } : {}),
+    });
+
+    // Save videos with predictable names (saveAs works for both local and remote CDP)
+    const paths: string[] = [];
+    for (const { video, tabId } of videos) {
+      const target = `${recording.dir}/tab-${tabId}.webm`;
+      await video.saveAs(target);
+      paths.push(target);
+    }
+
+    return { dir: recording.dir, startedAt: recording.startedAt, paths };
+  }
+
+  getVideoRecording(): { dir: string; startedAt: number } | null {
+    return this.videoRecording;
+  }
+
   // ─── Init Script ───────────────────────────────────────────
   setInitScript(script: string): void {
     this.initScript = script;

package/src/cli.ts

@@ -605,13 +605,14 @@ 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> | clipboard [write <text>]
-Visual:         screenshot [path] | pdf [path] | responsive [prefix]
+Visual:         screenshot [path] [--full] [--annotate] | pdf [path] | responsive [prefix]
 Snapshot:       snapshot [-i] [-c] [-C] [-d N] [-s sel]
 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]
+                video start [dir] | video stop | video status
 Tabs:           tabs | tab <id> | newtab [url] | closetab [id]
 Frames:         frame <sel> | frame main
 Sessions:       sessions | session-close <id>

package/src/commands/meta.ts

@@ -218,7 +218,8 @@ export async function handleMetaCommand(
     case 'screenshot': {
       const page = bm.getPage();
       const annotate = args.includes('--annotate');
-      const filteredArgs = args.filter(a => a !== '--annotate');
+      const isFullPage = args.includes('--full');
+      const filteredArgs = args.filter(a => a !== '--annotate' && a !== '--full');
       const screenshotPath = filteredArgs[0] || (currentSession ? `${currentSession.outputDir}/screenshot.png` : `${LOCAL_DIR}/browse-screenshot.png`);
 
       if (annotate) {
@@ -278,7 +279,7 @@ export async function handleMetaCommand(
             document.body.appendChild(container);
           }, badges);
 
-          await page.screenshot({ path: screenshotPath, fullPage: true });
+          await page.screenshot({ path: screenshotPath, fullPage: isFullPage });
         } finally {
           await page.evaluate(() => {
             document.getElementById('__browse_annotate__')?.remove();
@@ -288,7 +289,7 @@ export async function handleMetaCommand(
         return `Screenshot saved: ${screenshotPath}\n\nLegend:\n${legend.join('\n')}`;
       }
 
-      await page.screenshot({ path: screenshotPath, fullPage: true });
+      await page.screenshot({ path: screenshotPath, fullPage: isFullPage });
       return `Screenshot saved: ${screenshotPath}`;
     }
 
@@ -481,14 +482,16 @@ export async function handleMetaCommand(
 
     // ─── Screenshot Diff ──────────────────────────────
     case 'screenshot-diff': {
-      const baseline = args[0];
-      if (!baseline) throw new Error('Usage: browse screenshot-diff <baseline> [current] [--threshold 0.1]');
+      const isFullPageDiff = args.includes('--full');
+      const diffArgs = args.filter(a => a !== '--full');
+      const baseline = diffArgs[0];
+      if (!baseline) throw new Error('Usage: browse screenshot-diff <baseline> [current] [--threshold 0.1] [--full]');
       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 threshIdx = diffArgs.indexOf('--threshold');
+      if (threshIdx !== -1 && diffArgs[threshIdx + 1]) {
+        thresholdPct = parseFloat(diffArgs[threshIdx + 1]);
       }
 
       const baselineBuffer = fs.readFileSync(baseline);
@@ -496,16 +499,16 @@ export async function handleMetaCommand(
       // 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; }
+      for (let i = 1; i < diffArgs.length; i++) {
+        if (diffArgs[i] === '--threshold') { i++; continue; }
+        if (!diffArgs[i].startsWith('--')) { currentPath = diffArgs[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;
+        currentBuffer = await page.screenshot({ fullPage: isFullPageDiff }) as Buffer;
       }
 
       const { compareScreenshots } = await import('../png-compare');
@@ -619,6 +622,36 @@ export async function handleMetaCommand(
       throw new Error('Usage: browse har start | browse har stop [path]');
     }
 
+    // ─── Video Recording ─────────────────────────────────
+    case 'video': {
+      const subcommand = args[0];
+      if (!subcommand) throw new Error('Usage: browse video start [dir] | browse video stop | browse video status');
+
+      if (subcommand === 'start') {
+        const dir = args[1] || (currentSession
+          ? `${currentSession.outputDir}`
+          : `${LOCAL_DIR}`);
+        await bm.startVideoRecording(dir);
+        return `Video recording started — output dir: ${dir}`;
+      }
+
+      if (subcommand === 'stop') {
+        const result = await bm.stopVideoRecording();
+        if (!result) throw new Error('No active video recording. Run "browse video start" first.');
+        const duration = ((Date.now() - result.startedAt) / 1000).toFixed(1);
+        return `Video saved: ${result.paths.join(', ')} (${duration}s)`;
+      }
+
+      if (subcommand === 'status') {
+        const recording = bm.getVideoRecording();
+        if (!recording) return 'No active video recording';
+        const duration = ((Date.now() - recording.startedAt) / 1000).toFixed(1);
+        return `Video recording active — dir: ${recording.dir}, duration: ${duration}s`;
+      }
+
+      throw new Error('Usage: browse video start [dir] | browse video stop | browse video status');
+    }
+
     // ─── Semantic Locator ──────────────────────────────
     case 'find': {
       const root = bm.getLocatorRoot();

package/src/server.ts

@@ -129,7 +129,7 @@ const META_COMMANDS = new Set([
   'url', 'snapshot', 'snapshot-diff', 'screenshot-diff',
   'sessions', 'session-close',
   'frame', 'state', 'find',
-  'auth', 'har', 'inspect',
+  'auth', 'har', 'video', 'inspect',
 ]);
 
 // Probe if a port is free using net.createServer (not Bun.serve which fatally crashes on EADDRINUSE)