browserbeam 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 968540abd1c037b539260f27cf439d8f49d05a25f16e398cd56f56dc6d2c4591
-  data.tar.gz: fb7920bc04046dd96d62277826d2e3b4a83fce58d96961b65643686326c510d3
+  metadata.gz: 6b0481857f0872498c855f5c1cc7611f468f348e406299601fde653abb148487
+  data.tar.gz: 989f1e433800e1d2132cadb9bb83e8497884939da70deffe0e5148c21b74c647
 SHA512:
-  metadata.gz: bfe0019f622ff4273922faa8bc386264e013c33706f4ae3fe4921c68e04a42e9b7340b61874801df22d14efbc98529de2b5ef6937469e857f78377461a8a8f66
-  data.tar.gz: f4708420e29384d4a70d4ec10fe21d1d0b43a9cd83a9973c35d90991337e4175e1cd693da190cf0271d2e65b132958c1425ef1bd0b811171c18f12fd82aeee7e
+  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 |
@@ -87,6 +87,37 @@ session = client.sessions.create(
 | `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

@@ -27,10 +27,12 @@ module Browserbeam
       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 }])

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.2.0"
+  VERSION = "0.3.0"
 end

metadata

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