browserscale-ts 1.5.0 → 1.7.1

package/README.md

@@ -60,11 +60,40 @@ Rent an isolated browser session in seconds, automate it with human-like input,
   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 beside the browser** — `runScript` sends JavaScript to the
+  session, where it runs in an isolate of its own and reaches the document
+  through the engine: a cross-origin `<iframe>` is read as plain
+  `contentDocument` with no frame ids anywhere, values come back as live objects
+  you can assign to rather than snapshots, an element can be handed straight to
+  `browser.click`, and the page sees nothing injected. Steps cost microseconds
+  rather than network round trips, so loops are affordable. 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. A guide for it is still to
+  come.
+- **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
@@ -120,12 +149,16 @@ reports the element that occluded the click.
 | --- | --- |
 | `rentBrowser(cfg)` | Rent a fresh session (`new BrowserConfig(key, secs, host, port, user, pass)`). |
 | `connectSession(grpcUrl, apiKey, sessionId)` | Attach to an existing session by id (from a prior rent). |
+| `listBrowsers(apiKey)` | The sessions a key currently holds, each with the `grpcUrl` to hand to `connectSession`. |
 | `browser.navigate(url, opts?)` | Load a URL. |
 | `browser.wait(condition, opts?)` | Wait for a locator condition; returns the matched `frameId`. |
 | `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 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. |
 | `browser.solveCaptcha(opts?)` | Solve an interactive challenge in the live browser. |
 | `browser.stopBrowser()` | Release the rental. |
 

package/dist/browser.d.ts

@@ -5,9 +5,12 @@ export { BrowserConfig } from "./config.ts";
 export { Locator, css, js, node, at, AllFrames } from "./locator.ts";
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.ts";
 export { BrowserScaleError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.ts";
-export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, } from "./types.ts";
+export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, NetworkResourceType, NetworkServedFrom, NetworkBodies, NetworkCaptureOptions, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, BrowserInfo, } from "./types.ts";
 export type { Button, ClickAction, ClickOpts, FillOpts, SelectOpts, WaitOpts, WaitUntil, NavigateOpts, LoadHTMLOpts, GetDOMOpts, GetObservationOpts, ScreenshotOpts, ReadCanvasOpts, } from "./options.ts";
 export { type RequestPattern, type HeaderModification, type HeaderModificationAction, } from "./network.ts";
+export { ScriptRun, ScriptFollow, type ScriptEvent, type ScriptEventHandler, type ScriptFinished, type ScriptLogEntry, type ScriptResult, type ScriptRunInfo, } from "./scripts.ts";
+export { NetworkCapture, type NetworkExchangeHandler } from "./network-capture.ts";
+export { DomMirror, type DomNode, type DomSnapshot, type DomMirrorOptions, type DomChangeHandler, type DomResyncHandler, type DomResyncReason, } from "./dom-mirror.ts";
 export type { CookieParam } from "./cookies.ts";
 export type { StorageItem, StorageOriginEntry } from "./storage.ts";
 export type { AuthSession, DbscSession } from "./auth-session.ts";

package/dist/browser.js

@@ -10,6 +10,11 @@ export { Locator, css, js, node, at, AllFrames } from "./locator.js";
 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";
+// Scripts (automation running inside the browser process)
+export { ScriptRun, ScriptFollow, } from "./scripts.js";
+// Network capture (traffic log)
+export { NetworkCapture } from "./network-capture.js";
+export { DomMirror, } from "./dom-mirror.js";
 // Browser-side factory functions ───────────────────────────────────────
 /**
  * Attaches a {@link CloudBrowser} to an existing session over a raw