browserctl 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac5d5a587f5d9862ef7bd7839f7e7e817acd742ed0a1c6d6e33913eac1be1444
-  data.tar.gz: f28af579b05237429959a444c0369550bcc848c04644bf172b95a4927657b40c
+  metadata.gz: aa3b71160a355802bb8e1fd6667506af34dc354c97b60eb2e82e0b418c02dbe6
+  data.tar.gz: 83da78edf2d59d84be5a6fd617e5b2388928c77b005d7735f466ce4aad19699b
 SHA512:
-  metadata.gz: eca2babe456ed7a818ab908bbb9d0ec5fecb0a0474cdfe5335dbc5112667b8bf2e031a5a278dd8369b2009b284def98839ea26f712d88d94c2b89c061b5718f7
-  data.tar.gz: da2d6b4eff687f5257e178a00a96b3ec9b93256fc191b386848328874bd5070cb2631a594b039550a8e3ec6ff9f00fbbfbd088d9ee594cc1d04166c6074f0c60
+  metadata.gz: 1ff6294fbc0284a342d9d2377077a02f004aec2acfeb3c1908039b09753d203e8a641d1dd2cd8ab2fd1fc607c42af3aa86537fb47361bb6820cf9a04fa8d6159
+  data.tar.gz: d029df7a2d280172543cb52dcee92326c97464d3b8d750d2f718710d46db16402b8e1a235c83c5da229a2ae047a4ab92738c3d736f741a4964c1d324f7871c15

data/CHANGELOG.md

@@ -1,10 +1,44 @@
 # Changelog
 
+> **Do not edit this file manually.** It is generated automatically by
+> [release-please](https://github.com/googleapis/release-please) on every merge to `main`.
+> To include a change in the next release, write a
+> [Conventional Commit](https://www.conventionalcommits.org/) message (`feat:`, `fix:`, `chore:`, etc.).
+
 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.4.0](https://github.com/patrick204nqh/browserctl/compare/v0.3.1...v0.4.0) (2026-04-25)
+
+
+### Features
+
+* add Claude Code plugin support with installation instructions and plugin metadata ([b568ed2](https://github.com/patrick204nqh/browserctl/commit/b568ed29015d77bc521e4484aada1054b73362e6))
+* add PRODUCT and standardization plan documentation; update VISION, README, and command references ([5594b52](https://github.com/patrick204nqh/browserctl/commit/5594b520f65d19f6c0c022e7944f9a560044549f))
+* allow .browserctl/screenshots/ as project-scoped screenshot directory ([b6914f4](https://github.com/patrick204nqh/browserctl/commit/b6914f42ead76865b8c6e8e8c0e0f88516cb53e3))
+* browserctl v0.4 hardening (security, cookie I/O, store/fetch, params file) ([#15](https://github.com/patrick204nqh/browserctl/issues/15)) ([c702661](https://github.com/patrick204nqh/browserctl/commit/c702661196e0784179afdbd824e6064c1db047bc))
+* DX improvements, doc refresh, and hardening ([#16](https://github.com/patrick204nqh/browserctl/issues/16)) ([6e32e00](https://github.com/patrick204nqh/browserctl/commit/6e32e0038abfa28be9e92ec94f9a7642e29803c4))
+
+
+### Bug Fixes
+
+* add enabledPlugins section to settings.json for browserctl plugin activation ([924dbee](https://github.com/patrick204nqh/browserctl/commit/924dbeef9c86ea2c2486d4d93118045acc042833))
+* add marketplace.json and correct plugin metadata ([5cfc1d6](https://github.com/patrick204nqh/browserctl/commit/5cfc1d621bc162fb200150c71ad4f5b62b4bdcc7))
+* allow any path within daemon CWD for screenshots, not just .browserctl/screenshots ([817a492](https://github.com/patrick204nqh/browserctl/commit/817a49211e991493b6018b663fc198c4a0ff3742))
+* save login screenshot to ~/.browserctl/screenshots/ instead of docs/ path ([246688e](https://github.com/patrick204nqh/browserctl/commit/246688e5c586d2028b90c178994d0eb7f1e9c626))
+* update marketplace.json to set strict mode to true for browserctl plugin ([99db2ad](https://github.com/patrick204nqh/browserctl/commit/99db2ada2aae08f8bceb78658e15a267246df973))
+* use screenshot_path param in all examples; CI passes docs/screenshots/ explicitly ([64e073d](https://github.com/patrick204nqh/browserctl/commit/64e073d74979d869560d814b9a986c001b400238))
+
+## [0.3.1](https://github.com/patrick204nqh/browserctl/compare/v0.3.0...v0.3.1) (2026-04-20)
+
+
+### Bug Fixes
+
+* allow pre-registered workflows with slash names (e.g. the_internet/login) ([e755a4a](https://github.com/patrick204nqh/browserctl/commit/e755a4aa20608fb11ce425c81ed8c0a43f3b13fe))
+* remove unused client variable in runner spec ([94e1a31](https://github.com/patrick204nqh/browserctl/commit/94e1a310acc1d5ddb5e538860907040d3504f2c9))
+
 ## [0.3.0](https://github.com/patrick204nqh/browserctl/compare/v0.2.2...v0.3.0) (2026-04-20)
 
 

data/README.md

@@ -13,10 +13,10 @@ A persistent browser automation daemon and CLI, purpose-built for AI agents and
 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)
+browserd &                                               # start the daemon (headless)
 browserctl open login --url https://example.com/login
-browserctl snap login                                # AI-friendly JSON snapshot with ref IDs
-browserctl fill login --ref e1 --value me@example.com   # interact by ref
+browserctl snap login                                    # AI-friendly JSON snapshot with ref IDs
+browserctl fill login --ref e1 --value me@example.com   # interact by ref, no selectors needed
 browserctl click login --ref e2
 browserctl shutdown
 ```
@@ -35,11 +35,12 @@ Most automation tools are stateless — every script spins up a fresh browser an
 | Session persists across commands | ✓ | ✗ (per-script lifecycle) |
 | Named page handles | ✓ | ✗ |
 | AI-friendly DOM snapshot | ✓ | ✗ |
+| Human-in-the-loop pause/resume | ✓ | ✗ |
 | 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 browserctl when** you need a browser that stays alive and remembers state — for AI agents, iterative dev workflows, or tasks that mix automation with human judgment.
 
 **Use Playwright/Selenium when** you need parallel test suites, multi-browser support, or a full programmatic API.
 
@@ -47,8 +48,8 @@ Most automation tools are stateless — every script spins up a fresh browser an
 
 ## Requirements
 
-- Ruby >= 3.2
-- Chrome or Chromium installed and on `PATH`
+- Ruby >= 3.3
+- Chrome or Chromium on your `PATH`
 
 ---
 
@@ -66,223 +67,70 @@ 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
-```
+## Claude Code Plugin
 
-**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 click login "button[type=submit]"
-```
+browserctl ships as a Claude Code plugin. Install it once and Claude automatically knows how to use the daemon, ref-based interaction, HITL patterns, and workflow authoring.
 
-**5. Observe the result**
+**Install (interactive)**
 
-```bash
-browserctl snap login --diff       # only changed elements since last snap
-browserctl shot login --out /tmp/after-login.png --full
-browserctl url  login
 ```
-
-**6. Manage pages and daemon**
-
-```bash
-browserctl pages
-browserctl close login
-browserctl ping
-browserctl shutdown
+/plugin marketplace add patrick204nqh/browserctl
+/plugin install browserctl@browserctl
 ```
 
----
-
-## 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 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 |
-| `pause <page>` | Pause automation — browser stays live for manual interaction |
-| `resume <page>` | Resume automation after manual action |
-| `inspect <page>` | Open Chrome DevTools for a named page |
-| `cookies <page>` | List all cookies as JSON |
-| `set_cookie <page> <name> <value> <domain>` | Set a cookie (path defaults to `/`) |
-| `clear_cookies <page>` | Clear all cookies for a page |
-| `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
-
-| 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:
+**Install (project settings** — commit `.claude/settings.json` to share with your team)
 
 ```json
-[
-  {
-    "ref": "e1",
-    "tag": "input",
-    "text": "",
-    "selector": "form > input[name=email]",
-    "attrs": {
-      "type": "email",
-      "name": "email",
-      "placeholder": "Enter email"
+{
+  "extraKnownMarketplaces": {
+    "browserctl": {
+      "source": { "source": "github", "repo": "patrick204nqh/browserctl" }
     }
   },
-  {
-    "ref": "e2",
-    "tag": "button",
-    "text": "Sign in",
-    "selector": "form > button",
-    "attrs": {
-      "type": "submit"
-    }
+  "enabledPlugins": {
+    "browserctl@browserctl": true
   }
-]
-```
-
-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
-```
+Once installed, Claude Code loads the `browserctl` skill automatically — no `/invoke` needed.
 
 ---
 
-## 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
-```
+## Quick Start
 
 ```bash
-browserctl run smoke_login --email me@example.com --password s3cr3t
-```
+# 1. Start the daemon
+browserd &
 
-### Workflow DSL reference
+# 2. Open a named page
+browserctl open main --url https://the-internet.herokuapp.com/login
 
-| 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) |
-| `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 |
-
-### PageProxy methods
+# 3. Snapshot the page — get AI-friendly JSON with ref IDs
+browserctl snap main
 
-`goto(url)` · `fill(selector, value)` · `click(selector)` · `snapshot(**opts)` · `screenshot(**opts)` · `wait_for(selector, timeout: 10)` · `url` · `evaluate(expression)` · `pause` · `resume` · `inspect_page` · `cookies` · `set_cookie(name, value, domain, path: "/")` · `clear_cookies`
-
----
+# 4. Interact using refs
+browserctl fill  main --ref e1 --value tomsmith
+browserctl fill  main --ref e2 --value SuperSecretPassword!
+browserctl click main --ref e3
 
-## Examples
+# 5. Observe
+browserctl url  main
+browserctl snap main --diff   # only what changed
 
-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.
+# 6. Done
+browserctl shutdown
+```
 
-For a full guide on building your own workflows, see [docs/writing-workflows.md](docs/writing-workflows.md).
+→ [Full Getting Started guide](docs/getting-started.md)
 
 ---
 
 ## How it works
 
-`browserd` runs as a background process, listening on a Unix socket at `~/.browserctl/browserd.sock`. Start multiple named instances for agent isolation:
+`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.
+
+Start multiple named instances for agent isolation:
 
 ```bash
 browserd --name agent-a &
@@ -290,11 +138,22 @@ 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.
+The daemon shuts itself down after 30 minutes of inactivity.
+
+---
 
-`browserctl` sends JSON-RPC commands over the socket and prints the result. Workflows run in-process through the same client.
+## Documentation
 
-The daemon shuts itself down after 30 minutes of inactivity.
+| | |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Install, first session, first snapshot |
+| [Concepts](docs/concepts/) | Sessions, snapshots, human-in-the-loop |
+| [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
+| [Command Reference](docs/reference/commands.md) | Every command and flag |
+| [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |
+| [Product](docs/product.md) | What browserctl is and who it's for |
+| [Vision & Roadmap](docs/vision.md) | Philosophy and release roadmap |
+| [vs. agent-browser](docs/vs-agent-browser.md) | How browserctl differs from Vercel's agent-browser |
 
 ---
 

data/bin/browserctl

@@ -21,9 +21,13 @@ require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
 require "browserctl/commands/watch"
 require "browserctl/commands/record"
-require "browserctl/commands/pause_resume"
+require "browserctl/commands/pause"
+require "browserctl/commands/resume"
 require "browserctl/commands/init"
 require "browserctl/commands/inspect"
+require "browserctl/commands/export_cookies"
+require "browserctl/commands/import_cookies"
+require "browserctl/commands/status"
 
 def print_result(res)
   if res.is_a?(Hash) && res[:error]
@@ -59,8 +63,10 @@ def usage
       resume  <page>                               Resume automation after manual action
       inspect <page>                               Open Chrome DevTools for a named page
       cookies <page>                               List all cookies as JSON
-      set_cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
-      clear_cookies <page>                         Clear all cookies for a page
+      set-cookie <page> <name> <value> <domain>    Set a cookie (path defaults to /)
+      clear-cookies <page>                         Clear all cookies for a page
+      export-cookies <page> <path>                 Export cookies to a JSON file
+      import-cookies <page> <path>                 Import cookies from a JSON file
 
     Recording commands:
       record start <name>            Start recording browser commands
@@ -68,12 +74,13 @@ def usage
       record status                  Show active recording name
 
     Workflow commands:
-      run      <name|file> [--key value ...]   Run a workflow
+      run      <name|file> [--params file] [--key value ...]   Run a workflow
       workflows                                List available workflows
       describe <name>                          Describe a workflow
 
     Daemon commands:
       ping                   Check if browserd is alive
+      status                 Show daemon status, PID, and open pages
       shutdown               Stop browserd
 
     Options:
@@ -105,11 +112,23 @@ when "run"
     load File.expand_path(name)
     name = (Browserctl::REGISTRY.keys - before).first || File.basename(name, ".rb")
   end
-  params = {}
+  params_file_idx = args.index("--params")
+  file_params = {}
+  if params_file_idx
+    params_path = args.delete_at(params_file_idx + 1)
+    args.delete_at(params_file_idx)
+    begin
+      file_params = Browserctl::Runner.load_params_file(params_path)
+    rescue StandardError => e
+      abort "Error loading params file: #{e.message}"
+    end
+  end
+  cli_params = {}
   args.each_slice(2) do |flag, val|
     key = flag.sub(/\A--/, "").to_sym
-    params[key] = val
+    cli_params[key] = val
   end
+  params = file_params.merge(cli_params)
   success = runner.run_workflow(name, **params)
   exit(success ? 0 : 1)
 
@@ -139,13 +158,16 @@ else
   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 "pause"    then Browserctl::Commands::PauseResume.pause(client, args)
-  when "resume"   then Browserctl::Commands::PauseResume.resume(client, args)
+  when "pause"    then Browserctl::Commands::Pause.run(client, args)
+  when "resume"   then Browserctl::Commands::Resume.run(client, args)
   when "inspect"       then Browserctl::Commands::Inspect.run(client, args)
-  when "cookies"       then print_result(client.cookies(args[0]))
-  when "set_cookie"    then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
-  when "clear_cookies" then print_result(client.clear_cookies(args[0]))
+  when "cookies"         then print_result(client.cookies(args[0]))
+  when "set-cookie"      then print_result(client.set_cookie(args[0], args[1], args[2], args[3]))
+  when "clear-cookies"   then print_result(client.clear_cookies(args[0]))
+  when "export-cookies" then Browserctl::Commands::ExportCookies.run(client, args)
+  when "import-cookies" then Browserctl::Commands::ImportCookies.run(client, args)
   when "ping"     then print_result(client.ping)
+  when "status"   then Browserctl::Commands::Status.run(client)
   when "shutdown" then print_result(client.shutdown)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."

data/bin/browserd

@@ -16,7 +16,13 @@ opts = Optimist.options do
   opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
 end
 
-Browserctl.logger = Browserctl.build_logger(opts[:log_level])
+if opts[:name] && opts[:name] !~ /\A[a-zA-Z0-9_-]{1,64}\z/
+  abort "Invalid daemon name #{opts[:name].inspect} — use only letters, digits, _ or -"
+end
+
+log_path = Browserctl.log_path(opts[:name])
+warn "browserd starting — log: #{log_path}"
+Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
 Browserctl::Server.new(
   headless: !opts[:headed],
   socket_path: Browserctl.socket_path(opts[:name]),

data/examples/smoke/params_file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#
+# Smoke test for --params file loading (Task 7.5).
+#
+# Run with:
+#   browserctl run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
+#
+# The workflow logs in using credentials from the params file and asserts
+# the secure area is reached — proving the params were loaded and available.
+
+Browserctl.workflow "smoke/params_file" do
+  desc "Smoke: load credentials from a --params file and use them in a workflow"
+
+  param :username, required: true
+  param :password, required: true, 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 credentials from params file" do
+    puts "  [params] username = #{username.inspect}"
+    puts "  [params] password = (#{password.length} chars, secret)"
+    page(:main).fill("input#username", username)
+    page(:main).fill("input#password", password)
+    page(:main).click("button[type=submit]")
+  end
+
+  step "assert login succeeded" do
+    assert page(:main).url.include?("/secure"), "expected redirect to /secure — params may not have loaded"
+    puts "  [ok] reached secure area — params file loaded correctly"
+  end
+end

data/examples/smoke/store_fetch.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#
+# Smoke test for WorkflowContext#store / #fetch (Task 7.3).
+#
+# Uses the-internet's dynamic loading example: click Start, wait for "Hello World!",
+# capture the text in step 1, assert it is still accessible in step 2 via fetch.
+
+Browserctl.workflow "smoke/store_fetch" do
+  desc "Smoke: store a value in one step and retrieve it in a later step"
+
+  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 "click start and capture loaded text" do
+    page(:main).click("div#start button")
+    page(:main).wait_for("div#finish", timeout: 10)
+    text = client.evaluate("main", "document.querySelector('div#finish h4')?.innerText?.trim()")[:result]
+    assert text && !text.empty?, "expected loaded text, got: #{text.inspect}"
+    store(:loaded_text, text)
+    puts "  [store] loaded_text = #{text.inspect}"
+  end
+
+  step "fetch value from previous step and assert" do
+    text = fetch(:loaded_text)
+    puts "  [fetch] loaded_text = #{text.inspect}"
+    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
+  end
+
+  step "confirm fetch raises for unknown key" do
+    fetch(:nonexistent_key)
+    assert false, "expected KeyError was not raised"
+  rescue KeyError => e
+    puts "  [ok] KeyError raised as expected: #{e.message}"
+  end
+end

data/examples/the_internet/add_remove_elements.rb

@@ -3,7 +3,8 @@
 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"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_add_remove_elements.png")
 
   step "open add/remove elements page" do
     client.open_page("main", url: "#{base_url}/add_remove_elements/")
@@ -13,8 +14,7 @@ Browserctl.workflow "the_internet/add_remove_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")
+    page(:main).screenshot(path: screenshot_path)
   end
 
   step "remove one element" do

data/examples/the_internet/checkboxes.rb

@@ -3,7 +3,8 @@
 Browserctl.workflow "the_internet/checkboxes" do
   desc "Checkboxes: read state, toggle each, verify both checked"
 
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_checkboxes.png")
 
   step "open checkboxes page" do
     client.open_page("main", url: "#{base_url}/checkboxes")
@@ -29,7 +30,6 @@ Browserctl.workflow "the_internet/checkboxes" do
   end
 
   step "capture screenshot" do
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_checkboxes.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 end

data/examples/the_internet/dropdown.rb

@@ -3,7 +3,8 @@
 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"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dropdown.png")
 
   step "open dropdown page" do
     client.open_page("main", url: "#{base_url}/dropdown")
@@ -27,7 +28,6 @@ Browserctl.workflow "the_internet/dropdown" do
   end
 
   step "capture screenshot" do
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_dropdown.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 end

data/examples/the_internet/dynamic_loading.rb

@@ -3,7 +3,8 @@
 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"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dynamic_loading.png")
 
   step "open dynamic loading page" do
     client.open_page("main", url: "#{base_url}/dynamic_loading/1")
@@ -27,7 +28,6 @@ Browserctl.workflow "the_internet/dynamic_loading" do
     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")
+    page(:main).screenshot(path: screenshot_path)
   end
 end