browserctl 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2976bab368591b4cb06cd3a34d64c1078bd8588590d70c67ba3d78ecd721e572
-  data.tar.gz: 0fa9c86ec532df2c6763780bfb6c2ac47380ff1df400ae2639fe914fc66e0d04
+  metadata.gz: 7b5b21accfeb82afa82dc2c12d51ef7da31ed8ab9db073d2b576df0385e5adb6
+  data.tar.gz: d9cd601ce2d63b5c3f2c8d539d14dc684dcf3753a7f95002b9c165791ff2f584
 SHA512:
-  metadata.gz: ef5ab4df359bde2cc6b635f6ac77c1147df57e85c57ff61222179f223e4d41ef4d58b622aa928cde19c41b1927d6ebafd273847ada8c55bf74cfdc09b6ddb5c7
-  data.tar.gz: 0af88adb9b7076a4408c65ac25e7d13fd0f70aa2cdf79448fe9be7953695bd12de01d9c98626628163ce8edb738b4d2c83a925a77e2504924b1ee6bfe85c39d3
+  metadata.gz: 5bc9c337336ac4fb23da1966a9b51e3dffcef8b23ea00a2990310a0aae5978ccf423416118ebe61b83c92ca84f38846ca16ca909a376e2e3e8f13eb97e82b045
+  data.tar.gz: 13b8b5fcbc17e328210488ce8e50ead2ea8576419dc5d493c06285d8e191a4be7599a04a58b651f501febb351704609be6dc06c0c8c00c827a7c796667072943

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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

@@ -10,6 +10,8 @@ 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 usage
   puts <<~USAGE
@@ -26,6 +28,12 @@ def usage
       snap   <page> [--format ai|html]     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
@@ -35,10 +43,19 @@ def usage
     Daemon commands:
       ping                                 Check if browserd is alive
       shutdown                             Stop browserd
+
+    Options:
+      --daemon <name>    Connect to a named daemon instance
   USAGE
   exit 0
 end
 
+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,8 +87,10 @@ 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)
@@ -84,6 +103,7 @@ else
   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 "watch"  then Browserctl::Commands::Watch.run(client, args)
   when "ping"   then puts client.ping.to_json
   when "shutdown" then puts client.shutdown.to_json
   else

data/bin/browserd

@@ -3,8 +3,20 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "optimist"
 require "nokogiri"
+require "browserctl/logger"
 require "browserctl/server"
 
-headless = !ARGV.include?("--headed")
-Browserctl::Server.new(headless: headless).run
+opts = Optimist.options do
+  opt :headed,    "Run with a visible browser window",        default: false
+  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", type: :string
+  opt :name,      "Daemon instance name for multi-agent use", default: nil, 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/click.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "flag_extractor"
+
 module Browserctl
   module Commands
     class Click
       def self.run(client, args)
-        name, selector = args
-        abort "usage: browserctl click <page> <selector>" unless name && selector
-        puts client.click(name, selector).to_json
+        name = args.shift
+        ref  = FlagExtractor.extract_opt(args, "--ref")
+        selector = args.shift unless ref
+
+        if ref
+          abort "usage: browserctl click <page> --ref <ref>" unless name
+          puts client.click(name, ref: ref).to_json
+        else
+          abort "usage: browserctl click <page> <selector>" unless name && selector
+          puts client.click(name, selector).to_json
+        end
       end
     end
   end

data/lib/browserctl/commands/fill.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "flag_extractor"
+
 module Browserctl
   module Commands
     class Fill
       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
+        name = args.shift
+        ref  = FlagExtractor.extract_opt(args, "--ref")
+
+        if ref
+          value = FlagExtractor.extract_opt(args, "--value")
+          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && value
+          puts client.fill(name, nil, value, ref: ref).to_json
+        else
+          selector = args.shift
+          value = args.shift
+          abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
+          puts client.fill(name, selector, value).to_json
+        end
       end
     end
   end

data/lib/browserctl/commands/flag_extractor.rb

@@ -7,8 +7,16 @@ module Browserctl
         i = args.index(flag)
         return unless i
 
+        sliced = args.slice!(i, 2)
+        sliced.length == 2 ? sliced.last : nil
+      end
+
+      def self.extract_flag?(args, flag)
+        i = args.index(flag)
+        return false unless i
+
         args.delete_at(i)
-        args.delete_at(i)
+        true
       end
     end
   end

data/lib/browserctl/commands/record.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+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
+        end
+      end
+
+      class << self
+        private
+
+        def run_start(args)
+          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)
+          idx = args.index("--out")
+          out = if idx
+                  args.delete_at(idx)
+                  args.delete_at(idx)
+                end
+          name = Recording.stop
+          if out
+            FileUtils.mkdir_p(File.dirname(out))
+            Recording.generate_workflow(name, output_path: out)
+            puts "Workflow saved: #{out}"
+          else
+            dest_dir  = ".browserctl/workflows"
+            dest_file = File.join(dest_dir, "#{name}.rb")
+            FileUtils.mkdir_p(dest_dir)
+            Recording.generate_workflow(name, output_path: dest_file)
+            puts "Workflow saved: #{dest_file}"
+          end
+          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/snapshot.rb

@@ -7,9 +7,10 @@ module Browserctl
   module Commands
     class Snapshot
       def self.run(client, args)
-        name   = args.shift or abort "usage: browserctl snapshot <page> [--format ai|html]"
+        name   = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
         format = FlagExtractor.extract_opt(args, "--format") || "ai"
-        res    = client.snapshot(name, format: format)
+        diff   = FlagExtractor.extract_flag?(args, "--diff")
+        res    = client.snapshot(name, format: format, diff: diff)
         output_snapshot(res, format)
       end
 

data/lib/browserctl/commands/watch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "flag_extractor"
+
+module Browserctl
+  module Commands
+    class Watch
+      def self.run(client, args)
+        name     = args.shift
+        selector = args.shift
+        timeout  = (FlagExtractor.extract_opt(args, "--timeout") || 30).to_f
+        abort "usage: browserctl watch <page> <selector> [--timeout N]" unless name && selector
+        puts client.watch(name, selector, timeout: timeout).to_json
+      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.0"
 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.0
 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
@@ -107,9 +107,13 @@ files:
 - 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