browserctl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db03c20d156ddbfc0c81267889ce46be79cb9973f2ff55af65739ddfe370f9f6
+  data.tar.gz: 712a9ffd6206cd0c1e3614d0d7230bb1c998beed56d315313328b0c768c5d3ea
+SHA512:
+  metadata.gz: 7780abfa304abcbfb252fee4a41ff5bd592275e8fe6ac66b30ab3e2022b8e0a48c94b046458f5d10b215cef89f75c94691de16b0158378357f863bf6a2dc5a15
+  data.tar.gz: d7b0051c9b2c13bf79313cb0e5edb58062ebe4a9ae9a77a836a2e1394a5f537d72aa2bf61bbb3003dcb30d8eef66cd873d68b6cda394eb9a5c6f078ae6143c90

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+### Fixed
+- Thread safety: all server dispatch calls now protected by a Mutex
+- `fill` no longer queries the DOM twice; returns an error if selector is not found
+- `click` now returns an error when the selector is not found instead of silently succeeding
+- `wait_for` now polls for the selector until timeout instead of checking once after network idle
+- Circular workflow `invoke` calls now raise a descriptive `WorkflowError`
+
+### Added
+- GitHub Actions CI (lint + test across Ruby 3.2–3.4)
+- Gemspec metadata: `changelog_uri`, `source_code_uri`, `bug_tracker_uri`, `rubygems_mfa_required`
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release: persistent browser daemon (`browserd`) over Unix socket
+- CLI (`browserctl`) with commands: open, close, pages, goto, fill, click, shot, snap, url, eval, ping, shutdown
+- Ruby workflow DSL with params, steps, assertions, and `invoke`
+- AI-optimized DOM snapshot format (JSON with ref IDs)
+- Ferrum-backed Chrome/Chromium automation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 patrick204nqh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,272 @@
+<p align="center">
+  <img src=".github/logo.svg" width="96" height="96" alt="browserctl logo"/>
+</p>
+
+# browserctl
+
+[![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)
+
+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.
+
+```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 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>
+
+---
+
+## Why browserctl?
+
+Most automation tools are stateless — every script spins up a fresh browser and tears it down. browserctl doesn't.
+
+| | browserctl | Playwright / Selenium |
+|---|---|---|
+| Session persists across commands | ✓ | ✗ (per-script lifecycle) |
+| Named page handles | ✓ | ✗ |
+| AI-friendly DOM snapshot | ✓ | ✗ |
+| Lightweight CLI interface | ✓ | ✗ |
+| Full browser automation API | — | ✓ |
+| Parallel multi-browser testing | — | ✓ |
+
+**Use browserctl when** you need a browser that stays alive and remembers state — for AI agents, iterative dev workflows, or lightweight smoke tests.
+
+**Use Playwright/Selenium when** you need parallel test suites, multi-browser support, or a full programmatic API.
+
+---
+
+## Requirements
+
+- Ruby >= 3.2
+- Chrome or Chromium installed and on `PATH`
+
+---
+
+## Installation
+
+```bash
+gem install browserctl
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "browserctl"
+```
+
+---
+
+## Quick Start
+
+**1. Start the daemon**
+
+```bash
+browserd           # headless (default)
+browserd --headed  # visible browser window
+```
+
+**2. Open a named page**
+
+```bash
+browserctl open login --url https://app.example.com/login
+```
+
+**3. Interact with the page**
+
+```bash
+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**
+
+```bash
+browserctl snap login              # AI-friendly JSON (default)
+browserctl snap login --format html
+browserctl shot login --out /tmp/after-login.png --full
+browserctl url  login
+```
+
+**5. Manage pages and daemon**
+
+```bash
+browserctl pages
+browserctl close login
+browserctl ping
+browserctl shutdown
+```
+
+---
+
+## All Commands
+
+### Browser commands _(require `browserd` running)_
+
+| Command | Description |
+|---|---|
+| `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 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) |
+| `shot <page> [--out PATH] [--full]` | Take a screenshot |
+| `url <page>` | Print current URL |
+| `eval <page> <expression>` | Evaluate a JS expression |
+
+### Daemon commands
+
+| Command | Description |
+|---|---|
+| `ping` | Check if `browserd` is alive |
+| `shutdown` | Stop `browserd` |
+
+### Workflow commands
+
+| Command | Description |
+|---|---|
+| `run <name\|file.rb> [--key value ...]` | Run a named workflow or workflow file |
+| `workflows` | List available workflows |
+| `describe <name>` | Show workflow params and steps |
+
+---
+
+## AI Snapshot Format
+
+`browserctl snap <page>` returns a compact JSON array of interactable elements — designed to be token-efficient for AI agents:
+
+```json
+[
+  {
+    "ref": "e1",
+    "tag": "input",
+    "text": "",
+    "selector": "form > input[name=email]",
+    "attrs": {
+      "type": "email",
+      "name": "email",
+      "placeholder": "Enter email"
+    }
+  },
+  {
+    "ref": "e2",
+    "tag": "button",
+    "text": "Sign in",
+    "selector": "form > button",
+    "attrs": {
+      "type": "submit"
+    }
+  }
+]
+```
+
+Use `selector` values directly with `fill` and `click`.
+
+---
+
+## Workflows
+
+Workflows are Ruby files using the `Browserctl.workflow` DSL. Place them in any of:
+
+- `./.browserctl/workflows/`
+- `~/.browserctl/workflows/`
+
+### Example
+
+```ruby
+# .browserctl/workflows/smoke_login.rb
+Browserctl.workflow "smoke_login" do
+  desc "Log in and confirm the dashboard loads"
+
+  param :email,    required: true
+  param :password, required: true, secret: true
+  param :base_url, default: "https://app.example.com"
+
+  step "open login page" do
+    page(:login).goto("#{base_url}/login")
+  end
+
+  step "submit credentials" do
+    page(:login).fill("input[name=email]",    email)
+    page(:login).fill("input[name=password]", password)
+    page(:login).click("button[type=submit]")
+  end
+
+  step "verify dashboard" do
+    page(:login).wait_for("[data-test=dashboard]", timeout: 10)
+    assert page(:login).url.include?("/dashboard")
+  end
+end
+```
+
+```bash
+browserctl run smoke_login --email me@example.com --password s3cr3t
+```
+
+### Workflow DSL reference
+
+| Method | Description |
+|---|---|
+| `desc "text"` | Human-readable description |
+| `param :name, required:, secret:, default:` | Declare a parameter |
+| `step "label" { }` | Add a step (runs in order, halts on failure) |
+| `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 |
+
+### PageProxy methods
+
+`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)`
+
+---
+
+## Examples
+
+Ready-to-run smoke tests against [the-internet.herokuapp.com](https://the-internet.herokuapp.com) are included in `examples/the_internet/`. See [docs/smoke-testing-the-internet.md](docs/smoke-testing-the-internet.md) for annotated output and auto-generated screenshots of each scenario.
+
+For a full guide on building your own workflows, see [docs/writing-workflows.md](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.
+
+`browserctl` sends JSON-RPC commands over the socket and prints the result. Workflows run in-process through the same client.
+
+The daemon shuts itself down after 30 minutes of inactivity.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/patrick204nqh/browserctl
+cd browserctl
+bin/setup              # install deps + check for Chrome
+
+bundle exec rspec      # run tests
+bundle exec rubocop    # lint
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md)
+
+## License
+
+[MIT](LICENSE)

data/bin/browserctl

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "json"
+require "browserctl"
+require "browserctl/commands/open_page"
+require "browserctl/commands/fill"
+require "browserctl/commands/click"
+require "browserctl/commands/snapshot"
+require "browserctl/commands/screenshot"
+
+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
+
+    Workflow commands:
+      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
+  USAGE
+  exit 0
+end
+
+cmd  = ARGV.shift
+args = ARGV.dup
+
+usage if cmd.nil? || %w[-h --help help].include?(cmd)
+
+runner = Browserctl::Runner.new
+
+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
+    load File.expand_path(name)
+    name = (Browserctl::REGISTRY.keys - before).first || File.basename(name, ".rb")
+  end
+  params = {}
+  args.each_slice(2) do |flag, val|
+    key = flag.sub(/\A--/, "").to_sym
+    params[key] = val
+  end
+  success = runner.run_workflow(name, **params)
+  exit(success ? 0 : 1)
+
+when "workflows"
+  list = runner.list_workflows
+  list.each { |w| puts "#{w[:name].ljust(24)} #{w[:desc]}" }
+
+when "describe"
+  name = args.shift or abort "usage: browserctl describe <workflow_name>"
+  puts JSON.pretty_generate(runner.describe_workflow(name))
+
+else
+  client = Browserctl::Client.new
+
+  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
+  else
+    abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
+  end
+end

data/bin/browserd

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "nokogiri"
+require "browserctl/server"
+
+headless = !ARGV.include?("--headed")
+Browserctl::Server.new(headless: headless).run

data/bin/setup

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "==> Installing 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 "         Ubuntu: sudo apt-get install -y chromium-browser"
+fi
+
+echo ""
+echo "Done. Try: bundle exec browserd &"

data/examples/the_internet/add_remove_elements.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "the_internet/add_remove_elements" do
+  desc "Add/Remove Elements: add several elements, remove some, assert final count"
+
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open add/remove elements page" do
+    client.open_page("main", url: "#{base_url}/add_remove_elements/")
+  end
+
+  step "add three elements" do
+    3.times { page(:main).click("button[onclick]") }
+    count = client.evaluate("main", "document.querySelectorAll('#elements button').length")[:result]
+    assert count == 3, "expected 3 elements, got: #{count}"
+    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
+    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_add_remove_elements.png")
+  end
+
+  step "remove one element" do
+    page(:main).click("#elements button:first-child")
+    count = client.evaluate("main", "document.querySelectorAll('#elements button').length")[:result]
+    assert count == 2, "expected 2 elements after removal, got: #{count}"
+  end
+
+  step "remove all remaining elements" do
+    2.times { page(:main).click("#elements button:first-child") }
+    count = client.evaluate("main", "document.querySelectorAll('#elements button').length")[:result]
+    assert count.zero?, "expected 0 elements, got: #{count}"
+  end
+end

data/examples/the_internet/checkboxes.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "the_internet/checkboxes" do
+  desc "Checkboxes: read state, toggle each, verify both checked"
+
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open checkboxes page" do
+    client.open_page("main", url: "#{base_url}/checkboxes")
+  end
+
+  step "read initial state" do
+    js = "Array.from(document.querySelectorAll('input[type=checkbox]')).map(c => c.checked)"
+    states = client.evaluate("main", js)[:result]
+    assert states == [false, true], "expected initial state [false, true], got: #{states.inspect}"
+  end
+
+  step "toggle first checkbox on" do
+    page(:main).click("form#checkboxes input:first-child")
+    js = "document.querySelector('form#checkboxes input:first-child').checked"
+    checked = client.evaluate("main", js)[:result]
+    assert checked == true, "expected first checkbox to be checked"
+  end
+
+  step "verify both checkboxes are now checked" do
+    js = "Array.from(document.querySelectorAll('input[type=checkbox]')).map(c => c.checked)"
+    states = client.evaluate("main", js)[:result]
+    assert states.all?, "expected both checkboxes checked, got: #{states.inspect}"
+  end
+
+  step "capture screenshot" do
+    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
+    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_checkboxes.png")
+  end
+end

data/examples/the_internet/dropdown.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "the_internet/dropdown" do
+  desc "Dropdown: select each option via JS, assert selected value"
+
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open dropdown page" do
+    client.open_page("main", url: "#{base_url}/dropdown")
+  end
+
+  step "assert default is unselected" do
+    value = client.evaluate("main", "document.querySelector('select#dropdown').value")[:result]
+    assert value == "", "expected empty default, got: #{value.inspect}"
+  end
+
+  step "select Option 1" do
+    client.evaluate("main", "document.querySelector('select#dropdown').value = '1'")
+    selected = client.evaluate("main", "document.querySelector('select#dropdown option:checked').text")[:result]
+    assert selected == "Option 1", "expected 'Option 1', got: #{selected.inspect}"
+  end
+
+  step "select Option 2" do
+    client.evaluate("main", "document.querySelector('select#dropdown').value = '2'")
+    selected = client.evaluate("main", "document.querySelector('select#dropdown option:checked').text")[:result]
+    assert selected == "Option 2", "expected 'Option 2', got: #{selected.inspect}"
+  end
+
+  step "capture screenshot" do
+    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
+    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_dropdown.png")
+  end
+end

data/examples/the_internet/dynamic_loading.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "the_internet/dynamic_loading" do
+  desc "Dynamic loading: click Start, wait for hidden element to appear"
+
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open dynamic loading page" do
+    client.open_page("main", url: "#{base_url}/dynamic_loading/1")
+  end
+
+  step "assert finish text is hidden before start" do
+    visible = client.evaluate("main", "document.querySelector('#finish').style.display !== 'none'")[:result]
+    assert visible == false, "expected #finish to be hidden before start"
+  end
+
+  step "click Start and wait for content" do
+    page(:main).click("#start button")
+    page(:main).wait_for("#finish h4", timeout: 10)
+  end
+
+  step "assert finish text is correct" do
+    text = client.evaluate("main", "document.querySelector('#finish h4')?.innerText?.trim()")[:result]
+    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
+    # wait for #loading to disappear before screenshotting so the rendered state is correct
+    deadline = Time.now + 5
+    sleep 0.2 until client.evaluate("main",
+                                    "document.querySelector('#loading')?.style?.display")[:result] == "none" ||
+                    Time.now > deadline
+    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
+    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_dynamic_loading.png")
+  end
+end

data/examples/the_internet/login.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "the_internet/login" do
+  desc "Form authentication: fill credentials, submit, assert secure area"
+
+  param :username, default: "tomsmith"
+  param :password, default: "SuperSecretPassword!", secret: true
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open login page" do
+    client.open_page("main", url: "#{base_url}/login")
+  end
+
+  step "fill and submit credentials" do
+    page(:main).fill("input#username", username)
+    page(:main).fill("input#password", password)
+    page(:main).click("button[type=submit]")
+  end
+
+  step "verify secure area" do
+    assert page(:main).url.include?("/secure"), "expected redirect to /secure"
+    flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
+    assert flash&.include?("You logged into a secure area!"), "expected success flash, got: #{flash.inspect}"
+    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
+    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_login.png")
+  end
+
+  step "logout and verify" do
+    page(:main).click("a[href='/logout']")
+    flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
+    assert flash&.include?("You logged out"), "expected logout flash, got: #{flash.inspect}"
+  end
+end

data/lib/browserctl/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require_relative "constants"
+
+module Browserctl
+  class Client
+    def initialize(socket_path = SOCKET_PATH)
+      @socket_path = socket_path
+    end
+
+    def call(cmd, **params)
+      communicate(JSON.generate({ cmd: cmd }.merge(params)))
+    rescue Errno::ENOENT, Errno::ECONNREFUSED
+      raise "browserd is not running — start it with: browserd"
+    end
+
+    # Convenience wrappers matching CLI command vocabulary
+
+    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 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 url(name)                  = call("url",         name: name)
+    def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)
+    def ping                       = call("ping")
+    def shutdown                   = call("shutdown")
+
+    private
+
+    def communicate(payload)
+      UNIXSocket.open(@socket_path) do |sock|
+        sock.puts(payload)
+        read_response(sock)
+      end
+    end
+
+    def read_response(sock)
+      raise "browserd response timeout after 60s" unless sock.wait_readable(60)
+
+      raw = sock.gets
+      raise "browserd closed connection" unless raw
+
+      JSON.parse(raw.chomp, symbolize_names: true)
+    end
+  end
+end