browserctl 0.8.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd4d66743b0fba81220c113a7c99a09a94b216acee4d734a6e69ff76d27378b7
-  data.tar.gz: 60a8eb9469960e376c0d71a51bf801863e60d7a52e935578920ce227d8397e2b
+  metadata.gz: e27f4db200c9e26aaad474df3f55c1a7c91d602724d900d462a969ce4506ba9f
+  data.tar.gz: fba2acf3be3adf3a3a5ca9b42026abfcbfbeea7a8f8d48e51cd455b710fb403c
 SHA512:
-  metadata.gz: ceed28ff7dd8603bbaaee3ddaa5f6e65669a623aca423633a3ce08f64584064d37a400e461f8828260f245c34bba509452431c4af8ce2c672764778337a51075
-  data.tar.gz: 932c20041989b25fc3fc7d20aa23909edd1651a00500071fbe1ceb4b38edb7c0d64c033cd267f5a4ad240fb3d3f60020320f94f5c45ad9912f79a1960549d7e0
+  metadata.gz: 8ac208ae09f276efbf624ed297ef725d5144ec9c13624127f7f949491b0156f7a712ee22dc45cbe218addfe88227e7aa9676feaa105ef1813743b30ac3d5cd29
+  data.tar.gz: e5de1ed64d9d88e69c59a6de15bcfefaeb17b28cb578a8f6cddc2f5c97a8ee6d752c92efb6eff5d533d5923bfdcf6f29464a9f8bf06400953f6f874681c75689

data/CHANGELOG.md

@@ -10,6 +10,24 @@ 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.9.0](https://github.com/patrick204nqh/browserctl/compare/v0.8.4...v0.9.0) (2026-05-09)
+
+
+### Features
+
+* split skills into automate + feedback, refresh for v0.9 driver ([#80](https://github.com/patrick204nqh/browserctl/issues/80)) ([65c1a8e](https://github.com/patrick204nqh/browserctl/commit/65c1a8ee25a81aa5337fb8c447781efd8f6ade2e))
+* v0.9 browser-agnostic driver layer + Brave support ([#77](https://github.com/patrick204nqh/browserctl/issues/77)) ([0156c2d](https://github.com/patrick204nqh/browserctl/commit/0156c2defc105d49be038d108fa3da3ed1c4b402))
+
+## [0.8.4](https://github.com/patrick204nqh/browserctl/compare/v0.8.3...v0.8.4) (2026-05-01)
+
+
+### Bug Fixes
+
+* onboarding UX/DX improvements before v0.8.4 ([#73](https://github.com/patrick204nqh/browserctl/issues/73)) ([876dc58](https://github.com/patrick204nqh/browserctl/commit/876dc58c8408ffa5b4c861529db9f9d656204770))
+* OSS review improvements — security, community, and docs ([#76](https://github.com/patrick204nqh/browserctl/issues/76)) ([8e532f9](https://github.com/patrick204nqh/browserctl/commit/8e532f97d257b254fff601b7d2f5a38682f7795a))
+* **test:** clear localStorage before stale session save to prevent test pollution ([#72](https://github.com/patrick204nqh/browserctl/issues/72)) ([170b7be](https://github.com/patrick204nqh/browserctl/commit/170b7be68d4c4e366ad59c042500c3030886d70c))
+* UX/DX and docs improvements (M1–M4) ([#70](https://github.com/patrick204nqh/browserctl/issues/70)) ([747c17e](https://github.com/patrick204nqh/browserctl/commit/747c17e8821a0d1dde798ea8717ce3dd6cc33c63))
+
 ## [0.8.3](https://github.com/patrick204nqh/browserctl/compare/v0.8.2...v0.8.3) (2026-04-29)
 
 

data/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">browserctl</h1>
 
 <p align="center">
-  A browser daemon that keeps sessions alive between commands — for AI agents and iterative dev workflows.
+  The browser you delegate to your agents — with a pause button for the parts that still need you.
 </p>
 
 <p align="center">
@@ -29,29 +29,6 @@ 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
@@ -77,6 +54,11 @@ browserctl click main --ref e3
 browserctl url main
 browserctl snapshot main --diff   # only what changed
 
+# Session persistence: save now, pick up later
+browserctl session save my-session
+# On a fresh daemon tomorrow: `browserctl session load my-session`
+# → tabs restored, cookies intact, no re-login needed
+
 # 7. Done
 browserctl daemon stop
 ```
@@ -85,6 +67,29 @@ 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>
+
+---
+
 ## 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.
@@ -119,11 +124,19 @@ Most automation tools are stateless — every script spins up a fresh browser an
 
 **Requirements:** Ruby >= 3.3 · Chrome or Chromium installed
 
+**macOS (Homebrew — recommended)**
+
+```bash
+brew install patrick204nqh/tap/browserctl
+```
+
+**RubyGems**
+
 ```bash
 gem install browserctl
 ```
 
-Or in your `Gemfile`:
+Or in your `Gemfile` (for projects using the client API directly):
 
 ```ruby
 gem "browserctl"
@@ -182,10 +195,13 @@ The daemon shuts itself down after 30 minutes of inactivity.
 | | |
 |---|---|
 | [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |
+| [Agent Integration](docs/guides/agent-integration.md) | Call browserctl from Python, shell, or Anthropic tool-use agents |
 | [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |
 | [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
+| [Examples](examples/) | Runnable scripts: session reuse, Cloudflare HITL, and more |
 | [Command Reference](docs/reference/commands.md) | Every command and flag |
 | [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |
+| [CHANGELOG](CHANGELOG.md) | Release history |
 | [Product](docs/product.md) | What browserctl is and who it's for |
 | [Vision & Roadmap](docs/vision.md) | Philosophy and release roadmap |
 | [vs. agent-browser](docs/vs-agent-browser.md) | How browserctl differs from Vercel's agent-browser |
@@ -219,3 +235,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md)
 ## License
 
 [MIT](LICENSE)
+
+---
+
+Built by [Patrick](https://github.com/patrick204nqh) — I built this because I was building AI agents that needed authenticated web sessions, and every automation tool I tried restarted the browser between runs.

data/bin/browserd

@@ -9,17 +9,24 @@ require "browserctl/logger"
 require "browserctl/server"
 require "browserctl/version"
 
+SUPPORTED_BROWSERS = %w[chrome chromium brave].freeze
+
 opts = Optimist.options do
   version "browserd #{Browserctl::VERSION}"
   opt :headed,    "Run with a visible browser window",        default: false,  short: "-H"
   opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", short: "-l", type: :string
   opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
+  opt :browser,   "Browser to use: chrome, chromium, brave",  default: "chrome", short: "-b", type: :string
 end
 
 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
 
+unless SUPPORTED_BROWSERS.include?(opts[:browser])
+  abort "Unsupported browser #{opts[:browser].inspect} — choose one of: #{SUPPORTED_BROWSERS.join(', ')}"
+end
+
 assigned_name = opts[:name] || Browserctl.next_daemon_name
 if assigned_name && !opts[:name]
   warn "browserd: default slot taken — starting as '#{assigned_name}'"
@@ -29,8 +36,13 @@ 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(assigned_name),
-  pid_path: Browserctl.pid_path(assigned_name)
-).run
+begin
+  Browserctl::Server.new(
+    headless: !opts[:headed],
+    browser: opts[:browser],
+    socket_path: Browserctl.socket_path(assigned_name),
+    pid_path: Browserctl.pid_path(assigned_name)
+  ).run
+rescue Browserctl::BrowserNotFound => e
+  abort e.message
+end

data/examples/session_reuse.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Demonstrates the authenticate-once, reuse-forever pattern.
+#
+# The first run (no saved session) invokes `login_once` to authenticate,
+# which saves the session. Every subsequent run loads the saved session
+# directly — no re-authentication needed.
+#
+# `expired_if:` detects when the saved session exists but server-side auth
+# has lapsed (rotated cookie, token TTL), and automatically re-authenticates.
+#
+# Run:
+#   browserctl workflow run examples/session_reuse.rb \
+#     --app_url https://the-internet.herokuapp.com \
+#     --username tomsmith \
+#     --password "SuperSecretPassword!"
+#
+# On the first run: authenticates and saves the session.
+# On subsequent runs: loads the session and skips the login page entirely.
+
+# --- Step 1: define the login workflow (run once, triggered automatically on missing/expired session) ---
+
+Browserctl.workflow "session_reuse/login_once" do
+  desc "Authenticate and save session — called automatically by session_reuse when needed"
+
+  param :app_url,  required: true
+  param :username, required: true
+  param :password, required: true, secret: true
+
+  step "open login page" do
+    open_page(:main, url: "#{app_url}/login")
+  end
+
+  step "fill and submit credentials" do
+    page(:main).fill("input#username", username)
+    page(:main).fill("input#password", password)
+    page(:main).click("button[type=submit]")
+  end
+
+  step "verify login succeeded" do
+    assert page(:main).url.include?("/secure"), "login failed — still on login page"
+  end
+
+  step "save authenticated session" do
+    save_session("session_reuse_demo")
+    puts "  ✓ Session saved — future runs will skip this step"
+  end
+end
+
+# --- Step 2: the main workflow that reuses the saved session ---
+
+Browserctl.workflow "session_reuse" do
+  desc "Authenticate once, reuse forever — demonstrates load_session with fallback and expired_if"
+
+  param :app_url,  default: "https://the-internet.herokuapp.com"
+  param :username, default: "tomsmith"
+  param :password, default: "SuperSecretPassword!", secret: true
+
+  step "restore session or log in" do
+    load_session("session_reuse_demo",
+                 fallback: "session_reuse/login_once",
+                 expired_if: lambda {
+                   page(:main).navigate("#{app_url}/secure")
+                   !page(:main).url.include?("/secure")
+                 })
+    puts "  ✓ Session ready — authenticated as #{username}"
+  end
+
+  step "do authenticated work" do
+    page(:main).navigate("#{app_url}/secure")
+    heading = page(:main).evaluate("document.querySelector('h2')?.textContent?.trim()")
+    assert heading&.include?("Secure Area"), "expected to be in secure area, got: #{heading.inspect}"
+    puts "  ✓ Landed in secure area without re-authenticating"
+  end
+end

data/examples/the_internet/login.rb

@@ -20,14 +20,14 @@ Browserctl.workflow "the_internet/login" do
 
   step "verify secure area" do
     assert page(:main).url.include?("/secure"), "expected redirect to /secure"
-    flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
+    flash = page(:main).evaluate("document.querySelector('.flash.success')?.innerText?.trim()")
     assert flash&.include?("You logged into a secure area!"), "expected success flash, got: #{flash.inspect}"
     page(:main).screenshot(path: screenshot_path)
   end
 
   step "logout and verify" do
     page(:main).click("a[href='/logout']")
-    flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
+    flash = page(:main).evaluate("document.querySelector('.flash.success')?.innerText?.trim()")
     assert flash&.include?("You logged out"), "expected logout flash, got: #{flash.inspect}"
   end
 end

data/lib/browserctl/client.rb

@@ -18,7 +18,7 @@ module Browserctl
       Recording.append(cmd, **params) if result[:ok]
       result
     rescue Errno::ENOENT, Errno::ECONNREFUSED
-      raise "browserd is not running — start it with: browserd"
+      raise DaemonUnavailableError, "browserd is not running — start it with: browserd"
     end
 
     # Opens or focuses a named browser page.
@@ -234,27 +234,41 @@ module Browserctl
     # @param name [String] logical page name
     # @param key [String] key name e.g. "Enter", "Tab", "Escape", "ArrowDown"
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def press(name, key)          = call("press",  name: name, key: key)
+    def press(name, key) = call("press", name: name, key: key)
 
     # Moves the mouse to the centre of the element matched by selector.
     # @param name [String] logical page name
     # @param selector [String] CSS selector
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def hover(name, selector)     = call("hover",  name: name, selector: selector)
+    def hover(name, selector = nil, ref: nil)
+      raise ArgumentError, "hover: provide selector or ref:" unless selector || ref
+
+      call("hover", name: name, selector: selector, ref: ref)
+    end
 
     # Sets a file-input element to the given file path.
     # @param name [String] logical page name
-    # @param selector [String] CSS selector for the file input
-    # @param path [String] absolute or relative file path
+    # @param selector [String, nil] CSS selector for the file input
+    # @param path [String, nil] absolute or relative file path
+    # @param ref [String, nil] element ref from a prior snapshot
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def upload(name, selector, path) = call("upload", name: name, selector: selector, path: path)
+    def upload(name, selector = nil, path = nil, ref: nil)
+      raise ArgumentError, "upload: provide selector or ref:" unless selector || ref
+
+      call("upload", name: name, selector: selector, ref: ref, path: path)
+    end
 
     # Sets a <select> element's value and fires a change event.
     # @param name [String] logical page name
-    # @param selector [String] CSS selector for the select element
-    # @param value [String] option value to select
+    # @param selector [String, nil] CSS selector for the select element
+    # @param value [String, nil] option value to select
+    # @param ref [String, nil] element ref from a prior snapshot
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def select(name, selector, value) = call("select", name: name, selector: selector, value: value)
+    def select(name, selector = nil, value = nil, ref: nil)
+      raise ArgumentError, "select: provide selector or ref:" unless selector || ref
+
+      call("select", name: name, selector: selector, ref: ref, value: value)
+    end
 
     # Pre-registers a one-shot handler to accept the next JS dialog on a page.
     # @param name [String] logical page name

data/lib/browserctl/commands/daemon.rb

@@ -14,7 +14,13 @@ module Browserctl
       def self.run(client, args)
         sub = args.shift or abort USAGE
         case sub
-        when "ping"   then print_result(client.ping)
+        when "ping"
+          begin
+            print_result(client.ping)
+          rescue Browserctl::DaemonUnavailableError => e
+            puts JSON.generate({ ok: false, daemon: "offline", error: e.message })
+            exit 1
+          end
         when "status" then run_status(client)
         when "start"  then run_start(args)
         when "stop"   then print_result(client.shutdown)
@@ -36,9 +42,7 @@ module Browserctl
           protocol_version: ping[:protocol_version],
           pages: page_info
         )
-      rescue RuntimeError => e
-        raise unless e.message.include?("browserd is not running")
-
+      rescue Browserctl::DaemonUnavailableError => e
         puts JSON.pretty_generate(daemon: "offline", error: e.message)
         exit 1
       end
@@ -67,7 +71,7 @@ module Browserctl
           next unless status&.dig(:ok)
 
           { name: display_name, pid: status[:pid], pages: (client.page_list[:pages] || []).length }
-        rescue RuntimeError
+        rescue Browserctl::DaemonUnavailableError, RuntimeError
           nil
         end.compact
         puts({ daemons: rows }.to_json)

data/lib/browserctl/commands/record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
 require "optimist"
 require "browserctl/recording"
 
@@ -29,8 +30,7 @@ module Browserctl
           abort "Invalid recording name #{name.inspect} — use only letters, digits, _ or -" \
             unless name =~ /\A[a-zA-Z0-9_-]{1,64}\z/
           Recording.start(name)
-          puts "Recording started: #{name}"
-          puts "Run browser commands, then: browserctl record stop"
+          puts JSON.generate({ ok: true, name: name })
         end
 
         def run_stop(args)
@@ -42,13 +42,12 @@ module Browserctl
           out  = opts[:out] || File.join(".browserctl/workflows", "#{name}.rb")
           FileUtils.mkdir_p(File.dirname(out))
           Recording.generate_workflow(name, output_path: out)
-          puts "Workflow saved: #{out}"
-          puts "Run with: browserctl workflow run #{name}"
+          puts JSON.generate({ ok: true, name: name, path: out })
         end
 
         def run_status
           active = Recording.active
-          puts active ? "Active recording: #{active}" : "No active recording."
+          puts JSON.generate({ active: active })
         end
       end
     end

data/lib/browserctl/commands/session.rb

@@ -61,6 +61,7 @@ module Browserctl
         name    = args.shift or abort "usage: browserctl session export <name> <path> [--encrypt]"
         dest    = args.shift or abort "usage: browserctl session export <name> <path> [--encrypt]"
 
+        Browserctl::Session.validate_name!(name)
         session_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions", name)
         abort "session '#{name}' not found" unless Dir.exist?(session_dir)
 
@@ -85,6 +86,8 @@ module Browserctl
         sessions_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions")
         FileUtils.mkdir_p(sessions_dir)
 
+        before = Dir[File.join(sessions_dir, "*/")].map { |p| File.basename(p) }
+
         if encrypted_zip?(zip_path)
           passphrase = prompt_passphrase
           decrypt_import(zip_path, sessions_dir, passphrase)
@@ -93,7 +96,10 @@ module Browserctl
           Process.wait(pid)
         end
 
-        puts({ ok: true }.to_json)
+        after = Dir[File.join(sessions_dir, "*/")].map { |p| File.basename(p) }
+        name = (after - before).first
+
+        puts({ ok: true, name: name }.to_json)
       end
 
       # --- private helpers ---

data/lib/browserctl/commands/workflow.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "cli_output"
 
 module Browserctl
@@ -52,7 +53,7 @@ module Browserctl
 
       def self.run_list(runner)
         list = runner.list_workflows
-        list.each { |w| puts "#{w[:name].ljust(24)} #{w[:desc]}" }
+        puts JSON.generate({ workflows: list.map { |w| { name: w[:name], desc: w[:desc] } } })
       end
 
       def self.run_describe(runner, args)

data/lib/browserctl/detectors.rb

@@ -11,7 +11,7 @@ module Browserctl
 
     # Returns true if the page appears to be showing a Cloudflare challenge.
     # Checks both the current URL and the page body for known Cloudflare signals.
-    # @param page [Ferrum::Page] the browser page to inspect
+    # @param page [#current_url, #body] the browser page to inspect
     # @return [Boolean]
     def self.cloudflare?(page)
       url  = page.current_url.to_s

data/lib/browserctl/driver/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Driver
+    class Base
+      def create_page   = raise NotImplementedError, "#{self.class.name}#create_page not implemented"
+      def quit          = raise NotImplementedError, "#{self.class.name}#quit not implemented"
+      def headed?       = raise NotImplementedError, "#{self.class.name}#headed? not implemented"
+      def supports?(_)  = false
+      def devtools_info(_page) = raise NotImplementedError, "#{self.class.name}#devtools_info not implemented"
+    end
+  end
+end

data/lib/browserctl/driver/cdp.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "ferrum"
+require_relative "base"
+require_relative "cdp_page"
+require_relative "../errors"
+
+module Browserctl
+  module Driver
+    class CDP < Base
+      BRAVE_PATHS = {
+        darwin: [
+          "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+          File.expand_path("~/Applications/Brave Browser.app/Contents/MacOS/Brave Browser")
+        ],
+        linux: [
+          "/usr/bin/brave-browser",
+          "/usr/bin/brave",
+          "/snap/bin/brave"
+        ],
+        windows: [
+          "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe",
+          "C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe"
+        ]
+      }.freeze
+
+      def initialize(headless: true, browser: "chrome") # rubocop:disable Lint/MissingSuper
+        @headless = headless
+        @browser  = browser
+        @ferrum   = Ferrum::Browser.new(**ferrum_options)
+      end
+
+      def create_page
+        CDPPage.new(@ferrum.create_page)
+      end
+
+      def quit
+        @ferrum.quit
+      end
+
+      def headed?
+        !@headless
+      end
+
+      def supports?(capability)
+        capability == :devtools
+      end
+
+      def devtools_info(page)
+        port      = @ferrum.process.port
+        target_id = page.target_id
+        { port: port, target_id: target_id }
+      end
+
+      private
+
+      def ferrum_options
+        opts = {
+          timeout: 30,
+          process_timeout: 30,
+          browser_options: { "disable-dev-shm-usage" => nil, "disable-gpu" => nil }
+        }
+
+        if @browser != "chrome" && (path = resolve_browser_path)
+          opts[:browser_path] = path
+        end
+
+        if ENV["CI"] || ENV["BROWSERCTL_NO_SANDBOX"]
+          Browserctl.logger.warn "no-sandbox enabled (CI or BROWSERCTL_NO_SANDBOX set)"
+          opts[:browser_options]["no-sandbox"] = nil
+        end
+
+        opts[:headless] = @headless
+        opts
+      end
+
+      def resolve_browser_path
+        case @browser
+        when "chromium"
+          resolve_chromium_path
+        when "brave"
+          resolve_brave_path
+        else
+          raise ArgumentError, "Unknown browser: #{@browser.inspect}"
+        end
+      end
+
+      def resolve_chromium_path
+        env_override("CHROMIUM_PATH")
+        # Returns nil when no override — Ferrum finds Chromium automatically on most platforms.
+      end
+
+      def resolve_brave_path
+        override = env_override("BRAVE_PATH")
+        return override if override
+
+        platform = detect_platform
+        candidates = BRAVE_PATHS.fetch(platform, [])
+        path = candidates.find { |p| File.executable?(p) }
+        unless path
+          raise BrowserNotFound,
+                "Brave browser not found. Install Brave or set BRAVE_PATH to its executable."
+        end
+
+        path
+      end
+
+      def env_override(var)
+        value = ENV.fetch(var, nil)
+        return nil if value.nil? || value.empty?
+        raise BrowserNotFound, "#{var}=#{value} is not an executable file" unless File.executable?(value)
+
+        value
+      end
+
+      def detect_platform
+        case RUBY_PLATFORM
+        when /darwin/              then :darwin
+        when /mingw|mswin|windows/ then :windows
+        else                            :linux
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/driver/cdp_page.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Browserctl
+  module Driver
+    # Wraps a Ferrum::Page so handlers receive a driver-namespaced object instead of
+    # a raw Ferrum type. Currently a transparent delegator — the seam exists so future
+    # CDP-specific behaviour (capability checks, instrumentation) can live here without
+    # touching every handler. Delete this class if no override lands by the next driver.
+    class CDPPage < SimpleDelegator
+    end
+  end
+end

data/lib/browserctl/driver.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "driver/base"
+require_relative "driver/cdp_page"
+require_relative "driver/cdp"

data/lib/browserctl/errors.rb

@@ -21,8 +21,10 @@ module Browserctl
   class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
   class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
   class TimeoutError     < Error; def self.default_code = "timeout"            end
-  class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+  class KeyNotFound < Error; def self.default_code = "key_not_found" end
+  class DaemonUnavailableError < Error; def self.default_code = "daemon_unavailable" end
+  class BrowserNotFound < Error; def self.default_code = "browser_not_found" end
 
-  class WorkflowError < StandardError; end
-  class SecretResolverError < WorkflowError; end
+  class WorkflowError < Error; def self.default_code = "workflow_error" end
+  class SecretResolverError < WorkflowError; def self.default_code = "secret_resolver_error" end
 end

data/lib/browserctl/runner.rb

@@ -67,7 +67,8 @@ module Browserctl
     end
 
     def fetch_workflow(name)
-      return Browserctl.lookup_workflow(name.to_s) if Browserctl.lookup_workflow(name.to_s)
+      wf = Browserctl.lookup_workflow(name.to_s)
+      return wf if wf
 
       validate_name!(name)
       load_workflow_file(name)

data/lib/browserctl/secret_resolvers/macos_keychain.rb

@@ -8,7 +8,7 @@ module Browserctl
       def self.scheme = "keychain"
 
       def available?
-        RUBY_PLATFORM.include?("darwin") && system("which security > /dev/null 2>&1")
+        RUBY_PLATFORM.include?("darwin") && system("which", "security", out: File::NULL, err: File::NULL)
       end
 
       def resolve(reference)

data/lib/browserctl/secret_resolvers/one_password.rb

@@ -8,10 +8,16 @@ module Browserctl
       def self.scheme = "op"
 
       def available?
-        system("which op > /dev/null 2>&1")
+        system("which", "op", out: File::NULL, err: File::NULL)
       end
 
+      SAFE_REFERENCE = %r{\A[a-zA-Z0-9._\-/]+\z}
+
       def resolve(reference)
+        unless SAFE_REFERENCE.match?(reference)
+          raise SecretResolverError, "invalid 1Password reference format: #{reference.inspect}"
+        end
+
         result, status = Open3.capture2("op", "read", "op://#{reference}")
         raise SecretResolverError, "1Password item not found: op://#{reference}" unless status.success?
 

data/lib/browserctl/server/command_dispatcher.rb

@@ -73,9 +73,9 @@ module Browserctl
     SCREENSHOT_ROOTS = [SCREENSHOT_DIR, File.expand_path(".")].freeze
     SCREENSHOT_EXTS  = %w[.png .jpg .jpeg].freeze
 
-    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
+    def initialize(pages, driver, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
       @pages            = pages
-      @browser          = browser
+      @driver           = driver
       @snapshot_builder = snapshot_builder
       @global_mutex     = global_mutex
       @kv_store         = {}

data/lib/browserctl/server/handlers/devtools.rb

@@ -7,11 +7,14 @@ module Browserctl
         private
 
         def cmd_devtools(req)
+          return { error: "devtools is not supported by this driver" } unless @driver.supports?(:devtools)
+
           session = @global_mutex.synchronize { @pages[req[:name]] }
           return { error: "no page named '#{req[:name]}'" } unless session
 
-          port      = @browser.process.port
-          target_id = session.page.target_id
+          info      = @driver.devtools_info(session.page)
+          port      = info[:port]
+          target_id = info[:target_id]
           devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
                          "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
           { ok: true, devtools_url: devtools_url }

data/lib/browserctl/server/handlers/interaction.rb

@@ -16,15 +16,18 @@ module Browserctl
 
         def cmd_hover(req)
           with_page(req[:name]) do |session|
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
             coords = session.page.evaluate(
               "(function(sel) {   " \
               "var el = document.querySelector(sel);   " \
               "if (!el) return null;   " \
               "var r = el.getBoundingClientRect();   " \
               "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
-              "})(#{req[:selector].to_json})"
+              "})(#{sel.to_json})"
             )
-            return { error: "selector not found: #{req[:selector]}" } unless coords
+            return { error: "selector not found: #{sel}" } unless coords
 
             session.page.mouse.move(x: coords["x"], y: coords["y"])
             { ok: true }
@@ -36,8 +39,11 @@ module Browserctl
           return { error: "file not found: #{path}" } unless File.exist?(path)
 
           with_page(req[:name]) do |session|
-            el = session.page.at_css(req[:selector])
-            return { error: "selector not found: #{req[:selector]}" } unless el
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            el = session.page.at_css(sel)
+            return { error: "selector not found: #{sel}" } unless el
 
             el.select_file(path)
             { ok: true }
@@ -46,8 +52,11 @@ module Browserctl
 
         def cmd_select(req)
           with_page(req[:name]) do |session|
-            el = session.page.at_css(req[:selector])
-            return { error: "selector not found: #{req[:selector]}" } unless el
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            el = session.page.at_css(sel)
+            return { error: "selector not found: #{sel}" } unless el
 
             el.evaluate(
               "this.value = #{req[:value].to_json}; " \

data/lib/browserctl/server/handlers/page_lifecycle.rb

@@ -8,7 +8,7 @@ module Browserctl
 
         def cmd_page_open(req)
           session = @global_mutex.synchronize do
-            @pages[req[:name]] ||= PageSession.new(@browser.create_page)
+            @pages[req[:name]] ||= PageSession.new(@driver.create_page)
           end
           session.page.go_to(req[:url]) if req[:url]
           { ok: true, name: req[:name] }
@@ -25,9 +25,7 @@ module Browserctl
         end
 
         def cmd_page_focus(req)
-          unless @browser.options.headless == false
-            return { error: "page focus requires headed mode — start browserd with --headed" }
-          end
+          return { error: "page focus requires headed mode — start browserd with --headed" } unless @driver.headed?
 
           with_page(req[:name]) do |session|
             session.page.activate

data/lib/browserctl/server/handlers/session.rb

@@ -47,7 +47,7 @@ module Browserctl
             if existing
               existing.page.go_to(page_data[:url])
             else
-              new_page = @browser.create_page
+              new_page = @driver.create_page
               new_page.go_to(page_data[:url])
               @global_mutex.synchronize { @pages[page_name.to_s] = PageSession.new(new_page) }
             end
@@ -61,7 +61,7 @@ module Browserctl
           data[:local_storage].each do |origin, keys|
             next if keys.empty?
 
-            tmp_page = @browser.create_page
+            tmp_page = @driver.create_page
             begin
               tmp_page.go_to(origin)
               keys.each do |k, v|
@@ -75,7 +75,7 @@ module Browserctl
 
           { ok: true, cookies: cookie_count, pages: data[:metadata][:pages].length,
             local_storage_keys: ls_key_count }
-        rescue RuntimeError => e
+        rescue Browserctl::Error, ArgumentError, JSON::ParserError, RuntimeError => e
           { error: e.message }
         end
 

data/lib/browserctl/server.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require "ferrum"
 require "socket"
 require "json"
 require "fileutils"
 require "timeout"
 require_relative "constants"
 require_relative "logger"
+require_relative "driver"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
 require_relative "server/page_session"
 
 module Browserctl
   class Server
-    def initialize(headless: true, socket_path: SOCKET_PATH, pid_path: PID_PATH)
+    def initialize(headless: true, browser: "chrome", socket_path: SOCKET_PATH, pid_path: PID_PATH)
       @socket_path = socket_path
       @pid_path    = pid_path
-      prepare_runtime(headless)
-      @dispatcher = CommandDispatcher.new(@pages, @browser, global_mutex: @mutex)
+      prepare_runtime(headless, browser)
+      @dispatcher = CommandDispatcher.new(@pages, @driver, global_mutex: @mutex)
     end
 
     def run
@@ -33,21 +33,12 @@ module Browserctl
 
     private
 
-    def prepare_runtime(headless)
+    def prepare_runtime(headless, browser)
       FileUtils.mkdir_p(File.dirname(@socket_path))
-      @browser = init_browser(headless)
+      @driver = Driver::CDP.new(headless: headless, browser: browser)
       init_state
     end
 
-    def init_browser(headless)
-      Ferrum::Browser.new(headless: headless, **ferrum_options)
-    end
-
-    def ferrum_options
-      { timeout: 30, process_timeout: 30,
-        browser_options: { "no-sandbox" => nil, "disable-dev-shm-usage" => nil, "disable-gpu" => nil } }
-    end
-
     def init_state
       @pages     = {}
       @last_used = Time.now
@@ -114,7 +105,7 @@ module Browserctl
     def teardown(idle, server)
       idle&.kill
       quietly { server&.close }
-      quietly { Timeout.timeout(5) { @browser.quit } }
+      quietly { Timeout.timeout(5) { @driver.quit } }
       quietly { File.unlink(@socket_path) }
       quietly { File.unlink(@pid_path) }
     end
@@ -125,7 +116,7 @@ module Browserctl
 
     def quietly
       yield
-    rescue Exception
+    rescue StandardError
       nil
     end
   end

data/lib/browserctl/session.rb

@@ -162,7 +162,7 @@ module Browserctl
     private_class_method :keychain_fetch
 
     def self.keychain_available?
-      RUBY_PLATFORM.include?("darwin") && system("which security > /dev/null 2>&1")
+      RUBY_PLATFORM.include?("darwin") && system("which", "security", out: File::NULL, err: File::NULL)
     end
     private_class_method :keychain_available?
 
@@ -187,7 +187,7 @@ module Browserctl
     private_class_method :decrypt_json
 
     def self.write_json(path, data)
-      File.write(path, JSON.generate(data))
+      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(data)) }
     end
     private_class_method :write_json
 

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.8.3"
+  VERSION = "0.9.0"
 end

data/lib/browserctl/workflow.rb

@@ -104,14 +104,28 @@ module Browserctl
       raise WorkflowError, msg unless condition
     end
 
+    def compose(*)
+      raise WorkflowError,
+            "`compose` must be called at the workflow definition level, not inside a step block. " \
+            "Did you mean `invoke`?"
+    end
+
     private
 
     def validate_expired_if!(expired_if)
-      return unless expired_if && !expired_if.lambda?
+      return unless expired_if
+
+      unless expired_if.lambda?
+        raise ArgumentError,
+              "expired_if: must be a lambda (-> { }), not a Proc — " \
+              "bare return inside a Proc unwinds the caller"
+      end
+
+      return if expired_if.arity.zero?
 
       raise ArgumentError,
-            "expired_if: must be a lambda (-> { }), not a Proc — " \
-            "bare return inside a Proc unwinds the caller"
+            "expired_if: lambda must take zero arguments (got #{expired_if.arity}) — " \
+            "use -> { page(:name).url... } to access pages via the workflow context"
     end
 
     def call_expired_if(expired_if, session_name)
@@ -176,9 +190,16 @@ module Browserctl
       @client = client
     end
 
-    def navigate(url)             = unwrap @client.navigate(@name, url)
-    def fill(sel, val)            = unwrap @client.fill(@name, sel, val)
-    def click(sel)                = unwrap @client.click(@name, sel)
+    def navigate(url) = unwrap @client.navigate(@name, url)
+
+    def fill(selector = nil, value = nil, ref: nil)
+      unwrap @client.fill(@name, selector, value, ref: ref)
+    end
+
+    def click(selector = nil, ref: nil)
+      unwrap @client.click(@name, selector, ref: ref)
+    end
+
     def snapshot(**)              = unwrap @client.snapshot(@name, **)
     def screenshot(**)            = unwrap @client.screenshot(@name, **)
     def wait(sel, timeout: 30)    = unwrap @client.wait(@name, sel, timeout: timeout)
@@ -195,10 +216,20 @@ module Browserctl
       unwrap @client.storage_set(@name, key, value, store: store)
     end
 
-    def press(key)               = unwrap @client.press(@name, key)
-    def hover(selector)          = unwrap @client.hover(@name, selector)
-    def upload(selector, path)   = unwrap @client.upload(@name, selector, path)
-    def select(selector, value)  = unwrap @client.select(@name, selector, value)
+    def press(key) = unwrap @client.press(@name, key)
+
+    def hover(selector = nil, ref: nil)
+      unwrap @client.hover(@name, selector, ref: ref)
+    end
+
+    def upload(selector = nil, path = nil, ref: nil)
+      unwrap @client.upload(@name, selector, path, ref: ref)
+    end
+
+    def select(selector = nil, value = nil, ref: nil)
+      unwrap @client.select(@name, selector, value, ref: ref)
+    end
+
     def dialog_accept(text: nil) = unwrap @client.dialog_accept(@name, text: text)
     def dialog_dismiss           = unwrap @client.dialog_dismiss(@name)
 
@@ -260,7 +291,7 @@ module Browserctl
       (defn.retry_count + 1).times do
         execute_block(ctx, defn)
         return StepResult.new(name: defn.label, ok: true)
-      rescue WorkflowError, StandardError => e
+      rescue StandardError => e
         last_error = e
       end
       StepResult.new(name: defn.label, ok: false, error: last_error.message)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.9.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 description: Named browser sessions, Ruby workflow DSL, and a token-efficient DOM
-  snapshot format. Built on Ferrum (Chrome DevTools Protocol).
+  snapshot format. Built on a browser-agnostic driver layer (Ferrum/CDP backend).
 email:
 - patrick204nqh@gmail.com
 executables:
@@ -139,6 +139,7 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
+- examples/session_reuse.rb
 - examples/test_automation_practices/advanced/ab_testing.rb
 - examples/test_automation_practices/advanced/broken_images.rb
 - examples/test_automation_practices/advanced/file_download.rb
@@ -184,6 +185,10 @@ files:
 - lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
 - lib/browserctl/detectors.rb
+- lib/browserctl/driver.rb
+- lib/browserctl/driver/base.rb
+- lib/browserctl/driver/cdp.rb
+- lib/browserctl/driver/cdp_page.rb
 - lib/browserctl/errors.rb
 - lib/browserctl/logger.rb
 - lib/browserctl/policy.rb
@@ -221,6 +226,7 @@ metadata:
   source_code_uri: https://github.com/patrick204nqh/browserctl
   changelog_uri: https://github.com/patrick204nqh/browserctl/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/patrick204nqh/browserctl/issues
+  documentation_uri: https://github.com/patrick204nqh/browserctl/tree/main/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []