browserctl 0.10.0 → 0.11.0

data/lib/browserctl/recording.rb

@@ -2,12 +2,13 @@
 
 require "json"
 require "date"
+require "time"
 require "fileutils"
 require "tmpdir"
 require "uri"
 
 module Browserctl
-  class Recording
+  class Recording # rubocop:disable Metrics/ClassLength
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
@@ -15,6 +16,22 @@ module Browserctl
 
     SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
 
+    # Selector tokens that signal a fill is targeting a secret-shaped field.
+    # The captured group (or matched substring) is used as the inferred field
+    # name; that name later drives the generated `secret_ref:` placeholder.
+    SECRET_FIELD_PATTERN = /\b(password|passwd|api[_-]?key|token|secret|otp|pin|client[_-]?secret|access[_-]?token)\b/i
+
+    # Conservative thresholds for inferring an explicit wait between recorded
+    # steps. Gaps shorter than the threshold come from natural input cadence;
+    # gaps above it usually mean the page actually had work to do.
+    WAIT_THRESHOLD_SECONDS = 1.5
+    WAIT_PADDING_SECONDS   = 5
+    WAIT_FLOOR_SECONDS     = 5
+
+    # Bumped when the recording log shape changes in a way that older
+    # tooling (workflow generate, replay) cannot read.
+    LOG_FORMAT = "v0.11"
+
     def self.start(name)
       FileUtils.mkdir_p(RECORDINGS_DIR, mode: 0o700)
       FileUtils.mkdir_p(File.dirname(STATE_FILE))
@@ -22,6 +39,14 @@ module Browserctl
       FileUtils.rm_f(log_path(name))
       FileUtils.touch(log_path(name))
       File.chmod(0o600, log_path(name))
+      File.open(log_path(name), "a") do |f|
+        f.puts JSON.generate(
+          cmd: "_meta",
+          log_format: LOG_FORMAT,
+          recording: name,
+          started_at: Time.now.utc.iso8601
+        )
+      end
       name
     end
 
@@ -37,40 +62,45 @@ module Browserctl
       File.exist?(STATE_FILE) ? File.read(STATE_FILE).strip : nil
     end
 
-    def self.append(cmd, **attrs)
+    def self.append(cmd, response: nil, **attrs)
       name = active
       return unless name
       return unless RECORDABLE.include?(cmd.to_s)
 
       if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
-        record_ref_interaction(name, cmd.to_s, attrs)
+        record_ref_interaction(name, cmd.to_s, attrs, response)
         return
       end
 
       attrs = prepare_attrs(cmd.to_s, attrs)
+      entry = { cmd: cmd.to_s, ts: now }.merge(attrs.transform_keys(&:to_s))
+      entry.merge!(replay_metadata(response)) if response
 
       File.open(log_path(name), "a") do |f|
-        f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
+        f.puts JSON.generate(entry)
       end
     end
 
-    def self.generate_workflow(name, output_path: nil)
+    def self.generate_workflow(name, output_path: nil, keep_log: false)
       log = log_path(name)
       raise "no recording found for '#{name}'" unless File.exist?(log)
 
-      lines = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      raw   = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      lines = raw.reject { |l| l[:cmd] == "_meta" }
       ruby  = build_workflow_ruby(name, lines)
       File.write(output_path, ruby) if output_path
+      warn_about_ref_interactions(lines)
+      ruby
+    ensure
+      FileUtils.rm_f(log) if log && !keep_log
+    end
 
+    def self.warn_about_ref_interactions(lines)
       ref_count = lines.count { |l| l[:cmd] == "_ref_interaction" }
-      if ref_count.positive?
-        warn "Warning: #{ref_count} ref-based interaction(s) were captured but cannot be replayed by ref."
-        warn "Search the generated workflow for 'TODO: ref-based' and replace with stable CSS selectors."
-      end
+      return unless ref_count.positive?
 
-      ruby
-    ensure
-      FileUtils.rm_f(log) if log
+      warn "Warning: #{ref_count} ref-based interaction(s) were captured but cannot be replayed by ref."
+      warn "Search the generated workflow for 'TODO: ref-based' and replace with stable CSS selectors."
     end
 
     class << self
@@ -80,26 +110,163 @@ module Browserctl
         File.join(RECORDINGS_DIR, "#{name}.jsonl")
       end
 
-      def record_ref_interaction(recording_name, cmd, attrs)
-        entry = { cmd: "_ref_interaction", action: cmd, ref: attrs[:ref], name: attrs[:name] }
+      def record_ref_interaction(recording_name, cmd, attrs, response)
+        entry = { cmd: "_ref_interaction", ts: now, action: cmd, ref: attrs[:ref], name: attrs[:name] }
+        entry.merge!(replay_metadata(response)) if response
         File.open(log_path(recording_name), "a") do |f|
           f.puts JSON.generate(entry)
         end
       end
 
+      # Pulls the replay-relevant fields out of a daemon response. Each
+      # is optional — older daemons or non-resolving commands may omit
+      # any of them.
+      def now
+        Time.now.utc.to_f
+      end
+
+      def replay_metadata(response)
+        meta = {}
+        meta[:ref]                  = response[:ref]                  if response[:ref]
+        meta[:fingerprint]          = response[:fingerprint]          if response[:fingerprint]
+        meta[:snapshot_id]          = response[:snapshot_id]          if response[:snapshot_id]
+        meta[:postcondition_hint]   = response[:postcondition_hint]   if response[:postcondition_hint]
+        meta[:post_snapshot_digest] = response[:post_snapshot_digest] if response[:post_snapshot_digest]
+        meta.transform_keys(&:to_s)
+      end
+
       def build_workflow_ruby(name, commands)
-        steps = commands.map { |c| build_step(c) }.join("\n\n")
+        steps   = annotated_steps(commands).join("\n\n")
+        secrets = commands.map { |c| c[:secret_field] }.compact.uniq
+        header  = secret_header(secrets)
         <<~RUBY
           # frozen_string_literal: true
-
+          #{header}
           Browserctl.workflow #{name.inspect} do
             desc "Recorded on #{Date.today}"
-
+          #{secrets.map { |f| "  param :secret_#{f}, secret: true" }.join("\n")}
           #{steps.gsub(/^/, '  ')}
           end
         RUBY
       end
 
+      # Walks the recorded events and emits the rendered step strings,
+      # interleaving inferred waits before selector-driven actions whose
+      # preceding gap exceeds WAIT_THRESHOLD_SECONDS, and inferred URL
+      # postconditions after click/fill steps that triggered navigation.
+      def annotated_steps(commands)
+        last_url = {}
+        commands.each_with_index.flat_map do |cmd, i|
+          rendered = []
+          if i.positive? && (wait = inferred_wait_step(commands[i - 1], cmd))
+            rendered << wait
+          end
+          rendered << build_step(cmd)
+          if (post = url_postcondition_step(cmd, last_url))
+            rendered << post
+          end
+          if (snap = snapshot_postcondition_step(cmd))
+            rendered << snap
+          end
+          update_last_url!(cmd, last_url)
+          rendered
+        end
+      end
+
+      # Emits a postcondition assertion when a click/fill resulted in a URL
+      # change. Compares the canonical (scheme+host+path) form so query
+      # strings and fragments don't make every replay flaky.
+      def url_postcondition_step(cmd, last_url)
+        return nil unless %w[click fill].include?(cmd[:cmd])
+        return nil unless cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
+
+        page = cmd[:name]
+        observed = cmd[:postcondition_hint][:url]
+        prior    = last_url[page]
+        return nil if canonical_url(observed) == canonical_url(prior)
+
+        prefix = canonical_url(observed)
+        return nil unless prefix
+
+        <<~RUBY.chomp
+          step "assert url after #{cmd[:cmd]} on #{page}" do
+            current = page(:#{page}).url
+            assert current.start_with?(#{prefix.inspect}), "expected URL to start with #{prefix}, got \#{current}"
+          end
+        RUBY
+      end
+
+      # Emits an assert_snapshot_stable step when the recording captured a
+      # post-step DOM digest. Under workflow run --check the helper records
+      # drift on mismatch instead of raising, so a wiggly page surfaces in
+      # the report rather than failing the run outright.
+      def snapshot_postcondition_step(cmd)
+        return nil unless %w[click fill].include?(cmd[:cmd])
+        return nil unless cmd[:post_snapshot_digest]
+
+        page = cmd[:name]
+        digest = cmd[:post_snapshot_digest]
+        <<~RUBY.chomp
+          step "assert post-snapshot stable on #{page}" do
+            assert_snapshot_stable(:#{page}, expected_digest: #{digest.inspect})
+          end
+        RUBY
+      end
+
+      def update_last_url!(cmd, last_url)
+        case cmd[:cmd]
+        when "navigate", "page_open"
+          last_url[cmd[:name]] = cmd[:url] if cmd[:url]
+        when "click", "fill"
+          observed = cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
+          last_url[cmd[:name]] = observed if observed
+        end
+      end
+
+      def canonical_url(url)
+        return nil if url.nil? || url.empty?
+
+        uri = URI.parse(url)
+        path = uri.path.to_s
+        path = "/" if path.empty?
+        "#{uri.scheme}://#{uri.host}#{path}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def inferred_wait_step(prev, current)
+        return nil unless %w[fill click].include?(current[:cmd])
+        return nil unless current[:selector]
+
+        delta = elapsed(prev, current)
+        return nil unless delta && delta >= WAIT_THRESHOLD_SECONDS
+
+        timeout = [WAIT_FLOOR_SECONDS, delta.ceil + WAIT_PADDING_SECONDS].max
+        page = current[:name]
+        sel  = current[:selector]
+        <<~RUBY.chomp
+          # inferred wait: prior step took ~#{format('%.1f', delta)}s
+          step "wait for #{sel} on #{page}" do
+            page(:#{page}).wait(#{sel.inspect}, timeout: #{timeout})
+          end
+        RUBY
+      end
+
+      def elapsed(prev, current)
+        return nil unless prev && current && prev[:ts] && current[:ts]
+
+        current[:ts] - prev[:ts]
+      end
+
+      def secret_header(secrets)
+        return "" if secrets.empty?
+
+        lines = ["# TODO: review the following secret-shaped fields detected during recording.",
+                 "# Configure a secret_ref: source for each before running:"]
+        secrets.each { |f| lines << "#   - secret_#{f}" }
+        "\n#{lines.join("\n")}\n"
+      end
+
       def build_step(cmd)
         label, body = step_parts(cmd)
 
@@ -113,12 +280,13 @@ module Browserctl
                  "# end"
         end
 
-        url = cmd[:url].to_s
-        if url.include?("[REDACTED]")
-          "# NOTE: sensitive query params were redacted during recording\nstep #{label.inspect} do\n  #{body}\nend"
-        else
-          "step #{label.inspect} do\n  #{body}\nend"
-        end
+        prefix = []
+        prefix << "# NOTE: sensitive query params were redacted during recording" \
+          if cmd[:url].to_s.include?("[REDACTED]")
+        prefix << "# fingerprint fallback: #{cmd[:fingerprint].to_json}" if cmd[:fingerprint]
+
+        head = prefix.empty? ? "" : "#{prefix.join("\n")}\n"
+        "#{head}step #{label.inspect} do\n  #{body}\nend"
       end
 
       def step_parts(cmd)
@@ -143,8 +311,9 @@ module Browserctl
         page = cmd[:name]
         case cmd[:cmd]
         when "fill"
+          value_arg = cmd[:secret_field] ? "params[:secret_#{cmd[:secret_field]}]" : "params[:fill_value]"
           ["fill #{cmd[:selector]} on #{page}",
-           "page(:#{page}).fill(#{cmd[:selector].inspect}, params[:fill_value])"]
+           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{value_arg})"]
         when "click"
           ["click #{cmd[:selector]} on #{page}",
            "page(:#{page}).click(#{cmd[:selector].inspect})"]
@@ -152,11 +321,28 @@ module Browserctl
       end
 
       def prepare_attrs(cmd, attrs)
-        attrs = attrs.except(:value) if cmd == "fill"
+        attrs = attrs.except(:capture_post_snapshot)
+        if cmd == "fill"
+          attrs = attrs.except(:value)
+          field = infer_secret_field(attrs[:selector])
+          if field
+            attrs[:secret_hint]  = true
+            attrs[:secret_field] = field
+          end
+        end
         attrs[:url] = redact_url(attrs[:url]) if %w[navigate page_open].include?(cmd) && attrs[:url]
         attrs
       end
 
+      def infer_secret_field(selector)
+        return nil unless selector
+
+        match = selector.match(SECRET_FIELD_PATTERN)
+        return nil unless match
+
+        match[1].downcase.gsub(/[^a-z0-9]/, "_")
+      end
+
       def redact_url(url)
         uri = URI.parse(url)
         return url if uri.query.nil?

data/lib/browserctl/replay/context.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Replay
+    # Per-page replay context carried by PageProxy during a workflow run
+    # generated from a recording.
+    #
+    # Holds the recorded fingerprint for each selector that the workflow
+    # interacts with. When a selector-driven command fails with
+    # selector_not_found at replay time, the proxy looks up the fingerprint
+    # here and asks FingerprintMatcher to find a candidate in the live
+    # snapshot. The matched element's stable ref is then re-used to retry
+    # the original command.
+    #
+    # Drift events (rematches, threshold misses) are accumulated on the
+    # context so the surrounding workflow runner can render them into a
+    # drift report at end-of-run.
+    class Context
+      DriftEvent = Struct.new(:command, :selector, :matched_ref, :score, :reason, keyword_init: true)
+
+      attr_reader :drift_events
+
+      def initialize(fingerprints: {})
+        @fingerprints = fingerprints
+        @drift_events = []
+      end
+
+      def fingerprint_for(selector)
+        @fingerprints[selector]
+      end
+
+      def record(command:, selector:, matched_ref: nil, score: nil, reason: nil)
+        @drift_events << DriftEvent.new(
+          command: command, selector: selector,
+          matched_ref: matched_ref, score: score, reason: reason
+        )
+      end
+    end
+  end
+end

data/lib/browserctl/replay/fingerprint_matcher.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Replay
+    # Scores candidate snapshot entries against a recorded fingerprint and
+    # returns the best match above a configurable threshold.
+    #
+    # Inputs are the wire-shape fingerprints emitted by Snapshot::Fingerprint:
+    #   { text:, role:, neighbors: [...], position: { index:, depth: } }
+    #
+    # Score is a weighted sum in [0.0, 1.0]:
+    #   text      0.40   (exact match; case-insensitive)
+    #   role      0.20   (exact match)
+    #   neighbors 0.25   (Jaccard over the neighbor sets)
+    #   position  0.15   (proximity in (index, depth) space)
+    #
+    # Defaults reflect the v0.11 acceptance bar: text + role together (0.60)
+    # are enough to clear the default threshold, so a renamed neighbor or a
+    # shifted index doesn't break replay.
+    class FingerprintMatcher
+      DEFAULT_THRESHOLD = 0.6
+      WEIGHTS = { text: 0.40, role: 0.20, neighbors: 0.25, position: 0.15 }.freeze
+
+      Match = Struct.new(:candidate, :score, keyword_init: true)
+
+      def initialize(threshold: DEFAULT_THRESHOLD, weights: WEIGHTS)
+        @threshold = threshold
+        @weights = weights
+      end
+
+      # Returns the highest-scoring candidate entry above the threshold, or
+      # nil if no candidate qualifies. `candidates` must be an array of
+      # snapshot entries (hashes with a :fingerprint key). The returned
+      # Match wraps the candidate hash and the numeric score.
+      def best(target_fp, candidates)
+        scored = candidates
+                 .map { |c| Match.new(candidate: c, score: score(target_fp, c[:fingerprint])) }
+                 .sort_by { |m| -m.score }
+
+        winner = scored.first
+        return nil unless winner && winner.score >= @threshold
+
+        winner
+      end
+
+      def score(target, candidate)
+        return 0.0 unless target && candidate
+
+        (@weights[:text] * text_score(target[:text], candidate[:text])) +
+          (@weights[:role]      * bool_score(target[:role] == candidate[:role])) +
+          (@weights[:neighbors] * jaccard(target[:neighbors], candidate[:neighbors])) +
+          (@weights[:position] * position_score(target[:position], candidate[:position]))
+      end
+
+      private
+
+      def text_score(target, candidate)
+        return 0.0 if target.nil? || candidate.nil? || target.empty? || candidate.empty?
+
+        target.downcase.strip == candidate.downcase.strip ? 1.0 : 0.0
+      end
+
+      def bool_score(flag) = flag ? 1.0 : 0.0
+
+      def jaccard(target, candidate)
+        target = Array(target)
+        candidate = Array(candidate)
+        return 1.0 if target.empty? && candidate.empty?
+        return 0.0 if target.empty? || candidate.empty?
+
+        inter = (target & candidate).size
+        union = (target | candidate).size
+        union.zero? ? 0.0 : inter.to_f / union
+      end
+
+      def position_score(target, candidate)
+        return 0.0 unless target && candidate
+
+        idx_d = (target[:index].to_i - candidate[:index].to_i).abs
+        depth_d = (target[:depth].to_i - candidate[:depth].to_i).abs
+        # Soft falloff: 1.0 when identical, ~0 once they're 4+ apart in either axis.
+        [1.0 - ((idx_d + depth_d) / 8.0), 0.0].max
+      end
+    end
+  end
+end

data/lib/browserctl/replay/snapshot_diff.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Browserctl
+  module Replay
+    # Stable digest + element-set comparison for post-step snapshots.
+    #
+    # The digest is intentionally cheap and stable across cosmetic DOM noise:
+    # only the (selector, role, tag) triples drive the hash, sorted to remove
+    # ordering effects. That's enough to flag structural drift (a step that
+    # used to land on /dashboard now lands on /login) without flapping on
+    # every reflow or class rename.
+    module SnapshotDiff
+      module_function
+
+      def digest(snapshot)
+        return nil if snapshot.nil?
+
+        keys = Array(snapshot).map { |el| identity_tuple(el) }.compact.sort
+        Digest::SHA1.hexdigest(keys.join("\n"))[0, 16]
+      end
+
+      # Returns { added: [...], removed: [...] } of element selectors that
+      # differ between two snapshots. Empty arrays mean structurally identical.
+      def compare(prev, current)
+        prev_set    = element_set(prev)
+        current_set = element_set(current)
+        {
+          added: (current_set - prev_set).sort,
+          removed: (prev_set - current_set).sort
+        }
+      end
+
+      def identity_tuple(entry)
+        return nil unless entry.is_a?(Hash)
+
+        sel = entry[:selector] || entry["selector"]
+        role = entry[:role] || entry["role"]
+        tag = entry[:tag] || entry["tag"]
+        return nil unless sel
+
+        "#{sel}|#{role}|#{tag}"
+      end
+
+      def element_set(snapshot)
+        Array(snapshot).map { |entry| entry[:selector] || entry["selector"] }.compact
+      end
+    end
+  end
+end

data/lib/browserctl/replay/telemetry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../constants"
+
+module Browserctl
+  module Replay
+    # Append-only JSONL log of replay drift events for offline analysis.
+    # Local-only; nothing is uploaded. One line per event.
+    module Telemetry
+      LOG_BASENAME = "replay_drift.jsonl"
+
+      module_function
+
+      def log_path
+        File.join(Browserctl::BROWSERCTL_DIR, LOG_BASENAME)
+      end
+
+      # Write each drift event from a Replay::Context as its own JSONL line.
+      # @param ctx [Browserctl::Replay::Context, nil]
+      # @param workflow [String] workflow name for cross-reference
+      # @param path [String] override the destination (testing)
+      # @return [Integer] number of events written
+      def emit(ctx, workflow:, path: log_path)
+        events = ctx&.drift_events
+        return 0 if events.nil? || events.empty?
+
+        ensure_log_file(path)
+        ts = Time.now.utc.iso8601
+        File.open(path, "a") do |f|
+          events.each do |e|
+            f.puts JSON.generate(
+              event: "replay_drift",
+              ts: ts,
+              workflow: workflow,
+              command: e.command.to_s,
+              selector: e.selector,
+              matched_ref: e.matched_ref,
+              score: e.score,
+              reason: e.reason
+            )
+          end
+        end
+        events.size
+      rescue SystemCallError, IOError
+        # Telemetry must never break a run.
+        0
+      end
+
+      def ensure_log_file(path)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        return if File.exist?(path)
+
+        FileUtils.touch(path)
+        File.chmod(0o600, path)
+      end
+    end
+  end
+end

data/lib/browserctl/runner.rb

@@ -2,7 +2,9 @@
 
 require "json"
 require_relative "workflow"
+require_relative "workflow/promotion_ledger"
 require_relative "client"
+require_relative "replay/telemetry"
 
 module Browserctl
   class Runner
@@ -14,13 +16,27 @@ module Browserctl
     # 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
+    # @param check [Boolean] when true, attaches a Replay::Context, renders
+    #   a drift report after the run, and signals drift via exit code 2.
+    # @return [Symbol] :clean (all ok, no drift), :drift (all ok, drift seen), :fail (any step failed)
     # @raise [WorkflowError] if the name is invalid or a step fails
-    def run_workflow(name, **params)
+    def run_workflow(name, check: false, **params)
       defn    = fetch_workflow(name)
-      results = defn.call(params, Client.new)
+      ctx     = check ? Browserctl::Replay::Context.new : nil
+      begin
+        results = defn.call(params, Client.new, replay_context: ctx)
+      rescue StandardError
+        Browserctl::Workflow::PromotionLedger.record(workflow: name.to_s, verdict: :fail) if check
+        raise
+      end
       print_results(results)
-      results.all?(&:ok)
+      v = verdict(results, ctx)
+      if check
+        print_drift_report(ctx)
+        Browserctl::Replay::Telemetry.emit(ctx, workflow: name.to_s)
+        Browserctl::Workflow::PromotionLedger.record(workflow: name.to_s, verdict: v)
+      end
+      v
     end
 
     # Lists all registered workflows from the standard search paths.
@@ -109,6 +125,24 @@ module Browserctl
       $stdout.puts "  #{label} #{msg}"
     end
 
+    def print_drift_report(ctx)
+      events = ctx&.drift_events || []
+      report = {
+        drift: events.any?,
+        rematches: events.count { |e| e.reason == "rematch" },
+        unresolved: events.count { |e| e.reason == "no candidate above threshold" },
+        events: events.map(&:to_h)
+      }
+      $stdout.puts JSON.pretty_generate(report)
+    end
+
+    def verdict(results, ctx)
+      return :fail unless results.all?(&:ok)
+      return :drift if ctx&.drift_events&.any?
+
+      :clean
+    end
+
     def format_params(defn)
       defn.param_defs.transform_values do |p|
         entry = { required: p.required, secret: p.secret, default: p.default }

data/lib/browserctl/server/command_dispatcher.rb

@@ -11,9 +11,11 @@ require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
 require_relative "handlers/storage"
 require_relative "handlers/session"
+require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
+require_relative "../replay/snapshot_diff"
 
 module Browserctl
   class CommandDispatcher
@@ -26,6 +28,7 @@ module Browserctl
     include Handlers::DaemonControl
     include Handlers::Storage
     include Handlers::Session
+    include Handlers::State
     include Handlers::Interaction
 
     COMMAND_MAP = {
@@ -36,6 +39,7 @@ module Browserctl
       "navigate" => :cmd_navigate,
       "wait" => :cmd_wait,
       "snapshot" => :cmd_snapshot,
+      "auth_check" => :cmd_auth_check,
       "evaluate" => :cmd_evaluate,
       "fill" => :cmd_fill,
       "click" => :cmd_click,
@@ -66,7 +70,12 @@ module Browserctl
       "session_save" => :cmd_session_save,
       "session_load" => :cmd_session_load,
       "session_list" => :cmd_session_list,
-      "session_delete" => :cmd_session_delete
+      "session_delete" => :cmd_session_delete,
+      "state_save" => :cmd_state_save,
+      "state_load" => :cmd_state_load,
+      "state_list" => :cmd_state_list,
+      "state_info" => :cmd_state_info,
+      "state_delete" => :cmd_state_delete
     }.freeze
 
     SCREENSHOT_DIR   = File.expand_path("~/.browserctl/screenshots").freeze