browserctl 0.4.0 → 0.6.0

data/examples/smoke/params_file.rb

@@ -4,7 +4,7 @@
 # Smoke test for --params file loading (Task 7.5).
 #
 # Run with:
-#   browserctl run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
+#   browserctl workflow 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.
@@ -17,7 +17,7 @@ Browserctl.workflow "smoke/params_file" do
   param :base_url, default: "https://the-internet.herokuapp.com"
 
   step "open login page" do
-    client.open_page("main", url: "#{base_url}/login")
+    open_page(:main, url: "#{base_url}/login")
   end
 
   step "fill credentials from params file" do
@@ -29,6 +29,7 @@ Browserctl.workflow "smoke/params_file" do
   end
 
   step "assert login succeeded" do
+    page(:main).wait(".flash.success", timeout: 10)
     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

data/examples/smoke/store_fetch.rb

@@ -12,12 +12,12 @@ Browserctl.workflow "smoke/store_fetch" do
   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")
+    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)
+    page(:main).wait("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)
@@ -32,8 +32,8 @@ Browserctl.workflow "smoke/store_fetch" do
 
   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}"
+    assert false, "expected WorkflowError was not raised"
+  rescue Browserctl::WorkflowError => e
+    puts "  [ok] WorkflowError raised as expected: #{e.message}"
   end
 end

data/examples/test_automation_practices/checkboxes.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/checkboxes" do
+  desc "Checkboxes: toggle individual, check all, uncheck all — assert state each time"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_checkboxes.png")
+
+  step "open checkboxes page" do
+    open_page(:main, url: "#{base_url}/#/checkboxes")
+  end
+
+  step "read initial state — checkbox 2 pre-checked" do
+    js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
+    states = client.evaluate("main", js)[:result]
+    assert states == [false, true, false], "expected initial state [false, true, false], got: #{states.inspect}"
+  end
+
+  step "toggle checkbox 1 on" do
+    page(:main).click("[data-test='checkbox-checkbox1']")
+    checked = client.evaluate("main", "document.querySelector('[data-test=\"checkbox-checkbox1\"]').checked")[:result]
+    assert checked, "expected checkbox 1 to be checked after click"
+  end
+
+  step "check all and verify" do
+    page(:main).click("[data-test='check-all-button']")
+    js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
+    states = client.evaluate("main", js)[:result]
+    assert states.all?, "expected all checkboxes checked, got: #{states.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "uncheck all and verify" do
+    page(:main).click("[data-test='uncheck-all-button']")
+    js = "[1,2,3].map(i => document.querySelector(`[data-test=\"checkbox-checkbox${i}\"]`)?.checked)"
+    states = client.evaluate("main", js)[:result]
+    assert states.none?, "expected all checkboxes unchecked, got: #{states.inspect}"
+  end
+end

data/examples/test_automation_practices/dynamic_elements.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/dynamic_elements" do
+  desc "Dynamic elements: trigger reload, wait for items, toggle hidden content"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/test_automation_practices_dynamic_elements.png")
+
+  step "open dynamic elements page" do
+    open_page(:main, url: "#{base_url}/#/dynamic-elements")
+  end
+
+  step "assert no dynamic items exist before reload" do
+    absent = client.evaluate("main", "!document.querySelector('[data-test=\"dynamic-item-0\"]')")[:result]
+    assert absent, "expected no dynamic items before triggering reload"
+  end
+
+  step "click reload and wait for items" do
+    page(:main).click("[data-test='reload-button']")
+    # loading indicator appears first; wait for it to clear and items to render
+    page(:main).wait("[data-test='dynamic-item-0']", timeout: 15)
+  end
+
+  step "verify all three dynamic items are present" do
+    count = client.evaluate(
+      "main",
+      "[0,1,2].filter(i => !!document.querySelector(`[data-test=\"dynamic-item-${i}\"]`)).length"
+    )[:result]
+    assert count == 3, "expected 3 dynamic items, got: #{count}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "toggle hidden content on" do
+    page(:main).click("[data-test='toggle-hidden-button']")
+    page(:main).wait("[data-test='hidden-content']", timeout: 5)
+    visible = client.evaluate("main", "!!document.querySelector('[data-test=\"hidden-content\"]')")[:result]
+    assert visible, "expected hidden content to appear after toggle"
+  end
+end

data/examples/test_automation_practices/key_press.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/key_press" do
+  desc "Key press page: dispatch keyboard events, verify last-key display and history list update"
+
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_key_press.png")
+
+  step "open key press page" do
+    open_page(:main, url: "#{base_url}/#/key-press")
+  end
+
+  step "dispatch key events and verify last-key display" do
+    keys = %w[A B C D E]
+    keys.each do |key|
+      client.evaluate(
+        "main",
+        "document.dispatchEvent(new KeyboardEvent('keydown', { key: '#{key}', bubbles: true }))"
+      )
+      sleep 0.1
+    end
+
+    last = client.evaluate("main",
+                           "document.querySelector('[data-test=\"last-key-pressed\"]')?.innerText?.trim()")[:result]
+    assert last == keys.last, "expected last key '#{keys.last}', got: #{last.inspect}"
+    store(:keys, keys)
+  end
+
+  step "verify key history contains all dispatched keys" do
+    keys = fetch(:keys)
+    history = client.evaluate(
+      "main",
+      "Array.from(document.querySelectorAll('[data-test^=\"key-\"]')).map(el => el.innerText?.trim())"
+    )[:result]
+    # History shows most recent first; each entry typically contains the key label
+    keys.each do |key|
+      assert history.any? { |entry| entry&.include?(key) }, "expected '#{key}' in history, got: #{history.inspect}"
+    end
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/login.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/login" do
+  desc "Auth page: fill credentials, verify success message, logout"
+
+  param :username,        default: "admin"
+  param :password,        default: "admin", secret: true
+  param :base_url,        default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/test_automation_practices_login.png")
+
+  step "open auth page" do
+    open_page(:main, url: "#{base_url}/#/auth")
+  end
+
+  step "fill and submit credentials" do
+    page(:main).fill("[data-test='username-input']", username)
+    page(:main).fill("[data-test='password-input']", password)
+    page(:main).click("[data-test='login-button']")
+  end
+
+  step "verify successful login" do
+    page(:main).wait("[data-test='auth-success']", timeout: 10)
+    msg = client.evaluate("main", "document.querySelector('[data-test=\"auth-success\"]')?.innerText?.trim()")[:result]
+    assert msg&.length&.positive?, "expected a success message, got: #{msg.inspect}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+
+  step "logout and verify form reappears" do
+    page(:main).click("[data-test='logout-button']")
+    page(:main).wait("[data-test='login-button']", timeout: 5)
+    visible = client.evaluate("main", "!!document.querySelector('[data-test=\"login-button\"]')")[:result]
+    assert visible, "expected login form to reappear after logout"
+  end
+end

data/examples/test_automation_practices/login_negative.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Browserctl.workflow "test_automation_practices/login_negative" do
+  desc "Auth page: invalid credentials show an error message"
+
+  param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/test_automation_practices_login_negative.png")
+
+  step "open auth page" do
+    open_page(:main, url: "#{base_url}/#/auth")
+  end
+
+  step "submit wrong credentials" do
+    page(:main).fill("[data-test='username-input']", "wronguser")
+    page(:main).fill("[data-test='password-input']", "wrongpass")
+    page(:main).click("[data-test='login-button']")
+  end
+
+  step "verify error is shown and success is absent" do
+    page(:main).wait("[data-test='auth-error']", timeout: 10)
+    error = client.evaluate("main", "document.querySelector('[data-test=\"auth-error\"]')?.innerText?.trim()")[:result]
+    assert error&.length&.positive?, "expected an error message, got: #{error.inspect}"
+    no_success = client.evaluate("main", "!document.querySelector('[data-test=\"auth-success\"]')")[:result]
+    assert no_success, "expected no success element when credentials are invalid"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/test_automation_practices/notifications.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Individual notification items have data-test="notification-{id}".
+# The wrapper has data-test="notification-container" — excluded from counts below.
+NOTIFICATION_ITEMS_JS = <<~JS
+  document.querySelectorAll('[data-test^="notification-"]:not([data-test="notification-container"])').length
+JS
+
+Browserctl.workflow "test_automation_practices/notifications" do
+  desc "Notifications: trigger success, error, and info toasts — verify count increases on each trigger"
+
+  param :base_url, default: "https://moatazeldebsy.github.io/test-automation-practices"
+  param :screenshot_path,
+        default: File.expand_path(".browserctl/screenshots/test_automation_practices_notifications.png")
+
+  step "open notifications page and record baseline" do
+    open_page(:main, url: "#{base_url}/#/notifications")
+    page(:main).wait("[data-test='notification-container']", timeout: 5)
+    # Let any delayed on-load notifications finish appearing before we snapshot the baseline
+    sleep 1
+    store(:baseline, client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result])
+  end
+
+  step "trigger success notification and verify count increased by 1" do
+    base = fetch(:baseline)
+    page(:main).click("[data-test='add-success']")
+    page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
+    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    assert count == base + 1, "expected #{base + 1} notifications after success, got: #{count}"
+  end
+
+  step "dismiss one notification and verify count returns to baseline" do
+    base = fetch(:baseline)
+    client.evaluate("main", "document.querySelector('[data-test^=\"close-notification-\"]')?.click()")
+    deadline = Time.now + 5
+    remaining = nil
+    loop do
+      remaining = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+      break if remaining <= base || Time.now > deadline
+
+      sleep 0.2
+    end
+    assert remaining <= base, "expected count back to #{base} after dismiss, got: #{remaining}"
+    # Re-snapshot baseline in case on-load notifications auto-dismissed during this step
+    store(:baseline, remaining)
+  end
+
+  step "trigger error and info notifications and verify count increased by 2" do
+    base = fetch(:baseline)
+    page(:main).click("[data-test='add-error']")
+    page(:main).click("[data-test='add-info']")
+    page(:main).wait("[data-test^='notification-']:not([data-test='notification-container'])", timeout: 5)
+    count = client.evaluate("main", NOTIFICATION_ITEMS_JS)[:result]
+    assert count == base + 2, "expected #{base + 2} notifications (error + info), got: #{count}"
+    page(:main).screenshot(path: screenshot_path)
+  end
+end

data/examples/the_internet/add_remove_elements.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/add_remove_elements" do
   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/")
+    open_page(:main, url: "#{base_url}/add_remove_elements/")
   end
 
   step "add three elements" do

data/examples/the_internet/checkboxes.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/checkboxes" do
   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")
+    open_page(:main, url: "#{base_url}/checkboxes")
   end
 
   step "read initial state" do

data/examples/the_internet/dropdown.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/dropdown" do
   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")
+    open_page(:main, url: "#{base_url}/dropdown")
   end
 
   step "assert default is unselected" do

data/examples/the_internet/dynamic_loading.rb

@@ -7,7 +7,7 @@ Browserctl.workflow "the_internet/dynamic_loading" do
   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")
+    open_page(:main, url: "#{base_url}/dynamic_loading/1")
   end
 
   step "assert finish text is hidden before start" do
@@ -17,7 +17,7 @@ Browserctl.workflow "the_internet/dynamic_loading" do
 
   step "click Start and wait for content" do
     page(:main).click("#start button")
-    page(:main).wait_for("#finish h4", timeout: 10)
+    page(:main).wait("#finish h4", timeout: 10)
   end
 
   step "assert finish text is correct" do

data/examples/the_internet/login.rb

@@ -9,7 +9,7 @@ Browserctl.workflow "the_internet/login" do
   param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_login.png")
 
   step "open login page" do
-    client.open_page("main", url: "#{base_url}/login")
+    open_page(:main, url: "#{base_url}/login")
   end
 
   step "fill and submit credentials" do

data/lib/browserctl/client.rb

@@ -9,8 +9,8 @@ require_relative "recording"
 module Browserctl
   # Thin IPC client that wraps each browserd command as a Ruby method call.
   class Client
-    def initialize(socket_path = Browserctl.socket_path)
-      @socket_path = socket_path
+    def initialize(socket_path = nil)
+      @socket_path = socket_path || auto_discover_socket
     end
 
     def call(cmd, **params)
@@ -25,22 +25,22 @@ module Browserctl
     # @param name [String] logical page name
     # @param url [String, nil] optional URL to navigate to after opening
     # @return [Hash] `{ ok: true, name: }` or `{ error: }`
-    def open_page(name, url: nil)  = call("open_page",  name: name, url: url)
+    def page_open(name, url: nil)  = call("page_open",  name: name, url: url)
 
     # Closes a named page and removes it from the session.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def close_page(name)           = call("close_page", name: name)
+    def page_close(name)           = call("page_close", name: name)
 
     # Lists all open page names.
     # @return [Hash] `{ pages: [String] }`
-    def list_pages                 = call("list_pages")
+    def page_list                  = call("page_list")
 
     # Navigates a page to a URL. Returns `challenge: true` when Cloudflare is detected.
     # @param name [String] logical page name
     # @param url [String] destination URL
     # @return [Hash] `{ ok: true, url:, challenge: }` or `{ error: }`
-    def goto(name, url)            = call("goto", name: name, url: url)
+    def navigate(name, url)        = call("navigate", name: name, url: url)
 
     # Clicks an element identified by CSS selector or snapshot ref.
     # @param name [String] logical page name
@@ -74,39 +74,30 @@ module Browserctl
 
     # Takes a DOM snapshot. Returns `challenge: true` when Cloudflare is detected.
     # @param name [String] logical page name
-    # @param format [String] "ai" (token-efficient JSON) or "html" (raw HTML)
+    # @param format [String] "elements" (interactable elements JSON) or "html" (raw HTML)
     # @param diff [Boolean] return only elements changed since last snapshot
     # @return [Hash] `{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`
-    def snapshot(name, format: "ai", diff: false)
+    def snapshot(name, format: "elements", diff: false)
       call("snapshot", name: name, format: format, diff: diff)
     end
 
-    # Waits for a CSS selector to appear (short timeout).
+    # Waits for a CSS selector to appear within the given timeout.
     # @param name [String] logical page name
     # @param selector [String] CSS selector to wait for
-    # @param timeout [Numeric] seconds before giving up (default: 10)
-    # @return [Hash] `{ ok: true }` or `{ error: }`
-    def wait_for(name, selector, timeout: 10) = call("wait_for", name: name, selector: selector, timeout: timeout)
-
-    # Polls for a CSS selector with a longer timeout (suitable for async operations).
-    # @param name [String] logical page name
-    # @param selector [String] CSS selector to poll for
     # @param timeout [Numeric] seconds before giving up (default: 30)
     # @return [Hash] `{ ok: true, selector: }` or `{ error: }`
-    def watch(name, selector, timeout: 30)
-      call("watch", name: name, selector: selector, timeout: timeout)
-    end
+    def wait(name, selector, timeout: 30) = call("wait", name: name, selector: selector, timeout: timeout)
 
     # Returns the current URL of a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, url: }` or `{ error: }`
-    def url(name)                  = call("url",         name: name)
+    def url(name)                  = call("url",      name: name)
 
     # Evaluates a JavaScript expression and returns the result.
     # @param name [String] logical page name
     # @param expression [String] JavaScript expression
     # @return [Hash] `{ ok: true, result: }` or `{ error: }`
-    def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)
+    def evaluate(name, expression) = call("evaluate", name: name, expression: expression)
 
     # Checks if browserd is alive.
     # @return [Hash] `{ ok: true, pid: }` or raises if daemon is not running
@@ -118,23 +109,35 @@ module Browserctl
 
     # Pauses automation on a page so a human can interact directly.
     # @param name [String] logical page name
-    # @return [Hash] `{ ok: true, paused: true }` or `{ error: }`
-    def pause(name)                = call("pause",   name: name)
+    # @param message [String, nil] optional message displayed to the human
+    # @return [Hash] `{ ok: true, paused: true, message: }` or `{ error: }`
+    def pause(name, message: nil)  = call("pause",  name: name, message: message)
 
     # Resumes automation on a paused page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, paused: false }` or `{ error: }`
-    def resume(name)               = call("resume",  name: name)
+    def resume(name)               = call("resume", name: name)
 
     # Returns the Chrome DevTools URL for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, devtools_url: }` or `{ error: }`
-    def inspect_page(name)         = call("inspect", name: name)
+    def devtools(name)             = call("devtools", name: name)
+
+    # Stores a value in the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @param value [Object] value to store (must be JSON-serialisable)
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def store(key, value)          = call("store", key: key, value: value)
+
+    # Retrieves a value from the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @return [Hash] `{ ok: true, value: }` or `{ error:, code: "key_not_found" }`
+    def fetch(key)                 = call("fetch", key: key)
 
     # Returns all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, cookies: [Hash] }` or `{ error: }`
-    def cookies(name) = call("cookies", name: name)
+    def cookies(name)              = call("cookies", name: name)
 
     # Sets a cookie on a named page.
     # @param name [String] logical page name
@@ -148,12 +151,13 @@ module Browserctl
                          value: value, domain: domain, path: path)
     end
 
-    # Clears all cookies for a named page.
+    # Deletes all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true }` or `{ error: }`
-    def clear_cookies(name) = call("clear_cookies", name: name)
+    def delete_cookies(name) = call("delete_cookies", name: name)
 
     # Exports all cookies for a named page to a JSON file.
+    # File I/O is client-side; daemon provides the cookie data.
     # @param name [String] logical page name
     # @param path [String] file path to write cookies to
     # @return [Hash] `{ ok: true, path:, count: }` or `{ error: }`
@@ -177,8 +181,88 @@ module Browserctl
       call("import_cookies", name: name, cookies: cookies)
     end
 
+    # Returns the value of a localStorage or sessionStorage key.
+    # @param name [String] logical page name
+    # @param key [String] storage key
+    # @param store [String] "local" or "session" (default: "local")
+    # @return [Hash] `{ ok: true, value: }` or `{ error: }`
+    def storage_get(name, key, store: "local")
+      call("storage_get", name: name, key: key, store: store)
+    end
+
+    # Sets a localStorage or sessionStorage key.
+    # @param name [String] logical page name
+    # @param key [String] storage key
+    # @param value [String] storage value
+    # @param store [String] "local" or "session" (default: "local")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def storage_set(name, key, value, store: "local")
+      call("storage_set", name: name, key: key, value: value, store: store)
+    end
+
+    # Exports localStorage and/or sessionStorage to a JSON file.
+    # @param name [String] logical page name
+    # @param path [String] destination file path
+    # @param stores [String] "local", "session", or "all" (default: "all")
+    # @return [Hash] `{ ok: true, path:, key_count: }` or `{ error: }`
+    def storage_export(name, path, stores: "all")
+      call("storage_export", name: name, path: path, stores: stores)
+    end
+
+    # Imports storage keys from a JSON file into the page's localStorage.
+    # @param name [String] logical page name
+    # @param path [String] source file path
+    # @return [Hash] `{ ok: true, origins: N, key_count: M }` or `{ error: }`
+    def storage_import(name, path)
+      call("storage_import", name: name, path: path)
+    end
+
+    # Clears localStorage and/or sessionStorage for the page.
+    # @param name [String] logical page name
+    # @param stores [String] "local", "session", or "all" (default: "all")
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def storage_delete(name, stores: "all")
+      call("storage_delete", name: name, stores: stores)
+    end
+
+    # Saves the current browser state (cookies, localStorage, open pages) to a named session.
+    # @param session_name [String] name for the saved session
+    # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
+    def session_save(session_name)
+      call("session_save", session_name: session_name)
+    end
+
+    # Restores a previously saved session into the running daemon.
+    # @param session_name [String] name of the session to load
+    # @return [Hash] `{ ok: true, cookies: N, pages: N, local_storage_keys: N }` or `{ error: }`
+    def session_load(session_name)
+      call("session_load", session_name: session_name)
+    end
+
+    # Lists all saved sessions.
+    # @return [Hash] `{ ok: true, sessions: [Hash] }` or `{ error: }`
+    def session_list
+      call("session_list")
+    end
+
+    # Permanently deletes a named session.
+    # @param session_name [String] name of the session to delete
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def session_delete(session_name)
+      call("session_delete", session_name: session_name)
+    end
+
     private
 
+    def auto_discover_socket
+      default = Browserctl.socket_path
+      return default if File.exist?(default)
+
+      # Fall back to the first available auto-indexed daemon, or the default path
+      # (which will raise "browserd is not running" at connection time if absent).
+      Browserctl.all_daemon_sockets.first || default
+    end
+
     def communicate(payload)
       UNIXSocket.open(@socket_path) do |sock|
         sock.puts(payload)

data/lib/browserctl/commands/cookie.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Cookie
+      extend CliOutput
+
+      USAGE = "Usage: browserctl cookie <list|set|delete|export|import> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "list"   then run_list(client, args)
+        when "set"    then run_set(client, args)
+        when "delete" then run_delete(client, args)
+        when "export" then run_export(client, args)
+        when "import" then run_import(client, args)
+        else abort "unknown cookie subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_list(client, args)
+        page = args.shift or abort "usage: browserctl cookie list <page>"
+        print_result(client.cookies(page))
+      end
+
+      def self.run_set(client, args)
+        page   = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        name   = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        value  = args.shift or abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN [--path /]"
+        domain_idx = args.index("--domain")
+        domain = domain_idx ? args.delete_at(domain_idx + 1).tap { args.delete_at(domain_idx) } : nil
+        abort "usage: browserctl cookie set <page> <name> <value> --domain DOMAIN" unless domain
+        path_idx = args.index("--path")
+        path = path_idx ? args.delete_at(path_idx + 1).tap { args.delete_at(path_idx) } : "/"
+        print_result(client.set_cookie(page, name, value, domain, path: path))
+      end
+
+      def self.run_delete(client, args)
+        page = args.shift or abort "usage: browserctl cookie delete <page>"
+        print_result(client.delete_cookies(page))
+      end
+
+      def self.run_export(client, args)
+        page = args.shift or abort "usage: browserctl cookie export <page> <path>"
+        path = args.shift or abort "usage: browserctl cookie export <page> <path>"
+        print_result(client.export_cookies(page, path))
+      end
+
+      def self.run_import(client, args)
+        page = args.shift or abort "usage: browserctl cookie import <page> <path>"
+        path = args.shift or abort "usage: browserctl cookie import <page> <path>"
+        print_result(client.import_cookies(page, path))
+      end
+    end
+  end
+end