browserctl 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a09c4e2ffdede17be7f5d14108d72ef30ea75c82bbae924b753474e77c5778c2
-  data.tar.gz: 27dbcdbf87b1e2460ebfc7913dbeecf9780e218f7824e5e9292668db5a0fb59e
+  metadata.gz: '08df95ac04f1480c4e39d857c1472342b8b256a2047cb83808ba62daaf184330'
+  data.tar.gz: 1f67c6b991dd20af3907ab9a803f1021817e6d9b5dbe1774e42f0c509d907067
 SHA512:
-  metadata.gz: 4bb8d31d716febfc0a3ffa593d7d1141dfdf1ad6d548d5d2b8e4ed53a8d04adb9f5861728e3864f65b7a296cc58c93c2e3d66b4f632988508fc699cb841837d0
-  data.tar.gz: 8791f86942d5447fec3dc1aec3391c106a8553f7ef9e99ab372750a7ac18a278e824940a09cca5492bdc8a87e90dcd09ad7e1d04a47c9258e4783c2573bc36e6
+  metadata.gz: 5752121da2c9a9551773b6ab8b9c4f060744f14a6f505d7c38ab9338a99b2cda4012a22869b633be883ad1c810bb717e0edb77da8ef4eb3b7bf8eef19593efde
+  data.tar.gz: 4c44a6cfbb1b4402e30e1911c26bdfb608d3584ba463623fd8c75638ad836dcb428fcb0d99d58d37c2e557b0752c84f288288bad800667e18300cb36ace2570c

data/CHANGELOG.md

@@ -10,6 +10,13 @@ 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.14.0](https://github.com/patrick204nqh/browserctl/compare/v0.13.1...v0.14.0) (2026-05-11)
+
+
+### Features
+
+* validation error codes (v0.14 WS-1 PR 1) ([#179](https://github.com/patrick204nqh/browserctl/issues/179)) ([5475272](https://github.com/patrick204nqh/browserctl/commit/547527264c606e70d0c5509b58a42a10a7a93470))
+
 ## [0.13.1](https://github.com/patrick204nqh/browserctl/compare/v0.13.0...v0.13.1) (2026-05-11)
 
 

data/lib/browserctl/callable_definition.rb

@@ -48,7 +48,13 @@ module Browserctl
     end
 
     def step(label, retry_count: 0, timeout: nil, &block)
-      raise ArgumentError, "#{callable_kind} step '#{label}' requires a block" unless block
+      unless block
+        raise Browserctl::Error.new(
+          "#{callable_kind} step '#{label}' requires a block",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: callable_kind, action: :step, label: label }
+        )
+      end
 
       @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
     end

data/lib/browserctl/client/recording_interceptor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../recording"
+
+module Browserctl
+  class Client
+    # Bridges Client#call to the Recording subsystem. Keeps Client itself a
+    # pure IPC shim — Recording is pluggable via constructor injection.
+    class RecordingInterceptor
+      def initialize(recording: Browserctl::Recording)
+        @recording = recording
+      end
+
+      # Whether recording is currently active. Call sites that need to vary
+      # their request shape (e.g. click/fill passing capture_post_snapshot:)
+      # can ask without touching Recording directly.
+      def active?
+        @recording.active
+      end
+
+      # Returns `true` when active, `nil` otherwise. Matches the shape that
+      # click/fill historically passed as the `capture_post_snapshot` param.
+      def capture_post_snapshot_flag
+        return true if active?
+
+        nil
+      end
+
+      # Called after a successful Client#call to append the command and
+      # response to the active recording log. No-op if the response was
+      # not ok (recording only captures successful interactions).
+      def append(cmd, response:, params: {})
+        return unless response[:ok]
+
+        @recording.append(cmd, response: response, **params)
+      end
+    end
+  end
+end

data/lib/browserctl/client.rb

@@ -4,18 +4,19 @@ require "fileutils"
 require "socket"
 require "json"
 require_relative "constants"
-require_relative "recording"
+require_relative "client/recording_interceptor"
 
 module Browserctl
   # Thin IPC client that wraps each browserd command as a Ruby method call.
   class Client
-    def initialize(socket_path = nil)
+    def initialize(socket_path = nil, recording_interceptor: nil)
       @socket_path = socket_path || auto_discover_socket
+      @recording_interceptor = recording_interceptor
     end
 
     def call(cmd, **params)
       result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
-      Recording.append(cmd, response: result, **params) if result[:ok]
+      recording_interceptor.append(cmd, response: result, params: params)
       result
     rescue Errno::ENOENT, Errno::ECONNREFUSED
       raise DaemonUnavailableError, "browserd is not running — start it with: browserd"
@@ -48,10 +49,16 @@ module Browserctl
     # @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
+      unless selector || ref
+        raise Browserctl::Error.new(
+          "click: provide selector or ref",
+          code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
+          context: { method: :click, name: name }
+        )
+      end
 
       call("click", name: name, selector: selector, ref: ref,
-                    capture_post_snapshot: Recording.active ? true : nil)
+                    capture_post_snapshot: recording_interceptor.capture_post_snapshot_flag)
     end
 
     # Fills an input element with a value.
@@ -61,10 +68,16 @@ module Browserctl
     # @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
+      unless selector || ref
+        raise Browserctl::Error.new(
+          "fill: provide selector or ref",
+          code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
+          context: { method: :fill, name: name }
+        )
+      end
 
       call("fill", name: name, selector: selector, ref: ref, value: value,
-                   capture_post_snapshot: Recording.active ? true : nil)
+                   capture_post_snapshot: recording_interceptor.capture_post_snapshot_flag)
     end
 
     # Takes a screenshot of a named page.
@@ -243,7 +256,13 @@ module Browserctl
     # @param selector [String] CSS selector
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def hover(name, selector = nil, ref: nil)
-      raise ArgumentError, "hover: provide selector or ref:" unless selector || ref
+      unless selector || ref
+        raise Browserctl::Error.new(
+          "hover: provide selector or ref",
+          code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
+          context: { method: :hover, name: name }
+        )
+      end
 
       call("hover", name: name, selector: selector, ref: ref)
     end
@@ -255,7 +274,13 @@ module Browserctl
     # @param ref [String, nil] element ref from a prior snapshot
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def upload(name, selector = nil, path = nil, ref: nil)
-      raise ArgumentError, "upload: provide selector or ref:" unless selector || ref
+      unless selector || ref
+        raise Browserctl::Error.new(
+          "upload: provide selector or ref",
+          code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
+          context: { method: :upload, name: name }
+        )
+      end
 
       call("upload", name: name, selector: selector, ref: ref, path: path)
     end
@@ -267,7 +292,13 @@ module Browserctl
     # @param ref [String, nil] element ref from a prior snapshot
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def select(name, selector = nil, value = nil, ref: nil)
-      raise ArgumentError, "select: provide selector or ref:" unless selector || ref
+      unless selector || ref
+        raise Browserctl::Error.new(
+          "select: provide selector or ref",
+          code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
+          context: { method: :select, name: name }
+        )
+      end
 
       call("select", name: name, selector: selector, ref: ref, value: value)
     end
@@ -327,6 +358,10 @@ module Browserctl
 
     private
 
+    def recording_interceptor
+      @recording_interceptor ||= RecordingInterceptor.new
+    end
+
     def auto_discover_socket
       default = Browserctl.socket_path
       return default if File.exist?(default)

data/lib/browserctl/commands/passphrase_prompt.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Browserctl
+  module Commands
+    # Stdin/stderr passphrase prompting for `browserctl state` commands.
+    # Honours `BROWSERCTL_STATE_PASSPHRASE` for non-interactive use; otherwise
+    # reads from a tty with echo disabled and optional confirmation.
+    module PassphrasePrompt
+      module_function
+
+      # @return [String]
+      def read(confirm: false)
+        return ENV["BROWSERCTL_STATE_PASSPHRASE"] if ENV["BROWSERCTL_STATE_PASSPHRASE"]
+
+        pass = ask("Passphrase: ")
+        if confirm
+          confirm_pass = ask("Confirm passphrase: ")
+          abort "Passphrases do not match." unless pass == confirm_pass
+        end
+        pass
+      end
+
+      # Peek at the manifest first so we only prompt when the bundle is
+      # actually encrypted.
+      def needed_for?(client, name)
+        info = client.state_info(name)
+        return false if info[:error] || info["error"]
+
+        manifest = info[:info] || info["info"] || {}
+        manifest[:encrypted] || manifest["encrypted"] || false
+      end
+
+      def ask(label)
+        $stderr.print(label)
+        value = $stdin.noecho(&:gets).to_s.chomp
+        $stderr.puts
+        value
+      end
+      private_class_method :ask
+    end
+  end
+end

data/lib/browserctl/commands/state.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "io/console"
 require "json"
 require_relative "cli_output"
 require_relative "output_format"
+require_relative "passphrase_prompt"
 
 module Browserctl
   module Commands
@@ -23,7 +23,6 @@ module Browserctl
 
       def self.run(client, args)
         sub = args.shift or abort USAGE
-
         if (m = DAEMON_SUBCOMMANDS[sub])
           sub == "list" ? send(m, client) : send(m, client, args)
         elsif (m = LOCAL_SUBCOMMANDS[sub])
@@ -39,22 +38,14 @@ module Browserctl
         flow    = extract_value!(args, "--flow")
         name    = args.shift or abort "usage: browserctl state save <name> [--encrypt] " \
                                       "[--origins a,b] [--flow NAME]"
-
-        passphrase = encrypt ? prompt_passphrase(confirm: true) : nil
-        origin_list = parse_origins(origins)
-
+        passphrase  = encrypt ? PassphrasePrompt.read(confirm: true) : nil
+        origin_list = origins ? origins.split(",").map(&:strip).reject(&:empty?) : nil
         print_result(client.state_save(name, origins: origin_list, flow: flow, passphrase: passphrase))
       end
 
-      def self.parse_origins(value)
-        return nil unless value
-
-        value.split(",").map(&:strip).reject(&:empty?)
-      end
-
       def self.run_load(client, args)
         name = args.shift or abort "usage: browserctl state load <name>"
-        passphrase = state_needs_passphrase?(client, name) ? prompt_passphrase : nil
+        passphrase = PassphrasePrompt.needed_for?(client, name) ? PassphrasePrompt.read : nil
         print_result(client.state_load(name, passphrase: passphrase))
       end
 
@@ -72,67 +63,33 @@ module Browserctl
         print_result(client.state_delete(name))
       end
 
-      # Re-runs the flow bound to <name> and re-saves the bundle. The flow is
-      # read from the manifest (set when the bundle was originally produced
-      # via `state save --flow ...`). Params come from --params or k=v pairs.
+      # Re-runs the flow bound to <name> and re-saves it. Mutation logic
+      # lives in {Browserctl::State::Mutator}; this method is CLI plumbing.
       def self.run_rotate(client, args)
-        require "browserctl/flow_registry"
+        require "browserctl/state/mutator"
+        require "browserctl/runner"
         page_name   = extract_value!(args, "--page")
         params_path = extract_value!(args, "--params")
         name        = args.shift or abort "usage: browserctl state rotate <name> " \
                                           "[--page NAME] [--params FILE] [--key value ...]"
 
-        manifest = read_manifest!(client, name)
-        flow     = resolve_bound_flow!(manifest)
-        params   = build_rotate_params(params_path, args)
-        page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
-
-        flow.run(page: page_proxy, client: client, **params)
+        file_params = params_path ? Browserctl::Runner.load_params_file(params_path) : {}
+        cli_params  = args.each_slice(2).to_h { |flag, val| [flag.to_s.sub(/\A--/, "").to_sym, val] }
+        page        = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
 
-        save_result = client.state_save(name,
-                                        flow: flow.name,
-                                        flow_version: flow.version_string,
-                                        origins: manifest[:origins])
-        print_result(save_result.merge(rotated_flow: flow.name))
+        result = Browserctl::State::Mutator.new(client: client)
+                                           .rotate(name: name, params: file_params.merge(cli_params), page: page)
+        print_result(result.to_h)
       rescue Browserctl::FlowError => e
         warn "Error: #{e.message}"
         exit 1
       end
 
-      def self.read_manifest!(client, name)
-        info = client.state_info(name)
-        abort "Error: #{info[:error] || info['error']}" if info[:error] || info["error"]
-
-        info[:info] || info["info"] || {}
-      end
-      private_class_method :read_manifest!
-
-      def self.resolve_bound_flow!(manifest)
-        flow_name = manifest[:flow] || manifest["flow"]
-        abort "Error: state has no bound flow — re-save with `state save --flow NAME` first" if flow_name.nil? ||
-                                                                                                flow_name.to_s.empty?
-
-        flow = Browserctl::FlowRegistry.resolve(flow_name)
-        abort "Error: flow '#{flow_name}' not found in registry" unless flow
-
-        flow
-      end
-      private_class_method :resolve_bound_flow!
-
-      def self.build_rotate_params(params_path, args)
-        require "browserctl/runner"
-        file_params = params_path ? Browserctl::Runner.load_params_file(params_path) : {}
-        cli_params  = args.each_slice(2).to_h { |flag, val| [flag.to_s.sub(/\A--/, "").to_sym, val] }
-        file_params.merge(cli_params)
-      end
-      private_class_method :build_rotate_params
-
       def self.run_export(args)
         name        = args.shift or abort "usage: browserctl state export <name> <destination>"
         destination = args.shift or abort "usage: browserctl state export <name> <destination>"
         require "browserctl/state"
-        result = Browserctl::State.export(name, destination)
-        OutputFormat.current.emit(result)
+        OutputFormat.current.emit(Browserctl::State.export(name, destination))
       rescue Browserctl::State::Transport::TransportError, Browserctl::Error, ArgumentError => e
         warn "Error: #{e.message}"
         exit 1
@@ -142,53 +99,19 @@ module Browserctl
         name_override = extract_value!(args, "--name")
         source        = args.shift or abort "usage: browserctl state import <source> [--name NAME]"
         require "browserctl/state"
-        result = Browserctl::State.import(source, name: name_override)
-        OutputFormat.current.emit(result)
-      rescue Browserctl::State::Transport::TransportError,
-             Browserctl::State::Bundle::BundleError,
+        OutputFormat.current.emit(Browserctl::State.import(source, name: name_override))
+      rescue Browserctl::State::Transport::TransportError, Browserctl::State::Bundle::BundleError,
              Browserctl::Error, ArgumentError => e
         warn "Error: #{e.message}"
         exit 1
       end
 
-      private_class_method :parse_origins
-
       def self.extract_value!(args, flag)
-        idx = args.index(flag)
-        return nil unless idx
-
+        idx = args.index(flag) or return nil
         args.delete_at(idx)
         args.delete_at(idx) or abort "missing value for #{flag}"
       end
       private_class_method :extract_value!
-
-      def self.prompt_passphrase(confirm: false)
-        return ENV["BROWSERCTL_STATE_PASSPHRASE"] if ENV["BROWSERCTL_STATE_PASSPHRASE"]
-
-        $stderr.print "Passphrase: "
-        pass = $stdin.noecho(&:gets).to_s.chomp
-        $stderr.puts
-
-        if confirm
-          $stderr.print "Confirm passphrase: "
-          confirm_pass = $stdin.noecho(&:gets).to_s.chomp
-          $stderr.puts
-          abort "Passphrases do not match." unless pass == confirm_pass
-        end
-
-        pass
-      end
-      private_class_method :prompt_passphrase
-
-      # Peek at the manifest first so we only prompt for a passphrase when needed.
-      def self.state_needs_passphrase?(client, name)
-        info = client.state_info(name)
-        return false if info[:error] || info["error"]
-
-        manifest = info[:info] || info["info"] || {}
-        manifest[:encrypted] || manifest["encrypted"] || false
-      end
-      private_class_method :state_needs_passphrase?
     end
   end
 end

data/lib/browserctl/commands/trace.rb

@@ -1,112 +1,67 @@
 # frozen_string_literal: true
 
 require "json"
-require "time"
 require_relative "../logger"
 require_relative "../redactor"
 require_relative "../secret_resolver_registry"
+require_relative "../trace/event_stream"
+require_relative "../trace/renderer"
 require_relative "output_format"
 
 module Browserctl
   module Commands
     # `browserctl trace [<session>] [--no-redact]` — pretty timeline of
-    # structured log events across cli.log + daemon.log. Defaults to most
-    # recent session.
-    #
-    # Loose categorisation by inspecting common keys (event/snapshot/request/
-    # error). No schema is enforced — this command is tolerant of any JSONL
-    # produced by Browserctl::JsonlFormatter.
-    #
-    # Redaction: ON by default. Secret values are sourced from current ENV
-    # patterns (`*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD`) and any values
-    # captured by `SecretResolverRegistry` during this process. Pass
-    # `--no-redact` to disable (local debugging only). Note: when replaying
-    # historical traces from a previous process, registry-captured values are
-    # gone — only current ENV patterns apply.
+    # structured log events across cli.log + daemon.log. Thin CLI dispatcher;
+    # parsing lives in `Browserctl::Trace::EventStream`, rendering in
+    # `Browserctl::Trace::Renderer`, redaction in `Browserctl::Redactor`.
     module Trace
       USAGE = "Usage: browserctl trace [<session>] [--no-redact]"
       NO_REDACT_WARNING = "[browserctl] traces include unredacted secret values; " \
                           "do not paste this output publicly."
 
-      LEVEL_COLORS = {
-        "DEBUG" => "\e[2;37m", # dim grey
-        "INFO" => "\e[36m",    # cyan
-        "WARN" => "\e[33m",    # yellow
-        "ERROR" => "\e[31m" # red
-      }.freeze
-      RESET = "\e[0m"
-
-      CATEGORY_ICONS = {
-        error: "!",
-        snapshot: "S",
-        network: "N",
-        event: "."
-      }.freeze
-
-      OMIT_KEYS = %w[ts level component event msg].freeze
-
       def self.run(args, log_dir: Browserctl.log_dir, out: $stdout, err: $stderr)
         abort USAGE if args.include?("-h") || args.include?("--help")
         args = args.dup
         redact = !args.delete("--no-redact")
         session_filter = args.shift
-        redactor = resolve_redactor(redact, err)
-        records = collect_records(log_dir, session_filter, out)
-        emit_records(records, redactor, out) if records
-      end
+        redactor = redact ? build_redactor : (warn_no_redact(err) || nil)
 
-      def self.resolve_redactor(redact, err)
-        return nil unless redact
+        stream = Browserctl::Trace::EventStream.new(log_dir, session_filter: session_filter)
+        if stream.empty?
+          emit_empty(empty_message(log_dir, session_filter), out)
+          return
+        end
 
-        build_redactor
-      ensure
-        warn_no_redact(err) unless redact
+        emit(stream, redactor, out)
       end
 
-      def self.collect_records(log_dir, session_filter, out)
-        records = load_records(log_dir)
-        if records.empty?
-          emit_empty("No log entries found in #{log_dir}", out)
-          return nil
-        end
-
-        records = filter_session(records, session_filter)
-        if records.empty?
-          emit_empty("No entries match session=#{session_filter}", out)
-          return nil
+      def self.emit(stream, redactor, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit({ records: stream.records.map { |r| redact_record(r, redactor) } }, io: out)
+        elsif !fmt.silent?
+          Browserctl::Trace::Renderer.new(io: out, redactor: redactor).render(stream)
         end
+      end
 
-        records
+      def self.empty_message(log_dir, session_filter)
+        session_filter ? "No entries match session=#{session_filter}" : "No log entries found in #{log_dir}"
       end
 
       def self.emit_empty(message, out)
         OutputFormat.current.emit({ records: [], message: message }, message, io: out)
       end
 
-      def self.emit_records(records, redactor, out)
-        fmt = OutputFormat.current
-        if fmt.json?
-          fmt.emit({ records: records.map { |r| redact_record(r, redactor) } }, io: out)
-        elsif !fmt.silent?
-          render(records, out: out, redactor: redactor)
-        end
-      end
-
       def self.redact_record(record, redactor)
         return record unless redactor
 
-        line = JSON.generate(record)
-        JSON.parse(redactor.redact(line))
+        JSON.parse(redactor.redact(JSON.generate(record)))
       rescue JSON::ParserError
         record
       end
 
       def self.build_redactor
-        extra = if defined?(Browserctl::SecretResolverRegistry)
-                  Browserctl::SecretResolverRegistry.resolved_values
-                else
-                  []
-                end
+        extra = defined?(Browserctl::SecretResolverRegistry) ? Browserctl::SecretResolverRegistry.resolved_values : []
         Browserctl::Redactor.from_env(extra: extra)
       rescue StandardError
         Browserctl::Redactor.new(secrets: [])
@@ -114,103 +69,8 @@ module Browserctl
 
       def self.warn_no_redact(err)
         err&.puts NO_REDACT_WARNING
-      end
-
-      def self.load_records(log_dir)
-        paths = Dir.glob(File.join(log_dir, "{cli,daemon}.log"))
-        records = paths.flat_map do |path|
-          File.foreach(path).filter_map { |line| parse_line(line) }
-        end
-        records.sort_by { |r| r["ts"].to_s }
-      end
-
-      def self.parse_line(line)
-        line = line.strip
-        return nil if line.empty?
-
-        JSON.parse(line)
-      rescue JSON::ParserError
         nil
       end
-
-      # Session resolution. When session_id is stamped on records (future PR),
-      # filter/select by it. Otherwise, treat the entire merged stream as one
-      # session — caller can scope by tailing/rotating logs.
-      # TODO: stamp session_id on every log line so this scopes correctly.
-      def self.filter_session(records, session_filter)
-        if session_filter
-          records.select { |r| r["session_id"].to_s == session_filter }
-        else
-          ids = records.map { |r| r["session_id"] }.compact.uniq
-          if ids.empty?
-            records
-          else
-            recent = ids.last
-            records.select { |r| r["session_id"] == recent }
-          end
-        end
-      end
-
-      def self.render(records, out:, redactor: nil)
-        tty = out.respond_to?(:tty?) && out.tty?
-        records.each { |r| out.puts(format_line(r, tty: tty, redactor: redactor)) }
-      end
-
-      def self.format_line(record, tty:, redactor: nil)
-        level = (record["level"] || "INFO").to_s
-        line  = format("%-12<ts>s %<icon>s %-5<level>s %-7<comp>s %-22<label>s %<ctx>s",
-                       ts: format_ts(record["ts"]),
-                       icon: CATEGORY_ICONS.fetch(categorise(record), "."),
-                       level: level,
-                       comp: (record["component"] || "?").to_s,
-                       label: event_label(record),
-                       ctx: context_snippet(record)).rstrip
-
-        line = redactor.redact(line) if redactor
-        tty ? colourise(line, level) : line
-      end
-
-      def self.format_ts(timestamp)
-        Time.iso8601(timestamp.to_s).strftime("%H:%M:%S.%L")
-      rescue ArgumentError, TypeError
-        "??:??:??.???"
-      end
-
-      def self.categorise(record)
-        return :error    if record["level"] == "ERROR" || record["error"]
-        return :snapshot if record["snapshot"]
-        return :network  if record["request"] || record["response"] || record["url"]
-
-        :event
-      end
-
-      def self.event_label(record)
-        (record["event"] || record["snapshot"] || record["request"] ||
-          record["msg"] || "-").to_s.slice(0, 22)
-      end
-
-      # Compact "k=v k=v" snippet of remaining structured keys, capped to keep
-      # the timeline scannable. Skips fields already shown in fixed columns.
-      def self.context_snippet(record)
-        pairs = record.except(*OMIT_KEYS)
-        return "" if pairs.empty?
-
-        pairs.map { |k, v| "#{k}=#{format_value(v)}" }.join(" ").slice(0, 120)
-      end
-
-      def self.format_value(value)
-        case value
-        when String  then value.length > 40 ? "#{value[0, 37]}..." : value
-        when Array   then "[#{value.length}]"
-        when Hash    then "{#{value.keys.length}}"
-        else value.to_s
-        end
-      end
-
-      def self.colourise(line, level)
-        colour = LEVEL_COLORS[level] || ""
-        "#{colour}#{line}#{RESET}"
-      end
     end
   end
 end

data/lib/browserctl/driver/cdp.rb

@@ -80,7 +80,11 @@ module Browserctl
         when "brave"
           resolve_brave_path
         else
-          raise ArgumentError, "Unknown browser: #{@browser.inspect}"
+          raise Browserctl::Error.new(
+            "Unknown browser: #{@browser.inspect}",
+            code: Browserctl::Error::Codes::VALIDATION_FAILED,
+            context: { browser: @browser }
+          )
         end
       end