browserscale-ts 1.7.0 → 1.8.0

package/README.md

@@ -4,7 +4,7 @@
 
 **The official TypeScript SDK for [browserscale](https://browserscale.cloud) — real Chromium browsers in the cloud, driven over gRPC.**
 
-Rent an isolated browser session in seconds, automate it with human-like input, intercept network traffic, solve captchas, and watch a live video stream of everything your script does. Runs in Node.js and the browser.
+Browser automation that doesn't guess. Waits, clicks and frames are handled inside the browser engine instead of being approximated from outside — rent an isolated session in under 250 ms, drive it with input that arrives like hardware, see every request it makes, and watch it live. Runs in Node.js and the browser.
 
 [![npm](https://img.shields.io/npm/v/browserscale-ts?logo=npm)](https://www.npmjs.com/package/browserscale-ts)
 ![Node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)
@@ -19,82 +19,139 @@ Rent an isolated browser session in seconds, automate it with human-like input,
 
 ## Features
 
-- **Real browser sessions as a service** — full Chromium in the cloud with
-  pages, frames, cookies, storage and network state. No local binary.
-- **Parallel isolated contexts** — each task gets its own session, fingerprint
-  and lifecycle; large queues never share browser state. Sessions are browser
-  contexts, not VMs or processes, so they spin up in under 250 ms and fan out to
-  thousands in parallel.
-- **Fingerprint & proxy handling** — pinnable server-side fingerprints,
-  native Chrome control without CDP/Playwright/Puppeteer leaks, bring your own
-  proxy or let browserscale allocate one.
-- **Native engine-level control** — automation runs natively inside Chromium
-  itself, not from outside over the DevTools protocol. Nothing is injected, no
-  `Runtime.enable`, no DevTools handshake — page JS can't observe it. Waits run
-  fully async with no polling loop, and built-in steady-time checks only report
-  an element once it's stable in the DOM.
+### Acting on the page
+
+- **Clicks that check before they press** — the element is scrolled genuinely
+  into view (through nested scroll containers and up the frame chain), held
+  until it stops moving, approached on a human pointer path, and the exact pixel
+  is verified to belong to it — across process boundaries — before the button
+  goes down. Covered? The click re-aims at the visible part or steps out of a
+  hover overlay's way. Still blocked? It throws a `ClickError` naming the
+  element in the way.
+- **Input the way hardware sends it** — pointer and key events take the path a
+  real mouse and keyboard take, with none of the markers of remote-controlled
+  input. Typing follows the session region's keyboard layout with per-character
+  timing that varies like a hand.
+- **Failures you can act on** — every command answers with success or a stable
+  error code (`not_found`, `occluded_after_evade`, `timeout`, …) and throws a
+  typed error carrying the detail, so code and models repair a failure instead
+  of blindly retrying.
+
+### Waiting & reacting
+
+- **Waits the page reports, not a poll** — each document tells the wait the
+  moment a condition holds, usually within a frame; an idle wait does no work,
+  and more conditions or more frames cost a registration, not another loop. By
+  default a match means visible and holding still, not merely in the DOM.
+- **Timeouts that explain themselves** — a `WaitError` says per condition how
+  far it got: `not_found`, `found_hidden`, `found_occluded` (with the blocker)
+  or `pending_steady`.
+- **Reactions** — `addReaction` arms a one-shot handler in the browser for the
+  cookie banner or popup that may or may not show up. It fires between your
+  calls while the pointer is idle, across every frame and navigation, and
+  retires itself — so a click blocked by a modal lands because the reaction
+  cleared the modal mid-retry.
+
+### Frames
+
 - **One flat frame tree** — main document, same-origin iframes and cross-origin
-  OOPIFs are all just a `frameId` in one tree, no flattened sessions or
-  per-frame execution-context juggling. `wait`/`click` act across all frames or
-  a single iframe, and `wait` returns the `frameId` that matched.
-- **Human-like interaction** — mouse paths use browserscale's own movement algorithm
-  instead of instant synthetic jumps.
-- **WebRTC live video stream** — watch and control the rented browser live
-  from the browserscale web interface; mouse and keyboard go back over data channels.
-- **Captcha support, no third-party solvers** — passive anti-bot checks are
-  handled automatically; interactive challenges are solved with `solveCaptcha`
-  by browserscale's own AI solver, which learns the known challenge types — puzzle,
-  OCR, slide, hold and more — on its own and keeps improving as they evolve.
-  No token is ever synthesized or fetched from an external API: the challenge
-  is completed in the valid live browser and the provider's own JavaScript
-  issues the token itself — which is why even new or unknown protections
-  pass.
-- **Real hardware, real GPUs** — sessions run hardware-accelerated on real
-  consumer GPUs, not on VM cores with a WebGL faking layer. Canvas and WebGL
-  readbacks (`toDataURL`, `getImageData`) return genuinely rendered pixels —
-  no spoofing layer or fingerprint hash database for new bot protections to
-  unmask.
-- **Network control at the source** — interception sits in the browser's
-  network stack itself, so every request from every frame (including
-  cross-origin OOPIFs) passes through it; no handler races, nothing slips
-  through. Wait for, block, mock or modify requests and responses without
-  leaving the SDK; mark repeated assets as static with `setStaticPaths` to
-  serve them from a server-side cache and cut proxy bandwidth on repeat runs.
-- **Streaming network capture** — `captureNetwork` reports every request the
-  session completes as it happens, and "every request" is literal: capture sits
-  in the browser process rather than in a page, so cross-process iframes,
-  workers and service workers are included, the headers are the ones actually
-  put on the wire, and each hop of a redirect chain arrives as its own exchange.
-  Requests are never paused, so the page loads at full speed.
-- **Live DOM mirror** — `mirrorDom` holds the page as one incrementally updated
-  tree: the browser sends the top once and from then on only what changed in the
-  part you expanded, so a page churning inside a collapsed subtree costs one
-  number per batch instead of a re-serialized document. An `<iframe>` is an
-  ordinary element whose one child is the document it hosts, however deeply
-  nested or cross-origin, and `getDomRevision` is the O(1) change detector to
-  poll when you are not consuming events.
-- **Agent-friendly observation** — `getObservation` returns one line per visible
-  element across every frame, under headers carrying the URL, title and scroll
-  offset, with live form state (typed values, checkbox state, `<select>`
-  options) and a node handle to act on. A model reasons over what matters
-  instead of raw HTML, and doesn't need a JS round-trip to ask where it is.
-- **Scripts that run inside the browser** — `runScript` sends JavaScript to the
-  session and runs it in the browser process itself, with a `browser` object
-  giving it the same operations this SDK exposes — but as local calls rather than
-  network round trips, so a loop that polls or walks a list costs microseconds
-  per step instead of tens of milliseconds. The log streams back as the script
-  produces it. `startScript` leaves a script running without the caller, which is
-  how work outlives the process that started it, and `followScript` attaches to
-  one already under way.
-- **Sessions you can find again** — `listBrowsers` reports what an API key is
-  paying for: ids, proxy, egress address and remaining rental. A session
-  therefore outlives the process that rented it — recover it after a restart, or
-  from another machine entirely, and hand the `grpcUrl` it reports straight to
-  `connectSession`.
-- **Flow-optimized TypeScript** — fully typed promise-based API, `wait` races
-  multiple outcomes, JS locators target elements by page logic when CSS is
-  not enough. Runs in Node.js (native gRPC) and the browser (WebSocket via
-  `browserscale-ts/browser`).
+  OOPIFs are all just a `frameId`: no per-frame sessions, no isolated worlds,
+  no depth limit. A frame created mid-wait is covered the moment it exists, and
+  a match returns the frame plus a node handle the next action routes on its own.
+
+### Scripts beside the browser (BrowserVM, early access)
+
+- **`runScript`** runs JavaScript in its own isolate next to the page, reaching
+  the document through the engine: a cross-origin `<iframe>` is plain
+  `contentDocument`, values are live objects, an element goes straight into
+  `browser.click`, and the page sees nothing injected. A refusal throws the
+  same error classes as this SDK. Steps cost
+  microseconds instead of round trips, so loops are affordable. `startScript`
+  leaves a script running without the caller; `followScript` attaches to one
+  already under way. [More on BrowserVM](https://browserscale.cloud/browservm).
+  Access is opened per account while in early access: ask
+  [support](mailto:support@browserscale.cloud) or on [Discord](https://discord.gg/SfE9C9K28D).
+
+### Stealth on real hardware
+
+- **Control lives below the page** — commands are carried out by the browser
+  itself: nothing injected, no `Runtime.enable`, no DevTools handshake, nothing
+  for page JavaScript to observe.
+- **Real consumer GPUs, our own hardware** — Canvas, WebGL, audio and codec
+  readbacks are genuinely rendered; there is no spoofing layer or hash database
+  for deeper checks to unmask.
+- **A shipped Chrome, not a build of one** — sessions carry the state and wire
+  behavior of a consumer browser, consistent with the region they exit from and
+  reproducible run over run.
+
+### Network
+
+- **Armed at the root, before anything loads** — interception sits in the
+  browser's network stack, so every frame, cross-process iframe, worker and
+  service worker passes through it. No attach race, nothing slips.
+- **Capture that never pauses the page** — `captureNetwork` streams every
+  finished request with the headers and cookies actually put on the wire, each
+  redirect hop as its own exchange, bodies copied off to the side.
+- **Catch one call and change it** — wait for a request or response, block,
+  mock, rewrite headers or bodies, or answer a whole navigation yourself with
+  `loadHTML`.
+- **Pay for static assets once** — `setStaticPaths` serves heavy JS, CSS and
+  images from a server-side cache reached outside the proxy, so repeat runs pay
+  neither the download nor the proxy bandwidth.
+
+### Identity & state
+
+- **A login as one portable object** — `getAuthSession` / `setAuthSession`
+  export a signed-in persona, device-bound sessions (DBSC) included, and bring
+  it up signed in inside a fresh context.
+- **Cookies and storage as data** — the whole jar, partitioned cookies
+  included, and local storage per origin, read and written with no page open.
+- **A machine you can come back as** — a country sets language, locale,
+  timezone and keyboard together; cores, memory and renderer stay consistent in
+  every frame and worker. Pin the fingerprint and the next run is the same
+  computer returning. Bring your own proxy or let browserscale allocate one.
+
+### Seeing the page
+
+- **Agent-friendly observation** — `getObservation` returns one line per
+  element across every frame and closed shadow root, with role, live value,
+  label and flags, under a token budget — prompt-sized instead of a megabyte of
+  HTML, in one round trip.
+- **Live DOM mirror** — `mirrorDom` keeps an incrementally updated copy of the
+  page: only what changed in the part you expanded is sent, an `<iframe>` is an
+  ordinary element holding its document, and `getDomRevision` is an O(1)
+  change check.
+- Plus `screenshot`, `readCanvas` and `inspectAtPosition`.
+
+### Sessions at scale
+
+- **Contexts, not machines** — a session is an isolated browser context with
+  its own cookies, storage, cache, proxy and persona, ready in under 250 ms;
+  thousands run side by side without sharing state.
+- **Sessions you can find again** — the browser lives server-side, so a session
+  outlives the process that rented it. `listBrowsers` shows what a key holds,
+  and the `grpcUrl` it reports goes straight into `connectSession` from any
+  machine.
+- **Operated for you** — heavy sessions can't starve their neighbours, capacity
+  is warm before you rent (and a full host fails fast instead of hanging), and
+  sessions are rotated onto fresh processes without losing capacity.
+- **Live stream and takeover** — a WebRTC stream encoded on the GPU that paints
+  the page; take over with mouse, keyboard and clipboard from the dashboard or
+  the CLI.
+- **Captchas, no third-party solvers** — `solveCaptcha` completes interactive
+  challenges in the live session with browserscale's own solver; the provider's
+  own JavaScript issues the token, nothing is synthesized or bought from an
+  external API.
+
+### Built for agents
+
+- **MCP server** — `https://mcp.browserscale.cloud/mcp` exposes the same verbs
+  as this SDK to Cursor, Claude, Codex or any MCP client; the key stays in an
+  `Authorization` header, never in the model's context.
+- **Flow-optimized TypeScript** — fully typed and promise-based, `wait` races
+  several outcomes, `js(...)` locators target by page logic when CSS is not
+  enough. Native gRPC in Node.js, WebSocket in the browser via
+  `browserscale-ts/browser`.
 
 ## Install
 
@@ -152,7 +209,7 @@ reports the element that occluded the click.
 | `browser.click(target, opts?)` | Human-like click; throws a rich `ClickError` on failure. |
 | `browser.fill(target, text, opts?)` | Per-key typing that fires real input events; `insertText` for bulk commit. |
 | `browser.evaluate(expr)` | Run JS in the page/frame and get a typed value back. |
-| `browser.runScript(source)` | Run JavaScript in the browser process, where every operation is a local call; `startScript` leaves it running, `followScript` watches one already going. |
+| `browser.runScript(source)` | Run JavaScript beside the browser, where cross-origin frames are property access and every step is local; `startScript` leaves it running, `followScript` watches one already going. |
 | `browser.getObservation(opts?)` | Compact, node-handle-tagged view of the visible page across frames; `opts` tunes budgets and format. |
 | `browser.captureNetwork(opts, onExchange)` | Stream every request the session completes, optionally with response bodies. |
 | `browser.mirrorDom(opts, onChange, onResync?)` | Live, incrementally updated copy of the page's DOM across every frame. |
@@ -194,8 +251,9 @@ import { rentBrowser, css } from "browserscale-ts/browser";
 | --- | --- |
 | **browserscale-ts** (you are here) | The TypeScript SDK (Node.js + browser). |
 | [**browserscale-go**](https://github.com/browserscale/browserscale-go) | The Go SDK. |
-| [**browserscale-cli**](https://github.com/browserscale/browserscale-cli) | `browserscale init` — scaffold a runnable automation module (Go). |
+| [**browserscale**](https://github.com/browserscale/browserscale) | The CLI: `browserscale init` scaffolds a runnable automation module (Go), `dev` builds and streams it, `list`/`rent`/`view`/`stop` manage your cloud browsers. |
 | [**browserscale-kit**](https://github.com/browserscale/browserscale-kit) | Go toolkit around the browser: config, store, queues, proxies, logging, mail. |
+| [**MCP server**](https://mcp.browserscale.cloud/mcp) | The browser as tools for any MCP client, one-to-one with the SDK. |
 
 ## License
 

package/dist/browser.js

@@ -6,7 +6,7 @@ export { WebSocketTransport } from "./ws-transport.js";
 export { BrowserConfig } from "./config.js";
 // Locator + constructors + AllFrames sentinel
 export { Locator, css, js, node, at, AllFrames } from "./locator.js";
-// Defaults the SDK applies before sending a request
+// Server-side defaults, re-exported for reference only (all deprecated)
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.js";
 // Errors — base class plus the typed semantic-failure subclasses
 export { BrowserScaleError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.js";