browserctl 0.3.0 → 0.4.0

data/examples/the_internet/login.rb

@@ -3,9 +3,10 @@
 Browserctl.workflow "the_internet/login" do
   desc "Form authentication: fill credentials, submit, assert secure area"
 
-  param :username, default: "tomsmith"
-  param :password, default: "SuperSecretPassword!", secret: true
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :username,        default: "tomsmith"
+  param :password,        default: "SuperSecretPassword!", secret: true
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_login.png")
 
   step "open login page" do
     client.open_page("main", url: "#{base_url}/login")
@@ -21,8 +22,7 @@ Browserctl.workflow "the_internet/login" do
     assert page(:main).url.include?("/secure"), "expected redirect to /secure"
     flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
     assert flash&.include?("You logged into a secure area!"), "expected success flash, got: #{flash.inspect}"
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_login.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 
   step "logout and verify" do

data/lib/browserctl/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "socket"
 require "json"
 require_relative "constants"
@@ -152,6 +153,30 @@ module Browserctl
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def clear_cookies(name) = call("clear_cookies", name: name)
 
+    # Exports all cookies for a named page to a JSON file.
+    # @param name [String] logical page name
+    # @param path [String] file path to write cookies to
+    # @return [Hash] `{ ok: true, path:, count: }` or `{ error: }`
+    def export_cookies(name, path)
+      result = call("cookies", name: name)
+      return result unless result[:ok]
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(result[:cookies])) }
+      { ok: true, path: path, count: result[:cookies].length }
+    end
+
+    # Imports cookies from a JSON file into a named page.
+    # @param name [String] logical page name
+    # @param path [String] file path to read cookies from
+    # @return [Hash] `{ ok: true, count: }` or `{ error: }`
+    def import_cookies(name, path)
+      raise "cookie file not found: #{path}" unless File.exist?(path)
+
+      cookies = JSON.parse(File.read(path), symbolize_names: true)
+      call("import_cookies", name: name, cookies: cookies)
+    end
+
     private
 
     def communicate(payload)

data/lib/browserctl/commands/export_cookies.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class ExportCookies
+      def self.run(client, args)
+        page = args.shift or abort "usage: browserctl export-cookies <page> <path>"
+        path = args.shift or abort "usage: browserctl export-cookies <page> <path>"
+        result = client.export_cookies(page, path)
+        if result[:error]
+          warn "Error: #{result[:error]}"
+          exit 1
+        end
+        puts result.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/import_cookies.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class ImportCookies
+      def self.run(client, args)
+        page = args.shift or abort "usage: browserctl import-cookies <page> <path>"
+        path = args.shift or abort "usage: browserctl import-cookies <page> <path>"
+        begin
+          result = client.import_cookies(page, path)
+        rescue StandardError => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+        if result[:error]
+          warn "Error: #{result[:error]}"
+          exit 1
+        end
+        puts result.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/init.rb

@@ -13,15 +13,26 @@ module Browserctl
         # workflows_dir: .browserctl/workflows
       YAML
 
+      GITIGNORE_CONTENT = <<~GITIGNORE
+        # Cookie session exports — contain credentials, never commit
+        sessions/
+      GITIGNORE
+
       def self.run(_args)
         FileUtils.mkdir_p(".browserctl/workflows")
         FileUtils.touch(".browserctl/workflows/.keep")
 
+        FileUtils.mkdir_p(".browserctl/sessions")
+
+        gitignore_path = ".browserctl/.gitignore"
+        File.write(gitignore_path, GITIGNORE_CONTENT) unless File.exist?(gitignore_path)
+
         config_path = ".browserctl/config.yml"
         File.write(config_path, CONFIG_TEMPLATE) unless File.exist?(config_path)
 
         puts "Initialised browserctl project:"
         puts "  .browserctl/workflows/   (place workflow .rb files here)"
+        puts "  .browserctl/sessions/    (cookie exports — git-ignored)"
         puts "  .browserctl/config.yml   (project settings)"
       end
     end

data/lib/browserctl/commands/{pause_resume.rb → pause.rb}

@@ -4,10 +4,10 @@ require_relative "cli_output"
 
 module Browserctl
   module Commands
-    module PauseResume
+    module Pause
       extend CliOutput
 
-      def self.pause(client, args)
+      def self.run(client, args)
         name = args.shift or abort "usage: browserctl pause <page>"
         res = client.pause(name)
         if res[:error]
@@ -17,16 +17,6 @@ module Browserctl
         puts "Page '#{name}' paused. Browser is live — interact freely."
         puts "When done: browserctl resume #{name}"
       end
-
-      def self.resume(client, args)
-        name = args.shift or abort "usage: browserctl resume <page>"
-        res = client.resume(name)
-        if res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
-        end
-        puts "Page '#{name}' resumed."
-      end
     end
   end
 end

data/lib/browserctl/commands/record.rb

@@ -26,6 +26,8 @@ module Browserctl
         def run_start(args)
           Optimist.options(args) { banner "Usage: browserctl record start <name>" }
           name = args.shift or abort "usage: browserctl record start <name>"
+          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"

data/lib/browserctl/commands/resume.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Resume
+      extend CliOutput
+
+      def self.run(client, args)
+        name = args.shift or abort "usage: browserctl resume <page>"
+        res = client.resume(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts "Page '#{name}' resumed."
+      end
+    end
+  end
+end

data/lib/browserctl/commands/status.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browserctl
+  module Commands
+    module Status
+      def self.run(client)
+        ping = client.ping
+        pages = client.list_pages[:pages] || []
+        page_info = pages.map do |name|
+          url_res = client.url(name)
+          { name: name, url: url_res[:url] || url_res[:error] }
+        end
+
+        puts JSON.pretty_generate(
+          daemon: "online",
+          pid: ping[:pid],
+          protocol_version: ping[:protocol_version],
+          pages: page_info
+        )
+      rescue RuntimeError => e
+        raise unless e.message.include?("browserd is not running")
+
+        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        exit 1
+      end
+    end
+  end
+end

data/lib/browserctl/constants.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module Browserctl
-  BROWSERCTL_DIR = File.expand_path("~/.browserctl")
-  IDLE_TTL       = 30 * 60
+  BROWSERCTL_DIR   = File.expand_path("~/.browserctl")
+  IDLE_TTL         = 30 * 60
+  # Increment when a breaking wire protocol change ships (new field names, removed commands, changed response shapes).
+  # Clients read this from `ping` to verify compatibility before sending commands.
+  PROTOCOL_VERSION = "1"
 
   def self.socket_path(name = nil)
     File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")
@@ -12,6 +15,10 @@ module Browserctl
     File.join(BROWSERCTL_DIR, name ? "#{name}.pid" : "browserd.pid")
   end
 
+  def self.log_path(name = nil)
+    File.join(BROWSERCTL_DIR, name ? "#{name}.log" : "browserd.log")
+  end
+
   # Backward-compatible constants
   SOCKET_PATH = socket_path
   PID_PATH    = pid_path

data/lib/browserctl/logger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "fileutils"
 
 module Browserctl
   LEVEL_MAP = {
@@ -10,6 +11,25 @@ module Browserctl
     "error" => ::Logger::ERROR
   }.freeze
 
+  class MultiLogger
+    def initialize(*loggers)
+      @loggers = loggers
+    end
+
+    # Delegate to each logger; swallow individual write failures so a broken file
+    # logger never crashes the daemon or drops a client response.
+    def debug(msg = nil, &) = @loggers.each { |l| l.debug(msg, &) rescue nil } # rubocop:disable Style/RescueModifier
+    def info(msg = nil, &)  = @loggers.each { |l| l.info(msg, &)  rescue nil } # rubocop:disable Style/RescueModifier
+    def warn(msg = nil, &)  = @loggers.each { |l| l.warn(msg, &)  rescue nil } # rubocop:disable Style/RescueModifier
+    def error(msg = nil, &) = @loggers.each { |l| l.error(msg, &) rescue nil } # rubocop:disable Style/RescueModifier
+
+    def level = @loggers.first&.level
+
+    def level=(lvl)
+      @loggers.each { |l| l.level = lvl }
+    end
+  end
+
   def self.logger
     @logger ||= build_logger("info")
   end
@@ -18,11 +38,26 @@ module Browserctl
     @logger = instance
   end
 
-  def self.build_logger(level_name)
-    log = ::Logger.new($stderr)
-    log.level    = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
-    log.progname = "browserd"
-    log.formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+  def self.build_logger(level_name, log_path: nil)
+    level = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
+    formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+
+    stderr_log = make_logger($stderr, level, formatter)
+    return stderr_log unless log_path
+
+    FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
+    FileUtils.touch(log_path)
+    File.chmod(0o600, log_path)
+    file_log = make_logger(log_path, level, formatter)
+    MultiLogger.new(stderr_log, file_log)
+  end
+
+  def self.make_logger(device, level, formatter)
+    log = ::Logger.new(device)
+    log.level     = level
+    log.progname  = "browserd"
+    log.formatter = formatter
     log
   end
+  private_class_method :make_logger
 end

data/lib/browserctl/recording.rb

@@ -4,6 +4,7 @@ require "json"
 require "date"
 require "fileutils"
 require "tmpdir"
+require "uri"
 
 module Browserctl
   class Recording
@@ -12,11 +13,15 @@ module Browserctl
 
     RECORDABLE = %w[open_page goto fill click screenshot evaluate].freeze
 
+    SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
+
     def self.start(name)
-      FileUtils.mkdir_p(RECORDINGS_DIR)
+      FileUtils.mkdir_p(RECORDINGS_DIR, mode: 0o700)
       FileUtils.mkdir_p(File.dirname(STATE_FILE))
       File.write(STATE_FILE, name)
       FileUtils.rm_f(log_path(name))
+      FileUtils.touch(log_path(name))
+      File.chmod(0o600, log_path(name))
       name
     end
 
@@ -36,10 +41,13 @@ module Browserctl
       name = active
       return unless name
       return unless RECORDABLE.include?(cmd.to_s)
-      # ref-based interactions have no replayable selector — skip them
-      return if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
 
-      attrs = attrs.except(:value) if cmd.to_s == "fill"
+      if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
+        record_ref_interaction(name, cmd.to_s, attrs)
+        return
+      end
+
+      attrs = prepare_attrs(cmd.to_s, attrs)
 
       File.open(log_path(name), "a") do |f|
         f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
@@ -53,6 +61,13 @@ module Browserctl
       lines = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
       ruby  = build_workflow_ruby(name, lines)
       File.write(output_path, ruby) if output_path
+
+      ref_count = lines.count { |l| l[:cmd] == "_ref_interaction" }
+      if ref_count.positive?
+        warn "Warning: #{ref_count} ref-based interaction(s) were captured but cannot be replayed by ref."
+        warn "Search the generated workflow for 'TODO: ref-based' and replace with stable CSS selectors."
+      end
+
       ruby
     ensure
       FileUtils.rm_f(log) if log
@@ -65,6 +80,13 @@ module Browserctl
         File.join(RECORDINGS_DIR, "#{name}.jsonl")
       end
 
+      def record_ref_interaction(recording_name, cmd, attrs)
+        entry = { cmd: "_ref_interaction", action: cmd, ref: attrs[:ref], name: attrs[:name] }
+        File.open(log_path(recording_name), "a") do |f|
+          f.puts JSON.generate(entry)
+        end
+      end
+
       def build_workflow_ruby(name, commands)
         steps = commands.map { |c| build_step(c) }.join("\n\n")
         <<~RUBY
@@ -80,30 +102,74 @@ module Browserctl
 
       def build_step(cmd)
         label, body = step_parts(cmd)
-        "step #{label.inspect} do\n  #{body}\nend"
+
+        if body.nil?
+          page_sym = cmd[:name].to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          action   = cmd[:action].to_s.gsub(/[^a-z_]/, "")
+          return "# TODO: ref-based #{action} on #{cmd[:name].inspect} (ref: #{cmd[:ref].inspect}) — " \
+                 "replace with a stable CSS selector\n" \
+                 "# step #{label.inspect} do\n" \
+                 "#   page(:#{page_sym}).#{action}(\"YOUR_SELECTOR_HERE\")\n" \
+                 "# end"
+        end
+
+        url = cmd[:url].to_s
+        if url.include?("[REDACTED]")
+          "# NOTE: sensitive query params were redacted during recording\nstep #{label.inspect} do\n  #{body}\nend"
+        else
+          "step #{label.inspect} do\n  #{body}\nend"
+        end
       end
 
       def step_parts(cmd)
+        return ref_interaction_parts(cmd) if cmd[:cmd] == "_ref_interaction"
+        return selector_parts(cmd) if %w[fill click].include?(cmd[:cmd])
+
+        page = cmd[:name]
+        case cmd[:cmd]
+        when "open_page"  then ["open #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
+        when "goto"       then ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
+        when "screenshot" then ["screenshot #{page}", "page(:#{page}).screenshot"]
+        when "evaluate"   then ["eval on #{page}", "page(:#{page}).evaluate(#{cmd[:expression].inspect})"]
+        else ["#{cmd[:cmd]} on #{page}", "# unrecognised command: #{cmd.inspect}"]
+        end
+      end
+
+      def ref_interaction_parts(cmd)
+        ["TODO: ref-based #{cmd[:action]} on #{cmd[:name]} (ref: #{cmd[:ref]})", nil]
+      end
+
+      def selector_parts(cmd)
         page = cmd[:name]
         case cmd[:cmd]
-        when "open_page"
-          ["open #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
-        when "goto"
-          ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
         when "fill"
           ["fill #{cmd[:selector]} on #{page}",
            "page(:#{page}).fill(#{cmd[:selector].inspect}, params[:fill_value])"]
         when "click"
           ["click #{cmd[:selector]} on #{page}",
            "page(:#{page}).click(#{cmd[:selector].inspect})"]
-        when "screenshot"
-          ["screenshot #{page}", "page(:#{page}).screenshot"]
-        when "evaluate"
-          ["eval on #{page}", "page(:#{page}).evaluate(#{cmd[:expression].inspect})"]
-        else
-          ["#{cmd[:cmd]} on #{page}", "# unrecognised command: #{cmd.inspect}"]
         end
       end
+
+      def prepare_attrs(cmd, attrs)
+        attrs = attrs.except(:value) if cmd == "fill"
+        attrs[:url] = redact_url(attrs[:url]) if %w[goto open_page].include?(cmd) && attrs[:url]
+        attrs
+      end
+
+      def redact_url(url)
+        uri = URI.parse(url)
+        return url if uri.query.nil?
+
+        uri.query = uri.query.gsub(/([^&=]+)=([^&]*)/) do |full_match|
+          raw_key = ::Regexp.last_match(1)
+          key = URI.decode_www_form_component(raw_key)
+          key =~ SENSITIVE_PARAM_PATTERN ? "#{raw_key}=[REDACTED]" : full_match
+        end
+        uri.to_s
+      rescue URI::InvalidURIError
+        url
+      end
     end
   end
 end

data/lib/browserctl/runner.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "workflow"
 require_relative "client"
 
@@ -39,6 +40,24 @@ module Browserctl
 
     SAFE_WORKFLOW_NAME = /\A[a-zA-Z0-9_-]+\z/
 
+    def self.load_params_file(path)
+      raise "params file not found: #{path}" unless File.exist?(path)
+
+      case File.extname(path).downcase
+      when ".yml", ".yaml"
+        require "yaml"
+        YAML.safe_load_file(path, symbolize_names: true)
+      when ".json"
+        JSON.parse(File.read(path), symbolize_names: true)
+      else
+        raise "unsupported params file format: #{path} (use .yml, .yaml, or .json)"
+      end
+    rescue Psych::SyntaxError => e
+      raise "invalid YAML in #{path}: #{e.message}"
+    rescue JSON::ParserError => e
+      raise "invalid JSON in #{path}: #{e.message}"
+    end
+
     private
 
     def validate_name!(name)
@@ -48,6 +67,8 @@ module Browserctl
     end
 
     def fetch_workflow(name)
+      return REGISTRY[name.to_s] if REGISTRY.key?(name.to_s)
+
       validate_name!(name)
       load_workflow_file(name)
       REGISTRY[name.to_s] || raise("workflow '#{name}' not found")

data/lib/browserctl/server/command_dispatcher.rb

@@ -25,10 +25,12 @@ module Browserctl
       "inspect" => :cmd_inspect,
       "cookies" => :cmd_cookies,
       "set_cookie" => :cmd_set_cookie,
-      "clear_cookies" => :cmd_clear_cookies
+      "clear_cookies" => :cmd_clear_cookies,
+      "import_cookies" => :cmd_import_cookies
     }.freeze
 
-    SCREENSHOT_DIR  = File.expand_path("~/.browserctl/screenshots").freeze
+    SCREENSHOT_DIR   = File.expand_path("~/.browserctl/screenshots").freeze
+    SCREENSHOT_ROOTS = [SCREENSHOT_DIR, File.expand_path(".")].freeze
     SCREENSHOT_EXTS = %w[.png .jpg .jpeg].freeze
     CLOUDFLARE_SIGNALS = [
       "cf-challenge-running",
@@ -168,8 +170,8 @@ module Browserctl
     def safe_screenshot_path(requested, page_name)
       if requested
         expanded = File.expand_path(requested)
-        return { error: "path outside allowed directory (#{SCREENSHOT_DIR})" } \
-          unless expanded.start_with?(SCREENSHOT_DIR)
+        allowed  = SCREENSHOT_ROOTS.any? { |d| expanded.start_with?("#{d}/") || expanded.start_with?(d) }
+        return { error: "path outside allowed directory (#{SCREENSHOT_DIR} or project directory)" } unless allowed
         return { error: "invalid extension — use .png, .jpg, or .jpeg" } \
           unless SCREENSHOT_EXTS.include?(File.extname(expanded).downcase)
 
@@ -235,6 +237,23 @@ module Browserctl
       { ok: true }
     end
 
+    def cmd_import_cookies(req)
+      with_page(req[:name]) do |session|
+        req[:cookies].each do |c|
+          session.page.cookies.set(
+            name: c[:name],
+            value: c[:value],
+            domain: c[:domain],
+            path: c.fetch(:path, "/"),
+            httponly: c[:httpOnly] == true,
+            secure: c[:secure] == true,
+            expires: c[:expires] ? Time.at(c[:expires].to_i) : nil
+          )
+        end
+        { ok: true, count: req[:cookies].length }
+      end
+    end
+
     def cmd_inspect(req)
       session = @global_mutex.synchronize { @pages[req[:name]] }
       return { error: "no page named '#{req[:name]}'" } unless session
@@ -265,7 +284,7 @@ module Browserctl
       { ok: true, paused: false }
     end
 
-    def cmd_ping(_req) = { ok: true, pid: Process.pid }
+    def cmd_ping(_req) = { ok: true, pid: Process.pid, protocol_version: PROTOCOL_VERSION }
 
     def cmd_shutdown(_req)
       Process.kill("INT", Process.pid)

data/lib/browserctl/server.rb

@@ -21,6 +21,7 @@ module Browserctl
     end
 
     def run
+      guard_already_running!
       write_pid
       server, idle = setup_server
       serve(server)
@@ -63,10 +64,24 @@ module Browserctl
       FileUtils.rm_f(@socket_path)
       server = UNIXServer.new(@socket_path)
       File.chmod(0o600, @socket_path)
-      Browserctl.logger.info "listening on #{@socket_path}"
+      Browserctl.logger.info "daemon ready — listening on #{@socket_path}"
       server
     end
 
+    def guard_already_running!
+      return unless File.exist?(@pid_path)
+
+      pid = File.read(@pid_path).strip.to_i
+      return unless pid.positive?
+
+      Process.kill(0, pid)
+      abort "browserd already running (PID #{pid}). Use 'browserctl shutdown' first."
+    rescue Errno::ESRCH
+      # Dead process — stale PID file, safe to continue
+    rescue Errno::EPERM
+      abort "browserd (PID #{pid}) is running as a different user. Remove #{@pid_path} manually if stale."
+    end
+
     def serve(server)
       loop do
         client = server.accept

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -16,6 +16,15 @@ module Browserctl
     def initialize(params, client)
       @params = params
       @client = client
+      @_store = {}
+    end
+
+    def store(key, value)
+      @_store[key] = value
+    end
+
+    def fetch(key)
+      @_store.fetch(key) { raise KeyError, "no value stored for key #{key.inspect}" }
     end
 
     def method_missing(name, *args)
@@ -32,6 +41,20 @@ module Browserctl
       PageProxy.new(name.to_s, @client)
     end
 
+    def open_page(page_name, url: nil)
+      res = @client.open_page(page_name.to_s, url: url)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    def close_page(page_name)
+      res = @client.close_page(page_name.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
     def invoke(workflow_name, **override_params)
       name = workflow_name.to_s
       guard_circular!(name)
@@ -77,6 +100,7 @@ module Browserctl
     def click(sel)       = unwrap @client.click(@name, sel)
     def snapshot(**) = unwrap @client.snapshot(@name, **)
     def screenshot(**) = unwrap @client.screenshot(@name, **)
+    def watch(sel, timeout: 30)    = unwrap @client.watch(@name, sel, timeout: timeout)
     def wait_for(sel, timeout: 10) = unwrap @client.wait_for(@name, sel, timeout: timeout)
     def url              = @client.url(@name)[:url]
     def evaluate(expr)   = @client.evaluate(@name, expr)[:result]