browserctl 0.14.0 → 0.15.0

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

@@ -12,6 +12,9 @@ module Browserctl
         private
 
         def cmd_state_save(req)
+          # registry-wide: state save snapshots across all open pages,
+          # not a single addressed page — picks an arbitrary first session
+          # for cookie capture (cookies are browser-global in CDP).
           first_session = @global_mutex.synchronize { @pages.values.first }
           return { error: "no open pages — open a page before saving state" } unless first_session
 
@@ -40,6 +43,8 @@ module Browserctl
 
         def cmd_state_load(req)
           data = Browserctl::State.load(req[:name], passphrase: req[:passphrase])
+          # registry-wide: state load applies to any open page (cookies are
+          # browser-global); first session is fine as the cookie sink.
           target = @global_mutex.synchronize { @pages.values.first }
           return { error: "no open pages — open a page before loading state" } unless target
 
@@ -47,7 +52,7 @@ module Browserctl
 
           unless req[:skip_auth_check]
             auth = Browserctl::Detectors.auth_required(
-              target.page, cookies: cookies, suggested_flow: data[:manifest][:flow]
+              target.driver, cookies: cookies, suggested_flow: data[:manifest][:flow]
             )
             if auth.triggered
               return Browserctl::AuthRequiredError.new(
@@ -79,7 +84,7 @@ module Browserctl
         def restore_state_cookies(target, cookies)
           cookies.each do |raw|
             c = raw.transform_keys(&:to_sym)
-            target.page.cookies.set(**c.slice(:name, :value, :domain, :path))
+            target.driver.cookies_set(**c.slice(:name, :value, :domain, :path))
           end
         end
 
@@ -101,18 +106,23 @@ module Browserctl
         end
 
         def capture_state_payload
+          # registry-wide: cookies are browser-global, so any session works
+          # as the cookie source.
           first = @global_mutex.synchronize { @pages.values.first }
-          cookies = first.page.cookies.all.values.map(&:to_h)
+          cookies = first.driver.cookies_all.values.map(&:to_h)
 
           local_storage   = {}
           session_storage = {}
           captured_origins = []
 
+          # registry-wide: iterate every page to capture per-origin storage;
+          # snapshot the registry under @global_mutex, then take each
+          # session's own mutex to read storage safely.
           @global_mutex.synchronize { @pages.dup }.each_value do |session|
             session.mutex.synchronize do
-              origin    = session.page.evaluate("location.origin")
-              ls_str    = session.page.evaluate("JSON.stringify({...localStorage})") || "{}"
-              ss_str    = session.page.evaluate("JSON.stringify({...sessionStorage})") || "{}"
+              origin    = session.driver.evaluate("location.origin")
+              ls_str    = session.driver.evaluate("JSON.stringify({...localStorage})") || "{}"
+              ss_str    = session.driver.evaluate("JSON.stringify({...sessionStorage})") || "{}"
               local_storage[origin]   = JSON.parse(ls_str)
               session_storage[origin] = JSON.parse(ss_str)
               captured_origins << origin

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

@@ -13,7 +13,7 @@ module Browserctl
             js    = storage_js_get(store, req[:key])
             return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
 
-            value = session.page.evaluate(js)
+            value = session.driver.evaluate(js)
             { ok: true, value: value }
           end
         end
@@ -25,7 +25,7 @@ module Browserctl
             js    = storage_js_set(store, req[:key], req[:value])
             return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
 
-            session.page.evaluate(js)
+            session.driver.evaluate(js)
             { ok: true }
           end
         end
@@ -37,16 +37,16 @@ module Browserctl
             stores  = req.fetch(:stores, "all")
             data    = {}
 
-            origin = session.page.evaluate("location.origin")
+            origin = session.driver.evaluate("location.origin")
             data[origin] = {}
 
             if %w[local all].include?(stores)
-              local = JSON.parse(session.page.evaluate("JSON.stringify({...localStorage})") || "{}")
+              local = JSON.parse(session.driver.evaluate("JSON.stringify({...localStorage})") || "{}")
               data[origin].merge!(local)
             end
 
             if %w[session all].include?(stores)
-              sess = JSON.parse(session.page.evaluate("JSON.stringify({...sessionStorage})") || "{}")
+              sess = JSON.parse(session.driver.evaluate("JSON.stringify({...sessionStorage})") || "{}")
               data[origin].merge!(sess)
             end
 
@@ -71,7 +71,7 @@ module Browserctl
             key_count = 0
             data.each_value do |keys|
               keys.each do |k, v|
-                session.page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                session.driver.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
                 key_count += 1
               end
             end
@@ -84,8 +84,8 @@ module Browserctl
         def cmd_storage_delete(req)
           with_page(req[:name]) do |session|
             stores = req.fetch(:stores, "all")
-            session.page.evaluate("localStorage.clear()")   if %w[local all].include?(stores)
-            session.page.evaluate("sessionStorage.clear()") if %w[session all].include?(stores)
+            session.driver.evaluate("localStorage.clear()")   if %w[local all].include?(stores)
+            session.driver.evaluate("sessionStorage.clear()") if %w[session all].include?(stores)
             { ok: true }
           end
         end

data/lib/browserctl/server/page_session.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "../driver/ferrum_page_driver"
+
 module Browserctl
   class PageSession
-    attr_reader :page, :mutex, :pause_cv
+    attr_reader :driver, :mutex, :pause_cv
     attr_accessor :ref_registry, :prev_snapshot, :fingerprint_index, :snapshot_id
 
-    def initialize(page)
-      @page              = page
+    # @param page_or_driver [Browserctl::Driver::PageDriver, Object] either a
+    #   PageDriver (preferred) or a raw Ferrum/CDP page (auto-wrapped in
+    #   {Browserctl::Driver::FerrumPageDriver} for back-compat with callers
+    #   that still construct sessions from a raw page).
+    def initialize(page_or_driver)
+      @driver = if page_or_driver.is_a?(Browserctl::Driver::PageDriver)
+                  page_or_driver
+                else
+                  Browserctl::Driver::FerrumPageDriver.new(page_or_driver)
+                end
       @mutex             = Mutex.new
       @pause_cv          = ConditionVariable.new
       @ref_registry      = {}
@@ -16,6 +26,14 @@ module Browserctl
       @paused            = false
     end
 
+    # Back-compat accessor. New handler code calls {#driver} directly; this
+    # returns the underlying Ferrum/CDP page for legacy callers (the CDP
+    # driver's `devtools_info`, the page-lifecycle close path, and a unit
+    # spec).
+    def page
+      @driver.respond_to?(:raw_page) ? @driver.raw_page : @driver
+    end
+
     def paused? = @paused
     def pause!  = (@paused = true)
     def resume! = (@paused = false)

data/lib/browserctl/server/plugin_dispatcher.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require_relative "handlers/error_payload"
+require_relative "../errors"
+
+module Browserctl
+  # Invokes plugin commands registered via {Browserctl.register_command} from
+  # the daemon's command-dispatch loop. Extracted from `CommandDispatcher` in
+  # v0.15 WS-2 PR 5 so plugin invocation gets two daemon-protecting
+  # properties:
+  #
+  # - A per-plugin wall-clock timeout (default
+  #   {Browserctl::DEFAULT_PLUGIN_TIMEOUT}, configurable via `timeout:` on
+  #   `register_command`, opt-out with `timeout: nil`). On expiry the
+  #   dispatcher returns a typed `PLUGIN_TIMED_OUT` response and the daemon
+  #   stays answering subsequent commands.
+  # - A rescue boundary that converts ANY uncaught exception from the plugin
+  #   block into a typed `PLUGIN_FAILED` JSON-RPC response. The plugin name
+  #   is always present in the response's `context` so agents can branch on
+  #   it. The daemon process is never taken down by a buggy plugin.
+  #
+  # Plugins live in the Extension zone (see
+  # `docs/reference/api-stability.md`); the response shape here is documented
+  # in `docs/reference/errors.md`.
+  class PluginDispatcher
+    include CommandDispatcher::Handlers::ErrorPayload
+
+    # @param pages [Hash{String => PageSession}] shared daemon page registry
+    # @param global_mutex [Mutex] mutex guarding the page registry
+    def initialize(pages, global_mutex:)
+      @pages        = pages
+      @global_mutex = global_mutex
+    end
+
+    # Looks up the plugin command for `req[:cmd]` and invokes it under the
+    # timeout / rescue boundary. Returns `nil` if no plugin handles this
+    # command — the caller falls through to its "unknown command" branch.
+    #
+    # @param req [Hash{Symbol => Object}] parsed request
+    # @return [Hash{Symbol => Object}, nil]
+    def dispatch(req)
+      plugin = Browserctl.lookup_plugin_command(req[:cmd])
+      return nil unless plugin
+
+      name    = req[:cmd].to_s
+      session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
+
+      Browserctl.logger.debug("plugin:#{name} #{req[:name]}")
+      invoke(plugin, name, session, req)
+    end
+
+    private
+
+    def invoke(plugin, name, session, req)
+      response = if plugin.timeout
+                   Timeout.timeout(plugin.timeout) { plugin.block.call(session, req) }
+                 else
+                   plugin.block.call(session, req)
+                 end
+      # Verify the response will survive the daemon's JSON serialiser. A plugin
+      # that returns an unencodable object would otherwise blow up at the
+      # socket-write step, outside this rescue boundary.
+      JSON.generate(response)
+      response
+    rescue Timeout::Error
+      Browserctl.logger.warn("plugin:#{name} timed out after #{plugin.timeout}s")
+      error_payload(
+        code: Browserctl::Error::Codes::PLUGIN_TIMED_OUT,
+        message: "plugin '#{name}' timed out after #{plugin.timeout}s",
+        context: { plugin: name, timeout: plugin.timeout }
+      )
+    rescue StandardError, ScriptError => e
+      Browserctl.logger.warn("plugin:#{name} raised #{e.class}: #{e.message}")
+      error_payload(
+        code: Browserctl::Error::Codes::PLUGIN_FAILED,
+        message: "plugin '#{name}' failed: #{e.class}: #{e.message}",
+        context: { plugin: name, exception: e.class.name }
+      )
+    end
+  end
+end

data/lib/browserctl/state/mutator.rb

@@ -16,7 +16,7 @@ module Browserctl
     # caller (CLI or Workflow) can decide how to render them. The CLI maps
     # to a non-zero exit; a Workflow caller may catch and continue.
     class Mutator
-      Result = Struct.new(:save_result, :flow_name, :flow_version, keyword_init: true) do
+      Result = Data.define(:save_result, :flow_name, :flow_version) do
         def to_h
           (save_result || {}).merge(rotated_flow: flow_name)
         end

data/lib/browserctl/tracing.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Pluggable tracing seam shaped like OpenTelemetry's span API, without
+  # taking an OpenTelemetry dependency.
+  #
+  # Backend contract
+  # ----------------
+  #
+  # A tracing backend must respond to two methods:
+  #
+  #   start_span(name, attributes:) -> span
+  #     - `name` is a String (e.g. "command.navigate").
+  #     - `attributes` is a Hash of additional span tags.
+  #     - Returns an opaque span object that will be passed back to
+  #       `end_span`. May return `nil`; `end_span` must tolerate that.
+  #
+  #   end_span(span, status:, attributes: {})
+  #     - `span` is whatever `start_span` returned.
+  #     - `status` is `:ok` or `:error`.
+  #     - `attributes` carries any tags computed at close time
+  #       (notably `duration_ms`). Optional.
+  #
+  # The default backend is `NoopBackend` — it does nothing. A custom
+  # backend is wired in via `Browserctl::Tracing.backend = ...`.
+  # The contract is part of the Extension zone — see
+  # `docs/reference/api-stability.md`.
+  module Tracing
+    # No-op default. Implements the Backend contract above.
+    class NoopBackend
+      def start_span(_name, attributes: {}) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      def end_span(_span, status: :ok, attributes: {}) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+    end
+
+    @backend_mutex = Mutex.new
+    @backend = NoopBackend.new
+
+    class << self
+      def backend
+        @backend_mutex.synchronize { @backend }
+      end
+
+      def backend=(value)
+        @backend_mutex.synchronize { @backend = value || NoopBackend.new }
+      end
+
+      # Wraps a block in a span. Computes `duration_ms` and routes
+      # exceptions to `end_span(span, status: :error)`.
+      def in_span(name, attributes: {})
+        bk = backend
+        span = bk.start_span(name, attributes: attributes)
+        start = monotonic_ms
+        begin
+          result = yield
+        rescue StandardError
+          bk.end_span(span, status: :error, attributes: { duration_ms: monotonic_ms - start })
+          raise
+        end
+        bk.end_span(span, status: :ok, attributes: { duration_ms: monotonic_ms - start })
+        result
+      end
+
+      private
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+    end
+  end
+end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow/page_proxy.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../replay/fingerprint_matcher"
+
+module Browserctl
+  # Per-page wrapper handed to workflow step blocks via `page(:name)`. Forwards
+  # one-liners to the daemon `Client`, unwraps the response, and — when a replay
+  # context is attached — falls back to fingerprint-based rematching when a
+  # selector goes missing.
+  #
+  # Extracted from `workflow.rb` so the proxy can be loaded and reasoned about
+  # independently of the workflow DSL / registry; behaviour is unchanged.
+  class PageProxy
+    attr_accessor :replay_context
+
+    # Declarative wrapper for `unwrap @client.METHOD(@name, ...)` one-liners.
+    # Forwards positional + keyword args verbatim. Pass `extract:` to return
+    # a single key from the client response instead of unwrapping.
+    def self.delegate_unwrap(method_name, extract: nil)
+      if extract
+        define_method(method_name) do |*args, **kwargs|
+          @client.public_send(method_name, @name, *args, **kwargs)[extract]
+        end
+      else
+        define_method(method_name) do |*args, **kwargs|
+          unwrap @client.public_send(method_name, @name, *args, **kwargs)
+        end
+      end
+    end
+
+    def initialize(name, client, replay_context: nil, matcher: nil)
+      @name           = name
+      @client         = client
+      @replay_context = replay_context
+      @matcher        = matcher || Replay::FingerprintMatcher.new
+    end
+
+    delegate_unwrap :navigate
+    delegate_unwrap :snapshot
+    delegate_unwrap :screenshot
+    delegate_unwrap :wait
+    delegate_unwrap :delete_cookies
+    delegate_unwrap :press
+    delegate_unwrap :storage_set
+    delegate_unwrap :dialog_accept
+    delegate_unwrap :dialog_dismiss
+
+    delegate_unwrap :devtools,    extract: :devtools_url
+    delegate_unwrap :url,         extract: :url
+    delegate_unwrap :evaluate,    extract: :result
+    delegate_unwrap :storage_get, extract: :value
+
+    def fill(selector = nil, value = nil, ref: nil)
+      with_selector_fallback(:fill, selector, ref) do |sel, r|
+        @client.fill(@name, sel, value, ref: r)
+      end
+    end
+
+    def click(selector = nil, ref: nil)
+      with_selector_fallback(:click, selector, ref) do |sel, r|
+        @client.click(@name, sel, ref: r)
+      end
+    end
+
+    def hover(selector = nil, ref: nil)
+      with_selector_fallback(:hover, selector, ref) do |sel, r|
+        @client.hover(@name, sel, ref: r)
+      end
+    end
+
+    def upload(selector = nil, path = nil, ref: nil)
+      with_selector_fallback(:upload, selector, ref) do |sel, r|
+        @client.upload(@name, sel, path, ref: r)
+      end
+    end
+
+    def select(selector = nil, value = nil, ref: nil)
+      with_selector_fallback(:select, selector, ref) do |sel, r|
+        @client.select(@name, sel, value, ref: r)
+      end
+    end
+
+    private
+
+    # Issues the wrapped command. If the daemon returns selector_not_found
+    # and a replay context has a fingerprint for this selector, takes a
+    # fresh snapshot, asks the matcher for a candidate, and retries by ref.
+    def with_selector_fallback(cmd, selector, ref)
+      res = yield(selector, ref)
+      return unwrap(res) if !selector_not_found?(res) || ref || !@replay_context || !selector
+
+      fp = @replay_context.fingerprint_for(selector)
+      return unwrap(res) unless fp
+
+      match = @matcher.best(fp, snapshot_entries)
+      unless match
+        @replay_context.record(command: cmd, selector: selector, reason: "no candidate above threshold")
+        return unwrap(res)
+      end
+
+      log_rematch(cmd, selector, match)
+      @replay_context.record(command: cmd, selector: selector,
+                             matched_ref: match.candidate[:ref], score: match.score, reason: "rematch")
+      unwrap(yield(nil, match.candidate[:ref]))
+    end
+
+    def snapshot_entries
+      res = @client.snapshot(@name, format: "elements")
+      Array(res[:snapshot])
+    end
+
+    def selector_not_found?(res)
+      res.is_a?(Hash) && res[:code] == Browserctl::Error::Codes::SELECTOR_NOT_FOUND
+    end
+
+    def log_rematch(cmd, selector, match)
+      warn "[browserctl replay] #{cmd} selector #{selector.inspect} not found — " \
+           "rematched to ref=#{match.candidate[:ref]} (score=#{format('%.2f', match.score)})"
+    end
+
+    def unwrap(res)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+  end
+end

data/lib/browserctl/workflow.rb

@@ -8,6 +8,7 @@ require_relative "flow_registry"
 require_relative "replay/context"
 require_relative "replay/fingerprint_matcher"
 require_relative "replay/snapshot_diff"
+require_relative "workflow/page_proxy"
 
 module Browserctl
   # Workflow-file format version. Workflows are Ruby files; the schema gate
@@ -69,7 +70,7 @@ module Browserctl
   # workflow specs reference these directly).
   ParamDef = CallableDefinition::ParamDef
   StepDef  = CallableDefinition::StepDef
-  StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
+  StepResult = Data.define(:name, :ok, :error)
 
   class WorkflowContext
     include ContextualPersistence
@@ -193,121 +194,6 @@ module Browserctl
     end
   end
 
-  class PageProxy
-    attr_accessor :replay_context
-
-    # Declarative wrapper for `unwrap @client.METHOD(@name, ...)` one-liners.
-    # Forwards positional + keyword args verbatim. Pass `extract:` to return
-    # a single key from the client response instead of unwrapping.
-    def self.delegate_unwrap(method_name, extract: nil)
-      if extract
-        define_method(method_name) do |*args, **kwargs|
-          @client.public_send(method_name, @name, *args, **kwargs)[extract]
-        end
-      else
-        define_method(method_name) do |*args, **kwargs|
-          unwrap @client.public_send(method_name, @name, *args, **kwargs)
-        end
-      end
-    end
-
-    def initialize(name, client, replay_context: nil, matcher: nil)
-      @name           = name
-      @client         = client
-      @replay_context = replay_context
-      @matcher        = matcher || Replay::FingerprintMatcher.new
-    end
-
-    delegate_unwrap :navigate
-    delegate_unwrap :snapshot
-    delegate_unwrap :screenshot
-    delegate_unwrap :wait
-    delegate_unwrap :delete_cookies
-    delegate_unwrap :press
-    delegate_unwrap :storage_set
-    delegate_unwrap :dialog_accept
-    delegate_unwrap :dialog_dismiss
-
-    delegate_unwrap :devtools,    extract: :devtools_url
-    delegate_unwrap :url,         extract: :url
-    delegate_unwrap :evaluate,    extract: :result
-    delegate_unwrap :storage_get, extract: :value
-
-    def fill(selector = nil, value = nil, ref: nil)
-      with_selector_fallback(:fill, selector, ref) do |sel, r|
-        @client.fill(@name, sel, value, ref: r)
-      end
-    end
-
-    def click(selector = nil, ref: nil)
-      with_selector_fallback(:click, selector, ref) do |sel, r|
-        @client.click(@name, sel, ref: r)
-      end
-    end
-
-    def hover(selector = nil, ref: nil)
-      with_selector_fallback(:hover, selector, ref) do |sel, r|
-        @client.hover(@name, sel, ref: r)
-      end
-    end
-
-    def upload(selector = nil, path = nil, ref: nil)
-      with_selector_fallback(:upload, selector, ref) do |sel, r|
-        @client.upload(@name, sel, path, ref: r)
-      end
-    end
-
-    def select(selector = nil, value = nil, ref: nil)
-      with_selector_fallback(:select, selector, ref) do |sel, r|
-        @client.select(@name, sel, value, ref: r)
-      end
-    end
-
-    private
-
-    # Issues the wrapped command. If the daemon returns selector_not_found
-    # and a replay context has a fingerprint for this selector, takes a
-    # fresh snapshot, asks the matcher for a candidate, and retries by ref.
-    def with_selector_fallback(cmd, selector, ref)
-      res = yield(selector, ref)
-      return unwrap(res) if !selector_not_found?(res) || ref || !@replay_context || !selector
-
-      fp = @replay_context.fingerprint_for(selector)
-      return unwrap(res) unless fp
-
-      match = @matcher.best(fp, snapshot_entries)
-      unless match
-        @replay_context.record(command: cmd, selector: selector, reason: "no candidate above threshold")
-        return unwrap(res)
-      end
-
-      log_rematch(cmd, selector, match)
-      @replay_context.record(command: cmd, selector: selector,
-                             matched_ref: match.candidate[:ref], score: match.score, reason: "rematch")
-      unwrap(yield(nil, match.candidate[:ref]))
-    end
-
-    def snapshot_entries
-      res = @client.snapshot(@name, format: "elements")
-      Array(res[:snapshot])
-    end
-
-    def selector_not_found?(res)
-      res.is_a?(Hash) && res[:code] == Browserctl::Error::Codes::SELECTOR_NOT_FOUND
-    end
-
-    def log_rematch(cmd, selector, match)
-      warn "[browserctl replay] #{cmd} selector #{selector.inspect} not found — " \
-           "rematched to ref=#{match.candidate[:ref]} (score=#{format('%.2f', match.score)})"
-    end
-
-    def unwrap(res)
-      raise WorkflowError, res[:error] if res[:error]
-
-      res
-    end
-  end
-
   class WorkflowDefinition < CallableDefinition
     def callable_kind
       :workflow
@@ -359,7 +245,7 @@ module Browserctl
       last_error = nil
       (defn.retry_count + 1).times do
         execute_step_block(ctx, defn)
-        return StepResult.new(name: defn.label, ok: true)
+        return StepResult.new(name: defn.label, ok: true, error: nil)
       rescue StandardError => e
         last_error = e
       end

data/lib/browserctl.rb

@@ -4,16 +4,42 @@ require_relative "browserctl/version"
 require_relative "browserctl/constants"
 require_relative "browserctl/errors"
 require_relative "browserctl/secret_resolvers"
+require_relative "browserctl/tracing"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"
 
 module Browserctl
+  # Default per-plugin command timeout (seconds). Plugins registered via
+  # {register_command} without an explicit `timeout:` are wrapped in this
+  # cap by `Browserctl::PluginDispatcher`. Pass `timeout: nil` on
+  # `register_command` to opt out (not recommended — a runaway plugin will
+  # hold the daemon's command thread until the process is restarted).
+  DEFAULT_PLUGIN_TIMEOUT = 30
+
+  # Value object carried by the plugin registry. `block` is the plugin's
+  # `(session, req) -> response` callable; `timeout` is the per-command wall
+  # clock in seconds (or `nil` for no timeout).
+  PluginCommand = Struct.new(:block, :timeout, keyword_init: true)
+
   @plugin_commands_mutex = Mutex.new
   @plugin_commands = {}
 
-  def self.register_command(name, &block)
-    @plugin_commands_mutex.synchronize { @plugin_commands[name.to_s] = block }
+  # Registers a plugin command callable under `name`. The block receives
+  # `(session, req)` and must return a JSON-RPC-shaped Hash. The daemon wraps
+  # every invocation in a per-plugin timeout (default
+  # {DEFAULT_PLUGIN_TIMEOUT}) and a rescue boundary that converts any
+  # uncaught exception into a typed `PLUGIN_FAILED` response without taking
+  # down the daemon — see {Browserctl::PluginDispatcher}.
+  #
+  # @param name [String, Symbol] command verb on the wire
+  # @param timeout [Numeric, nil] per-invocation timeout in seconds;
+  #   `nil` opts out of the timeout entirely. Defaults to
+  #   {DEFAULT_PLUGIN_TIMEOUT}.
+  def self.register_command(name, timeout: DEFAULT_PLUGIN_TIMEOUT, &block)
+    @plugin_commands_mutex.synchronize do
+      @plugin_commands[name.to_s] = PluginCommand.new(block: block, timeout: timeout)
+    end
   end
 
   def self.lookup_plugin_command(name)