agent-browser-loop 0.2.1 → 0.3.0

package/.claude/skills/agent-browser-loop/REFERENCE.md

@@ -1,5 +1,7 @@
 # Agent Browser Loop - CLI Reference
 
+<!-- TIP: Check package.json for dev server scripts to find the port to test (e.g. dev:basic, dev:next) -->
+
 Complete CLI reference for `agent-browser`.
 
 ## Commands
@@ -18,12 +20,19 @@ agent-browser open <url> [options]
 | `--headed` | Show browser window (default: headless) |
 | `--new, -n` | Create new session with auto-generated ID |
 | `--session, -s <id>` | Target session (from `--new`) |
+| `--profile, -p <name>` | Load profile and save back on close |
+| `--no-save` | Don't save profile changes on close (read-only) |
+| `--width, -W <pixels>` | Viewport width (default: 1280) |
+| `--height, -H <pixels>` | Viewport height (default: 720) |
 | `--json` | Output as JSON |
 
 **Examples:**
 ```bash
 agent-browser open http://localhost:3000
 agent-browser open http://localhost:3000 --headed
+agent-browser open http://localhost:3000 --width 1920 --height 1080
+agent-browser open http://localhost:3000 --profile admin  # Loads and auto-saves on close
+agent-browser open http://localhost:3000 --profile admin --no-save  # Read-only
 agent-browser open --new http://localhost:3000  # Output: Session: swift-fox
 ```
 
@@ -54,6 +63,7 @@ agent-browser act <actions...> [options]
 | Type | `type:<ref>:<text>` | `type:input_0:hello` |
 | Press key | `press:<key>` | `press:Enter` |
 | Scroll | `scroll:<direction>[:<amount>]` | `scroll:down:500` |
+| Resize | `resize:<width>:<height>` | `resize:1920:1080` |
 | Select | `select:<ref>:<value>` | `select:select_0:option1` |
 | Check | `check:<ref>` | `check:checkbox_0` |
 | Uncheck | `uncheck:<ref>` | `uncheck:checkbox_0` |
@@ -213,6 +223,127 @@ agent-browser screenshot
 
 ---
 
+### `resize <width> <height>`
+
+Resize the browser viewport mid-session.
+
+```bash
+agent-browser resize <width> <height> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--session, -s <id>` | Target session |
+| `--json` | Output as JSON |
+
+**Examples:**
+```bash
+agent-browser resize 1920 1080
+agent-browser resize 375 667  # Mobile viewport
+agent-browser act "resize:1920:1080"  # Via act command
+```
+
+---
+
+### `profile <subcommand>`
+
+Manage session storage profiles (cookies + localStorage). The `<name>` in all commands is an arbitrary identifier you choose (e.g., `admin`, `testuser`, `staging`).
+
+#### `profile list`
+
+List all available profiles.
+
+```bash
+agent-browser profile list [--json]
+```
+
+#### `profile show <name>`
+
+Show profile contents.
+
+```bash
+agent-browser profile show <name> [--json]
+```
+
+#### `profile save <name>`
+
+Save current session storage to a profile.
+
+```bash
+agent-browser profile save <name> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--session, -s <id>` | Source session |
+| `--global` | Save to global profiles (`~/.config/agent-browser/profiles/`) |
+| `--private` | Save to private profiles (gitignored) |
+| `--description, -d <text>` | Profile description |
+
+#### `profile delete <name>`
+
+Delete a profile.
+
+```bash
+agent-browser profile delete <name>
+```
+
+#### `profile import <name> <path>`
+
+Import profile from a Playwright storage state JSON file.
+
+```bash
+agent-browser profile import <name> <path> [--global] [--private]
+```
+
+#### `profile capture <name>`
+
+Opens a headed browser, lets you interact manually (log in, etc.), then saves the session when you press Enter in the terminal.
+
+```bash
+agent-browser profile capture <name> --url <url> [options]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--url <url>` | URL to navigate to (required) |
+| `--global` | Save to global profiles |
+| `--private` | Save to private profiles |
+| `--description, -d <text>` | Profile description |
+
+**Examples:**
+```bash
+# Capture a session (opens browser, you log in, press Enter to save)
+agent-browser profile capture admin --url http://localhost:3000/login
+agent-browser profile capture testuser --url http://localhost:3000/login
+
+# Save from an already-open session instead
+agent-browser open http://localhost:3000/login --headed
+# ... log in manually ...
+agent-browser profile save admin --description "Admin account"
+
+# Use profile (loads saved cookies/localStorage)
+agent-browser open http://localhost:3000/dashboard --profile admin
+
+# List profiles
+agent-browser profile list
+
+# Import existing Playwright storage state file
+agent-browser profile import staging ./storage-state.json --global
+```
+
+**Profile Storage Locations:**
+- Local: `.agent-browser/profiles/<name>.json` (project-scoped, shareable via git)
+- Private: `.agent-browser/profiles/.private/<name>.json` (gitignored)
+- Global: `~/.config/agent-browser/profiles/<name>.json` (user-level)
+
+Resolution order: private -> local -> global
+
+---
+
 ### `close`
 
 Close browser session or stop daemon.

package/.claude/skills/agent-browser-loop/SKILL.md

@@ -3,12 +3,15 @@ name: agent-browser-loop
 description: Use when an agent must drive a live browser session in a back-and-forth loop (state -> explicit actions -> state) for UI validation, reproducible QA, or debugging UI behavior. Prefer this over one-shot CLI usage when an agent needs inspectable, stepwise control.
 ---
 
+
 # Agent Browser Loop
 
 Control a browser via CLI. Execute actions, read state, and verify UI changes in a stepwise loop.
 
 ## Quick Start
 
+> **TIP**: Check package.json for dev server scripts to find the port to test
+
 ```bash
 # Open a URL (starts browser daemon automatically)
 agent-browser open http://localhost:3000
@@ -165,13 +168,42 @@ agent-browser close
 # Headed mode (visible browser)
 agent-browser open http://localhost:3000 --headed
 
-# JSON output
-agent-browser state --json
+# Custom viewport size
+agent-browser open http://localhost:3000 --width 1920 --height 1080
+
+# Resize mid-session
+agent-browser resize 1920 1080
+```
+
+## Profiles (Session Storage)
+
+Save and reuse cookies/localStorage across sessions. The profile name (e.g., `admin`, `testuser`) is an arbitrary identifier you choose.
 
-# Skip state in response
-agent-browser act click:button_0 --no-state
+```bash
+# Capture: opens browser, you interact, press Enter in terminal to save
+agent-browser profile capture admin --url http://localhost:3000/login
+
+# Or save from an already-open session
+agent-browser open http://localhost:3000/login --headed
+# ... log in manually ...
+agent-browser profile save admin
+
+# Use saved profile - auto-saves updated tokens on close
+agent-browser open http://localhost:3000/dashboard --profile admin
+# ... use the app (tokens may refresh) ...
+agent-browser close  # Updated tokens saved back to profile
+
+# Use --no-save for read-only (don't save changes back)
+agent-browser open http://localhost:3000 --profile admin --no-save
+
+# List/manage profiles
+agent-browser profile list
+agent-browser profile show admin
+agent-browser profile delete admin
 ```
 
+Profiles are stored locally (`.agent-browser/profiles/`) or globally (`~/.config/agent-browser/profiles/`).
+
 ## Multi-Session
 
 Run multiple browsers in parallel with `--new`:

package/README.md

@@ -57,6 +57,45 @@ agent-browser state
 
 Every command returns the current page state - interactive elements, form values, scroll position, console errors, network failures. The agent sees exactly what it needs to verify the code works or debug why it doesn't.
 
+## Profiles (Session Storage)
+
+Save and reuse login sessions across runs:
+
+```bash
+# Save current session to a profile
+agent-browser profile save admin
+
+# Use profile (auto-saves updated tokens on close)
+agent-browser open http://localhost:3000 --profile admin
+
+# Use --no-save for read-only access
+agent-browser open http://localhost:3000 --profile admin --no-save
+
+# Other commands
+agent-browser profile list
+agent-browser profile capture admin --url http://localhost:3000/login
+agent-browser profile delete admin
+```
+
+Profiles store cookies and localStorage. Use `--global` for user-level profiles, `--private` for gitignored project profiles.
+
+## Multi-Session
+
+Run multiple browser sessions in parallel:
+
+```bash
+# Create sessions with auto-generated IDs
+agent-browser open --new http://localhost:3000     # Output: Session: swift-fox
+agent-browser open --new http://localhost:3000     # Output: Session: calm-river
+
+# Target specific sessions
+agent-browser act -s swift-fox click:button_0
+agent-browser state -s calm-river
+
+# List all sessions
+agent-browser sessions
+```
+
 ## CLI Reference
 
 | Command | Description |
@@ -102,23 +141,6 @@ agent-browser wait --timeout 60000         # Custom timeout
 --no-state            # Skip state in response
 ```
 
-## Multi-Session
-
-Run multiple browser sessions in parallel:
-
-```bash
-# Create sessions with auto-generated IDs
-agent-browser open --new http://localhost:3000     # Output: Session: swift-fox
-agent-browser open --new http://localhost:3000     # Output: Session: calm-river
-
-# Target specific sessions
-agent-browser act -s swift-fox click:button_0
-agent-browser state -s calm-river
-
-# List all sessions
-agent-browser sessions
-```
-
 ## State Output
 
 ```
@@ -172,6 +194,8 @@ export default defineBrowserConfig({
 });
 ```
 
+On macOS, headless system Chrome can crash during AppKit startup. By default, the CLI falls back to bundled Playwright Chromium when `headless: true`. If you explicitly want system Chrome in headless mode, set `allowSystemChromeHeadless: true`.
+
 ## What This Is NOT For
 
 This tool is for agents to test their own code. It is **not** for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser-loop",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Let your AI coding agent drive a browser to verify its own work",
   "license": "MIT",
   "author": "Jason Silberman",

package/src/actions.ts

@@ -1,4 +1,5 @@
 import type { Page, Request } from "playwright";
+import type { ElementRefStore } from "./ref-store";
 import type {
   ClickOptions,
   NavigateOptions,
@@ -7,27 +8,26 @@ import type {
 } from "./types";
 
 /**
- * Get a locator for an element by ref or index
- * After calling getState(), elements have data-ref attributes injected
+ * Get a locator for an element by ref or index using the ref store
+ * The ref store contains selectors generated during getState()
  */
-function getLocator(page: Page, options: { ref?: string; index?: number }) {
-  if (options.ref) {
-    return page.locator(`[data-ref="${options.ref}"]`);
-  }
-  if (options.index !== undefined) {
-    // Use data-index (injected by getState). Fallback to legacy e{index} refs.
-    return page.locator(
-      `[data-index="${options.index}"], [data-ref="e${options.index}"]`,
-    );
-  }
-  throw new Error("Must provide either ref or index");
+async function getLocator(
+  page: Page,
+  refStore: ElementRefStore,
+  options: { ref?: string; index?: number },
+) {
+  return await refStore.resolveLocator(page, options);
 }
 
 /**
  * Click an element
  */
-export async function click(page: Page, options: ClickOptions): Promise<void> {
-  const locator = getLocator(page, options);
+export async function click(
+  page: Page,
+  refStore: ElementRefStore,
+  options: ClickOptions,
+): Promise<void> {
+  const locator = await getLocator(page, refStore, options);
 
   const clickOptions: Parameters<typeof locator.click>[0] = {
     button: options.button,
@@ -44,8 +44,12 @@ export async function click(page: Page, options: ClickOptions): Promise<void> {
 /**
  * Type text into an element
  */
-export async function type(page: Page, options: TypeOptions): Promise<void> {
-  const locator = getLocator(page, options);
+export async function type(
+  page: Page,
+  refStore: ElementRefStore,
+  options: TypeOptions,
+): Promise<void> {
+  const locator = await getLocator(page, refStore, options);
 
   // Clear existing text if requested
   if (options.clear) {
@@ -129,9 +133,10 @@ export async function waitForElement(
  */
 export async function hover(
   page: Page,
+  refStore: ElementRefStore,
   options: { ref?: string; index?: number },
 ): Promise<void> {
-  const locator = getLocator(page, options);
+  const locator = await getLocator(page, refStore, options);
   await locator.hover();
 }
 
@@ -140,9 +145,10 @@ export async function hover(
  */
 export async function select(
   page: Page,
+  refStore: ElementRefStore,
   options: { ref?: string; index?: number; value: string | string[] },
 ): Promise<void> {
-  const locator = getLocator(page, options);
+  const locator = await getLocator(page, refStore, options);
   await locator.selectOption(options.value);
 }
 

package/src/browser.ts

@@ -3,6 +3,7 @@ import { chromium } from "playwright";
 import * as actions from "./actions";
 import { findChromeExecutable } from "./chrome";
 import { log } from "./log";
+import { ElementRefStore } from "./ref-store";
 import { formatStateText, getState } from "./state";
 import type {
   BrowserConfig,
@@ -33,12 +34,14 @@ export class AgentBrowser {
   private networkLogLimit: number;
   private usePersistentContext = false;
   private lastState: BrowserState | null = null;
+  private refStore: ElementRefStore = new ElementRefStore();
 
   constructor(options: AgentBrowserOptions = {}) {
     this.config = {
       headless: options.headless ?? true,
       executablePath: options.executablePath,
       useSystemChrome: options.useSystemChrome ?? true,
+      allowSystemChromeHeadless: options.allowSystemChromeHeadless,
       viewportWidth: options.viewportWidth ?? 1280,
       viewportHeight: options.viewportHeight ?? 720,
       userDataDir: options.userDataDir,
@@ -60,8 +63,27 @@ export class AgentBrowser {
       throw new Error("Browser already started");
     }
 
-    const resolvedExecutablePath = this.config.useSystemChrome
-      ? this.config.executablePath || findChromeExecutable()
+    const isDarwin = process.platform === "darwin";
+    let useSystemChrome = this.config.useSystemChrome ?? true;
+    let executablePath = this.config.executablePath;
+
+    if (
+      isDarwin &&
+      this.config.headless &&
+      (useSystemChrome || executablePath) &&
+      !this.config.allowSystemChromeHeadless
+    ) {
+      log
+        .withMetadata({ executablePath })
+        .warn(
+          "Headless system Chrome can crash on macOS. Falling back to bundled Chromium. Set allowSystemChromeHeadless to true to override.",
+        );
+      useSystemChrome = false;
+      executablePath = undefined;
+    }
+
+    const resolvedExecutablePath = useSystemChrome
+      ? executablePath || findChromeExecutable()
       : undefined;
 
     log
@@ -160,6 +182,7 @@ export class AgentBrowser {
     this.networkLogs = [];
     this.networkCaptureEnabled = false;
     this.usePersistentContext = false;
+    this.refStore.clear();
   }
 
   /**
@@ -190,15 +213,21 @@ export class AgentBrowser {
     options?: Omit<NavigateOptions, "url">,
   ): Promise<void> {
     await actions.navigate(this.getPage(), { url, ...options });
+    this.refStore.clear();
   }
 
   /**
    * Get rich state of the current page
-   * Also injects data-ref attributes for element targeting
+   * Stores element refs server-side (no DOM modification)
    */
   async getState(options?: GetStateOptions): Promise<BrowserState> {
-    // getState now handles ref injection internally
-    const state = await getState(this.getPage(), this.getContext(), options);
+    // getState now stores refs in this.refStore instead of injecting into DOM
+    const state = await getState(
+      this.getPage(),
+      this.getContext(),
+      this.refStore,
+      options,
+    );
     const result = {
       ...state,
       errors: {
@@ -254,14 +283,14 @@ export class AgentBrowser {
    * Click an element
    */
   async click(options: ClickOptions): Promise<void> {
-    await actions.click(this.getPage(), options);
+    await actions.click(this.getPage(), this.refStore, options);
   }
 
   /**
    * Type text into an element
    */
   async type(options: TypeOptions): Promise<void> {
-    await actions.type(this.getPage(), options);
+    await actions.type(this.getPage(), this.refStore, options);
   }
 
   /**
@@ -429,7 +458,7 @@ export class AgentBrowser {
    * Hover over an element
    */
   async hover(options: { ref?: string; index?: number }): Promise<void> {
-    await actions.hover(this.getPage(), options);
+    await actions.hover(this.getPage(), this.refStore, options);
   }
 
   /**
@@ -440,7 +469,7 @@ export class AgentBrowser {
     index?: number;
     value: string | string[];
   }): Promise<void> {
-    await actions.select(this.getPage(), options);
+    await actions.select(this.getPage(), this.refStore, options);
   }
 
   /**
@@ -453,6 +482,28 @@ export class AgentBrowser {
     return actions.screenshot(this.getPage(), options);
   }
 
+  /**
+   * Resize the viewport
+   */
+  async resize(width: number, height: number): Promise<void> {
+    await this.getPage().setViewportSize({ width, height });
+    this.config.viewportWidth = width;
+    this.config.viewportHeight = height;
+  }
+
+  /**
+   * Get current viewport size
+   */
+  getViewportSize(): { width: number; height: number } {
+    const size = this.getPage().viewportSize();
+    return (
+      size ?? {
+        width: this.config.viewportWidth!,
+        height: this.config.viewportHeight!,
+      }
+    );
+  }
+
   /**
    * Get captured console logs
    */
@@ -554,6 +605,13 @@ export class AgentBrowser {
     }
     return state;
   }
+
+  /**
+   * Get the element ref store (for advanced usage/testing)
+   */
+  getRefStore(): ElementRefStore {
+    return this.refStore;
+  }
 }
 
 /**