browserctl 0.10.0 → 0.12.0

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

@@ -8,7 +8,11 @@ module Browserctl
 
         def cmd_navigate(req)
           unless Policy.allowed_navigation?(req[:url].to_s)
-            return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
+            return error_payload(
+              code: Browserctl::Error::Codes::DOMAIN_NOT_ALLOWED,
+              message: "navigation to '#{req[:url]}' blocked by domain policy",
+              context: { url: req[:url].to_s }
+            )
           end
 
           with_page(req[:name]) do |session|
@@ -33,7 +37,8 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            type_into(session.page, sel, req[:value])
+            result = type_into(session.page, sel, req[:value])
+            enrich_with_recording_metadata(result, session, sel, req)
           end
         end
 
@@ -42,17 +47,51 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            click_element(session.page, sel)
+            result = click_element(session.page, sel)
+            enrich_with_recording_metadata(result, session, sel, req)
           end
         end
 
+        # Adds ref / fingerprint / snapshot_id / postcondition_hint to a successful
+        # click/fill response. Recording uses these to build a self-healing log.
+        # When req[:capture_post_snapshot] is true, also takes a fresh snapshot
+        # and attaches its digest so workflow run --check can diff DOM state
+        # against the recorded baseline.
+        def enrich_with_recording_metadata(result, session, selector, req)
+          return result unless result[:ok]
+
+          ref = req[:ref] || session.ref_registry.invert[selector]
+          fp  = (ref && session.fingerprint_index[ref]) || session.fingerprint_index[selector]
+          enriched = result.merge(
+            ref: ref,
+            fingerprint: fp,
+            snapshot_id: session.snapshot_id,
+            postcondition_hint: { url: session.page.current_url }
+          )
+          enriched[:post_snapshot_digest] = capture_post_snapshot_digest(session) if req[:capture_post_snapshot]
+          enriched.compact
+        end
+
+        def capture_post_snapshot_digest(session)
+          snapshot = @snapshot_builder.call(session.page)
+          Browserctl::Replay::SnapshotDiff.digest(snapshot)
+        rescue StandardError
+          nil
+        end
+
         def cmd_url(req)
           with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
         end
 
         def type_into(page, selector, value)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           el.focus
           el.evaluate("this.select()")
@@ -62,7 +101,13 @@ module Browserctl
 
         def click_element(page, selector)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           # Use the DOM native click() so JS-only event listeners fire.
           # CDP mouse simulation (el.click) dispatches events at screen coordinates

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

@@ -12,6 +12,30 @@ module Browserctl
           with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
         end
 
+        # Runs the auth_required detector against the page and returns either a
+        # plain `{ ok: true, auth_required: false }` response or a structured
+        # `{ error:, code: "AUTH_REQUIRED", state:, suggested_flow:, reason: }`
+        # error. Callers feed in cookies / suggested_flow when they have a
+        # bundle in hand (see PR 18); without them, only the URL signal fires.
+        def cmd_auth_check(req)
+          with_page(req[:name]) do |session|
+            cookies = session.page.cookies.all.values.map(&:to_h) if req[:include_cookies]
+            result = Browserctl::Detectors.auth_required(
+              session.page,
+              cookies: cookies,
+              suggested_flow: req[:suggested_flow]
+            )
+            next { ok: true, auth_required: false } unless result.triggered
+
+            Browserctl::AuthRequiredError.new(
+              result.reason,
+              state: req[:state],
+              suggested_flow: result.suggested_flow,
+              reason: result.reason
+            ).to_response
+          end
+        end
+
         def take_snapshot(session, format, diff)
           nonce     = SecureRandom.hex(8)
           challenge = Detectors.cloudflare?(session.page)
@@ -20,15 +44,32 @@ module Browserctl
 
           snapshot = @snapshot_builder.call(session.page)
           registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
+          fp_index = build_fingerprint_index(snapshot)
 
           prev = session.prev_snapshot
-          session.ref_registry  = registry
-          session.prev_snapshot = snapshot
+          session.ref_registry      = registry
+          session.fingerprint_index = fp_index
+          session.snapshot_id       = nonce
+          session.prev_snapshot     = snapshot
           result = diff && prev ? compute_diff(prev, snapshot) : snapshot
 
           { ok: true, snapshot: result, challenge: challenge, nonce: nonce }
         end
 
+        def build_fingerprint_index(snapshot)
+          index = {}
+          snapshot.each do |el|
+            ref = el[:ref]
+            sel = el[:selector]
+            fp  = el[:fingerprint]
+            next unless fp
+
+            index[ref] = fp if ref
+            index[sel] = fp if sel
+          end
+          index
+        end
+
         def compute_diff(prev, current)
           prev_by_sel = prev.to_h { |el| [el[:selector], el] }
           current.reject do |el|

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../state"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      # Top-level state management — collapses cookies + localStorage +
+      # sessionStorage into a single `.bctl` bundle. See lib/browserctl/state.rb.
+      module State
+        private
+
+        def cmd_state_save(req)
+          first_session = @global_mutex.synchronize { @pages.values.first }
+          return { error: "no open pages — open a page before saving state" } unless first_session
+
+          payload, captured_origins = capture_state_payload
+          manifest = Browserctl::State.save(
+            req[:name],
+            payload: payload,
+            origins: req[:origins] || captured_origins,
+            flow: req[:flow],
+            flow_version: req[:flow_version],
+            passphrase: req[:passphrase]
+          )
+
+          {
+            ok: true,
+            path: Browserctl::State.path(req[:name]),
+            origins: manifest[:origins],
+            cookies: payload[:cookies].length,
+            encrypted: manifest[:encrypted]
+          }
+        rescue Browserctl::Error, ArgumentError => e
+          { error: e.message }
+        end
+
+        def cmd_state_load(req)
+          data = Browserctl::State.load(req[:name], passphrase: req[:passphrase])
+          target = @global_mutex.synchronize { @pages.values.first }
+          return { error: "no open pages — open a page before loading state" } unless target
+
+          cookies = pluck(data[:payload], :cookies, default: [])
+
+          unless req[:skip_auth_check]
+            auth = Browserctl::Detectors.auth_required(
+              target.page, cookies: cookies, suggested_flow: data[:manifest][:flow]
+            )
+            if auth.triggered
+              return Browserctl::AuthRequiredError.new(
+                auth.reason,
+                state: req[:name],
+                suggested_flow: auth.suggested_flow,
+                reason: auth.reason
+              ).to_response
+            end
+          end
+
+          restore_state_cookies(target, cookies)
+          ls_count = restore_local_storage(pluck(data[:payload], :local_storage, default: {}))
+
+          {
+            ok: true,
+            cookies: cookies.length,
+            local_storage_keys: ls_count,
+            origins: data[:manifest][:origins]
+          }
+        rescue Browserctl::State::Bundle::BundleError, Browserctl::Error, ArgumentError, JSON::ParserError => e
+          { error: e.message }
+        end
+
+        def pluck(hash, sym, default:)
+          hash[sym] || hash[sym.to_s] || default
+        end
+
+        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))
+          end
+        end
+
+        def cmd_state_list(_req)
+          { ok: true, state: Browserctl::State.all }
+        end
+
+        def cmd_state_info(req)
+          { ok: true, info: Browserctl::State.info(req[:name]) }
+        rescue Browserctl::State::Bundle::BundleError, Browserctl::Error, ArgumentError => e
+          { error: e.message }
+        end
+
+        def cmd_state_delete(req)
+          Browserctl::State.delete(req[:name])
+          { ok: true }
+        rescue ArgumentError => e
+          { error: e.message }
+        end
+
+        def capture_state_payload
+          first = @global_mutex.synchronize { @pages.values.first }
+          cookies = first.page.cookies.all.values.map(&:to_h)
+
+          local_storage   = {}
+          session_storage = {}
+          captured_origins = []
+
+          @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})") || "{}"
+              local_storage[origin]   = JSON.parse(ls_str)
+              session_storage[origin] = JSON.parse(ss_str)
+              captured_origins << origin
+            end
+          end
+
+          payload = {
+            cookies: cookies,
+            local_storage: local_storage,
+            session_storage: session_storage
+          }
+          [payload, captured_origins.uniq]
+        end
+
+        def restore_local_storage(local_storage)
+          count = 0
+          local_storage.each do |origin, keys|
+            next if keys.nil? || keys.empty?
+
+            tmp_page = @driver.create_page
+            begin
+              tmp_page.go_to(origin.to_s)
+              keys.each do |k, v|
+                tmp_page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                count += 1
+              end
+            ensure
+              tmp_page.close
+            end
+          end
+          count
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server/page_session.rb

@@ -3,15 +3,17 @@
 module Browserctl
   class PageSession
     attr_reader :page, :mutex, :pause_cv
-    attr_accessor :ref_registry, :prev_snapshot
+    attr_accessor :ref_registry, :prev_snapshot, :fingerprint_index, :snapshot_id
 
     def initialize(page)
-      @page          = page
-      @mutex         = Mutex.new
-      @pause_cv      = ConditionVariable.new
-      @ref_registry  = {}
-      @prev_snapshot = nil
-      @paused        = false
+      @page              = page
+      @mutex             = Mutex.new
+      @pause_cv          = ConditionVariable.new
+      @ref_registry      = {}
+      @fingerprint_index = {}
+      @snapshot_id       = nil
+      @prev_snapshot     = nil
+      @paused            = false
     end
 
     def paused? = @paused

data/lib/browserctl/server/snapshot_builder.rb

@@ -1,55 +1,31 @@
 # frozen_string_literal: true
 
-require "nokogiri"
+require "browserctl/snapshot/extractor"
+require "browserctl/snapshot/annotator"
+require "browserctl/snapshot/serializer"
 
 module Browserctl
+  # Orchestrates the snapshot pipeline:
+  #
+  #   page.body  ──Extractor──▶  [nodes]
+  #              ──Annotator──▶  [entries with ref + fingerprint]
+  #              ──Serializer─▶  wire-shape array
+  #
+  # Each stage is independently testable. Inject alternates via the keyword
+  # args for tests that want to isolate one stage.
   class SnapshotBuilder
-    INTERACTABLE = %w[a button input select textarea
-                      [role=button] [role=link] [role=menuitem]].freeze
-    ATTRS        = %w[type name placeholder href aria-label role].freeze
-
-    def call(page)
-      doc = Nokogiri::HTML(page.body)
-      ref = 0
-      doc.css(INTERACTABLE.join(",")).map { |el| element_entry(el, ref += 1) }
-    end
-
-    private
-
-    def element_entry(elem, ref)
-      { ref: "e#{ref}", tag: elem.name, text: elem.text.strip.slice(0, 80),
-        selector: css_path(elem), attrs: element_attrs(elem) }
-    end
-
-    def element_attrs(elem)
-      elem.attributes.transform_values(&:value).slice(*ATTRS)
-    end
-
-    def css_path(node)
-      ancestors_until_html(node).map { |n| path_segment(n) }.join(" > ")
+    def initialize(extractor: Snapshot::Extractor.new,
+                   annotator: Snapshot::Annotator.new,
+                   serializer: Snapshot::Serializer.new)
+      @extractor = extractor
+      @annotator = annotator
+      @serializer = serializer
     end
 
-    def ancestors_until_html(node)
-      [].tap do |acc|
-        while node && node.name != "html"
-          acc.unshift(node)
-          node = node.parent
-        end
-      end
-    end
-
-    def path_segment(node)
-      node.name + id_fragment(node) + class_fragment(node)
-    end
-
-    def id_fragment(node)
-      (id = node["id"]) && !id.empty? ? "##{id}" : ""
-    end
-
-    def class_fragment(node)
-      return "" if node["id"] && !node["id"].empty?
-
-      (klass = node["class"]&.split&.first) ? ".#{klass}" : ""
+    def call(page)
+      nodes = @extractor.call(page.body)
+      entries = @annotator.call(nodes)
+      @serializer.call(entries)
     end
   end
 end

data/lib/browserctl/session.rb

@@ -71,7 +71,7 @@ module Browserctl
     def self.load(session_name)
       validate_name!(session_name)
       dir = path(session_name)
-      raise "session '#{session_name}' not found" unless Dir.exist?(dir)
+      raise Browserctl::Error, "session '#{session_name}' not found" unless Dir.exist?(dir)
 
       meta = JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true)
 

data/lib/browserctl/snapshot/annotator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "browserctl/snapshot/ref"
+require "browserctl/snapshot/fingerprint"
+
+module Browserctl
+  module Snapshot
+    # Stage 2 of the snapshot pipeline.
+    #
+    # Takes the list of interactable nodes from Extractor and produces
+    # element entries with stable refs, semantic metadata, a CSS selector
+    # path, and a fingerprint. Each entry is a plain Hash.
+    class Annotator
+      ATTRS = %w[type name placeholder href aria-label role].freeze
+
+      def initialize(ref_deriver: RefDeriver.new, fingerprint: Fingerprint.new)
+        @ref_deriver = ref_deriver
+        @fingerprint = fingerprint
+      end
+
+      def call(nodes)
+        taken = {}
+        nodes.map do |node|
+          ref = @ref_deriver.disambiguate(@ref_deriver.derive(node), taken)
+          taken[ref] = true
+          entry(node, ref)
+        end
+      end
+
+      private
+
+      def entry(node, ref)
+        {
+          ref: ref,
+          tag: node.name,
+          text: node.text.strip.slice(0, 80),
+          selector: css_path(node),
+          attrs: attrs(node),
+          fingerprint: @fingerprint.build(node)
+        }
+      end
+
+      def attrs(node)
+        node.attributes.transform_values(&:value).slice(*ATTRS)
+      end
+
+      def css_path(node)
+        ancestors_until_html(node).map { |n| segment(n) }.join(" > ")
+      end
+
+      def ancestors_until_html(node)
+        [].tap do |acc|
+          while node && node.name != "html"
+            acc.unshift(node)
+            node = node.parent
+          end
+        end
+      end
+
+      def segment(node)
+        node.name + id_fragment(node) + class_fragment(node)
+      end
+
+      def id_fragment(node)
+        (id = node["id"]) && !id.empty? ? "##{id}" : ""
+      end
+
+      def class_fragment(node)
+        return "" if node["id"] && !node["id"].empty?
+
+        (klass = node["class"]&.split&.first) ? ".#{klass}" : ""
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/extractor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Browserctl
+  module Snapshot
+    # Stage 1 of the snapshot pipeline.
+    #
+    # Parses raw HTML and returns the set of interactable Nokogiri nodes
+    # that the rest of the pipeline will annotate. This stage knows nothing
+    # about refs, fingerprints, or wire format.
+    class Extractor
+      INTERACTABLE = %w[a button input select textarea
+                        [role=button] [role=link] [role=menuitem]].freeze
+
+      def call(html)
+        Nokogiri::HTML(html).css(INTERACTABLE.join(",")).to_a
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/fingerprint.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "browserctl/snapshot/ref"
+
+module Browserctl
+  module Snapshot
+    # Builds a per-element fingerprint that survives small DOM changes.
+    #
+    # The fingerprint is later used by the replay layer to rematch an
+    # element when its recorded selector no longer resolves: score the
+    # candidate elements in the new DOM against the recorded fingerprint
+    # and pick the best match above a threshold.
+    #
+    # Shape:
+    #   {
+    #     text:      <accessible name>,
+    #     role:      <ARIA role, explicit or implicit>,
+    #     neighbors: [<short text of nearby siblings>, ...],
+    #     position:  { index: <int>, depth: <int> }
+    #   }
+    class Fingerprint
+      NEIGHBOR_RADIUS = 2 # siblings to capture on each side
+      NEIGHBOR_TEXT_LEN = 40
+
+      def initialize(ref_deriver: RefDeriver.new)
+        @ref_deriver = ref_deriver
+      end
+
+      def build(node)
+        {
+          text: accessible_name(node),
+          role: role(node),
+          neighbors: neighbors(node),
+          position: position(node)
+        }
+      end
+
+      private
+
+      def role(node)
+        explicit = node["role"]
+        return explicit if explicit && !explicit.empty?
+
+        RefDeriver::IMPLICIT_ROLE[node.name] || node.name
+      end
+
+      def accessible_name(node)
+        %w[aria-label placeholder alt title].each do |attr|
+          v = node[attr]
+          return v.strip if v && !v.strip.empty?
+        end
+        node.text.to_s.strip.slice(0, 80)
+      end
+
+      def neighbors(node)
+        parent = node.parent
+        return [] unless parent.respond_to?(:children)
+
+        idx = parent.children.to_a.index(node) || 0
+        window = parent.children.to_a[[idx - NEIGHBOR_RADIUS, 0].max...(idx + NEIGHBOR_RADIUS + 1)] || []
+        window
+          .reject { |c| c == node || !c.respond_to?(:name) }
+          .map { |c| neighbor_signal(c) }
+          .reject(&:empty?)
+      end
+
+      def neighbor_signal(node)
+        text = node.text.to_s.strip.gsub(/\s+/, " ").slice(0, NEIGHBOR_TEXT_LEN)
+        text.empty? ? "" : "#{node.name}:#{text}"
+      end
+
+      def position(node)
+        idx = node.parent.respond_to?(:children) ? (node.parent.children.to_a.index(node) || 0) : 0
+        { index: idx, depth: depth(node) }
+      end
+
+      def depth(node)
+        d = 0
+        cur = node.parent
+        while cur.respond_to?(:name) && cur.name != "document"
+          d += 1
+          cur = cur.parent
+        end
+        d
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/ref.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Browserctl
+  module Snapshot
+    # Derives a stable element ref from semantic + structural signals.
+    #
+    # The same DOM element should produce the same ref across two snapshots
+    # of the same page. Inputs to the hash are:
+    #   - role (explicit @role, else implicit ARIA role from tag)
+    #   - accessible name (aria-label || text || placeholder || alt)
+    #   - tag
+    #   - parent path (chain of ancestor tag names up to <html>)
+    #
+    # Collisions within a single snapshot are disambiguated by the caller via
+    # `disambiguate(ref, taken)` — the deriver itself is pure.
+    class RefDeriver
+      IMPLICIT_ROLE = {
+        "a" => "link", "button" => "button", "input" => "textbox",
+        "select" => "combobox", "textarea" => "textbox"
+      }.freeze
+
+      HASH_LEN = 7
+
+      def derive(node)
+        signal = [role(node), accessible_name(node), node.name, parent_path(node)].join("|")
+        "e#{Digest::SHA256.hexdigest(signal)[0, HASH_LEN]}"
+      end
+
+      # Given a candidate ref and a set of already-taken refs in the current
+      # snapshot, return a unique ref. Adds `-2`, `-3`, ... as needed.
+      def disambiguate(ref, taken)
+        return ref unless taken.include?(ref)
+
+        n = 2
+        n += 1 while taken.include?("#{ref}-#{n}")
+        "#{ref}-#{n}"
+      end
+
+      private
+
+      def role(node)
+        explicit = node["role"]
+        return explicit if explicit && !explicit.empty?
+
+        IMPLICIT_ROLE[node.name] || node.name
+      end
+
+      def accessible_name(node)
+        %w[aria-label placeholder alt title].each do |attr|
+          v = node[attr]
+          return v.strip if v && !v.strip.empty?
+        end
+        text = node.text.to_s.strip
+        text.empty? ? "" : text.slice(0, 80)
+      end
+
+      def parent_path(node)
+        parts = []
+        cur = node.parent
+        while cur.respond_to?(:name) && cur.name != "html" && cur.name != "document"
+          parts.unshift(cur.name)
+          cur = cur.parent
+        end
+        parts.join(">")
+      end
+    end
+  end
+end

data/lib/browserctl/snapshot/serializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Snapshot
+    # Stage 3 of the snapshot pipeline.
+    #
+    # Right now this is the identity function — annotated entries are
+    # already in the wire shape clients expect. It exists as a seam so
+    # later milestones can canonicalize, redact, or compress without
+    # touching extraction or annotation.
+    class Serializer
+      def call(entries)
+        entries
+      end
+    end
+  end
+end