@ulpi/browse 0.7.5 → 0.10.0

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse
-version: 2.5.1
+version: 2.7.0
 description: |
   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,
@@ -75,13 +75,21 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse frame:*)",
 "Bash(browse sessions:*)", "Bash(browse session-close:*)",
 "Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)", "Bash(browse video:*)",
+"Bash(browse record:*)",
 "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 clipboard:*)", "Bash(browse screenshot-diff:*)",
 "Bash(browse find:*)", "Bash(browse inspect:*)",
-"Bash(browse instances:*)", "Bash(browse --headed:*)"
+"Bash(browse instances:*)", "Bash(browse --headed:*)",
+"Bash(browse rightclick:*)", "Bash(browse tap:*)",
+"Bash(browse swipe:*)", "Bash(browse mouse:*)",
+"Bash(browse keyboard:*)", "Bash(browse scrollinto:*)",
+"Bash(browse scrollintoview:*)", "Bash(browse set:*)",
+"Bash(browse box:*)", "Bash(browse errors:*)",
+"Bash(browse doctor:*)", "Bash(browse upgrade:*)",
+"Bash(browse --max-output:*)"
 ```
 
 ## IMPORTANT
@@ -189,6 +197,28 @@ browse --allowed-domains example.com,*.cdn.example.com goto https://example.com
 # State persistence
 browse state save mysite
 browse state load mysite
+browse state clean                    # delete states older than 7 days
+browse state clean --older-than 30    # custom threshold
+
+# Cookie management
+browse cookie clear                                      # clear all cookies
+browse cookie set auth token --domain .example.com       # set with options
+browse cookie export ./cookies.json                      # export to file
+browse cookie import ./cookies.json                      # import from file
+
+# Cookie import from real browsers (macOS — Chrome, Arc, Brave, Edge)
+browse cookie-import --list                              # show installed browsers
+browse cookie-import chrome --domain .example.com        # import cookies for a domain
+browse cookie-import arc --domain .github.com            # import from Arc
+browse cookie-import chrome --profile "Profile 1" --domain .site.com  # specific Chrome profile
+
+# Session auto-persistence (named sessions survive restarts)
+browse --session myapp goto https://app.com/login        # login...
+browse session-close myapp                               # state auto-saved (encrypted if BROWSE_ENCRYPTION_KEY set)
+browse --session myapp goto https://app.com/dashboard    # cookies auto-restored
+
+# Load state at launch
+browse --state auth.json goto https://app.com            # load cookies before first command
 
 # Auth vault (credentials never visible to LLM)
 browse auth save github https://github.com/login user pass123
@@ -199,11 +229,31 @@ browse har start
 browse goto https://example.com
 browse har stop ./recording.har
 
-# Video recording
+# Video recording (watch a .webm of the session)
+browse video start ./videos
+browse goto https://example.com
+browse click @e3
+browse video stop
+
+# Command recording (export replayable scripts)
+browse record start
+browse goto https://example.com
+browse click "a"
+browse fill "[id=search]" "test query"
+browse record stop
+browse record export replay ./recording.json    # replay with: npx @puppeteer/replay ./recording.json
+browse record export browse ./steps.json        # replay with: cat steps.json | browse chain
+
+# Both together (video + replayable script)
 browse video start ./videos
+browse record start
 browse goto https://example.com
+browse snapshot -i
 browse click @e3
+browse fill "[id=email]" "user@test.com"
+browse record stop
 browse video stop
+browse record export replay ./recording.json
 
 # Device emulation
 browse emulate iphone
@@ -286,11 +336,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ```
 browse click <selector>        Click element (CSS selector or @ref)
 browse click <x>,<y>           Click at page coordinates (e.g. 590,461)
+browse rightclick <selector>   Right-click element (context menu)
 browse dblclick <selector>     Double-click element
 browse fill <selector> <value> Fill input field
 browse select <selector> <val> Select dropdown value
 browse hover <selector>        Hover over element
 browse focus <selector>        Focus element
+browse tap <selector>          Tap element (requires touch context via emulate)
 browse check <selector>        Check checkbox
 browse uncheck <selector>      Uncheck checkbox
 browse drag <src> <tgt>        Drag source to target
@@ -298,8 +350,24 @@ browse type <text>             Type into focused element
 browse press <key>             Press key (Enter, Tab, Escape, etc.)
 browse keydown <key>           Hold key down
 browse keyup <key>             Release key
+browse keyboard inserttext <t> Insert text without key events
 browse scroll [sel|up|down]    Scroll element/viewport/bottom
-browse wait <sel|--url|--network-idle>  Wait for element, URL, or network
+browse scrollinto <sel>        Scroll element into view (explicit)
+browse swipe <dir> [px]        Swipe up/down/left/right (touch events)
+browse mouse move <x> <y>     Move mouse to coordinates
+browse mouse down [button]     Press mouse button (left/right/middle)
+browse mouse up [button]       Release mouse button
+browse mouse wheel <dy> [dx]   Scroll wheel
+browse wait <sel>              Wait for element to appear
+browse wait <sel> --state hidden  Wait for element to disappear
+browse wait <ms>               Wait for milliseconds
+browse wait --text "..."       Wait for text to appear in page
+browse wait --fn "expr"        Wait for JavaScript condition
+browse wait --load <state>     Wait for load state
+browse wait --url <pattern>    Wait for URL match
+browse wait --network-idle     Wait for network idle
+browse set geo <lat> <lng>     Set geolocation
+browse set media <scheme>      Set color scheme (dark/light/no-preference)
 browse viewport <WxH>          Set viewport size (e.g. 375x812)
 browse upload <sel> <files>    Upload file(s) to a file input
 browse highlight <selector>    Highlight element (visual debugging)
@@ -327,8 +395,10 @@ browse attrs <selector>        Get element attributes as JSON
 browse element-state <selector> Element state (visible/enabled/checked/focused)
 browse value <selector>        Get input field value
 browse count <selector>        Count matching elements
+browse box <selector>          Get bounding box as JSON {x, y, width, height}
 browse dialog                  Last dialog info or "(no dialog detected)"
 browse console [--clear]       View/clear console messages
+browse errors [--clear]        View/clear page errors (filtered from console)
 browse network [--clear]       View/clear network requests
 browse cookies                 Dump all cookies as JSON
 browse storage [set <k> <v>]   View/set localStorage
@@ -342,6 +412,8 @@ browse clipboard write <text>  Write text to system clipboard
 ```
 browse screenshot [path]              Viewport screenshot (default: .browse/sessions/{id}/screenshot.png)
 browse screenshot --full [path]       Full-page screenshot (entire scrollable page)
+browse screenshot <sel|@ref> [path]   Screenshot specific element
+browse screenshot --clip x,y,w,h [path]  Screenshot clipped region
 browse screenshot --annotate [path]   Screenshot with numbered badges + legend
 browse pdf [path]                     Save as PDF
 browse responsive [prefix]            Screenshots at mobile/tablet/desktop
@@ -360,6 +432,11 @@ 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
+browse find alt <query>               Find elements by alt text
+browse find title <query>             Find elements by title attribute
+browse find first <sel>               First matching element
+browse find last <sel>                Last matching element
+browse find nth <n> <sel>             Nth matching element (0-indexed)
 ```
 
 ### Compare
@@ -394,6 +471,15 @@ 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
+browse state clean             Delete states older than 7 days
+browse state clean --older-than N   Custom age threshold (days)
+```
+
+### Cookie import (macOS — borrow auth from real browsers)
+```
+browse cookie-import --list                         List installed browsers
+browse cookie-import <browser> --domain <d>         Import cookies for a domain
+browse cookie-import <browser> --profile <p> --domain <d>   Specific Chrome profile
 ```
 
 ### Auth vault
@@ -417,11 +503,22 @@ browse video stop              Stop recording and save video files
 browse video status            Check if recording is active
 ```
 
+### Command recording & export
+```
+browse record start                    Start recording commands
+browse record stop                     Stop recording, keep steps for export
+browse record status                   Recording state and step count
+browse record export browse [path]     Export as chain-compatible JSON (replay with browse chain)
+browse record export replay [path]    Export as Chrome DevTools Recorder (Playwright/Puppeteer)
+```
+
 ### Server management
 ```
 browse status                  Server health, uptime, session count
 browse instances               List all running browse servers (instance, PID, port, status)
 browse version                 Print CLI version
+browse doctor                  System check (Bun, Playwright, Chromium)
+browse upgrade                 Self-update via npm
 browse stop                    Shutdown server
 browse restart                 Kill + restart server
 browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
@@ -431,10 +528,12 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 
 | Flag | Description |
 |------|-------------|
-| `--session <id>` | Named session (isolates tabs, refs, cookies) |
+| `--session <id>` | Named session (isolates tabs, refs, cookies — auto-persists on close) |
+| `--state <path>` | Load state file (cookies/storage) before first command |
 | `--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 |
+| `--max-output <n>` | Truncate output to N characters |
 | `--headed` | Run browser in headed (visible) mode |
 | `--runtime <name>` | Browser engine: playwright (default), rebrowser (stealth) |
 
@@ -480,6 +579,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | 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` |
+| Export automation script | `record start` → browse around → `record export replay ./recording.json` |
 | 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` |
@@ -489,6 +589,14 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Find by accessibility | `find role button` / `find text "Submit"` |
 | Visual regression | `screenshot-diff baseline.png` |
 | Debug with DevTools | `inspect` (set BROWSE_DEBUG_PORT first) |
+| Get element position | `box @e3` |
+| Check page errors | `errors` |
+| Right-click context menu | `rightclick @e3` |
+| Test mobile gestures | `emulate iphone` → `tap @e1` / `swipe down` |
+| Set dark mode | `set media dark` |
+| Test geolocation | `set geo 37.7 -122.4` → verify in page |
+| Export/import cookies | `cookie export ./cookies.json` / `cookie import ./cookies.json` |
+| Limit output size | `--max-output 5000 text` |
 | See the browser | `browse --headed goto <url>` |
 | Bypass bot detection | `--runtime rebrowser goto <url>` |
 

package/src/auth-vault.ts

@@ -8,11 +8,11 @@
  * Password never returned in list/get — only hasPassword: true
  */
 
-import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import type { BrowserManager } from './browser-manager';
 import { DEFAULTS } from './constants';
+import { resolveEncryptionKey, encrypt, decrypt } from './encryption';
 import { sanitizeName } from './sanitize';
 
 interface StoredCredential {
@@ -44,55 +44,7 @@ export class AuthVault {
 
   constructor(localDir: string) {
     this.authDir = path.join(localDir, 'auth');
-    this.encryptionKey = this.resolveKey(localDir);
-  }
-
-  private resolveKey(localDir: string): Buffer {
-    // 1. Env var (64-char hex = 32 bytes)
-    const envKey = process.env.BROWSE_ENCRYPTION_KEY;
-    if (envKey) {
-      if (envKey.length !== 64) {
-        throw new Error('BROWSE_ENCRYPTION_KEY must be 64 hex characters (32 bytes)');
-      }
-      return Buffer.from(envKey, 'hex');
-    }
-
-    // 2. Key file
-    const keyPath = path.join(localDir, '.encryption-key');
-    if (fs.existsSync(keyPath)) {
-      const hex = fs.readFileSync(keyPath, 'utf-8').trim();
-      return Buffer.from(hex, 'hex');
-    }
-
-    // 3. Auto-generate
-    const key = crypto.randomBytes(32);
-    fs.writeFileSync(keyPath, key.toString('hex') + '\n', { mode: 0o600 });
-    return key;
-  }
-
-  private encrypt(plaintext: string): { ciphertext: string; iv: string; authTag: string } {
-    const iv = crypto.randomBytes(12);
-    const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
-    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
-    return {
-      ciphertext: encrypted.toString('base64'),
-      iv: iv.toString('base64'),
-      authTag: cipher.getAuthTag().toString('base64'),
-    };
-  }
-
-  private decrypt(ciphertext: string, iv: string, authTag: string): string {
-    const decipher = crypto.createDecipheriv(
-      'aes-256-gcm',
-      this.encryptionKey,
-      Buffer.from(iv, 'base64'),
-    );
-    decipher.setAuthTag(Buffer.from(authTag, 'base64'));
-    const decrypted = Buffer.concat([
-      decipher.update(Buffer.from(ciphertext, 'base64')),
-      decipher.final(),
-    ]);
-    return decrypted.toString('utf-8');
+    this.encryptionKey = resolveEncryptionKey(localDir);
   }
 
   save(
@@ -104,7 +56,7 @@ export class AuthVault {
   ): void {
     fs.mkdirSync(this.authDir, { recursive: true });
 
-    const { ciphertext, iv, authTag } = this.encrypt(password);
+    const { ciphertext, iv, authTag } = encrypt(password, this.encryptionKey);
     const now = new Date().toISOString();
 
     const credential: StoredCredential = {
@@ -136,7 +88,7 @@ export class AuthVault {
 
   async login(name: string, bm: BrowserManager): Promise<string> {
     const cred = this.load(name);
-    const password = this.decrypt(cred.data, cred.iv, cred.authTag);
+    const password = decrypt(cred.data, cred.iv, cred.authTag, this.encryptionKey);
     const page = bm.getPage();
 
     // Navigate to login URL

package/src/browser-manager.ts

@@ -7,8 +7,7 @@
  *   We do NOT try to self-heal — don't hide failure.
  */
 
-import { devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Frame, type FrameLocator, type Request as PlaywrightRequest } from 'playwright';
-import { getRuntime } from './runtime';
+import { chromium, devices as playwrightDevices, type Browser, type BrowserContext, type Page, type Locator, type Frame, type FrameLocator, type Request as PlaywrightRequest } from 'playwright';
 import { SessionBuffers, type LogEntry, type NetworkEntry } from './buffers';
 import type { HarRecording } from './har';
 import type { DomainFilter } from './domain-filter';
@@ -203,9 +202,8 @@ export class BrowserManager {
    * Launch a new Chromium browser (single-session / multi-process mode).
    * This instance owns the browser and will close it on close().
    */
-  async launch(onCrash?: () => void, runtimeName?: string) {
-    const runtime = await getRuntime(runtimeName);
-    this.browser = await runtime.chromium.launch({ headless: true });
+  async launch(onCrash?: () => void) {
+    this.browser = await chromium.launch({ headless: true });
     this.ownsBrowser = true;
 
     // Chromium crash → notify caller (server uses this to exit; tests ignore it)
@@ -485,6 +483,23 @@ export class BrowserManager {
     return { selector };
   }
 
+  /**
+   * Resolve a ref with staleness detection. Throws immediately if the ref's
+   * element no longer exists in the DOM, instead of waiting for action timeout.
+   */
+  async resolveRefChecked(selector: string): Promise<{ locator: Locator } | { selector: string }> {
+    const resolved = this.resolveRef(selector);
+    if ('locator' in resolved) {
+      const count = await resolved.locator.count();
+      if (count === 0) {
+        throw new Error(
+          `Ref ${selector} is stale (element no longer exists). Re-run 'snapshot' to get fresh refs.`
+        );
+      }
+    }
+    return resolved;
+  }
+
   getRefCount(): number {
     return this.refMap.size;
   }

package/src/bun.d.ts

@@ -16,21 +16,9 @@ declare module 'bun' {
     stdio?: Array<'ignore' | 'pipe' | 'inherit'>;
     stdout?: 'pipe' | 'ignore' | 'inherit';
     stderr?: 'pipe' | 'ignore' | 'inherit';
-    stdin?: 'pipe' | 'ignore' | 'inherit';
     env?: Record<string, string | undefined>;
   }): BunSubprocess;
 
-  export function listen(options: {
-    hostname: string;
-    port: number;
-    socket: {
-      data: (...args: any[]) => void;
-      open?: (...args: any[]) => void;
-      close?: (...args: any[]) => void;
-      error?: (...args: any[]) => void;
-    };
-  }): BunTCPServer;
-
   export function sleep(ms: number): Promise<void>;
 
   export const stdin: { text(): Promise<string> };
@@ -40,26 +28,33 @@ declare module 'bun' {
     stop(): void;
   }
 
-  interface BunTCPServer {
-    port: number;
-    stop(): void;
-  }
-
   interface BunSubprocess {
     pid: number;
-    exitCode: number | null;
     stderr: ReadableStream<Uint8Array> | null;
     stdout: ReadableStream<Uint8Array> | null;
     exited: Promise<number>;
-    kill(signal?: number): void;
     unref(): void;
+    kill(signal?: number): void;
+  }
+}
+
+declare module 'bun:sqlite' {
+  export class Database {
+    constructor(filename: string, options?: { readonly?: boolean; create?: boolean });
+    query(sql: string): Statement;
+    close(): void;
+  }
+
+  interface Statement {
+    all(...params: any[]): any[];
+    get(...params: any[]): any;
+    run(...params: any[]): void;
   }
 }
 
 declare var Bun: {
   serve: typeof import('bun').serve;
   spawn: typeof import('bun').spawn;
-  listen: typeof import('bun').listen;
   sleep: typeof import('bun').sleep;
   stdin: typeof import('bun').stdin;
 };

package/src/chrome-discover.ts

@@ -0,0 +1,73 @@
+/**
+ * Discover a running Chrome instance for CDP connection.
+ *
+ * Strategy (first match wins):
+ *   1. Read DevToolsActivePort file from known browser profile paths
+ *   2. Probe well-known CDP ports (9222, 9229)
+ *   3. Return null if nothing found
+ */
+
+import * as os from 'os';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const PROFILE_PATHS = [
+  'Google/Chrome',
+  'Arc/User Data',
+  'BraveSoftware/Brave-Browser',
+  'Microsoft Edge',
+];
+
+const PROBE_PORTS = [9222, 9229];
+
+/** Fetch the CDP WebSocket URL from a Chrome /json/version endpoint. */
+async function fetchWsUrl(port: number): Promise<string | null> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { webSocketDebuggerUrl?: string };
+    return data.webSocketDebuggerUrl ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a DevToolsActivePort file and extract the port number. */
+function readDevToolsPort(filePath: string): number | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const port = parseInt(content.split('\n')[0], 10);
+    return Number.isFinite(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover a running Chrome instance and return its CDP WebSocket URL.
+ * Returns null if no reachable Chrome is found.
+ */
+export async function discoverChrome(): Promise<string | null> {
+  const home = os.homedir();
+
+  // 1. Try DevToolsActivePort files
+  for (const profile of PROFILE_PATHS) {
+    const filePath = path.join(home, 'Library', 'Application Support', profile, 'DevToolsActivePort');
+    const port = readDevToolsPort(filePath);
+    if (port) {
+      const wsUrl = await fetchWsUrl(port);
+      if (wsUrl) return wsUrl;
+    }
+  }
+
+  // 2. Probe well-known ports
+  for (const port of PROBE_PORTS) {
+    const wsUrl = await fetchWsUrl(port);
+    if (wsUrl) return wsUrl;
+  }
+
+  // 3. Nothing found
+  return null;
+}