browserbeam 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e5f1fad0f6f29ae8ce9616b429a9078771a1d6911a220e32b5f230c12ca02a
-  data.tar.gz: 18116e46d6cabbc54716f800964ae354a993cead2f1c44d2edf0e97bbc1f2656
+  metadata.gz: 6b0481857f0872498c855f5c1cc7611f468f348e406299601fde653abb148487
+  data.tar.gz: 989f1e433800e1d2132cadb9bb83e8497884939da70deffe0e5148c21b74c647
 SHA512:
-  metadata.gz: b8b82446fe2731ac36af5d52ee59706a43cc0e7214d404b066d472bb520cac5565a9eb04d1287858077b085e26bb0771f55cdfd3de3e63275e562859caeadd0b
-  data.tar.gz: d5f19a469e10f1eb4ff9225c24e5bb44155504a26a6d936be209f48efa4bbc0f4a1c46516b25f7c540bacdfc83f04b1ba3a72ddce54318c11e0926a522204ae2
+  metadata.gz: 0605be53e22028d51513793fb6f0542caac9a131135ea1566fff865f7a5087f3c8b168569749fefc4cb1473f46b9e0accc22020c66495d4493caae72f46815f9
+  data.tar.gz: c5d700fbcac26e7757a891729071e7cb959007e0b4f8d8b7b51a16d34a145af168db7f108b726f0e24f67ed41f67d571c33db1d1992c76320a2091656fbb1764

data/README.md

@@ -71,7 +71,7 @@ session = client.sessions.create(
 | Method | Description |
 |--------|-------------|
 | `session.goto(url)` | Navigate to a URL |
-| `session.observe` | Get page state as markdown |
+| `session.observe` | Get page state as markdown. Supports `mode: "full"` for all sections. |
 | `session.click(ref:)` | Click an element by ref, text, or label |
 | `session.fill(value, ref:)` | Fill an input field |
 | `session.type(value, label:)` | Type text character by character |
@@ -84,9 +84,40 @@ session = client.sessions.create(
 | `session.fill_form(fields, submit:)` | Fill and submit a form |
 | `session.wait(ms:)` | Wait for time, selector, or text |
 | `session.pdf` | Generate a PDF |
-| `session.execute_js(expr)` | Run JavaScript |
+| `session.execute_js(code)` | Run JavaScript |
 | `session.close` | Close the session |
 
+## Page Map & Full Mode
+
+The first `observe` call automatically includes a `page.map` — a lightweight structural outline of the page's landmark regions (header, nav, main, aside, footer) with CSS selectors and descriptive hints. Use it to discover what content is available outside the main area.
+
+```ruby
+res = session.observe
+res.page.map.each { |entry| puts "#{entry.section}: #{entry.hint}" }
+# nav: Home · Docs · Pricing
+# main: Getting started with Browserbeam...
+# aside: Related posts · Popular tags
+```
+
+To re-request the map on subsequent calls:
+
+```ruby
+session.observe(include_page_map: true)
+```
+
+When you need content from **all** page sections (sidebars, footer links, nav items), use `mode: "full"`. The response markdown is organized by region headers:
+
+```ruby
+full = session.observe(mode: "full", max_text_length: 20_000)
+puts full.page.markdown.content
+# ## [nav]
+# Home · Docs · Pricing
+# ## [main]
+# ...article content...
+# ## [aside]
+# Related posts · ...
+```
+
 ## Session Management
 
 ```ruby

data/lib/browserbeam/session.rb

@@ -19,17 +19,20 @@ module Browserbeam
       envelope
     end
 
-    def goto(url, wait_for: nil, wait_timeout: nil)
+    def goto(url, wait_for: nil, wait_until: nil, wait_timeout: nil)
       params = { url: url }
       params[:wait_for] = wait_for if wait_for
+      params[:wait_until] = wait_until if wait_until
       params[:wait_timeout] = wait_timeout if wait_timeout
       act([{ goto: params }])
     end
 
-    def observe(scope: nil, format: nil, include_links: nil, max_text_length: nil)
+    def observe(scope: nil, format: nil, mode: nil, include_page_map: nil, include_links: nil, max_text_length: nil)
       params = {}
       params[:scope] = scope if scope
       params[:format] = format if format
+      params[:mode] = mode if mode
+      params[:include_page_map] = include_page_map unless include_page_map.nil?
       params[:include_links] = include_links unless include_links.nil?
       params[:max_text_length] = max_text_length if max_text_length
       act([{ observe: params }])
@@ -43,43 +46,49 @@ module Browserbeam
       act([{ click: params }])
     end
 
-    def fill(value, ref: nil, label: nil)
+    def fill(value, ref: nil, text: nil, label: nil)
       params = { value: value }
       params[:ref] = ref if ref
+      params[:text] = text if text
       params[:label] = label if label
       act([{ fill: params }])
     end
 
-    def type(value, label: nil, ref: nil, delay: nil)
+    def type(value, ref: nil, text: nil, label: nil, delay: nil)
       params = { value: value }
-      params[:label] = label if label
       params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
       params[:delay] = delay if delay
       act([{ type: params }])
     end
 
-    def select(value, label: nil, ref: nil)
+    def select(value, ref: nil, text: nil, label: nil)
       params = { value: value }
-      params[:label] = label if label
       params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
       act([{ select: params }])
     end
 
-    def check(label: nil, ref: nil, checked: nil)
+    def check(ref: nil, text: nil, label: nil, checked: nil)
       params = {}
-      params[:label] = label if label
       params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
       params[:checked] = checked unless checked.nil?
       act([{ check: params }])
     end
 
-    def scroll(to: nil, direction: nil, amount: nil, times: nil, ref: nil)
+    def scroll(to: nil, direction: nil, amount: nil, times: nil, ref: nil, text: nil, label: nil)
       params = {}
       params[:to] = to if to
       params[:direction] = direction if direction
       params[:amount] = amount if amount
       params[:times] = times if times
       params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
       act([{ scroll: params }])
     end
 
@@ -101,11 +110,12 @@ module Browserbeam
       act([{ screenshot: params }])
     end
 
-    def wait(ms: nil, selector: nil, text: nil, timeout: nil)
+    def wait(ms: nil, selector: nil, text: nil, timeout: nil, **opts)
       params = {}
       params[:ms] = ms if ms
       params[:selector] = selector if selector
       params[:text] = text if text
+      params[:until] = opts[:until] if opts[:until]
       params[:timeout] = timeout if timeout
       act([{ wait: params }])
     end
@@ -120,20 +130,29 @@ module Browserbeam
       act([{ fill_form: params }])
     end
 
-    def upload(ref, files)
-      act([{ upload: { ref: ref, files: files } }])
+    def upload(files, ref: nil, text: nil, label: nil)
+      params = { files: files }
+      params[:ref] = ref if ref
+      params[:text] = text if text
+      params[:label] = label if label
+      act([{ upload: params }])
     end
 
-    def pdf(format: nil, landscape: nil, print_background: nil)
+    def pdf(format: nil, landscape: nil, print_background: nil, scale: nil, margin: nil)
       params = {}
       params[:format] = format if format
       params[:landscape] = landscape unless landscape.nil?
       params[:print_background] = print_background unless print_background.nil?
+      params[:scale] = scale if scale
+      params[:margin] = margin if margin
       act([{ pdf: params }])
     end
 
-    def execute_js(expression)
-      act([{ execute_js: { expression: expression } }])
+    def execute_js(code, result_key: nil, timeout: nil)
+      params = { code: code }
+      params[:result_key] = result_key if result_key
+      params[:timeout] = timeout if timeout
+      act([{ execute_js: params }])
     end
 
     def close

data/lib/browserbeam/types.rb

@@ -18,6 +18,12 @@ module Browserbeam
     end
   end
 
+  MapEntry = Struct.new(:section, :selector, :hint, keyword_init: true) do
+    def self.from_hash(data)
+      new(section: data["section"] || "", selector: data["selector"] || "", hint: data["hint"] || "")
+    end
+  end
+
   Changes = Struct.new(:content_changed, :content_delta, :elements_added, :elements_removed, keyword_init: true) do
     def self.from_hash(data)
       return nil unless data.is_a?(Hash)
@@ -37,7 +43,7 @@ module Browserbeam
     end
   end
 
-  PageState = Struct.new(:url, :title, :stable, :markdown, :interactive_elements, :forms, :changes, :scroll, keyword_init: true) do
+  PageState = Struct.new(:url, :title, :stable, :markdown, :map, :interactive_elements, :forms, :changes, :scroll, keyword_init: true) do
     def self.from_hash(data)
       return nil unless data.is_a?(Hash)
       new(
@@ -45,6 +51,7 @@ module Browserbeam
         title: data["title"] || "",
         stable: data["stable"] || false,
         markdown: MarkdownContent.from_hash(data["markdown"]),
+        map: data["map"] ? data["map"].map { |m| MapEntry.from_hash(m) } : nil,
         interactive_elements: (data["interactive_elements"] || []).map { |el| InteractiveElement.from_hash(el) },
         forms: data["forms"] || [],
         changes: Changes.from_hash(data["changes"]),

data/lib/browserbeam/version.rb

@@ -1,3 +1,3 @@
 module Browserbeam
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserbeam
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Browserbeam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday