browserctl 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3b71160a355802bb8e1fd6667506af34dc354c97b60eb2e82e0b418c02dbe6
-  data.tar.gz: 83da78edf2d59d84be5a6fd617e5b2388928c77b005d7735f466ce4aad19699b
+  metadata.gz: 37a7ccbe134ac1d42b514959c3db2ed17fd0229fdaed839842cf0af4a872d132
+  data.tar.gz: cea2a653eab69d4f544612122deb1bffe7827fca546b74c6f17f5fa8a16c6e8d
 SHA512:
-  metadata.gz: 1ff6294fbc0284a342d9d2377077a02f004aec2acfeb3c1908039b09753d203e8a641d1dd2cd8ab2fd1fc607c42af3aa86537fb47361bb6820cf9a04fa8d6159
-  data.tar.gz: d029df7a2d280172543cb52dcee92326c97464d3b8d750d2f718710d46db16402b8e1a235c83c5da229a2ae047a4ab92738c3d736f741a4964c1d324f7871c15
+  metadata.gz: 4bcf1b0d2200b774305555ec8d777d243556b4cb02c3aa7fc015392e6adec331613d17b020b0933212983914a8920beeab511b4dddadab7a2ee45f163897b84b
+  data.tar.gz: 551860c7cefd52148d764146e98083deb5c2cdea07e67fe458e33abf420c05a26e2783e763839e3bdd9011a0668a8fb1819f9284c97a47e746057afc3afeb6c3

data/CHANGELOG.md

@@ -10,6 +10,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0](https://github.com/patrick204nqh/browserctl/compare/v0.5.0...v0.6.0) (2026-04-28)
+
+
+### Features
+
+* add feedback capture guidelines and update .gitignore to include feedback directory ([03a436d](https://github.com/patrick204nqh/browserctl/commit/03a436d69d37826a6c24662b70d6852eac78aa54))
+* **v0.6:** CLI redesign — noun-verb commands, storage/session, daemon auto-index ([#41](https://github.com/patrick204nqh/browserctl/issues/41)) ([b40040f](https://github.com/patrick204nqh/browserctl/commit/b40040f6fba7b78791e845e55af156be46bde3c3))
+* **v0.6:** page_focus command, integration specs, and doc polish ([#42](https://github.com/patrick204nqh/browserctl/issues/42)) ([8cf006d](https://github.com/patrick204nqh/browserctl/commit/8cf006d0e3698bb0698c59d7af5b87f72a3cd154))
+
+
+### Bug Fixes
+
+* correct initial checkbox state assertion to [false, true, false] ([#33](https://github.com/patrick204nqh/browserctl/issues/33)) ([5ab0fe4](https://github.com/patrick204nqh/browserctl/commit/5ab0fe4fbe5d5f244c795235f0531e0c970d75c7))
+* dismiss on-load notifications before asserting counts ([#35](https://github.com/patrick204nqh/browserctl/issues/35)) ([b508ba6](https://github.com/patrick204nqh/browserctl/commit/b508ba6748d245526f6321a731e6a7bf4ad5cc86))
+* fill replaces existing input value instead of appending ([#29](https://github.com/patrick204nqh/browserctl/issues/29)) ([c7abb48](https://github.com/patrick204nqh/browserctl/commit/c7abb48153e1c64fcd73e22a5bf376a98555f68c))
+* notifications workflow — exclude container from counts, use evaluate for dismiss ([#34](https://github.com/patrick204nqh/browserctl/issues/34)) ([de43301](https://github.com/patrick204nqh/browserctl/commit/de43301942eb7a6335bc9fc7130c22ecf3dd8b38))
+* README & CONTRIBUTING polish + Rakefile v0.6 CI fix ([#43](https://github.com/patrick204nqh/browserctl/issues/43)) ([422c614](https://github.com/patrick204nqh/browserctl/commit/422c6141035d47bb3fd4bc86f732029b44e35206))
+* replace all remaining stale v0.5 CLI commands with v0.6 equivalents ([#45](https://github.com/patrick204nqh/browserctl/issues/45)) ([8d00923](https://github.com/patrick204nqh/browserctl/commit/8d0092380bbc7890761e6d8f5da7864358ce88f7))
+* update demo assets installation and improve login tape requirements ([cf02e3a](https://github.com/patrick204nqh/browserctl/commit/cf02e3ad11fc99f1483904e396160d4345363e17))
+* update login demo tape to use data-test selectors for input fields and buttons ([016fcda](https://github.com/patrick204nqh/browserctl/commit/016fcdaf77ce542d06efe898312063581fc3fffe))
+* update stale `browserctl run` references to `browserctl workflow run` ([#44](https://github.com/patrick204nqh/browserctl/issues/44)) ([7f7005a](https://github.com/patrick204nqh/browserctl/commit/7f7005ac6fd6517c8751cf808378233343e9ace8))
+* use baseline delta assertions instead of absolute notification counts ([#37](https://github.com/patrick204nqh/browserctl/issues/37)) ([33ac119](https://github.com/patrick204nqh/browserctl/commit/33ac119bbb43c0290fe03da06ca3f8545095f7a2))
+* wait for notification-container before dismissing on-load toasts ([#36](https://github.com/patrick204nqh/browserctl/issues/36)) ([883cdf8](https://github.com/patrick204nqh/browserctl/commit/883cdf839bcef2d57bcb4764ff89862aa1969486))
+
+## [0.5.0](https://github.com/patrick204nqh/browserctl/compare/v0.4.0...v0.5.0) (2026-04-25)
+
+
+### Features
+
+* add cookie export/import commands and refine interaction guidance ([1dc8b2c](https://github.com/patrick204nqh/browserctl/commit/1dc8b2c4c744a5f0930c28d3bcf93fd017c368b1))
+* rename snapshot format 'ai' to 'elements' ([#22](https://github.com/patrick204nqh/browserctl/issues/22)) ([9fde6af](https://github.com/patrick204nqh/browserctl/commit/9fde6afb9e53b9556c84b4c24987777a5c266adf))
+* v0.5 architecture & protocol lock ([#20](https://github.com/patrick204nqh/browserctl/issues/20)) ([1224f2f](https://github.com/patrick204nqh/browserctl/commit/1224f2fe2fb05119053831e7901b286fe93ad4fc))
+
+
+### Bug Fixes
+
+* add rake as development dependency ([13902d8](https://github.com/patrick204nqh/browserctl/commit/13902d81fdb986c6ca754fcb16ce61ee850e27ce))
+* improve browser GIF quality and fix terminal font rendering ([17afdb2](https://github.com/patrick204nqh/browserctl/commit/17afdb210916d8ebdabd237130da1fc534cdbd3e))
+* open PR for demo assets instead of pushing directly to main ([f051316](https://github.com/patrick204nqh/browserctl/commit/f051316962d308419c08f60550cfb9910b148f14))
+* quote filtergraph and add -update 1 for palette in browser GIF pipeline ([053d074](https://github.com/patrick204nqh/browserctl/commit/053d074b5fdd3e0ea6fc51589593d72d5f7fcd74))
+* replace undefined REGISTRY constant with Browserctl.registry_snapshot ([d19a6bf](https://github.com/patrick204nqh/browserctl/commit/d19a6bf7ded8a5211f5b2a75511a9532f94e3845))
+* update README for improved clarity and add Quick Start section ([881d914](https://github.com/patrick204nqh/browserctl/commit/881d914c2bf46625ee4ff5c1ca8ef21b462c533d))
+* use app-slug output instead of gh api /app in assets workflow ([ae6a0f8](https://github.com/patrick204nqh/browserctl/commit/ae6a0f80ba2b66c76d681b1f258de5d72bc34c72))
+* use CSS selectors for browser GIF and add full login flow frames ([717b86b](https://github.com/patrick204nqh/browserctl/commit/717b86befa9af6bab1823f984668ebdc29f2d7f8))
+
 ## [0.4.0](https://github.com/patrick204nqh/browserctl/compare/v0.3.1...v0.4.0) (2026-04-25)
 
 

data/README.md

@@ -2,27 +2,96 @@
   <img src=".github/logo.svg" width="96" height="96" alt="browserctl logo"/>
 </p>
 
-# browserctl
+<h1 align="center">browserctl</h1>
 
-[![CI](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/browserctl.svg)](https://badge.fury.io/rb/browserctl)
-[![Downloads](https://img.shields.io/gem/dt/browserctl)](https://rubygems.org/gems/browserctl)
+<p align="center">
+  A browser daemon that keeps sessions alive between commands — for AI agents and iterative dev workflows.
+</p>
+
+<p align="center">
+  <a href="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml"><img src="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+  <a href="https://badge.fury.io/rb/browserctl"><img src="https://badge.fury.io/rb/browserctl.svg" alt="Gem Version"/></a>
+  <a href="https://rubygems.org/gems/browserctl"><img src="https://img.shields.io/gem/dt/browserctl" alt="Downloads"/></a>
+</p>
 
-A persistent browser automation daemon and CLI, purpose-built for AI agents and developer workflows.
+---
 
-Unlike tools that restart the browser on every script run, **browserctl keeps a named browser session alive** — preserving cookies, localStorage, open tabs, and page state across discrete commands.
+Every browser automation tool restarts the browser when your script ends. That means re-authenticating, re-navigating, re-loading state — on every run. browserctl doesn't restart. The session stays alive between commands, so you pick up exactly where you left off.
 
 ```bash
 browserd &                                               # start the daemon (headless)
-browserctl open login --url https://example.com/login
-browserctl snap login                                    # AI-friendly JSON snapshot with ref IDs
-browserctl fill login --ref e1 --value me@example.com   # interact by ref, no selectors needed
-browserctl click login --ref e2
-browserctl shutdown
+browserctl page open main --url https://example.com/login
+browserctl snapshot main                                 # AI-friendly JSON snapshot with ref IDs
+browserctl fill main --ref e1 --value me@example.com    # interact by ref, no selectors needed
+browserctl click main --ref e2
+browserctl daemon stop
+```
+
+---
+
+## See it in action
+
+<table align="center"><tr>
+<td align="center" width="50%">
+
+**Terminal**<br/>
+<sub>CLI commands, live output, session persistence proof</sub>
+
+<img src="docs/assets/terminal.gif" alt="browserctl terminal demo"/>
+
+</td>
+<td align="center" width="50%">
+
+**Browser**<br/>
+<sub>What the browser sees as those commands run</sub>
+
+<img src="docs/assets/browser_demo.gif" alt="browserctl browser demo"/>
+
+</td>
+</tr></table>
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+gem install browserctl
+
+# 2. Start the daemon
+browserd &
+
+# 3. Open a named page
+browserctl page open main --url https://moatazeldebsy.github.io/test-automation-practices/#/auth
+
+# 4. Snapshot — returns JSON with a ref ID per interactable element
+browserctl snapshot main
+# → [{"ref":"e1","tag":"input","attrs":{"data-test":"username-input"}}, {"ref":"e2",...}, {"ref":"e3","tag":"button","text":"Login",...}]
+
+# 5. Interact using the ref IDs from the snapshot
+browserctl fill main --ref e1 --value admin
+browserctl fill main --ref e2 --value admin
+browserctl click main --ref e3
+
+# 6. Observe
+browserctl url main
+browserctl snapshot main --diff   # only what changed
+
+# 7. Done
+browserctl daemon stop
 ```
 
-![browserctl capturing a login flow](docs/screenshots/the_internet_login.png)
-<p align="center"><sub>Login flow captured with <code>browserctl shot</code></sub></p>
+→ [Full Getting Started guide](docs/getting-started.md)
+
+---
+
+## Use cases
+
+**AI coding agent authenticating into a staging environment** — the agent logs in once, the session persists, subsequent commands run inside the authenticated context without re-authenticating between steps.
+
+**Developer reproducing a multi-step bug report** — navigate to the failure point once, then iterate on the fix with the browser already in the right state; no restarting from the home page each run.
+
+**Automated smoke test that needs human sign-off** — the test runs until it hits something ambiguous, calls `browserctl pause`, lets a human inspect and act, then `browserctl resume` hands control back to the script with all state intact.
 
 ---
 
@@ -30,7 +99,7 @@ browserctl shutdown
 
 Most automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.
 
-| | browserctl | Playwright / Selenium |
+| Capability | browserctl | Playwright / Selenium |
 |---|---|---|
 | Session persists across commands | ✓ | ✗ (per-script lifecycle) |
 | Named page handles | ✓ | ✗ |
@@ -46,15 +115,10 @@ Most automation tools are stateless — every script spins up a fresh browser an
 
 ---
 
-## Requirements
-
-- Ruby >= 3.3
-- Chrome or Chromium on your `PATH`
-
----
-
 ## Installation
 
+**Requirements:** Ruby >= 3.3 · Chrome or Chromium installed
+
 ```bash
 gem install browserctl
 ```
@@ -71,14 +135,14 @@ gem "browserctl"
 
 browserctl ships as a Claude Code plugin. Install it once and Claude automatically knows how to use the daemon, ref-based interaction, HITL patterns, and workflow authoring.
 
-**Install (interactive)**
+**Interactive install**
 
 ```
 /plugin marketplace add patrick204nqh/browserctl
 /plugin install browserctl@browserctl
 ```
 
-**Install (project settings** — commit `.claude/settings.json` to share with your team)
+**Project settings** — commit `.claude/settings.json` to share with your team:
 
 ```json
 {
@@ -93,36 +157,7 @@ browserctl ships as a Claude Code plugin. Install it once and Claude automatical
 }
 ```
 
-Once installed, Claude Code loads the `browserctl` skill automatically — no `/invoke` needed.
-
----
-
-## Quick Start
-
-```bash
-# 1. Start the daemon
-browserd &
-
-# 2. Open a named page
-browserctl open main --url https://the-internet.herokuapp.com/login
-
-# 3. Snapshot the page — get AI-friendly JSON with ref IDs
-browserctl snap main
-
-# 4. Interact using refs
-browserctl fill  main --ref e1 --value tomsmith
-browserctl fill  main --ref e2 --value SuperSecretPassword!
-browserctl click main --ref e3
-
-# 5. Observe
-browserctl url  main
-browserctl snap main --diff   # only what changed
-
-# 6. Done
-browserctl shutdown
-```
-
-→ [Full Getting Started guide](docs/getting-started.md)
+Once installed, the `browserctl` skill loads automatically.
 
 ---
 
@@ -135,7 +170,7 @@ Start multiple named instances for agent isolation:
 ```bash
 browserd --name agent-a &
 browserd --name agent-b &
-browserctl --daemon agent-a open main --url https://app.example.com
+browserctl --daemon agent-a page open main --url https://app.example.com
 ```
 
 The daemon shuts itself down after 30 minutes of inactivity.
@@ -162,12 +197,19 @@ The daemon shuts itself down after 30 minutes of inactivity.
 ```bash
 git clone https://github.com/patrick204nqh/browserctl
 cd browserctl
-bin/setup              # install deps + check for Chrome
+bin/setup              # brew bundle (macOS) + bundle install + Chrome check
 
 bundle exec rspec      # run tests
 bundle exec rubocop    # lint
+
+rake demo               # full pipeline: screenshots + browser GIF + terminal GIF
+rake demo:screenshots   # smoke test screenshots only
+rake demo:browser_gif   # browser animation only  (requires: ffmpeg)
+rake demo:terminal      # terminal GIF only        (requires: vhs)
 ```
 
+> Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example.
+
 ---
 
 ## Contributing

data/bin/browserctl

@@ -14,20 +14,19 @@ require "json"
 require "optimist"
 require "browserctl"
 require "browserctl/commands/cli_output"
-require "browserctl/commands/open_page"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
 require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
-require "browserctl/commands/watch"
 require "browserctl/commands/record"
-require "browserctl/commands/pause"
 require "browserctl/commands/resume"
 require "browserctl/commands/init"
-require "browserctl/commands/inspect"
-require "browserctl/commands/export_cookies"
-require "browserctl/commands/import_cookies"
-require "browserctl/commands/status"
+require "browserctl/commands/page"
+require "browserctl/commands/cookie"
+require "browserctl/commands/storage"
+require "browserctl/commands/session"
+require "browserctl/commands/daemon"
+require "browserctl/commands/workflow"
 
 def print_result(res)
   if res.is_a?(Hash) && res[:error]
@@ -37,59 +36,79 @@ def print_result(res)
   puts res.to_json
 end
 
-# rubocop:disable Metrics/MethodLength
 def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
     Setup:
-      init                                         Scaffold .browserctl/ in this project
-
-    Browser commands (require browserd running):
-      open   <page> [--url URL]                   Open or focus a named page
-      close  <page>                                Close a named page
-      pages                                        List open pages
-      goto   <page> <url>                          Navigate a page
-      fill   <page> <selector> <value>             Fill an input
-             <page> --ref <ref> --value <value>    Fill via snapshot ref
-      click  <page> <selector>                     Click an element
-             <page> --ref <ref>                    Click via snapshot ref
-      shot   <page> [--out PATH] [--full]          Take a screenshot
-      snap   <page> [--format ai|html] [--diff]    Snapshot DOM (default: ai)
-      url    <page>                                Print current URL
-      eval   <page> <expression>                   Evaluate JS expression
-      watch  <page> <selector> [--timeout N]       Wait for a selector to appear
-      pause   <page>                               Pause automation — browser stays live
-      resume  <page>                               Resume automation after manual action
-      inspect <page>                               Open Chrome DevTools for a named page
-      cookies <page>                               List all cookies as JSON
-      set-cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
-      clear-cookies <page>                         Clear all cookies for a page
-      export-cookies <page> <path>                 Export cookies to a JSON file
-      import-cookies <page> <path>                 Import cookies from a JSON file
-
-    Recording commands:
-      record start <name>            Start recording browser commands
-      record stop  [--out PATH]      Stop recording and save workflow
-      record status                  Show active recording name
-
-    Workflow commands:
-      run      <name|file> [--params file] [--key value ...]   Run a workflow
-      workflows                                List available workflows
-      describe <name>                          Describe a workflow
-
-    Daemon commands:
-      ping                   Check if browserd is alive
-      status                 Show daemon status, PID, and open pages
-      shutdown               Stop browserd
-
-    Options:
-      --daemon <name>    Connect to a named daemon instance
-      --version, -v      Print version and exit
+      init
+
+    Page:
+      page open <name> [--url URL]
+      page close <name>
+      page list
+      page focus <name>
+
+    Interaction (page is always first arg after verb):
+      navigate <page> <url>
+      fill     <page> <selector> <value>
+               <page> --ref <ref> --value <value>
+      click    <page> <selector>
+               <page> --ref <ref>
+      snapshot <page> [--format elements|html] [--diff]
+      screenshot <page> [--out PATH] [--full]
+      evaluate <page> <expression>
+      url      <page>
+      wait     <page> <selector> [--timeout N]
+      pause    <page> [--message MSG]
+      resume   <page>
+      devtools <page>
+
+    Cookie:
+      cookie list   <page>
+      cookie set    <page> <name> <value> --domain DOMAIN [--path /]
+      cookie delete <page>
+      cookie export <page> <path>
+      cookie import <page> <path>
+
+    Storage:
+      storage get    <page> <key> [--store local|session]
+      storage set    <page> <key> <value> [--store local|session]
+      storage export <page> <path> [--store local|session|all]
+      storage import <page> <path>
+      storage delete <page> [--store local|session|all]
+
+    Session:
+      session save   <name>
+      session load   <name>
+      session list
+      session delete <name>
+      session export <name> <path>
+      session import <path>
+
+    Recording:
+      record start <name>
+      record stop  [--out PATH]
+      record status
+
+    Workflow:
+      workflow run      <name|file> [--params file] [--key value ...]
+      workflow list
+      workflow describe <name>
+
+    Daemon:
+      daemon start  [--headed] [--name NAME]
+      daemon stop
+      daemon status
+      daemon ping
+      daemon list
+
+    Global options:
+      --daemon <name>    Connect to named or auto-indexed daemon (d1, d2, work, ...)
+      --version, -v
   USAGE
   exit 0
 end
-# rubocop:enable Metrics/MethodLength
 
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
@@ -105,70 +124,60 @@ usage if cmd.nil? || %w[-h --help help].include?(cmd)
 runner = Browserctl::Runner.new
 
 case cmd
-when "run"
-  name = args.shift or abort "usage: browserctl run <workflow_name|file.rb> [--key value ...]"
-  if File.exist?(name)
-    before = Browserctl::REGISTRY.keys.dup
-    load File.expand_path(name)
-    name = (Browserctl::REGISTRY.keys - before).first || File.basename(name, ".rb")
-  end
-  params_file_idx = args.index("--params")
-  file_params = {}
-  if params_file_idx
-    params_path = args.delete_at(params_file_idx + 1)
-    args.delete_at(params_file_idx)
-    begin
-      file_params = Browserctl::Runner.load_params_file(params_path)
-    rescue StandardError => e
-      abort "Error loading params file: #{e.message}"
-    end
-  end
-  cli_params = {}
-  args.each_slice(2) do |flag, val|
-    key = flag.sub(/\A--/, "").to_sym
-    cli_params[key] = val
-  end
-  params = file_params.merge(cli_params)
-  success = runner.run_workflow(name, **params)
-  exit(success ? 0 : 1)
-
-when "workflows"
-  list = runner.list_workflows
-  list.each { |w| puts "#{w[:name].ljust(24)} #{w[:desc]}" }
-
-when "describe"
-  name = args.shift or abort "usage: browserctl describe <workflow_name>"
-  puts JSON.pretty_generate(runner.describe_workflow(name))
-
-when "record" then Browserctl::Commands::Record.run(args)
-when "init"   then Browserctl::Commands::Init.run(args)
+when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
+when "record"   then Browserctl::Commands::Record.run(args)
+when "init"     then Browserctl::Commands::Init.run(args)
 
 else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
-  when "open"     then Browserctl::Commands::OpenPage.run(client, args)
-  when "close"    then print_result(client.close_page(args[0]))
-  when "pages"    then print_result(client.list_pages)
-  when "goto"     then print_result(client.goto(args[0], args[1]))
+  when "page"     then Browserctl::Commands::Page.run(client, args)
+  when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
+  when "storage"  then Browserctl::Commands::Storage.run(client, args)
+  when "session"  then Browserctl::Commands::Session.run(client, args)
+  when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
+  when "navigate" then print_result(client.navigate(args[0], args[1]))
   when "fill"     then Browserctl::Commands::Fill.run(client, args)
   when "click"    then Browserctl::Commands::Click.run(client, args)
-  when "shot"     then Browserctl::Commands::Screenshot.run(client, args)
-  when "snap"     then Browserctl::Commands::Snapshot.run(client, args)
+  when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
+  when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
+  when "evaluate" then print_result(client.evaluate(args[0], args[1]))
   when "url"      then print_result(client.url(args[0]))
-  when "eval"     then print_result(client.evaluate(args[0], args[1]))
-  when "watch"    then Browserctl::Commands::Watch.run(client, args)
-  when "pause"    then Browserctl::Commands::Pause.run(client, args)
-  when "resume"   then Browserctl::Commands::Resume.run(client, args)
-  when "inspect"       then Browserctl::Commands::Inspect.run(client, args)
-  when "cookies"         then print_result(client.cookies(args[0]))
-  when "set-cookie"      then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
-  when "clear-cookies"   then print_result(client.clear_cookies(args[0]))
-  when "export-cookies" then Browserctl::Commands::ExportCookies.run(client, args)
-  when "import-cookies" then Browserctl::Commands::ImportCookies.run(client, args)
-  when "ping"     then print_result(client.ping)
-  when "status"   then Browserctl::Commands::Status.run(client)
-  when "shutdown" then print_result(client.shutdown)
+  when "wait"
+    opts = Optimist.options(args) do
+      opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+    end
+    name = args.shift
+    selector = args.shift
+    abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
+    print_result(client.wait(name, selector, timeout: opts[:timeout]))
+  when "pause"
+    opts = Optimist.options(args) do
+      opt :message, "Message shown to human", type: :string, short: "-m"
+    end
+    name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
+    res = client.pause(name, message: opts[:message])
+    if res[:error]
+      warn "Error: #{res[:error]}"
+      exit 1
+    end
+    puts "Page '#{name}' paused. Browser is live — interact freely."
+    puts "(#{opts[:message]})" if opts[:message]
+    puts "When done: browserctl resume #{name}"
+  when "resume" then Browserctl::Commands::Resume.run(client, args)
+  when "devtools"
+    name = args.shift or abort "usage: browserctl devtools <page>"
+    res = client.devtools(name)
+    if res[:error]
+      warn "Error: #{res[:error]}"
+      exit 1
+    end
+    url = res[:devtools_url]
+    puts "Opening DevTools for '#{name}':"
+    puts "  #{url}"
+    opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+    system(opener, url)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end

data/bin/browserd

@@ -20,11 +20,17 @@ if opts[:name] && opts[:name] !~ /\A[a-zA-Z0-9_-]{1,64}\z/
   abort "Invalid daemon name #{opts[:name].inspect} — use only letters, digits, _ or -"
 end
 
-log_path = Browserctl.log_path(opts[:name])
+assigned_name = opts[:name] || Browserctl.next_daemon_name
+if assigned_name && !opts[:name]
+  warn "browserd: default slot taken — starting as '#{assigned_name}'"
+  warn "  to connect: browserctl --daemon #{assigned_name} <command>"
+end
+
+log_path = Browserctl.log_path(assigned_name)
 warn "browserd starting — log: #{log_path}"
 Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
 Browserctl::Server.new(
   headless: !opts[:headed],
-  socket_path: Browserctl.socket_path(opts[:name]),
-  pid_path: Browserctl.pid_path(opts[:name])
+  socket_path: Browserctl.socket_path(assigned_name),
+  pid_path: Browserctl.pid_path(assigned_name)
 ).run

data/bin/setup

@@ -1,14 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "==> Installing dependencies..."
+if [[ "$(uname)" == "Darwin" ]] && command -v brew &>/dev/null; then
+  echo "==> Installing Homebrew dependencies (Brewfile)..."
+  brew bundle --no-upgrade
+fi
+
+echo "==> Installing gem dependencies..."
 bundle install
 
 echo "==> Checking for Chrome/Chromium..."
 if ! command -v google-chrome &>/dev/null && ! command -v chromium-browser &>/dev/null && ! command -v chromium &>/dev/null; then
   echo "WARNING: Chrome/Chromium not found on PATH."
-  echo "         Install it before running browserctl."
-  echo "         macOS:  brew install --cask google-chrome"
+  echo "         macOS:  brew bundle  (includes google-chrome)"
   echo "         Ubuntu: sudo apt-get install -y chromium-browser"
 fi
 

data/examples/cloudflare_hitl.rb

@@ -7,7 +7,7 @@
 # pauses automation so a human can solve it in the live browser, then resumes.
 #
 # Run:
-#   browserctl run examples/cloudflare_hitl.rb --url https://example.com
+#   browserctl workflow run examples/cloudflare_hitl.rb --url https://example.com
 #
 # Note: modern Cloudflare often passes a real headed Chrome without challenge.
 # The pause/resume branch fires only when the challenge page is actually served
@@ -22,11 +22,11 @@ Browserctl.workflow "cloudflare_hitl" do
   param :selector, default: "body"
 
   step "open page" do
-    client.open_page("main")
+    open_page(:main)
   end
 
   step "navigate to target URL" do
-    res = client.goto("main", url)
+    res = client.navigate("main", url)
 
     if res[:challenge]
       $stdout.puts ""
@@ -54,12 +54,12 @@ Browserctl.workflow "cloudflare_hitl" do
   end
 
   step "wait for content and snapshot" do
-    page(:main).wait_for(selector, timeout: 15)
-    result = page(:main).snapshot(format: "ai")
+    page(:main).wait(selector, timeout: 15)
+    result = page(:main).snapshot(format: "elements")
     $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
   end
 
   step "close page" do
-    client.close_page("main")
+    close_page(:main)
   end
 end