browserctl 0.8.2 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5145a9c65fc1dc92bd238aecd15c672286dfa41005333dbaa1e6a613834c9fc
-  data.tar.gz: 0f1c56d87a58b41fbdea2e3ec1abf211bcf08a3677348d34565301f15bb76e96
+  metadata.gz: dbfd167f7b8ad961fa91c544eb2636fa1bdc200b40f4738bbf27d9fa5a835cae
+  data.tar.gz: d3fdf8af59edd0c73ea1c415926baefbbe22405343898b46c60b1a18f2e623ac
 SHA512:
-  metadata.gz: 162679d64a18bfb241ef1312a7ecfac12cc312407ccd598bc0741c2f985d1754dbdcbe00112ee2cc522a3987b88d8cd34dd4799b48651238efb548348123d58f
-  data.tar.gz: 710809a3eb707ad0f1f7300c77cb4b6cfdc4f631dc7f1e02b4b426262164b061d7008ba1901e501483e85a09ecb7be63fd60afa08dba9039b79670e711532fa4
+  metadata.gz: c46b3611cc0a29633558cf0547cd532cefcf4dbecddbbc62e348af27b9c4e5eec498f00bb90892e84a4665281cad57b20e1a73b14b50cff2e579f222301cf549
+  data.tar.gz: f5b8451f0e909212acf63e1eecc49ca607a7d095ea44e4fd4ae42e9b2509b199b7ed35a7158a83764b825dfb6747970e20fe137be465063f50a42c39508bfb68

data/CHANGELOG.md

@@ -10,6 +10,28 @@ 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.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)
+
+
+### Features
+
+* expired_if: on load_session — detect stale sessions and auto-recover ([#67](https://github.com/patrick204nqh/browserctl/issues/67)) ([c6a4674](https://github.com/patrick204nqh/browserctl/commit/c6a467439835373165b1323c4aad6144388533be))
+
+
+### Miscellaneous Chores
+
+* pin next release to 0.8.3 ([#69](https://github.com/patrick204nqh/browserctl/issues/69)) ([a017e3c](https://github.com/patrick204nqh/browserctl/commit/a017e3c3b464060ced2ecd4d76fa04049f40e46a))
+
 ## [0.8.2](https://github.com/patrick204nqh/browserctl/compare/v0.8.1...v0.8.2) (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/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
@@ -270,8 +284,8 @@ module Browserctl
     # Saves the current browser state (cookies, localStorage, open pages) to a named session.
     # @param session_name [String] name for the saved session
     # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
-    def session_save(session_name)
-      call("session_save", session_name: session_name)
+    def session_save(session_name, encrypt: false)
+      call("session_save", session_name: session_name, encrypt: encrypt)
     end
 
     # Restores a previously saved session into the running daemon.

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/errors.rb

@@ -21,8 +21,9 @@ 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 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/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/session.rb

@@ -32,7 +32,8 @@ module Browserctl
                         created_at: now, updated_at: now, pages: pages_meta },
             cookies: cookies,
             local_storage: local_storage,
-            session_storage: {}
+            session_storage: {},
+            encrypt: req[:encrypt] || false
           )
           { ok: true, path: Browserctl::Session.path(req[:session_name]),
             pages: pages_meta.length, cookies: cookies.length }
@@ -74,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

@@ -44,8 +44,13 @@ module Browserctl
     end
 
     def ferrum_options
-      { timeout: 30, process_timeout: 30,
-        browser_options: { "no-sandbox" => nil, "disable-dev-shm-usage" => nil, "disable-gpu" => nil } }
+      opts = { timeout: 30, process_timeout: 30,
+               browser_options: { "disable-dev-shm-usage" => nil, "disable-gpu" => nil } }
+      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
     end
 
     def init_state
@@ -125,7 +130,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.2"
+  VERSION = "0.8.4"
 end

data/lib/browserctl/workflow.rb

@@ -68,23 +68,21 @@ module Browserctl
       res
     end
 
-    def load_session(session_name, fallback: nil)
+    def load_session(session_name, fallback: nil, expired_if: nil)
+      validate_expired_if!(expired_if)
+      fallback_name = fallback&.to_s
       res = @client.session_load(session_name)
-      return res unless res[:error]
 
-      raise WorkflowError, res[:error] unless fallback
+      if res[:error]
+        raise WorkflowError, res[:error] unless fallback_name
 
-      invoke(fallback.to_s)
-      res2 = @client.session_load(session_name)
-      if res2[:error]
-        msg = "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
-        unless Session.exist?(session_name)
-          msg += "\n  Hint: '#{fallback}' did not call save_session(\"#{session_name}\") — add it as the last step."
-        end
-        raise WorkflowError, msg
+        invoke(fallback_name)
+        return load_after_fallback(session_name, fallback_name)
       end
 
-      res2
+      return res if expired_if.nil? || !call_expired_if(expired_if, session_name)
+
+      recover_expired_session(session_name, fallback_name, expired_if)
     end
 
     def list_sessions
@@ -106,8 +104,64 @@ 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
+
+      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: 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)
+      expired_if.call
+    rescue WorkflowError, StandardError => e
+      raise WorkflowError, "expired_if check failed for session '#{session_name}': #{e.message}"
+    end
+
+    def recover_expired_session(session_name, fallback_name, expired_if)
+      unless fallback_name
+        raise WorkflowError,
+              "session '#{session_name}' is expired; provide fallback: to auto-recover"
+      end
+
+      invoke(fallback_name)
+      res = load_after_fallback(session_name, fallback_name)
+
+      if call_expired_if(expired_if, session_name)
+        raise WorkflowError,
+              "session '#{session_name}' still expired after running fallback '#{fallback_name}'"
+      end
+
+      res
+    end
+
+    def load_after_fallback(session_name, fallback)
+      res = @client.session_load(session_name)
+      return res unless res[:error]
+
+      msg = "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+      unless Session.exist?(session_name)
+        msg += "\n  Hint: '#{fallback}' did not call save_session(\"#{session_name}\") — add it as the last step."
+      end
+      raise WorkflowError, msg
+    end
+
     def invoke_stack
       @invoke_stack ||= []
     end
@@ -136,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)
@@ -155,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)
 
@@ -220,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.2
+  version: 0.8.4
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -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
@@ -221,6 +222,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: []