browserctl 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2976bab368591b4cb06cd3a34d64c1078bd8588590d70c67ba3d78ecd721e572
-  data.tar.gz: 0fa9c86ec532df2c6763780bfb6c2ac47380ff1df400ae2639fe914fc66e0d04
+  metadata.gz: c12ad0cc3d34e7163bab1d678d65b320e946e0fa16fe7bd3e9f5881855d4801f
+  data.tar.gz: 84d80f56270dfc7d252d7e63279f7c7c54123067837af457f5e92e82b2f0384e
 SHA512:
-  metadata.gz: ef5ab4df359bde2cc6b635f6ac77c1147df57e85c57ff61222179f223e4d41ef4d58b622aa928cde19c41b1927d6ebafd273847ada8c55bf74cfdc09b6ddb5c7
-  data.tar.gz: 0af88adb9b7076a4408c65ac25e7d13fd0f70aa2cdf79448fe9be7953695bd12de01d9c98626628163ce8edb738b4d2c83a925a77e2504924b1ee6bfe85c39d3
+  metadata.gz: c95dbbbe2a573635421fe90cd65d2ccc41baf968c32bb65edcea52030e1b0080fd2af0f50ea9d85bc827ff4f537e2c5b4f3a7631c8242380a007df432e820906
+  data.tar.gz: 1da50ab443d365e4a4b9ce145671e266fdfb0d83432b7b2313d87233b58b425252d2d9a365b0f8b3c31040961b90f684fe9299867c4cccfcd9600ea88cb93cc1

data/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.2.1](https://github.com/patrick204nqh/browserctl/compare/v0.2.0...v0.2.1) (2026-04-20)
+
+
+### Bug Fixes
+
+* align CLI with standard conventions ([215c2af](https://github.com/patrick204nqh/browserctl/commit/215c2af3a4c4d27397476932147f3fda39e4039c))
+* remove flag_extractor spec after deleting the module ([cd80045](https://github.com/patrick204nqh/browserctl/commit/cd8004515fcbae68248d7133e10d5c0223be10e1))
+* use GH_PAT for release-please to trigger release workflow ([da83358](https://github.com/patrick204nqh/browserctl/commit/da83358e8ff19e8a30c23b9f5d744cb11ffbc7c6))
+* use PAT for release-please to trigger release workflow ([4a9ea99](https://github.com/patrick204nqh/browserctl/commit/4a9ea99f418cbf719a16e2a971672175e0292221))
+
+## [0.2.0](https://github.com/patrick204nqh/browserctl/compare/v0.1.1...v0.2.0) (2026-04-20)
+
+
+### Features
+
+* add architecture documentation and decision records with diagrams ([9b67e40](https://github.com/patrick204nqh/browserctl/commit/9b67e40892cb87a075818fd7b166584a48c8edff))
+* add logging functionality and environment variable setup documentation ([feb529c](https://github.com/patrick204nqh/browserctl/commit/feb529c4040c6f84104fa6dc55afc8d0a5d1b1a7))
+* add record command — capture session as replayable workflow ([bb8988b](https://github.com/patrick204nqh/browserctl/commit/bb8988bcf17c0a7689f5a6e53d755d0e6a69b359))
+* add ref registry and diff cache to CommandDispatcher ([217e158](https://github.com/patrick204nqh/browserctl/commit/217e15831b2cf1f0bf693584f47ed5d315594803))
+* add ref-based click and fill using snapshot registry ([f0251c0](https://github.com/patrick204nqh/browserctl/commit/f0251c0732fd535bde8746b2817d3674ec8bc353))
+* add retry_count and timeout options to workflow steps ([7b5e694](https://github.com/patrick204nqh/browserctl/commit/7b5e694cfb246396502a07b02928de79233a715f))
+* add snap --diff returning only changed elements ([0a09558](https://github.com/patrick204nqh/browserctl/commit/0a095583ea23b1cff0df1ecc6cb91a3e35039e2c))
+* add watch command — poll selector and emit when found ([b9a3abf](https://github.com/patrick204nqh/browserctl/commit/b9a3abf15b7e021906dda940f29f029ca3c221c2))
+* named daemon instances via browserd --name and multi-socket support ([8cbc62d](https://github.com/patrick204nqh/browserctl/commit/8cbc62d6c8931b23cbf31e7285ee52c62e280f5c))
+* v0.2 AI-first enhancements ([d3246d4](https://github.com/patrick204nqh/browserctl/commit/d3246d4c861430fda1e7dfa1cb67ce22db33dd68))
+
+
+### Bug Fixes
+
+* add edited event and workflow_dispatch to release trigger ([b851306](https://github.com/patrick204nqh/browserctl/commit/b85130603986ea5a667f2a89e9af7139c38491f2))
+* add paths-ignore for markdown and docs in CI workflow ([3b7801d](https://github.com/patrick204nqh/browserctl/commit/3b7801dfa536ea0b0cd9bab189f237a2709e1515))
+* describe_workflow after StepDef refactor; skip nil-selector recording for ref commands ([9e437fa](https://github.com/patrick204nqh/browserctl/commit/9e437fa9c18b6c94259a652af238377ce120d12e))
+* fill --ref uses --value flag; add record generate subcommand ([ef3ed43](https://github.com/patrick204nqh/browserctl/commit/ef3ed433e09c0ae8ac6e241949ee9c2c0ccaa03c))
+* remove 'edited' type from release trigger events ([98f63f0](https://github.com/patrick204nqh/browserctl/commit/98f63f0c40cbdcd40e14704379f28c19c436a6c2))
+* rubocop offenses — formatting, guard clauses, predicate rename extract_flag? ([43341be](https://github.com/patrick204nqh/browserctl/commit/43341be50f12ca28699b009efb85b1ff404e4dab))
+* trigger release workflow on GitHub release publication ([55c8faa](https://github.com/patrick204nqh/browserctl/commit/55c8faae8d753f35663ebd3c02996d1a602de091))
+* update brand icon concept and roadmap versioning ([7a97b4b](https://github.com/patrick204nqh/browserctl/commit/7a97b4b0c0eaffbd8743ac30b2fbf13be468c80e))
+
 ## [0.1.1](https://github.com/patrick204nqh/browserctl/compare/v0.1.0...v0.1.1) (2026-04-19)
 
 

data/README.md

@@ -15,9 +15,9 @@ Unlike tools that restart the browser on every script run, **browserctl keeps a
 ```bash
 browserd &                                           # start the daemon (headless)
 browserctl open login --url https://example.com/login
-browserctl fill login "input[name=email]" me@example.com
-browserctl click login "button[type=submit]"
-browserctl snap login                                # AI-friendly JSON snapshot
+browserctl snap login                                # AI-friendly JSON snapshot with ref IDs
+browserctl fill login --ref e1 --value me@example.com   # interact by ref
+browserctl click login --ref e2
 browserctl shutdown
 ```
 
@@ -81,24 +81,34 @@ browserd --headed  # visible browser window
 browserctl open login --url https://app.example.com/login
 ```
 
-**3. Interact with the page**
+**3. Snapshot the page to discover refs**
+
+```bash
+browserctl snap login              # AI-friendly JSON with ref IDs (default)
+browserctl snap login --format html
+```
+
+**4. Interact using refs or selectors**
 
 ```bash
+browserctl fill  login --ref e1 --value user@example.com
+browserctl fill  login --ref e2 --value s3cr3t
+browserctl click login --ref e3
+
+# or using explicit CSS selectors
 browserctl fill  login "input[name=email]"    user@example.com
-browserctl fill  login "input[name=password]" s3cr3t
 browserctl click login "button[type=submit]"
 ```
 
-**4. Observe the result**
+**5. Observe the result**
 
 ```bash
-browserctl snap login              # AI-friendly JSON (default)
-browserctl snap login --format html
+browserctl snap login --diff       # only changed elements since last snap
 browserctl shot login --out /tmp/after-login.png --full
 browserctl url  login
 ```
 
-**5. Manage pages and daemon**
+**6. Manage pages and daemon**
 
 ```bash
 browserctl pages
@@ -119,12 +129,18 @@ browserctl shutdown
 | `close <page>` | Close a named page |
 | `pages` | List open pages |
 | `goto <page> <url>` | Navigate a page to a URL |
-| `fill <page> <selector> <value>` | Fill an input field |
-| `click <page> <selector>` | Click an element |
-| `snap <page> [--format ai\|html]` | Snapshot DOM (default: ai) |
+| `fill <page> <selector> <value>` | Fill an input field by CSS selector |
+| `fill <page> --ref <id> --value <v>` | Fill an input field by snapshot ref |
+| `click <page> <selector>` | Click an element by CSS selector |
+| `click <page> --ref <id>` | Click an element by snapshot ref |
+| `snap <page> [--format ai\|html] [--diff]` | Snapshot DOM; `--diff` returns only changed elements |
+| `watch <page> <selector> [--timeout N]` | Poll until selector appears (default timeout: 30s) |
 | `shot <page> [--out PATH] [--full]` | Take a screenshot |
 | `url <page>` | Print current URL |
 | `eval <page> <expression>` | Evaluate a JS expression |
+| `record start <name>` | Begin recording commands as a replayable workflow |
+| `record stop [--out path]` | End recording; saves to `.browserctl/workflows/` or custom path |
+| `record status` | Show whether a recording is active |
 
 ### Daemon commands
 
@@ -172,7 +188,24 @@ browserctl shutdown
 ]
 ```
 
-Use `selector` values directly with `fill` and `click`.
+Use `ref` values directly with `--ref` for zero-fragility interactions, or use `selector` values with `fill` and `click`.
+
+### Ref-based interaction
+
+After a `snap`, use ref IDs instead of CSS selectors — no selector knowledge required:
+
+```bash
+browserctl fill  login --ref e1 --value user@example.com
+browserctl click login --ref e2
+```
+
+### Diff snapshots
+
+Track only what changed since the last snapshot — useful for AI agents monitoring async updates:
+
+```bash
+browserctl snap login --diff
+```
 
 ---
 
@@ -222,6 +255,7 @@ browserctl run smoke_login --email me@example.com --password s3cr3t
 | `desc "text"` | Human-readable description |
 | `param :name, required:, secret:, default:` | Declare a parameter |
 | `step "label" { }` | Add a step (runs in order, halts on failure) |
+| `step "label", retry_count: N, timeout: S { }` | Step with retry and/or timeout |
 | `page(:name)` | Returns a `PageProxy` for the named page |
 | `invoke "other_workflow", **overrides` | Call another workflow |
 | `assert condition, "message"` | Raise `WorkflowError` if condition is false |
@@ -242,7 +276,15 @@ For a full guide on building your own workflows, see [docs/writing-workflows.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.
+`browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. Start multiple named instances for agent isolation:
+
+```bash
+browserd --name agent-a &
+browserd --name agent-b &
+browserctl --daemon agent-a open main --url https://app.example.com
+```
+
+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. Workflows run in-process through the same client.
 

data/bin/browserctl

@@ -3,41 +3,80 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "browserctl/version"
+
+if ARGV.intersect?(%w[--version -v])
+  puts "browserctl #{Browserctl::VERSION}"
+  exit 0
+end
+
 require "json"
+require "optimist"
 require "browserctl"
+require "browserctl/commands/cli_output"
 require "browserctl/commands/open_page"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
 require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
+require "browserctl/commands/watch"
+require "browserctl/commands/record"
 
+def print_result(res)
+  if res.is_a?(Hash) && res[:error]
+    warn "Error: #{res[:error]}"
+    exit 1
+  end
+  puts res.to_json
+end
+
+# rubocop:disable Metrics/MethodLength
 def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
     Browser commands (require browserd running):
-      open   <page> [--url URL]           Open or focus a named page
-      close  <page>                        Close a named page
-      pages                                List open pages
-      goto   <page> <url>                  Navigate a page
-      fill   <page> <selector> <value>     Fill an input
-      click  <page> <selector>             Click an element
-      shot   <page> [--out PATH] [--full]  Take a screenshot
-      snap   <page> [--format ai|html]     Snapshot DOM (default: ai)
-      url    <page>                        Print current URL
-      eval   <page> <expression>           Evaluate JS expression
+      open   <page> [--url URL]                   Open or focus a named page
+      close  <page>                                Close a named page
+      pages                                        List open pages
+      goto   <page> <url>                          Navigate a page
+      fill   <page> <selector> <value>             Fill an input
+             <page> --ref <ref> --value <value>    Fill via snapshot ref
+      click  <page> <selector>                     Click an element
+             <page> --ref <ref>                    Click via snapshot ref
+      shot   <page> [--out PATH] [--full]          Take a screenshot
+      snap   <page> [--format ai|html] [--diff]    Snapshot DOM (default: ai)
+      url    <page>                                Print current URL
+      eval   <page> <expression>                   Evaluate JS expression
+      watch  <page> <selector> [--timeout N]       Wait for a selector to appear
+
+    Recording commands:
+      record start <name>            Start recording browser commands
+      record stop  [--out PATH]      Stop recording and save workflow
+      record status                  Show active recording name
 
     Workflow commands:
-      run      <name|file> [--key value]   Run a workflow
-      workflows                            List available workflows
-      describe <name>                      Describe a workflow
+      run      <name|file> [--key value ...]   Run a workflow
+      workflows                                List available workflows
+      describe <name>                          Describe a workflow
 
     Daemon commands:
-      ping                                 Check if browserd is alive
-      shutdown                             Stop browserd
+      ping                   Check if browserd is alive
+      shutdown               Stop browserd
+
+    Options:
+      --daemon <name>    Connect to a named daemon instance
+      --version, -v      Print version and exit
   USAGE
   exit 0
 end
+# rubocop:enable Metrics/MethodLength
+
+daemon_idx  = ARGV.index("--daemon")
+daemon_name = if daemon_idx
+                ARGV.delete_at(daemon_idx)
+                ARGV.delete_at(daemon_idx)
+              end
 
 cmd  = ARGV.shift
 args = ARGV.dup
@@ -70,22 +109,25 @@ when "describe"
   name = args.shift or abort "usage: browserctl describe <workflow_name>"
   puts JSON.pretty_generate(runner.describe_workflow(name))
 
+when "record" then Browserctl::Commands::Record.run(args)
+
 else
-  client = Browserctl::Client.new
+  client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
-  when "open"   then Browserctl::Commands::OpenPage.run(client, args)
-  when "close"  then puts client.close_page(args[0]).to_json
-  when "pages"  then puts client.list_pages.to_json
-  when "goto"   then puts client.goto(args[0], args[1]).to_json
-  when "fill"   then Browserctl::Commands::Fill.run(client, args)
-  when "click"  then Browserctl::Commands::Click.run(client, args)
-  when "shot"   then Browserctl::Commands::Screenshot.run(client, args)
-  when "snap"   then Browserctl::Commands::Snapshot.run(client, args)
-  when "url"    then puts client.url(args[0]).to_json
-  when "eval"   then puts client.evaluate(args[0], args[1]).to_json
-  when "ping"   then puts client.ping.to_json
-  when "shutdown" then puts client.shutdown.to_json
+  when "open"     then Browserctl::Commands::OpenPage.run(client, args)
+  when "close"    then print_result(client.close_page(args[0]))
+  when "pages"    then print_result(client.list_pages)
+  when "goto"     then print_result(client.goto(args[0], args[1]))
+  when "fill"     then Browserctl::Commands::Fill.run(client, args)
+  when "click"    then Browserctl::Commands::Click.run(client, args)
+  when "shot"     then Browserctl::Commands::Screenshot.run(client, args)
+  when "snap"     then Browserctl::Commands::Snapshot.run(client, args)
+  when "url"      then print_result(client.url(args[0]))
+  when "eval"     then print_result(client.evaluate(args[0], args[1]))
+  when "watch"    then Browserctl::Commands::Watch.run(client, args)
+  when "ping"     then print_result(client.ping)
+  when "shutdown" then print_result(client.shutdown)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end

data/bin/browserd

@@ -3,8 +3,22 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "optimist"
 require "nokogiri"
+require "browserctl/logger"
 require "browserctl/server"
+require "browserctl/version"
 
-headless = !ARGV.include?("--headed")
-Browserctl::Server.new(headless: headless).run
+opts = Optimist.options do
+  version "browserd #{Browserctl::VERSION}"
+  opt :headed,    "Run with a visible browser window",        default: false,  short: "-H"
+  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", short: "-l", type: :string
+  opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
+end
+
+Browserctl.logger = Browserctl.build_logger(opts[:log_level])
+Browserctl::Server.new(
+  headless: !opts[:headed],
+  socket_path: Browserctl.socket_path(opts[:name]),
+  pid_path: Browserctl.pid_path(opts[:name])
+).run

data/lib/browserctl/client.rb

@@ -3,15 +3,18 @@
 require "socket"
 require "json"
 require_relative "constants"
+require_relative "recording"
 
 module Browserctl
   class Client
-    def initialize(socket_path = SOCKET_PATH)
+    def initialize(socket_path = Browserctl.socket_path)
       @socket_path = socket_path
     end
 
     def call(cmd, **params)
-      communicate(JSON.generate({ cmd: cmd }.merge(params)))
+      result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
+      Recording.append(cmd, **params) if result[:ok]
+      result
     rescue Errno::ENOENT, Errno::ECONNREFUSED
       raise "browserd is not running — start it with: browserd"
     end
@@ -21,12 +24,32 @@ module Browserctl
     def open_page(name, url: nil)  = call("open_page",  name: name, url: url)
     def close_page(name)           = call("close_page", name: name)
     def list_pages                 = call("list_pages")
-    def goto(name, url)            = call("goto",        name: name, url: url)
-    def fill(name, selector, val)  = call("fill",        name: name, selector: selector, value: val)
-    def click(name, selector)      = call("click",       name: name, selector: selector)
+    def goto(name, url)            = call("goto", name: name, url: url)
+
+    def click(name, selector = nil, ref: nil)
+      raise ArgumentError, "click: provide selector or ref:" unless selector || ref
+
+      call("click", name: name, selector: selector, ref: ref)
+    end
+
+    def fill(name, selector = nil, value = nil, ref: nil)
+      raise ArgumentError, "fill: provide selector or ref:" unless selector || ref
+
+      call("fill", name: name, selector: selector, ref: ref, value: value)
+    end
+
     def screenshot(name, path: nil, full: false) = call("screenshot", name: name, path: path, full: full)
-    def snapshot(name, format: "ai")             = call("snapshot",   name: name, format: format)
-    def wait_for(name, selector, timeout: 10)    = call("wait_for",   name: name, selector: selector, timeout: timeout)
+
+    def snapshot(name, format: "ai", diff: false)
+      call("snapshot", name: name, format: format, diff: diff)
+    end
+
+    def wait_for(name, selector, timeout: 10) = call("wait_for", name: name, selector: selector, timeout: timeout)
+
+    def watch(name, selector, timeout: 30)
+      call("watch", name: name, selector: selector, timeout: timeout)
+    end
+
     def url(name)                  = call("url",         name: name)
     def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)
     def ping                       = call("ping")

data/lib/browserctl/commands/cli_output.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    module CliOutput
+      def print_result(res)
+        if res.is_a?(Hash) && res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts res.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/click.rb

@@ -1,12 +1,28 @@
 # frozen_string_literal: true
 
+require "optimist"
+require_relative "cli_output"
+
 module Browserctl
   module Commands
     class Click
+      extend CliOutput
+
       def self.run(client, args)
-        name, selector = args
-        abort "usage: browserctl click <page> <selector>" unless name && selector
-        puts client.click(name, selector).to_json
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl click <page> <selector>\n       " \
+                 "browserctl click <page> --ref <ref>"
+          opt :ref, "Snapshot ref to click", type: :string, short: "-r"
+        end
+        name = args.shift
+        if opts[:ref]
+          abort "usage: browserctl click <page> --ref <ref>" unless name
+          print_result(client.click(name, ref: opts[:ref]))
+        else
+          selector = args.shift
+          abort "usage: browserctl click <page> <selector>" unless name && selector
+          print_result(client.click(name, selector))
+        end
       end
     end
   end

data/lib/browserctl/commands/fill.rb

@@ -1,12 +1,38 @@
 # frozen_string_literal: true
 
+require "optimist"
+require_relative "cli_output"
+
 module Browserctl
   module Commands
     class Fill
+      extend CliOutput
+
       def self.run(client, args)
-        name, selector, value = args
-        abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
-        puts client.fill(name, selector, value).to_json
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl fill <page> <selector> <value>\n       " \
+                 "browserctl fill <page> --ref <ref> --value <value>"
+          opt :ref,   "Snapshot ref to fill", type: :string, short: "-r"
+          opt :value, "Value to fill",        type: :string, short: "-V"
+        end
+        name = args.shift
+        opts[:ref] ? fill_by_ref(client, name, opts) : fill_by_selector(client, name, args, opts[:value])
+      end
+
+      class << self
+        private
+
+        def fill_by_ref(client, name, opts)
+          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && opts[:value]
+          print_result(client.fill(name, nil, opts[:value], ref: opts[:ref]))
+        end
+
+        def fill_by_selector(client, name, args, value_opt)
+          selector = args.shift
+          value    = value_opt || args.shift
+          abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
+          print_result(client.fill(name, selector, value))
+        end
       end
     end
   end

data/lib/browserctl/commands/open_page.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class OpenPage
+      extend CliOutput
+
       def self.run(client, args)
-        name = args.shift or abort "usage: browserctl open <name> [--url URL]"
-        url  = FlagExtractor.extract_opt(args, "--url")
-        res  = client.open_page(name, url: url)
-        puts res.to_json
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl open <page> [--url URL]"
+          opt :url, "URL to navigate to", type: :string, short: "-u"
+        end
+        name = args.shift or abort "usage: browserctl open <page> [--url URL]"
+        print_result(client.open_page(name, url: opts[:url]))
       end
     end
   end

data/lib/browserctl/commands/record.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optimist"
+require "browserctl/recording"
+
+module Browserctl
+  module Commands
+    class Record
+      USAGE = "Usage: browserctl record start <name> | stop [--out PATH] | status"
+
+      def self.run(args)
+        subcmd = args.shift
+        case subcmd
+        when "start"  then run_start(args)
+        when "stop"   then run_stop(args)
+        when "status" then run_status
+        else
+          abort "#{USAGE}\nRun 'browserctl record <subcommand> --help' for details."
+        end
+      end
+
+      class << self
+        private
+
+        def run_start(args)
+          Optimist.options(args) { banner "Usage: browserctl record start <name>" }
+          name = args.shift or abort "usage: browserctl record start <name>"
+          Recording.start(name)
+          puts "Recording started: #{name}"
+          puts "Run browser commands, then: browserctl record stop"
+        end
+
+        def run_stop(args)
+          opts = Optimist.options(args) do
+            banner "Usage: browserctl record stop [--out PATH]"
+            opt :out, "Output path for workflow file", type: :string, short: "-o"
+          end
+          name = Recording.stop
+          out  = opts[:out] || File.join(".browserctl/workflows", "#{name}.rb")
+          FileUtils.mkdir_p(File.dirname(out))
+          Recording.generate_workflow(name, output_path: out)
+          puts "Workflow saved: #{out}"
+          puts "Run with: browserctl run #{name}"
+        end
+
+        def run_status
+          active = Recording.active
+          puts active ? "Active recording: #{active}" : "No active recording."
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/commands/screenshot.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Screenshot
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl shot <page> [--out PATH] [--full]"
+          opt :out,  "Output file path",   type: :string, short: "-o"
+          opt :full, "Capture full page",  default: false, short: "-f"
+        end
         name = args.shift or abort "usage: browserctl shot <page> [--out PATH] [--full]"
-        path = FlagExtractor.extract_opt(args, "--out")
-        full = args.delete("--full") ? true : false
-        puts client.screenshot(name, path: path, full: full).to_json
+        print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end
   end

data/lib/browserctl/commands/snapshot.rb

@@ -1,24 +1,36 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "flag_extractor"
+require "optimist"
 
 module Browserctl
   module Commands
     class Snapshot
+      VALID_FORMATS = %w[ai html].freeze
+
       def self.run(client, args)
-        name   = args.shift or abort "usage: browserctl snapshot <page> [--format ai|html]"
-        format = FlagExtractor.extract_opt(args, "--format") || "ai"
-        res    = client.snapshot(name, format: format)
-        output_snapshot(res, format)
+        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"
+          opt :diff,   "Return only changed elements", default: false, short: "-d"
+        end
+        name = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
+        unless VALID_FORMATS.include?(opts[:format])
+          warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
+          exit 1
+        end
+        res = client.snapshot(name, format: opts[:format], diff: opts[:diff])
+        output_snapshot(res, opts[:format])
       end
 
       class << self
         private
 
         def output_snapshot(res, format)
-          return abort res[:error] if res[:error]
-
+          if res[:error]
+            warn "Error: #{res[:error]}"
+            exit 1
+          end
           puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
         end
       end

data/lib/browserctl/commands/watch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "optimist"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    class Watch
+      extend CliOutput
+
+      def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl watch <page> <selector> [--timeout N]"
+          opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+        end
+        name     = args.shift
+        selector = args.shift
+        abort "usage: browserctl watch <page> <selector> [--timeout N]" unless name && selector
+        unless opts[:timeout].positive?
+          warn "Error: --timeout must be a positive number"
+          exit 1
+        end
+        print_result(client.watch(name, selector, timeout: opts[:timeout]))
+      end
+    end
+  end
+end

data/lib/browserctl/constants.rb

@@ -1,7 +1,18 @@
 # frozen_string_literal: true
 
 module Browserctl
-  SOCKET_PATH = File.expand_path("~/.browserctl/browserd.sock")
-  PID_PATH    = File.expand_path("~/.browserctl/browserd.pid")
-  IDLE_TTL    = 30 * 60
+  BROWSERCTL_DIR = File.expand_path("~/.browserctl")
+  IDLE_TTL       = 30 * 60
+
+  def self.socket_path(name = nil)
+    File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")
+  end
+
+  def self.pid_path(name = nil)
+    File.join(BROWSERCTL_DIR, name ? "#{name}.pid" : "browserd.pid")
+  end
+
+  # Backward-compatible constants
+  SOCKET_PATH = socket_path
+  PID_PATH    = pid_path
 end

data/lib/browserctl/logger.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Browserctl
+  LEVEL_MAP = {
+    "debug" => ::Logger::DEBUG,
+    "info" => ::Logger::INFO,
+    "warn" => ::Logger::WARN,
+    "error" => ::Logger::ERROR
+  }.freeze
+
+  def self.logger
+    @logger ||= build_logger("info")
+  end
+
+  def self.logger=(instance)
+    @logger = instance
+  end
+
+  def self.build_logger(level_name)
+    log = ::Logger.new($stderr)
+    log.level    = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
+    log.progname = "browserd"
+    log.formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+    log
+  end
+end

data/lib/browserctl/recording.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "date"
+require "fileutils"
+require "tmpdir"
+
+module Browserctl
+  class Recording
+    RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
+    STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
+
+    RECORDABLE = %w[open_page goto fill click screenshot evaluate].freeze
+
+    def self.start(name)
+      FileUtils.mkdir_p(RECORDINGS_DIR)
+      FileUtils.mkdir_p(File.dirname(STATE_FILE))
+      File.write(STATE_FILE, name)
+      FileUtils.rm_f(log_path(name))
+      name
+    end
+
+    def self.stop
+      name = active
+      raise "no active recording — run: browserctl record start <name>" unless name
+
+      File.unlink(STATE_FILE)
+      name
+    end
+
+    def self.active
+      File.exist?(STATE_FILE) ? File.read(STATE_FILE).strip : nil
+    end
+
+    def self.append(cmd, **attrs)
+      name = active
+      return unless name
+      return unless RECORDABLE.include?(cmd.to_s)
+      # ref-based interactions have no replayable selector — skip them
+      return if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
+
+      File.open(log_path(name), "a") do |f|
+        f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
+      end
+    end
+
+    def self.generate_workflow(name, output_path: nil)
+      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) }
+      ruby  = build_workflow_ruby(name, lines)
+      File.write(output_path, ruby) if output_path
+      ruby
+    ensure
+      FileUtils.rm_f(log) if log
+    end
+
+    class << self
+      private
+
+      def log_path(name)
+        File.join(RECORDINGS_DIR, "#{name}.jsonl")
+      end
+
+      def build_workflow_ruby(name, commands)
+        steps = commands.map { |c| build_step(c) }.join("\n\n")
+        <<~RUBY
+          # frozen_string_literal: true
+
+          Browserctl.workflow #{name.inspect} do
+            desc "Recorded on #{Date.today}"
+
+          #{steps.gsub(/^/, '  ')}
+          end
+        RUBY
+      end
+
+      def build_step(cmd)
+        label, body = step_parts(cmd)
+        "step #{label.inspect} do\n  #{body}\nend"
+      end
+
+      def step_parts(cmd)
+        page = cmd[:name]
+        case cmd[:cmd]
+        when "open_page"
+          ["open #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
+        when "goto"
+          ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
+        when "fill"
+          ["fill #{cmd[:selector]} on #{page}",
+           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{cmd[:value].inspect})"]
+        when "click"
+          ["click #{cmd[:selector]} on #{page}",
+           "page(:#{page}).click(#{cmd[:selector].inspect})"]
+        when "screenshot"
+          ["screenshot #{page}", "page(:#{page}).screenshot"]
+        when "evaluate"
+          ["eval on #{page}", "page(:#{page}).evaluate(#{cmd[:expression].inspect})"]
+        else
+          ["#{cmd[:cmd]} on #{page}", "# unrecognised command: #{cmd.inspect}"]
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/runner.rb

@@ -24,7 +24,7 @@ module Browserctl
 
     def describe_workflow(name)
       defn = fetch_workflow(name)
-      { name: defn.name, desc: defn.description, params: format_params(defn), steps: defn.steps.map(&:first) }
+      { name: defn.name, desc: defn.description, params: format_params(defn), steps: defn.steps.map(&:label) }
     end
 
     private

data/lib/browserctl/server/command_dispatcher.rb

@@ -15,32 +15,33 @@ module Browserctl
       "click" => :cmd_click,
       "screenshot" => :cmd_screenshot,
       "wait_for" => :cmd_wait_for,
+      "watch" => :cmd_watch,
       "url" => :cmd_url,
       "ping" => :cmd_ping,
       "shutdown" => :cmd_shutdown
     }.freeze
 
     def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, mutex: Mutex.new)
-      @pages    = pages
-      @browser  = browser
-      @snapshot = snapshot_builder
-      @mutex    = mutex
+      @pages          = pages
+      @browser        = browser
+      @snapshot       = snapshot_builder
+      @mutex          = mutex
+      @ref_registries = {}
+      @prev_snapshots = {}
     end
 
     def dispatch(req)
       handler = COMMAND_MAP[req[:cmd]]
       return { error: "unknown command: #{req[:cmd]}" } unless handler
 
+      Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
       send(handler, req)
     end
 
     private
 
     def cmd_open_page(req)
-      page = @mutex.synchronize { @pages[req[:name]] } || begin
-        new_page = @browser.create_page
-        @mutex.synchronize { @pages[req[:name]] ||= new_page }
-      end
+      page = @mutex.synchronize { @pages[req[:name]] ||= @browser.create_page }
       page.go_to(req[:url]) if req[:url]
       { ok: true, name: req[:name] }
     end
@@ -62,11 +63,31 @@ module Browserctl
     end
 
     def cmd_snapshot(req)
-      with_page(req[:name]) { |p| build_snapshot(p, req[:format]) }
+      with_page(req[:name]) { |p| take_snapshot(req[:name], p, req[:format], req[:diff]) }
     end
 
-    def build_snapshot(page, format)
-      format == "ai" ? { ok: true, snapshot: @snapshot.call(page) } : { ok: true, html: page.body }
+    def take_snapshot(name, page, format, diff)
+      return { ok: true, html: page.body } unless format == "ai"
+
+      snapshot = @snapshot.call(page)
+      registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
+
+      result = @mutex.synchronize do
+        prev = @prev_snapshots[name]
+        @ref_registries[name] = registry
+        @prev_snapshots[name] = snapshot
+        diff && prev ? compute_diff(prev, snapshot) : snapshot
+      end
+
+      { ok: true, snapshot: result }
+    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)
@@ -74,7 +95,10 @@ module Browserctl
     end
 
     def cmd_fill(req)
-      with_page(req[:name]) { |p| type_into(p, req[:selector], req[:value]) }
+      sel = resolve_selector(req[:name], req)
+      return sel if sel.is_a?(Hash)
+
+      with_page(req[:name]) { |p| type_into(p, sel, req[:value]) }
     end
 
     def type_into(page, selector, value)
@@ -87,7 +111,10 @@ module Browserctl
     end
 
     def cmd_click(req)
-      with_page(req[:name]) { |p| click_element(p, req[:selector]) }
+      sel = resolve_selector(req[:name], req)
+      return sel if sel.is_a?(Hash)
+
+      with_page(req[:name]) { |p| click_element(p, sel) }
     end
 
     def click_element(page, selector)
@@ -110,6 +137,13 @@ module Browserctl
       with_page(req[:name]) { |p| wait_for_selector(p, req[:selector], req.fetch(:timeout, 10).to_f) }
     end
 
+    def cmd_watch(req)
+      with_page(req[:name]) do |p|
+        result = wait_for_selector(p, 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
       sleep 0.2 until (found = page.at_css(selector)) || Time.now > deadline
@@ -135,5 +169,13 @@ module Browserctl
 
       yield page
     end
+
+    def resolve_selector(name, req)
+      return req[:selector] if req[:selector]
+      return { error: "selector or ref required" } unless req[:ref]
+
+      sel = @mutex.synchronize { @ref_registries.dig(name, req[:ref]) }
+      sel || { error: "ref '#{req[:ref]}' not found — run snap first" }
+    end
   end
 end

data/lib/browserctl/server/idle_watcher.rb

@@ -25,7 +25,7 @@ module Browserctl
     end
 
     def shutdown(server)
-      $stdout.puts "browserd idle timeout, shutting down"
+      Browserctl.logger.info "idle timeout (#{IDLE_TTL / 60}min), shutting down"
       quietly { server.close }
       Process.kill("INT", Process.pid)
     end

data/lib/browserctl/server.rb

@@ -6,12 +6,15 @@ require "json"
 require "fileutils"
 require "timeout"
 require_relative "constants"
+require_relative "logger"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
 
 module Browserctl
   class Server
-    def initialize(headless: true)
+    def initialize(headless: true, socket_path: SOCKET_PATH, pid_path: PID_PATH)
+      @socket_path = socket_path
+      @pid_path    = pid_path
       prepare_runtime(headless)
       @dispatcher = CommandDispatcher.new(@pages, @browser, mutex: @mutex)
     end
@@ -29,7 +32,7 @@ module Browserctl
     private
 
     def prepare_runtime(headless)
-      FileUtils.mkdir_p(File.dirname(SOCKET_PATH))
+      FileUtils.mkdir_p(File.dirname(@socket_path))
       @browser = init_browser(headless)
       init_state
     end
@@ -56,18 +59,13 @@ module Browserctl
     end
 
     def setup_socket
-      FileUtils.rm_f(SOCKET_PATH)
-      server = UNIXServer.new(SOCKET_PATH)
-      File.chmod(0o600, SOCKET_PATH)
-      announce_socket
+      FileUtils.rm_f(@socket_path)
+      server = UNIXServer.new(@socket_path)
+      File.chmod(0o600, @socket_path)
+      Browserctl.logger.info "listening on #{@socket_path}"
       server
     end
 
-    def announce_socket
-      $stdout.puts "browserd listening on #{SOCKET_PATH}"
-      $stdout.flush
-    end
-
     def serve(server)
       loop do
         client = server.accept
@@ -78,6 +76,7 @@ module Browserctl
     def handle(socket)
       dispatch(socket, socket.gets)
     rescue StandardError => e
+      Browserctl.logger.error "#{e.class}: #{e.message}"
       quietly { socket.puts JSON.generate({ error: e.message }) }
     ensure
       quietly { socket.close }
@@ -100,12 +99,12 @@ module Browserctl
       idle&.kill
       quietly { server&.close }
       quietly { Timeout.timeout(5) { @browser.quit } }
-      quietly { File.unlink(SOCKET_PATH) }
-      quietly { File.unlink(PID_PATH) }
+      quietly { File.unlink(@socket_path) }
+      quietly { File.unlink(@pid_path) }
     end
 
     def write_pid
-      File.write(PID_PATH, Process.pid.to_s)
+      File.write(@pid_path, Process.pid.to_s)
     end
 
     def quietly

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "timeout"
 require_relative "client"
 
 module Browserctl
@@ -7,6 +8,7 @@ module Browserctl
 
   ParamDef = Struct.new(:name, :required, :secret, :default, keyword_init: true)
   StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
+  StepDef = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
 
   class WorkflowContext
     attr_reader :client
@@ -106,8 +108,8 @@ module Browserctl
       @param_defs[name] = ParamDef.new(name: name, required: required, secret: secret, default: default)
     end
 
-    def step(label, &block)
-      @steps << [label, block]
+    def step(label, retry_count: 0, timeout: nil, &block)
+      @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
     end
 
     def call(params, client)
@@ -118,16 +120,30 @@ module Browserctl
     private
 
     def execute_steps(ctx)
-      @steps.map { |label, block| run_step(ctx, label, block) }.each do |r|
+      @steps.map { |defn| run_step(ctx, defn) }.each do |r|
         raise WorkflowError, "step '#{r.name}' failed: #{r.error}" unless r.ok
       end
     end
 
-    def run_step(ctx, label, block)
-      ctx.instance_exec(&block)
-      StepResult.new(name: label, ok: true)
-    rescue WorkflowError, StandardError => e
-      StepResult.new(name: label, ok: false, error: e.message)
+    def run_step(ctx, defn)
+      last_error = nil
+      (defn.retry_count + 1).times do
+        execute_block(ctx, defn)
+        return StepResult.new(name: defn.label, ok: true)
+      rescue WorkflowError, StandardError => e
+        last_error = e
+      end
+      StepResult.new(name: defn.label, ok: false, error: last_error.message)
+    end
+
+    def execute_block(ctx, defn)
+      if defn.timeout
+        ::Timeout.timeout(defn.timeout) { ctx.instance_exec(&defn.block) }
+      else
+        ctx.instance_exec(&defn.block)
+      end
+    rescue ::Timeout::Error
+      raise WorkflowError, "step '#{defn.label}' timed out after #{defn.timeout}s"
     end
 
     def resolve_params(provided)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-19 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -103,13 +103,17 @@ files:
 - examples/the_internet/login.rb
 - lib/browserctl.rb
 - lib/browserctl/client.rb
+- lib/browserctl/commands/cli_output.rb
 - lib/browserctl/commands/click.rb
 - lib/browserctl/commands/fill.rb
-- lib/browserctl/commands/flag_extractor.rb
 - lib/browserctl/commands/open_page.rb
+- lib/browserctl/commands/record.rb
 - lib/browserctl/commands/screenshot.rb
 - lib/browserctl/commands/snapshot.rb
+- lib/browserctl/commands/watch.rb
 - lib/browserctl/constants.rb
+- lib/browserctl/logger.rb
+- lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb

data/lib/browserctl/commands/flag_extractor.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    module FlagExtractor
-      def self.extract_opt(args, flag)
-        i = args.index(flag)
-        return unless i
-
-        args.delete_at(i)
-        args.delete_at(i)
-      end
-    end
-  end
-end