@ulpi/browse 0.1.0 → 0.2.1

package/README.md

@@ -172,15 +172,21 @@ bun install -g @ulpi/browse
 
 Requires [Bun](https://bun.sh). Chromium is installed automatically via Playwright.
 
-### Claude Code Skill (optional)
+### Claude Code Skill
 
-Install the browse skill into your project so Claude Code uses it automatically:
+Install via [skills.sh](https://skills.sh) (works across Claude Code, Cursor, Cline, Windsurf, and 15+ agents):
+
+```bash
+npx skills add https://github.com/ulpi-io/skills --skill browse
+```
+
+Or install directly into your project:
 
 ```bash
 browse install-skill
 ```
 
-This copies the skill definition to `.claude/skills/browse/SKILL.md` and adds all browse commands to `.claude/settings.json` permissions — no more approval prompts.
+Both copy the skill definition to `.claude/skills/browse/SKILL.md` and add all browse commands to permissions — no more approval prompts.
 
 ## Real-World Example: E-Commerce Flow
 

package/bin/browse.ts

@@ -1,2 +1,11 @@
 #!/usr/bin/env bun
-import '../src/cli';
+import { main } from '../src/cli';
+
+if (process.env.__BROWSE_SERVER_MODE === '1') {
+  import('../src/server');
+} else {
+  main().catch((err) => {
+    console.error(`[browse] ${err.message}`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"
@@ -37,18 +37,19 @@
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
-  "devDependencies": {
-    "@types/node": "^25.5.0",
-    "typescript": "^5.9.3"
-  },
   "scripts": {
-    "build": "bun build --compile src/cli.ts --outfile dist/browse",
+    "build": "bun build --compile --external electron --external chromium-bidi src/cli.ts --outfile dist/browse",
+    "build:all": "bash scripts/build-all.sh",
     "dev": "bun run src/cli.ts",
     "server": "bun run src/server.ts",
     "test": "bun test",
     "start": "bun run src/server.ts",
     "postinstall": "bunx playwright install chromium",
     "benchmark": "bun run benchmark.ts"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
   }
-}
+}

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse
-version: 1.0.0
+version: 2.0.0
 description: |
   Fast web browsing for Claude Code via persistent headless Chromium daemon. Navigate to any URL,
   read page content, click elements, fill forms, run JavaScript, take screenshots,
@@ -53,20 +53,29 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse html:*)", "Bash(browse links:*)", "Bash(browse forms:*)",
 "Bash(browse accessibility:*)", "Bash(browse snapshot:*)",
 "Bash(browse snapshot-diff:*)", "Bash(browse click:*)",
-"Bash(browse fill:*)", "Bash(browse select:*)", "Bash(browse hover:*)",
-"Bash(browse type:*)", "Bash(browse press:*)", "Bash(browse scroll:*)",
-"Bash(browse wait:*)", "Bash(browse viewport:*)", "Bash(browse upload:*)",
+"Bash(browse dblclick:*)", "Bash(browse fill:*)", "Bash(browse select:*)",
+"Bash(browse hover:*)", "Bash(browse focus:*)",
+"Bash(browse check:*)", "Bash(browse uncheck:*)",
+"Bash(browse type:*)", "Bash(browse press:*)",
+"Bash(browse keydown:*)", "Bash(browse keyup:*)",
+"Bash(browse scroll:*)", "Bash(browse wait:*)",
+"Bash(browse viewport:*)", "Bash(browse upload:*)",
+"Bash(browse drag:*)", "Bash(browse highlight:*)", "Bash(browse download:*)",
 "Bash(browse dialog-accept:*)", "Bash(browse dialog-dismiss:*)",
 "Bash(browse js:*)", "Bash(browse eval:*)", "Bash(browse css:*)",
-"Bash(browse attrs:*)", "Bash(browse state:*)", "Bash(browse dialog:*)",
+"Bash(browse attrs:*)", "Bash(browse element-state:*)", "Bash(browse dialog:*)",
 "Bash(browse console:*)", "Bash(browse network:*)",
 "Bash(browse cookies:*)", "Bash(browse storage:*)", "Bash(browse perf:*)",
+"Bash(browse value:*)", "Bash(browse count:*)",
 "Bash(browse devices:*)", "Bash(browse emulate:*)",
 "Bash(browse screenshot:*)", "Bash(browse pdf:*)",
 "Bash(browse responsive:*)", "Bash(browse diff:*)",
 "Bash(browse chain:*)", "Bash(browse tabs:*)", "Bash(browse tab:*)",
 "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 route:*)", "Bash(browse offline:*)",
 "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
 "Bash(browse cookie:*)", "Bash(browse header:*)",
 "Bash(browse useragent:*)"
@@ -80,6 +89,9 @@ If the file is missing or does not contain browse permission rules in `permissio
 - The browser persists between calls — cookies, tabs, and state carry over.
 - The server auto-starts on first command. No manual setup needed.
 - Use `--session <id>` for parallel agent isolation. Each session gets its own tabs, refs, cookies.
+- Use `--json` for structured output (`{success, data, command}`).
+- Use `--content-boundaries` for prompt injection defense.
+- Use `--allowed-domains domain1,domain2` to restrict navigation.
 
 ## Quick Reference
 
@@ -91,7 +103,7 @@ browse goto https://example.com
 browse text
 
 # Take a screenshot (then Read the image)
-browse screenshot .browse/page.png
+browse screenshot .browse/sessions/default/screenshot.png
 
 # Snapshot: accessibility tree with refs
 browse snapshot -i
@@ -102,12 +114,25 @@ browse click @e3
 # Fill by ref
 browse fill @e4 "test@test.com"
 
+# Double-click, focus, check/uncheck
+browse dblclick @e3
+browse focus @e5
+browse check @e7
+browse uncheck @e7
+
+# Drag and drop
+browse drag @e1 @e2
+
 # Run JavaScript
 browse js "document.title"
 
 # Get all links
 browse links
 
+# Get input value / count elements
+browse value "[id=email]"
+browse count ".search-result"
+
 # Click by CSS selector
 browse click "button.submit"
 
@@ -116,17 +141,58 @@ browse fill "[id=email]" "test@test.com"
 browse fill "[id=password]" "abc123"
 browse click "button[type=submit]"
 
-# Get HTML of an element
-browse html "main"
+# Scroll
+browse scroll up
+browse scroll down
+browse scroll "[id=target]"
+
+# Wait for navigation or network
+browse wait ".loaded"
+browse wait --url "**/dashboard"
+browse wait --network-idle
 
-# Get computed CSS
-browse css "body" "font-family"
+# iframe targeting
+browse frame "[id=my-iframe]"
+browse text                    # reads from inside the iframe
+browse click @e3               # clicks inside the iframe
+browse frame main              # back to main page
 
-# Get element attributes
-browse attrs "nav"
+# Highlight an element (visual debugging)
+browse highlight @e5
 
-# Wait for element to appear
-browse wait ".loaded"
+# Download a file
+browse download @e3 ./file.pdf
+
+# Network mocking
+browse route "**/*.png" block
+browse route "**/api/data" fulfill 200 '{"mock":true}'
+browse route clear
+
+# Offline mode
+browse offline on
+browse offline off
+
+# JSON output mode
+browse --json goto https://example.com
+
+# Security: content boundaries
+browse --content-boundaries text
+
+# Security: domain restriction
+browse --allowed-domains example.com,*.cdn.example.com goto https://example.com
+
+# State persistence
+browse state save mysite
+browse state load mysite
+
+# Auth vault (credentials never visible to LLM)
+browse auth save github https://github.com/login user pass123
+browse auth login github
+
+# HAR recording
+browse har start
+browse goto https://example.com
+browse har stop ./recording.har
 
 # Device emulation
 browse emulate iphone
@@ -183,19 +249,36 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Interaction
 ```
 browse click <selector>        Click element (CSS selector or @ref)
+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 check <selector>        Check checkbox
+browse uncheck <selector>      Uncheck checkbox
+browse drag <src> <tgt>        Drag source to target
 browse type <text>             Type into focused element
 browse press <key>             Press key (Enter, Tab, Escape, etc.)
-browse scroll [selector]       Scroll element into view, or page bottom
-browse wait <selector>         Wait for element to appear (max 15s)
+browse keydown <key>           Hold key down
+browse keyup <key>             Release key
+browse scroll [sel|up|down]    Scroll element/viewport/bottom
+browse wait <sel|--url|--network-idle>  Wait for element, URL, or network
 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)
+browse download <sel> [path]   Download file triggered by click
 browse dialog-accept [value]   Set dialogs to auto-accept
 browse dialog-dismiss          Set dialogs to auto-dismiss (default)
 browse emulate <device>        Emulate device (iphone, pixel, etc.)
 browse emulate reset           Reset to desktop (1920x1080)
+browse offline [on|off]        Toggle offline mode
+```
+
+### Network
+```
+browse route <pattern> block           Block matching requests
+browse route <pattern> fulfill <s> [b] Mock with status + body
+browse route clear                     Remove all routes
 ```
 
 ### Inspection
@@ -204,7 +287,9 @@ browse js <expression>         Run JS, print result
 browse eval <js-file>          Run JS file against page
 browse css <selector> <prop>   Get computed CSS property
 browse attrs <selector>        Get element attributes as JSON
-browse state <selector>        Element state (visible/enabled/checked/focused)
+browse element-state <selector> Element state (visible/enabled/checked/focused)
+browse value <selector>        Get input field value
+browse count <selector>        Count matching elements
 browse dialog                  Last dialog info or "(no dialog detected)"
 browse console [--clear]       View/clear console messages
 browse network [--clear]       View/clear network requests
@@ -216,12 +301,18 @@ browse devices [filter]        List available device names
 
 ### Visual
 ```
-browse screenshot [path]              Screenshot (default: .browse/browse-screenshot.png)
+browse screenshot [path]              Screenshot (default: .browse/sessions/{id}/screenshot.png)
 browse screenshot --annotate [path]   Screenshot with numbered badges + legend
 browse pdf [path]                     Save as PDF
 browse responsive [prefix]            Screenshots at mobile/tablet/desktop
 ```
 
+### Frames (iframe targeting)
+```
+browse frame <selector>        Target an iframe (subsequent commands run inside it)
+browse frame main              Return to main page
+```
+
 ### Compare
 ```
 browse diff <url1> <url2>      Text diff between two pages
@@ -247,6 +338,26 @@ browse sessions                List active sessions
 browse session-close <id>      Close a session
 ```
 
+### State persistence
+```
+browse state save [name]       Save cookies + localStorage (all origins)
+browse state load [name]       Restore saved state
+```
+
+### Auth vault
+```
+browse auth save <name> <url> <user> <pass>   Save credentials (encrypted)
+browse auth login <name>                       Auto-login using saved credentials
+browse auth list                               List saved credentials
+browse auth delete <name>                      Delete credentials
+```
+
+### HAR recording
+```
+browse har start               Start recording network traffic
+browse har stop [path]         Stop and save HAR file
+```
+
 ### Server management
 ```
 browse status                  Server health, uptime, session count
@@ -254,6 +365,15 @@ browse stop                    Shutdown server
 browse restart                 Kill + restart server
 ```
 
+## CLI Flags
+
+| 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 (prompt injection defense) |
+| `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
+
 ## Speed Rules
 
 1. **Navigate once, query many times.** `goto` loads the page; then `text`, `js`, `css`, `screenshot` all run against the loaded page instantly.
@@ -264,6 +384,8 @@ browse restart                 Kill + restart server
 6. **Use `chain` for multi-step flows.** Avoids CLI overhead per step.
 7. **Use `responsive` for layout checks.** One command = 3 viewport screenshots.
 8. **Use `--session` for parallel work.** Multiple agents can browse simultaneously without interference.
+9. **Use `value`/`count` instead of `js`.** Purpose-built commands are cleaner than `js "document.querySelector(...).value"`.
+10. **Use `frame` for iframes.** Don't try to reach into iframes with CSS — use `frame [id=x]` first.
 
 ## When to Use What
 
@@ -272,30 +394,45 @@ browse restart                 Kill + restart server
 | Read a page | `goto <url>` then `text` |
 | Interact with elements | `snapshot -i` then `click @e3` |
 | Find hidden clickables | `snapshot -i -C` then `click @e15` |
-| Check if element exists | `js "!!document.querySelector('.thing')"` |
+| Check if element exists | `count ".thing"` |
+| Get input value | `value "[id=email]"` |
 | Extract specific data | `js "document.querySelector('.price').textContent"` |
-| Visual check | `screenshot .browse/x.png` then Read the image |
+| Visual check | `screenshot .browse/sessions/default/x.png` then Read the image |
 | Fill and submit form | `snapshot -i` → `fill @e4 "val"` → `click @e5` |
+| Check/uncheck boxes | `check @e7` / `uncheck @e7` |
 | Check CSS | `css "selector" "property"` or `css @e3 "property"` |
 | Inspect DOM | `html "selector"` or `attrs @e3` |
 | Debug console errors | `console` |
 | Check network requests | `network` |
+| Mock API responses | `route "**/api/*" fulfill 200 '{"data":[]}'` |
+| Block ads/trackers | `route "**/*.doubleclick.net/*" block` |
+| Test offline behavior | `offline on` → test → `offline off` |
+| Interact in iframe | `frame "[id=payment]"` → `fill @e2 "4242..."` → `frame main` |
 | Check local dev | `goto http://127.0.0.1:3000` |
 | Compare two pages | `diff <url1> <url2>` |
-| Mobile layout check | `responsive .browse/prefix` |
+| Mobile layout check | `responsive .browse/sessions/default/resp` |
 | Test on mobile device | `emulate iphone` → `goto <url>` → `screenshot` |
+| 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` |
 | 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` |
+| Scroll through results | `scroll down` → `text` → `scroll down` → `text` |
+| Drag and drop | `drag @e1 @e2` |
 
 ## Architecture
 
-- Persistent Chromium daemon on localhost (port 9400-9410)
+- Persistent Chromium daemon on localhost (port 9400-10400)
 - Bearer token auth per session
+- Auto-instance: each parent process (Claude Code) gets its own server
 - Session multiplexing: multiple agents share one Chromium via isolated BrowserContexts
 - Project-local state: `.browse/` directory at project root (auto-created, self-gitignored)
-  - `browse-server.json` — server PID, port, auth token
-  - `browse-console.log` — captured console messages
-  - `browse-network.log` — captured network requests
-  - `browse-screenshot.png` — default screenshot location
+  - `sessions/{id}/` — per-session screenshots, logs, PDFs
+  - `states/{name}.json` — saved browser state (cookies + localStorage)
+  - `browse-server-{instance}.json` — server PID, port, auth token
 - Auto-shutdown when all sessions idle past 30 min
 - Chromium crash → server exits → auto-restarts on next command
+- AI-friendly error messages: Playwright errors rewritten to actionable hints
+- CDP remote connection: `BROWSE_CDP_URL` to connect to existing Chrome
+- Policy enforcement: `browse-policy.json` for allow/deny/confirm rules

package/src/auth-vault.ts

@@ -0,0 +1,244 @@
+/**
+ * Credential vault — AES-256-GCM encrypted credential storage
+ *
+ * Encryption key: BROWSE_ENCRYPTION_KEY env var (64-char hex)
+ * or auto-generated at .browse/.encryption-key
+ *
+ * Storage: .browse/auth/<name>.json (mode 0o600)
+ * 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 { sanitizeName } from './sanitize';
+
+interface StoredCredential {
+  name: string;
+  url: string;
+  username: string;
+  encrypted: true;
+  iv: string;       // base64
+  authTag: string;  // base64
+  data: string;     // base64 (encrypted password)
+  usernameSelector?: string;
+  passwordSelector?: string;
+  submitSelector?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CredentialInfo {
+  name: string;
+  url: string;
+  username: string;
+  hasPassword: boolean;
+  createdAt: string;
+}
+
+export class AuthVault {
+  private authDir: string;
+  private encryptionKey: Buffer;
+
+  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');
+  }
+
+  save(
+    name: string,
+    url: string,
+    username: string,
+    password: string,
+    selectors?: { username?: string; password?: string; submit?: string },
+  ): void {
+    fs.mkdirSync(this.authDir, { recursive: true });
+
+    const { ciphertext, iv, authTag } = this.encrypt(password);
+    const now = new Date().toISOString();
+
+    const credential: StoredCredential = {
+      name,
+      url,
+      username,
+      encrypted: true,
+      iv,
+      authTag,
+      data: ciphertext,
+      usernameSelector: selectors?.username,
+      passwordSelector: selectors?.password,
+      submitSelector: selectors?.submit,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(credential, null, 2), { mode: 0o600 });
+  }
+
+  private load(name: string): StoredCredential {
+    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Credential "${name}" not found. Run "browse auth list" to see saved credentials.`);
+    }
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  }
+
+  async login(name: string, bm: BrowserManager): Promise<string> {
+    const cred = this.load(name);
+    const password = this.decrypt(cred.data, cred.iv, cred.authTag);
+    const page = bm.getPage();
+
+    // Navigate to login URL
+    await page.goto(cred.url, {
+      waitUntil: 'domcontentloaded',
+      timeout: DEFAULTS.COMMAND_TIMEOUT_MS,
+    });
+
+    // Resolve selectors: use stored or auto-detect
+    const userSel = cred.usernameSelector || await autoDetectSelector(page, 'username');
+    const passSel = cred.passwordSelector || await autoDetectSelector(page, 'password');
+    const submitSel = cred.submitSelector || await autoDetectSelector(page, 'submit');
+
+    // Fill credentials
+    await page.fill(userSel, cred.username, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+    await page.fill(passSel, password, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+
+    // Submit
+    await page.click(submitSel, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
+    await page.waitForLoadState('domcontentloaded').catch(() => {});
+
+    return `Logged in as ${cred.username} at ${page.url()}`;
+  }
+
+  list(): CredentialInfo[] {
+    if (!fs.existsSync(this.authDir)) return [];
+
+    const files = fs.readdirSync(this.authDir).filter(f => f.endsWith('.json'));
+    return files.map(f => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(this.authDir, f), 'utf-8'));
+        return {
+          name: data.name,
+          url: data.url,
+          username: data.username,
+          hasPassword: true,
+          createdAt: data.createdAt,
+        };
+      } catch {
+        return null;
+      }
+    }).filter(Boolean) as CredentialInfo[];
+  }
+
+  delete(name: string): void {
+    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Credential "${name}" not found.`);
+    }
+    fs.unlinkSync(filePath);
+  }
+}
+
+/**
+ * Auto-detect login form selectors by common patterns.
+ */
+async function autoDetectSelector(page: any, field: 'username' | 'password' | 'submit'): Promise<string> {
+  if (field === 'username') {
+    const candidates = [
+      'input[type="email"]',
+      'input[name="email"]',
+      'input[name="username"]',
+      'input[name="user"]',
+      'input[name="login"]',
+      'input[autocomplete="username"]',
+      'input[autocomplete="email"]',
+      'input[type="text"]:first-of-type',
+    ];
+    for (const sel of candidates) {
+      const count = await page.locator(sel).count();
+      if (count > 0) return sel;
+    }
+    throw new Error('Could not auto-detect username field. Save with explicit selectors: browse auth save <name> <url> <user> <pass> --user-sel <sel> --pass-sel <sel> --submit-sel <sel>');
+  }
+
+  if (field === 'password') {
+    const candidates = [
+      'input[type="password"]',
+      'input[name="password"]',
+      'input[name="pass"]',
+      'input[autocomplete="current-password"]',
+    ];
+    for (const sel of candidates) {
+      const count = await page.locator(sel).count();
+      if (count > 0) return sel;
+    }
+    throw new Error('Could not auto-detect password field.');
+  }
+
+  // submit
+  const candidates = [
+    'button[type="submit"]',
+    'input[type="submit"]',
+    'form button',
+    'button:has-text("Log in")',
+    'button:has-text("Sign in")',
+    'button:has-text("Login")',
+    'button:has-text("Submit")',
+  ];
+  for (const sel of candidates) {
+    const count = await page.locator(sel).count();
+    if (count > 0) return sel;
+  }
+  throw new Error('Could not auto-detect submit button.');
+}