browserctl 0.8.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbfd167f7b8ad961fa91c544eb2636fa1bdc200b40f4738bbf27d9fa5a835cae
-  data.tar.gz: d3fdf8af59edd0c73ea1c415926baefbbe22405343898b46c60b1a18f2e623ac
+  metadata.gz: e27f4db200c9e26aaad474df3f55c1a7c91d602724d900d462a969ce4506ba9f
+  data.tar.gz: fba2acf3be3adf3a3a5ca9b42026abfcbfbeea7a8f8d48e51cd455b710fb403c
 SHA512:
-  metadata.gz: c46b3611cc0a29633558cf0547cd532cefcf4dbecddbbc62e348af27b9c4e5eec498f00bb90892e84a4665281cad57b20e1a73b14b50cff2e579f222301cf549
-  data.tar.gz: f5b8451f0e909212acf63e1eecc49ca607a7d095ea44e4fd4ae42e9b2509b199b7ed35a7158a83764b825dfb6747970e20fe137be465063f50a42c39508bfb68
+  metadata.gz: 8ac208ae09f276efbf624ed297ef725d5144ec9c13624127f7f949491b0156f7a712ee22dc45cbe218addfe88227e7aa9676feaa105ef1813743b30ac3d5cd29
+  data.tar.gz: e5de1ed64d9d88e69c59a6de15bcfefaeb17b28cb578a8f6cddc2f5c97a8ee6d752c92efb6eff5d533d5923bfdcf6f29464a9f8bf06400953f6f874681c75689

data/CHANGELOG.md

@@ -10,6 +10,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0](https://github.com/patrick204nqh/browserctl/compare/v0.8.4...v0.9.0) (2026-05-09)
+
+
+### Features
+
+* split skills into automate + feedback, refresh for v0.9 driver ([#80](https://github.com/patrick204nqh/browserctl/issues/80)) ([65c1a8e](https://github.com/patrick204nqh/browserctl/commit/65c1a8ee25a81aa5337fb8c447781efd8f6ade2e))
+* v0.9 browser-agnostic driver layer + Brave support ([#77](https://github.com/patrick204nqh/browserctl/issues/77)) ([0156c2d](https://github.com/patrick204nqh/browserctl/commit/0156c2defc105d49be038d108fa3da3ed1c4b402))
+
 ## [0.8.4](https://github.com/patrick204nqh/browserctl/compare/v0.8.3...v0.8.4) (2026-05-01)
 
 

data/bin/browserd

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

data/lib/browserctl/detectors.rb

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

data/lib/browserctl/driver/base.rb

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

data/lib/browserctl/driver/cdp.rb

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

data/lib/browserctl/driver/cdp_page.rb

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

data/lib/browserctl/driver.rb

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

data/lib/browserctl/errors.rb

@@ -23,6 +23,7 @@ module Browserctl
   class TimeoutError     < Error; def self.default_code = "timeout"            end
   class KeyNotFound < Error; def self.default_code = "key_not_found" end
   class DaemonUnavailableError < Error; def self.default_code = "daemon_unavailable" end
+  class BrowserNotFound < Error; def self.default_code = "browser_not_found" end
 
   class WorkflowError < Error; def self.default_code = "workflow_error" end
   class SecretResolverError < WorkflowError; def self.default_code = "secret_resolver_error" end

data/lib/browserctl/server/command_dispatcher.rb

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

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

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

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

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

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

@@ -47,7 +47,7 @@ module Browserctl
             if existing
               existing.page.go_to(page_data[:url])
             else
-              new_page = @browser.create_page
+              new_page = @driver.create_page
               new_page.go_to(page_data[:url])
               @global_mutex.synchronize { @pages[page_name.to_s] = PageSession.new(new_page) }
             end
@@ -61,7 +61,7 @@ module Browserctl
           data[:local_storage].each do |origin, keys|
             next if keys.empty?
 
-            tmp_page = @browser.create_page
+            tmp_page = @driver.create_page
             begin
               tmp_page.go_to(origin)
               keys.each do |k, v|

data/lib/browserctl/server.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-require "ferrum"
 require "socket"
 require "json"
 require "fileutils"
 require "timeout"
 require_relative "constants"
 require_relative "logger"
+require_relative "driver"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
 require_relative "server/page_session"
 
 module Browserctl
   class Server
-    def initialize(headless: true, socket_path: SOCKET_PATH, pid_path: PID_PATH)
+    def initialize(headless: true, browser: "chrome", socket_path: SOCKET_PATH, pid_path: PID_PATH)
       @socket_path = socket_path
       @pid_path    = pid_path
-      prepare_runtime(headless)
-      @dispatcher = CommandDispatcher.new(@pages, @browser, global_mutex: @mutex)
+      prepare_runtime(headless, browser)
+      @dispatcher = CommandDispatcher.new(@pages, @driver, global_mutex: @mutex)
     end
 
     def run
@@ -33,26 +33,12 @@ module Browserctl
 
     private
 
-    def prepare_runtime(headless)
+    def prepare_runtime(headless, browser)
       FileUtils.mkdir_p(File.dirname(@socket_path))
-      @browser = init_browser(headless)
+      @driver = Driver::CDP.new(headless: headless, browser: browser)
       init_state
     end
 
-    def init_browser(headless)
-      Ferrum::Browser.new(headless: headless, **ferrum_options)
-    end
-
-    def ferrum_options
-      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
       @pages     = {}
       @last_used = Time.now
@@ -119,7 +105,7 @@ module Browserctl
     def teardown(idle, server)
       idle&.kill
       quietly { server&.close }
-      quietly { Timeout.timeout(5) { @browser.quit } }
+      quietly { Timeout.timeout(5) { @driver.quit } }
       quietly { File.unlink(@socket_path) }
       quietly { File.unlink(@pid_path) }
     end

data/lib/browserctl/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.9.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 description: Named browser sessions, Ruby workflow DSL, and a token-efficient DOM
-  snapshot format. Built on Ferrum (Chrome DevTools Protocol).
+  snapshot format. Built on a browser-agnostic driver layer (Ferrum/CDP backend).
 email:
 - patrick204nqh@gmail.com
 executables:
@@ -185,6 +185,10 @@ files:
 - lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
 - lib/browserctl/detectors.rb
+- lib/browserctl/driver.rb
+- lib/browserctl/driver/base.rb
+- lib/browserctl/driver/cdp.rb
+- lib/browserctl/driver/cdp_page.rb
 - lib/browserctl/errors.rb
 - lib/browserctl/logger.rb
 - lib/browserctl/policy.rb