obxcura 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0870aca291d2df42d4229d960e6382150034ee7a7294a1b75829392d0e13188
-  data.tar.gz: 9daacc30f29cfd803cab0135173ca1466f75f27e077ccba09f578a3b4edcc8dc
+  metadata.gz: ecefba7c3040b8f7659fceb7de9f9b3c36903ee3b370dbc43193362047edecb5
+  data.tar.gz: 84de6d7107dc9d147ba3f24ba2dc2e5567cd507fb202919a672d1b1cf01a410a
 SHA512:
-  metadata.gz: f1cb4c51f185f9898115c38743f5b83964442be4b14381f7cdb45b1bb75da1698ef8b918c053a6f9df4c5b9fed7058614e12a6bed1baf43a44813c16396e26e7
-  data.tar.gz: 510b721af05b438f4f72791a3e78c49e97be680912f21fd1ca59064e59f72191f27cc3a6058d86d68b97445c15d7ca65091a1bd51de0bc50da2bfb51c4567efc
+  metadata.gz: 554a2a92cfc7e93dc9d3a15bd3e9bf5c04751a03e9c933c8c291811043dae050f63246c7aa27c5c319d6d536bc4f78a6ea9282bf11c8328c26674aa614817ba6
+  data.tar.gz: 897e5a2a9ce08f4c3dd4d2a9f8861022e8f333b940c89d30f5ccea9bd3a5610b8f3b601b3a3682f739a678b782886b21c413481dc293adf1e7f71dace295c449

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-29
+
+Realigns the client with Obscura 0.1.11, which lifted several of the browser
+limits this gem was built around. Every change below was verified against the
+0.1.11 binary rather than taken from the release notes — two claims in those
+notes did not hold, and are documented as still-standing constraints.
+
+### Changed
+
+- **Breaking:** `Page#xhr_post` is now `Page#post` and uses `fetch`, which
+  Obscura routes as of 0.1.11. `xhr_post` remains as a deprecated alias.
+  `timeout:` is now enforced *in the page* by racing the request against a
+  timer, so a tarpitting server fails at roughly `timeout:` instead of waiting
+  out the CDP reply timeout. It races rather than using `AbortSignal.timeout`
+  because an abort's rejection is swallowed and surfaces as `undefined`.
+- **Breaking:** `Node#type` dispatches real key events via
+  `Input.dispatchKeyEvent` instead of assigning `value` directly, so the browser
+  performs the insertion and `keydown`/`input`/`keyup` fire as they would from a
+  keyboard. `change` no longer fires per keystroke — real browsers only fire it
+  on blur, so listeners depending on the old behaviour should use `input`.
+  `Input.insertText` is still unimplemented, so insertion is per character.
+- **Breaking:** `Frame#read_string` and `Runtime::EVALUATE_CHUNK` are removed,
+  along with the `window.__obxcura_read` global. Obscura's single-message ceiling
+  went from ~500–700 KB to 64 MiB, so `Page#html` reads `outerHTML` in one round
+  trip. Verified with 8 MiB and 16 MiB strings.
+- `Node#submit` always uses `requestSubmit` and no longer falls back to
+  `submit()`. In 0.1.11 the two genuinely differ — `submit()` bypasses the
+  cancelable submit event — so the fallback would have quietly skipped both
+  constraint validation and any registered listener.
+
+### Added
+
+- `Page#network_log` — the request log has existed as internal state since
+  0.1.0, but `Network.enable` was never sent, so no events ever arrived and
+  nothing could read it. The domain is now enabled per page and the log is
+  exposed. Scope is navigation-driven requests only: script-initiated requests
+  emit no CDP network events, so `#post` traffic does not appear. This
+  contradicts the 0.1.11 note for #415, and was confirmed by measurement.
+- `Browser#clear_cookies` — listed in the 0.1.0 changelog and referenced in the
+  docs, but never actually implemented; the call site was commented out in
+  `Page#close`. Now a real method. Note cookies no longer leak between
+  connections in 0.1.11, so this only resets state within one connection.
+
+### Performance
+
+- `Client::READ_CHUNK` raised from 512 B to 64 KiB. With frames now reaching
+  64 MiB, a 512-byte read turned a single reply into tens of thousands of
+  syscalls. Measured on a 16 MiB reply: 0.188s → 0.105s. Past 64 KiB the curve
+  flattens.
+
 ## [0.2.0] - 2026-07-20
 
 ### Added

data/README.md

@@ -70,11 +70,11 @@ JS
 
 ### POSTing from inside the page
 
-Obscura routes `XMLHttpRequest` but not `fetch`, so `#xhr_post` runs the POST
-from the page's context (reusing its cookies). Values cross as arguments:
+`#post` runs the POST from the page's context with `fetch`, reusing its cookies.
+Values cross as arguments:
 
 ```ruby
-result = page.xhr_post(
+result = page.post(
   "https://example.com/api/login",
   URI.encode_www_form(user: "me", pass: "secret"),   # payload
   "application/x-www-form-urlencoded",                # content type
@@ -91,24 +91,27 @@ A transport failure — the request never reached the server (CORS, the
 private-network SSRF guard, mixed origin, a dead host) — raises
 `Obxcura::ConnectionError`. If the server accepts the connection but never
 answers, the wait ends with `Obxcura::TimeoutError`; pass `timeout:` (seconds)
-to bound it. Some anti-bot endpoints tarpit non-stealth clients — try
-`obscura serve --stealth`.
+to bound it, and the request is dropped in the page at roughly that mark. Some
+anti-bot endpoints tarpit non-stealth clients — try `obscura serve --stealth`.
+
+> Before Obscura 0.1.11 this had to use `XMLHttpRequest`, because `fetch` wasn't
+> routed. The old name `#xhr_post` still works as a deprecated alias.
 
 ## API
 
 `Obxcura.start(**opts)` is sugar for `Obxcura::Browser.new`.
 
 - **`Obxcura::Browser`** — `.new(host:, port:, timeout:)`, `#create_page(url)`,
-  `#go_to`/`#goto`, `#targets`, `#version`, `#command`, `#close`/`#quit`.
-  Readers: `#client`, `#pages`, `#host`, `#port`.
+  `#go_to`/`#goto`, `#targets`, `#version`, `#clear_cookies`, `#command`,
+  `#close`/`#quit`. Readers: `#client`, `#pages`, `#host`, `#port`.
 - **`Obxcura::Page`** — `#goto`/`#go_to`, `#evaluate`, `#evaluate_func`,
-  `#html`/`#body`, `#title`, `#current_url`, `#at_css`, `#css`, `#xhr_post`,
-  `#cookies`, `#refresh`/`#reload`, `#command`, `#close`, `#close_connection`.
-  Readers: `#frame`, `#target_id`, `#session_id`, `#client`.
-- **`Obxcura::Node`** (from `#at_css`/`#css`) — `#text`, `#[]` (attribute),
-  `#outer_html`, `#object_id`.
+  `#html`/`#body`, `#title`, `#current_url`, `#at_css`, `#css`, `#post`,
+  `#cookies`, `#network_log`, `#refresh`/`#reload`, `#command`, `#close`,
+  `#close_connection`. Readers: `#frame`, `#target_id`, `#session_id`, `#client`.
+- **`Obxcura::Node`** (from `#at_css`/`#css`) — `#text`, `#value`, `#[]`
+  (attribute), `#at_css`, `#focus`, `#type`, `#submit`, `#outer_html`.
 - **`Obxcura::Frame`** — the main frame behind a Page; carries the DOM/Runtime
-  methods Page delegates (`#evaluate`, `#at_css`, `#read_string`, …).
+  methods Page delegates (`#evaluate`, `#at_css`, `#call_on`, …).
 - **`Obxcura::Client`** — the CDP transport, if you need raw `#command`,
   `#subscribe` / `#unsubscribe`, or `#close`.
 
@@ -122,22 +125,30 @@ API, so they're worth knowing:
 
 - **No paint engine.** There is no screenshot API, and there never will be one
   here. `Page.captureScreenshot` is unusable.
-- **~500–700 KB message ceiling.** Obscura won't send a single CDP message
-  larger than that. `Page#html` works around it by snapshotting `outerHTML` into
-  a page global and pulling it back in 400 KB slices. Don't return giant values
-  from `#evaluate` directly.
 - **DOM nodes don't serialize.** A node returned by value comes back as an
   internal stub, so `#at_css` / `#css` resolve it (via `DOM.resolveNode`) to a
   live handle and read it with `Runtime.callFunctionOn`.
-- **XHR, not fetch.** Obscura routes `XMLHttpRequest` but not `fetch`, so
-  `#xhr_post` uses XHR from the page context. It also ignores
-  `XMLHttpRequest#timeout`, so the effective bound is the CDP-level `timeout:`.
-- **Persistent cookies.** `obscura serve` is long-lived and its cookie jar
-  survives `#quit` (that only drops the WebSocket). Read them with
-  `page.cookies`; closing a page clears the browser's cookie jar.
+- **In-page throws vanish.** A JS `throw` comes back as `undefined` rather than
+  an exception, so the gem returns `{ error: ... }` sentinels and raises from
+  Ruby. It's also why `#post` bounds itself by racing a timer instead of using
+  `AbortSignal.timeout` — the abort works, but its rejection doesn't survive the
+  trip, so the reason has to come back as a resolved value.
+- **The network log only sees navigation.** `#network_log` records the document
+  and its subresources. Script-initiated requests — including `#post` — emit no
+  CDP network events at all, so they never appear.
+- **No bulk text insertion.** `Input.insertText` isn't implemented, so `#type`
+  dispatches one key event per character via `Input.dispatchKeyEvent`. Real
+  `keydown`/`input`/`keyup` fire; `change` does not, matching browsers, which
+  only fire it on blur.
 - **Private networks are blocked by default.** To drive a local site, start the
   browser with `obscura serve --allow-private-network`.
 
+Two long-standing limits were lifted in Obscura 0.1.11, so if you've read older
+notes: the **~500–700 KB message ceiling is gone** (64 MiB now, so `#html`
+returns even a huge document in one round trip), and **cookies no longer leak
+between connections** — each `Browser` gets its own browser context, and
+`#clear_cookies` is now only about resetting state within one connection.
+
 The transport is built directly on `websocket-driver` rather than
 `websocket-client-simple`, which reads a byte at a time and wedges on large
 frames.

data/lib/obxcura/browser.rb

@@ -82,6 +82,20 @@ module Obxcura
       JSON.parse(Net::HTTP.get(uri))
     end
 
+    # Drop every cookie held on this connection.
+    #
+    # Since Obscura 0.1.11 each connection owns its own browser context, so cookies
+    # no longer leak between `Browser` instances and this is only about resetting
+    # state *within* one connection — between logical sessions on the same socket,
+    # say. `obscura serve` is still long-lived and {#quit} only drops the socket, so
+    # a fresh `Browser` is the other way to get a clean jar.
+    #
+    # @return [void]
+    def clear_cookies
+      command("Network.clearBrowserCookies")
+      nil
+    end
+
     # Stop tracking a page. Called by {Obxcura::Page#close}.
     #
     # @param page [Obxcura::Page] the page to forget.

data/lib/obxcura/client.rb

@@ -25,17 +25,20 @@ module Obxcura
     # @return [Integer] default seconds to wait for a command reply.
     DEFAULT_TIMEOUT = 30
 
-    # Obscura frames stay well under this; it's just a guard against a runaway
-    # allocation — a sane cap on the receive size.
+    # Matches Obscura's own 64 MiB frame ceiling, so anything the browser is
+    # willing to send, the driver is willing to assemble.
     #
     # @return [Integer] largest CDP frame (bytes) the driver will assemble.
     MAX_MESSAGE_SIZE = 64 * 1024 * 1024
 
-    # Bytes pulled per read syscall. Small is fine — the driver reassembles
-    # frames across reads; this only bounds how much we buffer at once.
+    # Bytes pulled per read syscall. This has to be large: since Obscura raised
+    # its frame ceiling to 64 MiB, multi-megabyte replies are routine, and a
+    # small value turns one reply into tens of thousands of syscalls. Measured
+    # on a 16 MiB reply: 512B → 0.188s, 64KiB → 0.105s. Past 64KiB the curve
+    # flattens, so the extra buffer buys nothing.
     #
     # @return [Integer]
-    READ_CHUNK = 512
+    READ_CHUNK = 64 * 1024
 
     # @return [String] the WebSocket URL of the browser endpoint.
     attr_reader :url

data/lib/obxcura/frame/dom.rb

@@ -19,13 +19,12 @@ module Obxcura
         evaluate("document.title")
       end
 
-      # The live, post-JS HTML. Retrieved in chunks (see {Runtime#read_string})
-      # because a full page's outerHTML routinely exceeds Obscura's message limit.
-      # Aliased as `html`.
+      # The live, post-JS HTML, in a single round trip. Obscura's frame ceiling is
+      # 64 MiB, so even a very large document comes back whole. Aliased as `html`.
       #
       # @return [String] the rendered document's outer HTML.
       def body
-        read_string("document.documentElement.outerHTML")
+        evaluate("document.documentElement.outerHTML")
       end
       alias_method :html, :body
 

data/lib/obxcura/frame/runtime.rb

@@ -10,13 +10,6 @@ module Obxcura
     # being string-interpolated into source. Node-handle resolution, cyclic-node
     # detection and a retry loop are deliberately left out.
     module Runtime
-      # Obscura won't send a single CDP message larger than ~500-700KB, so we pull
-      # large strings back in slices this size and stitch them together. Well under
-      # the ceiling, and each slice is fast over the websocket-driver transport.
-      #
-      # @return [Integer] slice size (bytes) used by {#read_string}.
-      EVALUATE_CHUNK = 400_000
-
       # Evaluate a JS expression and return its value (awaits promises).
       #
       # Extra args are passed to the page as real values, reachable in the
@@ -75,25 +68,6 @@ module Obxcura
         ))
       end
 
-      # Pull a possibly-large JS string back in {EVALUATE_CHUNK}-sized slices. The
-      # expression is snapshotted into a page global once, so it's evaluated a
-      # single time no matter how big the result is; we then slice that global.
-      #
-      # @param js_expression [String] a JS expression producing a string.
-      # @return [String] the full string, reassembled from slices.
-      def read_string(js_expression)
-        length = evaluate("(window.__obxcura_read = String(#{js_expression})).length").to_i
-        return "" if length.zero?
-
-        buffer = String.new(capacity: length)
-        offset = 0
-        while offset < length
-          buffer << evaluate("window.__obxcura_read.slice(#{offset}, #{offset + EVALUATE_CHUNK})")
-          offset += EVALUATE_CHUNK
-        end
-        buffer
-      end
-
       private
 
       # objectId of the live global object, fetched fresh so it can't go stale

data/lib/obxcura/node.rb

@@ -51,28 +51,42 @@ module Obxcura
       tap { @frame.page.command("DOM.focus", objectId: remote_object_id) }
     end
 
-    # Type text into this node. Obscura has no Input domain (Input.insertText /
-    # dispatchKeyEvent are unimplemented), so this sets `value` in page context
-    # and fires the `input`/`change` events real typing would, letting listeners
-    # react. Appends, matching keyboard behaviour when the node already has text.
+    # Type text into this node with real key events, one character at a time —
+    # Obscura implements `Input.dispatchKeyEvent`, so the browser itself performs
+    # the insertion and fires `keydown`, `input` and `keyup` the way a keyboard
+    # would. Focuses the node first, since key events go to the active element.
+    # Appends, matching keyboard behaviour when the node already has text.
+    #
+    # Note `change` does *not* fire per keystroke — real browsers only fire it on
+    # blur. The previous implementation synthesized both by assigning `value`
+    # directly; listeners that relied on that `change` need to react to `input`.
+    #
+    # `Input.insertText` is still unimplemented in Obscura 0.1.11, so there is no
+    # bulk-insert fast path: this costs two CDP round trips per character. Fine for
+    # form fields (100 chars ≈ 40ms), but it is genuinely slower than the old
+    # single-assignment approach — 500 chars ≈ 0.11s — so don't use it to stuff
+    # large text through. Assign `value` via {Frame::Runtime#call_on} for that, and
+    # accept that no key events fire.
     #
     # @param keys [Array<String>] text fragments to type (joined).
     # @return [self]
     def type(*keys)
-      tap { @frame.call_on(remote_object_id, <<~JS, [ keys.join ])
-        function(text) {
-          this.value = (this.value || "") + text;
-          this.dispatchEvent(new Event("input", { bubbles: true }));
-          this.dispatchEvent(new Event("change", { bubbles: true }));
-        }
-      JS
-      }
+      focus
+      keys.join.each_char do |char|
+        dispatch_key("keyDown", char, text: char)
+        dispatch_key("keyUp", char)
+      end
+      self
     end
 
     # Submit this node's form. Works whether the node is the `<form>` itself or a
-    # control inside one (resolved via `.form` / closest `<form>`). Prefers
-    # `requestSubmit` (runs validation and fires the submit event) and falls back
-    # to `submit` where it's unavailable.
+    # control inside one (resolved via `.form` / closest `<form>`).
+    #
+    # Always goes through `requestSubmit`, which follows the interactive path:
+    # constraint validation runs and a cancelable `submit` event fires. There is no
+    # fallback to `submit()` — as of Obscura 0.1.11 the two genuinely differ, with
+    # `submit()` bypassing the submit event entirely, so falling back would quietly
+    # skip both validation and any listener a caller registered.
     #
     # @return [self]
     # @raise [Obxcura::ProtocolError] if the node isn't a form or inside one.
@@ -81,7 +95,7 @@ module Obxcura
         function() {
           const form = this.tagName === "FORM" ? this : (this.form || this.closest("form"));
           if (!form) return { error: "node is not a form and has no ancestor form" };
-          form.requestSubmit ? form.requestSubmit() : form.submit();
+          form.requestSubmit();
         }
       JS
       raise ProtocolError, result["error"] if result.is_a?(Hash) && result["error"]
@@ -93,5 +107,15 @@ module Obxcura
     def outer_html
       @frame.call_on(remote_object_id, "function() { return this.outerHTML; }")
     end
+
+    private
+
+    # `code` is deliberately left off: it describes a physical key, which we can't
+    # infer from a character, and Obscura keys insertion off `text` anyway.
+    def dispatch_key(type, char, text: nil)
+      params = { type: type, key: char }
+      params[:text] = text if text
+      @frame.page.command("Input.dispatchKeyEvent", params)
+    end
   end
 end

data/lib/obxcura/page.rb

@@ -23,6 +23,12 @@ module Obxcura
   class Page
     extend Forwardable
 
+    # Seconds of slack given to the CDP reply beyond a {#post} timeout, so the
+    # in-page abort is what surfaces rather than the transport giving up first.
+    #
+    # @return [Integer]
+    TIMEOUT_HEADROOM = 5
+
     # @return [String] the CDP target id backing this page.
     # @return [String] the CDP session id attached to the target.
     # @return [Obxcura::Client] the shared CDP transport.
@@ -47,6 +53,21 @@ module Obxcura
       @network_mutex = Mutex.new
 
       @client.subscribe(@session_id) { |method, params| dispatch_event(method, params) }
+      command("Network.enable")
+    end
+
+    # Requests this page issued, oldest first, as
+    # `{ url:, request_id:, finished: }`.
+    #
+    # Scope is deliberately narrow: Obscura emits Network events for requests the
+    # *navigation* drives (the document and its subresources), but not for ones
+    # started from script. A {#post} — or any in-page `fetch`/`XMLHttpRequest` —
+    # therefore never shows up here. Verified against Obscura 0.1.11: enabling the
+    # Network domain and issuing a scripted POST produces no events at all.
+    #
+    # @return [Array<Hash>] a snapshot of the log, safe to iterate.
+    def network_log
+      @network_mutex.synchronize { @network_log.map(&:dup) }
     end
 
     # Navigate to `url` and block until the page's load event fires. Aliased as
@@ -105,50 +126,70 @@ module Obxcura
       @client.command(method, params, session_id: @session_id)
     end
 
-    # POST via XMLHttpRequest from the page context. Obscura routes XHR but not
-    # fetch, so this is the reliable POST path. All values cross as arguments,
-    # never interpolated into the JS. Returns { status, ok, body } on any HTTP
-    # reply (including 4xx/5xx). A transport failure — the request never reached
-    # the server (blocked by CORS / private-network SSRF guard, mixed origin, or
-    # a dead host) — raises ConnectionError instead of silently returning nil.
+    # POST from the page context via `fetch`. All values cross as arguments, never
+    # interpolated into the JS. Returns { status, ok, body } on any HTTP reply
+    # (including 4xx/5xx). A transport failure — the request never reached the
+    # server (blocked by CORS / private-network SSRF guard, mixed origin, or a
+    # dead host) — raises ConnectionError instead of silently returning nil.
     #
-    # `timeout` (seconds) bounds how long we wait for the reply. If the server
-    # accepts the connection but never answers the XHR (some anti-bot endpoints
-    # tarpit non-stealth clients), the wait ends with a TimeoutError that points
-    # at the likely cause. Note: Obscura ignores XMLHttpRequest#timeout, so the
-    # effective bound is this CDP-level one.
+    # `timeout` (seconds) is enforced in the page by racing the fetch against a
+    # timer, so a server that accepts the connection and never answers (some
+    # anti-bot endpoints tarpit non-stealth clients) fails in roughly `timeout`
+    # seconds instead of {Client::DEFAULT_TIMEOUT}. The CDP reply gets a little
+    # headroom past that so the in-page result is what we observe.
+    #
+    # The race is deliberate, and not the obvious `AbortSignal.timeout`. Obscura
+    # does accept an abort signal, but when the abort actually fires, the fetch
+    # rejection is swallowed and the call returns `undefined` — the same
+    # in-page-throws-vanish behaviour that makes {Frame::Runtime} use `{ error: }`
+    # sentinels. A rejection can't carry the reason across, so a resolved value
+    # has to. We still abort the underlying request once the timer wins, purely so
+    # it stops occupying the connection.
+    #
+    # Requests made here do not appear in {#network_log}; see that method.
     #
     # @param url [String] the URL to POST to.
     # @param payload [String] the raw request body.
     # @param content_type [String] the Content-Type header value.
     # @param headers [Hash{String=>String}] extra request headers.
-    # @param timeout [Integer, nil] seconds to wait for the reply.
+    # @param timeout [Integer, nil] seconds to allow before giving up.
     # @return [Hash] `{ "status" => Integer, "ok" => Boolean, "body" => String }`.
     # @raise [Obxcura::ConnectionError] if the request never reached the server.
     # @raise [Obxcura::TimeoutError] if the server accepts but never answers.
-    def xhr_post(url, payload, content_type, headers, timeout: nil)
-      result = evaluate_func(<<~JS, url, payload, content_type, headers, timeout:)
-        function(url, payload, contentType, headers) {
-          return new Promise((resolve) => {
-            const x = new XMLHttpRequest();
-            x.onreadystatechange = () => {
-              if (x.readyState === 4) {
-                resolve({ status: x.status, ok: x.status >= 200 && x.status < 300, body: x.responseText });
-              }
-            };
-            x.onerror = () => resolve({ error: "network error or request blocked (CORS / private network / mixed origin)" });
-            try {
-              x.open("POST", url, true);
-              x.setRequestHeader("Content-Type", contentType);
-              Object.keys(headers).forEach((k) => x.setRequestHeader(k, headers[k]));
-              x.send(payload);
-            } catch (e) {
-              resolve({ error: String(e) });
-            }
-          });
+    def post(url, payload, content_type, headers, timeout: nil)
+      timeout_ms = timeout && (timeout * 1000).to_i
+      result = evaluate_func(<<~JS, url, payload, content_type, headers, timeout_ms, timeout: timeout && timeout + TIMEOUT_HEADROOM)
+        function(url, payload, contentType, headers, timeoutMs) {
+          const controller = timeoutMs ? new AbortController() : null;
+          const init = {
+            method: "POST",
+            headers: Object.assign({ "Content-Type": contentType }, headers),
+            body: payload
+          };
+          if (controller) init.signal = controller.signal;
+
+          let timer = null;
+          const request = fetch(url, init)
+            .then((r) => r.text().then((body) => ({ status: r.status, ok: r.ok, body: body })))
+            .catch((e) => ({ error: String(e) }))
+            .then((outcome) => { if (timer) clearTimeout(timer); return outcome; });
+
+          if (!timeoutMs) return request;
+
+          return Promise.race([
+            request,
+            new Promise((resolve) => {
+              timer = setTimeout(() => {
+                if (controller) controller.abort();
+                resolve({ timeout: true });
+              }, timeoutMs);
+            })
+          ]);
         }
       JS
 
+      raise TimeoutError, timeout_message(url) if result.is_a?(Hash) && result["timeout"]
+
       if result.nil? || result["error"]
         reason = result&.dig("error") || "no response (request blocked or never settled)"
         raise ConnectionError, "POST #{url} failed: #{reason}"
@@ -156,14 +197,19 @@ module Obxcura
 
       result
     rescue TimeoutError
-      raise TimeoutError,
-        "POST #{url} did not complete in time. The server accepted the connection " \
-        "but never answered the XHR — likely anti-bot tarpitting. Try submitting the " \
-        "real form with #type/#submit, run `obscura serve --stealth`, or pass a larger timeout:."
+      raise TimeoutError, timeout_message(url)
     end
+    # @deprecated Renamed to {#post} once Obscura started routing `fetch`.
+    alias_method :xhr_post, :post
 
     private
 
+    def timeout_message(url)
+      "POST #{url} did not complete in time. The server accepted the connection " \
+        "but never answered — likely anti-bot tarpitting. Try submitting the real " \
+        "form with #type/#submit, run `obscura serve --stealth`, or pass a larger timeout:."
+    end
+
     def dispatch_event(method, params)
       case method
       when "Page.loadEventFired"

data/lib/obxcura/version.rb

@@ -4,5 +4,5 @@ module Obxcura
   # The gem's semantic version string.
   #
   # @return [String]
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: obxcura
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - memoxmrdl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: websocket-driver