browserctl 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c12ad0cc3d34e7163bab1d678d65b320e946e0fa16fe7bd3e9f5881855d4801f
-  data.tar.gz: 84d80f56270dfc7d252d7e63279f7c7c54123067837af457f5e92e82b2f0384e
+  metadata.gz: 1626673b3046c133aa7e1d63ee7d1886ed3071970227c184ab412a8f3cf48a4f
+  data.tar.gz: 4773002a9052247ec8afe259abd0d4c38cc3aa308be81bbeca756626bb206d44
 SHA512:
-  metadata.gz: c95dbbbe2a573635421fe90cd65d2ccc41baf968c32bb65edcea52030e1b0080fd2af0f50ea9d85bc827ff4f537e2c5b4f3a7631c8242380a007df432e820906
-  data.tar.gz: 1da50ab443d365e4a4b9ce145671e266fdfb0d83432b7b2313d87233b58b425252d2d9a365b0f8b3c31040961b90f684fe9299867c4cccfcd9600ea88cb93cc1
+  metadata.gz: 8e241d9fc064c419285b2e83b5e5154c6ccb639aeffb2179ace9b6ef3ec180069b76772cf5f6485af3cea4ef4616265a87dbbc43d7879cd0a71eec946e022ce8
+  data.tar.gz: b396184b74f6804e3b84105c4b75a89ef5a63751ad5577e2dc8008ed1c3111614f2d579ac9c3a12f7943968b3c4cab59fab69dfe392f4af51ba59fff0e8684ba

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.3.1](https://github.com/patrick204nqh/browserctl/compare/v0.3.0...v0.3.1) (2026-04-20)
+
+
+### Bug Fixes
+
+* allow pre-registered workflows with slash names (e.g. the_internet/login) ([e755a4a](https://github.com/patrick204nqh/browserctl/commit/e755a4aa20608fb11ce425c81ed8c0a43f3b13fe))
+* remove unused client variable in runner spec ([94e1a31](https://github.com/patrick204nqh/browserctl/commit/94e1a310acc1d5ddb5e538860907040d3504f2c9))
+
+## [0.3.0](https://github.com/patrick204nqh/browserctl/compare/v0.2.2...v0.3.0) (2026-04-20)
+
+
+### Features
+
+* add cookies, set_cookie, clear_cookies commands for CF clearance replay ([dd38f2d](https://github.com/patrick204nqh/browserctl/commit/dd38f2d587d12f789072326310a1f490e7f993b7))
+* add cookies, set_cookie, clear_cookies commands for CF clearance replay ([c773fe2](https://github.com/patrick204nqh/browserctl/commit/c773fe25e73660cbe5c7e0e3d698fbf7709df51d))
+* browserctl v0.3 — HITL, Cloudflare detection, init, compose, plugins, inspect, RBS, YARD ([ec24c85](https://github.com/patrick204nqh/browserctl/commit/ec24c85a7772b508c477ef4413b0b4a64be8dfa2))
+
+
+### Bug Fixes
+
+* rubocop offenses — bump ClassLength max to 240, fix hash alignment ([52669fd](https://github.com/patrick204nqh/browserctl/commit/52669fd21051e1fef581d1c6acd3189d7d805dfb))
+* rubocop offenses — move CLOUDFLARE_SIGNALS above private, autocorrect style ([0ad3d38](https://github.com/patrick204nqh/browserctl/commit/0ad3d38127671284c935809e189478c7160294f6))
+
+## [0.2.2](https://github.com/patrick204nqh/browserctl/compare/v0.2.1...v0.2.2) (2026-04-20)
+
+
+### Bug Fixes
+
+* never record plaintext fill values in session recordings ([a0ea9a1](https://github.com/patrick204nqh/browserctl/commit/a0ea9a15f4dbdc29a0a6aaa8186fa313e601c691))
+* rescue Timeout::Error in quietly; remove duplicate [@last](https://github.com/last)_used update ([d0b1430](https://github.com/patrick204nqh/browserctl/commit/d0b143051a4a6adcdc80620388390bd649ee0bce))
+* restrict screenshot path to ~/.browserctl/screenshots ([0a1303f](https://github.com/patrick204nqh/browserctl/commit/0a1303f95b1df3135a81c98e531ac31c99e2e275))
+* rubocop offenses — constant scope and hash alignment ([cc11bc5](https://github.com/patrick204nqh/browserctl/commit/cc11bc546746c7f341573ffff43b02fdc94578d8))
+* security patches and PageSession architecture refactor (review fixes) ([a01d0f7](https://github.com/patrick204nqh/browserctl/commit/a01d0f7bd3f58b51d21fc534a67dda25c15b029b))
+* trigger release on tag push; revert release-please to default token ([011d4dc](https://github.com/patrick204nqh/browserctl/commit/011d4dcddd872f0ed88548ee9c2e8b19d64ad5c2))
+* update CI workflows to use actions/checkout@v4 and set timeout for jobs ([15ab5d4](https://github.com/patrick204nqh/browserctl/commit/15ab5d471952ff9759eff7ff77ce2df30eea5e1f))
+* validate workflow name to prevent path traversal ([1d0f221](https://github.com/patrick204nqh/browserctl/commit/1d0f221b35a855c1991bee5177b7e742ecb16e86))
+
 ## [0.2.1](https://github.com/patrick204nqh/browserctl/compare/v0.2.0...v0.2.1) (2026-04-20)
 
 

data/README.md

@@ -138,6 +138,12 @@ browserctl shutdown
 | `shot <page> [--out PATH] [--full]` | Take a screenshot |
 | `url <page>` | Print current URL |
 | `eval <page> <expression>` | Evaluate a JS expression |
+| `pause <page>` | Pause automation — browser stays live for manual interaction |
+| `resume <page>` | Resume automation after manual action |
+| `inspect <page>` | Open Chrome DevTools for a named page |
+| `cookies <page>` | List all cookies as JSON |
+| `set_cookie <page> <name> <value> <domain>` | Set a cookie (path defaults to `/`) |
+| `clear_cookies <page>` | Clear all cookies for a page |
 | `record start <name>` | Begin recording commands as a replayable workflow |
 | `record stop [--out path]` | End recording; saves to `.browserctl/workflows/` or custom path |
 | `record status` | Show whether a recording is active |
@@ -262,7 +268,7 @@ browserctl run smoke_login --email me@example.com --password s3cr3t
 
 ### PageProxy methods
 
-`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)`
+`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)` · `pause` · `resume` · `inspect_page` · `cookies` · `set_cookie(name, value, domain, path: "/")` · `clear_cookies`
 
 ---
 

data/bin/browserctl

@@ -21,6 +21,9 @@ require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
 require "browserctl/commands/watch"
 require "browserctl/commands/record"
+require "browserctl/commands/pause_resume"
+require "browserctl/commands/init"
+require "browserctl/commands/inspect"
 
 def print_result(res)
   if res.is_a?(Hash) && res[:error]
@@ -35,6 +38,9 @@ def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
+    Setup:
+      init                                         Scaffold .browserctl/ in this project
+
     Browser commands (require browserd running):
       open   <page> [--url URL]                   Open or focus a named page
       close  <page>                                Close a named page
@@ -49,6 +55,12 @@ def usage
       url    <page>                                Print current URL
       eval   <page> <expression>                   Evaluate JS expression
       watch  <page> <selector> [--timeout N]       Wait for a selector to appear
+      pause   <page>                               Pause automation — browser stays live
+      resume  <page>                               Resume automation after manual action
+      inspect <page>                               Open Chrome DevTools for a named page
+      cookies <page>                               List all cookies as JSON
+      set_cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
+      clear_cookies <page>                         Clear all cookies for a page
 
     Recording commands:
       record start <name>            Start recording browser commands
@@ -110,6 +122,7 @@ when "describe"
   puts JSON.pretty_generate(runner.describe_workflow(name))
 
 when "record" then Browserctl::Commands::Record.run(args)
+when "init"   then Browserctl::Commands::Init.run(args)
 
 else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
@@ -126,6 +139,12 @@ else
   when "url"      then print_result(client.url(args[0]))
   when "eval"     then print_result(client.evaluate(args[0], args[1]))
   when "watch"    then Browserctl::Commands::Watch.run(client, args)
+  when "pause"    then Browserctl::Commands::PauseResume.pause(client, args)
+  when "resume"   then Browserctl::Commands::PauseResume.resume(client, args)
+  when "inspect"       then Browserctl::Commands::Inspect.run(client, args)
+  when "cookies"       then print_result(client.cookies(args[0]))
+  when "set_cookie"    then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
+  when "clear_cookies" then print_result(client.clear_cookies(args[0]))
   when "ping"     then print_result(client.ping)
   when "shutdown" then print_result(client.shutdown)
   else

data/examples/cloudflare_hitl.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Demonstrates the Cloudflare HITL (Human-in-the-Loop) pattern.
+#
+# When an agent navigates to a Cloudflare-protected page and hits a bot challenge,
+# it cannot interact with the real page content. This workflow detects the challenge,
+# pauses automation so a human can solve it in the live browser, then resumes.
+#
+# Run:
+#   browserctl run examples/cloudflare_hitl.rb --url https://example.com
+#
+# Note: modern Cloudflare often passes a real headed Chrome without challenge.
+# The pause/resume branch fires only when the challenge page is actually served
+# (typically against headless or CDP-fingerprinted browsers, or stricter zones).
+# When paused, the terminal prints instructions. Solve the challenge in the open
+# browser window, then run: browserctl resume main
+
+Browserctl.workflow "cloudflare_hitl" do
+  desc "Navigate a Cloudflare-protected URL with human-assisted challenge bypass"
+
+  param :url,      required: true
+  param :selector, default: "body"
+
+  step "open page" do
+    client.open_page("main")
+  end
+
+  step "navigate to target URL" do
+    res = client.goto("main", url)
+
+    if res[:challenge]
+      $stdout.puts ""
+      $stdout.puts "  ⚠  Cloudflare challenge detected on #{url}"
+      $stdout.puts "  → Pausing automation. Solve the challenge in the browser, then run:"
+      $stdout.puts "       browserctl resume main"
+      $stdout.puts ""
+
+      client.pause("main")
+
+      # Block here until the human calls `browserctl resume main`.
+      # The pause command marks the page; resume unblocks and signals the CV.
+      # In a workflow context, we poll the server until the page is unpaused
+      # by attempting a lightweight snapshot — once it succeeds, we're through.
+      loop do
+        snap = client.snapshot("main", format: "html")
+        break unless snap[:challenge]
+
+        $stdout.puts "  … still on challenge page, waiting 3s"
+        sleep 3
+      end
+
+      $stdout.puts "  ✓ Challenge cleared — resuming automation"
+    end
+  end
+
+  step "wait for content and snapshot" do
+    page(:main).wait_for(selector, timeout: 15)
+    result = page(:main).snapshot(format: "ai")
+    $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
+  end
+
+  step "close page" do
+    client.close_page("main")
+  end
+end

data/lib/browserctl/client.rb

@@ -6,6 +6,7 @@ require_relative "constants"
 require_relative "recording"
 
 module Browserctl
+  # Thin IPC client that wraps each browserd command as a Ruby method call.
   class Client
     def initialize(socket_path = Browserctl.socket_path)
       @socket_path = socket_path
@@ -19,42 +20,138 @@ module Browserctl
       raise "browserd is not running — start it with: browserd"
     end
 
-    # Convenience wrappers matching CLI command vocabulary
-
+    # Opens or focuses a named browser page.
+    # @param name [String] logical page name
+    # @param url [String, nil] optional URL to navigate to after opening
+    # @return [Hash] `{ ok: true, name: }` or `{ error: }`
     def open_page(name, url: nil)  = call("open_page",  name: name, url: url)
+
+    # Closes a named page and removes it from the session.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def close_page(name)           = call("close_page", name: name)
+
+    # Lists all open page names.
+    # @return [Hash] `{ pages: [String] }`
     def list_pages                 = call("list_pages")
+
+    # Navigates a page to a URL. Returns `challenge: true` when Cloudflare is detected.
+    # @param name [String] logical page name
+    # @param url [String] destination URL
+    # @return [Hash] `{ ok: true, url:, challenge: }` or `{ error: }`
     def goto(name, url)            = call("goto", name: name, url: url)
 
+    # Clicks an element identified by CSS selector or snapshot ref.
+    # @param name [String] logical page name
+    # @param selector [String, nil] CSS selector
+    # @param ref [String, nil] snapshot ref (e.g. "e3")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def click(name, selector = nil, ref: nil)
       raise ArgumentError, "click: provide selector or ref:" unless selector || ref
 
       call("click", name: name, selector: selector, ref: ref)
     end
 
+    # Fills an input element with a value.
+    # @param name [String] logical page name
+    # @param selector [String, nil] CSS selector
+    # @param value [String, nil] text to type
+    # @param ref [String, nil] snapshot ref
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def fill(name, selector = nil, value = nil, ref: nil)
       raise ArgumentError, "fill: provide selector or ref:" unless selector || ref
 
       call("fill", name: name, selector: selector, ref: ref, value: value)
     end
 
+    # Takes a screenshot of a named page.
+    # @param name [String] logical page name
+    # @param path [String, nil] output path (default: ~/.browserctl/screenshots/)
+    # @param full [Boolean] capture full page (default: false)
+    # @return [Hash] `{ ok: true, path: }` or `{ error: }`
     def screenshot(name, path: nil, full: false) = call("screenshot", name: name, path: path, full: full)
 
+    # Takes a DOM snapshot. Returns `challenge: true` when Cloudflare is detected.
+    # @param name [String] logical page name
+    # @param format [String] "ai" (token-efficient JSON) or "html" (raw HTML)
+    # @param diff [Boolean] return only elements changed since last snapshot
+    # @return [Hash] `{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`
     def snapshot(name, format: "ai", diff: false)
       call("snapshot", name: name, format: format, diff: diff)
     end
 
+    # Waits for a CSS selector to appear (short timeout).
+    # @param name [String] logical page name
+    # @param selector [String] CSS selector to wait for
+    # @param timeout [Numeric] seconds before giving up (default: 10)
+    # @return [Hash] `{ ok: true }` or `{ error: }`
     def wait_for(name, selector, timeout: 10) = call("wait_for", name: name, selector: selector, timeout: timeout)
 
+    # Polls for a CSS selector with a longer timeout (suitable for async operations).
+    # @param name [String] logical page name
+    # @param selector [String] CSS selector to poll for
+    # @param timeout [Numeric] seconds before giving up (default: 30)
+    # @return [Hash] `{ ok: true, selector: }` or `{ error: }`
     def watch(name, selector, timeout: 30)
       call("watch", name: name, selector: selector, timeout: timeout)
     end
 
+    # Returns the current URL of a named page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true, url: }` or `{ error: }`
     def url(name)                  = call("url",         name: name)
+
+    # Evaluates a JavaScript expression and returns the result.
+    # @param name [String] logical page name
+    # @param expression [String] JavaScript expression
+    # @return [Hash] `{ ok: true, result: }` or `{ error: }`
     def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)
+
+    # Checks if browserd is alive.
+    # @return [Hash] `{ ok: true, pid: }` or raises if daemon is not running
     def ping                       = call("ping")
+
+    # Shuts down browserd gracefully.
+    # @return [Hash] `{ ok: true }`
     def shutdown                   = call("shutdown")
 
+    # Pauses automation on a page so a human can interact directly.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true, paused: true }` or `{ error: }`
+    def pause(name)                = call("pause",   name: name)
+
+    # Resumes automation on a paused page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true, paused: false }` or `{ error: }`
+    def resume(name)               = call("resume",  name: name)
+
+    # Returns the Chrome DevTools URL for a named page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true, devtools_url: }` or `{ error: }`
+    def inspect_page(name)         = call("inspect", name: name)
+
+    # Returns all cookies for a named page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true, cookies: [Hash] }` or `{ error: }`
+    def cookies(name) = call("cookies", name: name)
+
+    # Sets a cookie on a named page.
+    # @param name [String] logical page name
+    # @param cookie_name [String] cookie name (e.g. "cf_clearance")
+    # @param value [String] cookie value
+    # @param domain [String] cookie domain (e.g. ".example.com")
+    # @param path [String] cookie path (default: "/")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def set_cookie(name, cookie_name, value, domain, path: "/")
+      call("set_cookie", name: name, cookie_name: cookie_name,
+                         value: value, domain: domain, path: path)
+    end
+
+    # Clears all cookies for a named page.
+    # @param name [String] logical page name
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def clear_cookies(name) = call("clear_cookies", name: name)
+
     private
 
     def communicate(payload)

data/lib/browserctl/commands/init.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Browserctl
+  module Commands
+    class Init
+      CONFIG_TEMPLATE = <<~YAML
+        # browserctl project configuration
+        # Uncomment and edit to customise.
+
+        # daemon: default          # named daemon instance (see browserd --name)
+        # workflows_dir: .browserctl/workflows
+      YAML
+
+      def self.run(_args)
+        FileUtils.mkdir_p(".browserctl/workflows")
+        FileUtils.touch(".browserctl/workflows/.keep")
+
+        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/config.yml   (project settings)"
+      end
+    end
+  end
+end

data/lib/browserctl/commands/inspect.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class Inspect
+      def self.run(client, args)
+        name = args.shift or abort "usage: browserctl inspect <page>"
+        res = client.inspect_page(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        url = res[:devtools_url]
+        puts "Opening DevTools for '#{name}':"
+        puts "  #{url}"
+        opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+        system(opener, url)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/pause_resume.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module PauseResume
+      extend CliOutput
+
+      def self.pause(client, args)
+        name = args.shift or abort "usage: browserctl pause <page>"
+        res = client.pause(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        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/recording.rb

@@ -39,6 +39,8 @@ module Browserctl
       # 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"
+
       File.open(log_path(name), "a") do |f|
         f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
       end
@@ -90,7 +92,7 @@ module Browserctl
           ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
         when "fill"
           ["fill #{cmd[:selector]} on #{page}",
-           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{cmd[:value].inspect})"]
+           "page(:#{page}).fill(#{cmd[:selector].inspect}, params[:fill_value])"]
         when "click"
           ["click #{cmd[:selector]} on #{page}",
            "page(:#{page}).click(#{cmd[:selector].inspect})"]

data/lib/browserctl/runner.rb

@@ -10,6 +10,11 @@ module Browserctl
       File.expand_path("~/.browserctl/workflows")
     ].freeze
 
+    # Runs a named workflow with the given parameters.
+    # @param name [String] workflow name (must match /\A[a-zA-Z0-9_-]+\z/)
+    # @param params [Hash] keyword arguments passed to the workflow
+    # @return [Boolean] true if all steps succeeded
+    # @raise [WorkflowError] if the name is invalid or a step fails
     def run_workflow(name, **params)
       defn    = fetch_workflow(name)
       results = defn.call(params, Client.new)
@@ -17,19 +22,35 @@ module Browserctl
       results.all?(&:ok)
     end
 
+    # Lists all registered workflows from the standard search paths.
+    # @return [Array<Hash>] array of `{ name:, desc: }` hashes
     def list_workflows
       load_all_workflows
       REGISTRY.map { |name, defn| { name: name, desc: defn.description } }
     end
 
+    # Returns detailed information about a workflow.
+    # @param name [String] workflow name
+    # @return [Hash] `{ name:, desc:, params:, steps: }`
     def describe_workflow(name)
       defn = fetch_workflow(name)
       { name: defn.name, desc: defn.description, params: format_params(defn), steps: defn.steps.map(&:label) }
     end
 
+    SAFE_WORKFLOW_NAME = /\A[a-zA-Z0-9_-]+\z/
+
     private
 
+    def validate_name!(name)
+      return if SAFE_WORKFLOW_NAME.match?(name.to_s)
+
+      raise Browserctl::WorkflowError, "invalid workflow name: #{name.inspect} — use letters, digits, _ and - only"
+    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")
     end

data/lib/browserctl/server/command_dispatcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "snapshot_builder"
+require_relative "page_session"
 
 module Browserctl
   class CommandDispatcher
@@ -18,68 +19,92 @@ module Browserctl
       "watch" => :cmd_watch,
       "url" => :cmd_url,
       "ping" => :cmd_ping,
-      "shutdown" => :cmd_shutdown
+      "shutdown" => :cmd_shutdown,
+      "pause" => :cmd_pause,
+      "resume" => :cmd_resume,
+      "inspect" => :cmd_inspect,
+      "cookies" => :cmd_cookies,
+      "set_cookie" => :cmd_set_cookie,
+      "clear_cookies" => :cmd_clear_cookies
     }.freeze
 
-    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, mutex: Mutex.new)
-      @pages          = pages
-      @browser        = browser
-      @snapshot       = snapshot_builder
-      @mutex          = mutex
-      @ref_registries = {}
-      @prev_snapshots = {}
+    SCREENSHOT_DIR  = File.expand_path("~/.browserctl/screenshots").freeze
+    SCREENSHOT_EXTS = %w[.png .jpg .jpeg].freeze
+    CLOUDFLARE_SIGNALS = [
+      "cf-challenge-running",
+      "cf_chl_opt",
+      "__cf_chl_f_tk",
+      "Just a moment..."
+    ].freeze
+
+    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
+      @pages            = pages
+      @browser          = browser
+      @snapshot_builder = snapshot_builder
+      @global_mutex     = global_mutex
     end
 
     def dispatch(req)
       handler = COMMAND_MAP[req[:cmd]]
-      return { error: "unknown command: #{req[:cmd]}" } unless handler
+      if handler
+        Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
+        return send(handler, req)
+      end
+
+      if (plugin = Browserctl::PLUGIN_COMMANDS[req[:cmd]])
+        Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
+        session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
+        return plugin.call(session, req)
+      end
 
-      Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
-      send(handler, req)
+      { error: "unknown command: #{req[:cmd]}" }
     end
 
     private
 
     def cmd_open_page(req)
-      page = @mutex.synchronize { @pages[req[:name]] ||= @browser.create_page }
-      page.go_to(req[:url]) if req[:url]
+      session = @global_mutex.synchronize do
+        @pages[req[:name]] ||= PageSession.new(@browser.create_page)
+      end
+      session.page.go_to(req[:url]) if req[:url]
       { ok: true, name: req[:name] }
     end
 
     def cmd_close_page(req)
-      @mutex.synchronize { @pages.delete(req[:name]) }&.close
+      session = @global_mutex.synchronize { @pages.delete(req[:name]) }
+      session&.page&.close
       { ok: true }
     end
 
     def cmd_list_pages(_req)
-      { pages: @mutex.synchronize { @pages.keys } }
+      { pages: @global_mutex.synchronize { @pages.keys } }
     end
 
     def cmd_goto(req)
-      with_page(req[:name]) do |p|
-        p.go_to(req[:url])
-        { ok: true, url: p.current_url }
+      with_page(req[:name]) do |session|
+        session.page.go_to(req[:url])
+        { ok: true, url: session.page.current_url, challenge: cloudflare_challenge?(session.page) }
       end
     end
 
     def cmd_snapshot(req)
-      with_page(req[:name]) { |p| take_snapshot(req[:name], p, req[:format], req[:diff]) }
+      with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
     end
 
-    def take_snapshot(name, page, format, diff)
-      return { ok: true, html: page.body } unless format == "ai"
+    def take_snapshot(session, format, diff)
+      challenge = cloudflare_challenge?(session.page)
+
+      return { ok: true, html: session.page.body, challenge: challenge } unless format == "ai"
 
-      snapshot = @snapshot.call(page)
+      snapshot = @snapshot_builder.call(session.page)
       registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
 
-      result = @mutex.synchronize do
-        prev = @prev_snapshots[name]
-        @ref_registries[name] = registry
-        @prev_snapshots[name] = snapshot
-        diff && prev ? compute_diff(prev, snapshot) : snapshot
-      end
+      prev = session.prev_snapshot
+      session.ref_registry  = registry
+      session.prev_snapshot = snapshot
+      result = diff && prev ? compute_diff(prev, snapshot) : snapshot
 
-      { ok: true, snapshot: result }
+      { ok: true, snapshot: result, challenge: challenge }
     end
 
     def compute_diff(prev, current)
@@ -91,14 +116,16 @@ module Browserctl
     end
 
     def cmd_evaluate(req)
-      with_page(req[:name]) { |p| { ok: true, result: p.evaluate(req[:expression]) } }
+      with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
     end
 
     def cmd_fill(req)
-      sel = resolve_selector(req[:name], req)
-      return sel if sel.is_a?(Hash)
+      with_page(req[:name]) do |session|
+        sel = resolve_selector_from(session, req)
+        return sel if sel.is_a?(Hash)
 
-      with_page(req[:name]) { |p| type_into(p, sel, req[:value]) }
+        type_into(session.page, sel, req[:value])
+      end
     end
 
     def type_into(page, selector, value)
@@ -111,10 +138,12 @@ module Browserctl
     end
 
     def cmd_click(req)
-      sel = resolve_selector(req[:name], req)
-      return sel if sel.is_a?(Hash)
+      with_page(req[:name]) do |session|
+        sel = resolve_selector_from(session, req)
+        return sel if sel.is_a?(Hash)
 
-      with_page(req[:name]) { |p| click_element(p, sel) }
+        click_element(session.page, sel)
+      end
     end
 
     def click_element(page, selector)
@@ -126,56 +155,145 @@ module Browserctl
     end
 
     def cmd_screenshot(req)
-      with_page(req[:name]) do |p|
-        path = req[:path] || "/tmp/browserctl_shot_#{req[:name]}_#{Time.now.to_i}.png"
-        p.screenshot(path: path, full: req.fetch(:full, false))
+      with_page(req[:name]) do |session|
+        path = safe_screenshot_path(req[:path], req[:name])
+        return path if path.is_a?(Hash)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        session.page.screenshot(path: path, full: req.fetch(:full, false))
         { ok: true, path: path }
       end
     end
 
+    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)
+        return { error: "invalid extension — use .png, .jpg, or .jpeg" } \
+          unless SCREENSHOT_EXTS.include?(File.extname(expanded).downcase)
+
+        expanded
+      else
+        name_safe = page_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
+        File.join(SCREENSHOT_DIR, "browserctl_shot_#{name_safe}_#{Time.now.to_i}.png")
+      end
+    end
+
     def cmd_wait_for(req)
-      with_page(req[:name]) { |p| wait_for_selector(p, req[:selector], req.fetch(:timeout, 10).to_f) }
+      with_page(req[:name]) { |session| wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f) }
     end
 
     def cmd_watch(req)
-      with_page(req[:name]) do |p|
-        result = wait_for_selector(p, req[:selector], req.fetch(:timeout, 30).to_f)
+      with_page(req[:name]) do |session|
+        result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
         result[:error] ? result : { ok: true, selector: req[:selector] }
       end
     end
 
     def wait_for_selector(page, selector, timeout)
       deadline = Time.now + timeout
-      sleep 0.2 until (found = page.at_css(selector)) || Time.now > deadline
-      found ? { ok: true } : { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" }
+      loop do
+        found = page.at_css(selector)
+        break { ok: true } if found
+        break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" } if Time.now >= deadline
+
+        sleep 0.2
+      end
     end
 
     def cmd_url(req)
-      with_page(req[:name]) { |p| { ok: true, url: p.current_url } }
+      with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
     end
 
-    def cmd_ping(_req)
-      { ok: true, pid: Process.pid }
+    def cmd_cookies(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      all = session.page.cookies.all
+      { ok: true, cookies: all.values.map(&:to_h) }
+    end
+
+    def cmd_set_cookie(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.page.cookies.set(
+        name: req[:cookie_name],
+        value: req[:value],
+        domain: req[:domain],
+        path: req.fetch(:path, "/")
+      )
+      { ok: true }
     end
 
+    def cmd_clear_cookies(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.page.cookies.clear
+      { ok: true }
+    end
+
+    def cmd_inspect(req)
+      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
+      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 }
+    end
+
+    def cmd_pause(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.mutex.synchronize { session.pause! }
+      { ok: true, paused: true }
+    end
+
+    def cmd_resume(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.mutex.synchronize do
+        session.resume!
+        session.pause_cv.signal
+      end
+      { ok: true, paused: false }
+    end
+
+    def cmd_ping(_req) = { ok: true, pid: Process.pid }
+
     def cmd_shutdown(_req)
       Process.kill("INT", Process.pid)
       { ok: true }
     end
 
     def with_page(name)
-      page = @mutex.synchronize { @pages[name] }
-      return { error: "no page named '#{name}'" } unless page
+      session = @global_mutex.synchronize { @pages[name] }
+      return { error: "no page named '#{name}'" } unless session
+
+      session.mutex.synchronize do
+        session.pause_cv.wait(session.mutex) while session.paused?
+        yield session
+      end
+    end
 
-      yield page
+    def cloudflare_challenge?(page)
+      url  = page.current_url.to_s
+      body = page.body.to_s
+      url.include?("challenge-platform") ||
+        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
     end
 
-    def resolve_selector(name, req)
+    def resolve_selector_from(session, req)
       return req[:selector] if req[:selector]
       return { error: "selector or ref required" } unless req[:ref]
 
-      sel = @mutex.synchronize { @ref_registries.dig(name, req[:ref]) }
-      sel || { error: "ref '#{req[:ref]}' not found — run snap first" }
+      session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
     end
   end
 end

data/lib/browserctl/server/page_session.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class PageSession
+    attr_reader :page, :mutex, :pause_cv
+    attr_accessor :ref_registry, :prev_snapshot
+
+    def initialize(page)
+      @page          = page
+      @mutex         = Mutex.new
+      @pause_cv      = ConditionVariable.new
+      @ref_registry  = {}
+      @prev_snapshot = nil
+      @paused        = false
+    end
+
+    def paused? = @paused
+    def pause!  = (@paused = true)
+    def resume! = (@paused = false)
+  end
+end

data/lib/browserctl/server.rb

@@ -9,6 +9,7 @@ require_relative "constants"
 require_relative "logger"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
+require_relative "server/page_session"
 
 module Browserctl
   class Server
@@ -16,7 +17,7 @@ module Browserctl
       @socket_path = socket_path
       @pid_path    = pid_path
       prepare_runtime(headless)
-      @dispatcher = CommandDispatcher.new(@pages, @browser, mutex: @mutex)
+      @dispatcher = CommandDispatcher.new(@pages, @browser, global_mutex: @mutex)
     end
 
     def run
@@ -85,7 +86,6 @@ module Browserctl
     def dispatch(socket, line)
       return unless line
 
-      @mutex.synchronize { @last_used = Time.now }
       socket.puts JSON.generate(process(line))
     end
 
@@ -109,7 +109,7 @@ module Browserctl
 
     def quietly
       yield
-    rescue StandardError
+    rescue Exception # rubocop:disable Lint/RescueException
       nil
     end
   end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -112,6 +112,13 @@ module Browserctl
       @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
     end
 
+    def compose(workflow_name)
+      source = REGISTRY[workflow_name.to_s]
+      raise WorkflowError, "workflow '#{workflow_name}' not found for composition" unless source
+
+      @steps.concat(source.steps)
+    end
+
     def call(params, client)
       ctx = WorkflowContext.new(resolve_params(params), client)
       execute_steps(ctx)

data/lib/browserctl.rb

@@ -5,3 +5,11 @@ require_relative "browserctl/constants"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"
+
+module Browserctl
+  PLUGIN_COMMANDS = {} # rubocop:disable Style/MutableConstant
+
+  def self.register_command(name, &block)
+    PLUGIN_COMMANDS[name.to_s] = block
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Patrick
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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).
 email:
@@ -96,6 +110,7 @@ files:
 - bin/browserctl
 - bin/browserd
 - bin/setup
+- examples/cloudflare_hitl.rb
 - examples/the_internet/add_remove_elements.rb
 - examples/the_internet/checkboxes.rb
 - examples/the_internet/dropdown.rb
@@ -106,7 +121,10 @@ files:
 - lib/browserctl/commands/cli_output.rb
 - lib/browserctl/commands/click.rb
 - lib/browserctl/commands/fill.rb
+- lib/browserctl/commands/init.rb
+- lib/browserctl/commands/inspect.rb
 - lib/browserctl/commands/open_page.rb
+- lib/browserctl/commands/pause_resume.rb
 - lib/browserctl/commands/record.rb
 - lib/browserctl/commands/screenshot.rb
 - lib/browserctl/commands/snapshot.rb
@@ -118,6 +136,7 @@ files:
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
 - lib/browserctl/server/idle_watcher.rb
+- lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
 - lib/browserctl/version.rb
 - lib/browserctl/workflow.rb