browserscale-ts 1.4.0 → 1.7.0

package/dist/client.js

@@ -2,10 +2,13 @@ import { createClient } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Browser, 
 // request / response schemas
-SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, } from "./gen/wrc_pb.js";
+SetProxyRequestSchema, GetPagesRequestSchema, NavigateRequestSchema, LoadHTMLRequestSchema, EvaluateRequestSchema, WaitForAnyParamsSchema, WaitConditionSchema, ClickRequestSchema, FillRequestSchema, MoveToRequestSchema, ScrollToRequestSchema, DragRequestSchema, SelectOptionRequestSchema, GetDOMRequestSchema, GetDOMHashRequestSchema, GetObservationRequestSchema, ScreenshotRequestSchema, ReadCanvasRequestSchema, SetBlockListRequestSchema, SetStaticPathsRequestSchema, WaitForAnyRequestRequestSchema, WaitForAnyResponseRequestSchema, ModifyRequestRequestSchema, GetCookiesRequestSchema, SetCookiesRequestSchema, ClearCookiesRequestSchema, GetStorageRequestSchema, SetStorageRequestSchema, ClearStorageRequestSchema, GetAuthSessionRequestSchema, SetAuthSessionRequestSchema, InspectAtPositionRequestSchema, HighlightNodeRequestSchema, InsertTextRequestSchema, TypeRequestSchema, PressKeyRequestSchema, ReleaseKeyRequestSchema, GetSelectionRequestSchema, SolveCaptchaRequestSchema, GetStreamConfigRequestSchema, StartStreamRequestSchema, StopStreamRequestSchema, AddReactionRequestSchema, RemoveReactionRequestSchema, ListReactionsRequestSchema, StartNetworkCaptureRequestSchema, StopNetworkCaptureRequestSchema, StartDomMirrorRequestSchema, StopDomMirrorRequestSchema, GetDomChildrenRequestSchema, ReleaseDomSubtreeRequestSchema, RevealDomNodeRequestSchema, GetDomRevisionRequestSchema, StreamDomEventsRequestSchema, StreamNetworkExchangesRequestSchema, RunScriptRequestSchema, StartScriptRequestSchema, StopScriptsRequestSchema, ListScriptRunsRequestSchema, StreamScriptEventsRequestSchema, } from "./gen/wrc_pb.js";
 import { DefaultWaitTimeoutMs } from "./defaults.js";
 import { BrowserScaleError } from "./errors.js";
-import { cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
+import { NetworkCapture } from "./network-capture.js";
+import { ScriptFollow, ScriptRun, scriptLogEntryFromProto, } from "./scripts.js";
+import { DomMirror, } from "./dom-mirror.js";
+import { authSessionFromProto, authSessionToProto, cookieParamFromProto, cookieParamsToProto, elementFields, headerModsToProto, headersToProto, interceptedRequestFromProto, interceptedResponseFromProto, pageInfoFromProto, rectFromProto, splitRequestPatterns, storageEntriesToProto, storageEntryFromProto, unwrapClick, unwrapDrag, unwrapFill, unwrapMove, unwrapScroll, unwrapSelect, unwrapWait, } from "./internal/convert.js";
 /**
  * CloudBrowser is the SDK-side handle for an active browserscale browser session.
  *
@@ -1047,6 +1050,334 @@ export class CloudBrowser {
         return interceptedRequestFromProto(resp.request);
     }
     // ──────────────────────────────────────────────────────────────────
+    // Network capture
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Starts capturing the session's network traffic and returns a live view of
+     * it.
+     *
+     * Every request matching `opts.patterns` is reported once it completes, 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 (Cookie and
+     * Sec-* included), and each hop of a redirect chain arrives as its own
+     * exchange. Requests are never paused, so the page loads at full speed.
+     *
+     * This resolves as soon as the capture is running; onExchange then fires in
+     * the background while you drive the browser. The capture is armed only after
+     * the subscription exists, so nothing that happens after this resolves is
+     * missed. Call {@link NetworkCapture.stop} when done — it disarms the capture
+     * server-side, which an aborted transport alone does not.
+     *
+     * @param opts - which requests to capture and whether to keep bodies
+     * @param onExchange - called per exchange; see {@link NetworkExchangeHandler}
+     *   for the ordering and blocking rules
+     *
+     * @returns NetworkCapture handle for stopping the capture and inspecting how
+     *   it ended
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be started
+     *
+     * @example
+     * const capture = await browser.captureNetwork(
+     *   { patterns: ["*\/api/*"], bodies: "text" },
+     *   (ex) => console.log(ex.statusCode, ex.method, ex.url),
+     * );
+     * try {
+     *   await browser.navigate("https://example.com");
+     * } finally {
+     *   await capture.stop();
+     * }
+     */
+    async captureNetwork(opts, onExchange) {
+        const capture = await this.subscribeNetworkExchanges(onExchange);
+        try {
+            await this.startNetworkCapture(opts);
+        }
+        catch (err) {
+            // Not armed yet, so this only tears down the local subscription.
+            await capture.stop();
+            throw err;
+        }
+        capture.arm();
+        return capture;
+    }
+    /**
+     * Arms a capture without subscribing to it.
+     *
+     * Use it when the reader lives somewhere else — another tab, or a later
+     * {@link createWebSocketBrowser} against the same session. Most callers want
+     * {@link CloudBrowser.captureNetwork} instead, which arms and subscribes
+     * together. Calling this again replaces the running capture.
+     *
+     * @param opts - which requests to capture and whether to keep bodies
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be started
+     */
+    async startNetworkCapture(opts) {
+        await this.client.startNetworkCapture(create(StartNetworkCaptureRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            patterns: opts.patterns ?? [],
+            bodies: opts.bodies ?? "none",
+            bodyPatterns: opts.bodyPatterns ?? [],
+        }));
+    }
+    /**
+     * Disarms the session's capture.
+     *
+     * @returns whether a capture was running
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be stopped
+     */
+    async stopNetworkCapture() {
+        const resp = await this.client.stopNetworkCapture(create(StopNetworkCaptureRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.stopped;
+    }
+    /**
+     * Subscribes to the session's capture without arming one, for reading a
+     * capture that {@link CloudBrowser.startNetworkCapture} armed elsewhere.
+     * Several readers can watch the same capture, each with its own buffer.
+     *
+     * Stopping the returned view detaches this reader and leaves the capture
+     * running, since other readers may still be attached.
+     *
+     * @param onExchange - called per exchange; see {@link NetworkExchangeHandler}
+     *   for the ordering and blocking rules
+     *
+     * @returns NetworkCapture attached to whatever capture is running; onExchange
+     *   simply never fires when none is
+     *
+     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     */
+    async streamNetworkExchanges(onExchange) {
+        return this.subscribeNetworkExchanges(onExchange);
+    }
+    /**
+     * Opens the stream and waits for the server to acknowledge the subscription
+     * before resolving.
+     *
+     * Merely calling the streaming method does not wait for the server to start
+     * handling it, so arming a capture straight after could outrun the
+     * subscription and lose the first exchanges. The response headers arrive once
+     * the handler is subscribed, and onHeader reports exactly that — over native
+     * gRPC as well as over the WebSocket transport, which forwards the event as
+     * its own frame.
+     */
+    async subscribeNetworkExchanges(onExchange) {
+        const abort = new AbortController();
+        let subscribed;
+        const ready = new Promise((resolve) => {
+            subscribed = resolve;
+        });
+        const stream = this.client.streamNetworkExchanges(create(StreamNetworkExchangesRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }), { signal: abort.signal, onHeader: () => subscribed() });
+        const capture = new NetworkCapture({
+            stream,
+            onExchange,
+            abort,
+            disarm: () => this.stopNetworkCapture(),
+        });
+        // A stream that dies before it is acknowledged would leave the wait above
+        // hanging, so race the two outcomes.
+        const ended = capture.wait().then(() => {
+            throw new BrowserScaleError("browserscale.captureNetwork: stream closed before the subscription was established");
+        });
+        ended.catch(() => { }); // the loser of the race must not look unhandled
+        await Promise.race([ready, ended]);
+        return capture;
+    }
+    // ──────────────────────────────────────────────────────────────────
+    // DOM mirror
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Starts a live copy of a frame's DOM and keeps it up to date.
+     *
+     * The browser sends the top of the tree once, then reports only what changed
+     * in the part you expanded. Everything else costs a child count per batch, no
+     * matter how much churns inside it — which is what makes this usable on a
+     * page that rewrites a list sixty times a second, where re-fetching the
+     * document on a timer is not.
+     *
+     * Expand and collapse as the user opens and closes nodes; that is what moves
+     * the boundary of what gets reported. The returned {@link DomMirror} holds
+     * the tree and exposes `expand`, `collapse` and `reveal`.
+     *
+     * The handler runs after each applied batch. `mirror.root` is a new object
+     * whenever anything under it changed and the untouched parts keep their
+     * identity, so rendering straight from it with memoized components is cheap.
+     *
+     * One mirror covers the whole page as ONE tree. An `<iframe>` is an
+     * ordinary element whose single child is the document it hosts; expanding it
+     * fetches that document and starts mirroring the frame, however deeply
+     * nested and whether or not it is cross-origin. Unlike the inlining
+     * {@link CloudBrowser.getDOM} does, these regions stay live — and frames
+     * nobody opened cost nothing.
+     *
+     * ```ts
+     * const mirror = await browser.mirrorDom({ pierce: true }, () => {
+     *   render(mirror.root);
+     * });
+     * await mirror.expand(bodyNode);
+     * // ...
+     * await mirror.stop();
+     * ```
+     *
+     * @param opts initial depth and whether to pierce shadow roots
+     * @param onChange called after every change, including the first snapshot
+     * @param onResync called when the copy had to be rebuilt, after the new tree
+     *   is in place. Rebuilding is automatic; this is for telling the user why
+     *   their expanded nodes collapsed.
+     * @throws UNKNOWN_ERROR - the mirror could not be started
+     */
+    async mirrorDom(opts, onChange, onResync) {
+        const abort = new AbortController();
+        let subscribed;
+        const ready = new Promise((resolve) => {
+            subscribed = resolve;
+        });
+        const stream = this.client.streamDomEvents(create(StreamDomEventsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }), { signal: abort.signal, onHeader: () => subscribed() });
+        const mirror = new DomMirror({
+            stream,
+            transport: {
+                start: (o) => this.startDomMirror(o),
+                stop: () => this.stopDomMirror(),
+                children: (id, frameId, depth) => this.getDomChildren(id, frameId, depth),
+                release: (id, frameId) => this.releaseDomSubtree(id, frameId),
+                reveal: (id, frameId) => this.revealDomNode(id, frameId),
+            },
+            options: opts,
+            onChange,
+            onResync,
+            abort,
+        });
+        // A stream that dies before it is acknowledged would leave the wait below
+        // hanging, so race the two outcomes.
+        const ended = mirror.wait().then(() => {
+            throw new BrowserScaleError("browserscale.mirrorDom: stream closed before the subscription was established");
+        });
+        ended.catch(() => { });
+        await Promise.race([ready, ended]);
+        // Snapshot only now: taken before the subscription exists, changes between
+        // the two would be lost with nothing to indicate it.
+        try {
+            mirror.install(await this.startDomMirror(opts));
+        }
+        catch (err) {
+            abort.abort();
+            throw err;
+        }
+        onChange(mirror);
+        return mirror;
+    }
+    /**
+     * Starts (or restarts) the page's mirror and returns the main document,
+     * without subscribing to changes. {@link CloudBrowser.mirrorDom} is what you
+     * normally want; this is the raw command.
+     */
+    async startDomMirror(opts = {}) {
+        const req = create(StartDomMirrorRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        });
+        if (opts.depth !== undefined)
+            req.depth = opts.depth;
+        if (opts.pierce !== undefined)
+            req.pierce = opts.pierce;
+        const resp = await this.client.startDomMirror(req);
+        return {
+            root: resp.root,
+            frameId: resp.frameId,
+            seq: Number(resp.seq),
+        };
+    }
+    /** Stops the page's mirror, every frame of it. Idempotent. */
+    async stopDomMirror() {
+        await this.client.stopDomMirror(create(StopDomMirrorRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+    }
+    /**
+     * Fetches a node's children and starts reporting changes inside them.
+     * {@link DomMirror.expand} calls this and folds the result into the tree.
+     *
+     * On an `<iframe>` the one child is the document it hosts, and this call is
+     * what starts mirroring that frame.
+     */
+    async getDomChildren(backendNodeId, frameId = "", depth) {
+        const req = create(GetDomChildrenRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            backendNodeId,
+        });
+        if (frameId)
+            req.frameId = frameId;
+        if (depth !== undefined)
+            req.depth = depth;
+        const resp = await this.client.getDomChildren(req);
+        return { children: resp.children, seq: Number(resp.seq) };
+    }
+    /**
+     * Stops reporting changes inside a node, and inside any frame below it.
+     * {@link DomMirror.collapse} calls this.
+     */
+    async releaseDomSubtree(backendNodeId, frameId = "") {
+        const req = create(ReleaseDomSubtreeRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            backendNodeId,
+        });
+        if (frameId)
+            req.frameId = frameId;
+        await this.client.releaseDomSubtree(req);
+    }
+    /**
+     * Returns the chain from the main document down to a node, each ancestor
+     * with its own children, crossing into frames where it has to and starting
+     * the ones it passes through. {@link DomMirror.reveal} calls this and
+     * splices it in.
+     */
+    async revealDomNode(backendNodeId, frameId = "") {
+        const req = create(RevealDomNodeRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            backendNodeId,
+        });
+        if (frameId)
+            req.frameId = frameId;
+        const resp = await this.client.revealDomNode(req);
+        return { path: resp.path, seq: Number(resp.seq) };
+    }
+    /**
+     * A frame's mutation counter, incremented on every change the document sees.
+     * O(1) in the browser and the change detector to poll if you are not
+     * consuming mirror events.
+     *
+     * Prefer this over {@link CloudBrowser.getDOMHash}, which serializes the
+     * whole tree just to hash it. The two answer different questions: a hash
+     * compares content, a revision only says whether this document moved since
+     * you last asked.
+     */
+    async getDomRevision(frameId = "") {
+        const req = create(GetDomRevisionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        });
+        if (frameId)
+            req.frameId = frameId;
+        const resp = await this.client.getDomRevision(req);
+        return Number(resp.revision);
+    }
+    // ──────────────────────────────────────────────────────────────────
     // Cookies
     // ──────────────────────────────────────────────────────────────────
     /**
@@ -1193,6 +1524,54 @@ export class CloudBrowser {
         await this.client.clearStorage(req);
     }
     // ──────────────────────────────────────────────────────────────────
+    // Auth / DBSC (portable signed-in persona)
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Exports the signed-in primary account and DBSC sessions of this
+     * browser context.
+     *
+     * State is read in the browser process, so no page needs to be open.
+     * Returns undefined when the context has neither a signed-in account
+     * nor DBSC sessions.
+     *
+     * @returns AuthSession, or undefined when there is nothing to export
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be read
+     *
+     * @example
+     * const auth = await browser.getAuthSession();
+     * if (auth) await fs.writeFile("auth.json", JSON.stringify(auth));
+     */
+    async getAuthSession() {
+        const resp = await this.client.getAuthSession(create(GetAuthSessionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.session ? authSessionFromProto(resp.session) : undefined;
+    }
+    /**
+     * Imports an auth session so the context comes up signed in (and syncing
+     * if syncConsent) with its DBSC sessions restored.
+     *
+     * Call it before navigating. Pair with setCookies() / setStorage() to
+     * restore a full persona.
+     *
+     * @param session - session as returned by getAuthSession()
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be written
+     *
+     * @example
+     * await browser.setAuthSession(saved);
+     * await browser.navigate("https://mail.google.com");
+     */
+    async setAuthSession(session) {
+        await this.client.setAuthSession(create(SetAuthSessionRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            session: authSessionToProto(session),
+        }));
+    }
+    // ──────────────────────────────────────────────────────────────────
     // Devtools / live-UI helpers
     // ──────────────────────────────────────────────────────────────────
     /**
@@ -1464,20 +1843,20 @@ export class CloudBrowser {
     }
     /**
      * Answers your WebRTC SDP offer and starts streaming the page as a video
-     * track, returning the SDP answer to set as your peer's remote description.
-     * The browser is the answerer; you are the offerer (see
+     * track. The browser is the answerer; you are the offerer (see
      * {@link getStreamConfig} for the credentials to build the offer).
      *
      * @param offerSdp - your `RTCPeerConnection`'s SDP offer
      *
-     * @returns the SDP answer to apply as the remote description
+     * @returns the SDP answer to apply as the remote description, plus the
+     *   viewport to map input coordinates into
      *
      * @throws UNKNOWN_ERROR - the offer was empty, TURN is unconfigured, or the
      *   browser could not negotiate the stream
      *
      * @example
-     * const answer = await browser.startStream(offer.sdp);
-     * await pc.setRemoteDescription({ type: "answer", sdp: answer });
+     * const { answerSdp, viewport } = await browser.startStream(offer.sdp);
+     * await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });
      */
     async startStream(offerSdp) {
         const resp = await this.client.startStream(create(StartStreamRequestSchema, {
@@ -1485,7 +1864,12 @@ export class CloudBrowser {
             apiKey: this.apiKey,
             offerSdp,
         }));
-        return resp.answerSdp;
+        return {
+            answerSdp: resp.answerSdp,
+            viewport: resp.viewport
+                ? { width: resp.viewport.width, height: resp.viewport.height }
+                : null,
+        };
     }
     /**
      * Tears down the live video stream for the session's page. Safe to call even
@@ -1613,6 +1997,236 @@ export class CloudBrowser {
             visible: r.visible,
         }));
     }
+    // ──────────────────────────────────────────────────────────────────
+    // Scripts
+    // ──────────────────────────────────────────────────────────────────
+    /**
+     * Runs `source` in the session's browser and waits for it to finish.
+     *
+     * The script executes in a V8 isolate inside the browser process, not in the
+     * page, and reaches the same operations this SDK exposes through a `browser`
+     * object it is handed. The difference is cost: each call is a function call in
+     * the browser rather than a network round trip, so work that is chatty by
+     * nature — polling for a selector, walking a list, following pagination —
+     * runs in microseconds per step instead of tens of milliseconds.
+     *
+     * This waits for as long as the script runs, and cannot be bounded: the run
+     * id needed to cancel only arrives with the reply. Use
+     * {@link CloudBrowser.startScript} when the script may outlive the caller's
+     * patience, or {@link CloudBrowser.stopScripts} to abandon what this session
+     * is running.
+     *
+     * @param source - JavaScript to execute; its return value comes back as JSON
+     *
+     * @returns the return value and the script's whole console output. A script
+     *   that threw is reported as `success: false`, not as a rejection
+     *
+     * @throws UNKNOWN_ERROR - the script could not be delivered to the browser
+     *
+     * @example
+     * const result = await browser.runScript(`
+     *   await browser.navigate("https://example.com");
+     *   const items = [];
+     *   for (const el of await browser.getDOM().querySelectorAll("h1")) {
+     *     items.push(el.textContent);
+     *   }
+     *   return items;
+     * `);
+     * console.log(result.success, result.result);
+     */
+    async runScript(source) {
+        const resp = await this.client.runScript(create(RunScriptRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            source,
+        }));
+        return {
+            success: resp.success,
+            result: resp.result,
+            runId: resp.runId,
+            log: resp.log.map(scriptLogEntryFromProto),
+            truncated: resp.truncated,
+        };
+    }
+    /**
+     * Launches `source` in the session's browser and resolves as soon as the run
+     * is under way.
+     *
+     * The counterpart to {@link CloudBrowser.runScript}, for scripts that are not
+     * worth waiting on: a watcher that runs for the life of the session, work
+     * that should survive this page. Output arrives at `onEvent` while the caller
+     * gets on with something else, and {@link ScriptRun.wait} collects the
+     * outcome if it is wanted.
+     *
+     * Subscribing has to happen before the launch, because a detached run's
+     * output is not kept anywhere — the browser rejects a start with nobody
+     * listening rather than discard the script's log and result. This call does
+     * both in that order, so nothing the script prints is missed.
+     *
+     * @param source - JavaScript to execute
+     * @param onEvent - called per log line and once for the outcome; see
+     *   {@link ScriptEventHandler} for the ordering and blocking rules
+     *
+     * @returns ScriptRun handle for awaiting or cancelling the run
+     *
+     * @throws UNKNOWN_ERROR - the run could not be started
+     *
+     * @example
+     * const run = await browser.startScript(source, (ev) => {
+     *   if (ev.log) console.log(ev.log.level, ev.log.message);
+     * });
+     * const outcome = await run.wait();
+     */
+    async startScript(source, onEvent) {
+        // Subscribe unfiltered: the run id this handle filters on does not exist
+        // yet. Events for it pile up in the server's per-reader buffer between the
+        // subscription and the launch, which is what that buffer is for.
+        const abort = new AbortController();
+        let subscribed;
+        const ready = new Promise((resolve) => {
+            subscribed = resolve;
+        });
+        const stream = this.client.streamScriptEvents(create(StreamScriptEventsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }), { signal: abort.signal, onHeader: () => subscribed() });
+        // Opening a stream does not wait for the server to start handling it. For a
+        // capture that would only cost the first few events; here it would fail the
+        // launch outright, since the browser refuses to start a run before a
+        // subscription exists. The headers arrive once it is subscribed.
+        const iterator = stream[Symbol.asyncIterator]();
+        const first = iterator.next();
+        // A stream that fails or closes before it is acknowledged would leave the
+        // wait below hanging, so race the two outcomes. An event arriving ahead of
+        // the headers is not a failure — it proves the subscription exists.
+        const ended = first.then((result) => {
+            if (result.done) {
+                throw new BrowserScaleError("browserscale.startScript: stream closed before the subscription was established");
+            }
+        });
+        ended.catch(() => { }); // the loser of the race must not look unhandled
+        try {
+            await Promise.race([ready, ended]);
+        }
+        catch (err) {
+            abort.abort();
+            throw err;
+        }
+        let runId;
+        try {
+            const resp = await this.client.startScript(create(StartScriptRequestSchema, {
+                sessionId: this.sessionId,
+                apiKey: this.apiKey,
+                source,
+            }));
+            runId = resp.runId;
+        }
+        catch (err) {
+            abort.abort();
+            throw err;
+        }
+        // Resume from the pending read rather than iterating the stream again: the
+        // first next() is already in flight and its value would otherwise be lost.
+        const resumed = resumeStream(iterator, first);
+        return new ScriptRun({
+            runId,
+            stream: resumed,
+            onEvent,
+            abort,
+            cancel: (id) => this.stopScripts(id),
+        });
+    }
+    /**
+     * Watches script output in this session without starting anything.
+     *
+     * For the case {@link CloudBrowser.startScript} cannot cover: a run somebody
+     * else launched, or one this page started before it reloaded. Several readers
+     * can watch the same session, each with its own buffer.
+     *
+     * Only output produced from now on arrives — lines printed before the
+     * subscription existed are not kept. A run that has already finished is
+     * therefore invisible here; {@link CloudBrowser.listScriptRuns} is how you
+     * tell that apart from a run that is merely quiet.
+     *
+     * @param runId - run to follow, or `""` to follow every run in the session
+     * @param onEvent - called per event; see {@link ScriptEventHandler} for the
+     *   ordering and blocking rules
+     *
+     * @returns ScriptFollow handle for stopping the subscription
+     *
+     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     *
+     * @example
+     * const follow = await browser.followScript(runId, (ev) => {
+     *   if (ev.log) console.log(ev.log.message);
+     * });
+     * try {
+     *   await follow.wait();
+     * } finally {
+     *   await follow.stop();
+     * }
+     */
+    async followScript(runId, onEvent) {
+        const abort = new AbortController();
+        const stream = this.client.streamScriptEvents(create(StreamScriptEventsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            runId,
+        }), { signal: abort.signal });
+        return new ScriptFollow({ stream, onEvent, abort });
+    }
+    /**
+     * Cancels runs in this session and reports how many it ended.
+     *
+     * An empty `runId` cancels every run in the session, which is the only form
+     * available to a caller that never learned an id — notably one abandoning a
+     * {@link CloudBrowser.runScript}.
+     *
+     * @param runId - run to cancel, or `""` for all of them
+     *
+     * @returns how many runs were cancelled; 0 when the id named nothing in
+     *   flight
+     *
+     * @throws UNKNOWN_ERROR - the cancel could not be delivered
+     *
+     * @example
+     * await browser.stopScripts(""); // abandon everything running
+     */
+    async stopScripts(runId) {
+        const resp = await this.client.stopScripts(create(StopScriptsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+            runId,
+        }));
+        return resp.stopped;
+    }
+    /**
+     * Reports the scripts still running in this session.
+     *
+     * Only runs in flight — a finished run is reported once on the event stream
+     * and then forgotten, so this is not a history. Its use is finding work this
+     * caller did not start: a script a previous page left behind, which
+     * {@link CloudBrowser.stopScripts} needs an id to name.
+     *
+     * @returns one entry per run still executing
+     *
+     * @throws UNKNOWN_ERROR - the session could not be queried
+     *
+     * @example
+     * for (const run of await browser.listScriptRuns()) {
+     *   console.log(run.runId, run.runningMs);
+     * }
+     */
+    async listScriptRuns() {
+        const resp = await this.client.listScriptRuns(create(ListScriptRunsRequestSchema, {
+            sessionId: this.sessionId,
+            apiKey: this.apiKey,
+        }));
+        return resp.runs.map((run) => ({
+            runId: run.runId,
+            runningMs: Number(run.runningMs),
+        }));
+    }
     /**
      * @internal — a reaction match/action must be a css()/js() locator: node()
      * and at() are rejected (a reaction watches for a condition, like a wait).
@@ -1626,3 +2240,18 @@ export class CloudBrowser {
         }
     }
 }
+/**
+ * Continues an async iterator whose first read is already in flight.
+ *
+ * startScript has to know the subscription exists before it launches anything,
+ * and the only way to make the client send the request is to start reading. That
+ * read cannot be discarded — it may already hold the run's first log line — so
+ * the reader is handed a stream that replays it before continuing.
+ */
+async function* resumeStream(iterator, first) {
+    let result = await first;
+    while (!result.done) {
+        yield result.value;
+        result = await iterator.next();
+    }
+}