browserctl 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3b71160a355802bb8e1fd6667506af34dc354c97b60eb2e82e0b418c02dbe6
-  data.tar.gz: 83da78edf2d59d84be5a6fd617e5b2388928c77b005d7735f466ce4aad19699b
+  metadata.gz: ec75744264ce56f8c3f94ab95518a106c8225ec1dc11dd35a97f43186b590502
+  data.tar.gz: 973c3b270b5d1bba3dfa900623790e3c5cb9d5bd8ebe8faa50c28d09e48fbfff
 SHA512:
-  metadata.gz: 1ff6294fbc0284a342d9d2377077a02f004aec2acfeb3c1908039b09753d203e8a641d1dd2cd8ab2fd1fc607c42af3aa86537fb47361bb6820cf9a04fa8d6159
-  data.tar.gz: d029df7a2d280172543cb52dcee92326c97464d3b8d750d2f718710d46db16402b8e1a235c83c5da229a2ae047a4ab92738c3d736f741a4964c1d324f7871c15
+  metadata.gz: 16cd84c58a070de0b9d340ed2bb4e3a951216526dd77a9f18e0f9ea7292311eb51eddf1989c93c11d488cf4bf29163a60a13510f5949599d6027142cf808c1a0
+  data.tar.gz: 615213ac9ba1e694c9fb4597a348abebab9d8f2ba04801dd7d59c1dc00829111f0cce9f49391a7883e7502422ed0b246e86d8c553c62b9be406e0f1e23946e8c

data/CHANGELOG.md

@@ -10,6 +10,27 @@ 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.5.0](https://github.com/patrick204nqh/browserctl/compare/v0.4.0...v0.5.0) (2026-04-25)
+
+
+### Features
+
+* add cookie export/import commands and refine interaction guidance ([1dc8b2c](https://github.com/patrick204nqh/browserctl/commit/1dc8b2c4c744a5f0930c28d3bcf93fd017c368b1))
+* rename snapshot format 'ai' to 'elements' ([#22](https://github.com/patrick204nqh/browserctl/issues/22)) ([9fde6af](https://github.com/patrick204nqh/browserctl/commit/9fde6afb9e53b9556c84b4c24987777a5c266adf))
+* v0.5 architecture & protocol lock ([#20](https://github.com/patrick204nqh/browserctl/issues/20)) ([1224f2f](https://github.com/patrick204nqh/browserctl/commit/1224f2fe2fb05119053831e7901b286fe93ad4fc))
+
+
+### Bug Fixes
+
+* add rake as development dependency ([13902d8](https://github.com/patrick204nqh/browserctl/commit/13902d81fdb986c6ca754fcb16ce61ee850e27ce))
+* improve browser GIF quality and fix terminal font rendering ([17afdb2](https://github.com/patrick204nqh/browserctl/commit/17afdb210916d8ebdabd237130da1fc534cdbd3e))
+* open PR for demo assets instead of pushing directly to main ([f051316](https://github.com/patrick204nqh/browserctl/commit/f051316962d308419c08f60550cfb9910b148f14))
+* quote filtergraph and add -update 1 for palette in browser GIF pipeline ([053d074](https://github.com/patrick204nqh/browserctl/commit/053d074b5fdd3e0ea6fc51589593d72d5f7fcd74))
+* replace undefined REGISTRY constant with Browserctl.registry_snapshot ([d19a6bf](https://github.com/patrick204nqh/browserctl/commit/d19a6bf7ded8a5211f5b2a75511a9532f94e3845))
+* update README for improved clarity and add Quick Start section ([881d914](https://github.com/patrick204nqh/browserctl/commit/881d914c2bf46625ee4ff5c1ca8ef21b462c533d))
+* use app-slug output instead of gh api /app in assets workflow ([ae6a0f8](https://github.com/patrick204nqh/browserctl/commit/ae6a0f80ba2b66c76d681b1f258de5d72bc34c72))
+* use CSS selectors for browser GIF and add full login flow frames ([717b86b](https://github.com/patrick204nqh/browserctl/commit/717b86befa9af6bab1823f984668ebdc29f2d7f8))
+
 ## [0.4.0](https://github.com/patrick204nqh/browserctl/compare/v0.3.1...v0.4.0) (2026-04-25)
 
 

data/README.md

@@ -2,15 +2,21 @@
   <img src=".github/logo.svg" width="96" height="96" alt="browserctl logo"/>
 </p>
 
-# browserctl
+<h1 align="center">browserctl</h1>
 
-[![CI](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/browserctl.svg)](https://badge.fury.io/rb/browserctl)
-[![Downloads](https://img.shields.io/gem/dt/browserctl)](https://rubygems.org/gems/browserctl)
+<p align="center">
+  A persistent browser daemon for AI agents and iterative dev workflows — the session stays alive between commands.
+</p>
+
+<p align="center">
+  <a href="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml"><img src="https://github.com/patrick204nqh/browserctl/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+  <a href="https://badge.fury.io/rb/browserctl"><img src="https://badge.fury.io/rb/browserctl.svg" alt="Gem Version"/></a>
+  <a href="https://rubygems.org/gems/browserctl"><img src="https://img.shields.io/gem/dt/browserctl" alt="Downloads"/></a>
+</p>
 
-A persistent browser automation daemon and CLI, purpose-built for AI agents and developer workflows.
+---
 
-Unlike tools that restart the browser on every script run, **browserctl keeps a named browser session alive** — preserving cookies, localStorage, open tabs, and page state across discrete commands.
+Every browser automation tool restarts the browser when your script ends. That means re-authenticating, re-navigating, re-loading state — on every run. browserctl doesn't restart. The session stays alive between commands, so you pick up exactly where you left off.
 
 ```bash
 browserd &                                               # start the daemon (headless)
@@ -21,8 +27,79 @@ browserctl click login --ref e2
 browserctl shutdown
 ```
 
-![browserctl capturing a login flow](docs/screenshots/the_internet_login.png)
-<p align="center"><sub>Login flow captured with <code>browserctl shot</code></sub></p>
+---
+
+## See it in action
+
+<table align="center"><tr>
+<td align="center" width="50%">
+
+**Terminal**<br/>
+<sub>CLI commands, live output, session persistence proof</sub>
+
+<img src="docs/assets/terminal.webp" alt="browserctl terminal demo"/>
+
+</td>
+<td align="center" width="50%">
+
+**Browser**<br/>
+<sub>What the browser sees as those commands run</sub>
+
+<img src="docs/assets/browser_demo.gif" alt="browserctl browser demo"/>
+
+</td>
+</tr></table>
+
+> Demo assets are regenerated automatically on every push to `main` that touches `demo/` or the login example. To regenerate locally:
+>
+> ```bash
+> rake demo               # full pipeline: screenshots + browser GIF + terminal GIF
+> rake demo:screenshots   # smoke test screenshots only
+> rake demo:browser_gif   # browser animation only  (requires: ffmpeg)
+> rake demo:terminal      # terminal GIF only        (requires: vhs)
+> ```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+gem install browserctl
+
+# 2. Start the daemon
+browserd &
+
+# 3. Open a named page
+browserctl open main --url https://the-internet.herokuapp.com/login
+
+# 4. Snapshot the page — get AI-friendly JSON with ref IDs
+browserctl snap main
+
+# 5. Interact using refs
+browserctl fill  main --ref e1 --value tomsmith
+browserctl fill  main --ref e2 --value SuperSecretPassword!
+browserctl click main --ref e3
+
+# 6. Observe
+browserctl url  main
+browserctl snap main --diff   # only what changed
+
+# 7. Done
+browserctl shutdown
+```
+
+→ [Full Getting Started guide](docs/getting-started.md)
+
+---
+
+## Use cases
+
+**AI coding agent authenticating into a staging environment** — the agent logs in once, the session persists, subsequent commands run inside the authenticated context without re-authenticating between steps.
+
+**Developer reproducing a multi-step bug report** — navigate to the failure point once, then iterate on the fix with the browser already in the right state; no restarting from the home page each run.
+
+**Automated smoke test that needs human sign-off** — the test runs until it hits something ambiguous, calls `browserctl pause`, lets a human inspect and act, then `browserctl resume` hands control back to the script with all state intact.
 
 ---
 
@@ -46,15 +123,10 @@ Most automation tools are stateless — every script spins up a fresh browser an
 
 ---
 
-## Requirements
-
-- Ruby >= 3.3
-- Chrome or Chromium on your `PATH`
-
----
-
 ## Installation
 
+**Requirements:** Ruby >= 3.3 · Chrome or Chromium on your `PATH`
+
 ```bash
 gem install browserctl
 ```
@@ -71,14 +143,14 @@ gem "browserctl"
 
 browserctl ships as a Claude Code plugin. Install it once and Claude automatically knows how to use the daemon, ref-based interaction, HITL patterns, and workflow authoring.
 
-**Install (interactive)**
+**Interactive install**
 
 ```
 /plugin marketplace add patrick204nqh/browserctl
 /plugin install browserctl@browserctl
 ```
 
-**Install (project settings** — commit `.claude/settings.json` to share with your team)
+**Project settings** — commit `.claude/settings.json` to share with your team:
 
 ```json
 {
@@ -97,35 +169,6 @@ Once installed, Claude Code loads the `browserctl` skill automatically — no `/
 
 ---
 
-## Quick Start
-
-```bash
-# 1. Start the daemon
-browserd &
-
-# 2. Open a named page
-browserctl open main --url https://the-internet.herokuapp.com/login
-
-# 3. Snapshot the page — get AI-friendly JSON with ref IDs
-browserctl snap main
-
-# 4. Interact using refs
-browserctl fill  main --ref e1 --value tomsmith
-browserctl fill  main --ref e2 --value SuperSecretPassword!
-browserctl click main --ref e3
-
-# 5. Observe
-browserctl url  main
-browserctl snap main --diff   # only what changed
-
-# 6. Done
-browserctl shutdown
-```
-
-→ [Full Getting Started guide](docs/getting-started.md)
-
----
-
 ## How it works
 
 `browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. It manages a Ferrum (Chrome DevTools Protocol) browser instance with named page handles. `browserctl` sends JSON-RPC commands over the socket and prints the result.
@@ -162,10 +205,14 @@ The daemon shuts itself down after 30 minutes of inactivity.
 ```bash
 git clone https://github.com/patrick204nqh/browserctl
 cd browserctl
-bin/setup              # install deps + check for Chrome
+bin/setup              # brew bundle (macOS) + bundle install + Chrome check
 
 bundle exec rspec      # run tests
 bundle exec rubocop    # lint
+
+rake demo              # regenerate screenshots + terminal GIF
+rake demo:screenshots  # screenshots only (no VHS required)
+rake demo:terminal     # terminal GIF only
 ```
 
 ---

data/bin/browserctl

@@ -108,9 +108,9 @@ case cmd
 when "run"
   name = args.shift or abort "usage: browserctl run <workflow_name|file.rb> [--key value ...]"
   if File.exist?(name)
-    before = Browserctl::REGISTRY.keys.dup
+    before = Browserctl.registry_snapshot.keys
     load File.expand_path(name)
-    name = (Browserctl::REGISTRY.keys - before).first || File.basename(name, ".rb")
+    name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
   end
   params_file_idx = args.index("--params")
   file_params = {}

data/bin/setup

@@ -1,14 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "==> Installing dependencies..."
+if [[ "$(uname)" == "Darwin" ]] && command -v brew &>/dev/null; then
+  echo "==> Installing Homebrew dependencies (Brewfile)..."
+  brew bundle --no-upgrade
+fi
+
+echo "==> Installing gem dependencies..."
 bundle install
 
 echo "==> Checking for Chrome/Chromium..."
 if ! command -v google-chrome &>/dev/null && ! command -v chromium-browser &>/dev/null && ! command -v chromium &>/dev/null; then
   echo "WARNING: Chrome/Chromium not found on PATH."
-  echo "         Install it before running browserctl."
-  echo "         macOS:  brew install --cask google-chrome"
+  echo "         macOS:  brew bundle  (includes google-chrome)"
   echo "         Ubuntu: sudo apt-get install -y chromium-browser"
 fi
 

data/examples/cloudflare_hitl.rb

@@ -55,7 +55,7 @@ Browserctl.workflow "cloudflare_hitl" do
 
   step "wait for content and snapshot" do
     page(:main).wait_for(selector, timeout: 15)
-    result = page(:main).snapshot(format: "ai")
+    result = page(:main).snapshot(format: "elements")
     $stdout.puts "  Snapshot: #{result[:snapshot]&.length || 0} elements captured"
   end
 

data/lib/browserctl/client.rb

@@ -74,10 +74,10 @@ module Browserctl
 
     # Takes a DOM snapshot. Returns `challenge: true` when Cloudflare is detected.
     # @param name [String] logical page name
-    # @param format [String] "ai" (token-efficient JSON) or "html" (raw HTML)
+    # @param format [String] "elements" (interactable elements JSON) or "html" (raw HTML)
     # @param diff [Boolean] return only elements changed since last snapshot
     # @return [Hash] `{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`
-    def snapshot(name, format: "ai", diff: false)
+    def snapshot(name, format: "elements", diff: false)
       call("snapshot", name: name, format: format, diff: diff)
     end
 
@@ -131,6 +131,17 @@ module Browserctl
     # @return [Hash] `{ ok: true, devtools_url: }` or `{ error: }`
     def inspect_page(name)         = call("inspect", name: name)
 
+    # Stores a value in the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @param value [Object] value to store (must be JSON-serialisable)
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def store(key, value) = call("store", key: key, value: value)
+
+    # Retrieves a value from the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @return [Hash] `{ ok: true, value: }` or `{ error:, code: "key_not_found" }`
+    def fetch(key) = call("fetch", key: key)
+
     # Returns all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, cookies: [Hash] }` or `{ error: }`

data/lib/browserctl/commands/snapshot.rb

@@ -6,15 +6,15 @@ require "optimist"
 module Browserctl
   module Commands
     class Snapshot
-      VALID_FORMATS = %w[ai html].freeze
+      VALID_FORMATS = %w[elements html].freeze
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl snap <page> [--format ai|html] [--diff]"
-          opt :format, "Output format: ai or html", default: "ai", short: "-f"
+          banner "Usage: browserctl snap <page> [--format elements|html] [--diff]"
+          opt :format, "Output format: elements (default) or html", default: "elements", short: "-f"
           opt :diff,   "Return only changed elements", default: false, short: "-d"
         end
-        name = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
+        name = args.shift or abort "usage: browserctl snap <page> [--format elements|html] [--diff]"
         unless VALID_FORMATS.include?(opts[:format])
           warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
           exit 1
@@ -31,7 +31,7 @@ module Browserctl
             warn "Error: #{res[:error]}"
             exit 1
           end
-          puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
+          puts(format == "elements" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
         end
       end
     end

data/lib/browserctl/detectors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Detectors
+    CLOUDFLARE_SIGNALS = [
+      "cf-challenge-running",
+      "cf_chl_opt",
+      "__cf_chl_f_tk",
+      "Just a moment..."
+    ].freeze
+
+    # Returns true if the page appears to be showing a Cloudflare challenge.
+    # Checks both the current URL and the page body for known Cloudflare signals.
+    # @param page [Ferrum::Page] the browser page to inspect
+    # @return [Boolean]
+    def self.cloudflare?(page)
+      url  = page.current_url.to_s
+      body = page.body.to_s
+      url.include?("challenge-platform") ||
+        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
+    end
+  end
+end

data/lib/browserctl/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Base error class for all browserctl daemon errors.
+  # Subclasses carry a machine-readable `code` that appears in wire responses.
+  # @attr_reader code [String] machine-readable error code
+  class Error < StandardError
+    def self.default_code = "error"
+
+    attr_reader :code
+
+    def initialize(msg = nil, code: self.class.default_code)
+      @code = code
+      super(msg)
+    end
+  end
+
+  class PageNotFound     < Error; def self.default_code = "page_not_found"     end
+  class SelectorNotFound < Error; def self.default_code = "selector_not_found" end
+  class RefNotFound      < Error; def self.default_code = "ref_not_found"      end
+  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
+  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
+  class TimeoutError     < Error; def self.default_code = "timeout"            end
+  class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+end

data/lib/browserctl/policy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Browserctl
+  module Policy
+    # Returns true if the URL is permitted by the domain policy.
+    # When BROWSERCTL_ALLOWED_DOMAINS is unset, all URLs are allowed.
+    # @param url [String] the URL to check
+    # @return [Boolean]
+    def self.allowed_navigation?(url)
+      domains = allowed_domains
+      return true if domains.empty?
+
+      host_matches?(URI.parse(url).host, domains)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.allowed_domains
+      raw = ENV.fetch("BROWSERCTL_ALLOWED_DOMAINS", nil)
+      return [] unless raw&.match?(/\S/)
+
+      raw.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def self.host_matches?(host, domains)
+      return false unless host
+
+      normalised = host.downcase
+      domains.any? { |d| normalised == d.downcase || normalised.end_with?(".#{d.downcase}") }
+    end
+
+    private_class_method :allowed_domains, :host_matches?
+  end
+end

data/lib/browserctl/runner.rb

@@ -27,7 +27,7 @@ module Browserctl
     # @return [Array<Hash>] array of `{ name:, desc: }` hashes
     def list_workflows
       load_all_workflows
-      REGISTRY.map { |name, defn| { name: name, desc: defn.description } }
+      Browserctl.registry_snapshot.map { |name, defn| { name: name, desc: defn.description } }
     end
 
     # Returns detailed information about a workflow.
@@ -67,15 +67,15 @@ module Browserctl
     end
 
     def fetch_workflow(name)
-      return REGISTRY[name.to_s] if REGISTRY.key?(name.to_s)
+      return Browserctl.lookup_workflow(name.to_s) if Browserctl.lookup_workflow(name.to_s)
 
       validate_name!(name)
       load_workflow_file(name)
-      REGISTRY[name.to_s] || raise("workflow '#{name}' not found")
+      Browserctl.lookup_workflow(name.to_s) || raise("workflow '#{name}' not found")
     end
 
     def load_workflow_file(name)
-      return if REGISTRY.key?(name.to_s)
+      return if Browserctl.lookup_workflow(name.to_s)
 
       path = workflow_path(name)
       load path if path

data/lib/browserctl/server/command_dispatcher.rb

@@ -2,9 +2,26 @@
 
 require_relative "snapshot_builder"
 require_relative "page_session"
+require_relative "handlers/page_lifecycle"
+require_relative "handlers/navigation"
+require_relative "handlers/observation"
+require_relative "handlers/cookies"
+require_relative "handlers/hitl"
+require_relative "handlers/devtools"
+require_relative "handlers/daemon_control"
+require_relative "../detectors"
+require_relative "../policy"
 
 module Browserctl
   class CommandDispatcher
+    include Handlers::PageLifecycle
+    include Handlers::Navigation
+    include Handlers::Observation
+    include Handlers::Cookies
+    include Handlers::Hitl
+    include Handlers::DevTools
+    include Handlers::DaemonControl
+
     COMMAND_MAP = {
       "open_page" => :cmd_open_page,
       "close_page" => :cmd_close_page,
@@ -26,26 +43,28 @@ module Browserctl
       "cookies" => :cmd_cookies,
       "set_cookie" => :cmd_set_cookie,
       "clear_cookies" => :cmd_clear_cookies,
-      "import_cookies" => :cmd_import_cookies
+      "import_cookies" => :cmd_import_cookies,
+      "store" => :cmd_store,
+      "fetch" => :cmd_fetch
     }.freeze
 
     SCREENSHOT_DIR   = File.expand_path("~/.browserctl/screenshots").freeze
     SCREENSHOT_ROOTS = [SCREENSHOT_DIR, File.expand_path(".")].freeze
-    SCREENSHOT_EXTS = %w[.png .jpg .jpeg].freeze
-    CLOUDFLARE_SIGNALS = [
-      "cf-challenge-running",
-      "cf_chl_opt",
-      "__cf_chl_f_tk",
-      "Just a moment..."
-    ].freeze
+    SCREENSHOT_EXTS  = %w[.png .jpg .jpeg].freeze
 
     def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
       @pages            = pages
       @browser          = browser
       @snapshot_builder = snapshot_builder
       @global_mutex     = global_mutex
+      @kv_store         = {}
+      @kv_mutex         = Mutex.new
     end
 
+    # Dispatches a parsed request to the appropriate handler.
+    # Returns `{ error: String, code: String }` for unknown commands.
+    # @param req [Hash{Symbol => Object}] parsed request; must include `:cmd`
+    # @return [Hash{Symbol => Object}] response; always includes `:ok` or `:error`
     def dispatch(req)
       handler = COMMAND_MAP[req[:cmd]]
       if handler
@@ -53,7 +72,7 @@ module Browserctl
         return send(handler, req)
       end
 
-      if (plugin = Browserctl::PLUGIN_COMMANDS[req[:cmd]])
+      if (plugin = Browserctl.lookup_plugin_command(req[:cmd]))
         Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
         session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
         return plugin.call(session, req)
@@ -64,233 +83,6 @@ module Browserctl
 
     private
 
-    def cmd_open_page(req)
-      session = @global_mutex.synchronize do
-        @pages[req[:name]] ||= PageSession.new(@browser.create_page)
-      end
-      session.page.go_to(req[:url]) if req[:url]
-      { ok: true, name: req[:name] }
-    end
-
-    def cmd_close_page(req)
-      session = @global_mutex.synchronize { @pages.delete(req[:name]) }
-      session&.page&.close
-      { ok: true }
-    end
-
-    def cmd_list_pages(_req)
-      { pages: @global_mutex.synchronize { @pages.keys } }
-    end
-
-    def cmd_goto(req)
-      with_page(req[:name]) do |session|
-        session.page.go_to(req[:url])
-        { ok: true, url: session.page.current_url, challenge: cloudflare_challenge?(session.page) }
-      end
-    end
-
-    def cmd_snapshot(req)
-      with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
-    end
-
-    def take_snapshot(session, format, diff)
-      challenge = cloudflare_challenge?(session.page)
-
-      return { ok: true, html: session.page.body, challenge: challenge } unless format == "ai"
-
-      snapshot = @snapshot_builder.call(session.page)
-      registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
-
-      prev = session.prev_snapshot
-      session.ref_registry  = registry
-      session.prev_snapshot = snapshot
-      result = diff && prev ? compute_diff(prev, snapshot) : snapshot
-
-      { ok: true, snapshot: result, challenge: challenge }
-    end
-
-    def compute_diff(prev, current)
-      prev_by_sel = prev.to_h { |el| [el[:selector], el] }
-      current.reject do |el|
-        old = prev_by_sel[el[:selector]]
-        old && old.slice(:text, :attrs) == el.slice(:text, :attrs)
-      end
-    end
-
-    def cmd_evaluate(req)
-      with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
-    end
-
-    def cmd_fill(req)
-      with_page(req[:name]) do |session|
-        sel = resolve_selector_from(session, req)
-        return sel if sel.is_a?(Hash)
-
-        type_into(session.page, sel, req[:value])
-      end
-    end
-
-    def type_into(page, selector, value)
-      el = page.at_css(selector)
-      return { error: "selector not found: #{selector}" } unless el
-
-      el.focus
-      el.type(value)
-      { ok: true }
-    end
-
-    def cmd_click(req)
-      with_page(req[:name]) do |session|
-        sel = resolve_selector_from(session, req)
-        return sel if sel.is_a?(Hash)
-
-        click_element(session.page, sel)
-      end
-    end
-
-    def click_element(page, selector)
-      el = page.at_css(selector)
-      return { error: "selector not found: #{selector}" } unless el
-
-      el.click
-      { ok: true }
-    end
-
-    def cmd_screenshot(req)
-      with_page(req[:name]) do |session|
-        path = safe_screenshot_path(req[:path], req[:name])
-        return path if path.is_a?(Hash)
-
-        FileUtils.mkdir_p(File.dirname(path))
-        session.page.screenshot(path: path, full: req.fetch(:full, false))
-        { ok: true, path: path }
-      end
-    end
-
-    def safe_screenshot_path(requested, page_name)
-      if requested
-        expanded = File.expand_path(requested)
-        allowed  = SCREENSHOT_ROOTS.any? { |d| expanded.start_with?("#{d}/") || expanded.start_with?(d) }
-        return { error: "path outside allowed directory (#{SCREENSHOT_DIR} or project directory)" } unless allowed
-        return { error: "invalid extension — use .png, .jpg, or .jpeg" } \
-          unless SCREENSHOT_EXTS.include?(File.extname(expanded).downcase)
-
-        expanded
-      else
-        name_safe = page_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
-        File.join(SCREENSHOT_DIR, "browserctl_shot_#{name_safe}_#{Time.now.to_i}.png")
-      end
-    end
-
-    def cmd_wait_for(req)
-      with_page(req[:name]) { |session| wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f) }
-    end
-
-    def cmd_watch(req)
-      with_page(req[:name]) do |session|
-        result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
-        result[:error] ? result : { ok: true, selector: req[:selector] }
-      end
-    end
-
-    def wait_for_selector(page, selector, timeout)
-      deadline = Time.now + timeout
-      loop do
-        found = page.at_css(selector)
-        break { ok: true } if found
-        break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" } if Time.now >= deadline
-
-        sleep 0.2
-      end
-    end
-
-    def cmd_url(req)
-      with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
-    end
-
-    def cmd_cookies(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      all = session.page.cookies.all
-      { ok: true, cookies: all.values.map(&:to_h) }
-    end
-
-    def cmd_set_cookie(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      session.page.cookies.set(
-        name: req[:cookie_name],
-        value: req[:value],
-        domain: req[:domain],
-        path: req.fetch(:path, "/")
-      )
-      { ok: true }
-    end
-
-    def cmd_clear_cookies(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      session.page.cookies.clear
-      { ok: true }
-    end
-
-    def cmd_import_cookies(req)
-      with_page(req[:name]) do |session|
-        req[:cookies].each do |c|
-          session.page.cookies.set(
-            name: c[:name],
-            value: c[:value],
-            domain: c[:domain],
-            path: c.fetch(:path, "/"),
-            httponly: c[:httpOnly] == true,
-            secure: c[:secure] == true,
-            expires: c[:expires] ? Time.at(c[:expires].to_i) : nil
-          )
-        end
-        { ok: true, count: req[:cookies].length }
-      end
-    end
-
-    def cmd_inspect(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      port      = @browser.process.port
-      target_id = session.page.target_id
-      devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
-                     "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
-      { ok: true, devtools_url: devtools_url }
-    end
-
-    def cmd_pause(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      session.mutex.synchronize { session.pause! }
-      { ok: true, paused: true }
-    end
-
-    def cmd_resume(req)
-      session = @global_mutex.synchronize { @pages[req[:name]] }
-      return { error: "no page named '#{req[:name]}'" } unless session
-
-      session.mutex.synchronize do
-        session.resume!
-        session.pause_cv.signal
-      end
-      { ok: true, paused: false }
-    end
-
-    def cmd_ping(_req) = { ok: true, pid: Process.pid, protocol_version: PROTOCOL_VERSION }
-
-    def cmd_shutdown(_req)
-      Process.kill("INT", Process.pid)
-      { ok: true }
-    end
-
     def with_page(name)
       session = @global_mutex.synchronize { @pages[name] }
       return { error: "no page named '#{name}'" } unless session
@@ -300,19 +92,5 @@ module Browserctl
         yield session
       end
     end
-
-    def cloudflare_challenge?(page)
-      url  = page.current_url.to_s
-      body = page.body.to_s
-      url.include?("challenge-platform") ||
-        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
-    end
-
-    def resolve_selector_from(session, req)
-      return req[:selector] if req[:selector]
-      return { error: "selector or ref required" } unless req[:ref]
-
-      session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
-    end
   end
 end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Cookies
+        private
+
+        def cmd_cookies(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          all = session.page.cookies.all
+          { ok: true, cookies: all.values.map(&:to_h) }
+        end
+
+        def cmd_set_cookie(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          session.page.cookies.set(
+            name: req[:cookie_name],
+            value: req[:value],
+            domain: req[:domain],
+            path: req.fetch(:path, "/")
+          )
+          { ok: true }
+        end
+
+        def cmd_clear_cookies(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          session.page.cookies.clear
+          { ok: true }
+        end
+
+        def cmd_import_cookies(req)
+          with_page(req[:name]) do |session|
+            req[:cookies].each do |c|
+              session.page.cookies.set(
+                name: c[:name],
+                value: c[:value],
+                domain: c[:domain],
+                path: c.fetch(:path, "/"),
+                httponly: c[:httpOnly] == true,
+                secure: c[:secure] == true,
+                expires: c[:expires] ? Time.at(c[:expires].to_i) : nil
+              )
+            end
+            { ok: true, count: req[:cookies].length }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module DaemonControl
+        private
+
+        def cmd_ping(_req) = { ok: true, pid: Process.pid, protocol_version: PROTOCOL_VERSION }
+
+        def cmd_shutdown(_req)
+          Process.kill("INT", Process.pid)
+          { ok: true }
+        end
+
+        def cmd_store(req)
+          @kv_mutex.synchronize { @kv_store[req[:key].to_s] = req[:value] }
+          { ok: true }
+        end
+
+        def cmd_fetch(req)
+          key = req[:key].to_s
+          found = @kv_mutex.synchronize { @kv_store.key?(key) ? { ok: true, value: @kv_store[key] } : nil }
+          found || { error: "key '#{key}' not found", code: "key_not_found" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module DevTools
+        private
+
+        def cmd_inspect(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          port      = @browser.process.port
+          target_id = session.page.target_id
+          devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
+                         "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
+          { ok: true, devtools_url: devtools_url }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Hitl
+        private
+
+        def cmd_pause(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          session.mutex.synchronize { session.pause! }
+          { ok: true, paused: true }
+        end
+
+        def cmd_resume(req)
+          session = @global_mutex.synchronize { @pages[req[:name]] }
+          return { error: "no page named '#{req[:name]}'" } unless session
+
+          session.mutex.synchronize do
+            session.resume!
+            session.pause_cv.signal
+          end
+          { ok: true, paused: false }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Navigation
+        private
+
+        def cmd_goto(req)
+          unless Policy.allowed_navigation?(req[:url].to_s)
+            return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
+          end
+
+          with_page(req[:name]) do |session|
+            session.page.go_to(req[:url])
+            { ok: true, url: session.page.current_url, challenge: Detectors.cloudflare?(session.page) }
+          end
+        end
+
+        def cmd_evaluate(req)
+          with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
+        end
+
+        def cmd_fill(req)
+          with_page(req[:name]) do |session|
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            type_into(session.page, sel, req[:value])
+          end
+        end
+
+        def cmd_click(req)
+          with_page(req[:name]) do |session|
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            click_element(session.page, sel)
+          end
+        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
+
+          el.focus
+          el.type(value)
+          { ok: true }
+        end
+
+        def click_element(page, selector)
+          el = page.at_css(selector)
+          return { error: "selector not found: #{selector}" } unless el
+
+          el.click
+          { ok: true }
+        end
+
+        def resolve_selector_from(session, req)
+          return req[:selector] if req[:selector]
+          return { error: "selector or ref required" } unless req[:ref]
+
+          session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Observation
+        private
+
+        def cmd_snapshot(req)
+          with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
+        end
+
+        def take_snapshot(session, format, diff)
+          nonce     = SecureRandom.hex(8)
+          challenge = Detectors.cloudflare?(session.page)
+
+          return { ok: true, html: session.page.body, challenge: challenge, nonce: nonce } unless format == "elements"
+
+          snapshot = @snapshot_builder.call(session.page)
+          registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
+
+          prev = session.prev_snapshot
+          session.ref_registry  = registry
+          session.prev_snapshot = snapshot
+          result = diff && prev ? compute_diff(prev, snapshot) : snapshot
+
+          { ok: true, snapshot: result, challenge: challenge, nonce: nonce }
+        end
+
+        def compute_diff(prev, current)
+          prev_by_sel = prev.to_h { |el| [el[:selector], el] }
+          current.reject do |el|
+            old = prev_by_sel[el[:selector]]
+            old && old.slice(:text, :attrs) == el.slice(:text, :attrs)
+          end
+        end
+
+        def cmd_screenshot(req)
+          with_page(req[:name]) do |session|
+            path = safe_screenshot_path(req[:path], req[:name])
+            return path if path.is_a?(Hash)
+
+            FileUtils.mkdir_p(File.dirname(path))
+            session.page.screenshot(path: path, full: req.fetch(:full, false))
+            { ok: true, path: path }
+          end
+        end
+
+        def safe_screenshot_path(requested, page_name)
+          return default_screenshot_path(page_name) unless requested
+
+          expanded = File.expand_path(requested)
+          return { error: "invalid extension — use .png, .jpg, or .jpeg" } unless valid_screenshot_ext?(expanded)
+          return { error: "path outside allowed directory (#{SCREENSHOT_DIR} or project directory)" } \
+            unless within_screenshot_roots?(expanded)
+
+          File.join(resolve_dir(File.dirname(expanded)), File.basename(expanded))
+        end
+
+        def valid_screenshot_ext?(path)
+          SCREENSHOT_EXTS.include?(File.extname(path).downcase)
+        end
+
+        def within_screenshot_roots?(path)
+          dir = resolve_dir(File.dirname(path))
+          SCREENSHOT_ROOTS.any? do |root|
+            real_root = resolve_dir(root)
+            dir.start_with?("#{real_root}/") || dir == real_root
+          end
+        end
+
+        def resolve_dir(dir)
+          File.realpath(dir)
+        rescue Errno::ENOENT
+          dir
+        end
+
+        def default_screenshot_path(page_name)
+          name_safe = page_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
+          File.join(SCREENSHOT_DIR, "browserctl_shot_#{name_safe}_#{Time.now.to_i}.png")
+        end
+
+        def cmd_wait_for(req)
+          with_page(req[:name]) do |session|
+            wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f)
+          end
+        end
+
+        def cmd_watch(req)
+          with_page(req[:name]) do |session|
+            result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
+            result[:error] ? result : { ok: true, selector: req[:selector] }
+          end
+        end
+
+        def wait_for_selector(page, selector, timeout)
+          deadline = Time.now + timeout
+          loop do
+            found = page.at_css(selector)
+            break { ok: true } if found
+            if Time.now >= deadline
+              break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" }
+            end
+
+            sleep 0.2
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module PageLifecycle
+        private
+
+        def cmd_open_page(req)
+          session = @global_mutex.synchronize do
+            @pages[req[:name]] ||= PageSession.new(@browser.create_page)
+          end
+          session.page.go_to(req[:url]) if req[:url]
+          { ok: true, name: req[:name] }
+        end
+
+        def cmd_close_page(req)
+          session = @global_mutex.synchronize { @pages.delete(req[:name]) }
+          session&.page&.close
+          { ok: true }
+        end
+
+        def cmd_list_pages(_req)
+          { pages: @global_mutex.synchronize { @pages.keys } }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server.rb

@@ -62,8 +62,9 @@ module Browserctl
 
     def setup_socket
       FileUtils.rm_f(@socket_path)
+      old_umask = File.umask(0o177)
       server = UNIXServer.new(@socket_path)
-      File.chmod(0o600, @socket_path)
+      File.umask(old_umask)
       Browserctl.logger.info "daemon ready — listening on #{@socket_path}"
       server
     end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -16,15 +16,20 @@ module Browserctl
     def initialize(params, client)
       @params = params
       @client = client
-      @_store = {}
     end
 
     def store(key, value)
-      @_store[key] = value
+      res = @client.store(key.to_s, value)
+      raise WorkflowError, res[:error] if res[:error]
+
+      value
     end
 
     def fetch(key)
-      @_store.fetch(key) { raise KeyError, "no value stored for key #{key.inspect}" }
+      res = @client.fetch(key.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res[:value]
     end
 
     def method_missing(name, *args)
@@ -137,7 +142,7 @@ module Browserctl
     end
 
     def compose(workflow_name)
-      source = REGISTRY[workflow_name.to_s]
+      source = Browserctl.lookup_workflow(workflow_name.to_s)
       raise WorkflowError, "workflow '#{workflow_name}' not found for composition" unless source
 
       @steps.concat(source.steps)
@@ -187,11 +192,20 @@ module Browserctl
     end
   end
 
-  REGISTRY = {} # rubocop:disable Style/MutableConstant
+  @registry_mutex = Mutex.new
+  @registry = {}
 
   def self.workflow(name, &)
     defn = WorkflowDefinition.new(name.to_s)
     defn.instance_exec(&)
-    REGISTRY[name.to_s] = defn
+    @registry_mutex.synchronize { @registry[name.to_s] = defn }
+  end
+
+  def self.lookup_workflow(name)
+    @registry_mutex.synchronize { @registry[name.to_s] }
+  end
+
+  def self.registry_snapshot
+    @registry_mutex.synchronize { @registry.dup }
   end
 end

data/lib/browserctl.rb

@@ -2,14 +2,24 @@
 
 require_relative "browserctl/version"
 require_relative "browserctl/constants"
+require_relative "browserctl/errors"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"
 
 module Browserctl
-  PLUGIN_COMMANDS = {} # rubocop:disable Style/MutableConstant
+  @plugin_commands_mutex = Mutex.new
+  @plugin_commands = {}
 
   def self.register_command(name, &block)
-    PLUGIN_COMMANDS[name.to_s] = block
+    @plugin_commands_mutex.synchronize { @plugin_commands[name.to_s] = block }
+  end
+
+  def self.lookup_plugin_command(name)
+    @plugin_commands_mutex.synchronize { @plugin_commands[name.to_s] }
+  end
+
+  def self.plugin_commands_snapshot
+    @plugin_commands_mutex.synchronize { @plugin_commands.dup }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Patrick
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -150,11 +164,21 @@ files:
 - lib/browserctl/commands/status.rb
 - lib/browserctl/commands/watch.rb
 - lib/browserctl/constants.rb
+- lib/browserctl/detectors.rb
+- lib/browserctl/errors.rb
 - lib/browserctl/logger.rb
+- lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
+- lib/browserctl/server/handlers/cookies.rb
+- lib/browserctl/server/handlers/daemon_control.rb
+- lib/browserctl/server/handlers/devtools.rb
+- lib/browserctl/server/handlers/hitl.rb
+- lib/browserctl/server/handlers/navigation.rb
+- lib/browserctl/server/handlers/observation.rb
+- lib/browserctl/server/handlers/page_lifecycle.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb